Crate relay_cabi
source ·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 usingcargo
.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 therelay-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§
- A binary buffer of known length.
- A geo ip lookup helper based on maxmind db files.
- Represents a key pair from key generation.
- Represents a public key in Relay.
- Represents a register request.
- Represents a secret key in Relay.
- The processor that normalizes events for store.
- A length-prefixed UTF-8 string.
- A 16-byte UUID.
- Configuration for the store step – validation and normalization.
Enums§
- Classifies the type of data that is being ingested.
- The type of an event.
- Controls the globbing behaviors.
- Represents all possible error codes.
- Trace status.
Functions§
- Normalize a cardinality limit config.
- Frees a Relay buf.
- Compares two versions.
- Convert an old datascrubbing config to the new PII config format.
- Creates a challenge from a register request and returns JSON.
- Parses a
DataCategory
from an event type. - Returns the API name of the given
DataCategory
. - Parses a
DataCategory
from its API name. - Clears the last error.
- Returns the panic information as string.
- Returns the last error code.
- Returns the last error message.
- Generates a secret, public key pair.
- Randomly generates an relay id
- Frees a
RelayGeoIpLookup
. - Opens a maxminddb file by path.
- Initializes the library
- Returns
true
if the codeowners path matches the value,false
otherwise. - Performs a glob operation on bytes.
- Normalize a global config.
- Normalize a project config.
- Parse a sentry release structure from a string.
- 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.
- Scrub an event using new PII stripping config.
- Frees a public key.
- Parses a public key from a string.
- Converts a public key into a string.
- Verifies a signature
- Verifies a signature
- Frees a secret key.
- Parses a secret key from a string.
- Verifies a signature
- Converts a secret key into a string.
- Chunks the given text based on remarks.
- Frees a
RelayStoreNormalizer
. - Creates a new normalization config.
- Normalizes the event given as JSON.
- Frees a Relay str.
- Creates a Relay string from a c string.
- A test function that always panics.
- Replaces invalid JSON generated by Python.
- Returns true if the uuid is nil.
- Formats the UUID into a string.
- Returns a list of all valid platform identifiers.
- Validate a PII config against the schema. Used in project options UI.
- Validates a PII selector spec. Used to validate datascrubbing safe fields.
- Validates a register response.
- Validate a dynamic rule condition.
- 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.
- Returns true if the given version is supported by this library.