Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
runtrue-wasm-runtime
A Rust runtime for standard WebAssembly Components with cold, disk-AOT, warmish, and warm execution tiers.
| Property | Value |
|---|---|
| Status | 0.1 alpha |
| Platform | Linux x86_64 |
| Rust | 1.94 |
| Wasmtime | 46.0.3 |
| Primary WASI profile | 0.3 |
| Compatibility profile | 0.2 |
Supported components
The runtime accepts WebAssembly components exporting one supported standard world:
| Workload | WASI 0.3 | WASI 0.2 |
|---|---|---|
| Commands | wasi:cli/command |
wasi:cli/command |
| HTTP services | wasi:http/handler |
wasi:http/incoming-handler |
Native binaries, core Wasm modules, and components outside these worlds are rejected.
Optional WASIX features
wasixenables the isolated worker protocol with WASIX's minimal native system surface.wasix-checkpointadditionally enables the pinned native journal cohort required for checkpoint capture and replay. It is opt-in because the WASIX 0.701 journal is part of its broadersyspreset.
The checkpoint feature does not relax the worker trust boundary: guest input
is still withheld until the fresh worker reports the required compatibility
and Linux isolation state. On Linux 5.6 or newer, the host pins a trusted
regular worker inode with openat2, executes that descriptor with execveat,
and verifies the worker's self-reported executable SHA-256 before sending input.
Every Linux worker arms SIGKILL as its parent-death signal before exec and
checks for a parent-loss race, so a worker cannot continue when its immediate
runtime parent disappears. This protects the worker process itself; deployments
that permit native descendants must additionally use a cgroup whose lifecycle
is owned by the supervisor.
WasixWorkerConfig::with_worker_placement installs a synchronous, fail-closed
placement policy that runs with the fresh PID before the parent sends module,
checkpoint, request, or Execute bytes. A production scheduler can use it to
attach each invocation to a pre-created cgroup v2 and verify membership before
returning. A placement error kills and reaps the worker. The default config has
no placement policy and does not claim cgroup CPU, memory, PID, or descendant
containment; deployments requiring those controls must configure the policy.
restore_wasix_checkpoint accepts an authenticated checkpoint and its exact
module, starts a fresh isolated destination worker, and resumes without any
destination arguments. Restored arguments and process state come only from the
checkpoint journal. The destination waits for native WASIX thread-pool work to
quiesce and tears down its task runtime before returning independently bounded
guest stdout and stderr. Worker-process diagnostics are separately bounded and
redacted from ordinary Display and Debug error formatting; callers must
explicitly access them from a structured checkpoint restore failure. When a
failed worker exits before supervision terminates it, the same failure reports
its portable exit code or Unix termination signal.
capture_wasix_checkpoint starts a fresh isolated source worker with bounded
arguments and environment, stops at an explicit WASIX snapshot, and returns a
trusted journal for WasixCheckpointCodec::seal. Standard input is not yet
supported by the capture path. Worker-process diagnostics are concurrently
drained into a separate bounded buffer and redacted from ordinary Display and
Debug error formatting. Structured capture failures report their protocol
phase and, when observable, the worker exit code or Unix termination signal.
To move the checkpoint, authenticate the captured journal with
WasixCheckpointCodec, transfer the sealed artifact and exact module to the
destination, reopen the artifact, and pass it to restore_wasix_checkpoint.
Checkpoint format version 2 binds the artifact to the exact source worker
executable; the destination must run the byte-identical worker build. Drain
checkpoints before deploying a different worker binary.
The integration suite proves this flow with a Rust/WASIX program that captures
the argument 424242 in one worker and prints it after resuming in a different
worker without destination arguments.
Execution tiers
| Tier | Retained material | Work before execution |
|---|---|---|
Cold |
Source component | Validate and compile |
DiskAot |
Authenticated native AOT file | Read, authenticate, and deserialize |
Warmish |
AOT bytes in memory | Deserialize |
Warm |
Compiled component in memory | Create or reuse an eligible worker |
Loading a component schedules bounded background promotion when a Tokio runtime is available. Concurrent callers join the same preparation operation for a component digest.
Code tier and HTTP worker state are separate. A service reports whether it has no resident worker, an active worker, or a paused resident worker. Idle worker eviction can demote its code from warm to warmish.
Commands
Each command run gets a fresh Store, instance, resource table, WASI context, fuel budget, deadline, and I/O streams.
use ;
# async
HTTP services
Program::http_service creates a reusable standard WASI HTTP service:
# use ;
# async
HttpService::handleis the buffered function-style API.HttpService::handle_streamingaccepts standardhttp::Requestbodies and streams the response without rebuilding headers, the URI, or the body.
Both APIs enforce admission, worker reuse, request deadlines, body limits, and outbound capabilities. Outbound HTTP is denied unless an exact origin, method, network, and byte-limit grant is configured.
Run the included streaming HTTP/1 host with:
cargo run --release --example http_server
cargo run --release --example http_server -- service.wasm 127.0.0.1:8080
Telemetry
| API | Value |
|---|---|
service.startup_from() |
Tier before service preparation |
service.startup_prepare() |
Code-preparation time |
service.startup_total() |
Total service-construction time |
response.body().metadata() |
Request ID, tier at admission, worker creation, and time to headers |
service.state() |
Worker residency state |
service.metrics() |
Worker, eviction, in-flight, and completion counters |
Cold and disk-AOT are normally service-startup observations. Warm and warmish remain visible for each streaming request.
Pause and resume
Program::start returns a controllable command invocation. pause() retains
the same Store and guest state; resume() continues that invocation. A paused
invocation is evicted after RuntimeConfig::paused_resident_ttl, which defaults
to 30 seconds. Eviction returns Error::IdleEvicted; a later run starts a new
invocation.
Security
Components receive no ambient environment, arguments, filesystem, process handles, sockets, proxies, or credentials. Outbound HTTP is default-deny. AOT files are deserialized only after identity checks and HMAC authentication.
WASI capability restrictions are not an OS multi-tenant sandbox. Isolate mutually distrusting workloads in separate unprivileged processes or containers. See Security and Production isolation.
Benchmarks
Direct tier, TCP, capacity, and soak harnesses are under benchmarks/. Run
scripts through uv and retain raw JSON with every performance claim. See
Benchmark methodology and Performance
regressions.
Development
cargo fmt --all -- --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked --all-targets
scripts/release-check.sh
Additional documentation: