Crate afterburner 

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

feature	default	unlocks
wasm	yes	Wasmtime backend (WasmCombustor)
native	yes	rquickjs backend (NativeCombustor)
thrust	yes	multi-threaded scheduler (ThrustEngine)
adaptive	no	dual-tier native → wasm auto-switch
flow	no	flow-engine glue (multi-module bundles)
host-http	no	outbound HTTP host function
bin	no	burn 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 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.

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.

FuelGauge

Execution resource limits applied per call. Each field is optional; None means “no cap on this dimension.”

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.

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.

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.

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.

LogLevel

Log severity, mirroring console.* in JS.

Mode

Which backend AfterburnerBuilder::build should construct.

NetAccess

Outbound networking capability. Inbound/listening is never supported — Afterburner has no event loop and scripts are request/response shaped.

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.

StateStore

Pluggable cross-invocation key/value storage.

Functions

sha256

SHA-256 the given bytes. Shared helper so every engine hashes sources identically and ScriptIds round-trip between backends.

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.