Mozilla's toolkit for generating safe, multi-language bindings from a single Rust library — and exactly what happens under the hood.
- Context: evaluating it fordpp → Go bindings
-UniFFI is a tool from Mozilla (born out of the Firefox/Application-Services effort to ship one Rust core to iOS, Android, and desktop) that auto-generates the FFI glue needed to call a Rust library from other languages. You write your logic once in Rust, describe the interface, and UniFFI emits:
-extern "C" entry points compiled into your crate, andOfficially supported targets: KotlinSwiftPythonRuby. Additional targets exist as external bindings generators — including Go (see §9), C#, Kotlin-Multiplatform, and Dart.
- -Calling Rust from another language always has to cross a C ABI — that is the only calling convention every runtime agrees on. Hand-writing that boundary means manually authoring #[no_mangle] extern "C" functions, raw-pointer marshalling, string/array encoding, error codes, and a matching set of unsafe declarations on the other side. It is repetitive, easy to get subtly wrong, and must be re-done for every language.
UniFFI's bet: that glue is mechanical, so generate it. One interface description → correct, consistent glue for N languages, regenerated automatically whenever the API changes.
- -There are two ways to tell UniFFI about your API. Modern projects favor proc-macros; the original mechanism is a UDL file.
- -Annotate the real Rust directly — no separate file:
-// lib.rs
-#[derive(uniffi::Record)]
-pub struct DirEntry { pub name: String, pub size: u64 }
-
-#[derive(uniffi::Object)]
-pub struct Filesystem { /* … */ }
-
-#[uniffi::export]
-impl Filesystem {
- pub fn list_directory(&self, path: String)
- -> Result<Vec<DirEntry>, DppError> { /* … */ }
-}
-
-uniffi::setup_scaffolding!();A WebIDL-like schema file, kept in sync with the Rust:
-// dpp.udl
-dictionary DirEntry {
- string name;
- u64 size;
-};
-
-interface Filesystem {
- [Throws=DppError]
- sequence<DirEntry> list_directory(string path);
-};Pulled in via uniffi::include_scaffolding!("dpp") in build.rs.
Either way, UniFFI builds an internal component-interface metadata model (records, enums, objects, functions, errors, their types) that drives all code generation.
- -End to end, here is what runs and what it produces:
-So there are two generated artifacts: (1) the C-ABI surface inside your compiled Rust library, and (2) the per-language wrapper source that knows how to call it. Both come from the same metadata, which is why they never drift.
- -The scaffolding is ordinary (generated) Rust that UniFFI compiles into your crate. For each exported function it emits a #[no_mangle] pub extern "C" shim that:
RustBuffer — see §6);catch_unwind guard (a Rust panic must never unwind across the boundary);It also exports housekeeping symbols: a per-type free function, allocators for RustBuffer, a checksum/contract-version symbol so a mismatched binding refuses to load, and (in proc-macro mode) the metadata the generator reads. You never see or hand-edit this code.
Scalars (i32, f64, …) cross the boundary directly. Everything compound — strings, structs (records), enums, sequences, maps, optionals — is serialized into bytes and passed as a RustBuffer: a small { ptr, len, capacity } struct describing a Rust-allocated byte buffer.
The encoding is defined by the FfiConverter trait (and Lift/Lower/Read/Write helpers). Each side implements the same wire format:
| Type | Wire encoding |
|---|---|
i32 / u64 / f64 … | passed by value, no buffer |
String | length-prefixed UTF-8 in a RustBuffer |
record (struct) | fields written back-to-back in declaration order |
enum | u32 variant discriminant, then that variant's fields |
Option<T> | 1 flag byte, then T if present |
sequence<T> / map | i32 count, then each element encoded in turn |
object (interface) | an opaque handle, not serialized — see §7 |
Records are passed by value (copied through a RustBuffer). Objects (anything with methods and identity — e.g. a Filesystem or Pipeline) are passed by reference as an opaque handle: the foreign side holds an integer/pointer it cannot inspect, and every method call passes that handle back to Rust.
Lifetime is reference-counted. The Rust side keeps the object behind an Arc; the scaffolding exposes clone/free symbols. The generated binding wires the object's destructor in the host language to the free symbol:
deinitCleaner / explicit .destroy() (and AutoCloseable)__del__ / context managerruntime.SetFinalizer plus a generated Destroy() methodArc are two separate accountants. UniFFI bridges them, but use-after-Destroy on a handle is the failure mode you still have to respect — the same lifecycle care any handle-based API needs. It is bounded to object handles, not to data.Result<T, E> where E is a UniFFI error enum becomes a thrown exception (Kotlin/Swift/Python) or an idiomatic error return (Go). The scaffolding writes a status code + serialized error into an out-param; the binding turns it into the host idiom.async fn across the boundary by integrating the host's event loop with a Rust future poller. (Go support for async lags the core; verify before relying on it.)uniffi-bindgen-goGo is not an officially-maintained target. It is served by an external generator, NordSecurity/uniffi-bindgen-go, which plugs into UniFFI as a custom bindings backend. Practical realities:
-import "C" / cgo glue you'd otherwise hand-write, plus typed Go structs for your records and Destroy()-bearing wrappers for your objects.uniffi-rs version. You must keep the generator, the runtime, and your crate's UniFFI dependency in lockstep.This is the question that actually matters for dpp, whose selling point is a memory-safe Apple-format parser. Precise answer:
unsafe.unsafe surface is ~zero: the glue is generated and shared across every consumer of UniFFI.unsafe by nature — UniFFI generates that unsafe, it does not eliminate it.Arc) coexist; use-after-Destroy of a handle is still possible from host misuse.If the requirement is a hard memory boundary — where even a hypothetical Rust bug cannot touch Go's address space — no in-process FFI (UniFFI or hand-written) achieves that, because they share an address space by definition. That guarantee only comes from process isolation (a subprocess/IPC daemon) or a WASM sandbox (compile dpp to wasm32-wasi, run it under a wasm runtime). Those trade performance and ergonomics for a true isolation wall. UniFFI's actual claim is narrower and still valuable: minimize and standardize the unavoidable unsafe, and keep every line of your real logic safe.