rill_handler_api/
lib.rs

1//! Versioned WIT ABI and guest SDK for Rill runtime handlers.
2//!
3//! This crate ships the canonical WIT world definition
4//! ([`wit/rill-handler.wit`](https://github.com/hello-yunshu/rill-ml/tree/main/crates/rill-handler-api/wit/rill-handler.wit))
5//! that every Rill handler must export.
6//!
7//! Handler authors compile a Rust crate to `wasm32-wasip1` using
8//! [`wit-bindgen`](https://crates.io/crates/wit-bindgen) to generate guest
9//! bindings from the WIT file, then wrap the core module into a Component
10//! Model component with `wasm-tools component new`.
11//!
12//! This crate intentionally has **no dependencies** so that it can be consumed
13//! as a build-time WIT source without pulling in any runtime code. The
14//! constants below mirror the WIT declarations and are used by both the host
15//! and guest for compile-time version checks.
16
17/// Handler ABI version. Independent from the host IPC API version and the model
18/// pack format version. Increment only on a breaking WIT change.
19pub const HANDLER_API_VERSION: u32 = 1;
20
21/// WIT package name as declared in `rill-handler.wit`.
22pub const WIT_PACKAGE: &str = "rill:handler";
23
24/// WIT package version as declared in `rill-handler.wit`.
25pub const WIT_VERSION: &str = "1.0.0";
26
27/// WIT world name as declared in `rill-handler.wit`.
28pub const WIT_WORLD: &str = "invoke-handler";
29
30/// Maximum number of capabilities a handler may declare.
31pub const MAX_CAPABILITIES: usize = 32;
32
33/// Maximum length of a capability string.
34pub const MAX_CAPABILITY_LEN: usize = 96;
35
36/// Maximum length of a handler id.
37pub const MAX_HANDLER_ID_LEN: usize = 96;
38
39/// Maximum length of a handler version string.
40pub const MAX_HANDLER_VERSION_LEN: usize = 48;
41
42/// Preview Stateful Handler ABI v2 declarations. The frozen top-level v1
43/// constants above intentionally retain their exact values.
44pub mod v2 {
45    /// Preview stateful handler ABI version.
46    pub const HANDLER_API_VERSION: u32 = 2;
47    /// WIT package name.
48    pub const WIT_PACKAGE: &str = "rill:handler";
49    /// WIT package version.
50    pub const WIT_VERSION: &str = "2.0.0";
51    /// Stateful WIT world name.
52    pub const WIT_WORLD: &str = "stateful-handler";
53    /// Event JSON byte limit.
54    pub const MAX_EVENT_BYTES: usize = 1024 * 1024;
55    /// Output JSON byte limit.
56    pub const MAX_OUTPUT_BYTES: usize = 1024 * 1024;
57    /// Persisted handler state byte limit.
58    pub const MAX_STATE_BYTES: usize = 256 * 1024;
59}
60
61#[cfg(test)]
62mod tests {
63    use super::*;
64
65    #[test]
66    fn constants_are_stable() {
67        assert_eq!(HANDLER_API_VERSION, 1);
68        assert_eq!(WIT_PACKAGE, "rill:handler");
69        assert_eq!(WIT_VERSION, "1.0.0");
70        assert_eq!(WIT_WORLD, "invoke-handler");
71    }
72
73    #[test]
74    fn preview_v2_constants_are_independent() {
75        assert_eq!(v2::HANDLER_API_VERSION, 2);
76        assert_eq!(v2::WIT_VERSION, "2.0.0");
77        assert_eq!(v2::WIT_WORLD, "stateful-handler");
78        assert_eq!(HANDLER_API_VERSION, 1);
79    }
80}
rill_handler_api/lib.rs

rill_handler_api/
lib.rs
