Crate relay_cabi

Expand description

This package contains the C-ABI of Relay. It builds a C header file and associated library that can be linked to any C or C++ program. Note that the header is C only. Primarily, this package is meant to be consumed by higher-level wrappers in other languages, such as the sentry-relay Python package.

§Building

Building the dynamic library has the same requirements as building the relay crate:

Latest stable Rust and Cargo
A checkout of this repository and all its GIT submodules

To build, run make release in this directory. This creates a release build of the dynamic library in target/release/librelay_cabi.*.

§Usage

The header comes packaged in the include/ directory. It does not have any dependencies other than standard C headers. Then, include it in sources and use like this:

#include "relay.h"

int main() {
    RelayUuid uuid = relay_generate_relay_id();
    // use uuid

    return 0;
}

In your application, point to the Relay include directory and specify the relay library:

$(CC) -Irelay-cabi/include -Ltarget/release -lrelay -o myprogram main.c

§Development

§Requirements

In addition to the build requirements, development requires a recent version of the the cbindgen tool. To set this up, run:

cargo install cbindgen

If your machine already has cbindgen installed, check the header of [include/relay.h] for the minimum version required. This can be verified by running cbindgen --version. It is generally advisable to keep cbindgen updated to its latest version, and always check in cbindgen updates separate from changes to the public interface.

§Makefile

This package contains the Rust crate relay-cabi that exposes a public FFI interface. There are additional build steps involved in generating the header file located at include/relay.h. To aid development, there is a Makefile that exposes all relevant commands for building:

make build: Builds the library using cargo.
make header: Updates the header file based on the public interface.
make clean: Removes all build artifacts but leaves the header.
make: Builds the library and the header.

For ease of development, the header is always checked into the repository. After making changes, do not forget to run at least make header to ensure the header is in sync with the library.

§Development Flow

Make changes to the relay crates and add tests.
Update relay-cabi and add, remove or update functions as needed.
Regenerate the header by running make header in the relay-cabi/ directory.
Go to the Python package in the py/ folder and update the high-level wrappers.
Consider whether this changeset requires a major version bump.

The general rule for major versions is:

If everything is backward compatible, do not major bump.
If the C interface breaks compatibility but high-level wrappers are still backwards compatible, do not major bump. The C interface is currently viewed as an implementation detail.
If high-level wrappers are no longer backwards compatible or there are breaking changes in the relay crate itself, do major bump.

Structs§

RelayBuf: A binary buffer of known length.
RelayGeoIpLookup: A geo ip lookup helper based on maxmind db files.
RelayKeyPair: Represents a key pair from key generation.
RelayPublicKey: Represents a public key in Relay.
RelayRegisterRequest: Represents a register request.
RelaySecretKey: Represents a secret key in Relay.
RelayStoreNormalizer: The processor that normalizes events for store.
RelayStr: A length-prefixed UTF-8 string.
RelayUuid: A 16-byte UUID.
StoreNormalizer: Configuration for the store step – validation and normalization.

Enums§

DataCategory: Classifies the type of data that is being ingested.
EventType: The type of an event.
GlobFlags: Controls the globbing behaviors.
RelayErrorCode: Represents all possible error codes.
SpanStatus: Trace status.

Functions§

normalize_cardinality_limit_config^⚠: Normalize a cardinality limit config.
relay_buf_free^⚠: Frees a Relay buf.
relay_compare_versions^⚠: Compares two versions.
relay_convert_datascrubbing_config^⚠: Convert an old datascrubbing config to the new PII config format.
relay_create_register_challenge^⚠: Creates a challenge from a register request and returns JSON.
relay_data_category_from_event_type^⚠: Parses a DataCategory from an event type.
relay_data_category_name^⚠: Returns the API name of the given DataCategory.
relay_data_category_parse^⚠: Parses a DataCategory from its API name.
relay_err_clear: Clears the last error.
relay_err_get_backtrace: Returns the panic information as string.
relay_err_get_last_code: Returns the last error code.
relay_err_get_last_message: Returns the last error message.
relay_generate_key_pair^⚠: Generates a secret, public key pair.
relay_generate_relay_id^⚠: Randomly generates an relay id
relay_geoip_lookup_free^⚠: Frees a RelayGeoIpLookup.
relay_geoip_lookup_new^⚠: Opens a maxminddb file by path.
relay_init: Initializes the library
relay_is_codeowners_path_match^⚠: Returns true if the codeowners path matches the value, false otherwise.
relay_is_glob_match^⚠: Performs a glob operation on bytes.
relay_normalize_global_config^⚠: Normalize a global config.
relay_normalize_project_config^⚠: Normalize a project config.
relay_parse_release^⚠: Parse a sentry release structure from a string.
relay_pii_selector_suggestions_from_event^⚠: Walk through the event and collect selectors that can be applied to it in a PII config. This function is used in the UI to provide auto-completion of selectors.
relay_pii_strip_event^⚠: Scrub an event using new PII stripping config.
relay_publickey_free^⚠: Frees a public key.
relay_publickey_parse^⚠: Parses a public key from a string.
relay_publickey_to_string^⚠: Converts a public key into a string.
relay_publickey_verify^⚠: Verifies a signature
relay_publickey_verify_timestamp^⚠: Verifies a signature
relay_secretkey_free^⚠: Frees a secret key.
relay_secretkey_parse^⚠: Parses a secret key from a string.
relay_secretkey_sign^⚠: Verifies a signature
relay_secretkey_to_string^⚠: Converts a secret key into a string.
relay_split_chunks^⚠: Chunks the given text based on remarks.
relay_store_normalizer_free^⚠: Frees a RelayStoreNormalizer.
relay_store_normalizer_new^⚠: Creates a new normalization config.
relay_store_normalizer_normalize_event^⚠: Normalizes the event given as JSON.
relay_str_free^⚠: Frees a Relay str.
relay_str_from_cstr^⚠: Creates a Relay string from a c string.
relay_test_panic^⚠: A test function that always panics.
relay_translate_legacy_python_json^⚠: Replaces invalid JSON generated by Python.
relay_uuid_is_nil^⚠: Returns true if the uuid is nil.
relay_uuid_to_str^⚠: Formats the UUID into a string.
relay_valid_platforms^⚠: Returns a list of all valid platform identifiers.
relay_validate_pii_config^⚠: Validate a PII config against the schema. Used in project options UI.
relay_validate_pii_selector^⚠: Validates a PII selector spec. Used to validate datascrubbing safe fields.
relay_validate_register_response^⚠: Validates a register response.
relay_validate_rule_condition^⚠: Validate a dynamic rule condition.
relay_validate_sampling_configuration^⚠: Validate whole rule ( this will be also implemented in Sentry for better error messages) The implementation in relay is just to make sure that the Sentry implementation doesn’t go out of sync.
relay_version_supported^⚠: Returns true if the given version is supported by this library.

Crate relay_cabiCopy item path