flemming-it
d3642853ec
All checks were successful
CI / Linux x86_64 (Forgejo) (push) Successful in 1m41s
The SDK provides a stable, ergonomic Rust surface for writing
F∆I Platform modules. A module is now a single decorated
function:
#[fai_module]
fn invoke(_ctx: Context, inputs: Inputs)
-> Result<Outputs, ModuleError>
{
let text = inputs.require_text("input")?;
Ok(Outputs::new().with_text("output", format!("echo: {text}")))
}
The macro absorbs every piece of WASM-module boilerplate that
previously lived per-repo: the wit_bindgen::generate! call, the
Guest trait impl, the WIT-to-SDK type conversions, the
wit_bindgen::export! glue, and the unsafe_op_in_unsafe_fn allow
attribute. Module repos depend only on fai-module-sdk and need
no wit/ directory of their own — the SDK ships a verified
mirror of the platform's frozen v1.0 WIT contract.
The SDK is the central lever for keeping the contract stable
without freezing module ergonomics. If the platform ever bumps
the WIT contract (additive minor or coordinated v2.0), the
change is absorbed inside the SDK; existing module source
keeps compiling against a new SDK release.
Components in this initial drop:
crates/fai-module-sdk
Public types — Context, Inputs, Outputs, Payload,
ModuleError. Helpers like require_text / require_json /
with_bytes / with_json. Pure Rust, no wit_bindgen
dependency in user-facing code.
crates/fai-module-sdk-macros
The proc-macro crate that emits the wit_bindgen call,
the Guest impl, the WIT<->SDK conversion code, and the
export! invocation. Uses runtime_path to route the
generated bindings through the SDK's re-export of
wit_bindgen::rt so user crates need no direct dep.
wit/world.wit
Mirror of fai/platform :: wit/world.wit, frozen at v1.0.
A snapshot test (crates/fai-module-sdk/tests/wit_freeze.rs)
asserts the SHA-256 matches the platform constant; CI
fails if the two ever drift.
examples/echo
Reference module that demonstrates the entire authoring
surface. Compiles to wasm32-wasip2 with the correct
v1.0 imports baked in (verified manually; CI runs the
same build).
Tests: 7 unit tests + 1 snapshot test. Cargo fmt and clippy
clean across the workspace and the example.
Forgejo CI workflow mirrors the platform pattern (manual
external-URL checkout + libssl-dev system deps + wasm32-wasip2
target + workspace fmt/clippy/build/test + example wasm build).
Signed-off-by: flemming-it <sf@flemming.it>
99 lines
2.9 KiB
Text
99 lines
2.9 KiB
Text
// =============================================================
|
|
// FROZEN. Wire contract between hub and modules.
|
|
// =============================================================
|
|
//
|
|
// This file is the stable wire contract between the F∆I Hub
|
|
// and any module compiled against it. It is **frozen at v1.0**.
|
|
//
|
|
// Frozen means:
|
|
//
|
|
// - No removal, rename, or signature change of any existing
|
|
// interface, function, type, field, or variant case.
|
|
// - Additive changes (new types, new variant cases at the end,
|
|
// new fields with stable defaults) require a minor bump
|
|
// (1.0 -> 1.1) and a coordinated review.
|
|
// - Any breaking change requires a major bump (1.0 -> 2.0)
|
|
// and a parallel-world transition plan.
|
|
//
|
|
// The fai_runtime crate ships a snapshot test that fails if
|
|
// this file changes without an intentional, reviewed update.
|
|
// See `crates/fai_runtime/tests/wit_freeze.rs`.
|
|
//
|
|
// Module authors do NOT depend on this file directly. They
|
|
// use `fai-module-sdk`, which wraps these bindings behind a
|
|
// stable, ergonomic surface. That is what protects modules
|
|
// from any future evolution of this contract.
|
|
|
|
package fai:platform@1.0.0;
|
|
|
|
/// Types that flow between the host (hub) and modules.
|
|
interface types {
|
|
/// A typed value passed between the host and a module.
|
|
variant payload {
|
|
/// Plain UTF-8 text.
|
|
text(string),
|
|
/// Arbitrary JSON encoded as a string.
|
|
json(string),
|
|
/// Raw bytes with a MIME type.
|
|
bytes(bytes-value),
|
|
/// A reference to a file, by URI.
|
|
file-ref(file-ref),
|
|
}
|
|
|
|
/// Inline byte content.
|
|
record bytes-value {
|
|
mime-type: string,
|
|
data: list<u8>,
|
|
}
|
|
|
|
/// File reference by URI.
|
|
record file-ref {
|
|
uri: string,
|
|
mime-type: string,
|
|
size-bytes: u64,
|
|
sha256: string,
|
|
}
|
|
|
|
/// Context passed with every invocation.
|
|
record invocation-context {
|
|
invocation-id: string,
|
|
capability-namespace: string,
|
|
capability-name: string,
|
|
deadline-ms: u64,
|
|
}
|
|
|
|
/// Structured error type returned by modules.
|
|
variant invocation-error {
|
|
invalid-input(string),
|
|
permission-denied(string),
|
|
resource-exhausted(string),
|
|
deadline-exceeded,
|
|
internal(string),
|
|
}
|
|
}
|
|
|
|
/// The host-provided interface that modules can import to talk back.
|
|
interface host {
|
|
/// Log a structured message. Level is "trace", "debug", "info", "warn", "error".
|
|
log: func(level: string, message: string);
|
|
}
|
|
|
|
/// The core interface every module exports.
|
|
interface invoke {
|
|
use types.{payload, invocation-context, invocation-error};
|
|
|
|
/// Invoke the module with inputs, receive outputs or an error.
|
|
invoke: func(
|
|
ctx: invocation-context,
|
|
inputs: list<tuple<string, payload>>,
|
|
) -> result<list<tuple<string, payload>>, invocation-error>;
|
|
}
|
|
|
|
/// The world a module component targets.
|
|
///
|
|
/// Modules `export` the invoke interface to be callable by the hub.
|
|
/// Modules `import` the host interface to emit logs.
|
|
world module {
|
|
import host;
|
|
export invoke;
|
|
}
|