chio-wasm-guards 0.1.0

WASM guard runtime for Chio -- load and execute .wasm guard modules with fuel metering
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

//! WASM Guard Runtime for Chio.
//!
//! This crate allows operators to author guards in any language that compiles
//! to WebAssembly (Rust, AssemblyScript, Go, C) and load them into the Chio
//! kernel at runtime via `chio.yaml` configuration.
//!
//! # Dual-mode support
//!
//! The host transparently supports two WASM formats:
//!
//! - **Core modules** (raw ABI): traditional modules that export `evaluate(ptr, len) -> i32`.
//!   These are loaded through `WasmtimeBackend` with host-provided functions.
//! - **Component Model components** (WIT-based): modules compiled against the
//!   `chio:guard@0.1.0` WIT interface. These are loaded through `ComponentBackend`
//!   with type-safe bindings generated by `wasmtime::component::bindgen!`.
//!
//! Format detection happens automatically at load time via [`detect_wasm_format`].
//! The [`create_backend`] factory inspects binary magic bytes and routes to the
//! correct backend. Callers do not need to know which format a `.wasm` file uses.
//!
//! # Core module ABI
//!
//! Each core `.wasm` guard module exports a single function:
//!
//! ```text
//! evaluate(request_ptr: i32, request_len: i32) -> i32
//! ```
//!
//! The host serializes the guard request as JSON into guest memory, calls
//! `evaluate`, and interprets the return value:
//!
//! - `0` = Allow
//! - `1` = Deny (guard-specific reason returned through shared memory)
//! - any negative value = error (fail-closed)
//!
//! Fuel metering limits CPU consumption. When fuel runs out the guard is
//! treated as denied (fail-closed).
//!
//! # Feature flags
//!
//! - **`wasmtime-runtime`**: Enables the `wasmtime`-backed runtime. Without
//!   this feature only the trait-based abstractions are available, which is
//!   useful for testing or providing alternative backends.

#![cfg_attr(test, allow(clippy::expect_used, clippy::unwrap_used))]

pub mod abi;
#[cfg(feature = "wasmtime-runtime")]
pub mod component;
pub mod config;
pub mod error;
#[cfg(feature = "wasmtime-runtime")]
pub mod host;
pub mod manifest;
pub mod placeholders;
pub mod runtime;
#[cfg(feature = "wasmtime-runtime")]
pub mod wiring;

pub use abi::{GuardRequest, GuardVerdict, WasmGuardAbi};
#[cfg(feature = "wasmtime-runtime")]
pub use component::ComponentBackend;
pub use config::WasmGuardConfig;
pub use error::WasmGuardError;
#[cfg(feature = "wasmtime-runtime")]
pub use host::WasmHostState;
pub use manifest::{
    load_signature_sidecar, signature_sidecar_path, signed_module_message, verify_guard_signature,
    verify_signed_module, write_signature_sidecar, GuardManifest, SignedWasmModule,
    MANIFEST_FILENAME, SIGNATURE_SUFFIX, SUPPORTED_ABI_VERSIONS,
};
pub use placeholders::{
    resolve_placeholders, resolve_placeholders_in_json, PlaceholderEnv, PlaceholderError,
    ProcessEnv,
};
#[cfg(feature = "wasmtime-runtime")]
pub use runtime::wasmtime_backend::{
    create_backend, detect_wasm_format, load_guards_from_policy, load_signed_guard, LoadError,
    PolicyCustomGuard, PolicyCustomGuards, PolicyModuleSource, WasmFormat, WasmGuardHandle,
    KNOWN_HOST_FUNCTIONS,
};
pub use runtime::{WasmGuard, WasmGuardRuntime};
#[cfg(feature = "wasmtime-runtime")]
pub use wiring::{build_guard_pipeline, load_wasm_guards};