Module runtime 

Compiled WASM runtime (shared, immutable, thread-safe).

Architecture

• Runtime: Compiled WASM component. Thread-safe, shareable (Arc<Runtime>). Compile once, instantiate many times. Holds a pool of initialized Controllers for reuse. A Tokio semaphore caps checked-out controllers (in-flight use). Idle controllers in the pool release their semaphore permits so waiters can proceed; permits are re-acquired when a pooled controller is checked out again. max_pool_size bounds the pool size and the maximum concurrent instances.

• Controller: Per-execution instance. Single-threaded. Can be reused across invocations by swapping the host context between calls, preserving WASM linear memory (statics, heap).

Instance Reuse

Controllers are pooled inside the Runtime. Between invocations, the host InvocationContext (which carries per-request auth, permissions, KV store) is swapped out. The WASM linear memory persists, so Rust statics (OnceLock, etc.) survive across calls. Security is enforced by the host context, not by memory isolation — the module never sees user identity directly.

Concurrency Patterns

use std::sync::Arc;
use surrealism_runtime::{runtime::Runtime, package::SurrealismPackage};

// Compile once (expensive)
let runtime = Arc::new(Runtime::new(package, 8, None, None, None, None)?);

// For each concurrent request:
let runtime = runtime.clone();
tokio::spawn(async move {
    let context = Box::new(MyContext::new());
    let mut controller = runtime.acquire_controller(context).await?;
    let result = controller.invoke(None, args).await;
    // Return to pool on success; drop on trap
    if result.is_ok() {
        runtime.release_controller(controller);
    }
    result
});

Structs

Runtime

Compiled WASM runtime. Thread-safe, can be shared across threads via Arc. Compiles WASM once, then each controller gets its own isolated Store/Instance. Holds a pool of initialized controllers for reuse across invocations.