witforge

WIT-first contract compiler for stable Rust, protobuf, JSON Schema, and versioned adapters

View the Project on GitHub asamarts/witforge

witforge quickstart

witforge turns one hand-written WIT package into the artifacts the two sides of a contract need:

It is not a runtime, transport, or WASM guest-binding generator. Non-Rust consumers use the emitted .proto with their normal protobuf toolchain; Rust consumers can use the generated plain types directly.

Install

Install the current release:

cargo install witforge-cli --version 0.5.0 --locked
witforge --version

From this repository, before or after publication:

cargo run -p witforge-cli -- --version

The examples below use witforge; replace it with cargo run -p witforge-cli -- when working from a checkout. Every command on this page runs from one working directory, the one that contains my-contract/, and the test suite runs them in this order.

One version

Create a root with a version directory:

my-contract/
  wit/
    v0.1/
      contract.wit
mkdir -p my-contract/wit/v0.1

Save a small contract as my-contract/wit/v0.1/contract.wit. The package version must match the directory name, and an interface and a world cannot share a name:

package example:hello@0.1.0;

interface greeter {
    record greeting {
        text: string,
    }

    greet: func(name: string) -> greeting;
}

world hello {
    export greeter;
}

At this point, contract.wit is the only file in v0.1. Do not create wire.lock by hand.

Create the lockfile, assign wire numbers, and validate the contract:

witforge lock my-contract/wit/v0.1 --first
witforge check my-contract/wit/v0.1

witforge lock --first creates my-contract/wit/v0.1/wire.lock. Commit contract.wit and the generated wire.lock together. The lockfile is append-only: generated protobuf field numbers and method ids must never change.

Generate each projection:

witforge rust   my-contract/wit --out my-contract/generated/rust
witforge proto  my-contract/wit --out my-contract/generated/proto
witforge schema my-contract/wit --out my-contract/generated/schema
witforge glue   my-contract/wit --out my-contract/generated/glue \
  --plain-root crate::generated::rust --proto-root crate::generated::proto

--plain-root and --proto-root are Rust module paths, not output directories. The glue emitter uses them to reference the plain types and the prost types generated from the .proto schema.

Every generator supports --check, which writes nothing and fails if committed output differs:

witforge rust   my-contract/wit --out my-contract/generated/rust --check
witforge proto  my-contract/wit --out my-contract/generated/proto --check
witforge schema my-contract/wit --out my-contract/generated/schema --check
witforge glue   my-contract/wit --out my-contract/generated/glue \
  --plain-root crate::generated::rust --proto-root crate::generated::proto --check

Use witforge.toml

Put the repeated paths in a project file, my-contract/witforge.toml:

version = 1

[project.hello]
root = "wit"

[project.hello.rust]
out = "generated/rust"
# serde = true  # opt in to Serialize/Deserialize derives

[project.hello.proto]
out = "generated/proto"

[project.hello.schema]
out = "generated/schema"

[project.hello.glue]
out = "generated/glue"
plain-root = "crate::generated::rust"
proto-root = "crate::generated::proto"

Then each generator only needs the project file:

witforge rust   --config my-contract/witforge.toml
witforge proto  --config my-contract/witforge.toml
witforge schema --config my-contract/witforge.toml
witforge glue   --config my-contract/witforge.toml

If the file has more than one project, add --project NAME. Paths inside the file are relative to the file itself. Explicit CLI paths override configured paths, and the command-line-only form continues to work. --serde or --no-serde overrides the Rust section’s serde setting; the generated code then requires the consumer’s serde crate with derive.

Evolve a contract

A contract change is a new version directory, never an edit to a released one. Keep every released version in the tree:

my-contract/wit/
  released              # lists v0.1
  v0.1/
    contract.wit
    wire.lock
  v0.2/
    contract.wit
    wire.lock

When v0.1 ships, record it as released. released lists frozen version directories, one per line:

echo v0.1 > my-contract/wit/released

Start the next minor as a copy of the previous version, lockfile included. The copied lockfile is what carries the field numbers, method ids, and reservations forward; never start a later minor with lock --first:

mkdir my-contract/wit/v0.2
cp my-contract/wit/v0.1/contract.wit my-contract/wit/v0.1/wire.lock my-contract/wit/v0.2/

Edit my-contract/wit/v0.2/contract.wit. Change the package version to 0.2.0 first: until it matches the directory name, every command refuses the directory. Then make the change. Add new members with defaultable types when possible:

package example:hello@0.2.0;

interface greeter {
    record greeting {
        text: string,
        language: option<string>,   // old values become None
        tags: list<string>,         // old values become an empty list
    }

    greet: func(name: string) -> greeting;
}

world hello {
    export greeter;
}

Assign numbers to the new members and validate the draft against the released lockfile:

witforge lock  my-contract/wit/v0.2 --against my-contract/wit/v0.1/wire.lock
witforge check my-contract/wit/v0.2 --against my-contract/wit/v0.1/wire.lock

Regenerate. With two versions in the root, witforge rust also writes convert.rs:

witforge rust   --config my-contract/witforge.toml
witforge proto  --config my-contract/witforge.toml
witforge schema --config my-contract/witforge.toml
witforge glue   --config my-contract/witforge.toml

convert.rs holds old-to-new and new-to-old adapters. Old-to-new conversion fills an added option with None and an added list with an empty list. New-to-old conversion drops members the older version does not have. Missing required older members are reported as ConversionError::MissingMember; added or removed cases are reported as ConversionError::UnknownCase. A required, non-defaultable addition is refused by conversion generation.

Do not edit a released version’s WIT, lockfile, or generated Rust module. witforge lock refuses a released directory, and check and the generators fail when a released WIT file no longer matches its lockfile. No witforge command notices a released WIT file and its lockfile edited together: that needs a history check in CI, such as this repository’s ci/check-release-freeze.sh.

Review a change

Compare a draft with the previous version before merging it:

witforge diff my-contract/wit/v0.1 my-contract/wit/v0.2
witforge diff my-contract/wit/v0.1 my-contract/wit/v0.2 --json
witforge diff my-contract/wit/v0.1 my-contract/wit/v0.2 --check   # exits 1: see below

--check fails on wire-, source-, or generated-API-breaking changes. It exits 1 for the change above: the two added fields keep every wire number and convert from old values, but Rust code that constructs a Greeting has to be updated, so diff reports them as source- and API-breaking. --json is the complete diff report. diff also reports a note when a shared record type’s generated new-to-old converter is guaranteed to fail because the older version requires a member the newer version removed; the notes do not change the change counts or --check result. To make any command’s diagnostics machine-readable, add --format json or --format sarif; the catalogue is in the diagnostics specification.

For CI, asamarts/witforge publishes an Action that installs the matching release and can run the same checks; see the Action specification.

Non-Rust consumers

Use the protobuf output with the normal generator for the target language:

The generated language type is only the protobuf projection. Proto3 cannot express every WIT decode rule: narrow integers need range checks, required optional and message fields need presence checks, enums are closed, and variant/result oneof values must select a known case. Implement those rules in the non-Rust adapter and test invalid as well as valid values. The Non-Rust implementation guide specifies the complete profile.

witforge intentionally does not duplicate wit-bindgen’s runtime WIT bindings or own transport framing. The stable protobuf numbers and JSON Schema are cross-language contract artifacts, not a complete application protocol.

Supported WIT subset

The current subset is deliberately pure and synchronous:

Run witforge check for the exact diagnostic. The design overview has the full contract model and the reasons for each refusal.

Dependencies and Serde

A version directory may use standard deps/ packages. Put the dependency under wit/v0.1/deps/, declare its package, and import its types or interfaces normally:

package example:app@0.1.0;

interface api {
    use example:shared/types@0.1.0.{item};
    get: func() -> item;
}

world plugin {
    import example:shared/types@0.1.0;
}

witforge rust, proto, schema, and glue generate the dependency bindings alongside the local output. See the dependency specification for the generated files and dependency glue layout.

Serde is opt-in per project:

[project.demo.rust]
out = "generated/rust"
serde = true

The default generated output is unchanged; enabling Serde requires the consumer’s serde crate with the derive feature. --serde and --no-serde override the configuration.

JSON projections

Plain Rust Serde, Draft 7 JSON Schema, and proto3-JSON project the same WIT values differently:

Choose one authoritative JSON profile. Keep an explicit application adapter when an existing protocol differs, and do not validate one projection with another projection’s schema. See JSON projections for the full comparison.

Examples

Troubleshooting