WebAssembly Runtime

Extend TrailBase with custom server-side logic using WebAssembly components

Overview

TrailBase includes a powerful WebAssembly (WASM) runtime built on Wasmtime that allows you to extend your backend with custom server-side logic. The runtime supports the WebAssembly Component Model, enabling you to write components in multiple languages including Rust, JavaScript, and TypeScript.

Key Features

Custom HTTP Endpoints

Create custom API endpoints with full request/response control

Scheduled Jobs

Run background tasks on a cron schedule

Database Access

Query and modify your SQLite database directly from WASM

Multi-Language

Write components in Rust, JavaScript, TypeScript, or any language that compiles to WASM

Architecture

The WASM runtime consists of two main parts:

Host Runtime

Located in crates/wasm-runtime-host/, the host runtime:

• Compiles and loads WASM components using Wasmtime
• Provides sandboxed execution environment with configurable permissions
• Manages component lifecycle and hot-reloading
• Exposes host capabilities through WASI interfaces

let runtime = Runtime::init(
    wasm_component_path,
    store_builder,
    RuntimeOptions {
        fs_root_path: Some(PathBuf::from("/sandbox")),
        use_winch: false,
        tokio_runtime: None,
    },
)?;

Guest Runtime

Located in crates/wasm-runtime-guest/, the guest runtime provides:

• Type-safe API bindings for Rust, JavaScript, and TypeScript
• HTTP request/response handling
• Database query interface
• Job scheduling primitives
• Key-value store access
• Outbound HTTP fetch capabilities

Capabilities

Database Access

Components can query and modify the SQLite database:

Rust

use trailbase_wasm::db::{query, execute, Value};

let rows = query(
    "SELECT * FROM users WHERE age > $1",
    [Value::Integer(18)]
).await?;

let affected = execute(
    "UPDATE users SET verified = 1 WHERE id = $1",
    [Value::Integer(user_id)]
).await?;

import { query } from 'trailbase-wasm/db';

const rows = await query(
  'SELECT * FROM users WHERE age > $1',
  [18]
);

HTTP Fetch

Make outbound HTTP requests from your components:

Rust

use trailbase_wasm::fetch::{get, Request};

let data = get("https://api.example.com/data").await?;

import { fetch } from 'trailbase-wasm/fetch';

const response = await fetch('https://api.example.com/data');

Key-Value Store

Components have access to a shared key-value store:

Rust

use trailbase_wasm::kv;

kv::set("counter", vec![0, 0, 0, 42])?;
let value = kv::get("counter")?;

import { kv } from 'trailbase-wasm/kv';

kv.set('counter', new Uint8Array([42]));
const value = kv.get('counter');

Security & Sandboxing

WASM components run in a secure sandbox with:

• Memory isolation: Each component has its own linear memory
• Filesystem restrictions: Optional read-only access to a specified directory
• Network controls: No raw socket access, only HTTP through WASI interfaces
• Resource limits: Configurable memory reservation (default 64MB)

pub struct RuntimeOptions {
    /// Optional file-system sandbox root for r/o file access
    pub fs_root_path: Option<PathBuf>,
    
    /// Whether to use the non-optimizing baseline compiler
    pub use_winch: bool,
    
    /// Which tokio runtime handle to execute on
    pub tokio_runtime: Option<tokio::runtime::Handle>,
}

Component Discovery

TrailBase automatically discovers and loads WASM components from the components/ directory in your data directory:

pub fn find_wasm_components(components_path: impl AsRef<Path>) -> Vec<PathBuf> {
    // Finds all .wasm files in the components directory
}

Use Cases

Custom Business Logic

Implement complex validation, calculations, or workflows

Third-Party Integrations

Connect to external APIs and services

Data Processing

Transform and aggregate data before storage or retrieval

Server-Side Rendering

Generate dynamic HTML responses

Performance

The runtime is optimized for production use:

• Ahead-of-time compilation: Components are compiled once at startup
• Caching: Compiled components are cached to disk
• Parallel compilation: Utilizes all available CPU cores during compilation
• Efficient instantiation: Fast component instantiation for request handling

log::info!("Compiling: {wasm_source_file:?}. May take some time...");

let component = wasmtime::CodeBuilder::new(&engine)
    .wasm_binary_or_text_file(&wasm_source_file)?
    .compile_component()?;

component.initialize_copy_on_write_image()?;

Next Steps

WASM Components

Learn how to create WASM components

Custom Endpoints

Build custom HTTP endpoints

Server-Side Rendering

Render dynamic HTML with WASM

Jobs Scheduler

Schedule background tasks