Crate relay_cabi 

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

1. Make changes to the relay crates and add tests.
2. Update relay-cabi and add, remove or update functions as needed.
3. Regenerate the header by running make header in the relay-cabi/ directory.
4. Go to the Python package in the py/ folder and update the high-level wrappers.
5. 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.

RelayPattern

A Relay pattern.

RelayPatterns

Represents a collection of compiled Relay patterns with shared options.

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

CategoryUnit

The unit in which a data category is measured.

DataCategory

Classifies the type of data that is being ingested.

EventType

The type of an event.

RelayErrorCode

Represents all possible error codes.

SpanStatus

Trace status.

Functions

relay_buf_free^⚠

Frees a Relay buf.

relay_category_unit_name^⚠

Returns the API name of the given CategoryUnit.

relay_category_unit_parse^⚠

Parses a CategoryUnit from its API name.

relay_compare_versions^⚠

Compares two versions.

relay_compare_versions_semver_precedence^⚠

Compares two versions, ignoring build code via semver 1.0’s cmp_precedence.

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_data_category_unit^⚠

Returns the CategoryUnit for a given DataCategory.

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_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_pattern_free^⚠

Frees a compiled Relay pattern.

relay_pattern_is_match^⚠

Returns true if the pattern matches the UTF-8 string.

relay_pattern_new^⚠

Creates a new Relay Pattern.

relay_pattern_to_string^⚠

Formats the pattern using its Display implementation.

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.