Skip to main content

Crate afterburner

Crate afterburner 

Source
Expand description

§Afterburner

Sandboxed JavaScript runtime for Rust. One crate, one entry point.

use afterburner::Afterburner;
use serde_json::json;

let ab = Afterburner::new()?;
let id = ab.register("(d) => d.n + 1")?;
let out = ab.run(&id, &json!({ "n": 41 }))?;
assert_eq!(out, json!(42));

§Modes

  • Adaptive (default): first call runs via rquickjs (native, sub-microsecond); a background thread compiles the same script to WASM, and subsequent calls switch to the sandboxed Wasmtime path.
  • Native only: trusted code; sub-microsecond throughput, no sandbox.
  • WASM only: untrusted code; Wasmtime + QuickJS, capability gates via Manifold.
  • Threaded: N worker threads behind a single Afterburner. Hash-routed with Chase-Lev-style steal-when-idle, token-bucket admission, graceful drain. Enable via AfterburnerBuilder::threaded.

§Feature flags

featuredefaultunlocks
wasmyesWasmtime backend (WasmCombustor)
nativeyesrquickjs backend (NativeCombustor)
thrustyesmulti-threaded scheduler (ThrustEngine)
adaptivenodual-tier native → wasm auto-switch
flownoflow-engine glue (multi-module bundles)
host-httpnooutbound HTTP host function
binnoburn CLI binary deps (clap, rustyline)

§Capability gating

Every thrust carries a Manifold (via FuelGauge) that controls what host-backed modules (fs, crypto, net, env) the script can reach. Default is Manifold::sealed - nothing accessible.

Re-exports§

pub use polyglot::Outcome;
pub use afterburner_core as core;
pub use afterburner_node_compat as node_compat;
pub use afterburner_wasi as wasi;
pub use afterburner_ignite as ignite;
pub use afterburner_thrust as thrust_crate;

Modules§

native
Native backend - trusted code via rquickjs FFI.
polyglot
Unified polyglot facade: one entry point for every language.
prelude
Common imports, re-exported as a single glob target.
thrust
Multi-threaded scheduler.
wasm
WASM backend - untrusted code via Wasmtime + QuickJS plugin.

Structs§

Afterburner
One-stop entry point. Construct via Afterburner::new or Afterburner::builder.
AfterburnerBuilder
Configuration builder for Afterburner.
BurnCache
Thread-safe compile-or-cache wrapper over a Combustor. Identical sources produce exactly one compile across concurrent callers; losers of the insert race wait on the same OnceLock rather than issuing a duplicate ignite. Hit path is wait-free.
CallSite
Where in the guest source the effect was requested. Optional because not every substrate can attribute a call site.
FuelGauge
Execution resource limits applied per call. Each field is optional; None means “no cap on this dimension.”
HostEffect
The seam record: the identity of one effect the guest requested, byte safe. This is what a host inspects in HostContext::on_host_call to decide record vs serve.
HostEffectRecord
The request plus its recorded result. On the original run the substrate executes the real effect and hands back one of these; on replay the host returns a stored one and the substrate performs no real effect.
HttpResponse
Response returned from HostFunction::HttpRequest.
InMemoryStateStore
Default in-process backend backed by a lock-free HopscotchMap. Suitable for single-process deployments; not durable across restarts.
InProcessCacheBackend
In-process default backend - no network involvement, state lives in a single lock-free map. Equivalent to the pre-Phase-G behavior.
Manifold
A full capability profile for one script execution.
NullHost
Zero-capability host context - useful as a default for tests and for the minimal flow-engine path that only uses Log.
RegistryStats
Statistics the cache exposes for observability. Load-atomically; no snapshot guarantees across fields.
RunResult
Result of crate::engine::Combustor::run_with_result - a full run that also surfaces the typed return value.
ScriptId
Identifier returned by Combustor::ignite and consumed by thrust / extinguish. Content-addressed: the hash is SHA-256 of the JS source, so two identical sources produce the same ScriptId regardless of which Combustor compiled them.
ScriptInvocation
Input for crate::engine::Combustor::run_script - the script source plus Node-style process.argv and process.env values.
ScriptOutcome
Result of crate::engine::Combustor::run_script - top-level script-mode execution (no UDF envelope).
ThreadedBuilder
Builder for the multi-threaded Afterburner variant. Obtained via AfterburnerBuilder::threaded.

Enums§

AfterburnerError
Every failure mode Afterburner exposes to callers. Keep the set closed: callers match on it exhaustively.
EffectDetail
Op-specific detail for a HostEffect. Fs needs none (its FileOp is already in EffectKind::Fs); the other kinds carry their shape here.
EffectKind
The broad category of a side effect. Fs carries the concrete file operation inline; the raw op only - the effect class (idempotent, observed, mutating, …) is causarum’s concern and is deliberately not pre-baked here.
EffectStatus
The terminal status of a recorded effect. An error is carried as bytes, never a lossy String, so a non-UTF-8 error payload round-trips exactly.
EngineMode
Which backend produced a ScriptId. Useful for adaptive tier switching and for diagnostics; callers generally shouldn’t branch on this.
EnvAccess
Process-environment access for process.env and getenv.
FileOp
The raw filesystem operation. Raw op only - no pre-baked classification.
FsAccess
Filesystem capability. Roots are resolved via fs::canonicalize at call time; any path escape (via .., symlinks, etc.) outside the listed roots is rejected with AfterburnerError::PermissionDenied.
HostFunction
The full host-function set.
HttpMethod
HTTP method for HostFunction::HttpRequest. Present even when the host-http feature is off so the enum shape is stable.
Language
A source language supported by the afterburner runtime.
ListenAccess
Inbound listening capability - which ports daemon-mode servers (http.createServer().listen(port), the HTTP/3 listener) may bind. Checked by the listen host-calls before any socket bind; a denied port surfaces as PermissionDenied, exactly like outbound net and fs denials.
LogLevel
Log severity, mirroring console.* in JS.
Mode
Which backend AfterburnerBuilder::build should construct.
NetAccess
Outbound networking capability. Inbound listening is governed separately by ListenAccess - net models outbound only.
OutputTag
Which OutputValue shape a frame carries.
OutputValue
Result of an output-framing-aware invocation (thrust_out / thrust_raw_out) - the output-side mirror of the input framings.

Traits§

BurnCacheBackend
Pluggable storage for script source text, keyed by SHA-256 of the source. Enables distributed deployments where a single script is registered once on any node and replicated via an external coordinator (Redis, S3, NATS, etc.). Each node still compiles locally - the backend stores source text, not compiled modules, since the compiled form is engine-specific (wasmtime vs rquickjs) and not portably serializable today.
Combustor
The engine contract. Implementations must be Send + Sync so a single instance can back a shared BurnCache across threads.
HostContext
Callbacks the host provides to the script runtime. Implementations supply whichever methods are relevant; defaults are intentionally no-ops or None so minimal hosts (e.g. tests) don’t need to stub every variant.
Session
A stateful run session over a persistent, byte-exact filesystem root.
StateStore
Pluggable cross-invocation key/value storage.

Functions§

content_hash
BLAKE3 the given bytes: the canonical content-address for effect and output payloads. The frame carrier (crate::frame) and the effect seam (crate::effect) both use this one function, so a value carried as an output and the same bytes seen as a filesystem effect content-address identically (the record/replay parity crux). Distinct from sha256, which stays the source-address for a ScriptId.
decode_frame
Decode a frame, returning its tag and payload bytes.
decode_output_value
Decode a frame back into an OutputValue. A Json-tagged payload is parsed as JSON (a parse failure is loud); a Bytes-tagged payload is returned verbatim.
encode_frame
Encode payload into a self-verifying frame tagged kind.
encode_output_value
Encode an OutputValue into a frame. Json is carried as its canonical serialized text bytes, Bytes verbatim. The inverse of decode_output_value.
sha256
SHA-256 the given bytes. Shared helper so every engine hashes sources identically and ScriptIds round-trip between backends. This is the source-address (a ScriptId); the content-address for effect and output payloads is content_hash (BLAKE3).

Type Aliases§

Result
Convenience alias used across the workspace.
SharedStateStore
Convenience shared handle. The store is reference-counted and Arc<dyn StateStore> is what gets stashed in WasmCombustor / thread-local activator.