Reference

Architecture

One schema feeds three generators. Three runtimes hold the mirrors. A small binary wire carries writes in and change-sets out. This page is the tour, and the specification in the repository is the contract.

The shape of it#

Undra is a Rust core, a schema extracted from it, three code generators, and three platform runtimes. Your screens sit on generated bindings; the bindings sit on a runtime package; the runtime talks to the core through a transport that is an ABI, not a framework.

The core is one codebase. On each platform it is linked the way that platform expects: a prelinked static library in an XCFramework on iOS, a .so over JNI on Android, a wasm module on the web, each named after the core's namespace and reached through one table of entry points, so an app can carry more than one core. A React Native app links the iOS and Android builds as they are and reaches them from JavaScript through JSI, under the same generated package and @undra/runtime as the web (React Native). During development the same core can instead run on your machine behind a WebSocket (undra dev).

From Rust to native code#

Everything starts with the macros. #[undra::api], #[undra::store], #[undra::port] and friends validate your code and register a description of each public type and function. Collected together, those descriptions are the schema: records, enums, objects, stores with their signals, functions, ports and queries. The CLI builds your core as a host library, loads it, asks for the schema, and hands it to undra bindgen, which writes a Swift package, a Gradle module and an npm package. Generated code depends only on the matching runtime package.

Three properties of this design are worth stating plainly:

• Names become ids at compile time. A type id is a hash of its name, a method id a hash of Type.method, a port id a hash of port.Trait, and a signal id is its position among the store's signal fields. Every platform agrees without a registry lookup. The hash is FNV-1a.
• The schema has a hash. It is the FNV-1a hash of a canonical form: lists sorted by name, no whitespace, doc comments excluded, so two cores with the same public surface hash the same. Each binding carries the hash it was generated from, and the runtime compares it with the core's when it attaches.
• Generated code is reviewed like hand-written code. Golden files lock the output for all three languages, and the output is compiled and run in tests. A record becomes a Swift struct, a Kotlin data class and a TypeScript interface; an error becomes a typed-throws enum, a sealed class and an Error subclass. See the API overviews for Swift, Kotlin and TypeScript.

The standard ports and their types are in every schema but are not generated into your bindings, because each runtime already implements them; see Ports & adapters.

The crates#

Thirteen Rust crates, and only one of them may contain unsafe.

The runtimes are runtimes/swift/UndraRuntime, runtimes/kotlin/undra-runtime and runtimes/ts/@undra/runtime. The Kotlin runtime depends on the standard library and kotlinx-coroutines only, and the TypeScript core package has no runtime dependencies.

The wire#

The wire is small on purpose. It is little-endian throughout, with no alignment and no padding. All lengths are u32. Decoders never panic on malformed input; they return a typed error.

Transports that cross a real pipe (the WebSocket and worker transports) wrap every message in a 23-byte envelope. In-process calls skip it and carry only the payload.

The kind byte says what the payload is:

A call carries a target (free function, object method, constructor or lazy page), the object handle, the method id, a call id the host chose, and the arguments encoded in order. The reply carries the call id and a status: 0 ok, 1 a typed error, 2 a panic (message and backtrace), 3 cancelled, 4 a stream was opened, 5 a bad request such as an unknown method or a schema mismatch. A failure is always a typed value; nothing escapes as an abort.

A change-set is how state comes back. It carries a transaction id and one entry per dirty observed signal.

An entry's op is 0 for a full value, 1 for a keyed patch, and 2 for "lazy list invalidated". A keyed patch is a count and a list of operations (Insert, Remove, Update, Move, Clear) applied in order to the host's copy; see Core concepts. The len field lets a host skip an entry it cannot decode.

Streams use credit-based backpressure. A host grants credit and the core sends at most that many items beyond what has been credited; generated bindings grant 16 on subscribe and top up when consumption drops below 8. A cancel closes the stream.

The boundary#

The native boundary is a C ABI of C-compatible types only. Each core exports one symbol named after its namespace, <namespace>_undra_api, which returns a table: its version and size, the schema hash, the namespace, and seventeen entry points (parameter lists abridged here). Two cores in one process are two tables, and nothing of one can bind to the other (ADR-044).

const UndraApi *playground_core_undra_api(void);

typedef struct UndraApi {
    uint32_t    abi_version;                       // 2
    uint32_t    size;                              // sizeof(UndraApi), for later additions
    uint64_t    schema_hash;
    const char *name_space;                        // "playground_core"
    UndraBuf  (*schema_json)(void);
    uint32_t  (*init)(cfg, len, reply_cb, changeset_cb, stream_cb, user);
    void      (*shutdown)(void);
    uint32_t  (*call)(ptr, len);                   // async reply arrives on reply_cb
    UndraBuf  (*call_sync)(ptr, len);              // reply returned directly
    void      (*cancel)(call_id);
    void      (*stream_credit)(call_id, credit);
    void      (*observe)(handle, signal_id, on);
    void      (*release)(handle);
    void      (*port_register)(port_id, cb, user);
    void      (*port_reply)(ptr, len);
    void      (*event)(port_id, method_id, ptr, len);
    void      (*timer_fired)(timer_id);
    UndraBuf  (*snapshot)(void);
    uint32_t  (*restore)(ptr, len);
    UndraBuf  (*stats_json)(void);
    void      (*buf_free)(UndraBuf buf);
} UndraApi;

Android reaches the same functions through a JNI shim that registers its natives once at load on the bindings' own class, so there is no per-call lookup and two cores never share one. The web has its own module per core, so it needs no table, and no wasm-bindgen: the module exports and imports use only i32, i64 and f64, a 64-bit handle is passed as two halves, and undra_poll() drives the executor. Clock, Rng and Log are bound to wasm imports, so a web app needs no adapter code for them.

Callbacks are where hosts get hurt, so the contract is explicit and enforced. A callback runs on whichever thread produced the event, possibly with the core lock held, so it must be short, thread-safe and must not throw. It must not call back into the core except the few entries that never take the lock (freeing a buffer, replying to a port call, granting stream credit, firing a timer, reading stats). Every other re-entry is refused with E_REENTRANT instead of deadlocking, in every build.

The synchronous call path is allocation-free once warm. A per-thread reply slot lets a synchronous method encode its whole reply into one reusable buffer, which is what moves a call through the C ABI to 49.8 ns (ADR-028); a counting allocator in the tests holds the lending entry to zero allocations and a C ABI call to exactly one, the buffer it hands back.

Threading#

• One mutator. The core has one lock. Whoever holds it is the core loop. A synchronous call from the host runs on the caller's thread holding that lock, so it costs a mutex acquire, not a thread hop.
• Async work. Async calls are tasks on a small executor with no tokio, polled by the core thread, one task per in-flight call. Cancelling a call drops its future.
• A blocking pool runs blocking work off the lock. It must not write signals, and debug builds refuse such writes.
• wasm is single threaded. The host calls undra_poll() on the next microtask whenever the core asks to be scheduled.
• Shutdown is orderly. Every call still in flight is answered as cancelled and every stream ends, each exactly once, before the threads are joined.

Transports and modes#

Platform runtimes do the same jobs everywhere: load the core, allocate call ids, map replies to continuations, hold the mirror and apply change-sets on the main thread, implement observe and release, provide default adapters, implement the codecs, and refuse a mismatched core with a clear error that names both hashes.

Compatibility#

A UI and a core that were not built from the same schema must not talk. The schema hash is checked when the runtime attaches and surfaces as a typed mismatch error, and undra bindgen --check catches stale bindings at build time. Breaking the wire is a major version and needs an ADR; a changed schema still restores what the last build stored (Shipping an update).

Where drift is caught#

One schema removes most of the ways three platforms can disagree, and each remaining way has a check that fails:

• At load: the schema hash, on every platform, before a single call.
• At build: undra bindgen --check, and undra_bindings_test under Bazel, for committed bindings that are not what the schema generates.
• In review: undra schema diff marks each change to the public API breaking or additive.
• In the runtimes: the contract grid, 35 scenarios against the real core on Swift, Kotlin and TypeScript, every cell passing.
• In the hosts: undra drift compares recordings of one flow made on iOS, Android and the web: the calls each UI made and their order, what each platform's port adapters answered, the events each host pushed, what was observed, and the state every store ended in, with the arguments decoded through the schema (Testing).
• In a custom port: the generated Swift compiles under Swift's default main-actor isolation, proven by a compile test in CI (Ports).

Diagnostics#

Every macro mistake is an error with a stable code and a fixed shape: what happened, why, how to fix it, and where to read more. The same shape is used by schema validation and the runtime. This one is verbatim from the test suite:

error[undra::E0012]: `Vec<Box<dyn Any>>` cannot cross the boundary
  = note: trait objects have no wire representation
  = help: make `items` a concrete `#[undra::api]` type, or an enum listing the cases you need
  = docs: https://shreypdev.github.io/undra/docs/errors.html#E0012

The catalogue, by family:

The CLI has its own C00NN codes with the same shape; the error-codes page lists all of them, each with real messages from the test suite.

The constitution#

Twelve rules, enforced in review, not aspirational. They are the reason the project reads the way it does.

The engineering standards behind them: Rust 2024 edition with MSRV 1.85, clippy -D warnings, no anyhow in library crates, no println! in library code (logs go through the Log port), and no dependency that does not build for wasm32, iOS and Android.

Decisions on record#

The big decisions are written down as ADRs before the code. The ones in the tree today:

What Undra leaves out#

By design, Undra has no sync engine, no hosted services and no shared UI of any kind. Storage is a port the platform implements (Kv, SecureStore, Fs, and the opt-in Db over SQLite), not a database the core owns. Those are choices recorded in the specification and the roadmap, not gaps.

Read the source of truth#

• docs/SPEC.md: the binding specification for the wire, the ABI, the schema, the runtime model and the generated shapes. Code that disagrees with it is wrong.
• bench/RESULTS.md: every benchmark row, the machine, and what is still waiting for devices.
• .10x/reviews/: the adversarial reviews: the four core crates (signals, runtime, macros, ffi) first, then every feature before it merged.
• contract-tests/scenarios.md: the 35 scenarios that define "the platforms agree".

Edit this page on GitHub