This crate implements a support library to simplify implementing the patterns that the
mozilla/application-services repository uses for it's "Rust Component" FFI libraries.
It is strongly encouraged that anybody writing FFI code in this repository read this documentation before doing so, as it is a subtle, difficult, and error prone process.
For each library, there are currently three parts we're concerned with. There's no clear correct name for these, so this documentation will attempt to use the following terminology:
Rust Component: A Rust crate which does not expose an FFI directly, but may be may be wrapped by one that does. These have a
crate-typein their Cargo.toml (see https://doc.rust-lang.org/reference/linkage.html) of
lib, and not
libis the default if
crate-typeis not specified). Examples include the
FFI Component: A wrapper crate that takes a Rust component, and exposes an FFI from it. These typically have
ffiin the name, and have
crate-type = ["lib", "staticlib", "cdylib"]in their Cargo.toml. For example, the
logins/fficrates (note: paths are subject to change). When built, these produce a native library that is consumed by the "FFI Consumer".
FFI Consumer: This is a low level library, typically implemented in Kotlin (for Android) or Swift (for iOS), that exposes a memory-safe wrapper around the memory-unsafe C API produced by the FFI component. It's expected that the maintainers of the FFI Component and FFI Consumer be the same (or at least, the author of the consumer should be completely comfortable with the API exposed by, and code in the FFI component), since the code in these is extremely tightly coupled, and very easy to get wrong.
Note that while there are three parts, there may be more than three libraries relevant here, for example there may be more than one FFI consumer (one for Android, one for iOS).
This library will typically be used in both the Rust component, and the FFI component, however it frequently will be an optional dependency in the Rust component that's only available when a feature flag (which the FFI component will always require) is used.
The reason it's required inside the Rust component (and not solely in the FFI component, which
would be nice), is so that types provided by that crate may implement the traits provided by
this crate (this is because Rust does not allow crate
C to implement a trait defined in crate
A for a type defined in crate
Inside the Rust component, you will implement:
IntoFfifor all types defined in that crate that you want to return over the FFI. For most common cases, the
implement_into_ffi_by_protobuf!macros will do the job here, however you can see that trait's documentation for discussion and examples of implementing it manually.
ExternErrorfor the error type(s) exposed by that rust component, that is,
impl From<MyError> for ExternError.
Inside the FFI component, you will use this library in a few ways:
Destructors will be exposed for each types that had
implement_into_ffi_by_pointer!called on it (using
define_box_destructor!), and a destructor for strings should be exposed as well, using
This is required because if we
panic!(e.g. from an
expect(), from indexing past the end of an array, etc) across the FFI boundary, the behavior is undefined and in practice very weird things tend to happen (we aren't caught by the caller, since they don't have the same exception behavior as us).
If you don't think your program (or possibly just certain calls) can handle panics, you may also use the versions of these functions in the
abort_on_panicmodule, which do as their name suggest.
Additionally, c strings that are passed in as arguments may be represented using
which contains several helpful inherent methods for extracting their data.
This module provides a
Define a (public) destructor for a type that was allocated by
Define a (public) destructor for the ByteBuffer type.
Define a (public) destructor for a type that lives inside a lazy_static
For a number of reasons (name collisions are a big one, but, it also wouldn't work on all
platforms), we cannot export
Implement IntoFfi for a type by converting through another type.
Force a compile error if the condition is not met. Requires a unique name for the assertion for... reasons. This is included mainly because it's a common desire for FFI code, but not for other sorts of code.
ByteBuffer is a struct that represents an array of bytes to be sent over the FFI boundaries. There are several cases when you might want to use this, but the primary one for us is for returning protobuf-encoded data to Swift and Java. The type is currently rather limited (implementing almost no functionality), however in the future it may be more expanded.
A wrapper around error codes, which is represented identically to an i32 on the other side of the FFI. Essentially exists to check that we don't accidentally reuse success/panic codes for other things.
Represents an error that occured within rust, storing both an error code, and additional data that may be used by the caller.
This trait is used to return types over the FFI. It essentially is a mapping between a type and
version of that type we can pass back to C (
Call a callback that returns a
Call a callback that returns a
Free the memory of a string created by
Convert a null-terminated C string to a rust
Convert a null-terminated C into an owned rust string, replacing invalid UTF-8 with the unicode replacement character.
Convert a rust string into a NUL-terminated utf-8 string suitable for passing to C, or to things ABI-compatible with C.