Introduction

WeaveFFI generates type-safe bindings for 11 languages for any native library that exposes a C ABI, whether it’s written in Rust, C, C++, Zig, or another language: no hand-written JNI, no duplicate implementations, no unsafe boilerplate.

Define your API once as an IDL in YAML, JSON, or TOML, and WeaveFFI generates idiomatic packages for C, C++, Swift, Kotlin/Android, Node.js, WebAssembly, Python, .NET, Dart, Go, and Ruby, all talking to the same stable C ABI. Any backend that implements the symbols declared in the generated C header can be the producer.

Writing your producer in Rust? Annotate a normal module with #[weaveffi::module] and the macro generates the C ABI and derives the IDL for you, so you write no unsafe glue and keep no separate IDL in sync. The macro is one ergonomic path onto the same engine the IDL uses, so whichever you pick, the producer you build and the bindings you ship cannot drift.

Why WeaveFFI?

• One definition, eleven languages. Write the API once (safe Rust or an IDL) and ship packages to npm, SwiftPM, Maven, PyPI, NuGet, pub.dev, RubyGems, and Go modules.
• Safe Rust in, C ABI out. The #[weaveffi::module] macro emits the extern "C" thunks, marshalling every argument through an audited runtime, so a Rust producer writes no unsafe glue and the IDL is derived from the code rather than maintained beside it.
• Stable C ABI underneath. Every target speaks to the same extern "C" contract, so adding a new platform later is a code-gen change, not a rewrite.
• Idiomatic per-target output. No lowest-common-denominator surface area. Swift gets async/await and throws, Kotlin gets suspend and JNI glue, Python gets typed .pyi stubs, TypeScript gets Promises, Dart gets dart:ffi, all from the same definition.

Design principle: standalone generated packages

Generated packages are fully self-contained and publishable to their native ecosystem (npm, CocoaPods, Maven Central, PyPI, NuGet, pub.dev, RubyGems, etc.) without requiring consumers to install WeaveFFI tooling or runtime dependencies. WeaveFFI is a build-time tool for library authors; consumers should never need to know it exists. Helper code (error types, memory management utilities) is generated inline into each package rather than pulled from a shared runtime dependency.

Where to next

• Getting Started: install, define an IDL, generate, and call from C.
• The Rust Producer Macro: the #[weaveffi::module] attribute family, the supported feature set, and the roadmap.
• Comparison: feature matrix vs UniFFI, cbindgen, diplomat, SWIG, autocxx, and an honest “when to choose WeaveFFI” guide.
• FAQ: runtime cost, customization, Windows support, distribution, licensing.
• Samples: the kitchen-sink kvstore reference plus calculator/contacts/inventory walkthroughs.
• Generators: per-target reference for each of the eleven languages.
• Guides: memory ownership, error handling, async, configuration.

Getting Started

This guide walks you through installing WeaveFFI, defining an API as a language-neutral IDL, generating multi-language bindings from it, implementing the native library behind the generated C ABI, and calling it from C.

WeaveFFI works with any native library that exposes a C ABI, so the producer can be written in Rust, C, C++, Zig, or anything else that can speak C. This guide implements it in Rust because that’s the quickest to set up. If you’re writing a Rust producer, you can also let the #[weaveffi::module] macro generate the C ABI and derive the IDL for you, instead of hand-writing YAML (see step 2).

Prerequisites

You need the Rust toolchain (stable channel) to install the CLI, and for this guide’s Rust producer. Verify with:

rustc --version
cargo --version

The CLI is the only hard requirement. The library you generate bindings for can be written in any language that exposes a C ABI.

1) Install WeaveFFI

Install the CLI from crates.io:

cargo install weaveffi-cli

This puts the weaveffi binary on your PATH.

2) Define your API as an IDL

Describe the API once in a language-neutral IDL. Create math.yml with a record and a function:

version: "0.5.0"
package:
  name: my-math
  version: "0.1.0"
modules:
  - name: math
    structs:
      - name: Point
        fields:
          - { name: x, type: f64 }
          - { name: y, type: f64 }
    functions:
      - name: add
        params:
          - { name: a, type: i32 }
          - { name: b, type: i32 }
        return: i32

The optional package: block sets the name and version stamped into every generated package manifest (package.json, pyproject.toml, Package.swift, and so on). The IDL also supports primitives (i32, f64, bool, string, bytes, handle), optionals (string?), lists ([i32]), interfaces (objects with constructors, methods, and statics), and typed error domains (opt in per function with throws: true). See the IDL Schema reference for the full specification.

Prefer not to hand-write YAML? Run weaveffi new my-project to scaffold a starter project (an example IDL plus a Cargo.toml and src/lib.rs stub) you can edit instead.

Writing a Rust producer? You can make annotated Rust the single source of truth instead of a separate IDL: annotate a module with #[weaveffi::module] and point the generator straight at the source. The macro emits the C ABI and derives the IDL from your code, so you write no unsafe glue. See The Rust Producer Macro. The rest of this guide uses the IDL.

3) Generate bindings

Run the generator to produce bindings for all targets:

weaveffi generate math.yml -o generated --scaffold

The --scaffold flag also emits a scaffold.rs with Rust FFI stubs you can use as a starting point. The output tree looks like:

generated/
├── c/          # C header + convenience stubs
├── swift/      # SwiftPM package + Swift wrapper
├── android/    # Kotlin JNI wrapper + Gradle skeleton
├── node/       # N-API loader + TypeScript types
├── wasm/       # Wasm loader stub
└── scaffold.rs # Rust FFI function stubs

4) Examine the generated output

C header (generated/c/weaveffi.h)

The C generator produces an opaque struct with lifecycle functions and getters, plus a module-level function. Functions and constructors take an out_err parameter for error reporting (destructors and getters don’t):

typedef struct weaveffi_math_Point weaveffi_math_Point;

weaveffi_math_Point* weaveffi_math_Point_create(
    double x, double y, weaveffi_error* out_err);
void weaveffi_math_Point_destroy(weaveffi_math_Point* ptr);
double weaveffi_math_Point_get_x(const weaveffi_math_Point* ptr);
double weaveffi_math_Point_get_y(const weaveffi_math_Point* ptr);

int32_t weaveffi_math_add(int32_t a, int32_t b, weaveffi_error* out_err);

Swift wrapper (generated/swift/Sources/MyMath/MyMath.swift)

Structs become classes that own an OpaquePointer and free it on deinit. Module functions are grouped under a Swift enum namespace. Because add doesn’t declare throws: true, its Swift wrapper is a plain non-throwing function:

public class Point {
    let ptr: OpaquePointer
    deinit { weaveffi_math_Point_destroy(ptr) }

    public var x: Double { weaveffi_math_Point_get_x(ptr) }
    public var y: Double { weaveffi_math_Point_get_y(ptr) }
}

public enum Math {
    public static func add(a: Int32, b: Int32) -> Int32 { ... }
}

TypeScript types (generated/node/types.d.ts)

Structs become interfaces with mapped types. Functions use the IR name directly (no module prefix):

export interface Point {
  x: number;
  y: number;
}

// module math
export function add(a: number, b: number): number

5) Implement the library behind the C ABI

The generated C header (generated/c/weaveffi.h) is the contract your native library must satisfy, and it’s the same contract every language binding calls into. You can implement it in any language that can expose a C ABI; here we use Rust, starting from the generated scaffold.rs, which already contains a #[no_mangle] extern "C" stub (with a todo!() body) for every symbol in the header.

Create a library crate, add the WeaveFFI ABI helpers, and build a cdylib:

cargo new --lib my-math
cd my-math
cargo add weaveffi-abi

In Cargo.toml:

[lib]
crate-type = ["cdylib"]

Copy scaffold.rs into src/lib.rs and fill in the bodies. Implementing add looks like this (struct lifecycle omitted for brevity):

#![allow(unused)]
#![allow(unsafe_code)]
#![allow(clippy::not_unsafe_ptr_arg_deref)]

fn main() {
use weaveffi_abi::{self as abi, weaveffi_error};

#[no_mangle]
pub extern "C" fn weaveffi_math_add(
    a: i32,
    b: i32,
    out_err: *mut weaveffi_error,
) -> i32 {
    abi::error_set_ok(out_err);
    a + b
}

// Emit the fixed WeaveFFI C ABI runtime surface (free_string, free_bytes,
// error_clear, cancel_token_*) in one line. Call this exactly once per
// cdylib.
abi::export_runtime!();
}

Key points:

• Every exported function uses #[no_mangle] and extern "C".
• out_err must always be cleared on success with abi::error_set_ok.
• On error, call abi::error_set(out_err, code, message) and return a zero/null value.
• The library must export the WeaveFFI runtime symbols: invoke weaveffi_abi::export_runtime!() to emit all of them in one line instead of writing each #[no_mangle] thunk by hand.

Tip for Rust producers: the #[weaveffi::module] macro generates these #[no_mangle] extern "C" thunks for you from safe Rust, so you never fill in stubs by hand. See The Rust Producer Macro.

Build with:

cargo build

This produces a shared library (libmy_math.dylib on macOS, libmy_math.so on Linux, my_math.dll on Windows). The exported symbols match generated/c/weaveffi.h by construction.

6) Build and test with C

Write a small C program that calls your library:

main.c:

#include <stdio.h>
#include "weaveffi.h"

int main(void) {
    struct weaveffi_error err = {0};

    int32_t sum = weaveffi_math_add(3, 4, &err);
    if (err.code) {
        printf("error: %s\n", err.message);
        weaveffi_error_clear(&err);
        return 1;
    }
    printf("add(3, 4) = %d\n", sum);

    return 0;
}

Compile, link, and run:

# macOS
cc -I generated/c main.c -L target/debug -lmy_math -o my_example
DYLD_LIBRARY_PATH=target/debug ./my_example

# Linux
cc -I generated/c main.c -L target/debug -lmy_math -o my_example
LD_LIBRARY_PATH=target/debug ./my_example

Expected output:

add(3, 4) = 7

Next steps

• Run weaveffi doctor to check which platform toolchains are available.
• Read the IDL Schema reference for all supported types and features.
• Writing a Rust producer? See The Rust Producer Macro to skip the scaffold and generate the C ABI directly from annotated Rust.
• See the Calculator tutorial for a full end-to-end walkthrough including Swift and Node.js.
• Explore the Generators section for target-specific details.

Checking a single target

weaveffi doctor runs every toolchain check it knows about. To narrow it down to a single target, pass --target {name}:

weaveffi doctor --target dart
weaveffi doctor --target cpp
weaveffi doctor --target go
weaveffi doctor --target ruby
weaveffi doctor --target dotnet
weaveffi doctor --target python
weaveffi doctor --target swift
weaveffi doctor --target android
weaveffi doctor --target node
weaveffi doctor --target wasm

Only checks whose applies_to set contains the chosen target (plus the required Rust toolchain, which always runs) are executed. When --target is set the command exits with a non-zero status if any of those checks failed, making it scriptable in CI:

if ! weaveffi doctor --target dart; then
  echo "Dart toolchain not ready" >&2
  exit 1
fi

For machine-readable output (handy for piping into jq or aggregating results across CI matrices), use --format json:

weaveffi doctor --target ruby --format json | jq '.[] | select(.ok == false)'

Each entry has id, name, ok, version, hint, and applies_to fields.

Architecture

This page is the canonical reference for how WeaveFFI works internally. It is the document new generator authors and contributors should read before making non-trivial changes; all other documentation is consumer- or library-author-facing.

High-level pipeline

Every weaveffi generate invocation flows through the same five stages, in this order:

Input: annotated Rust (.rs) or an IDL (YAML/JSON/TOML)
   │
   ▼
Parse        ── weaveffi-ir::parse (IDL) | weaveffi-bridge (.rs): builds an `Api` IR
   │
   ▼
Validate     ── weaveffi-core::validate: rejects errors, collects warnings,
   │            and rewrites every parsed type reference to its resolved kind
   │
   ▼
Resolve      ── weaveffi-cli `CliConfig`: merges --config TOML and the
   │            inline generators: section into each target's typed config
   ▼
Generate     ── weaveffi-core::codegen::Orchestrator: dispatches every
   │            selected target generator in parallel via rayon
   ▼
Output       ── Each generator writes its files under {out_dir}/{target}/
                and updates {out_dir}/.weaveffi-cache/{target}.hash

Subcommands like validate, lint, diff, format, and watch re-use the parse and validate stages; generate, diff, and watch additionally exercise resolve and generate.

A .rs input is lowered to the IR by weaveffi-bridge, the same extractor the #[weaveffi::module] proc-macro uses to build a producer’s C ABI glue. Because the CLI and the macro share one extraction, the IDL the CLI derives and the symbols the macro emits are two views of one parse and cannot drift. See The Rust Producer Macro.

Crate layout

The workspace is structured as a small set of stable, focused crates. The dependency graph is acyclic and shallow:

weaveffi-cli ──► weaveffi-core ──► weaveffi-ir
       │              │
       │              ├──► weaveffi-gen-c
       │              ├──► weaveffi-gen-cpp
       │              ├──► weaveffi-gen-swift
       │              ├──► weaveffi-gen-android
       │              ├──► weaveffi-gen-node
       │              ├──► weaveffi-gen-wasm
       │              ├──► weaveffi-gen-python
       │              ├──► weaveffi-gen-dotnet
       │              ├──► weaveffi-gen-dart
       │              ├──► weaveffi-gen-go
       │              └──► weaveffi-gen-ruby
       └──► weaveffi-bridge ──► weaveffi-ir   (lowers annotated .rs to IR)

Producer side (a Rust cdylib depends on these, not on the CLI):

weaveffi ──► weaveffi-macros ──► weaveffi-bridge, weaveffi-core, weaveffi-ir
   │
   └──► weaveffi-abi   (the C ABI runtime, re-exported as `weaveffi::abi`)

weaveffi-abi  ──► (stand-alone, linked at run time by every cdylib that
                  exposes the WeaveFFI C ABI)

weaveffi-fuzz ──► weaveffi-ir, weaveffi-core (workspace-private; unpublished)

Crates that contain unsafe code opt in explicitly: weaveffi-abi, weaveffi-fuzz, the scaffold output emitted by weaveffi generate --scaffold, and any samples/* producer that dereferences a raw handle pointer in its own helpers (such as kvstore) add #![allow(unsafe_code)] at the top of their main source file. The thunks the #[weaveffi::module] macro emits instead carry a scoped #[allow(unsafe_code)] on each generated function, so a macro-based producer needs no crate-level opt-in. The workspace-wide unsafe_code = deny lint forbids it everywhere else.

CLI internals

weaveffi-cli is split so that main.rs holds only argument parsing and command dispatch; each subcommand and shared concern lives in its own module:

The cli_targets! registry

The 11 language targets used to be spelled out a dozen times (config struct fields, the --target parser, inline-generator merging, and the Orchestrator wiring). They now live in one declarative macro, cli_targets!, defined and invoked in config.rs:

#![allow(unused)]
fn main() {
cli_targets! {
    "c"       => c:       CConfig       via CGenerator,
    "cpp"     => cpp:     CppConfig     via CppGenerator,
    "swift"   => swift:   SwiftConfig   via SwiftGenerator,   strip,
    // … one line per target …
    "ruby"    => ruby:    RubyConfig    via RubyGenerator,
}
}

That single invocation expands to the CliConfig struct (one typed field per target), build_generators, apply_inline_target, and the strip_module_prefix/input-stamping fan-out. Adding a language is a one-line change here; see Adding a new generator.

Format canonicalization

weaveffi format (and format --check) round-trips an IDL through the IR and re-serializes it, so the on-disk form is canonical. For the check to be a no-op on an already-formatted file, serialization must omit every field that is at its default; otherwise serde would inject null, [], and false noise that the parser then drops on the next read, making format non-idempotent. The IR types therefore tag their optional/defaulted fields with #[serde(skip_serializing_if = …)] (Option::is_none, Vec::is_empty, and a local is_false for booleans that default to false). This keeps canonical IDLs terse and makes format idempotent; it also removes the now-meaningless default annotations from the generated weaveffi.schema.json.

The IR

weaveffi_ir::ir defines a small algebraic type system. The shapes that matter most:

• Api { version, modules, generators }: root node.
• Module { name, functions, interfaces, structs, enums, callbacks, listeners, errors, modules }: modules can nest.
• Function { name, params, returns, doc, throws, async, cancellable, deprecated, since }. The same shape describes an interface’s constructors, methods, and statics.
• InterfaceDef { name, doc, constructors, methods, statics }: an opaque object type; every interface also receives an implicit destroy symbol.
• TypeRef enumerates every supported type reference: primitives (I32, U32, I64, F64, Bool, StringUtf8, Bytes, Handle, BorrowedStr, BorrowedBytes), user types (Named(String), Record(String), RichEnum(String), Enum(String), Interface(String), TypedHandle(String)), and the four composite shapes (Optional, List, Map, Iterator).

User-type references are two-phase. The parser cannot know whether a bare identifier names a record, an enum, or an interface, so every user-type reference starts life as TypeRef::Named. The resolution pass (weaveffi_core::validate::resolve_type_refs, run by validate_api after the rule checks pass) rewrites each occurrence into Record (a struct), RichEnum (an algebraic enum), Enum (a C-style enum), or Interface, and qualifies cross-module references with the owning module’s dot-joined path. Generators run strictly post-resolution: no Named reference remains, and a generator may treat one as a bug (the core ABI lowering panics on it). Record and RichEnum share the opaque-object-pointer ABI (TypeRef::is_object_ref() returns true for both), while Enum lowers by value as an integer.

Every IR type derives Debug, Clone, PartialEq, Serialize, and Deserialize. Eq is derived where possible; a few types (Api, Module, StructDef, StructField) intentionally omit Eq because they transitively contain f64 (in default values) or serde_yaml::Value.

TypeRef (de)serializes as a string with custom syntax (i32, handle<T>, [T], {K:V}, T?, &str, &[u8]). The parser is weaveffi_ir::ir::parse_type_ref; both human-written IDL and the JSON Schema export rely on it.

Schema versioning

CURRENT_SCHEMA_VERSION (currently "0.5.0") lives in crates/weaveffi-ir/src/ir.rs. Pre-1.0, SUPPORTED_VERSIONS contains exactly the current version; older schema revisions are rejected by validation with an actionable error. When you change the schema:

1. Bump CURRENT_SCHEMA_VERSION (and the weaveffi-ir minor version).
2. Document the changes in CHANGELOG.md under a “Migration” section.
3. Update every sample IDL, the weaveffi new template, the README quickstart, and the Getting Started doc.

The stability page is the external contract; this section is the implementation note.

Validation

weaveffi_core::validate::validate_api is the single entry point. It returns a Vec<ValidationError> (errors that must be fixed before generation) and a separate Vec<ValidationWarning> (advisory; the lint subcommand surfaces these).

Errors enforced today:

• Identifier well-formedness (is_valid_identifier).
• Reserved keyword rejection (if, else, for, while, loop, match, type, return, async, await, break, continue, fn, struct, enum, mod, use).
• Uniqueness of module/function/parameter/struct/enum/field/variant names within their respective scopes, plus API-wide uniqueness of bare type names (structs, enums, interfaces, and error domains share one global namespace).
• Structs must have at least one field; enums at least one variant; interfaces at least one member.
• Enum discriminant uniqueness within an enum.
• Type references resolve by bare name across the whole API and are qualified to their owning module during resolution, which also rewrites each parsed TypeRef::Named reference into its resolved kind (see The IR and Cross-module references).
• Interface members (constructors, methods, statics) share one namespace per interface; constructors declare no return and cannot be async; interface types are valid only as parameters, returns, and optionals of those. Free functions and interface members share the module’s C symbol namespace.
• throws: true requires an error domain in scope (the module or an ancestor).
• Iterator return types are valid in return position only.
• Map keys must be a primitive or enum type.
• event_callback on a listener must reference a callback in the same module.
• Error domain name must not collide with a function name in the same module; codes must be non-zero and unique within the domain; code names must be unique across every domain in the API.

Warnings emitted today:

• LargeEnumVariantCount (>100 variants).
• DeepNesting (composite types nested deeper than 3 levels).
• EmptyModuleDoc (no doc: on any function in the module).
• AsyncVoidFunction (async without a return type).
• MutableOnValueType (mutable: true on a non-pointer parameter).
• DeprecatedFunction (informational).

Interfaces, typed error domains, async functions, cancellable functions, listeners, callbacks, iterators (iter<T>), typed handles (handle<T>), borrowed types (&str, &[u8]), nested modules, and cross-module type references are all first-class. They pass validation and every generator handles them. Do not re-add validator rejections for these features.

Per-target capability gating still exists as a mechanism: each generator declares a TargetCapabilities (async, callbacks, listeners, iterators), and the orchestrator fails generation (listing the offending IDL definitions) when a selected target cannot deliver a used feature. Today every shipped target declares full support, so the gate only fires if a future target (or a new gated feature) introduces a gap; a partial target’s allow_unsupported = true config would opt into generating the rest of the surface with explicit throwing stubs in place of the unsupported entry points. The Wasm generator’s Emscripten mode is the one place stubs still appear: async functions, callbacks, and listeners become explicit throwing stubs there (and are omitted from the TypeScript declarations) because Emscripten modules do not portably expose the trampoline machinery. Capability failures and mode gaps must stay loud: never skip a definition silently.

Generator configuration resolution

There is no single global config object. Each generator owns its own typed Generator::Config (CConfig, SwiftConfig, PythonConfig, …), so adding a knob to one target only touches that target’s crate. The CLI gathers all of them into one CliConfig struct (generated by the cli_targets! macro, one field per target) and resolves it from three sources (later wins):

1. Defaults baked into each Config::default().
2. The --config <file.toml> external file passed to generate.
3. The inline generators: section of the IDL.

The IDL section is the project-local source of truth and overrides any machine-local TOML; see the Generator Configuration guide. Each resolved config is hashed (via serde_json) into the per-generator cache key, so a config-only change re-runs just that target.

Orchestrator

weaveffi_core::codegen::Orchestrator coordinates the generator stage:

1. If --force is set, every cache entry under {out_dir}/.weaveffi-cache/{target}.hash is invalidated.
2. For each registered generator, the orchestrator hashes (api, generator.name(), config) and compares against the persisted hash, so an IR or config change re-runs just the affected target.
3. If a pre_generate hook is configured (OrchestratorHooks), the orchestrator shells out to it (cmd on Windows, sh elsewhere) and aborts on non-zero exit.
4. The pending generators run in parallel via rayon::par_iter. Generators must therefore be Send + Sync.
5. post_generate runs once after every generator has succeeded.
6. Each successful generator’s hash is persisted.

This per-generator caching is what lets weaveffi generate skip every target whose IR has not changed since the last run; see the Generator Configuration guide.

The Generator trait and the language-backend framework

The orchestrator consumes the object-safe Generator trait (weaveffi_core::codegen::Generator). Each generator owns a typed, serializable Config; the orchestrator stays config-agnostic by working through the object-safe DynGenerator view:

pub trait Generator: Send + Sync {
    /// Per-target options. Must round-trip through `serde_json` so the
    /// orchestrator can fold the config into the cache key.
    type Config: Serialize + Default + Clone + Send + Sync;

    /// Stable short name (`"swift"`, `"c"`, …): the `--target` token and
    /// the per-generator cache-file basename.
    fn name(&self) -> &'static str;

    /// Render the bindings under `out_dir`.
    fn generate(&self, api: &Api, out_dir: &Utf8Path, config: &Self::Config) -> Result<()>;

    /// Files `generate` would write (used by `--dry-run` and `diff`).
    fn output_files(&self, api: &Api, out_dir: &Utf8Path, config: &Self::Config) -> Vec<String>;
}

To erase the associated Config, a typed generator is paired with a concrete config value via ConfiguredGenerator::new(gen, config), which implements the object-safe DynGenerator trait the Orchestrator stores. The CLI builds one ConfiguredGenerator per selected target from the resolved CliConfig.

LanguageBackend and the shared driver

Generators are not written against Generator directly. Each target implements weaveffi_core::backend::LanguageBackend and is bridged to Generator by the impl_generator_via_backend! macro, so the model construction, the file I/O, and the output_files derivation live in one place instead of being re-implemented eleven times:

pub trait LanguageBackend: Send + Sync {
    type Config: Serialize + Default + Clone + Send + Sync;
    fn name(&self) -> &'static str;

    /// C ABI symbol prefix; the driver builds the `BindingModel` with it.
    fn prefix<'a>(&self, config: &'a Self::Config) -> &'a str { "weaveffi" }

    /// The single required hook: assemble every output file. Rendering is
    /// pure; the driver performs the actual writes.
    fn files(&self, api: &Api, model: &BindingModel,
             out_dir: &Utf8Path, config: &Self::Config) -> Vec<OutputFile>;

    /// Canonical per-module walk (error → enums → structs → interfaces →
    /// callbacks → listeners → functions) with call-shape dispatch.
    /// Single-pass backends override the `render_enum`/`render_struct`/
    /// `render_function` hooks and call this; multi-pass backends build
    /// their layout in `files` directly.
    fn emit_members(&self, out: &mut String, module: &ModuleBinding, config: &Self::Config) { /* … */ }
    // render_error / render_enum / render_struct / render_interface /
    // render_callback / render_listener / render_function: all default
    // to no-op.
}

The free backend::run builds the BindingModel once (with the backend’s prefix), calls files, and writes each OutputFile (creating parent directories). backend::output_files calls the same files and returns the sorted path list, so generate and output_files are derived from a single source and cannot drift. Python is the reference single-pass backend (it overrides the per-entity hooks and composes emit_members); Ruby, .NET, Node, and Android are multi-pass (their FFI declarations, wrapper classes, and secondary surfaces such as the JNI C shim are emitted in their own passes inside files).

Generators emit code into a String; there is no template-engine layer (an early Tera prototype intended for user template overrides was removed in 0.4.0 because nothing read from it). Indentation and block nesting are managed by the CodeWriter toolkit (see below) rather than by hand-rolled \n/space bookkeeping. Shared rendering infrastructure lives in weaveffi_core:

• backend: the LanguageBackend trait, the run/output_files driver, the OutputFile type, and the impl_generator_via_backend! bridge macro.
• model::BindingModel: the normalized, fully-lowered view every backend renders from (precomputed C symbol names and ABI signatures).
• codegen::writer::CodeWriter: the structured code-emission toolkit (see The CodeWriter emission toolkit).
• codegen::common: module-tree traversal (walk_modules, walk_modules_with_path), the is_c_pointer_type ABI classifier, doc-comment emission (emit_doc), and pascal_case naming.
• plan: the marshalling plan, the language-neutral calling contracts every backend renders (see The marshalling plan).

The CodeWriter emission toolkit

weaveffi_core::codegen::CodeWriter is a small, deterministic, language-agnostic builder that owns indentation and block scoping, so a generator describes the shape of its output instead of threading \n and indent strings through every push_str. It is the preferred way to render any indented, line-oriented body.

let mut w = CodeWriter::four_space(); // or two_space() / tabs()
w.line("class Greeter:");
w.scope(|w| {                          // one deeper indent level
    w.line("def greet(self, name):");
    w.scope(|w| {
        w.line("return f\"Hello, {name}\"");
    });
});
let src = w.finish();                  // owns the assembled String

Design points that keep output stable and migrations safe:

• One indent authority. line writes indent + text + "\n"; scope/block push and pop a level around a closure; indent/ dedent adjust it manually. Blank lines (blank) never carry trailing whitespace, preserving the determinism contract.
• with_depth(n) seeds the starting indent so a writer can render a fragment that will be spliced into an already-indented context.
• raw appends pre-formatted text verbatim (no re-indentation), which is how existing helpers (e.g. emit_doc) and large literal blocks compose into a writer without a rewrite. This makes adoption incremental: a backend can move one function at a time onto CodeWriter while the snapshot suite proves the output is unchanged byte-for-byte.

The Python backend (weaveffi-gen-python) is the reference adopter: its return marshalling, getters, enums, callbacks, listeners, and the central function renderer are built with CodeWriter. Remaining generators are being migrated onto it incrementally, each move guarded by the snapshot corpus.

The signatures above use Result<T> from anyhow and IR types from weaveffi_ir; consult those crates for the precise import set.

Implementation notes:

• Implement name() (the --target flag value, e.g. "swift"), the associated Config type, and files(); override prefix() when the config carries a configurable c_prefix.
• Return every emitted file from files(); --dry-run and weaveffi diff read the derived output_files, so there is no separate list to keep in sync.
• All paths are joined under out_dir; do not write outside the passed directory or you will break the per-generator cache.
• Generators run in parallel; share no mutable state across calls.

C ABI naming convention

Every emitted C symbol follows {c_prefix}_{module}_{function} (default c_prefix = "weaveffi"). The c_prefix configuration is honored end-to-end: when set, the generated C output uses it consistently, including references to weaveffi-abi runtime symbols ({c_prefix}_error, {c_prefix}_error_clear, {c_prefix}_free_string, {c_prefix}_free_bytes).

Struct lifecycle, enum constants, and getter symbols follow the patterns in the C generator reference.

The ABI lowering model

The C ABI is the foundation every binding sits on: a flat, C-callable surface where each IDL type lowers to a fixed sequence of C parameters. A string becomes one const char*; bytes becomes const uint8_t* {name}_ptr, size_t {name}_len; a map<K,V> becomes parallel {name}_keys / {name}_values / {name}_len slots; collection and out-of-band returns append out_* pointers; and every fallible call ends with a trailing {prefix}_error*.

That calling convention is defined once, in weaveffi_core::abi, rather than re-derived inside each generator:

• CType: a prefix-agnostic algebra of C types (Int32, Size, Ptr { pointee, const_pos }, StructTag { module, name }, …) with a single render_c(prefix) method that produces canonical C spelling.
• element_ctype(ty, module): the C type of a single element.
• lower_param(name, ty, module, mutable): expands one IDL parameter into its ordered AbiParam slots.
• lower_return(ty, module): the return CType plus any trailing out_* AbiParams.
• callback_result_params(ty, module): the trailing slots an async callback receives after (context, err).

The C and C++ generators render these slots straight to C declarations, so their headers are the model by construction. The declarative consumer generators (Python, Ruby, .NET) call the same lower_* functions and map each CType onto their own FFI vocabulary (ctypes.c_*, Ruby FFI symbols, P/Invoke IntPtr/UIntPtr). This is what guarantees the producer header and every consumer agree on the parameter arity and order of a symbol: the class of drift that previously hid in a dozen hand-written copies of the lowering.

A few conventions are genuinely language-specific and stay local to their generator rather than leaking into the shared model:

• Iterator returns. The C ABI returns an opaque iterator handle ({prefix}_{module}_{Iter}*) while other backends model the same slot differently, so lower_return refuses an Iterator and each caller lowers it explicitly.
• byref out-params. ctypes (Python) and P/Invoke (.NET) express a map return’s out_keys / out_values with an extra pointer level or the C# out keyword; those renderings stay in the respective generator.

Imperative generators (Go cgo, Node, Dart, Swift) build their FFI signatures inline with marshalling code and share the single is_c_pointer_type classifier in weaveffi_core::codegen::common. The Android (JNI) and Wasm backends target different ABIs entirely and do not consume the C lowering.

When you add a parameter shape or change how a type crosses the boundary, change weaveffi_core::abi and let the consumers inherit it; the snapshot suite will show every generator the edit touches.

The marshalling plan

The ABI lowering model answers which symbols exist and what their C signatures are. weaveffi_core::plan is a distinct layer one level up, sitting between that lowering and the syntax backends: a language-neutral statement of the calling contracts every backend renders, the questions the eleven generators used to answer independently (and inconsistently):

• Errors. ErrorStrategy (Throws | Trap): when a call reports through out_err, is the non-zero code a typed domain error the caller can catch (throws: true), or a producer bug the wrapper must trap on? FnBinding::error_strategy() answers it once. See the Error Handling guide.
• Ownership. ReturnFree and ElemFree (via the return_free and elem_free functions): after copying a returned value, or one array/map/iterator element, into a native one, exactly which runtime release call does the wrapper owe ({prefix}_free_string, {prefix}_free_bytes, a type’s _destroy symbol), if any?
• Iterators. IteratorProtocol (IteratorBinding::protocol): the iter<T> pull contract, including the requirement that wrappers stay lazy (one producer next call per consumer step, never a hidden drain into a list), the per-element release plan, and the destroy-exactly-once handle lifecycle.
• Async. AsyncProtocol (AsyncBinding::protocol): the completion-callback contract: the callback fires exactly once from an arbitrary producer thread, borrowed result buffers are valid only for the callback’s duration, and owned-object results are adopted by the consumer.

Generators are thin syntax backends over this shared plan: a backend that renders these plans in its own syntax cannot drift from the others on semantics; only the spelling differs. The producer side consumes the same contracts: each weaveffi-macros codegen submodule states which plan clause it implements (the generated _async launchers free borrowed result buffers after the callback returns, iterator thunks yield one element per _next, and error dispatch follows ErrorStrategy), so the emitted glue and every consumer wrapper agree by construction. When a generator needs a free/destroy or throws/trap decision, it should consume the plan rather than re-derive the fact with a local match.

Determinism

Regenerating with the same WeaveFFI version on the same IDL produces byte-identical output.

The contract is enforced by determinism tests in the snapshot suite. Internally, every HashMap iteration that contributes to generated output has been replaced with BTreeMap or an explicit sort, and the serde_json-backed cache key uses canonical ordering.

If you need to iterate a map inside a generator, use BTreeMap or collect to a Vec and sort_by_key. Never rely on HashMap iteration order for output; CI snapshot tests will fail non-deterministically on different platforms or insta orderings.

Snapshot tests

crates/weaveffi-cli/tests/snapshots.rs runs every generator across a ten-fixture corpus (tests/fixtures/01_calculator … 10_shapes: calculator, contacts, inventory, async-demo, events, kitchen-sink, docs-everywhere, kvstore, nested-modules, and shapes). Output is diffed via cargo-insta. When a snapshot diff is intentional:

cargo install cargo-insta --locked
cargo test -p weaveffi-cli --test snapshots
cargo insta review

Press a to accept, r to reject, s to skip. Commit accepted .snap files in the same commit as the code change that produced them; never commit .snap.new. CI rejects pending snapshots.

The harness redacts the WeaveFFI version in each file’s generated-by prelude to [VERSION] before snapshotting (and separately asserts the real prelude is present), so a routine version bump does not invalidate every snapshot in the corpus.

Adding a new generator

A condensed checklist (the long version lives in CONTRIBUTING.md):

1. Create crates/weaveffi-gen-<lang>/ mirroring the layout of weaveffi-gen-c. Add it to members in the root Cargo.toml and depend on weaveffi-core and weaveffi-ir.
2. Implement weaveffi_core::backend::LanguageBackend: define the associated Config type, then name, prefix (if the config carries a c_prefix), and files (returning every OutputFile). For a single-pass layout, override the render_enum/render_struct/ render_function hooks and compose emit_members; otherwise build the layout directly in files. Then add weaveffi_core::impl_generator_via_backend!(<Generator>); to bridge it to Generator (this derives generate and output_files). Reuse BindingModel and weaveffi_core::codegen::common instead of re-deriving traversal or ABI classification.
3. Wire the generator into the cli_targets! registry macro in crates/weaveffi-cli/src/config.rs: add one line ("<name>" => <field>: <Config> via <Generator>, plus strip if the generator honors strip_module_prefix). That single entry is the source of truth: it expands to the CliConfig field, the --target <name> parser entry, inline-config merging, and the Orchestrator registration. No other CLI edits are required.
4. Add snapshot fixtures in crates/weaveffi-cli/tests/snapshots.rs covering at minimum the calculator, contacts, inventory, async-demo, and events sample IDLs.
5. Document the generator under docs/src/generators/<lang>.md and link it from docs/src/SUMMARY.md.
6. Add conformance consumers under conformance/<lang>/ and wire them into conformance/run.sh.
7. Add scripts/publish-crates.sh to the dependency-ordered publish list (only when the crate is ready to be released).

Where to read next

• IDL Schema: the type system and validation rules from a user’s perspective.
• Generator Configuration: every option a consumer can set.
• Stability and Versioning: what counts as a breaking change once we hit 1.0.
• Memory Ownership: the per-target memory rules every generator must enforce.
• Async Functions: the per-target async invariants every async-capable generator implements.

Comparison

WeaveFFI sits in a crowded ecosystem of FFI tooling. This page is an honest, side-by-side look at how it compares to the projects you are most likely to evaluate against it: UniFFI, cbindgen, diplomat, SWIG, and autocxx.

All comparisons reflect the public state of each project at the time of writing. If something here is out of date, please open a PR.

At a glance

Legend: ✓ = first-class support; partial = supported with caveats or via extensions; ✗ = not supported; n/a = not applicable to that tool’s scope.

Where competitors are stronger

We try hard to be honest about the trade-offs. Pick the right tool for the job:

• UniFFI is more mature. It ships in production at Mozilla (Firefox Sync, Glean, Nimbus) and has years of battle-testing across iOS, Android, and desktop. If you only need Swift, Kotlin, and Python today and you are comfortable with a UDL-or-proc-macro workflow, UniFFI is the safer choice.
• cbindgen is simpler if all you want is a C header. WeaveFFI generates a C header and ten other targets. If you only consume the C surface from C/C++ code, cbindgen has less ceremony, no IDL file, and a smaller dependency footprint.
• diplomat has a more polished C++ story. Its C++ output uses richer templates and integrates more cleanly with existing C++ codebases. WeaveFFI’s C++ output is RAII-based and includes a CMakeLists.txt, but it’s optimized for greenfield projects, not for slotting into a 20-year-old C++ build system.
• SWIG covers languages WeaveFFI doesn’t. Lua, Tcl, R, Octave, Perl, PHP: if your target is exotic, SWIG probably has a generator. SWIG also natively understands C and C++ headers, so you don’t need to author an IDL at all.
• autocxx is unmatched for “wrap an existing C++ library.” It reads your C++ headers directly and uses bindgen + cxx under the hood. WeaveFFI does not parse C++; you describe the surface area you want to expose, and WeaveFFI generates the contract.
• No IDE plugin yet. The other tools listed have community VSCode/JetBrains extensions of varying quality. WeaveFFI ships a JSON Schema for editor autocompletion and a format command, but no first-party IDE plugin.
• No formal stability guarantee yet. WeaveFFI is pre-1.0; the IDL, generated output, and runtime symbol names can shift in minor releases. UniFFI, cbindgen, and SWIG offer stronger compatibility commitments today.

When to choose WeaveFFI

WeaveFFI is the right pick when you want:

1. One source of truth for many languages. If your library has to land in npm and SwiftPM and PyPI and NuGet and pub.dev and RubyGems and a Go module and a Gradle artifact, that’s the WeaveFFI sweet spot. UniFFI covers a smaller subset out of the box; cbindgen and autocxx don’t try.
2. Standalone, publishable consumer packages. Generated packages are self-contained: a Swift consumer adds your .xcframework + a SwiftPM manifest and is done. No “install WeaveFFI” step on the consumer side.
3. A native library that isn’t (only) Rust. WeaveFFI works against anything that exposes a stable C ABI: Rust (with --scaffold convenience), C, C++, Zig, etc. UniFFI and diplomat assume Rust; autocxx assumes C++.
4. Idiomatic per-target output, not a lowest-common-denominator API. Async functions become async/await in Swift, Promises in Node, suspend fun in Kotlin, async def in Python, and Task<T> in C#, all from the same async: true flag in the IDL.
5. A CLI workflow with validate, lint, diff, watch, and format. WeaveFFI is built for monorepos and CI: every sub-command has a --format json output mode, and diff --check and format --check are designed to drop into pre-commit and CI gates.
6. Honest pre-1.0 churn, documented every release. Every breaking IDL change is called out in CHANGELOG.md with a migration note, and weaveffi validate rejects out-of-date schema versions with an actionable error instead of silently misreading them.

When to choose something else

• You only need Swift + Kotlin + Python and want maximum stability: use UniFFI.
• You only need a C header for a Rust crate: use cbindgen.
• You’re wrapping a large existing C++ codebase: use autocxx (or cxx + bindgen directly).
• Your target language is Lua, Tcl, R, Octave, Perl, or PHP: use SWIG.
• You need a battle-tested C++ binding generator with rich template support: use diplomat or SWIG.

Migrating to / from WeaveFFI

WeaveFFI’s IDL is intentionally close to UniFFI’s UDL surface area, which makes hand-porting straightforward in either direction. There is no automatic UDL → WeaveFFI converter today, but weaveffi extract can read annotated Rust source and produce a starting IDL, which is often the fastest path off any Rust-only generator. See the extract guide for details.

FAQ

The top ten questions we hear about WeaveFFI. For broader context see the introduction, the comparison page, and the per-target generator docs.

1. Why not UniFFI?

UniFFI is excellent, ships in production at Mozilla, and is the right choice if you only need Swift, Kotlin, and Python. We built WeaveFFI because we needed:

• More targets out of the box. WeaveFFI ships first-class generators for C, C++, Swift, Kotlin/Android, Node.js, Wasm, Python, .NET, Dart, Go, and Ruby, eleven in total. UniFFI’s first-party language list is shorter and the rest live as community extensions of varying maturity.
• A standalone CLI workflow. WeaveFFI is a single binary (cargo install weaveffi-cli) with validate, lint, diff, watch, format, and extract subcommands designed to drop into CI. UniFFI is a build-script integration first.
• A non-Rust-only story. WeaveFFI’s IR is language-agnostic: any backend that can expose a stable C ABI (Rust, C, C++, Zig, …) can be driven from the same IDL. UniFFI is Rust-first.
• A YAML/JSON/TOML IDL with a JSON Schema. WeaveFFI ships weaveffi.schema.json for editor autocompletion. UniFFI’s UDL is custom-syntax and proc-macro is Rust-only.

If your matrix is only Swift+Kotlin+Python and you want maximum maturity today, UniFFI is the safer pick. See the comparison page for the full table.

2. Can I use it with C++ codebases?

Two distinct cases:

• Generating C++ bindings for consumers. Yes, --target cpp emits a header-only RAII C++ API (weaveffi.hpp) with std::optional, std::vector, std::unordered_map, exception-based errors, move semantics, and a CMakeLists.txt. See the C++ generator docs.
• Wrapping an existing C++ library. WeaveFFI does not parse C++ headers; you describe the surface area you want to expose in the IDL and the C++ implementation provides the stable C ABI symbols. If you want to start from C++ headers and auto-generate, look at autocxx or SWIG.

3. Does it support generics?

Yes, with a curated set of built-in generic shapes rather than open user-defined generics:

• handle<T>: typed opaque pointers (compile-time-checked handle types per resource).
• iter<T>: lazy streaming sequences with _next / _destroy ABI.
• [T]: homogeneous lists.
• {K:V}: homogeneous maps (passed as parallel key/value arrays at the C ABI).
• T?: optionals.
• &str, &[u8]: borrowed views (no copy at the boundary).

We deliberately do not support arbitrary user-defined generics (e.g. Result<MyType, MyError> parameterized at the IDL level). Cross-language generic monomorphization is a rabbit hole; the built-in shapes cover ~95% of real-world FFI surface area without requiring every target generator to implement type-erasure logic.

4. What’s the runtime overhead?

WeaveFFI itself adds no runtime beyond the small weaveffi-abi crate (a few hundred lines: error helpers, string/byte-slice allocators, cancel tokens). Per-call overhead is the cost of:

1. Marshalling arguments across the C ABI (string→const char*, list→*ptr + len, etc.). Borrowed types (&str, &[u8]) avoid copies.
2. The single extern "C" function call.
3. Marshalling the return value back.

For primitive arguments and return types, this is roughly the cost of a normal function call plus an out-pointer write for the error. For larger structs, lists, and maps, it’s dominated by the underlying allocation/copy cost, not by anything WeaveFFI inserts.

Async functions add a callback indirection (the C ABI is callback-based) plus whatever runtime your backend uses. There is no scheduler imposed by WeaveFFI; the implementation chooses how to spawn work.

5. How are errors propagated?

At the C ABI, generated functions take a trailing weaveffi_error* out_err parameter. On success the runtime sets code = 0 and message = NULL. On failure it sets a non-zero code and a heap-allocated UTF-8 message that the caller frees via weaveffi_error_clear.

Above the ABI, error surfacing is opt-in per function: a module declares an error domain (errors: in the IDL) with named, stable codes, and functions marked throws: true surface those codes as the domain’s typed error in each language. Taking a KvError domain as the example:

• C: direct weaveffi_error struct, plus an enum constant per code (weaveffi_kv_KvError_KeyNotFound).
• C++: per-domain exception types (KvError + per-code subclasses).
• Swift: throws with a domain enum conforming to Error (catch KvError.keyNotFound).
• Kotlin: domain exceptions (KvException extends WeaveFFIException, one nested class per code).
• Node.js / TypeScript: domain error classes (KvError extends WeaveFFIError); async functions reject the promise with them.
• Wasm/JS: the same domain error classes.
• Python: a domain exception hierarchy (KvError extends WeaveFFIError, KeyNotFound extends KvError).
• .NET: thrown KvException (extends WeaveFFIException).
• Dart: thrown KvException (extends WeaveFFIException).
• Go: a second error return carrying a typed error struct matched via errors.As and code constants (KvErrorKeyNotFound).
• Ruby: domain exception classes (KvError with nested per-code classes).

Non-throwing functions (the default) return plain values; a non-zero code on one of them only ever reports a producer bug, so the wrapper panics or traps instead of surfacing an error type. See the Error Handling guide.

6. Can I customize the generated code?

Yes, via two escape hatches in increasing order of power:

1. Generator config (--config cfg.toml or inline generators: table in the IDL). Controls Swift module names, Android package, C prefix, C++ namespace, Dart/Go/Ruby package names, module-prefix stripping (strip_module_prefix), and other per-target knobs. See the Generator Configuration guide.
2. Hook commands (pre_generate / post_generate in the config). Run arbitrary shell commands before and after generation, useful for prettier, swiftformat, gofmt, etc.

If you need to change the C ABI shape itself, that’s a generator contribution. See CONTRIBUTING.md.

7. Does it work with Flutter?

Yes, --target dart emits dart:ffi bindings plus a pubspec.yaml that’s drop-in compatible with both Flutter and pure Dart projects. You ship the generated package alongside the cdylib for each platform Flutter targets (iOS framework, Android .so per ABI, macOS .dylib, Linux .so, Windows .dll).

The generated Dart code uses the standard package:ffi helpers, so it works on every Flutter platform that supports dart:ffi (i.e. everything except Web today; for the browser, use --target wasm and load the bindings via JS interop). See the Dart generator docs.

8. Is it Windows-friendly?

Yes, WeaveFFI itself builds and runs on Windows (the CLI is plain Rust, no platform-specific dependencies). Generated outputs target Windows correctly:

• C / C++: emitted headers are compiler-agnostic (MSVC, clang, gcc), and every prototype carries a portable WEAVEFFI_API visibility macro. Consumers resolve it to __declspec(dllimport); a C/C++/Zig backend that implements the header builds its library with WEAVEFFI_BUILD defined to export the symbols via __declspec(dllexport) (see the C generator docs).
• .NET: P/Invoke uses DllImport with the right calling conventions and looks up weaveffi.dll.
• Node.js: the N-API addon builds with node-gyp on Windows.
• Python: ctypes loads weaveffi.dll.
• Dart: looks up weaveffi.dll via Platform.isWindows.
• Go / Ruby: load the appropriate Windows shared library.

CI builds and tests the workspace on Windows on every PR, and a dedicated Windows job generates every target’s bindings and verifies the output. The full conformance harness (running the generated bindings in all eleven languages) is exercised on Linux. If you hit a Windows-specific issue, please open an issue.

9. How do I distribute the cdylib?

You build a platform-specific shared library per target triple and ship it alongside the generated package. Three common patterns:

• Per-platform npm/PyPI/gem packages. Publish one package per (os, arch) and use a small loader in the consumer that picks the right binary at install or runtime. WeaveFFI generates the TypeScript/Python/Ruby loader, you supply the binaries.
• xcframework for Swift. Bundle iOS device, iOS simulator, and macOS slices into a single .xcframework that SwiftPM can consume. The generated Package.swift references it as a .binaryTarget.
• .aar for Android. Package the JNI shim + per-ABI .so files into an Android Archive that Gradle resolves like any other dependency. The generated build.gradle skeleton is compatible with this layout.

The name, version, and metadata stamped into every generated manifest (package.json, pyproject.toml, *.gemspec, *.csproj, pubspec.yaml, Package.swift, go.mod, …) come from a single package: block in your IDL, so you set your identity once and every ecosystem stays in sync.

There is no opinionated “weaveffi publish” command today; you use each ecosystem’s normal publish flow. The generator-specific docs cover the recommended build matrix per language.

10. What’s the licensing?

WeaveFFI is dual-licensed under MIT OR Apache-2.0 at your option, the same dual-license used by the Rust project itself.

You can use WeaveFFI in commercial, closed-source, or open-source projects without restriction. Generated code carries no license header of its own; it’s yours to license however you like. Contributions to the WeaveFFI repo are accepted under the same MIT-or-Apache-2.0 dual license; see CONTRIBUTING.md.

Stability and Versioning

WeaveFFI follows Semantic Versioning once it reaches 1.0.0. Until then it is in active pre-1.0 development and any surface area may change between minor versions. This page documents exactly what is and isn’t covered, what the deprecation policy will look like post-1.0, and how to bind your CI to a stable WeaveFFI workflow today.

What semver covers (post-1.0)

After the 1.0.0 release, the following surfaces will be governed by SemVer:

• CLI flags and subcommands. Every documented weaveffi <subcommand>, every flag, every exit code, and every documented stdout/stderr format (--format json payloads in particular). Adding a new optional flag is a minor bump; removing or renaming one is a breaking change.
• IDL schema. The set of accepted top-level keys, type-reference syntax (handle<T>, iter<T>, [T], {K:V}, T?, &str, &[u8], primitives, user-defined struct/enum/interface names), version semantics, and the JSON Schema exported by weaveffi schema --format json-schema.
• Generated code shape. The exported symbol names, function signatures, type names, package layouts, and ABI conventions of every generator’s output. A patch release will not change the bytes of the generated output; a minor release may add new symbols but will not remove or rename existing ones; a major release may break.
• Public Rust API of every published crate. That is weaveffi-ir, weaveffi-abi, weaveffi-core, weaveffi-gen-c, weaveffi-gen-cpp, weaveffi-gen-swift, weaveffi-gen-android, weaveffi-gen-node, weaveffi-gen-wasm, weaveffi-gen-python, weaveffi-gen-dotnet, weaveffi-gen-dart, weaveffi-gen-go, weaveffi-gen-ruby, and weaveffi-cli. The Generator trait, the Orchestrator, the IR types, and the C ABI runtime symbols exported from weaveffi-abi are all public contracts.

What is NOT covered pre-1.0

While the workspace is at 0.x, everything above may change without warning. In practice we try to keep breaking changes batched (one batch per minor release, with a schema-version bump), but the contract is “no contract.” Things that have already changed during 0.x:

• IR type-reference syntax (callback was removed in 0.3.0).
• The IR TypeRef::Struct variant was split into Named (the unresolved parsed form), Record, and RichEnum, and a shared marshalling-plan module (weaveffi_core::plan) now states the calling contracts every generator renders. Generated wrapper surfaces changed with it: iter<T> returns became each target’s native lazy iteration idiom (Go []T became an iter.Seq, C++ std::vector<T> became a range type), and async result buffers became producer-freed after the completion callback returns.
• Schema 0.5.0 introduced first-class interfaces (interfaces:, objects with constructors, methods, and statics) and per-function typed errors (throws:), and made bare type names unique across the whole API. The samples’ handle-based resource surfaces were rewritten as interfaces.
• The Generator trait gained generate_with_config in 0.3.0, then was reworked in 0.5.0 into an associated Config type (with an object-safe DynGenerator view) that replaced the *_with_config method pair. A prototype Tera template hook (generate_with_templates, --templates, template_dir) was added and then removed in 0.4.0 because no generator ever consumed it.
• The C ABI runtime added weaveffi_arena_* and weaveffi_cancel_token_* families.
• weaveffi doctor gained --target and --format json.

Pin the WeaveFFI version in CI (cargo install weaveffi-cli --version =0.3.0) and vendor the generated output in your repository so that upgrades are an explicit, reviewable event.

Post-1.0 deprecation policy

Once we reach 1.0.0, breaking changes will follow this path:

1. The feature is marked deprecated in a minor release. The CLI prints a --warn-style diagnostic (weaveffi: warning: <name> is deprecated; <suggested replacement>) on every invocation that touches it. The generators emit a native deprecation marker where the target language supports one (#[deprecated] in Rust, @Deprecated in Kotlin/Java, @available(*, deprecated:) in Swift, [Obsolete] in .NET, JSDoc @deprecated in TypeScript, and so on, driven by the existing IDL deprecated: field).
2. The deprecated feature continues to work for at least one full minor version.
3. Removal lands in the next major release with a migration note in CHANGELOG.md.

In short: nothing disappears in a patch release, nothing disappears without at least one minor release of warnings, and every removal ships with a documented replacement.

IR schema version policy

The IR schema version is independent of the workspace version, but it is tied to weaveffi-ir’s minor version: each weaveffi-ir minor bump corresponds to at most one schema version bump. CURRENT_SCHEMA_VERSION in crates/weaveffi-ir/src/ir.rs is the source of truth; the current schema version is 0.5.0.

Pre-1.0, only the current schema version is accepted (SUPPORTED_VERSIONS contains exactly CURRENT_SCHEMA_VERSION), so a document declaring any earlier revision is rejected with an actionable error. When a schema bump lands, update the version field in your IDL and adjust the document to the new schema by hand; the changes are documented in CHANGELOG.md with a “Migration” section. Post-1.0, schema bumps will ship with an automated migration tool and a widened SUPPORTED_VERSIONS window.

Generated-code stability (determinism)

Regenerating with the same WeaveFFI version on the same IDL produces byte-identical output.

This is enforced by the determinism tests: every generator’s output is hashed and re-hashed on the kitchen-sink fixture, and any deviation fails CI. Internally, every HashMap iteration that contributes to generated output has been replaced by BTreeMap or an explicit sort. The serde_json-backed cache key uses a canonical key ordering.

Practical consequences:

• Vendoring the generated bindings/ directory in your repository is safe. A reviewer will only see a diff when the IDL or the generator itself changes.
• weaveffi diff --check (see below) is a reliable CI gate.
• Cross-platform regeneration (Linux vs macOS vs Windows) produces the same bytes for the same WeaveFFI version.

If you ever observe non-determinism, please file an issue with the IDL that triggers it. It’s a bug, not a quirk.

The weaveffi diff --check workflow for downstream CI

The single recommended way to guard a downstream repository against “forgot to regenerate” mistakes is weaveffi diff --check:

weaveffi diff path/to/api.yml --out generated/ --check

diff --check regenerates into a temporary directory, compares against --out, and exits:

• 0 when the on-disk output matches what regeneration would produce,
• 2 when at least one file differs (modified content),
• 3 when files are missing or extra (a target was added/removed).

It prints only the summary + N added, - M removed, ~ K modified, suitable for CI logs without flooding the output.

A typical GitHub Actions step:

- name: Verify generated bindings are up to date
  run: |
    cargo install weaveffi-cli --locked --version =0.3.0
    weaveffi diff idl/api.yml --out generated/ --check

Combine it with weaveffi format --check idl/api.yml (canonical IDL) and weaveffi validate idl/api.yml (schema correctness) for a complete CI guard.

See also

• IDL Schema: the type system the schema version governs.
• Getting Started: installation and the basic workflow diff --check plugs into.

Performance

WeaveFFI is designed to disappear in the build. Code generation should finish in under a second on every project from the calculator sample to a fully featured kitchen-sink API, leaving a budget for the surrounding build steps.

This page lists the explicit performance targets the project commits to, the methodology used to measure them, the latest measurements taken on commodity hardware, and the locations of the workflow artifacts that the CI system uploads on every push to main.

Targets

The values below are hard targets enforced via the criterion benchmarks in crates/weaveffi-core/benches/codegen_bench.rs and crates/weaveffi-cli/benches/generate_bench.rs. The first two benchmarks measure single-purpose pipeline stages; the latter two measure the full code-generation surface (all 11 generators) end-to-end.

A regression that pushes any of these benchmarks past its target is a release blocker; the CI workflow uploads benchmark output as an artifact on every push to main so reviewers can spot drift before it ships.

Methodology

The benchmarks use criterion.rs in its default sampling mode (100 samples, ~3 s measurement, statistical analysis). Each benchmark builds a fresh temporary directory per iteration so I/O is included in the measurement; this matches what users observe at the command line.

cargo bench --workspace -- --noplot

Profile a generator end-to-end with a flame graph:

cargo flamegraph -p weaveffi-cli --bench generate_bench

On macOS, the equivalent invocation uses cargo-instruments:

cargo instruments -t Time -p weaveffi-cli --bench generate_bench

Reference hardware for the numbers below: Apple M-series laptop, release build (--release, lto = false), no other heavy processes running.

Latest measurements

These numbers were captured on the most recent baseline run after the hot-path optimizations described below. Each row is the criterion median; the parentheses show the headroom relative to the documented target.

The *_large_api benchmarks operate on a synthetic 10-module × 50-function API (500 functions total) that does not have a documented ceiling; they exist as a regression signal for the per-function cost of each generator.

Optimized hot paths

Profiling revealed three meaningful hot paths in the code-generation pipeline. Each one was tightened in this iteration; the optimizations delivered the cumulative ~7-10 % wall-clock improvement visible in the table above.

1. Pre-allocate output buffers. Both render_c_header and render_swift_wrapper started from String::new() and let the buffer grow by doubling, copying the entire string on each re-allocation. They now estimate the final output size from the number of modules, functions, structs, and callbacks in the API and pre-allocate accordingly via String::with_capacity.

2. write! instead of push_str(&format!(...)) in the per-function hot loop of render_module_header (C generator) and the function wrappers in the Swift generator. Each replacement eliminates the intermediate String that format! allocates before the result is appended to the output buffer.

3. Drop the Vec<String> + join(", ") pattern when emitting parameter signatures. The Swift generator now writes the comma-separated parameter list directly into the output buffer via the write_swift_params_sig helper; the C generator routes through a write_params_into helper that takes string slices, eliminating the per-parameter allocation loop and the joined intermediate.

These three categories are the ones explicitly called out as candidates in the original performance plan, in order of impact.

Things explicitly not optimized

• serde_yaml parsing is the dominant cost of the weaveffi generate happy path on disk because parsing happens before the benchmarks above run. The kitchen-sink fixture takes ~50 µs to parse on reference hardware, well below the validate/hash targets, and serde_yaml does not expose a streaming API that is materially faster for our schemas. We accept it as the dominant CLI startup cost and document it here.

CI artifacts

The bench.yml workflow runs cargo bench on every push to main and uploads the captured criterion output as a bench-results artifact (retained for 90 days). To inspect the most recent run:

1. Open the bench workflow runs on GitHub.
2. Pick the latest run that succeeded.
3. Download the bench-results artifact and extract bench.txt; it contains the full criterion output (medians, ranges, outlier counts) for the entire workspace.

The workflow does not gate merges on absolute thresholds today; instead it serves as the authoritative trail when a PR claims to improve or preserve benchmark numbers.

Roadmap

This page is a placeholder. WeaveFFI is in active 0.x development, and we’ll use this page to share a public roadmap once there’s a concrete plan worth publishing.

For now, the CHANGELOG is the source of truth for what has shipped, and Stability and Versioning explains how releases and schema versioning work.

Samples

This repo includes sample projects under samples/ that showcase end-to-end usage of WeaveFFI. Every producer is written as safe Rust and annotated with the #[weaveffi::module] family of attributes, so the macro generates its C ABI (see The Rust Producer Macro). The simpler producers (calculator, contacts, and inventory) generate bindings straight from their annotated source. The advanced samples (async-demo, events, kvstore, shapes) are macro-annotated too, and they keep a committed YAML IDL as the generation source of truth because their surfaces carry metadata the extractor does not yet recover from source, such as package and per-generator configuration and standalone since tags.

Kvstore (kitchen-sink reference)

Path: samples/kvstore

A production-quality, in-memory key/value store that exercises every IDL feature WeaveFFI supports in a single sample. Use this as the canonical reference when learning the IDL surface or when you need to copy/paste a real-world pattern for a new generator.

What it demonstrates:

• A first-class interface (Store) with a throwing constructor (open), instance methods, a static (default_capacity), and implicit destroy
• A struct (Entry) with every primitive: i64, string, bytes, optional field (expires_at: i64?), list field (tags: [string]), and map field (metadata: {string:string}), plus per-field doc strings and builder: true
• A documented enum (EntryKind with Volatile, Persistent, Encrypted)
• A documented error domain (KvError with KeyNotFound, Expired, StoreFull, IoError) and opt-in throws: true on the fallible methods
• A module-level callback (OnEvict) and listener (eviction_listener)
• A streaming iterator return (list_keys -> iter<string>) with prefix filter
• A cancellable async method (compact, async: true, cancellable: true) that respects a weaveffi_cancel_token while reclaiming bytes on a worker thread
• A deprecated method (legacy_put)
• A nested sub-module (kv.stats) with its own struct (Stats) and a function that takes a cross-module Store parameter
• Inline generators: overrides for swift.module_name, cpp.namespace, dotnet.namespace, dart.package_name, go.module_path, and ruby.module_name

Build, generate bindings, and run the C ABI tests:

cargo build -p kvstore
cargo test -p kvstore
weaveffi generate samples/kvstore/kvstore.yml -o generated

The conformance/ harness ships a kvstore consumer for every language that opens a Store, round-trips entries, drives the async compact, and asserts the typed KvError surface; see conformance/run.sh.

Shapes (rich enums + numerics)

Path: samples/shapes

The reference sample for rich (algebraic) enums (sum types whose variants carry associated data) and the expanded numeric primitives. Use it when learning how a tagged union crosses the C ABI as an opaque object and how each backend wraps it.

What it demonstrates:

• A rich enum (Shape) with a data-less variant (Empty) and three payload variants (Circle { radius: f64 }, Rectangle { width: f32, height: f32 }, and Labeled { label: string, count: u8 }) lowered to an opaque object with per-variant constructors, a tag reader, per-variant field getters, and a destructor
• A plain C-style enum (Channel) alongside the rich enum, showing both enum flavors in one module
• The new numeric primitives (f32, u8, u64) as variant fields, parameters, and return types
• Functions that take and return a rich enum (describe, scale) and a list-of-bytes reduction (sum_bytes(values: [u8]) -> u64)

Build, generate bindings, and run the C ABI tests:

cargo build -p shapes
cargo test -p shapes
weaveffi generate samples/shapes/shapes.yml -o generated

The conformance/ harness ships a shapes consumer for every language that constructs each variant, reads the tag and fields back, and round-trips through describe/scale; see conformance/run.sh.

Calculator

Path: samples/calculator

The simplest sample: a single #[weaveffi::module] with four functions that exercise primitive types (i32) and string passing. Good starting point for understanding the basic C ABI contract and the macro workflow.

What it demonstrates:

• Scalar parameters and return values (i32)
• String parameters and return values (C string ownership)
• The smallest possible typed error surface: a #[weaveffi::error] enum (CalcError) and one throwing function (div returns Result<i32, CalcError>)
• A producer written entirely as safe Rust (no hand-written FFI glue)

Build and generate bindings (from the annotated source):

cargo build -p calculator
weaveffi generate samples/calculator/src/lib.rs -o generated

This produces target-specific output under generated/ (C headers, Swift wrapper, Android skeleton, Node addon sources, Wasm loader). The Calculator tutorial walks through running C, Node, and Swift consumers against it.

Contacts

Path: samples/contacts

A CRUD-style sample with a single module, written as safe Rust and annotated with #[weaveffi::module]. It exercises richer type-system features than the calculator while writing no unsafe glue.

What it demonstrates:

• A #[weaveffi::enumeration] (ContactType with Personal, Work, Other)
• A #[weaveffi::record] (Contact) with generated create/destroy/getters
• Optional fields (Option<String> for the email)
• A #[weaveffi::interface] (ContactBook) with a new constructor, instance methods, and implicit destroy
• List return types (Vec<Contact> from ContactBook::list)
• A #[weaveffi::error] domain (ContactsError) surfaced by the throwing methods via Result<Contact, ContactsError>

Build and generate bindings (from the annotated source):

cargo build -p contacts
weaveffi generate samples/contacts/src/lib.rs -o generated

Inventory

Path: samples/inventory

A richer, multi-module sample with products and orders modules, written as safe Rust with two #[weaveffi::module] blocks. It exercises cross-module references and record lists across the macro.

What it demonstrates:

• Two annotated modules in one crate, each with its own error domain (ProductsError, OrdersError)
• A #[weaveffi::interface] (Catalog) owning its product list, alongside free functions in the orders module
• A #[weaveffi::enumeration] (Category) and #[weaveffi::record]s (Product, Order, OrderItem)
• Optional and list fields (Option<String>, Vec<String> tags)
• A record-list return (Catalog::search -> Vec<Product>) and a record-list parameter (create_order(items: Vec<OrderItem>))
• A cross-module record parameter (orders::add_product_to_order takes a products::Product)

Build and generate bindings (from the annotated source):

cargo build -p inventory
weaveffi generate samples/inventory/src/lib.rs -o generated

Async Demo

Path: samples/async-demo

Demonstrates the async function pattern using callback-based invocation. Async functions in the YAML definition get an _async suffix at the C ABI layer and accept a callback + context pointer instead of returning directly.

What it demonstrates:

• Async function declarations (async: true in the YAML)
• Callback-based C ABI pattern (weaveffi_tasks_run_task_async)
• Callback type definitions (weaveffi_tasks_run_task_callback)
• Batch async operations (run_batch processes a list of names sequentially)
• Synchronous fallback functions (cancel_task is non-async in the same module)
• Struct return types through callbacks (TaskResult delivered via callback)

Build and run tests:

cargo build -p async-demo
cargo test -p async-demo

Note: Async functions are fully supported by the validator. This sample focuses on the C ABI callback pattern; see the Async Functions guide for the per-target async/await story.

Events

Path: samples/events

Demonstrates callbacks, event listeners, and iterator-based return types.

What it demonstrates:

• Callback type definitions (OnMessage callback)
• Listener registration and unregistration (message_listener)
• Event-driven patterns (sending a message triggers the registered callback)
• Iterator return types (iter<string> in the YAML)
• Iterator lifecycle (get_messages returns a GetMessagesIterator, advanced with _next, freed with _destroy)

Build and run tests:

cargo build -p events
cargo test -p events

Node Addon

Path: samples/node-addon

An N-API addon crate that loads the calculator’s C ABI shared library at runtime via libloading and exposes the functions as JavaScript-friendly #[napi] exports. It shows the hand-rolled alternative to the generated weaveffi_addon.c, which the Node generator now emits for you.

What it demonstrates:

• Dynamic loading of a weaveffi_* shared library from JavaScript
• Mapping C ABI error structs to N-API errors
• String ownership across the FFI boundary (CString in, CStr out, free)

Build (requires the calculator library first):

cargo build -p calculator
cargo build -p weaveffi-node-addon

End-to-end testing

The conformance/ directory is the end-to-end regression oracle for the code generators. Every consumer under conformance/<language>/ binds through the generated wrappers (not the raw C ABI) and asserts concrete results against the contacts, events, kvstore, and shapes samples. The conformance/run.sh harness builds each producer cdylib, runs weaveffi generate for it, then compiles and runs every per-(language, sample) consumer:

bash conformance/run.sh

It prints [OK] {target} for each consumer that succeeds and reports a pass/fail summary at the end. Use ONLY=c-contacts,cpp-contacts to run a subset, or SKIP=go-contacts to omit individual targets. Missing toolchains cause the affected target to fail; skip those explicitly. See the comment block at the top of conformance/run.sh for the per-target prerequisites.

Reference

IDL Type Reference

WeaveFFI consumes a declarative IDL (Interface Definition Language) that describes modules, types, and functions. YAML, JSON, and TOML are all supported; this reference uses YAML throughout.

Editor autocomplete (JSON Schema)

WeaveFFI ships a JSON Schema for the IDL. To get autocomplete and validation in editors that support the YAML Language Server (VS Code, Neovim, Helix, …), add the following header comment to the top of your YAML file:

# yaml-language-server: $schema=./weaveffi.schema.json

The schema is generated by weaveffi schema --format json-schema and a copy is checked in at weaveffi.schema.json in the repository root.

Top-level structure

The shape of an IDL document, with placeholder ellipses for nested arrays and objects:

# yaml-language-server: $schema=./weaveffi.schema.json
version: "0.5.0"
package:
  name: my_app
  version: "1.0.0"
modules:
  - name: my_module
    structs: [...]
    enums: [...]
    interfaces: [...]
    functions: [...]
    callbacks: [...]
    listeners: [...]
    errors: { ... }
    modules: [...]
generators:
  swift:
    module_name: MyApp

A complete, validating example lives at the bottom of this page in the Complete example section.

Module

Function

Param

Package metadata

The optional top-level package block is the single source of truth for the publishable identity stamped into every generated ecosystem manifest: package.json (Node/Wasm), pyproject.toml/setup.py (Python), *.gemspec (Ruby), *.csproj/*.nuspec (.NET), pubspec.yaml (Dart), Package.swift (Swift), go.mod (Go), settings.gradle (Android), and CMakeLists.txt (C++). Declaring it once keeps the name, version, and metadata consistent across all eleven targets instead of every generator hardcoding weaveffi / 0.1.0.

Package schema

Name and version resolution

Each target resolves its package name with the following precedence (first non-empty wins):

1. an explicit per-target override (e.g. python.package_name, dart.package_name, ruby.gem_name),
2. package.name,
3. the IDL file stem (e.g. kvstore.yml → kvstore),
4. the built-in default weaveffi.

The version resolves from package.version, falling back to 0.1.0. Names are normalized per ecosystem, e.g. a Python import package or Ruby require path lowercases and replaces non-alphanumerics with _ (my-kv.store → my_kv_store), while the published distribution name keeps the original spelling.

Code-level identity that has no manifest of its own still follows the package where it is unambiguous: the Swift module name defaults to the PascalCased package.name (async-demo → AsyncDemo). The stable C ABI symbol prefix is not affected: it stays weaveffi (or your global c_prefix) so the generated bindings keep calling the symbols the producer exports.

Package example

version: "0.5.0"
package:
  name: kvstore
  version: "1.0.0"
  description: An embedded key-value store API.
  license: MIT
  authors:
    - WeaveFoundry <hello@weavefoundry.dev>
  homepage: https://github.com/weavefoundry/weaveffi
  repository: https://github.com/weavefoundry/weaveffi
modules:
  - name: kv
    functions:
      - name: count
        params: []
        return: i64

Primitive types

The following primitive types are supported. All primitives are valid in both parameters and return types.

Note on JavaScript/Wasm: 64-bit integers (i64, u64) surface as BigInt in the Node and WebAssembly backends; all narrower integers and the floats surface as number.

Primitive examples

version: "0.5.0"
modules:
  - name: primitives
    structs:
      - name: Session
        fields:
          - { name: id, type: i64 }
    functions:
      - name: add
        params:
          - { name: a, type: i32 }
          - { name: b, type: i32 }
        return: i32

      - name: scale
        params:
          - { name: value, type: f64 }
          - { name: factor, type: f64 }
        return: f64

      - name: count
        params:
          - { name: limit, type: u32 }
        return: u32

      - name: timestamp
        params: []
        return: i64

      - name: is_valid
        params:
          - { name: token, type: string }
        return: bool

      - name: echo
        params:
          - { name: message, type: string }
        return: string

      - name: compress
        params:
          - { name: data, type: bytes }
        return: bytes

      - name: open_resource
        params:
          - { name: path, type: string }
        return: handle

      - name: close_resource
        params:
          - { name: id, type: handle }

      - name: open_session
        params:
          - { name: config, type: string }
        return: "handle<Session>"
        doc: "Returns a typed handle scoped to Session"

      - name: write_fast
        params:
          - { name: data, type: "&str" }
        doc: "Borrowed string: no copy at the FFI boundary"

      - name: send_raw
        params:
          - { name: payload, type: "&[u8]" }
        doc: "Borrowed byte slice: no copy at the FFI boundary"

Typed handles

handle<T> is a typed variant of handle that associates the opaque identifier with a named type T. This gives generators type-safety information, for example, generating a distinct wrapper class per handle type. T must be a struct defined in the same module so the generator knows how to spell the handle’s type. At the C ABI level, handle<T> is still a uint64_t.

version: "0.5.0"
modules:
  - name: sessions
    structs:
      - name: Session
        fields:
          - { name: id, type: i64 }
    functions:
      - name: create_session
        params: []
        return: "handle<Session>"

      - name: close_session
        params:
          - { name: session, type: "handle<Session>" }

Borrowed types

&str and &[u8] are zero-copy borrowed variants of string and bytes. They indicate that the callee only reads the data for the duration of the call and does not take ownership. This avoids an allocation and copy at the FFI boundary.

YAML note: Quote borrowed types like "&str" and "&[u8]" because YAML interprets & as an anchor indicator.

Struct definitions

Structs define composite types with named, typed fields. Define structs under the structs key of a module, then reference them by name in function signatures and other type positions.

Struct schema

When builder: true, generators emit a builder class with with_* setter methods and a build() method, enabling incremental construction of complex structs.

Each field:

Struct example

version: "0.5.0"
modules:
  - name: geometry
    structs:
      - name: Point
        doc: "A 2D point in space"
        fields:
          - name: x
            type: f64
            doc: "X coordinate"
          - name: "y"
            type: f64
            doc: "Y coordinate"

      - name: Rect
        fields:
          - name: origin
            type: Point
          - name: width
            type: f64
          - name: height
            type: f64

      - name: Config
        builder: true
        fields:
          - name: timeout
            type: i32
            default: 30
          - name: retries
            type: i32
            default: 3
          - name: label
            type: "string?"

    functions:
      - name: distance
        params:
          - { name: a, type: Point }
          - { name: b, type: Point }
        return: f64

      - name: bounding_box
        params:
          - { name: points, type: "[Point]" }
        return: Rect

Struct fields may reference other structs, enums, optionals, lists, or maps. Interface references, borrowed types, and iterators are not valid field types (see Type compatibility).

Enum definitions

Enums define a fixed set of named integer variants. Each variant has an explicit value (i32). Define enums under the enums key.

Enum schema

Each variant:

Enum example

version: "0.5.0"
modules:
  - name: contacts
    enums:
      - name: ContactType
        doc: "Category of contact"
        variants:
          - name: Personal
            value: 0
            doc: "Friends and family"
          - name: Work
            value: 1
            doc: "Professional contacts"
          - name: Other
            value: 2

    functions:
      - name: count_by_type
        params:
          - { name: contact_type, type: ContactType }
        return: i32

Variant values must be unique within an enum, and variant names must be unique within an enum.

Rich (algebraic) enums: sum types

When one or more variants declare fields, the enum becomes a rich enum: an algebraic sum type whose variants carry associated data (like a Rust enum or a Swift enum with associated values). A unit variant (no fields) and a data variant may coexist in the same enum.

version: "0.5.0"
modules:
  - name: shapes
    enums:
      - name: Shape
        doc: "An algebraic shape"
        variants:
          - name: Empty
            value: 0
          - name: Circle
            value: 1
            fields:
              - { name: radius, type: f64 }
          - name: Rectangle
            value: 2
            fields:
              - { name: width, type: f32 }
              - { name: height, type: f32 }
    functions:
      - name: area
        params:
          - { name: shape, type: Shape }
        return: f64

Unlike a plain C-style enum (which crosses the ABI by value as an integer), a rich enum crosses as an opaque object pointer, exactly like a struct. The C ABI gains a tag reader, a per-variant constructor and field getters, and a destructor; each backend wraps these into an idiomatic owned type:

A variant fields entry uses the same shape as a struct field (name, type, doc), but obeys the positional rules of a return-like slot: no borrowed (&str/&[u8]) types and no iterators. Field names must be unique within a variant.

Interfaces

An interface is a first-class object type: a stateful resource with identity and behavior, declared under the interfaces key of a module. Where a struct models a plain data record with fields, an interface models something you hold and operate on: a store, a session, a connection. The object lives behind the FFI boundary and crosses it as an opaque reference; consumers see a real class (or the target’s closest analogue) whose constructors, methods, and statics call back into the producer.

Interface schema

An interface must declare at least one member, and constructor, method, and static names share one namespace per interface (no duplicates across the three lists).

Each constructor:

A constructor implicitly returns a new instance of its interface, so it declares no return field, and it may not be async (expose an async static factory returning the interface instead). A constructor named new becomes the canonical constructor where the target language has one (Swift init, Python __init__); every other constructor becomes a static factory method.

Methods and statics use the full Function schema, including throws, async, cancellable, deprecated, and since. A method receives the instance implicitly; it does not declare a self parameter. A static takes no instance at all.

Lifecycle

Every interface receives an implicit destructor: the C ABI gains a *_destroy symbol, and each generated wrapper releases the underlying object through its language’s natural disposal hook (RAII destructors, deinit, __del__, IDisposable, finalizers, close()). You never declare destroy in the IDL.

Ownership follows the reference direction: an interface passed as a parameter is borrowed for the duration of the call, while an interface returned from a call is a new owned reference the caller (or its wrapper) must eventually release.

Where interface types may appear

An interface name is a valid TypeRef in function and method parameters, in return types, and in optionals of those (Store, Store?). It is not valid as a struct field, a collection element ([Store]), a map key or value, or a callback parameter; the validator rejects those positions.

Interface example

A trimmed version of the kvstore sample’s Store interface:

version: "0.5.0"
modules:
  - name: kv
    errors:
      name: KvError
      codes:
        - { name: KeyNotFound, code: 1001, message: "key not found" }
        - { name: IoError, code: 1004, message: "I/O failure" }
    interfaces:
      - name: Store
        doc: An embedded key-value store owning its entries
        constructors:
          - name: open
            doc: Open (or create) a store backed by the given filesystem path
            params:
              - { name: path, type: string }
            throws: true
        methods:
          - name: get
            doc: Look up a value by key
            params:
              - { name: key, type: string }
            return: bytes
            throws: true
          - name: delete
            doc: Remove the entry for the given key, returning true if it existed
            params:
              - { name: key, type: string }
            return: bool
            throws: true
          - name: count
            doc: Return the number of live entries in the store
            params: []
            return: i64
        statics:
          - name: default_capacity
            doc: The largest number of live entries one store will hold
            params: []
            return: i64

C ABI lowering

An interface lowers to an opaque struct tag plus one C symbol per member. Constructors return an owned pointer; methods take a leading const {tag}* self argument before their declared parameters; statics take no self; and the implicit destructor releases the object:

typedef struct weaveffi_kv_Store weaveffi_kv_Store;

/* Constructor: returns a new owned instance. */
weaveffi_kv_Store* weaveffi_kv_Store_open(const char* path, weaveffi_error* out_err);

/* Methods: an implicit leading self slot. */
bool weaveffi_kv_Store_delete(const weaveffi_kv_Store* self, const char* key,
                              weaveffi_error* out_err);
int64_t weaveffi_kv_Store_count(const weaveffi_kv_Store* self, weaveffi_error* out_err);

/* Statics: no self slot. */
int64_t weaveffi_kv_Store_default_capacity(weaveffi_error* out_err);

/* Implicit destructor: releases the object. */
void weaveffi_kv_Store_destroy(weaveffi_kv_Store* self);

Async and iterator-returning members follow the same shapes as free functions (the async launcher and the iterator handle simply carry the self slot). Free functions and interface members share the module’s C symbol namespace, so a free function named Store_get would collide with a get method on an interface Store; the validator rejects the collision.

Optional types

Append ? to any type to make it optional (nullable). When a value is absent, the default is null.

Optional example

version: "0.5.0"
modules:
  - name: contacts
    structs:
      - name: Contact
        fields:
          - { name: id, type: i64 }
          - { name: name, type: string }
          - { name: email, type: "string?" }
          - { name: nickname, type: "string?" }
    functions:
      - name: find_contact
        params:
          - { name: id, type: i64 }
        return: "Contact?"
        doc: "Returns null if no contact exists with the given id"

      - name: update_email
        params:
          - { name: id, type: i64 }
          - { name: email, type: "string?" }

YAML note: Quote optional types like "string?" and "Contact?" to prevent the YAML parser from treating ? as special syntax.

List types

Wrap a type in [T] brackets to declare a list (variable-length sequence).

List example

version: "0.5.0"
modules:
  - name: lists
    structs:
      - name: Contact
        fields:
          - { name: id, type: i64 }
    functions:
      - name: sum
        params:
          - { name: values, type: "[i32]" }
        return: i32

      - name: list_contacts
        params: []
        return: "[Contact]"

      - name: batch_delete
        params:
          - { name: ids, type: "[i64]" }
        return: i32

YAML note: Quote list types like "[i32]" and "[Contact]" because YAML interprets bare [...] as an inline array.

Map types

Wrap a key-value pair in {K:V} braces to declare a map (dictionary / associative array). Keys must be primitive types or enums; structs, lists, and maps are not valid key types. Values may be any valid TypeRef.

Map example

version: "0.5.0"
modules:
  - name: maps
    structs:
      - name: Contact
        fields:
          - { name: id, type: i64 }
          - { name: name, type: string }
          - { name: email, type: "string?" }
    functions:
      - name: update_scores
        params:
          - { name: scores, type: "{string:i32}" }
        return: bool
        doc: "Update player scores by name"

      - name: get_contacts
        params: []
        return: "{string:Contact}"
        doc: "Returns a map of name to Contact"

      - name: merge_tags
        params:
          - { name: current, type: "{string:string}" }
          - { name: additions, type: "{string:string}" }
        return: "{string:string}"

YAML note: Quote map types like "{string:i32}" because YAML interprets bare {...} as an inline mapping.

C ABI convention

Maps are passed across the FFI boundary as parallel arrays of keys and values, plus a shared length. A map parameter {K:V} named m expands to three C parameters:

const K* m_keys, const V* m_values, size_t m_len

A map return value expands to out-parameters:

K* out_keys, V* out_values, size_t* out_len

For example, a function update_scores(scores: {string:i32}) generates:

void weaveffi_mymod_update_scores(
    const char* const* scores_keys,
    const int32_t* scores_values,
    size_t scores_len,
    weaveffi_error* out_err
);

Key type restrictions

Only primitive types (i32, u32, i64, f64, bool, string, bytes, handle) and enum types are valid map keys. The validator rejects structs, lists, and maps as key types.

Nested types

Optional and list modifiers compose freely:

Nested type example

version: "0.5.0"
modules:
  - name: nested
    structs:
      - name: Contact
        fields:
          - { name: id, type: i64 }
    functions:
      - name: search
        params:
          - { name: query, type: string }
        return: "[Contact?]"
        doc: "Returns a list where some entries may be null (redacted)"

      - name: get_scores
        params:
          - { name: user_id, type: i64 }
        return: "[i32]?"
        doc: "Returns null if user has no scores, otherwise a list"

      - name: bulk_update
        params:
          - { name: emails, type: "[string?]" }
        return: i32

The parser evaluates type syntax outside-in: [Contact?] is parsed as List(Optional(Contact)), while [Contact]? is parsed as Optional(List(Contact)).

Iterator types

Wrap a type in iter<T> to declare a lazy iterator over values of type T. Unlike [T] (which materializes the full list), iterators yield elements one at a time and are suitable for large or streaming result sets.

Iterator example

version: "0.5.0"
modules:
  - name: streaming
    structs:
      - name: Contact
        fields:
          - { name: id, type: i64 }
    functions:
      - name: scan_entries
        params:
          - { name: prefix, type: string }
        return: "iter<Contact>"
        doc: "Lazily iterates over matching contacts"

Laziness is part of the binding contract, not just the C ABI shape. Every generated wrapper surfaces iter<T> as its language’s native lazy iteration idiom: an iter.Seq in Go (iter.Seq2 when the function throws), a Sequence in Swift, an input-iterator range in C++, an iterator in Python, an Enumerator in Ruby, an IEnumerable<T> in C#, an Iterable<T> in Dart, an iterable in JavaScript, and an Iterator<T> with close() in Kotlin. The wrapper issues one producer next call per consumer step; no target drains the sequence into a hidden list. The underlying iterator handle is destroyed exactly once, eagerly on exhaustion or from the wrapper’s disposal idiom when iteration is abandoned early, and errors from the launch and from each next follow the function’s error strategy (see the Error Handling guide). The full pull contract is stated in weaveffi_core::plan::IteratorProtocol; element ownership is covered in the Memory Ownership guide.

Iterators are only valid as return types. The validator rejects iterators in parameter positions.

Callbacks

Callbacks define function signatures that can be passed from the host language into Rust. They enable event-driven patterns where Rust code invokes a caller-provided function.

Callback schema

Callback example

version: "0.5.0"
modules:
  - name: events
    functions: []
    callbacks:
      - name: on_data
        params:
          - { name: payload, type: string }
        doc: "Fired when data arrives"

      - name: on_error
        params:
          - { name: code, type: i32 }
          - { name: message, type: string }

Callback names are not a valid TypeRef. Callbacks are wired up at the module level: declare them under callbacks:, reference them from a listeners: entry via event_callback, and emit asynchronous results from functions marked async: true.

Listeners

Listeners provide a higher-level abstraction over callbacks for event subscription patterns. A listener combines an event callback with subscribe/unsubscribe lifecycle management.

Listener schema

Listener example

version: "0.5.0"
modules:
  - name: events
    functions: []
    callbacks:
      - name: on_data
        params:
          - { name: payload, type: string }

    listeners:
      - name: data_stream
        event_callback: on_data
        doc: "Subscribe to data events"

The event_callback must reference a callback defined in the same module.

Nested modules

Modules can contain sub-modules, enabling hierarchical organization of large APIs. Nested modules share the same validation rules as top-level modules.

Nested module example

version: "0.5.0"
modules:
  - name: app
    functions:
      - name: init
        params: []

    modules:
      - name: auth
        structs:
          - name: Session
            fields:
              - { name: id, type: i64 }
        functions:
          - name: login
            params:
              - { name: username, type: string }
              - { name: password, type: string }
            return: "handle<Session>"

      - name: data
        structs:
          - name: Record
            fields:
              - { name: id, type: i64 }
              - { name: value, type: string }

        functions:
          - name: get_record
            params:
              - { name: id, type: i64 }
            return: Record

C ABI symbols for nested modules use underscores to join the path: weaveffi_app_auth_login, weaveffi_app_data_get_record.

Cross-module type references

Struct, enum, interface, and error domain names are unique across the whole API (the validator rejects two types sharing a bare name, wherever they are declared). A bare type name therefore resolves unambiguously from any module: reference the type by name and the toolchain qualifies the reference to its owning module internally.

For example, a nested stats module can take the parent kv module’s Store interface as a parameter:

version: "0.5.0"
modules:
  - name: kv
    errors:
      name: KvError
      codes:
        - { name: IoError, code: 1004, message: "I/O failure" }
    interfaces:
      - name: Store
        constructors:
          - name: open
            params:
              - { name: path, type: string }
            throws: true
        methods:
          - name: count
            params: []
            return: i64
    modules:
      - name: stats
        structs:
          - name: Stats
            fields:
              - { name: total_entries, type: i64 }
        functions:
          - name: get_stats
            doc: Snapshot the current store statistics
            params:
              - { name: store, type: Store }
            return: Stats
            throws: true

The generated bindings spell a cross-module reference with the owning module’s qualification where the target needs one.

Async and lifecycle annotations

Async functions

Functions can be marked as asynchronous. See the Async Functions guide for detailed per-target behaviour.

version: "0.5.0"
modules:
  - name: net
    errors:
      name: NetError
      codes:
        - { name: Unreachable, code: 1, message: "host unreachable" }
    functions:
      - name: fetch_data
        params:
          - { name: url, type: string }
        return: string
        async: true
        throws: true

      - name: upload_file
        params:
          - { name: path, type: string }
        return: bool
        async: true
        cancellable: true

async composes with throws: an async function that also declares throws: true delivers its failure as the module’s typed domain error through the target’s async idiom (an async throws function in Swift, a rejected promise carrying the typed error in JavaScript, and so on). An async function without throws gets a plain async shape, and a failure can only be a producer bug.

Async void functions (no return type) emit a validator warning since they are unusual. An async function cannot return an iterator (iter<T>); return a list instead or make the function synchronous.

Deprecated functions

Mark a function as deprecated with a migration message:

version: "0.5.0"
modules:
  - name: legacy
    functions:
      - name: add_old
        params:
          - { name: a, type: i32 }
          - { name: b, type: i32 }
        return: i32
        deprecated: "Use add_v2 instead"
        since: "0.1.0"

Generators propagate the deprecation message to the target language (e.g. @available(*, deprecated) in Swift, @Deprecated in Kotlin, warn in Ruby).

Mutable parameters

Mark a parameter as mutable when the callee may modify it in-place:

version: "0.5.0"
modules:
  - name: buffers
    functions:
      - name: fill_buffer
        params:
          - { name: buf, type: bytes, mutable: true }

This affects the C ABI signature (non-const pointer) and may influence generated wrapper code in target languages.

Generators section

The top-level generators key provides per-generator configuration directly in the IDL file. This is an alternative to using a separate TOML configuration file with --config.

version: "0.5.0"
modules:
  - name: math
    functions:
      - name: add
        params:
          - { name: a, type: i32 }
          - { name: b, type: i32 }
        return: i32

generators:
  swift:
    module_name: MyMathLib
  android:
    package: com.example.math
  ruby:
    module_name: MathBindings
    gem_name: math_bindings
  go:
    module_path: github.com/myorg/mathlib

Each key under generators is the target name (matching the --target flag). The value is a target-specific configuration object. See the Generator Configuration guide for the full list of options.

Type compatibility

All types are valid in both parameter and return positions unless noted.

Complete example

A full IDL combining structs, enums, optionals, lists, an interface, and a typed error domain (a trimmed version of the contacts sample):

version: "0.5.0"
modules:
  - name: contacts
    enums:
      - name: ContactType
        variants:
          - { name: Personal, value: 0 }
          - { name: Work, value: 1 }
          - { name: Other, value: 2 }

    structs:
      - name: Contact
        doc: "A contact record"
        fields:
          - { name: id, type: i64 }
          - { name: first_name, type: string }
          - { name: last_name, type: string }
          - { name: email, type: "string?" }
          - { name: contact_type, type: ContactType }

    errors:
      name: ContactsError
      codes:
        - { name: InvalidName, code: 1, message: "name must not be empty" }
        - { name: NotFound, code: 2, message: "contact not found" }

    interfaces:
      - name: ContactBook
        doc: "An in-memory address book owning its contacts"
        constructors:
          - name: new
            params: []
        methods:
          - name: add
            doc: "Add a contact, returning the stored record with its assigned id"
            params:
              - { name: first_name, type: string }
              - { name: last_name, type: string }
              - { name: email, type: "string?" }
              - { name: contact_type, type: ContactType }
            return: Contact
            throws: true

          - name: get
            doc: "Look up a contact by id"
            params:
              - { name: id, type: i64 }
            return: Contact
            throws: true

          - name: list
            params: []
            return: "[Contact]"

          - name: remove
            params:
              - { name: id, type: i64 }
            return: bool

          - name: count
            params: []
            return: i32

Validation rules

• Module, function, parameter, struct, enum, interface, field, and variant names must be valid identifiers (start with a letter or _, contain only alphanumeric characters and _).
• Names must be unique within their scope (no duplicate module names, no duplicate function names within a module, etc.).
• Struct, enum, interface, and error domain names must be unique across the whole API, not just their module: generators emit flat per-language type names, and bare-name references resolve API-wide.
• Reserved keywords are rejected: if, else, for, while, loop, match, type, return, async, await, break, continue, fn, struct, enum, mod, use.
• Structs must have at least one field. Enums must have at least one variant. Interfaces must have at least one constructor, method, or static.
• Enum variant values must be unique within their enum.
• Type references to structs, enums, and interfaces must resolve to a definition somewhere in the API (see Cross-module type references).
• Interface members (constructors, methods, and statics) share one namespace per interface; a constructor may not declare a return type and may not be async.
• Interface types are valid only as parameters, return types, and optionals of those; not as struct fields, collection elements, map keys or values, or callback parameters.
• Free functions and interface members share the module’s C symbol namespace; two declarations lowering to the same symbol are rejected.
• throws: true requires an error domain in scope: on the same module or an ancestor module.
• Error codes must be non-zero (and not -2, which is reserved for producer panics) and unique within their domain. Error code names must be unique within their domain and across every domain in the API.
• Error domain names must not collide with function names in the same module.
• Async functions are allowed. Async void functions (no return type) emit a warning. An async function cannot return an iterator.
• Listener event_callback must reference a callback in the same module.

ABI mapping

• Parameters map to C ABI types; string and bytes are passed as pointer + length.
• Return values are direct scalars except:
  • string: returns const char* allocated by Rust; caller must free via weaveffi_free_string.
  • bytes: returns const uint8_t* and requires an extra size_t* out_len param; caller frees with weaveffi_free_bytes.
• Each function takes a trailing weaveffi_error* out_err for error reporting.

Error domain

A module can declare one error domain: a named set of symbolic error codes its fallible functions report. The domain generates a typed error construct in every target language (an error enum in Swift, an exception class hierarchy in Python, sealed exception subclasses in Kotlin, and so on), so consumers catch and match on the codes you declared rather than on raw integers.

Error domain schema

Each code:

PascalCase code names (KeyNotFound, StoreFull) are the convention: each generator re-cases them into its own idiom.

Opting in with throws

Declaring a domain reserves the codes; a function, method, or constructor joins the typed error path by declaring throws: true:

version: "0.5.0"
modules:
  - name: contacts
    errors:
      name: ContactsError
      codes:
        - { name: InvalidName, code: 1, message: "name must not be empty" }
        - { name: NotFound, code: 2, message: "contact not found" }
    functions:
      - name: get_contact
        params:
          - { name: id, type: i64 }
        return: string
        throws: true

      - name: count_contacts
        params: []
        return: i32

A throwing callable surfaces in each target’s error idiom (throws in Swift, raise in Python, (T, error) in Go, exceptions elsewhere), and the error it delivers is the domain type: the numeric code maps to the matching declared case. A callable without throws (like count_contacts above) has a plain signature at the idiomatic surface; it cannot report a domain error, and a failure there can only be a producer bug, which surfaces as a generic branded error or a trap rather than a typed error. See the Error Handling guide for the full model, including panic behavior.

The domain is in scope for its module and every module nested inside it, so a domain declared on a parent module serves the whole subtree. Declaring throws: true with no domain in scope is a validation error.

Validation

• Codes must be non-zero (0 means success) and must not be -2 (reserved for producer panics).
• Numeric codes must be unique within a domain.
• Code names must be unique within a domain and across every domain in the API: backends with flat namespaces derive one error class or constant per code, so two domains both declaring NotFound would collide. Qualify one of them (e.g. OrderNotFound).
• The domain name must not collide with a function name in the same module, and it shares the API-wide type namespace with struct, enum, and interface names.

Documentation comments

Every IR element accepts an optional doc: field. WeaveFFI propagates that text into the generated bindings using each language’s native doc-comment syntax. Multi-line strings (use YAML’s | block form) are preserved across the boundary; single-line strings collapse to a one-liner where the target syntax allows.

Supported sites:

• Function.doc, Param.doc
• InterfaceDef.doc, plus each of its constructors, methods, and statics (interface members use the function schema, so they carry Function.doc and Param.doc)
• StructDef.doc, StructField.doc
• EnumDef.doc, EnumVariant.doc
• CallbackDef.doc, ListenerDef.doc
• ErrorCode.doc

Per-target syntax:

Example IDL:

version: "0.5.0"
modules:
  - name: docs
    structs:
      - name: Document
        doc: |
          Represents a single document tracked by the system.

          Documents are persisted to disk and exposed via the public API.
        fields:
          - { name: id, type: i64, doc: Stable opaque identifier }
          - { name: title, type: string, doc: Human-readable title }
    functions:
      - name: create_document
        doc: Create a brand new document
        params:
          - { name: title, type: string, doc: Human-readable title }
        return: Document

All eleven generators emit emit_doc calls before every documented declaration; absent or empty doc: fields produce no extra output, so the feature is fully opt-in.

Memory and Error Model

This section summarizes the C ABI conventions exposed by WeaveFFI and how to manage ownership across the FFI boundary.

Error handling

• Every generated C function ends with an out_err parameter of type weaveffi_error*, except _destroy symbols and struct field getters.
• On success: out_err->code == 0 and out_err->message == NULL.
• On failure: out_err->code != 0 and out_err->message points to a Rust-allocated NUL-terminated UTF-8 string that must be cleared.
• On a throws: true function, a non-zero code is one of the module’s declared domain codes (the header emits an enum constant per code, such as weaveffi_kv_KvError_KeyNotFound); on a non-throwing function a non-zero code only ever reports a producer bug such as a panic.

Relevant declarations (from the generated header):

typedef struct weaveffi_error { int32_t code; const char* message; } weaveffi_error;
void weaveffi_error_clear(weaveffi_error* err);

Typical C usage:

struct weaveffi_error err = {0};
int32_t sum = weaveffi_calculator_add(3, 4, &err);
if (err.code) { fprintf(stderr, "%s\n", err.message ? err.message : ""); weaveffi_error_clear(&err); }

Notes:

• The default unspecified error code used by the runtime is -1.
• weaveffi_error_clear is idempotent: it frees the message and nulls the pointer, so clearing an already-cleared struct is safe.
• Module error domains declare their own codes in the IDL; see the Error Handling Guide for the typed error model, including the Throws versus Trap interpretation of non-zero codes.

Strings and bytes

Returned strings are owned by Rust and must be freed by the caller:

const char* s = weaveffi_calculator_echo(msg, &err);
// ... use s ...
weaveffi_free_string(s);

Returned bytes include a separate out-length parameter and must be freed by the caller:

size_t out_len = 0;
const uint8_t* buf = weaveffi_module_fn(/* params ... */, &out_len, &err);
// ... copy data from buf ...
weaveffi_free_bytes((uint8_t*)buf, out_len);

Relevant declarations:

void weaveffi_free_string(const char* ptr);
void weaveffi_free_bytes(uint8_t* ptr, size_t len);

Iterators

An iter<T> return yields an opaque iterator handle. Each _next call writes an element the caller now owns: free string elements with weaveffi_free_string and record or rich-enum elements with their _destroy symbol after copying; by-value elements need nothing. Call the iterator’s _destroy exactly once, whether iteration ran to exhaustion or was abandoned early.

Async completion callbacks

Result buffers passed to an async completion callback (strings, bytes, arrays, boxed optional scalars) are borrowed: the producer owns them, they are valid only for the callback’s duration, and the producer frees them after the callback returns. Copy inside the callback; do not free them. Owned-object results (records, rich enums, interfaces) are the exception: the callback receives ownership and must eventually call _destroy. The err struct is likewise borrowed; copy its code and message inside the callback (clearing it anyway is safe because the clear is idempotent).

Handles and interfaces

Untyped opaque resources are represented as weaveffi_handle_t (64-bit). Treat them as tokens; their lifecycle APIs are defined by your module. Interface objects cross the boundary as typed opaque pointers (weaveffi_kv_Store*): constructors and methods take out_err, methods take the receiver as their leading argument, and the _destroy symbol frees the instance exactly once.

Language wrappers

• Swift: the generated wrapper automatically clears errors and frees returned strings; a throws: true function throws the module’s typed error enum, and a non-throwing function traps on a poisoned error slot.
• Node: the generated weaveffi_addon.c clears errors and frees returned strings; the JS loader prefers the node-gyp output (build/Release/weaveffi.node), honors a WEAVEFFI_ADDON path override, and falls back to a prebuilt index.node next to it.

C-string safety

When constructing C strings, interior NUL bytes are sanitized on the Rust side to maintain valid C semantics.

Naming and Package Conventions

Naming and Package Conventions

This guide standardizes how we name the Weave projects, repositories, packages, modules, and identifiers across ecosystems.

Human-facing brand names (prose)

• Use condensed names in sentences and documentation:
  • WeaveFFI
  • WeaveHeap

Repository and package slugs (URLs and registries)

• Use condensed lowercase slugs for top-level repositories:

  • GitHub: weaveffi, weaveheap (repos: weavefoundry/weaveffi, weavefoundry/weaveheap)

• Use hyphenated slugs for subpackages and components, prefixed with the top-level slug:

  • Examples: weaveffi-core, weaveffi-ir, weaveheap-core

• Planned package names (not yet published):

  • crates.io: weaveffi, weaveffi-core, weaveffi-ir, etc.
  • npm: @weavefoundry/weaveffi
  • PyPI: weaveffi
  • SPM (repo slug): weaveffi

Rationale: condensed top-level slugs unify handles across registries and are ergonomic to type; hyphenated subpackages remain idiomatic and map cleanly to ecosystems that normalize to underscores or CamelCase.

Code identifiers by ecosystem

• Rust

  • Crates: hyphenated subcrates on crates.io (e.g., weaveffi-core), imported as underscores (e.g., weaveffi_core). Top-level crate (if any): weaveffi.
  • Modules/paths: snake_case.
  • Types/traits/enums: CamelCase (e.g., WeaveFFI).

• Swift / Apple platforms

  • Package products and modules: UpperCamelCase (e.g., WeaveFFI, WeaveHeap).
  • Keep repo slug condensed; SPM product name provides the CamelCase surface.

• Java / Kotlin (Android)

  • Group ID / package base: reverse-DNS, all lowercase (e.g., com.weavefoundry.weaveffi).
  • Artifact ID: top-level condensed (e.g., weaveffi); sub-artifacts hyphenated (e.g., weaveffi-android).
  • Class names: UpperCamelCase (e.g., WeaveFFI).

• JavaScript / TypeScript (Node, bundlers)

  • Package name: scope + condensed for top-level, hyphenated for subpackages (e.g., @weavefoundry/weaveffi, @weavefoundry/weaveffi-core).
  • Import alias: flexible, prefer WeaveFFI in examples when using default exports or named namespaces.

• Python

  • PyPI name: top-level condensed (e.g., weaveffi); subpackages hyphenated (e.g., weaveffi-core).
  • Import module: condensed for top-level (e.g., import weaveffi); underscores for hyphenated subpackages (e.g., import weaveffi_core).

• C / CMake

  • Target/library names: snake_case (e.g., weaveffi, weaveffi_core).
  • Header guards / include dirs: snake_case or directory-based (e.g., #include <weaveffi/weaveffi.h>).

Writing guidelines

• In prose, prefer the condensed brand names: “WeaveFFI”, “WeaveHeap”.
• In code snippets, follow the host language conventions above.
• For cross-language docs, show both the repo/package slug and the language-appropriate identifier on first mention, e.g., “Install weaveffi (import as weaveffi, Swift module WeaveFFI). For subpackages, install weaveffi-core (import as weaveffi_core).”

Migration guidance

• New crates and packages should follow the condensed top-level + hyphenated subpackage pattern:
  • Rust crates: weaveffi-*, weaveheap-*.
  • npm packages (planned): @weavefoundry/weaveffi-*, @weavefoundry/weaveheap-*.
  • Swift products: UpperCamelCase (e.g., WeaveFFICore).
• Prefer condensed top-level slugs. Avoid hyphenated top-level slugs like weave-ffi, weave-heap going forward.

Examples

• Rust

  • Crate: weaveffi-core
  • Import: use weaveffi_core::{WeaveFFI};

• Swift (SPM)

  • Repo: weaveffi
  • Package product: WeaveFFI
  • Import: import WeaveFFI

• Python (planned)

  • Package: weaveffi
  • Import: import weaveffi as ffi

• Node (planned)

  • Package: @weavefoundry/weaveffi
  • Import: import { WeaveFFI } from '@weavefoundry/weaveffi'

Generators

This section contains language-specific generators and guidance for using the artifacts they produce. Choose a target below to explore the details.

Feature support matrix

Every generator implements the full IDL surface (structs, enums, interfaces, optionals, lists, maps, typed handles, borrowed parameters, builders, typed error domains with opt-in throws, and nested modules) plus the call shapes below. A generator that cannot support a feature declares it in its TargetCapabilities, and weaveffi generate fails loudly when an IDL uses a feature the selected target cannot deliver (no silent skips).

Notes:

• Iterators are lazy. Every target wraps the C ABI’s handle/_next/_destroy triple in its native lazy idiom (Go iter.Seq, Swift Sequence, C++ input-iterator range, Kotlin Iterator, JS iterables, Python iterators, .NET IEnumerable<T>, Dart Iterable, Ruby Enumerator), pulling one element per consumer step and destroying the handle exactly once. C exposes the raw symbols directly.
• Go and Ruby async wrappers block the calling thread until the producer’s completion callback fires (a channel receive in Go, a Queue#pop in Ruby). Run them from a goroutine or Ruby thread for concurrency; the native producer still runs off-thread.
• Wasm callbacks/listeners deliver synchronously. The loader installs one long-lived JavaScript trampoline per callback typedef in the module’s function table, so the producer’s emit_* dispatches straight back into JS. Because wasm32-unknown-unknown is single-threaded, events fire only while a call into the module is on the stack; a producer that emits from a spawned thread cannot run on this target at all (details). In Emscripten mode callbacks, listeners, and async functions become explicit throwing stubs rather than silent no-ops.

Android

Overview

The Android target produces a Gradle android-library template that combines a Kotlin wrapper, JNI C shims, and a CMake build for the JNI shared library. The wrapper exposes idiomatic Kotlin types while the JNI layer bridges them to the C ABI.

What gets generated

Type mapping

Example IDL → generated code

version: "0.5.0"
modules:
  - name: contacts
    enums:
      - name: ContactType
        variants:
          - { name: Personal, value: 0 }
          - { name: Work, value: 1 }
          - { name: Other, value: 2 }

    structs:
      - name: Contact
        fields:
          - { name: name, type: string }
          - { name: age, type: i32 }

    functions:
      - name: get_contact
        params:
          - { name: id, type: i32 }
        return: Contact

      - name: find_by_type
        params:
          - { name: contact_type, type: ContactType }
        return: "[Contact]"

The Kotlin wrapper declares external fun entries inside a companion object and loads the JNI library on first use. Function names are lowerCamelCase with the module prefix stripped by default (strip_module_prefix = false in [android] restores prefixed names). Where a parameter or return value needs wrapping (enums, structs), the external entry is a private ...Jni function with lowered types and a public wrapper converts at the boundary. Struct returns come back as handles and are wrapped in the struct class; [Contact] stays a LongArray of handles:

package com.weaveffi

class WeaveFFI {
    companion object {
        init { System.loadLibrary("weaveffi") }

        @JvmStatic private external fun getContactJni(id: Int): Long
        @JvmStatic fun getContact(id: Int): Contact = Contact(getContactJni(id))
        @JvmStatic private external fun findByTypeJni(contactType: Int): LongArray
        @JvmStatic fun findByType(contactType: ContactType): LongArray = findByTypeJni(contactType.value)
    }
}

Enums become Kotlin enum class with a fromValue factory:

enum class ContactType(val value: Int) {
    Personal(0),
    Work(1),
    Other(2);

    companion object {
        fun fromValue(value: Int): ContactType = entries.first { it.value == value }
    }
}

Structs are wrapped in a Kotlin class implementing Closeable, with a finalize() safety net:

class Contact internal constructor(internal var handle: Long) : java.io.Closeable {
    companion object {
        init { System.loadLibrary("weaveffi") }

        @JvmStatic external fun nativeCreate(name: String, age: Int): Long
        @JvmStatic external fun nativeDestroy(handle: Long)
        @JvmStatic external fun nativeGetName(handle: Long): String
        @JvmStatic external fun nativeGetAge(handle: Long): Int

        fun create(name: String, age: Int): Contact = Contact(nativeCreate(name, age))
    }

    val name: String get() = nativeGetName(handle)
    val age: Int get() = nativeGetAge(handle)

    override fun close() {
        if (handle != 0L) {
            nativeDestroy(handle)
            handle = 0L
        }
    }

    protected fun finalize() {
        close()
    }
}

The JNI shims (weaveffi_jni.c) bridge each Kotlin external fun into the C ABI and route errors through a shared throw_weaveffi_error helper that throws the generic WeaveFFIException:

static void throw_weaveffi_error(JNIEnv* env, weaveffi_error* err) {
    const char* msg = err->message ? err->message : "WeaveFFI error";
    jclass exClass = (*env)->FindClass(env, "com/weaveffi/WeaveFFIException");
    if (exClass != NULL) {
        jmethodID ctor = (*env)->GetMethodID(env, exClass, "<init>", "(ILjava/lang/String;)V");
        jstring jmsg = (*env)->NewStringUTF(env, msg);
        jthrowable ex = (jthrowable)(*env)->NewObject(env, exClass, ctor, (jint)err->code, jmsg);
        if (ex != NULL) { (*env)->Throw(env, ex); }
    }
    weaveffi_error_clear(err);
}

JNIEXPORT jlong JNICALL Java_com_weaveffi_WeaveFFI_getContactJni(JNIEnv* env, jclass clazz, jint id) {
    weaveffi_error err = {0, NULL};
    weaveffi_contacts_Contact* rv = weaveffi_contacts_get_contact((int32_t)id, &err);
    if (err.code != 0) {
        throw_weaveffi_error(env, &err);
        return 0;
    }
    return (jlong)(intptr_t)rv;
}

The CMake file links the JNI shim against the generated C header:

cmake_minimum_required(VERSION 3.22)
project(weaveffi)
add_library(weaveffi SHARED weaveffi_jni.c)
target_include_directories(weaveffi PRIVATE ../../../../c)

Typed errors

Every generated file carries the generic open class WeaveFFIException(val code: Int, message: String). A module’s error domain adds a sealed exception hierarchy named after the domain with the trailing Error stem replaced by Exception (KvError becomes KvException), one nested class per code, and a fromCode mapper. From the kvstore sample:

/** Generic WeaveFFI failure: panics, marshalling errors, and unknown codes. */
open class WeaveFFIException(val code: Int, message: String) : Exception(message)

/** Typed error domain `KvError` declared by module `kv`. */
sealed class KvException(code: Int, message: String) : WeaveFFIException(code, message) {
    class KeyNotFound(message: String = "key not found") : KvException(1001, message)
    class Expired(message: String = "entry expired") : KvException(1002, message)
    class StoreFull(message: String = "store has reached capacity") : KvException(1003, message)
    class IoError(message: String = "I/O failure") : KvException(1004, message)

    companion object {
        fun fromCode(code: Int, message: String): WeaveFFIException = when (code) {
            1001 -> KeyNotFound(message)
            1002 -> Expired(message)
            1003 -> StoreFull(message)
            1004 -> IoError(message)
            else -> WeaveFFIException(code, message)
        }
    }
}

A callable with throws: true throws the matching subclass from its JNI shim (a per-domain throw_weaveffi_kv_KvError helper resolves com/weaveffi/KvException$KeyNotFound and friends by code); catch the specific class, the sealed domain, or the generic base:

try {
    store.put("alpha", byteArrayOf(1), EntryKind.Volatile, null)
} catch (e: KvException.StoreFull) {
    // typed case
} catch (e: KvException) {
    // any kv domain error
}

A callable without throws keeps a plain signature; its only possible failures are producer bugs (a panic or a marshalling failure), which arrive as the generic WeaveFFIException. Unknown codes on the typed path fall back to WeaveFFIException too.

Interfaces

An interfaces: entry becomes a Kotlin class holding a Long handle and implementing java.io.Closeable, exactly like a struct wrapper. Its members live on the class: constructors become companion factories (a constructor named new becomes operator fun invoke, so ContactBook() reads like a real constructor), methods are instance functions, statics are companion functions, and close() calls the implicit destroy symbol. From the kvstore sample’s Store (trimmed):

/** An embedded key-value store owning its entries */
class Store internal constructor(internal var handle: Long) : java.io.Closeable {
    companion object {
        init { System.loadLibrary("weaveffi") }

        @JvmStatic private external fun nativeOpen(path: String): Long
        @JvmStatic private external fun nativeDefaultCapacity(): Long
        @JvmStatic private external fun nativeDelete(selfHandle: Long, key: String): Boolean
        @JvmStatic private external fun nativeDestroy(handle: Long)

        /** Open (or create) a store backed by the given filesystem path */
        fun open(path: String): Store = Store(nativeOpen(path))

        /** The largest number of live entries one store will hold */
        fun defaultCapacity(): Long = nativeDefaultCapacity()
    }

    /** Remove the entry for the given key, returning true if it existed */
    fun delete(key: String): Boolean = nativeDelete(handle, key)

    /** Stream every key, optionally filtered by a prefix */
    fun listKeys(prefix: String?): Iterator<String> = KvStoreListKeysIterator(nativeListKeys(handle, prefix))

    /** Reclaim space asynchronously; returns the number of bytes reclaimed */
    suspend fun compact(): Long = suspendCancellableCoroutine { cont ->
        nativeCompactAsync(handle, 0L, WeaveContinuation(cont) { code, message -> KvException.fromCode(code, message) })
    }

    /** Legacy single-shot put kept for compatibility */
    @Deprecated("use put() with explicit kind")
    fun legacyPut(key: String, value: ByteArray): Boolean = nativeLegacyPut(handle, key, value)

    override fun close() {
        if (handle != 0L) {
            nativeDestroy(handle)
            handle = 0L
        }
    }
}

Store.open("/tmp/cache.kv").use { store ->
    store.put("alpha", byteArrayOf(1), EntryKind.Volatile, null)
    println(store.count())
}

The JNI externals pass the wrapper’s handle as the leading selfHandle argument. An interface parameter elsewhere in the API takes the wrapper class (WeaveFFI.getStats(store: Store) in the nested stats module); an interface return wraps the new owned handle.

Rich (algebraic) enums

A rich (algebraic) enum, a sum type whose variants carry associated data, lowers to an opaque object handle at the C ABI, exactly like a struct, and shares the same ownership model as the struct wrappers above. The Kotlin wrapper is a Closeable class holding a Long handle, with one static factory per variant, a nested Tag discriminant enum class, and per-variant field getters. (A plain C-style enum with no payloads stays a Kotlin enum class backed by an Int; see above.)

For the shapes module’s Shape enum (Empty, Circle { radius: f64 }, Rectangle { width: f32, height: f32 }, and Labeled { label: string, count: u8 }), the generator emits (abridged):

/** An algebraic shape (sum type with associated data) */
class Shape internal constructor(internal var handle: Long) : java.io.Closeable {
    companion object {
        init { System.loadLibrary("weaveffi") }

        @JvmStatic external fun nativeTag(handle: Long): Int
        @JvmStatic external fun nativeDestroy(handle: Long)
        @JvmStatic external fun nativeNewEmpty(): Long
        @JvmStatic external fun nativeNewCircle(radius: Double): Long
        @JvmStatic external fun nativeNewRectangle(width: Float, height: Float): Long
        @JvmStatic external fun nativeNewLabeled(label: String, count: Byte): Long
        @JvmStatic external fun nativeGetCircleRadius(handle: Long): Double
        @JvmStatic external fun nativeGetLabeledCount(handle: Long): Byte

        /** The empty shape */
        fun empty(): Shape = Shape(nativeNewEmpty())
        /** A circle with a radius */
        fun circle(radius: Double): Shape = Shape(nativeNewCircle(radius))
        /** An axis-aligned rectangle */
        fun rectangle(width: Float, height: Float): Shape = Shape(nativeNewRectangle(width, height))
        /** A labeled shape with a small count */
        fun labeled(label: String, count: Byte): Shape = Shape(nativeNewLabeled(label, count))
    }

    enum class Tag(val value: Int) {
        Empty(0),
        Circle(1),
        Rectangle(2),
        Labeled(3);

        companion object {
            fun fromValue(value: Int): Tag = entries.first { it.value == value }
        }
    }

    val tag: Tag get() = Tag.fromValue(nativeTag(handle))

    /** Radius in points */
    val circleRadius: Double get() = nativeGetCircleRadius(handle)
    val labeledCount: Byte get() = nativeGetLabeledCount(handle)

    override fun close() {
        if (handle != 0L) {
            nativeDestroy(handle)
            handle = 0L
        }
    }

    protected fun finalize() {
        close()
    }
}

Each nativeNew* factory maps to a per-variant constructor (weaveffi_shapes_Shape_<Variant>_new), nativeTag reads the discriminant (weaveffi_shapes_Shape_tag), the nativeGet* getters read one variant field (weaveffi_shapes_Shape_<Variant>_get_<field>), and nativeDestroy frees the handle (weaveffi_shapes_Shape_destroy). The JNI shims that back these external methods are named Java_com_weaveffi_Shape_native*:

JNIEXPORT jlong JNICALL Java_com_weaveffi_Shape_nativeNewCircle(JNIEnv* env, jclass clazz, jdouble radius) {
    weaveffi_error err = {0, NULL};
    weaveffi_shapes_Shape* rv = weaveffi_shapes_Shape_Circle_new((double)radius, &err);
    if (err.code != 0) {
        throw_weaveffi_error(env, &err);
        return 0;
    }
    return (jlong)(intptr_t)rv;
}

JNIEXPORT jint JNICALL Java_com_weaveffi_Shape_nativeTag(JNIEnv* env, jclass clazz, jlong handle) {
    return (jint)weaveffi_shapes_Shape_tag((const weaveffi_shapes_Shape*)(intptr_t)handle);
}

JNIEXPORT void JNICALL Java_com_weaveffi_Shape_nativeDestroy(JNIEnv* env, jclass clazz, jlong handle) {
    weaveffi_shapes_Shape_destroy((weaveffi_shapes_Shape*)(intptr_t)handle);
}

Free functions that take or return the enum pass the handle across the boundary; on the WeaveFFI companion they are describe(shape: Shape): String and scale(shape: Shape, factor: Double): Shape:

Shape.circle(2.0).use { c ->
    println(c.tag)            // Tag.Circle
    println(c.circleRadius)   // 2.0
    val bigger = WeaveFFI.scale(c, 3.0)   // returns a new Shape
    try {
        println(WeaveFFI.describe(bigger))
    } finally {
        bigger.close()
    }
}

Ownership: a Shape owns its native handle, so call close() (or use use { ... }) on every Shape you construct or receive, including the new Shape returned by scale. The finalize() safety net runs during GC but is not a substitute for deterministic cleanup.

Build instructions

1. Install Android Studio (Giraffe or newer) plus the NDK.

2. Cross-compile the Rust cdylib for every Android ABI you support:

   rustup target add aarch64-linux-android armv7-linux-androideabi \
                     x86_64-linux-android i686-linux-android
   export ANDROID_NDK_HOME=/path/to/ndk
   cargo ndk -t arm64-v8a -t armeabi-v7a -t x86_64 -t x86 \
       build --release -p your_library
   

3. Open generated/android in Android Studio, sync Gradle, and build the AAR (./gradlew :weaveffi:assemble).

4. Add the resulting AAR as a dependency in your app module and ensure your jniLibs/ directory contains the Rust-built cdylib for each supported ABI.

Memory and ownership

• Struct and interface wrappers implement Closeable; either call .close() explicitly or use use { ... }. The finalize() safety net runs during GC but is not a substitute for deterministic cleanup.
• Strings returned from JNI are fresh Java strings; the JNI shim frees the underlying Rust pointer with weaveffi_free_string before returning.
• Byte arrays returned from JNI are copied with SetByteArrayRegion, then the Rust buffer is freed with weaveffi_free_bytes.
• Returned string arrays and maps free each element with weaveffi_free_string after copying, then release the array buffer (or both parallel key/value buffers) with weaveffi_free_bytes.
• Optional values are passed as boxed wrappers (Integer, Long, Double, Boolean); the JNI shim unboxes and forwards them to the C ABI. A returned boxed optional scalar is read and its box freed with weaveffi_free_bytes.

Async support

Async IDL functions (async: true) are exposed as Kotlin suspend fun declarations built on suspendCancellableCoroutine. The public suspend wrapper passes a WeaveContinuation (a small class with onSuccess / onError methods) to a private external launcher; struct results resume as raw handles and are re-wrapped after the await. From the async-demo sample (WeaveFFI.kt):

@JvmStatic private external fun runTaskAsync(name: String, callback: Any)
@JvmStatic suspend fun runTask(name: String): TaskResult {
    val raw: Long = suspendCancellableCoroutine { cont ->
        runTaskAsync(name, WeaveContinuation(cont) { code, message -> TaskException.fromCode(code, message) })
    }
    return TaskResult(raw)
}

internal class WeaveContinuation<T>(
    private val cont: kotlinx.coroutines.CancellableContinuation<T>,
    private val mapError: (Int, String) -> Throwable
) {
    @Suppress("UNCHECKED_CAST")
    fun onSuccess(result: Any?) { cont.resume(result as T) }
    fun onError(code: Int, message: String) { cont.resumeWithException(mapError(code, message)) }
}

run_task declares throws: true, so a failed suspend call resumes with the typed TaskException; an async callable without throws maps its (producer-bug-only) failures to the generic WeaveFFIException.

The JNI launcher allocates a per-call context holding the JavaVM and a NewGlobalRef to the WeaveContinuation, then hands the C ABI a completion callback. That callback attaches the producer’s thread to the JVM if it is not already attached, calls onSuccess/onError, deletes the global ref, frees the context exactly once, and detaches the thread if it attached it:

typedef struct {
    JavaVM* jvm;
    jobject callback;
} weaveffi_jni_async_ctx;

JNIEXPORT void JNICALL Java_com_weaveffi_WeaveFFI_runTaskAsync(JNIEnv* env, jclass clazz, jstring name, jobject callback) {
    weaveffi_jni_async_ctx* ctx = (weaveffi_jni_async_ctx*)malloc(sizeof(weaveffi_jni_async_ctx));
    (*env)->GetJavaVM(env, &ctx->jvm);
    ctx->callback = (*env)->NewGlobalRef(env, callback);
    const char* name_chars = (*env)->GetStringUTFChars(env, name, NULL);
    weaveffi_tasks_run_task_async(name_chars, weaveffi_tasks_run_task_jni_cb, ctx);
    (*env)->ReleaseStringUTFChars(env, name, name_chars);
}

static void weaveffi_tasks_run_task_jni_cb(void* context, weaveffi_error* err, void* result) {
    weaveffi_jni_async_ctx* ctx = (weaveffi_jni_async_ctx*)context;
    JNIEnv* env = NULL;
    int attached = 0;
    if ((*ctx->jvm)->GetEnv(ctx->jvm, (void**)&env, JNI_VERSION_1_6) != JNI_OK) {
        if ((*ctx->jvm)->AttachCurrentThread(ctx->jvm, (void**)&env, NULL) != JNI_OK) { free(ctx); return; }
        attached = 1;
    }
    /* ... calls callback.onError(int, String) or callback.onSuccess(Object) ... */
    weaveffi_jni_handle_uncaught(env);
    (*env)->DeleteGlobalRef(env, ctx->callback);
    JavaVM* jvm = ctx->jvm;
    free(ctx);
    if (attached) (*jvm)->DetachCurrentThread(jvm);
}

The completion callback fires exactly once, on a producer thread. Result buffers passed to it (strings, byte arrays, arrays) are borrowed from the producer for the callback’s duration, so the shim copies them into Java objects (NewStringUTF, SetByteArrayRegion) inside the callback and never frees them. Owned-object results are the exception: the callback receives ownership, resumes the continuation with the raw handle, and the suspend wrapper adopts it into the wrapper class (TaskResult(raw) above). An exception thrown by the resumed coroutine goes through the same weaveffi_jni_handle_uncaught path as listener exceptions (see Callbacks and listeners).

The generated build.gradle does not declare a coroutines dependency; add org.jetbrains.kotlinx:kotlinx-coroutines-android (or -core) to the consuming project.

For callables marked cancellable: true, the C ABI takes an extra weaveffi_cancel_token* parameter. The private external launcher carries it as cancelToken: Long and the shim casts it to weaveffi_cancel_token*, but the public suspend wrapper currently passes 0L (no token); coroutine cancellation isn’t wired to the native cancel token. From the kvstore sample’s async method Store.compact:

@JvmStatic private external fun nativeCompactAsync(selfHandle: Long, cancelToken: Long, callback: Any)

suspend fun compact(): Long = suspendCancellableCoroutine { cont ->
    nativeCompactAsync(handle, 0L, WeaveContinuation(cont) { code, message -> KvException.fromCode(code, message) })
}

Callbacks and listeners

IDL callbacks paired with listeners produce a register/unregister pair. From the events sample:

modules:
  - name: events
    callbacks:
      - name: OnMessage
        params:
          - { name: message, type: string }
    listeners:
      - name: message_listener
        event_callback: OnMessage

The Kotlin surface takes a lambda and returns a Long subscription id; pass that id back to unregister:

@JvmStatic external fun registerMessageListener(callback: (String) -> Unit): Long
@JvmStatic external fun unregisterMessageListener(id: Long)

The JNI shim keeps the lambda alive with a NewGlobalRef stored in a mutex-guarded registry (a linked list of contexts holding the JavaVM, the global ref, and the subscription id). When the producer fires, a C trampoline attaches the producer’s thread to the JVM if needed and invokes the lambda through its kotlin.jvm.functions.Function1 invoke(Object): Object method; unregistering removes the registry entry, deletes the global ref, and frees the context:

static void weaveffi_events_OnMessage_fn_jni_tramp(const char* message, void* context) {
    weaveffi_jni_listener_ctx* ctx = (weaveffi_jni_listener_ctx*)context;
    JNIEnv* env = NULL;
    int attached = 0;
    if ((*ctx->jvm)->GetEnv(ctx->jvm, (void**)&env, JNI_VERSION_1_6) != JNI_OK) {
        if ((*ctx->jvm)->AttachCurrentThread(ctx->jvm, (void**)&env, NULL) != JNI_OK) return;
        attached = 1;
    }
    if ((*env)->PushLocalFrame(env, 32) != 0) {
        if (attached) (*ctx->jvm)->DetachCurrentThread(ctx->jvm);
        return;
    }
    jobject _a0 = message ? (jobject)(*env)->NewStringUTF(env, message) : (jobject)(*env)->NewStringUTF(env, "");
    jclass fn_cls = (*env)->GetObjectClass(env, ctx->callback);
    jmethodID invoke = (*env)->GetMethodID(env, fn_cls, "invoke", "(Ljava/lang/Object;)Ljava/lang/Object;");
    (*env)->CallObjectMethod(env, ctx->callback, invoke, _a0);
    weaveffi_jni_handle_uncaught(env);
    (*env)->PopLocalFrame(env, NULL);
    if (attached) (*ctx->jvm)->DetachCurrentThread(ctx->jvm);
}

JNIEXPORT jlong JNICALL Java_com_weaveffi_WeaveFFI_registerMessageListener(JNIEnv* env, jclass clazz, jobject callback) {
    weaveffi_jni_listener_ctx* ctx = (weaveffi_jni_listener_ctx*)calloc(1, sizeof(weaveffi_jni_listener_ctx));
    (*env)->GetJavaVM(env, &ctx->jvm);
    ctx->callback = (*env)->NewGlobalRef(env, callback);
    uint64_t id = weaveffi_events_register_message_listener(weaveffi_events_OnMessage_fn_jni_tramp, ctx);
    /* ... stores ctx in the registry under id ... */
    return (jlong)id;
}

The callback runs on the producer’s thread, whichever thread the native side fires the event from. For UI work, hop to the main thread yourself (e.g. withContext(Dispatchers.Main) or Handler.post).

An exception thrown by the Kotlin callback has no caller to propagate to, since the frame below it is native producer code. The glue routes it through weaveffi_jni_handle_uncaught, which delivers it to the handler installed on the module companion:

/**
 * Installs a handler for exceptions thrown by listener callbacks and
 * async continuations on native producer threads. These exceptions have
 * no Kotlin caller to propagate to; when no handler is installed, they
 * are logged with their stack trace and dropped. Pass `null` to
 * restore the default logging behavior.
 */
@JvmStatic fun setCallbackExceptionHandler(handler: ((Throwable) -> Unit)?) {
    callbackExceptionHandler = handler
}

When a module declares listeners or async functions, the JNI glue also defines JNI_OnLoad, which caches a global reference to the wrapper class and the dispatchCallbackException method id so the producer thread can deliver exceptions without an extra class lookup.

Iterators

iter<T> returns surface as Iterator<T> in Kotlin, backed by a generated per-function wrapper class that is fully lazy: the external launcher returns the raw iterator handle as a Long, and each hasNext() lookahead issues exactly one nativeNext call, which maps to one producer _next call. Nothing is drained into a hidden list. From the events sample (get_messages returns iter<string>):

@JvmStatic private external fun getMessagesJni(): Long
@JvmStatic fun getMessages(): Iterator<String> = EventsGetMessagesIterator(getMessagesJni())

/**
 * A lazy iterator over the `String` elements streamed by [getMessages]. Each step pulls
 * exactly one element from the native producer. The native handle is
 * released when the producer is exhausted, when [close] is called, or by
 * the finalizer if the iterator is abandoned, whichever comes first.
 */
class EventsGetMessagesIterator internal constructor(private var handle: Long) : Iterator<String>, java.io.Closeable {
    private var nextSlot: Array<Any?>? = null

    override fun hasNext(): Boolean {
        if (nextSlot != null) return true
        if (handle == 0L) return false
        val slot = nativeNext(handle)
        if (slot == null) {
            close()
            return false
        }
        nextSlot = slot
        return true
    }

    override fun next(): String {
        if (!hasNext()) throw NoSuchElementException()
        val raw = nextSlot!![0]
        nextSlot = null
        return raw as String
    }

    override fun close() {
        if (handle != 0L) {
            nativeDestroy(handle)
            handle = 0L
        }
    }

    protected fun finalize() {
        close()
    }

    companion object {
        init { System.loadLibrary("weaveffi") }

        @JvmStatic private external fun nativeNext(handle: Long): Array<Any?>?
        @JvmStatic private external fun nativeDestroy(handle: Long)
    }
}

The JNI nativeNext shim pulls one element and returns it in a one-slot Object[]; null means the stream is exhausted. Each string element is freed with weaveffi_free_string right after NewStringUTF copies it; when the element type is a struct, the raw handle is returned instead and the Kotlin next() adopts it into the owning wrapper class (Contact(raw as Long)), whose close() eventually destroys it:

JNIEXPORT jobjectArray JNICALL Java_com_weaveffi_EventsGetMessagesIterator_nativeNext(JNIEnv* env, jclass clazz, jlong handle) {
    weaveffi_events_GetMessagesIterator* _iter = (weaveffi_events_GetMessagesIterator*)(intptr_t)handle;
    const char* _item = (const char*)0;
    weaveffi_error err = {0, NULL};
    int32_t _has = weaveffi_events_GetMessagesIterator_next(_iter, &_item, &err);
    if (err.code != 0) {
        throw_weaveffi_error(env, &err);
        return NULL;
    }
    if (_has == 0) { return NULL; }
    jstring _jitem = _item ? (*env)->NewStringUTF(env, _item) : (*env)->NewStringUTF(env, "");
    weaveffi_free_string(_item);
    jclass _obj_cls = (*env)->FindClass(env, "java/lang/Object");
    jobjectArray _slot = (*env)->NewObjectArray(env, 1, _obj_cls, NULL);
    (*env)->SetObjectArrayElement(env, _slot, 0, _jitem);
    return _slot;
}

The native handle is destroyed exactly once: close() is called eagerly when hasNext() sees exhaustion, callers can call close() themselves (the class implements Closeable) when abandoning iteration early, and the finalize() safety net covers abandoned iterators during GC. Nulling the handle makes a double destroy impossible.

Errors from the launcher and from each next follow the function’s error strategy: the throwing kvstore sample’s Store.listKeys shim throws the typed domain exception (throw_weaveffi_kv_KvError, so KvException.KeyNotFound and friends) from the step that failed, while the non-throwing getMessages throws the generic WeaveFFIException only for producer bugs.

Troubleshooting

• UnsatisfiedLinkError: Couldn't find libweaveffi.so: the Rust-built cdylib was not packaged inside the AAR. Place it under src/main/jniLibs/<abi>/ and rebuild.
• UnsatisfiedLinkError for the JNI symbol itself: Kotlin external function names must match the JNI signature, including the _1 escape for underscores. Re-run weaveffi generate if you hand-edited either side.
• Crashes when releasing strings: the JNI shim is responsible for calling ReleaseStringUTFChars on every GetStringUTFChars. If you edit the shim, keep the pairing intact.
• R8/ProGuard removes WeaveFFI symbols: keep the wrapper class with -keep class com.weaveffi.** { *; } in your ProGuard rules.

C

Overview

The C target emits the canonical C header and a thin reference C file that every other WeaveFFI target ultimately speaks to. All cross-language bindings sit on top of these symbols, so the C output is also the easiest way to inspect what the IDL compiles to.

What gets generated

Type mapping

C ABI symbol naming follows a strict convention:

{Function} is the function name converted to PascalCase (get_messages → GetMessages). An iterator returned by an interface method nests under the interface instead: weaveffi_kv_Store_ListKeysIterator. Interface members and async launchers compose the same way (weaveffi_kv_Store_compact_async).

When the IDL sets c_prefix, every symbol, including the runtime helpers, is rewritten with the new prefix.

Example IDL → generated code

version: "0.5.0"
modules:
  - name: contacts
    enums:
      - name: ContactType
        variants:
          - { name: Personal, value: 0 }
          - { name: Work, value: 1 }
          - { name: Other, value: 2 }

    structs:
      - name: Contact
        fields:
          - { name: name, type: string }
          - { name: email, type: "string?" }
          - { name: age, type: i32 }

    functions:
      - name: create_contact
        params:
          - { name: first_name, type: string }
          - { name: last_name, type: string }
        return: Contact

      - name: find_contact
        params:
          - { name: id, type: "i32?" }
        return: "Contact?"

      - name: list_contacts
        params: []
        return: "[Contact]"

      - name: count_contacts
        params: []
        return: i32

The header opens with an include guard, standard headers, an extern "C" block, and the shared error/memory helpers:

#ifndef WEAVEFFI_H
#define WEAVEFFI_H

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef uint64_t weaveffi_handle_t;

typedef struct weaveffi_error {
    int32_t code;
    const char* message;
} weaveffi_error;

void weaveffi_error_clear(weaveffi_error* err);
void weaveffi_free_string(const char* ptr);
void weaveffi_free_bytes(uint8_t* ptr, size_t len);

In the real output each prototype is prefixed with a WEAVEFFI_API visibility macro (and deprecated functions with WEAVEFFI_DEPRECATED), omitted here for brevity. See Symbol visibility for what it does and when you need it.

Structs become forward-declared opaque typedefs reached via create/destroy/getter functions:

typedef struct weaveffi_contacts_Contact weaveffi_contacts_Contact;

weaveffi_contacts_Contact* weaveffi_contacts_Contact_create(
    const char* name,
    const char* email,
    int32_t age,
    weaveffi_error* out_err);

void weaveffi_contacts_Contact_destroy(weaveffi_contacts_Contact* ptr);

const char* weaveffi_contacts_Contact_get_name(
    const weaveffi_contacts_Contact* ptr);

Enums turn into typed enum declarations with prefixed variants:

typedef enum {
    weaveffi_contacts_ContactType_Personal = 0,
    weaveffi_contacts_ContactType_Work = 1,
    weaveffi_contacts_ContactType_Other = 2
} weaveffi_contacts_ContactType;

Optionals and lists use pointer-with-sentinel and pointer+length pairs:

int32_t* weaveffi_store_find(const int32_t* id, weaveffi_error* out_err);

weaveffi_contacts_Contact** weaveffi_contacts_list_contacts(
    size_t* out_len,
    weaveffi_error* out_err);

Every function takes a trailing weaveffi_error* out_err. On failure out_err->code is non-zero and out_err->message points at a Rust-allocated string the consumer must clear:

weaveffi_error err = {0, NULL};
int32_t total = weaveffi_contacts_count_contacts(&err);
if (err.code != 0) {
    fprintf(stderr, "Error %d: %s\n", err.code, err.message);
    weaveffi_error_clear(&err);
    return 1;
}

Interfaces

An interfaces: entry lowers to a forward-declared opaque struct plus one prototype per member. Constructors return an owned pointer, methods take a leading const {tag}* self argument before their declared parameters, statics take no self, and every interface gets an implicit _destroy. From the kvstore sample’s Store:

typedef struct weaveffi_kv_Store weaveffi_kv_Store;

/* Constructor: returns a new owned instance. */
weaveffi_kv_Store* weaveffi_kv_Store_open(const char* path, weaveffi_error* out_err);

/* Static: no self slot. */
int64_t weaveffi_kv_Store_default_capacity(weaveffi_error* out_err);

/* Methods: an implicit leading self slot. */
bool weaveffi_kv_Store_delete(const weaveffi_kv_Store* self, const char* key,
                              weaveffi_error* out_err);
int64_t weaveffi_kv_Store_count(const weaveffi_kv_Store* self, weaveffi_error* out_err);

/* Implicit destructor: releases the object. */
void weaveffi_kv_Store_destroy(weaveffi_kv_Store* self);

Ownership follows the reference direction: an interface parameter (such as const weaveffi_kv_Store* store on weaveffi_kv_stats_get_stats) is borrowed for the duration of the call, while every pointer returned by a constructor or function is owned by the consumer, who must eventually pass it to _destroy. Iterator-returning and async methods follow the same shapes as free functions with the self slot in front: Store.list_keys yields a weaveffi_kv_Store_ListKeysIterator handle, and the async Store.compact appears under Async support.

Typed errors

C is the raw ABI surface, so throwing and non-throwing callables look identical: every prototype carries the trailing weaveffi_error* out_err, and the consumer checks err.code after each call. What a module’s error domain adds is a typed C enum naming the codes its throws: true callables can report, so consumers match on names instead of magic numbers. From the kvstore sample’s KvError domain:

/** Error codes reported by throwing functions in the `kv` module tree. */
typedef enum {
    weaveffi_kv_KvError_KeyNotFound = 1001,
    weaveffi_kv_KvError_Expired = 1002,
    weaveffi_kv_KvError_StoreFull = 1003,
    weaveffi_kv_KvError_IoError = 1004
} weaveffi_kv_KvError;

A callable declared with throws: true can set any of these codes; a callable without throws can only fail with the reserved codes (-2 for a producer panic, 1 for a marshalling failure). See the Error Handling guide for the full code table.

Symbol visibility

Every function prototype is tagged with a WEAVEFFI_API macro that the header defines near the top:

#ifndef WEAVEFFI_API
#  if defined(_WIN32) || defined(__CYGWIN__)
#    ifdef WEAVEFFI_BUILD
#      define WEAVEFFI_API __declspec(dllexport)
#    else
#      define WEAVEFFI_API __declspec(dllimport)
#    endif
#  elif defined(__GNUC__) && (__GNUC__ >= 4)
#    define WEAVEFFI_API __attribute__((visibility("default")))
#  else
#    define WEAVEFFI_API
#  endif
#endif

This covers the two ways the header is used:

• Consuming a prebuilt library (the common case) needs nothing extra. On Windows the prototypes resolve to __declspec(dllimport); everywhere else the macro is harmless.
• Implementing the header (a C, C++, or Zig backend that supplies the symbols instead of calling them) relies on the macro to stay exportable. Under hidden default visibility (-fvisibility=hidden, the release-build norm and the MSVC default) an untagged definition is local and ships no usable symbol. On GCC and Clang the macro applies visibility("default"), so your definitions export with no extra flags.

When you implement the header on Windows, compile your library with WEAVEFFI_BUILD defined so the macro switches to __declspec(dllexport):

cc -DWEAVEFFI_BUILD -shared mylib.c -o mylib.dll

Deprecated functions carry a companion WEAVEFFI_DEPRECATED("...") macro that expands to __declspec(deprecated(...)) on MSVC and __attribute__((deprecated(...))) on GCC and Clang.

When the IDL sets c_prefix, both macros follow it: a c_prefix of acme yields ACME_API, ACME_BUILD, and ACME_DEPRECATED, so two WeaveFFI-generated libraries can coexist in one translation unit without colliding.

Rich (algebraic) enums

An enum whose variants declare fields is a rich (algebraic) enum, a sum type with associated data. Unlike a plain C-style enum (a bare int32_t discriminant), a rich enum crosses the ABI as an opaque object pointer, exactly like a struct: the producer owns the payload and the consumer holds a handle. A plain _Tag enum names the discriminants, then constructors, a tag reader, per-variant getters, and a destructor operate on the handle. From the shapes sample (Shape = Empty | Circle{radius} | Rectangle{width,height} | Labeled{label,count}):

typedef enum {
    weaveffi_shapes_Shape_Empty = 0,
    weaveffi_shapes_Shape_Circle = 1,
    weaveffi_shapes_Shape_Rectangle = 2,
    weaveffi_shapes_Shape_Labeled = 3
} weaveffi_shapes_Shape_Tag;

typedef struct weaveffi_shapes_Shape weaveffi_shapes_Shape;

int32_t weaveffi_shapes_Shape_tag(const weaveffi_shapes_Shape* self);

weaveffi_shapes_Shape* weaveffi_shapes_Shape_Empty_new(weaveffi_error* out_err);
weaveffi_shapes_Shape* weaveffi_shapes_Shape_Circle_new(double radius, weaveffi_error* out_err);
weaveffi_shapes_Shape* weaveffi_shapes_Shape_Rectangle_new(float width, float height, weaveffi_error* out_err);
weaveffi_shapes_Shape* weaveffi_shapes_Shape_Labeled_new(const char* label, uint8_t count, weaveffi_error* out_err);

double weaveffi_shapes_Shape_Circle_get_radius(const weaveffi_shapes_Shape* self);
float weaveffi_shapes_Shape_Rectangle_get_width(const weaveffi_shapes_Shape* self);
float weaveffi_shapes_Shape_Rectangle_get_height(const weaveffi_shapes_Shape* self);
const char* weaveffi_shapes_Shape_Labeled_get_label(const weaveffi_shapes_Shape* self);
uint8_t weaveffi_shapes_Shape_Labeled_get_count(const weaveffi_shapes_Shape* self);

void weaveffi_shapes_Shape_destroy(weaveffi_shapes_Shape* self);

Read _tag, then call only the matching variant’s getters. A getter that returns a const char* hands back Rust-owned memory to free with weaveffi_free_string:

weaveffi_error err = {0, NULL};
weaveffi_shapes_Shape* shape = weaveffi_shapes_Shape_Circle_new(2.0, &err);

if (weaveffi_shapes_Shape_tag(shape) == weaveffi_shapes_Shape_Circle) {
    printf("radius = %f\n", weaveffi_shapes_Shape_Circle_get_radius(shape));
}

const char* text = weaveffi_shapes_describe(shape, &err);
printf("%s\n", text);
weaveffi_free_string(text);

weaveffi_shapes_Shape_destroy(shape);

The consumer owns every weaveffi_shapes_Shape* returned by a constructor or by a function such as weaveffi_shapes_scale; release each one with weaveffi_shapes_Shape_destroy.

Build instructions

The runnable consumer uses the contacts sample crate and its conformance program.

macOS:

cargo build -p contacts
weaveffi generate samples/contacts/contacts.yml -o generated

cc -I generated/c conformance/c/contacts.c -L target/debug -lcontacts -o c_contacts
DYLD_LIBRARY_PATH=target/debug ./c_contacts

Linux:

cargo build -p contacts
weaveffi generate samples/contacts/contacts.yml -o generated

cc -I generated/c conformance/c/contacts.c -L target/debug -lcontacts -o c_contacts
LD_LIBRARY_PATH=target/debug ./c_contacts

Windows:

cargo build -p contacts
weaveffi generate samples\contacts\contacts.yml -o generated
cl /I generated\c conformance\c\contacts.c /link contacts.lib
.\contacts.exe

See conformance/c/ for end-to-end consumers of every sample.

Memory and ownership

Rust always owns memory it allocates. Strings and byte buffers returned across the boundary must be freed by the consumer with the matching helper:

const char* name = weaveffi_contacts_Contact_get_name(contact);
printf("Name: %s\n", name);
weaveffi_free_string(name);

size_t len;
const uint8_t* data = weaveffi_storage_get_data(&len, &err);
weaveffi_free_bytes((uint8_t*)data, len);

For struct handles, call the matching _destroy symbol when the consumer is done. Borrowed parameters (const T*, string/bytes inputs) remain owned by the caller for the duration of the call only.

Callbacks and listeners

A callbacks: entry becomes a function-pointer typedef whose parameters mirror the IDL signature plus a trailing opaque void* context. A listeners: entry becomes a register/unregister pair built on that typedef. From the events sample:

typedef void (*weaveffi_events_OnMessage_fn)(const char* message, void* context);

uint64_t weaveffi_events_register_message_listener(
    weaveffi_events_OnMessage_fn callback,
    void* context);
void weaveffi_events_unregister_message_listener(uint64_t id);

The contract:

• register_* stores the (callback, context) pair and returns a uint64_t subscription id. Pass that id to unregister_* to stop delivery.
• context is opaque to the producer and is passed back verbatim as the last argument of every invocation. It must stay valid until the listener is unregistered.
• The producer invokes the callback on its own thread, whenever the event fires. The callback must be thread-safe and must not assume it runs on the registering thread.
• Pointer arguments (e.g. const char* message) are only valid for the duration of the invocation; copy anything that must outlive it.

static void on_message(const char* message, void* context) {
    int* count = context;       /* runs on the producer's thread */
    (*count)++;
}

weaveffi_error err = {0, NULL};
int count = 0;
uint64_t id = weaveffi_events_register_message_listener(on_message, &count);
weaveffi_events_send_message("hello", &err);   /* fires the listener */
weaveffi_events_unregister_message_listener(id);

Async support

Async functions (async: true) get no synchronous prototype. Each one emits a per-function callback typedef, (void* context, weaveffi_error* err, <result slots>), and a launcher with the _async suffix. From the async-demo sample:

typedef void (*weaveffi_tasks_run_task_callback)(
    void* context,
    weaveffi_error* err,
    weaveffi_tasks_TaskResult* result);

void weaveffi_tasks_run_task_async(
    const char* name,
    weaveffi_tasks_run_task_callback callback,
    void* context);

The launcher returns immediately; WeaveFFI invokes the callback exactly once, with either a result or a populated error, from the producer’s worker thread.

Ownership inside the callback follows the async contract. Result buffers (strings, bytes, arrays, map buffers, boxed optional scalars) are borrowed: they stay owned by the producer and are valid only for the callback’s duration, so copy anything you need before returning and don’t free them. Owned-object results (records, rich enums, interfaces, including optional ones) are the exception: the callback receives ownership of the pointer and must eventually pass it to the matching _destroy. The err struct is likewise borrowed; copy its code and message inside the callback.

For cancellable: true functions the launcher gains a weaveffi_cancel_token* slot before the callback, and the runtime provides the token lifecycle. Async interface methods follow the same shape with the leading self slot; from the kvstore sample’s async cancellable Store.compact:

typedef void (*weaveffi_kv_Store_compact_callback)(
    void* context,
    weaveffi_error* err,
    int64_t result);

void weaveffi_kv_Store_compact_async(
    const weaveffi_kv_Store* self,
    weaveffi_cancel_token* cancel_token,
    weaveffi_kv_Store_compact_callback callback,
    void* context);

weaveffi_cancel_token* weaveffi_cancel_token_create(void);
void weaveffi_cancel_token_cancel(weaveffi_cancel_token* token);
bool weaveffi_cancel_token_is_cancelled(const weaveffi_cancel_token* token);
void weaveffi_cancel_token_destroy(weaveffi_cancel_token* token);

See Async functions for the full pattern.

Iterators

Functions returning iter<T> produce an opaque iterator handle plus _next/_destroy functions instead of a materialized list. From the events sample (get_messages returns iter<string>):

typedef struct weaveffi_events_GetMessagesIterator weaveffi_events_GetMessagesIterator;

weaveffi_events_GetMessagesIterator* weaveffi_events_get_messages(
    weaveffi_error* out_err);
int32_t weaveffi_events_GetMessagesIterator_next(
    weaveffi_events_GetMessagesIterator* iter,
    const char** out_item,
    weaveffi_error* out_err);
void weaveffi_events_GetMessagesIterator_destroy(
    weaveffi_events_GetMessagesIterator* iter);

_next writes the next element into the one-slot out-param and returns 1, or returns 0 when exhausted (leaving *out_item untouched). Failures are reported through out_err, so check it after the loop ends. Element ownership follows the usual return rules; each next hands over an element the consumer now owns, so here each const char* must be freed with weaveffi_free_string. Call _destroy exactly once when done, even if iteration stopped early:

weaveffi_error err = {0, NULL};
weaveffi_events_GetMessagesIterator* iter = weaveffi_events_get_messages(&err);
const char* item = NULL;
while (weaveffi_events_GetMessagesIterator_next(iter, &item, &err) == 1) {
    printf("%s\n", item);
    weaveffi_free_string(item);
}
if (err.code != 0) { /* a failing step ended the loop */ }
weaveffi_events_GetMessagesIterator_destroy(iter);

The higher-level targets wrap exactly these three symbols in their native lazy idioms; only the C surface exposes them raw.

Troubleshooting

• undefined reference to weaveffi_*: make sure the linker sees the cdylib (-L target/debug -l<your-crate>). The header alone is not enough.
• Crashes inside weaveffi_free_string: the pointer wasn’t Rust-allocated. Only free pointers returned from a generated getter or function.
• error: unknown type weaveffi_handle_t: the consumer included the header without <stdint.h>. Include order matters; the generated header pulls in the standard integer typedefs explicitly.
• weaveffi.c looks nearly empty: that file only carries the default weaveffi_alloc/weaveffi_dealloc implementations for Wasm producers. All declarations live in weaveffi.h.

Node.js

Overview

The Node.js target produces a CommonJS loader, TypeScript type definitions, and the complete N-API addon C source (plus a binding.gyp) that bridges JS to the C ABI. The loader honors a WEAVEFFI_ADDON environment override, then prefers the node-gyp build output (./build/Release/weaveffi.node), and falls back to a prebuilt binary placed next to it as index.node. On top of the raw native bindings it layers the idiomatic wrappers: error classes, interface and rich-enum classes, and camelCased function wrappers.

What gets generated

Type mapping

Example IDL → generated code

version: "0.5.0"
modules:
  - name: contacts
    enums:
      - name: Color
        variants:
          - { name: Red, value: 0 }
          - { name: Green, value: 1 }
          - { name: Blue, value: 2 }

    structs:
      - name: Contact
        fields:
          - { name: name, type: string }
          - { name: email, type: "string?" }
          - { name: tags, type: "[string]" }

    functions:
      - name: get_contact
        params:
          - { name: id, type: i32 }
        return: "Contact?"

      - name: list_contacts
        params: []
        return: "[Contact]"

      - name: set_favorite_color
        params:
          - { name: contact_id, type: i32 }
          - { name: color, type: "Color?" }

      - name: get_tags
        params:
          - { name: contact_id, type: i32 }
        return: "[string]"

Structs become TypeScript interfaces and enums become explicit numeric TypeScript enums:

export interface Contact {
  name: string;
  email: string | null;
  tags: string[];
}

export enum Color {
  Red = 0,
  Green = 1,
  Blue = 2,
}

Functions are exported flat in lowerCamelCase with the module prefix stripped by default (strip_module_prefix = false in [node] restores <module>_-prefixed names); parameters are camelCased too. Optional return and parameter types use | null, arrays use T[]:

export function getContact(id: number): Contact | null
export function listContacts(): Contact[]
export function setFavoriteColor(contactId: number, color: Color | null): void
export function getTags(contactId: number): string[]

Typed errors

Every generated index.js exports WeaveFFIError (extending Error with a numeric code and the raw errorMessage). A module’s error domain adds a class named after the domain plus one subclass per code, each carrying its stable CODE. From the kvstore sample:

class WeaveFFIError extends Error {
  constructor(code, message) {
    super('(' + code + ') ' + (message || ''));
    this.name = 'WeaveFFIError';
    this.code = code;
    this.errorMessage = message || '';
  }
}

class KvError extends WeaveFFIError { /* ... */ }

class KeyNotFoundError extends KvError {
  constructor(message) {
    super(1001, message || 'key not found');
    this.name = 'KeyNotFoundError';
  }
}
KeyNotFoundError.CODE = 1001;
// ExpiredError, StoreFullError, IoError follow the same shape.

A callable with throws: true rebrands any native failure through the domain’s code map, so consumers catch the typed class:

try {
  store.put('alpha', Buffer.from('1'), EntryKind.Volatile, null);
} catch (e) {
  if (e instanceof StoreFullError) {
    // typed case; e.code === 1003
  } else if (e instanceof KvError) {
    // any kv domain error
  }
}

A callable without throws has the same JS signature (JavaScript has no checked exceptions), but its failures can only be producer bugs, which surface as the generic WeaveFFIError. Unknown codes on the typed path fall back to WeaveFFIError as well.

Interfaces

An interfaces: entry becomes a JS class owning the native pointer, registered with a FinalizationRegistry and freed deterministically via destroy(). Constructors become static factories, methods are instance methods, statics are static methods, all camelCased. From the kvstore sample’s Store (trimmed from index.js):

class Store {
  static open(path) {
    const _r = __invoke(addon.Store_open, [path], __kvErrorFrom);
    return Store._fromHandle(_r);
  }
  put(key, value, kind, ttlSeconds) {
    return __invoke(addon.Store_put, [this._handle, key, value, kind, ttlSeconds], __kvErrorFrom);
  }
  listKeys(prefix) {
    const _it = __invoke(addon.Store_list_keys, [this._handle, prefix], __kvErrorFrom);
    return new WeaveFFIIterator(_it, addon.Store_list_keys_iterNext, addon.Store_list_keys_iterDestroy, __kvErrorFrom, null);
  }
  count() {
    return __invoke(addon.Store_count, [this._handle], __generic);
  }
  compact() {
    return __invokeAsync(addon.Store_compact, [this._handle], __kvErrorFrom);
  }
  static defaultCapacity() {
    return __invoke(addon.Store_default_capacity, [], __generic);
  }
  destroy() {
    if (this._handle) {
      Store._cleanup.unregister(this);
      addon.Store_destroy(this._handle);
      this._handle = 0;
    }
  }
}
Store._cleanup = new FinalizationRegistry((handle) => {
  if (handle) { addon.Store_destroy(handle); }
});

The typed declarations mirror the class, with @throws and @deprecated JSDoc tags:

export class Store {
  /** @throws {KvError} */
  static open(path: string): Store;
  /** @throws {KvError} */
  put(key: string, value: Buffer, kind: EntryKind, ttlSeconds: number | null): boolean;
  /** @throws {KvError} */
  listKeys(prefix: string | null): IterableIterator<string>;
  count(): number;
  /** @throws {KvError} */
  compact(): Promise<number>;
  static defaultCapacity(): number;
  /** Free the underlying native object. */
  destroy(): void;
}

A function elsewhere in the API that takes the interface accepts the wrapper instance and unwraps its handle (getStats(store) in the nested stats module); a function returning an interface wraps the new owned handle in a fresh instance. Call destroy() when you’re done; the FinalizationRegistry is only a GC-timed safety net.

Rich (algebraic) enums

A rich (algebraic) enum is a sum type whose variants carry associated data. A plain C-style enum stays a numeric TypeScript enum, but a rich enum lowers to an opaque object handle at the C ABI, exactly like a struct. The loader layers an idiomatic wrapper class on top of the raw native bindings, and that class owns the native pointer.

Take a Shape enum with variants Empty, Circle { radius: f64 }, Rectangle { width: f32, height: f32 }, and Labeled { label: string, count: u8 }. The generated index.js builds a Shape class with one static factory per variant, a tag() discriminant reader, a camelCased getter per variant field, and a destroy() method, backed by a FinalizationRegistry:

class Shape {
  static empty() {
    return new Shape(__invoke(addon.Shape_empty_new, [], __generic));
  }
  static circle(radius) {
    return new Shape(__invoke(addon.Shape_circle_new, [radius], __generic));
  }
  static rectangle(width, height) {
    return new Shape(__invoke(addon.Shape_rectangle_new, [width, height], __generic));
  }
  static labeled(label, count) {
    return new Shape(__invoke(addon.Shape_labeled_new, [label, count], __generic));
  }
  tag() {
    return addon.Shape_tag(this._handle);
  }
  get circleRadius() {
    return addon.Shape_circle_get_radius(this._handle);
  }
  get rectangleWidth() {
    return addon.Shape_rectangle_get_width(this._handle);
  }
  get rectangleHeight() {
    return addon.Shape_rectangle_get_height(this._handle);
  }
  get labeledLabel() {
    return addon.Shape_labeled_get_label(this._handle);
  }
  get labeledCount() {
    return addon.Shape_labeled_get_count(this._handle);
  }
  destroy() {
    if (this._handle) {
      Shape._cleanup.unregister(this);
      addon.Shape_destroy(this._handle);
      this._handle = 0;
    }
  }
}
Shape._cleanup = new FinalizationRegistry((handle) => {
  if (handle) { addon.Shape_destroy(handle); }
});
Shape.Tag = Object.freeze({ Empty: 0, Circle: 1, Rectangle: 2, Labeled: 3 });

The active variant is read with tag() and compared against the frozen Shape.Tag map ({ Empty: 0, Circle: 1, Rectangle: 2, Labeled: 3 }). Each variant field is a getter named <variant><Field> (circleRadius, rectangleWidth, rectangleHeight, labeledLabel, labeledCount), delegating to the matching native accessor (e.g. addon.Shape_circle_get_radius(this._handle)). Free functions that take or return the enum accept the wrapper directly: describe(shape) unwraps shape._handle, and scale(shape, factor) wraps its result back into a new Shape.

The generated types.d.ts types the wrapper as a real export class, with the Shape.Tag constants in a companion namespace:

export class Shape {
  static empty(): Shape;
  static circle(radius: number): Shape;
  static rectangle(width: number, height: number): Shape;
  static labeled(label: string, count: number): Shape;
  tag(): number;
  get circleRadius(): number;
  get rectangleWidth(): number;
  get rectangleHeight(): number;
  get labeledLabel(): string;
  get labeledCount(): number;
  destroy(): void;
}
export namespace Shape {
  const Tag: Readonly<{
    Empty: 0,
    Circle: 1,
    Rectangle: 2,
    Labeled: 3,
  }>;
}

A short round-trip that constructs a couple of variants, reads the tag and a field, calls describe / scale, then releases the handles:

const { Shape, describe, scale } = require('./index.js');

const circle = Shape.circle(2.0);
const label = Shape.labeled('unit', 3);

if (circle.tag() === Shape.Tag.Circle) {
  console.log(circle.circleRadius); // 2
}

console.log(describe(circle)); // native-rendered description
const bigger = scale(circle, 3.0); // a fresh Shape

// Done with the handles, release the native objects.
circle.destroy();
label.destroy();
bigger.destroy();

Ownership: each Shape owns its native object. Call destroy() when you are finished to free it deterministically; if you forget, the FinalizationRegistry calls the native destroy once the wrapper is garbage-collected, but GC timing isn’t guaranteed, so prefer an explicit destroy().

Build instructions

The generated addon is self-contained: run npm install (the install script runs node-gyp rebuild on the generated binding.gyp) inside generated/node/ with the generated C headers at ../c and the producer cdylib on the linker path:

cargo build -p kvstore
weaveffi generate samples/kvstore/kvstore.yml -o generated

cd generated/node
npm install          # builds build/Release/weaveffi.node
DYLD_LIBRARY_PATH=../../target/debug node -e "
  const kv = require('./index.js');
  const store = kv.Store.open('/tmp/cache.kv');
  console.log(store.count());
"

(Use LD_LIBRARY_PATH on Linux.) Then publish the generated directory as a private npm package or ship it inside your app. Copying a prebuilt platform binary in as index.node also works, and the WEAVEFFI_ADDON env var can point the loader at any built addon (the conformance/node/ consumers use it; see conformance/run.sh).

Memory and ownership

• The N-API addon is responsible for all conversions between JS values and C ABI types. Strings and byte buffers are copied into JS-managed storage, so consumers never need to think about freeing memory.
• Struct values are returned as plain JS objects: the addon copies the fields out and destroys the native struct before the call returns, so there is nothing to dispose on the JS side.
• Interface and rich-enum wrappers own their native pointer; release it with destroy() (a FinalizationRegistry backstops forgotten handles at GC time).
• Typed handles (handle<Struct>) pass through as opaque values; release them through the API’s own teardown function.
• iter<T> returns are lazy JS iterables; see Iterators. The native handle is released on exhaustion, on early exit, or by a finalizer as a backstop.
• Errors from the C ABI are converted into JavaScript Error instances by the addon, then rebranded into the typed error classes by the loader before bubbling up to the caller.

Async support

Async IDL functions are exposed as JS functions that return a Promise:

export function runTask(name: string): Promise<TaskResult>

The addon creates the promise with napi_create_promise and calls the C ABI _async entry point, which runs the work on a native producer thread. The promise is never settled from that thread: the completion callback only stashes the result (or error) and posts it through a napi_threadsafe_function whose settle callback runs on the JS event loop and calls napi_resolve_deferred / napi_reject_deferred there:

static void weaveffi_tasks_run_task_napi_cb(void* context, weaveffi_error* err, weaveffi_tasks_TaskResult* result) {
    weaveffi_tasks_run_task_napi_actx* ctx = (weaveffi_tasks_run_task_napi_actx*)context;
    if (err != NULL && err->code != 0) {
        ctx->err_code = err->code;
        ctx->err_msg = err->message ? strdup(err->message) : strdup("unknown error");
    } else {
        ctx->result = (void*)result;
    }
    napi_call_threadsafe_function(ctx->tsfn, ctx, napi_tsfn_blocking);
}

The completion callback fires exactly once, on the producer thread. Result buffers passed to it (strings, byte buffers, arrays) are borrowed for the callback’s duration, so the callback deep-copies them (note the strdup on the error message above) before returning and never frees them. Owned-object results are the exception: the callback receives ownership of the pointer (ctx->result = (void*)result above) and the settle callback wraps it into the JS-side owner.

Rejected promises carry the C error message plus a numeric code property; the loader rebrands the rejection into the module’s typed error class when the callable declares throws: true (an async method like Store.compact() rejects with KvError subclasses), and into the generic WeaveFFIError otherwise. The settle callback releases the threadsafe function once the promise is settled, so a pending async call keeps the event loop alive until it completes.

For functions marked cancellable: true the addon passes NULL for the C ABI’s cancel-token slot; the token is not surfaced to JS and there is no AbortSignal parameter. Only the C, C++, and Kotlin targets expose cancellation tokens.

Iterators

iter<T> returns are lazy: the addon hands back an opaque external wrapping the native iterator handle, and the loader wraps it in a shared WeaveFFIIterator class implementing the JS iterator protocol. Nothing is drained up front; each next() issues exactly one native _iterNext call. From the events sample’s index.js:

// Lazy iterator over a native producer: one native `next` per step.
// The native handle is released on exhaustion, by `return()` on early
// exit, or by the external's finalizer if the iterator is abandoned.
class WeaveFFIIterator {
  next() {
    if (this._done) {
      return { done: true, value: undefined };
    }
    const _v = __invoke(this._nextFn, [this._ext], this._map);
    if (_v === undefined) {
      this._done = true;
      return { done: true, value: undefined };
    }
    return { done: false, value: this._wrapElem ? this._wrapElem(_v) : _v };
  }
  return(value) {
    if (!this._done) {
      this._done = true;
      this._destroyFn(this._ext);
    }
    return { done: true, value };
  }
  [Symbol.iterator]() {
    return this;
  }
}

wv.getMessages = function () {
  const _it = __invoke(addon.getMessages, [], __generic);
  return new WeaveFFIIterator(_it, addon.getMessages_iterNext, addon.getMessages_iterDestroy, __generic, null);
};

The TypeScript declaration is IterableIterator<T>, so a plain for...of loop works and breaking out of it triggers return(), which destroys the native iterator early. The addon’s _iterNext binding pulls one element, copies it into a JS value (freeing the native string), and destroys the iterator eagerly when the producer reports exhaustion; the external’s N-API finalizer backstops abandoned iterators at GC time, nulling the stored handle so a double destroy is impossible. Struct elements are copied into plain JS objects (and the native struct destroyed) per step; rich-enum elements arrive as owned raw handles that the loader adopts into their wrapper class via the wrapElem hook.

Errors from the launcher and each next step follow the function’s error strategy: Store.listKeys (throws) rebrands a failing step through __kvErrorFrom into the typed KvError subclasses, while the non-throwing getMessages throws the generic WeaveFFIError only for producer bugs.

Callbacks and listeners

An IDL listener becomes a register/unregister pair. Registration takes a plain JS function and returns a numeric subscription id; unregistration takes that id back:

export function registerMessageListener(callback: (message: string) => void): number
export function unregisterMessageListener(id: number): void

The id is the uint64 returned by the C ABI’s weaveffi_events_register_message_listener(callback_fn, context); each registration gets its own id and threadsafe function.

The native callback fires on the producer’s thread, and the addon never calls into JS from there. Registration wraps the JS function in a napi_threadsafe_function, and a C trampoline copies the payload and queues it onto the JS event loop:

static void weaveffi_events_OnMessage_fn_napi_tramp(const char* message, void* context) {
    weaveffi_napi_listener_ctx* ctx = (weaveffi_napi_listener_ctx*)context;
    weaveffi_events_OnMessage_fn_payload* p = (weaveffi_events_OnMessage_fn_payload*)calloc(1, sizeof(weaveffi_events_OnMessage_fn_payload));
    p->message = message ? strdup(message) : NULL;
    napi_call_threadsafe_function(ctx->tsfn, p, napi_tsfn_nonblocking);
}

The threadsafe function is unref’d immediately after registration:

napi_create_threadsafe_function(env, args[0], NULL, resource_name, 0, 1, NULL, NULL, NULL, weaveffi_events_OnMessage_fn_napi_calljs, &ctx->tsfn);
napi_unref_threadsafe_function(env, ctx->tsfn);
uint64_t id = weaveffi_events_register_message_listener(weaveffi_events_OnMessage_fn_napi_tramp, ctx);

Threading caveats:

• The JS callback always runs on the JS thread; delivery is asynchronous and the producer does not wait for it (napi_tsfn_nonblocking).
• Because the threadsafe function is unref’d, a registered listener does not keep the process alive; the loop may exit with listeners still registered.
• Unregistering calls the C ABI unregister, releases the threadsafe function, and frees the listener context.

Troubleshooting

• Error: Cannot find module './index.node': no addon binary was found at either loader path. Run npm install in generated/node/ to build the generated addon with node-gyp, or copy a prebuilt binary in as index.node.
• dlopen: ... image not found: the addon links against the Rust cdylib at runtime; set DYLD_LIBRARY_PATH / LD_LIBRARY_PATH or copy the cdylib next to index.node.
• BigInt errors with handle: handles are 64-bit; pass them as bigint, not number.
• TypeScript complains about missing types: point tsconfig’s paths at generated/node/types.d.ts or include the generated package in compilerOptions.types.

Swift

Overview

The Swift target emits a SwiftPM System Library (CWeaveFFI) that references the generated C header via a module.modulemap, plus a thin Swift module (WeaveFFI) that wraps the C ABI in idiomatic Swift with throws-based error handling and Swift-native types.

What gets generated

The module name shown above (WeaveFFI) is the default. It is overridden by [swift] module_name or, failing that, by the IDL package: name PascalCased (async-demo → AsyncDemo). The Swift wrapper, its Sources/<Module>/ directory, the system-library target, and its Sources/C<Module>/ module map all move together (e.g. AsyncDemo + CAsyncDemo), so the generated package stays buildable under any name.

Type mapping

Example IDL → generated code

version: "0.5.0"
modules:
  - name: contacts
    enums:
      - name: ContactType
        variants:
          - { name: Personal, value: 0 }
          - { name: Work, value: 1 }
          - { name: Other, value: 2 }

    structs:
      - name: Contact
        fields:
          - { name: name, type: string }
          - { name: email, type: "string?" }
          - { name: age, type: i32 }

    errors:
      name: ContactsError
      codes:
        - { name: InvalidName, code: 1, message: "name must not be empty" }
        - { name: NotFound, code: 2, message: "contact not found" }

    functions:
      - name: create_contact
        params:
          - { name: name, type: string }
          - { name: age, type: i32 }
        return: Contact
        throws: true

      - name: find_contact
        params:
          - { name: id, type: i32 }
        return: "Contact?"
        throws: true

      - name: list_contacts
        params: []
        return: "[Contact]"

      - name: set_type
        params:
          - { name: id, type: i32 }
          - { name: contact_type, type: ContactType }

Enums become Swift enums with lowerCamelCase cases backed by UInt32:

public enum ContactType: UInt32 {
    case personal = 0
    case work = 1
    case other = 2
}

Structs are wrapper classes around an OpaquePointer. The deinit calls the C destructor; computed properties call the C getters:

public class Contact {
    let ptr: OpaquePointer
    init(ptr: OpaquePointer) { self.ptr = ptr }
    deinit { weaveffi_contacts_Contact_destroy(ptr) }

    public var name: String {
        let raw = weaveffi_contacts_Contact_get_name(ptr)
        guard let raw = raw else { return "" }
        defer { weaveffi_free_string(raw) }
        return String(cString: raw)
    }
}

Module functions live as static methods on a namespace enum in lowerCamelCase with real argument labels; the module prefix is stripped by default (strip_module_prefix = false in [swift] restores it), since the namespace enum already scopes the name. A function with throws: true becomes a Swift throws function delivering the typed domain error. String parameters are passed as NUL-terminated C strings via withCString:

public enum Contacts {
    public static func createContact(name: String, age: Int32) throws -> Contact {
        var err = weaveffi_error(code: 0, message: nil)
        let result: OpaquePointer? = name.withCString { name_ptr in
                return weaveffi_contacts_create_contact(name_ptr, age, &err)
        }
        try checkContacts(&err)
        guard let result = result else { throw WeaveFFIError.error(code: -1, message: "null pointer") }
        return Contact(ptr: result)
    }
}

Call it as try Contacts.createContact(name: "Grace", age: 46). A function without throws keeps a plain non-throwing signature; its only possible failures are producer bugs, which trap via fatalError. Nested IDL modules become nested namespace enums (Kv.Stats.getStats(store:) in the kvstore sample).

Optionals and lists use withOptionalPointer, withOptionalCString, and withUnsafeBufferPointer helpers:

@inline(__always)
func withOptionalPointer<T, R>(to value: T?, _ body: (UnsafePointer<T>?) throws -> R) rethrows -> R {
    guard let value = value else { return try body(nil) }
    return try withUnsafePointer(to: value) { try body($0) }
}

ids.withUnsafeBufferPointer { buf in
    let ids_ptr = buf.baseAddress
    let ids_len = buf.count
}

Typed errors

A module’s error domain becomes a Swift error enum conforming to Error and LocalizedError, with one lowerCamelCase case per declared code, each carrying its message. From the kvstore sample’s KvError:

/// Typed errors reported by the `kv` module.
public enum KvError: Error, LocalizedError {
    case keyNotFound(message: String)
    case expired(message: String)
    case storeFull(message: String)
    case ioError(message: String)

    /// The numeric ABI code carried by this error.
    public var errorCode: Int32 {
        switch self {
        case .keyNotFound: return 1001
        case .expired: return 1002
        case .storeFull: return 1003
        case .ioError: return 1004
        }
    }
}

Callables with throws: true route failures through a per-domain checker (checkKv) that maps the ABI code to the matching case, falling back to the generic WeaveFFIError.error(code:message:) for codes the domain doesn’t declare (a producer panic, for example):

do {
    let entry = try store.get(key: "alpha")
} catch KvError.keyNotFound {
    print("no such key")
} catch let e as KvError {
    print("kv failure \(e.errorCode)")
}

Callables without throws have plain, non-throwing signatures. They still check the error slot after the call, but a non-zero code there can only be a producer bug, so it traps with fatalError("\(code): \(message)") instead of throwing.

Interfaces

An interfaces: entry becomes a final class owning an OpaquePointer, with deinit calling the implicit C destructor. A constructor named new becomes init; any other constructor becomes a throwing static factory. Methods are instance methods and statics are static methods, all in lowerCamelCase with argument labels. From the kvstore sample’s Store (trimmed):

/// An embedded key-value store owning its entries
public final class Store {
    let ptr: OpaquePointer

    deinit {
        weaveffi_kv_Store_destroy(ptr)
    }

    /// Open (or create) a store backed by the given filesystem path
    public static func open(path: String) throws -> Store {
        var err = weaveffi_error(code: 0, message: nil)
        let result: OpaquePointer? = path.withCString { path_ptr in
                return weaveffi_kv_Store_open(path_ptr, &err)
        }
        try checkKv(&err)
        guard let result = result else { throw WeaveFFIError.error(code: -1, message: "null pointer") }
        return Store(ptr: result)
    }

    /// Remove the entry for the given key, returning true if it existed
    public func delete(key: String) throws -> Bool

    /// Return the number of live entries in the store
    public func count() -> Int64          // no throws: traps on producer bugs

    /// Stream every key, optionally filtered by a prefix
    public func listKeys(prefix: String?) throws -> KvStoreListKeysIterator

    /// Reclaim space asynchronously; returns the number of bytes reclaimed
    public func compact() async throws -> Int64

    /// Legacy single-shot put kept for compatibility
    @available(*, deprecated, message: "use put() with explicit kind")
    public func legacyPut(key: String, value: Data) throws -> Bool

    /// The largest number of live entries one store will hold
    public static func defaultCapacity() -> Int64
}

let store = try Store.open(path: "/tmp/cache.kv")
_ = try store.put(key: "alpha", value: Data("1".utf8), kind: .volatile, ttlSeconds: nil)
print(store.count())
let reclaimed = try await store.compact()

The contacts sample’s ContactBook declares a constructor named new, which surfaces as a real initializer: let book = ContactBook(). ARC releases the underlying object when the last reference goes away; there’s no manual close. An interface parameter is borrowed for the call (the wrapper passes its pointer); an interface return wraps the owned pointer in a new instance.

Rich (algebraic) enums

An enum whose variants declare fields is a rich (algebraic) enum, a sum type with associated data. Plain C-style enums stay Swift enums backed by UInt32; a rich enum instead becomes a wrapper class around an OpaquePointer (same ownership model as a struct class) with a nested Tag, throwing static factories, and per-variant computed properties. From the shapes sample:

public class Shape {
    let ptr: OpaquePointer
    deinit { weaveffi_shapes_Shape_destroy(ptr) }

    public enum Tag: Int32 {
        case empty = 0
        case circle = 1
        case rectangle = 2
        case labeled = 3
    }
    public var tag: Tag { Tag(rawValue: weaveffi_shapes_Shape_tag(ptr))! }

    public static func empty() throws -> Shape
    public static func circle(radius: Double) throws -> Shape
    public static func rectangle(width: Float, height: Float) throws -> Shape
    public static func labeled(label: String, count: UInt8) throws -> Shape

    public var circleRadius: Double { get }
    public var rectangleWidth: Float { get }
    public var rectangleHeight: Float { get }
    public var labeledLabel: String { get }
    public var labeledCount: UInt8 { get }
}

Build a variant with its throwing factory, switch on tag, and read only the matching property. Module functions live on the Shapes namespace enum and take/return the wrapper:

let shape = try Shape.circle(radius: 2.0)

if shape.tag == .circle {
    print("radius = \(shape.circleRadius)")
}

print(Shapes.describe(shape: shape))
let bigger = Shapes.scale(shape: shape, factor: 3.0)

Ownership matches struct classes: the Shape deinit calls weaveffi_shapes_Shape_destroy, so ARC frees the handle when the last reference goes away, no manual free required.

Build instructions

Build the producer cdylib, generate the bindings, and compile your program against the generated Swift module (the contacts sample shown; its module resolves to Contacts + CContacts from the package name):

cargo build -p contacts
weaveffi generate samples/contacts/contacts.yml -o generated

swiftc \
  -I generated/swift/Sources/CContacts \
  -L target/debug -lcontacts \
  -Xlinker -rpath -Xlinker target/debug \
  generated/swift/Sources/Contacts/Contacts.swift main.swift -o app

DYLD_LIBRARY_PATH=target/debug ./app   # LD_LIBRARY_PATH on Linux

In a real SwiftPM application, add the generated package as a path dependency, link the system-library and wrapper targets, and ship the cdylib as part of an XCFramework or bundled .dylib/.so. The conformance/swift/ consumers show a complete SwiftPM assembly for every sample (see conformance/run.sh).

Memory and ownership

• Struct and interface classes own an OpaquePointer. The class deinit calls the matching C destructor.
• Returned strings are copied into Swift String and the raw pointer is freed via weaveffi_free_string immediately.
• withUnsafeBufferPointer and withOptionalPointer keep input buffers alive only for the duration of the C call; there’s no copy.
• For bytes parameters, the wrapper copies the Data into a [UInt8] array and passes it via withUnsafeBufferPointer; returned bytes are copied into Data and the Rust buffer is freed with weaveffi_free_bytes.
• Returned optional scalars arrive boxed behind a pointer; the wrapper dereferences the value and frees the box with the wvFreeBox helper. Returned arrays and maps free each string element individually, then release the buffer(s) with wvFreeArray; both helpers call weaveffi_free_bytes.

Async support

Async IDL functions (async: true) are exposed as async throws methods that bridge the C ABI completion callback into Swift structured concurrency via withCheckedThrowingContinuation. The continuation is boxed in a ContinuationRef, retained with Unmanaged.passRetained, and released exactly once, by takeRetainedValue() inside the C completion callback. From the async-demo sample:

private final class ContinuationRef<T, E: Error> {
    let value: CheckedContinuation<T, E>
    init(_ value: CheckedContinuation<T, E>) { self.value = value }
}

public static func runTask(name: String) async throws -> TaskResult {
    try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<TaskResult, Error>) in
        let ctx = Unmanaged.passRetained(ContinuationRef(continuation)).toOpaque()
        name.withCString { name_ptr in
            weaveffi_tasks_run_task_async(name_ptr, { context, err, result in
                let contRef = Unmanaged<ContinuationRef<TaskResult, Error>>.fromOpaque(context!).takeRetainedValue()
                if let err = err, err.pointee.code != 0 {
                    let code = err.pointee.code
                    let msg = err.pointee.message.flatMap { String(cString: $0) } ?? ""
                    contRef.value.resume(throwing: mapTasks(code: code, message: msg))
                } else {
                    guard let result = result else {
                        contRef.value.resume(throwing: WeaveFFIError.error(code: -1, message: "null pointer"))
                        return
                    }
                    contRef.value.resume(returning: TaskResult(ptr: result))
                }
            }, ctx)
        }
    }
}

The completion callback fires exactly once, on an arbitrary producer thread, and the continuation is resumed exactly once from inside it. Result buffers passed to the callback (strings, bytes, arrays) are borrowed from the producer for the callback’s duration: the wrapper copies them (for example String(cString:) on the error message) before the callback returns and never frees them. Owned-object results are the exception: run_task returns a struct, so the callback adopts the pointer into a new TaskResult, whose deinit eventually frees it.

run_task declares throws: true, so the continuation rejects with the typed TaskError (via mapTasks). An async callable without throws is async but not throws: it uses a plain withCheckedContinuation whose failure type is Never, and a producer bug traps instead.

For callables marked cancellable: true, the C ABI takes an extra weaveffi_cancel_token* parameter. The Swift wrapper passes nil for that slot; cancellation isn’t surfaced in Swift, and Swift Task cancellation doesn’t propagate to the native operation (from the kvstore sample’s Store.compact):

weaveffi_kv_Store_compact_async(ptr, nil, { context, err, result in

Callbacks and listeners

IDL callbacks paired with listeners produce a register/unregister pair. From the events sample:

modules:
  - name: events
    callbacks:
      - name: OnMessage
        params:
          - { name: message, type: string }
    listeners:
      - name: message_listener
        event_callback: OnMessage

Registration is a static method on the module’s namespace enum: it takes a plain Swift closure and returns a UInt64 subscription id; pass that id back to unregister. The closure is boxed (WvCallbackBox), retained with Unmanaged.passRetained, and handed to the C ABI as the void* context of a C trampoline. The context pointer is kept in a global wvListenerContexts dictionary keyed by subscription id and guarded by an NSLock (wvListenerLock); unregistering removes the entry and releases the box:

public static func registerMessageListener(_ callback: @escaping (String) -> Void) -> UInt64 {
    let box = WvCallbackBox(callback)
    let ctx = Unmanaged.passRetained(box).toOpaque()
    let id = weaveffi_events_register_message_listener({ message, context in
        let cb = Unmanaged<WvCallbackBox<(String) -> Void>>.fromOpaque(context!).takeUnretainedValue().value
        cb(String(cString: message!))
    }, ctx)
    wvListenerLock.lock()
    wvListenerContexts[id] = ctx
    wvListenerLock.unlock()
    return id
}

public static func unregisterMessageListener(_ id: UInt64) {
    weaveffi_events_unregister_message_listener(id)
    wvListenerLock.lock()
    let ctx = wvListenerContexts.removeValue(forKey: id)
    wvListenerLock.unlock()
    if let ctx = ctx {
        Unmanaged<WvCallbackBox<(String) -> Void>>.fromOpaque(ctx).release()
    }
}

The callback runs on the producer’s thread, whichever thread the native side fires the event from. For UI work, hop to the main thread yourself (e.g. DispatchQueue.main.async or await MainActor.run).

Iterators

iter<T> returns are lazy: the wrapper returns a generated final class conforming to Sequence and IteratorProtocol that wraps the opaque C iterator handle. Nothing is drained up front; each next() call pulls exactly one element from the producer, copies it into Swift memory, and frees the element’s native allocation (strings via weaveffi_free_string). From the events sample (get_messages returns iter<string> and doesn’t declare throws, so the wrapper is non-throwing and traps on producer bugs):

/// A lazy sequence over the `String` elements streamed by `weaveffi_events_get_messages`.
///
/// Each `next()` call pulls exactly one element from the producer. The
/// underlying C iterator is destroyed eagerly on exhaustion and from
/// `deinit` when iteration is abandoned early.
public final class EventsGetMessagesIterator: Sequence, IteratorProtocol {
    private var handle: OpaquePointer?

    deinit {
        destroyHandle()
    }

    /// Pulls the next element from the producer, or returns `nil` once the
    /// stream is exhausted (destroying the underlying iterator).
    public func next() -> String? {
        guard let handle = handle else { return nil }
        var item: UnsafePointer<CChar>? = nil
        var err = weaveffi_error(code: 0, message: nil)
        if weaveffi_events_GetMessagesIterator_next(handle, &item, &err) == 0 {
            // ... a non-zero code is a producer bug: fatalError ...
            destroyHandle()
            return nil
        }
        let element = String(cString: item!)
        weaveffi_free_string(item)
        return element
    }
}

public static func getMessages() -> EventsGetMessagesIterator {
    var err = weaveffi_error(code: 0, message: nil)
    let iter = weaveffi_events_get_messages(&err)
    trap(&err)
    guard let iter = iter else { fatalError("-1: null iterator") }
    return EventsGetMessagesIterator(handle: iter)
}

The handle is destroyed exactly once: eagerly when next() reports exhaustion, or from deinit when the sequence is abandoned early (destroyHandle nulls the stored handle, so a double destroy is impossible). Since the class conforms to Sequence, callers just write for message in Events.getMessages() { ... }; the sequence is single-pass.

A throwing iterator function like the kvstore sample’s Store.listKeys(prefix:) declares throws and routes a launch failure through the typed checker (checkKv). Swift’s IteratorProtocol.next() can’t throw, so a mid-stream error can’t surface on the step that failed; instead it ends iteration and is stored in the sequence’s public error property for the caller to inspect after the loop:

/// If the producer reports an error mid-stream, iteration ends and the
/// error is stored in ``error`` for the caller to inspect after the loop.
public final class KvStoreListKeysIterator: Sequence, IteratorProtocol {
    /// The error that ended iteration early, if any.
    public private(set) var error: Error?
    // ... same handle lifecycle as above; a failing next() maps the
    // code through mapKv, stores it in `error`, and returns nil ...
}

let keys = try store.listKeys(prefix: nil)
for key in keys { print(key) }
if let error = keys.error { throw error }

Troubleshooting

• module 'CWeaveFFI' not found: Xcode/SwiftPM didn’t pick up the generated module.modulemap. Make sure Sources/CWeaveFFI/module.modulemap is on disk and the package declares systemLibrary(name: "CWeaveFFI").
• Library not loaded: libweaveffi.dylib: set DYLD_LIBRARY_PATH for development or embed the dylib in your application bundle for distribution.
• Crashes after deinit: never reuse an OpaquePointer after the owning Swift wrapper goes out of scope. The C side has already freed it.
• Optional struct ends up nil even when present: the C function is allowed to return a null pointer to indicate absence; double-check the Rust implementation actually returns Some(_) for the case you expect.

Wasm

Overview

The Wasm target produces a typed ES module loader for wasm32-unknown-unknown builds of WeaveFFI cdylibs. The loader wraps the raw exports in idiomatic JavaScript: per-module namespaces, struct wrapper classes with getters, thrown Errors instead of error slots, Promise-based async functions, and automatic string/bytes staging in linear memory. TypeScript declarations describe the whole surface.

C and C++ producers compiled with Emscripten are supported through a dedicated loader variant; see Emscripten mode.

Callbacks and listeners are supported with synchronous, same-thread delivery: a wasm32-unknown-unknown module is single-threaded, so events fire only while a call into the module is on the stack; see Callbacks and listeners.

What gets generated

Type mapping

Example IDL → generated code

The loader exports a single async entry point that fetches, instantiates, and wraps a .wasm module:

import { loadWeaveffiWasm } from './weaveffi_wasm.js';

const api = await loadWeaveffiWasm('/your_library.wasm');

Functions are grouped by IDL module in lowerCamelCase (nested IDL modules nest namespaces, e.g. api.kv.stats) and have idiomatic signatures; strings, arrays, and error handling are taken care of inside the wrapper:

api.events.sendMessage('hello');            // throws WeaveFFIError on failure
for (const m of api.events.getMessages()) { // iter<string> -> lazy iterable
  console.log(m);
}

Structs come back as wrapper classes holding the native handle, with a getter per field and a static create when the struct has a constructor:

const result = await api.tasks.runTask('build');
console.log(result.id, result.value, result.success);

The raw exports stay reachable for anything not covered by the typed surface:

api._raw.weaveffi_alloc(16);

The generated weaveffi_wasm.d.ts mirrors all of this for TypeScript consumers:

export interface WeaveffiWasmModule {
  _raw: WebAssembly.Exports;
  events: {
    sendMessage(text: string): void;
    getMessages(): IterableIterator<string>;
  };
}

export function loadWeaveffiWasm(url: string): Promise<WeaveffiWasmModule>;

Typed errors

The module exports WeaveFFIError (extending Error with a numeric code). A module’s error domain adds an exported base class named after the domain plus one exported class per code, each carrying its stable CODE and reachable both flat and via the domain class. From the kvstore sample:

export class WeaveFFIError extends Error {
  constructor(code, message) {
    super(message ? `WeaveFFI error ${code}: ${message}` : `WeaveFFI error ${code}`);
    this.name = new.target.name;
    this.code = code;
  }
}

/** Base error for the `kv` module's error domain. */
export class KvError extends WeaveFFIError {}

// key not found
export class KeyNotFound extends KvError {
  constructor(message = "key not found") {
    super(1001, message);
  }
}
KeyNotFound.CODE = 1001;
KvError.KeyNotFound = KeyNotFound;
// Expired, StoreFull, IoError follow the same shape.

A callable with throws: true checks the error slot through the domain’s mapper (_kvErrorFrom), so a failure arrives as the matching subclass (KeyNotFound), the domain (KvError), or, for codes outside the domain, the generic WeaveFFIError. A callable without throws uses the generic checker only; a failure there can only be a producer bug and throws WeaveFFIError.

Interfaces

An interfaces: entry becomes a class exposed on its module’s namespace (api.kv.Store). Constructors are static factories, methods are camelCased instance methods, statics are static methods, and free() releases the native object (there’s no FinalizationRegistry on this target). From the kvstore sample (trimmed):

// An embedded key-value store owning its entries
class Store {
  free() {
    if (this._handle !== 0) {
      wasm.weaveffi_kv_Store_destroy(this._handle);
      this._handle = 0;
    }
  }
  static open(path) {
    const [a0_p, a0_s] = _cstr(wasm, path);
    const _err = _allocErr(wasm);
    const _r = wasm.weaveffi_kv_Store_open(a0_p, _err);
    wasm.weaveffi_dealloc(a0_p, a0_s);
    _checkKvError(wasm, _err);
    _freeErr(wasm, _err);
    return Store._wrap(_r);
  }
  delete(key) { /* throws typed KvError subclasses */ }
  count() { /* generic check only (no throws) */ }
  compact() {
    return new Promise((resolve, reject) => {
      const ctxId = _nextCtxId++;
      _asyncContexts.set(ctxId, { resolve, reject, mkErr: _kvErrorFrom });
      wasm.weaveffi_kv_Store_compact_async(this._handle, 0, _cbPtr_i32_i32_i64, ctxId);
    });
  }
  /** @deprecated use put() with explicit kind */
  legacyPut(key, value) { /* ... */ }
  static defaultCapacity() { /* ... */ }
}

const store = api.kv.Store.open('/tmp/cache.kv');
store.put('alpha', new Uint8Array([1]), api.kv.EntryKind.Volatile, null);
console.log(store.count());
store.free();

An interface parameter accepts the wrapper and reads _handle (api.kv.stats.getStats(store)); an interface return wraps the owned pointer in a fresh instance. Call free() when done; otherwise the allocation lives until the module instance is dropped.

Rich (algebraic) enums

A rich (algebraic) enum is a sum type whose variants carry associated data. A plain C-style enum stays an i32 discriminant (surfaced as a number plus a frozen constants object), but a rich enum lowers to an opaque object handle, an i32 pointer into linear memory, exactly like a struct wrapper. The loader wraps it in a Shape class that owns that handle for the lifetime of the module instance.

For a Shape enum with variants Empty, Circle { radius: f64 }, Rectangle { width: f32, height: f32 }, and Labeled { label: string, count: u8 }, the generated Shape class has one static factory per variant, a tag getter, a getter per variant field, and an explicit free() (there is no FinalizationRegistry on this target):

class Shape {
  constructor(wasm, handle) {
    this._wasm = wasm;
    this._handle = handle;
  }
  get tag() {
    const wasm = this._wasm;
    const _r = wasm.weaveffi_shapes_Shape_tag(this._handle);
    return _r;
  }
  static empty(wasm) {
    const _err = _allocErr(wasm);
    const _r = wasm.weaveffi_shapes_Shape_Empty_new(_err);
    _checkErr(wasm, _err);
    _freeErr(wasm, _err);
    return new Shape(wasm, _r);
  }
  static circle(wasm, radius) {
    const _err = _allocErr(wasm);
    const _r = wasm.weaveffi_shapes_Shape_Circle_new(radius, _err);
    _checkErr(wasm, _err);
    _freeErr(wasm, _err);
    return new Shape(wasm, _r);
  }
  // ... rectangle(wasm, width, height), labeled(wasm, label, count) ...
  get circleRadius() {
    const wasm = this._wasm;
    const _r = wasm.weaveffi_shapes_Shape_Circle_get_radius(this._handle);
    return _r;
  }
  get labeledLabel() {
    const wasm = this._wasm;
    const _r = wasm.weaveffi_shapes_Shape_Labeled_get_label(this._handle);
    return _takeCStr(wasm, _r);
  }
  // ... rectangleWidth, rectangleHeight, labeledCount ...
  free() {
    if (this._handle !== 0) {
      this._wasm.weaveffi_shapes_Shape_destroy(this._handle);
      this._handle = 0;
    }
  }
}
Shape.Tag = Object.freeze({
  Empty: 0,
  Circle: 1,
  Rectangle: 2,
  Labeled: 3,
});

The wasm instance is bound for you by the loader, so on the returned API the factories take only their declared arguments. Under api.shapes.Shape you get empty(), circle(radius), rectangle(width, height), labeled(label, count), plus the frozen Tag map:

shapes: {
  // ...
  Shape: {
    empty: (...args) => Shape.empty(wasm, ...args),
    circle: (...args) => Shape.circle(wasm, ...args),
    rectangle: (...args) => Shape.rectangle(wasm, ...args),
    labeled: (...args) => Shape.labeled(wasm, ...args),
    Tag: Shape.Tag,
  },
},

The active variant is read through the tag getter (no call parentheses) and compared against api.shapes.Shape.Tag. Each variant field is a camelCased getter: circleRadius, rectangleWidth, rectangleHeight, labeledLabel, labeledCount. Functions that take or return the enum pass the wrapper directly: describe(shape) reads shape._handle, and scale(shape, factor) returns a fresh Shape.

The generated weaveffi_wasm.d.ts types the wrapper as an export declare class:

export declare class Shape {
  get tag(): number;
  static readonly Tag: Readonly<{
    Empty: 0;
    Circle: 1;
    Rectangle: 2;
    Labeled: 3;
  }>;
  static empty(): Shape;
  static circle(radius: number): Shape;
  static rectangle(width: number, height: number): Shape;
  static labeled(label: string, count: number): Shape;
  get circleRadius(): number;
  get rectangleWidth(): number;
  get rectangleHeight(): number;
  get labeledLabel(): string;
  get labeledCount(): number;
  free(): void;
}

A short round-trip that constructs a couple of variants, reads the tag and a field, calls describe / scale, then frees the handles:

const api = await loadWeaveffiWasm('/shapes.wasm');

const circle = api.shapes.Shape.circle(2.0);
const label = api.shapes.Shape.labeled('unit', 3);

if (circle.tag === api.shapes.Shape.Tag.Circle) {
  console.log(circle.circleRadius); // 2
}

console.log(api.shapes.describe(circle)); // native-rendered description
const bigger = api.shapes.scale(circle, 3.0); // a fresh Shape

// No FinalizationRegistry on this target. Free handles yourself.
circle.free();
label.free();
bigger.free();

Ownership: a Shape owns its native object. JavaScript has no deterministic destructors here, so call free() when you are done; otherwise the allocation lives until the module instance is dropped.

Async support

Async IDL functions return real Promises. The loader grows the module’s __indirect_function_table and registers one JavaScript trampoline per completion-callback signature using the JS Type Reflection API (new WebAssembly.Function(...)); each call stores its resolve/reject pair in a context map keyed by an integer id:

runTask(name) {
  return new Promise((resolve, reject) => {
    const ctxId = _nextCtxId++;
    _asyncContexts.set(ctxId, { resolve, reject, mkErr: _taskErrorFrom, unwrap: (w, h) => new TaskResult(w, h) });
    const [a0_p, a0_s] = _cstr(wasm, name);
    wasm.weaveffi_tasks_run_task_async(a0_p, _cbPtr_i32_i32_i32, ctxId);
    wasm.weaveffi_dealloc(a0_p, a0_s);
  });
}

When the producer invokes the completion callback, the trampoline looks up the context, settles the promise, and removes the entry. A callable with throws: true stores the module’s typed error mapper in the context (mkErr), so the rejection carries the domain error; a non-throwing async callable rejects with the generic WeaveFFIError only when the producer has a bug.

Two caveats apply:

• WebAssembly.Function requires a runtime with JS Type Reflection (recent V8/SpiderMonkey; Chrome, Firefox, Node 16+, Deno).
• The module is single-threaded: the producer must complete the callback on the calling thread (e.g. an executor polled by the same thread). A producer that spawns OS threads will not work on wasm32-unknown-unknown.

A cancellable function’s ABI symbol takes a weaveffi_cancel_token* parameter; the loader passes a null token, so cancellation isn’t surfaced on this target (Store.compact() runs to completion). An IDL function that models cancellation itself is exposed as a plain function in the same namespace (e.g. api.tasks.cancelTask(id)).

Iterators

iter<T> returns are lazy: the wrapper launches the producer iterator and hands back a shared _WeaveFFIIterator implementing the JS iterator protocol over the iterator handle. Nothing is drained; each next() issues exactly one producer next call through a per-element slot staged in linear memory. From the events sample:

getMessages() {
  const _err = _allocErr(wasm);
  const _it = wasm.weaveffi_events_get_messages(_err);
  _checkErr(wasm, _err);
  _freeErr(wasm, _err);
  return new _WeaveFFIIterator(wasm, _it, 4,
    (it, slot, ep) => wasm.weaveffi_events_GetMessagesIterator_next(it, slot, ep),
    (it) => wasm.weaveffi_events_GetMessagesIterator_destroy(it),
    _checkErr, (w, p) => _takeCStr(w, new DataView(w.memory.buffer).getUint32(p, true)));
}

The class settles the handle’s lifecycle exactly once: _close() destroys the producer iterator, frees the element slot, and nulls the handle. It runs eagerly on exhaustion, on a next error, or from return() when iteration stops early; a for...of loop calls return() automatically on break or throw. There is no reliable finalization hook across the runtimes this loader supports, so abandoning an iterator without exhausting or closing it leaks the producer handle.

Each decoded element is copied out of linear memory and its producer allocation released (_takeCStr frees strings via weaveffi_free_string). Errors from the launcher and from each next follow the function’s error strategy: a throwing function such as the kvstore sample’s Store.listKeys checks each step with the domain checker and throws the typed KvError subclasses; a non-throwing one like getMessages throws the generic WeaveFFIError only for producer bugs. The TypeScript declaration is IterableIterator<T>.

Callbacks and listeners

Each listener surfaces on its module namespace as a register.../unregister... pair. register takes a plain JavaScript function and returns a numeric subscription id; unregister takes that id and stops delivery. From the events sample:

const received = [];
const sub = api.events.registerMessageListener((message) => received.push(message));

api.events.sendMessage('alpha'); // emit_message_listener fires synchronously
console.log(received);           // ['alpha']

api.events.unregisterMessageListener(sub);

Under the hood the loader reuses the async machinery: it installs one long-lived trampoline per callback typedef in the module’s __indirect_function_table (via WebAssembly.Function, the same JS Type Reflection API dependency async functions have) and hands the trampoline’s table index plus a per-subscription context id to the producer’s register_* symbol. When the producer’s emit_* helper fires, the trampoline looks up the subscription by context id, decodes each argument, and invokes the JavaScript callback:

let _nextLsnId = 1;
const _listeners = new Map();

const _lsnPtr_weaveffi_events_OnMessage_fn = _registerTrampoline(_table, ['i32', 'i32'], (a0, _ctx) => {
  const _l = _listeners.get(_ctx);
  if (_l === undefined) return;
  const _p0 = _readCStr(wasm, a0);
  _l.callback(_p0);
});

// On the module object:
registerMessageListener(callback) {
  const _id = _nextLsnId++;
  const _rid = wasm.weaveffi_events_register_message_listener(_lsnPtr_weaveffi_events_OnMessage_fn, _id);
  _listeners.set(_id, { callback, rid: _rid });
  return _id;
},
unregisterMessageListener(id) {
  const _l = _listeners.get(id);
  if (_l === undefined) return;
  _listeners.delete(id);
  wasm.weaveffi_events_unregister_message_listener(_l.rid);
},

One trampoline serves every subscription to callbacks of the same typedef (the context id disambiguates), so register/unregister churn never grows the function table. The producer’s uint64_t subscription id stays internal to the loader; the public surface deals only in plain numbers.

Two semantic points to keep in mind:

• Delivery is synchronous and same-thread. The target is single-threaded, so emit_* can only run while a call into the module is on the stack, and your callback runs before that call returns. This is not a limitation of the bindings: a producer that emits from a spawned thread cannot run on wasm32-unknown-unknown at all (std::thread::spawn fails there).
• Callback arguments are borrowed. The producer owns every argument for the duration of the dispatch. Strings and byte buffers are copied into JavaScript values before your callback runs, but struct, rich-enum, and interface arguments wrap producer-owned memory: read what you need inside the callback and do not retain the wrapper or call free() on it.

In Emscripten mode callbacks and listeners are not supported; each register/unregister entry point becomes an explicit throwing stub and is omitted from the TypeScript declarations, exactly like async functions in that mode.

Emscripten mode

The default loader fetches a bare .wasm and calls WebAssembly.instantiate with an empty import object, which only works for wasm32-unknown-unknown builds. A C or C++ library compiled with Emscripten needs its own JS runtime, its own import object, and exposes exports as Module['_name'] rather than instance.exports.name. Set emscripten to generate a loader for that layout:

# weaveffi.toml
[wasm]
emscripten = true

or inline in the IDL:

generators:
  wasm:
    emscripten: true

Instead of a URL, the loader accepts the initialized Emscripten module, or the promise returned by its MODULARIZE factory. You construct the module yourself, so options like locateFile stay under your control:

import Module from './your_library.js';
import { loadWeaveffiWasm } from './weaveffi_wasm.js';

const api = await loadWeaveffiWasm(Module({ locateFile: (p) => 'build/' + p }));

Internally the loader binds the module’s underscore-prefixed exports to the symbol names the glue calls, once, up front:

const wasm = {
  // Emscripten replaces HEAPU8 when linear memory grows, so the
  // buffer is re-read on every access instead of captured once.
  get memory() { return { buffer: m['HEAPU8'].buffer }; },
  weaveffi_alloc: m['_weaveffi_alloc'],
  weaveffi_dealloc: m['_weaveffi_dealloc'],
  weaveffi_math_add: m['_weaveffi_math_add'],
  // ...
};

Everything after that prologue is identical to the standard loader. The quoted bracket access on the Emscripten module is deliberate: it survives Closure Compiler’s advanced property renaming, while the rest of the glue keeps consistent dot access on this locally constructed object, which Closure can rename safely.

Building the producer

The generated header tags every export with {PREFIX}_API, which expands to __attribute__((used, visibility("default"))) under Emscripten (the same expansion as EMSCRIPTEN_KEEPALIVE), so the symbols survive dead-code elimination without an -sEXPORTED_FUNCTIONS list. The glue stages arguments through weaveffi_alloc / weaveffi_dealloc; the generated weaveffi.c provides malloc/free- backed defaults, so compile it into your library or export your own implementations. A typical build:

emcc your_library.c generated/c/weaveffi.c -Igenerated/c \
  -o your_library.js \
  -sMODULARIZE=1 -sEXPORT_ES6=1 \
  -sEXPORTED_RUNTIME_METHODS=HEAPU8 \
  -sALLOW_MEMORY_GROWTH=1

-sEXPORTED_RUNTIME_METHODS=HEAPU8 is required: the glue reads and writes linear memory through Module['HEAPU8'].

Limitations

Async functions, callbacks, and listeners are not supported in Emscripten mode. The trampoline registration in the standard loader relies on WebAssembly.Function and a growable __indirect_function_table, neither of which an Emscripten module exposes portably. Each async, register, and unregister entry point becomes an explicit stub that throws at call time and is omitted from the TypeScript declarations.

Build instructions

macOS / Linux / Windows (cross-compilation, all hosts):

rustup target add wasm32-unknown-unknown
cargo build --target wasm32-unknown-unknown --release -p your_library

The resulting .wasm is in target/wasm32-unknown-unknown/release/. Serve it over HTTP and load it with the generated helper:

<script type="module">
  import { loadWeaveffiWasm } from './weaveffi_wasm.js';
  const api = await loadWeaveffiWasm('/your_library.wasm');
</script>

Memory and ownership

• The wrapper stages strings, bytes, and arrays into linear memory with the exported weaveffi_alloc / weaveffi_dealloc and releases them after the call; you don’t manage buffers for typed calls.
• Producer-owned returns (strings, arrays, struct fields) are copied to JavaScript values and freed via weaveffi_free_string / weaveffi_dealloc inside the wrapper.
• Struct wrapper objects hold a native handle. JavaScript has no deterministic destructors; the underlying allocation lives until the module is dropped. Treat handles as owned by the module instance.
• Error slots are allocated, checked, and cleared internally; failures surface as thrown Errors with the producer’s code and message.
• When you bypass the typed surface via _raw, the conventions at the top of weaveffi_wasm.js apply and every alloc must be paired with a dealloc.

Troubleshooting

• WebAssembly.Function is not a constructor: the runtime lacks JS Type Reflection. Use a current Chrome/Firefox/Node/Deno, or avoid async functions, callbacks, and listeners for this target.
• LinkError: import object field 'env' is not a Function: the loader instantiates with an empty imports object. If your Rust crate imports host functions, extend loadWeaveffiWasm to pass them in. If the module was built with Emscripten, use Emscripten mode instead.
• An async call never settles: the producer must invoke the completion callback on the same thread; std::thread::spawn does not exist on wasm32-unknown-unknown.
• A registered listener never fires: delivery is synchronous, so events arrive only while a call into the module is on the stack. The producer must emit_* during one of your calls; there is no background delivery on this target.
• Out-of-memory after many _raw calls: every pointer returned from the module must be deallocated; the typed wrappers do this for you, raw calls do not.
• The .wasm file fails to instantiate: the build artifact must be wasm32-unknown-unknown. wasm32-wasi modules require WASI imports and cannot run in the browser without a polyfill.

Python

Overview

The Python target produces pure-Python ctypes bindings, type stubs, and packaging files. Calls go through Python’s built-in ctypes module so there is no compilation step, no native extension, and no third-party runtime dependency. The generated package works on any Python 3.7+ interpreter that can dlopen the shared library.

The trade-off is that ctypes calls are slower than compiled extensions (cffi, pybind11, PyO3). For typical FFI workloads the overhead is negligible compared to the work done inside the Rust library.

What gets generated

The package directory follows the IDL package.name (a package named events produces python/events/...); weaveffi is the default.

Type mapping

Booleans cross the boundary as c_int32 (0/1) because C has no standard fixed-width boolean type across ABIs.

Example IDL → generated code

version: "0.5.0"
modules:
  - name: contacts
    enums:
      - name: ContactType
        doc: "Type of contact"
        variants:
          - { name: Personal, value: 0 }
          - { name: Work, value: 1 }
          - { name: Other, value: 2 }

    structs:
      - name: Contact
        doc: "A contact record"
        fields:
          - { name: name, type: string }
          - { name: email, type: "string?" }
          - { name: age, type: i32 }

    functions:
      - name: create_contact
        params:
          - { name: name, type: string }
          - { name: email, type: "string?" }
          - { name: contact_type, type: ContactType }
        return: handle

      - name: get_contact
        params:
          - { name: id, type: handle }
        return: Contact

      - name: count_contacts
        params: []
        return: i32

The generated module loads the platform-specific shared library:

def _load_library() -> ctypes.CDLL:
    # An explicit path in WEAVEFFI_LIBRARY wins, so callers can point at a
    # specific build artifact regardless of its file name or location.
    override = os.environ.get("WEAVEFFI_LIBRARY")
    if override:
        return ctypes.CDLL(override)
    system = platform.system()
    if system == "Darwin":
        name = "libweaveffi.dylib"
    elif system == "Windows":
        name = "weaveffi.dll"
    else:
        name = "libweaveffi.so"
    return ctypes.CDLL(name)

_lib = _load_library()

Functions become snake_case Python functions with full type hints; ctypes argtypes/restype are set up at the call site:

def create_contact(name: str, email: Optional[str], contact_type: "ContactType") -> int:
    _fn = _lib.weaveffi_contacts_create_contact
    _fn.argtypes = [ctypes.c_char_p, ctypes.c_char_p, ctypes.c_int32,
                    ctypes.POINTER(_WeaveFFIErrorStruct)]
    _fn.restype = ctypes.c_uint64
    _err = _WeaveFFIErrorStruct()
    _result = _fn(_string_to_bytes(name), _string_to_bytes(email),
                  contact_type.value, ctypes.byref(_err))
    _check_error(_err)
    return _result

Enums become IntEnum subclasses:

class ContactType(IntEnum):
    """Type of contact"""
    Personal = 0
    Work = 1
    Other = 2

Structs become Python classes that wrap a void pointer and expose @property getters; __del__ calls the C destructor:

class Contact:
    """A contact record"""

    def __init__(self, _ptr: int) -> None:
        self._ptr = _ptr

    def __del__(self) -> None:
        if self._ptr is not None:
            _lib.weaveffi_contacts_Contact_destroy.argtypes = [ctypes.c_void_p]
            _lib.weaveffi_contacts_Contact_destroy.restype = None
            _lib.weaveffi_contacts_Contact_destroy(self._ptr)
            self._ptr = None

    @property
    def name(self) -> str:
        _fn = _lib.weaveffi_contacts_Contact_get_name
        _fn.argtypes = [ctypes.c_void_p]
        _fn.restype = ctypes.c_void_p
        return _take_string(_fn(self._ptr)) or ""

String getters return the C string as a raw address; _take_string copies it into a Python str and frees the producer’s buffer with weaveffi_free_string, so the getter doesn’t leak.

The accompanying .pyi stub mirrors the public surface for IDE/mypy:

class ContactType(IntEnum):
    Personal: int
    Work: int
    Other: int

class Contact:
    @property
    def name(self) -> str: ...
    @property
    def email(self) -> Optional[str]: ...
    @property
    def age(self) -> int: ...

def create_contact(name: str, email: Optional[str], contact_type: "ContactType") -> int: ...

Wrapper names drop the IDL module prefix by default and stay snake_case, so create_contact in module contacts is exported as plain create_contact (the C symbol keeps its full weaveffi_contacts_create_contact name). Set strip_module_prefix: false in the Python generator config (or under [global]) to restore module-prefixed wrapper names like contacts_create_contact.

Typed errors

Every generated module defines WeaveFFIError(Exception) with code and message attributes. A module that declares an error domain also gets a domain base class and one subclass per code, each pinning its stable CODE; from the contacts sample:

class ContactsError(WeaveFFIError):
    """Base exception for the `contacts` module's error domain."""


class InvalidName(ContactsError):
    """name must not be empty"""

    CODE = 1

    def __init__(self, message: str = "name must not be empty") -> None:
        super().__init__(1, message)


class NotFound(ContactsError):
    """contact not found"""

    CODE = 2

    def __init__(self, message: str = "contact not found") -> None:
        super().__init__(2, message)


ContactsError.InvalidName = InvalidName
ContactsError.NotFound = NotFound

Only callables marked throws: true in the IDL raise these typed errors: their wrappers check the error slot with _check_contacts_error, which maps the code through _contacts_error_from and raises NotFound, InvalidName, or (for codes outside the domain, such as producer panics) a plain WeaveFFIError. Their docstrings carry a Raises section naming the domain. A callable without throws uses the generic _check_error, which raises WeaveFFIError only if the producer misbehaves:

try:
    contact = book.get(999)
except NotFound:
    ...                      # specific code
except ContactsError as e:
    print(e.code, e.message) # any domain error

Interfaces

An interfaces: entry becomes a Python class wrapping the opaque pointer. A constructor named new renders as __init__; any other constructor becomes a @classmethod factory. Methods are instance methods, statics are @staticmethods, and __del__ calls the C destructor; _from_ptr builds an instance around a pointer the C side already owns. From the kvstore sample (trimmed):

class Store:
    """An embedded key-value store owning its entries"""

    @classmethod
    def _from_ptr(cls, ptr) -> "Store":
        _obj = cls.__new__(cls)
        _obj._ptr = ptr
        return _obj

    def __del__(self) -> None:
        if self._ptr is not None:
            _lib.weaveffi_kv_Store_destroy.argtypes = [ctypes.c_void_p]
            _lib.weaveffi_kv_Store_destroy.restype = None
            _lib.weaveffi_kv_Store_destroy(self._ptr)
            self._ptr = None

    @classmethod
    def open(cls, path: str) -> "Store":
        """Open (or create) a store backed by the given filesystem path

        Raises
        ------
        KvError
            If the call reports one of the domain's error codes.
        """
        _fn = _lib.weaveffi_kv_Store_open
        _fn.argtypes = [ctypes.c_char_p, ctypes.POINTER(_WeaveFFIErrorStruct)]
        _fn.restype = ctypes.c_void_p
        _err = _WeaveFFIErrorStruct()
        _result = _fn(_string_to_bytes(path), ctypes.byref(_err))
        _check_kv_error(_err)
        if _result is None:
            raise WeaveFFIError(-1, "null pointer")
        return cls._from_ptr(_result)

    def get(self, key: str) -> Optional["Entry"]: ...
    def delete(self, key: str) -> bool: ...

    async def compact(self) -> int:
        _fn = _lib.weaveffi_kv_Store_compact_async
        _loop = asyncio.get_running_loop()
        _fut = _loop.create_future()
        # ... completion callback resolves _fut via call_soon_threadsafe ...
        return await _fut

    def legacy_put(self, key: str, value: bytes) -> bool:
        import warnings
        warnings.warn("use put() with explicit kind", DeprecationWarning, stacklevel=2)
        ...

    @staticmethod
    def default_capacity() -> int: ...

A constructor named new (as on the contacts sample’s ContactBook) lets you write book = ContactBook(); named constructors read as store = Store.open("/tmp/cache.kv"). Methods on the C ABI take the receiver as the leading argument (weaveffi_kv_Store_put(self._ptr, ...)), and functions elsewhere in the IDL accept or return the wrapper directly (get_stats(store) passes store._ptr). Deprecated members emit DeprecationWarning at call time.

import asyncio
from kvstore import EntryKind, Store

store = Store.open("/tmp/cache.kv")
store.put("alpha", b"\x01", EntryKind.Persistent, None)
print(store.count(), Store.default_capacity())
reclaimed = asyncio.run(store.compact())

Rich (algebraic) enums

A rich (algebraic) enum is a sum type whose variants carry associated data. Unlike a plain C-style Enum, which crosses the boundary as a bare ctypes.c_int32 discriminant, a rich enum lowers to an opaque object handle, so the generator emits a wrapper class with exactly the same ownership model as a struct wrapper: a ctypes.c_void_p held behind @property accessors and freed by __del__.

Given a Shape enum with variants Empty, Circle { radius: f64 }, Rectangle { width: f32, height: f32 }, and Labeled { label: string, count: u8 }, the generated class exposes a nested Tag IntEnum, one @classmethod constructor per variant, a tag property, and a per-variant field getter for each payload:

class Shape:
    """An algebraic shape (sum type with associated data)"""

    class Tag(IntEnum):
        Empty = 0
        Circle = 1
        Rectangle = 2
        Labeled = 3

    def __del__(self) -> None:
        if self._ptr is not None:
            _lib.weaveffi_shapes_Shape_destroy.argtypes = [ctypes.c_void_p]
            _lib.weaveffi_shapes_Shape_destroy.restype = None
            _lib.weaveffi_shapes_Shape_destroy(self._ptr)
            self._ptr = None

    @property
    def tag(self) -> int:
        _fn = _lib.weaveffi_shapes_Shape_tag
        _fn.argtypes = [ctypes.c_void_p]
        _fn.restype = ctypes.c_int32
        return _fn(self._ptr)

    @classmethod
    def circle(cls, radius: float) -> "Shape":
        """A circle with a radius"""
        _fn = _lib.weaveffi_shapes_Shape_Circle_new
        _fn.argtypes = [ctypes.c_double, ctypes.POINTER(_WeaveFFIErrorStruct)]
        _fn.restype = ctypes.c_void_p
        _err = _WeaveFFIErrorStruct()
        _result = _fn(radius, ctypes.byref(_err))
        _check_error(_err)
        if _result is None:
            raise WeaveFFIError(-1, "null pointer")
        return cls(_result)

    @property
    def circle_radius(self) -> float:
        """Radius in points"""
        _fn = _lib.weaveffi_shapes_Shape_Circle_get_radius
        _fn.argtypes = [ctypes.c_void_p]
        _fn.restype = ctypes.c_double
        return _fn(self._ptr)

The full surface mirrors the variants: constructors Shape.empty(), Shape.circle(radius), Shape.rectangle(width, height), and Shape.labeled(label, count) (the last takes ctypes.c_char_p + ctypes.c_uint8); field getters circle_radius, rectangle_width, rectangle_height, labeled_label, and labeled_count. Each C symbol follows the weaveffi_shapes_Shape_<Variant>_new / weaveffi_shapes_Shape_<Variant>_get_<field> pattern, with weaveffi_shapes_Shape_tag reading the discriminant.

Construct a couple of variants, read the tag and a field, then hand the wrapper to a free function:

from weaveffi import Shape, describe, scale

circle = Shape.circle(2.0)
labeled = Shape.labeled("unit", 3)

if circle.tag == Shape.Tag.Circle:
    print(circle.circle_radius)      # 2.0
print(labeled.labeled_count)         # 3

print(describe(circle))              # render via the C ABI
bigger = scale(circle, 3.0)          # returns a brand-new Shape

Ownership: each Shape owns its ctypes.c_void_p; __del__ calls weaveffi_shapes_Shape_destroy once the last Python reference is dropped, and the Shape returned by scale is owned the same way. The .pyi stub mirrors the class (nested Tag, @classmethod constructors, and @property getters) for IDE and mypy support.

Build instructions

1. Generate the bindings:

   weaveffi generate weaveffi.yaml -o generated --target python
   

2. Build the Rust shared library:

   cargo build --release -p your_library
   

3. Install the package (editable install for development):

   cd generated/python
   pip install -e .
   

4. Make the shared library findable at runtime:

   • macOS: export DYLD_LIBRARY_PATH=$PWD/../../target/release
   • Linux: export LD_LIBRARY_PATH=$PWD/../../target/release
   • Windows: place weaveffi.dll next to your script or add its directory to PATH.

5. Use the bindings:

   from weaveffi import (
       ContactType,
       count_contacts,
       create_contact,
       get_contact,
   )
   
   handle = create_contact("Alice", "alice@example.com", ContactType.Work)
   contact = get_contact(handle)
   print(f"{contact.name} ({contact.email})")
   print(f"Total: {count_contacts()}")
   

Memory and ownership

• Strings in: Python str is encoded to UTF-8 by _string_to_bytes before crossing the boundary. ctypes manages the lifetime of the temporary buffer.

• Strings out: owned const char* returns come back as raw addresses; _take_string copies the text and immediately calls weaveffi_free_string on the producer’s buffer. (_bytes_to_string is reserved for borrowed strings, such as listener callback parameters, which the wrapper must not free.)

• Bytes: copied in via a ctypes array, copied out via slicing (_result[:_out_len.value]); the wrapper then releases the producer’s buffer with weaveffi_free_bytes.

• Optional scalars out: the producer boxes the value behind a pointer (null means None); the wrapper dereferences it and frees the box with weaveffi_free_bytes.

• Lists and maps out: each element is copied (string elements through _take_string, which frees them individually), then the array buffer itself, or both parallel key/value buffers for a map, is released with weaveffi_free_bytes.

• Structs: wrappers hold an opaque c_void_p. __del__ calls the matching _destroy C function. For deterministic cleanup, use the _PointerGuard context manager:

  with _PointerGuard(handle, _lib.weaveffi_contacts_Contact_destroy):
      ...
  

Async support

Async IDL functions (async: true) are exposed as async def wrappers that integrate directly with asyncio; no worker thread blocks waiting for the result. The wrapper creates a future on the running loop, builds a ctypes.CFUNCTYPE completion callback, calls the _async-suffixed C launcher (which returns immediately), and awaits the future. From the kvstore sample’s Store.compact:

async def compact(self) -> int:
    """Reclaim space asynchronously; returns the number of bytes reclaimed

    Raises
    ------
    KvError
        If the call reports one of the domain's error codes.
    """
    _fn = _lib.weaveffi_kv_Store_compact_async
    _loop = asyncio.get_running_loop()
    _fut = _loop.create_future()

    def _cb_impl(context, err, result):
        # Fires exactly once, on a producer thread: convert (copying
        # borrowed buffers) here, then hop back to the event loop.
        _state = {"err": None, "val": None}
        if err and err.contents.code != 0:
            _code = err.contents.code
            _msg = err.contents.message.decode("utf-8") if err.contents.message else ""
            _lib.weaveffi_error_clear(ctypes.byref(err.contents))
            _state["err"] = _kv_error_from(_code, _msg)
        else:
            _state["val"] = result

        def _resolve():
            _async_pending.pop(_token, None)
            # A cancelled future must not be resolved.
            if _fut.cancelled():
                return
            if _state["err"] is not None:
                _fut.set_exception(_state["err"])
            else:
                _fut.set_result(_state["val"])

        _loop.call_soon_threadsafe(_resolve)

    _cb_type = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.POINTER(_WeaveFFIErrorStruct), ctypes.c_int64)
    _cb = _cb_type(_cb_impl)
    _token = _async_register(_cb)  # pinned until completion
    _fn.argtypes = [ctypes.c_void_p, ctypes.c_void_p, _cb_type, ctypes.c_void_p]
    _fn.restype = None
    _fn(self._ptr, None, _cb, None)
    return await _fut

The completion callback fires exactly once, on an arbitrary producer thread. Result buffers passed to it (strings, bytes, arrays) are owned by the producer and valid only for the callback’s duration, so the wrapper deep-copies them inside the callback and never frees them. Owned-object results (structs, rich enums, interfaces, including optional ones) are the exception: the callback receives ownership and adopts the pointer into a wrapper class. Conversion happens on the producer thread; the wrapper then hops back to the event loop with loop.call_soon_threadsafe to resolve the future, since asyncio futures must not be touched from foreign threads.

When the callable is marked throws: true, an error reported through the callback is mapped through the domain mapper (here _kv_error_from) and set as the future’s exception, so await raises the typed error. For a non-throwing callable a non-zero code can only be a producer bug; the wrapper raises the generic WeaveFFIError rather than swallowing it.

Each callback trampoline is pinned in the module-level _async_pending dict until completion, so the GC cannot collect an object the producer still holds, even if the awaiting coroutine is cancelled. A cancelled future is never resolved, but the native operation itself keeps running.

Async interface methods work the same way as bound methods: the receiver pointer is passed as the launcher’s leading argument.

For functions marked cancellable: true the C launcher takes an extra cancel-token parameter; the Python wrapper always passes None (NULL) for it, as in the compact example above. The token is not exposed, so cancelling the awaiting asyncio task does not stop the native operation. Cancellation tokens are currently surfaced only by the C and C++ targets.

Callbacks and listeners

IDL callbacks declare a C function-pointer type; a listener pairs one with register/unregister entry points:

callbacks:
  - name: OnMessage
    params:
      - { name: message, type: string }
listeners:
  - name: message_listener
    event_callback: OnMessage

Each listener becomes a register/unregister pair of module functions. Registering wraps the Python callable in a ctypes.CFUNCTYPE trampoline that decodes each C slot, and returns a uint64 subscription id:

_CFUNC_weaveffi_events_OnMessage_fn = ctypes.CFUNCTYPE(
    None, ctypes.c_char_p, ctypes.c_void_p)


def register_message_listener(callback: Callable[[str], None]) -> int:
    def _trampoline(message, _context):
        callback(_bytes_to_string(message))
    _cfunc = _CFUNC_weaveffi_events_OnMessage_fn(_trampoline)
    _fn = _lib.weaveffi_events_register_message_listener
    _fn.argtypes = [_CFUNC_weaveffi_events_OnMessage_fn, ctypes.c_void_p]
    _fn.restype = ctypes.c_uint64
    _listener_id = int(_fn(_cfunc, None))
    _listener_refs[_listener_id] = _cfunc
    return _listener_id


def unregister_message_listener(listener_id: int) -> None:
    _fn = _lib.weaveffi_events_unregister_message_listener
    # ...
    _fn(ctypes.c_uint64(listener_id))
    _listener_refs.pop(listener_id, None)

• GC safety: the ctypes function object is pinned in the module-level _listener_refs dict, keyed by subscription id, so the garbage collector cannot reclaim a trampoline the producer may still call. Unregistering drops the reference.
• Subscription ids: registration returns the uint64 id produced by weaveffi_events_register_message_listener(fn, context); pass it to unregister_message_listener to stop delivery and release the trampoline.
• Threading: the callback fires on the producer’s thread, not the thread that registered it. Do not block inside it; if results must reach an asyncio loop or UI thread, marshal them yourself (e.g. with loop.call_soon_threadsafe).

Typical round trip:

listener_id = register_message_listener(lambda m: print(m))
send_message("hello")
unregister_message_listener(listener_id)

Iterators

Functions returning iter<T> receive an opaque iterator handle from the C ABI (weaveffi_events_get_messages) and wrap it in a generated lazy iterator class. The wrapper returns immediately; nothing is drained, and each consumer step issues exactly one producer next call (weaveffi_events_GetMessagesIterator_next). The signature is annotated Iterator[str]:

def get_messages() -> Iterator[str]:
    """
    Return an iterator over all sent messages

    Returns a lazy iterator: each step pulls one element from the producer. Exhaust or close() the iterator to release its native handle (garbage collection also releases it).
    """
    _fn = _lib.weaveffi_events_get_messages
    _fn.argtypes = [ctypes.POINTER(_WeaveFFIErrorStruct)]
    _fn.restype = ctypes.c_void_p
    _err = _WeaveFFIErrorStruct()
    _result = _fn(ctypes.byref(_err))
    _check_error(_err)
    return _GetMessagesIterator(_result)

The per-function iterator class implements the Python iterator protocol. Each __next__ pulls one element, checks the step’s error slot, and copies the yielded string with _take_string (which also frees the producer’s buffer per element):

class _GetMessagesIterator:
    """Lazy iterator over a producer stream: each step pulls one element
    across the C boundary. The native handle is released exactly once, on
    exhaustion, on close(), or when the iterator is garbage collected."""

    def __next__(self):
        if self._done:
            raise StopIteration
        # ... argtypes/restype for _next_fn ...
        _out_item = ctypes.c_void_p()
        _err = _WeaveFFIErrorStruct()
        _has = _next_fn(self._ptr, ctypes.byref(_out_item), ctypes.byref(_err))
        _check_error(_err)
        if not _has:
            self._done = True
            self._destroy()
            raise StopIteration
        return _take_string(_out_item.value)

    def close(self):
        """Release the native iterator without draining it."""
        self._done = True
        self._destroy()

The native handle is destroyed exactly once: eagerly on exhaustion, via close() when iteration is abandoned early, or from __del__ as a garbage-collection backstop. _destroy nulls the stored pointer, so a double destroy is impossible.

Errors from the launcher and from each next follow the function’s error strategy. A throwing iterator such as the kvstore sample’s Store.list_keys checks each step with _check_kv_error and raises the typed domain error (KeyNotFound, IoError, …) from the step that failed; a non-throwing iterator like get_messages raises the generic WeaveFFIError only for producer bugs.

Troubleshooting

• OSError: cannot find ...: the loader could not locate the shared library. Set DYLD_LIBRARY_PATH / LD_LIBRARY_PATH or copy the library next to your script.
• WeaveFFIError: ...: the Rust side returned a non-zero error code. Catch WeaveFFIError and inspect .code / .message.
• AttributeError: ... has no attribute 'argtypes': the wrapper sets argtypes/restype at the call site; ensure you’re calling the generated function, not reaching into _lib directly.
• Garbage-collected struct still referenced from Rust: keep a Python reference until you’re done; Python will call __del__ only after the last reference is dropped.

.NET

Overview

The .NET target emits a C# class library that wraps the C ABI through P/Invoke. Structs and interfaces are exposed as IDisposable classes with PascalCase members, error domains become managed exception types, and the project targets net8.0.

What gets generated

File names and the C# namespace follow the IDL package.name (a package named kvstore produces Kvstore.cs inside namespace Kvstore); WeaveFFI is the default.

Type mapping

Example IDL → generated code

version: "0.5.0"
modules:
  - name: contacts
    enums:
      - name: ContactType
        doc: Type of contact
        variants:
          - { name: Personal, value: 0 }
          - { name: Work, value: 1 }
          - { name: Other, value: 2 }

    structs:
      - name: Contact
        doc: A contact record
        fields:
          - { name: name, type: string }
          - { name: email, type: "string?" }
          - { name: age, type: i32 }
          - { name: contact_type, type: ContactType }

    functions:
      - name: create_contact
        params:
          - { name: name, type: string }
          - { name: email, type: "string?" }
          - { name: age, type: i32 }
        return: handle

      - name: get_contact
        params:
          - { name: id, type: handle }
        return: Contact

      - name: list_contacts
        params: []
        return: "[Contact]"

Enums become C# enums with explicit values:

/// <summary>Type of contact</summary>
public enum ContactType
{
    Personal = 0,
    Work = 1,
    Other = 2,
}

Structs are wrapped in IDisposable classes with a finalizer safety net:

public class Contact : IDisposable
{
    private IntPtr _handle;
    private bool _disposed;

    internal Contact(IntPtr handle)
    {
        _handle = handle;
    }

    internal IntPtr Handle => _handle;

    public string Name
    {
        get
        {
            var ptr = NativeMethods.weaveffi_contacts_Contact_get_name(_handle);
            var str = WeaveFFIHelpers.PtrToString(ptr);
            NativeMethods.weaveffi_free_string(ptr);
            return str ?? "";
        }
    }

    public void Dispose()
    {
        if (!_disposed)
        {
            NativeMethods.weaveffi_contacts_Contact_destroy(_handle);
            _disposed = true;
        }
        GC.SuppressFinalize(this);
    }

    ~Contact()
    {
        Dispose();
    }
}

Functions live as static methods on a class named after the module. Method names are PascalCase with the module prefix stripped (Contacts.CreateContact, not ContactsCreateContact); set strip_module_prefix: false in the .NET generator config (or under [global]) to keep prefixed names. Nested IDL modules flatten into a single class with a concatenated name (a stats module nested under kv becomes KvStats with KvStats.GetStats):

public static class Contacts
{
    public static ulong CreateContact(string name, string? email, int age)
    {
        var err = new WeaveFFIError();
        var namePtr = Marshal.StringToCoTaskMemUTF8(name);
        var emailPtr = email != null ? Marshal.StringToCoTaskMemUTF8(email) : IntPtr.Zero;
        try
        {
            var result = NativeMethods.weaveffi_contacts_create_contact(namePtr, emailPtr, age, ref err);
            WeaveFFIError.Check(err);
            return result;
        }
        finally
        {
            Marshal.FreeCoTaskMem(namePtr);
            if (emailPtr != IntPtr.Zero) Marshal.FreeCoTaskMem(emailPtr);
        }
    }
}

P/Invoke entries live in an internal NativeMethods class:

internal static class NativeMethods
{
    private const string LibName = "weaveffi";

    [DllImport(LibName, CallingConvention = CallingConvention.Cdecl)]
    internal static extern void weaveffi_free_string(IntPtr ptr);

    [DllImport(LibName, EntryPoint = "weaveffi_contacts_create_contact", CallingConvention = CallingConvention.Cdecl)]
    internal static extern ulong weaveffi_contacts_create_contact(IntPtr name, IntPtr email, int age, ref WeaveFFIError err);
}

Typed errors

The library defines WeaveFFIException with a Code property. A module’s error domain adds a derived exception named by replacing the trailing Error stem with Exception (KvError becomes KvException), carrying one const int per code and a FromCode factory. From the kvstore sample:

/// <summary>Typed exception for the KvError error domain (module kv).</summary>
public class KvException : WeaveFFIException
{
    /// <summary>key not found</summary>
    public const int KeyNotFound = 1001;
    /// <summary>entry expired</summary>
    public const int Expired = 1002;
    /// <summary>store has reached capacity</summary>
    public const int StoreFull = 1003;
    /// <summary>I/O failure</summary>
    public const int IoError = 1004;

    public KvException(int code, string message) : base(code, message)
    {
    }

    /// <summary>Wraps a raw error slot in the typed exception, falling
    /// back to <see cref="WeaveFFIException"/> for unknown codes.</summary>
    internal static WeaveFFIException FromCode(int code, string message)
    {
        switch (code)
        {
            case KeyNotFound:
                return new KvException(code, string.IsNullOrEmpty(message) ? "key not found" : message);
            // ... Expired, StoreFull, IoError ...
            default:
                return new WeaveFFIException(code, message);
        }
    }
}

Only callables marked throws: true in the IDL surface the typed exception: their wrappers check the error slot with WeaveFFIError.CheckKv, which throws KvException for domain codes and plain WeaveFFIException for anything else (producer panics, marshalling failures), and their doc comments carry an <exception cref="KvException"> tag. A callable without throws uses the generic WeaveFFIError.Check, which only throws WeaveFFIException if the producer misbehaves.

try
{
    store.Delete("missing");
}
catch (KvException e) when (e.Code == KvException.KeyNotFound)
{
    // specific code
}

Interfaces

An interfaces: entry becomes a class implementing IDisposable. Constructors are static factories (a constructor named new becomes a public C# constructor), methods are PascalCase instance methods, statics are static methods, and Dispose() calls the C destructor with a finalizer as a safety net. From the kvstore sample (trimmed):

public class Store : IDisposable
{
    private IntPtr _handle;
    private bool _disposed;

    internal Store(IntPtr handle)
    {
        _handle = handle;
    }

    /// <summary>Open (or create) a store backed by the given filesystem path</summary>
    /// <exception cref="KvException">Thrown when the call reports a KvError code.</exception>
    public static Store Open(string path)
    {
        var err = new WeaveFFIError();
        var pathPtr = Marshal.StringToCoTaskMemUTF8(path);
        try
        {
            var result = NativeMethods.weaveffi_kv_Store_open(pathPtr, ref err);
            WeaveFFIError.CheckKv(err);
            return new Store(result);
        }
        finally
        {
            Marshal.FreeCoTaskMem(pathPtr);
        }
    }

    public bool Put(string key, byte[] value, EntryKind kind, long? ttlSeconds) { /* throws KvException */ }
    public Entry? Get(string key) { /* throws KvException */ }
    public IEnumerable<string> ListKeys(string? prefix) { /* lazy; see Memory and ownership */ }
    public long Count() { /* generic check only (no throws) */ }

    /// <exception cref="KvException">Thrown when the call reports a KvError code.</exception>
    public async Task<long> Compact() { /* see Async support */ }

    [Obsolete("use put() with explicit kind")]
    public bool LegacyPut(string key, byte[] value) { /* ... */ }

    /// <summary>The largest number of live entries one store will hold</summary>
    public static long DefaultCapacity()
    {
        var err = new WeaveFFIError();
        var result = NativeMethods.weaveffi_kv_Store_default_capacity(ref err);
        WeaveFFIError.Check(err);
        return result;
    }

    public void Dispose()
    {
        if (!_disposed)
        {
            NativeMethods.weaveffi_kv_Store_destroy(_handle);
            _disposed = true;
        }
        GC.SuppressFinalize(this);
    }

    ~Store()
    {
        Dispose();
    }
}

Functions elsewhere in the IDL pass the wrapper’s handle across the boundary (KvStats.GetStats(store) reads store.Handle and returns a new Stats). Deprecated members carry [Obsolete]:

using var store = Store.Open("/tmp/cache.kv");
store.Put("alpha", new byte[] { 1 }, EntryKind.Persistent, null);
Console.WriteLine($"{store.Count()} / {Store.DefaultCapacity()}");
long reclaimed = await store.Compact();

Rich (algebraic) enums

A rich (algebraic) enum, a sum type whose variants carry associated data, lowers to an opaque handle at the C ABI, just like a struct, and uses the same IDisposable ownership model as the struct wrappers above. The generated C# type is a class wrapping an IntPtr, with one static factory per variant, a nested Tag enum for the discriminant, and per-variant property getters. (A plain C-style enum with no payloads stays a normal C# enum backed by int; see above.)

For the shapes module’s Shape enum (Empty, Circle { radius: f64 }, Rectangle { width: f32, height: f32 }, and Labeled { label: string, count: u8 }), the generator emits (abridged):

/// <summary>An algebraic shape (sum type with associated data)</summary>
public class Shape : IDisposable
{
    private IntPtr _handle;
    private bool _disposed;

    internal Shape(IntPtr handle)
    {
        _handle = handle;
    }

    internal IntPtr Handle => _handle;

    public enum Tag
    {
        Empty = 0,
        Circle = 1,
        Rectangle = 2,
        Labeled = 3,
    }

    public Tag GetTag()
    {
        return (Tag)NativeMethods.weaveffi_shapes_Shape_tag(_handle);
    }

    /// <summary>A circle with a radius</summary>
    public static Shape Circle(double radius)
    {
        var err = new WeaveFFIError();
        var result = NativeMethods.weaveffi_shapes_Shape_Circle_new(radius, ref err);
        WeaveFFIError.Check(err);
        return new Shape(result);
    }

    /// <summary>A labeled shape with a small count</summary>
    public static Shape Labeled(string label, byte count)
    {
        var err = new WeaveFFIError();
        var labelPtr = Marshal.StringToCoTaskMemUTF8(label);
        try
        {
            var result = NativeMethods.weaveffi_shapes_Shape_Labeled_new(labelPtr, count, ref err);
            WeaveFFIError.Check(err);
            return new Shape(result);
        }
        finally
        {
            Marshal.FreeCoTaskMem(labelPtr);
        }
    }

    /// <summary>Radius in points</summary>
    public double CircleRadius
    {
        get
        {
            return NativeMethods.weaveffi_shapes_Shape_Circle_get_radius(_handle);
        }
    }

    public byte LabeledCount
    {
        get
        {
            return NativeMethods.weaveffi_shapes_Shape_Labeled_get_count(_handle);
        }
    }

    public void Dispose()
    {
        if (!_disposed)
        {
            NativeMethods.weaveffi_shapes_Shape_destroy(_handle);
            _disposed = true;
        }
        GC.SuppressFinalize(this);
    }

    ~Shape()
    {
        Dispose();
    }
}

The static factories (Shape.Empty(), Shape.Circle(double), Shape.Rectangle(float, float), Shape.Labeled(string, byte)) call the per-variant constructors weaveffi_shapes_Shape_<Variant>_new; GetTag() reads the discriminant via weaveffi_shapes_Shape_tag; each getter reads one variant field via weaveffi_shapes_Shape_<Variant>_get_<field>; and Dispose() frees the handle via weaveffi_shapes_Shape_destroy. The P/Invoke entries live in NativeMethods:

[DllImport(LibName, EntryPoint = "weaveffi_shapes_Shape_tag", CallingConvention = CallingConvention.Cdecl)]
internal static extern int weaveffi_shapes_Shape_tag(IntPtr ptr);

[DllImport(LibName, EntryPoint = "weaveffi_shapes_Shape_Circle_new", CallingConvention = CallingConvention.Cdecl)]
internal static extern IntPtr weaveffi_shapes_Shape_Circle_new(double radius, ref WeaveFFIError err);

[DllImport(LibName, EntryPoint = "weaveffi_shapes_Shape_destroy", CallingConvention = CallingConvention.Cdecl)]
internal static extern void weaveffi_shapes_Shape_destroy(IntPtr ptr);

Free functions that take or return the enum live on the module class Shapes and pass the wrapper’s handle across the boundary (Shapes.Describe(Shape), Shapes.Scale(Shape, double)):

using var c = Shape.Circle(2.0);
Console.WriteLine(c.GetTag());                // Tag.Circle
Console.WriteLine(c.CircleRadius);            // 2
using var bigger = Shapes.Scale(c, 3.0);      // returns a new Shape
Console.WriteLine(Shapes.Describe(bigger));

Ownership: a Shape owns its native handle, so dispose every Shape you create or receive, including the one returned by Shapes.Scale, with using or an explicit Dispose(). The finalizer is a safety net that runs on a non-deterministic schedule.

Build instructions

1. Generate the bindings:

   weaveffi generate api.yaml -o generated/ --target dotnet
   

2. Build:

   cd generated/dotnet
   dotnet build
   

3. Pack as NuGet:

   dotnet pack -c Release
   

   The resulting .nupkg lives in bin/Release/. For production packages, bundle the native cdylib inside the package under runtimes/{rid}/native/.

4. Make the cdylib findable at runtime: place it next to the built DLL, set LD_LIBRARY_PATH / DYLD_LIBRARY_PATH, or include it in the NuGet package as above.

Memory and ownership

• Each struct and interface class implements IDisposable; use using for deterministic cleanup. The finalizer is a safety net only and runs on a non-deterministic schedule.
• Strings returned from getters are copied into managed memory and the raw pointer is freed via weaveffi_free_string immediately, so string properties do not require any disposal.
• Strings passed as parameters are marshalled with Marshal.StringToCoTaskMemUTF8 and freed in a finally block.
• Returned byte[], array, and dictionary buffers are copied into managed memory and released with weaveffi_free_bytes; string elements are freed individually with weaveffi_free_string first.
• Optional struct returns surface as IntPtr.Zero from the C ABI and become null in C#. A boxed optional scalar is dereferenced and its box freed with weaveffi_free_bytes.
• iter<T> functions return a lazy, single-use IEnumerable<T> (WeaveFFIOnceEnumerable<T>) that pulls one item through the C _next function per enumeration step; each string element is copied and freed with weaveffi_free_string, and the native iterator handle is destroyed in a finally block when enumeration completes, a step fails, or the enumerator is disposed early (a foreach disposes it automatically, including on early exit). A throwing function checks the launch and each step with the domain checker (Store.ListKeys throws KvException from the failing step).

Async support

Async IDL functions are exposed as async Task<T> methods (named like every other wrapper: no extra Async suffix is appended). The wrapper wires the C ABI completion callback into a TaskCompletionSource<T> and keeps the callback delegate alive with a GCHandle while the call is in flight:

/// <exception cref="TaskException">Thrown when the call reports a TaskError code.</exception>
public static async Task<TaskResult> RunTask(string name)
{
    var tcs = new TaskCompletionSource<TaskResult>(TaskCreationOptions.RunContinuationsAsynchronously);
    NativeMethods.AsyncCb_weaveffi_tasks_run_task callback = (context, err, result) =>
    {
        try
        {
            // ... tcs.SetException(TaskException.FromCode(...)) on error ...
            tcs.SetResult(new TaskResult(result));
        }
        finally
        {
            if (context != IntPtr.Zero)
            {
                GCHandle.FromIntPtr(context).Free();
            }
        }
    };
    var gcHandle = GCHandle.Alloc(callback, GCHandleType.Normal);
    var ctx = GCHandle.ToIntPtr(gcHandle);
    // ... marshal parameters, gcHandle.Free() in a catch if the native call throws ...
    NativeMethods.weaveffi_tasks_run_task_async(namePtr, callback, ctx);
    return await tcs.Task;
}

• The GCHandle prevents the GC from collecting the delegate (and the native thunk the producer will call) before completion. It is freed exactly once: in the callback’s finally, or on the catch path if the native call itself throws synchronously.
• The completion callback runs on the producer’s native thread; RunContinuationsAsynchronously keeps awaiting code from running inline on that thread.
• For a callable marked throws: true, an error faults the task with the domain exception via its FromCode factory (KvException.FromCode on Store.Compact()); otherwise a failure can only be a producer bug and faults the task with WeaveFFIException.
• Result ownership follows the async contract: string, bytes, array, map, and boxed optional scalar results are borrowed for the callback’s duration, so the callback deep-copies them into managed values and never frees them (the producer does after the callback returns). Object results (records, rich enums, interfaces, including optional ones) are the exception: the callback receives ownership, and the wrapper adopts the pointer, as new TaskResult(result) does above.

Async interface methods follow the same pattern as instance methods: await store.Compact() returns Task<long>.

For functions marked cancellable: true the wrapper passes IntPtr.Zero for the C ABI’s cancel-token slot; no CancellationToken parameter is exposed. Only the C and C++ targets expose cancellation tokens.

Callbacks and listeners

An IDL listener becomes a register/unregister pair on the module class. Registration takes an Action<...> and returns a ulong subscription id; unregistration takes that id back:

public static ulong RegisterMessageListener(Action<string> callback)
public static void UnregisterMessageListener(ulong id)

The id is the uint64 returned by the C ABI’s weaveffi_events_register_message_listener(callback_fn, context). Registration wraps the Action in a Cdecl delegate trampoline and stores it in a registry keyed by the subscription id so the GC cannot collect it while the native side may still call it:

private static readonly object _listenerLock = new object();
private static readonly Dictionary<ulong, Delegate> _listenerRefs = new Dictionary<ulong, Delegate>();

public static ulong RegisterMessageListener(Action<string> callback)
{
    NativeMethods.Cb_weaveffi_events_OnMessage_fn trampoline = (message, context) =>
    {
        callback(Marshal.PtrToStringUTF8(message) ?? "");
    };
    ulong id;
    lock (_listenerLock)
    {
        id = NativeMethods.weaveffi_events_register_message_listener(trampoline, IntPtr.Zero);
        _listenerRefs[id] = trampoline;
    }
    return id;
}

The trampoline’s delegate type is declared with [UnmanagedFunctionPointer(CallingConvention.Cdecl)]. Events.UnregisterMessageListener(id) calls the C ABI unregister first and then drops the registry entry, releasing the delegate for collection.

Threading caveats:

• The callback runs on the producer’s native thread, not on any captured SynchronizationContext. Post to your UI thread or dispatcher yourself if needed.
• Keep callbacks fast and non-throwing; they execute while the native producer is delivering the event.

Troubleshooting

• DllNotFoundException: Unable to load DLL 'weaveffi': the runtime cannot find the shared library. Place it in the application directory or set LD_LIBRARY_PATH / DYLD_LIBRARY_PATH.
• AccessViolationException on dispose: the struct has been disposed twice. Wrap usage in using and avoid passing handles around once disposed.
• Strings returned with garbage characters: make sure your binding is targeting UTF8 (Marshal.PtrToStringUTF8, StringToCoTaskMemUTF8); the generated helpers do this for you.
• NuGet consumers cannot find the cdylib: ship it inside the package under runtimes/{rid}/native/ so the .NET runtime resolves it automatically.

C++

Overview

The C++ target emits a header-only library weaveffi.hpp that wraps the C ABI in idiomatic C++17. Structs and interfaces become RAII classes with deleted copies and movable handles, error domains map to typed exception hierarchies, async functions return std::future, and listeners accept std::function callbacks. A CMakeLists.txt is included so the generated directory can be dropped into any CMake build.

What gets generated

Type mapping