fusabi-host

Shared host/runtime utilities for Fusabi across Scarab, Tolaria, Hibana, and Phage.

Features

• Engine Pools - Thread-safe engine pooling for concurrent script execution
• Value Conversion - Seamless Value↔Serde transformation helpers
• Typed Host Functions - Ergonomic macros for host function registration
• Sandbox & Capabilities - Fine-grained security controls for untrusted code
• Stable Compile/Run APIs - Consistent interfaces for host integration

Quick Start

use fusabi_host::{EnginePool, PoolConfig, Capabilities, Limits};

fn main() -> fusabi_host::Result<()> {
    // Create a pool with 4 engines
    let config = PoolConfig::new(4)
        .with_limits(Limits::default())
        .with_capabilities(Capabilities::safe_defaults());

    let pool = EnginePool::new(config)?;

    // Execute a script
    let result = pool.execute("1 + 2")?;
    println!("Result: {}", result);

    Ok(())
}

Feature Flags

Safety Model

Capabilities

Scripts must be granted explicit capabilities for privileged operations:

use fusabi_host::{Capabilities, Capability};

// No capabilities (fully sandboxed)
let none = Capabilities::none();

// Safe defaults (time, random, stdout, logging)
let safe = Capabilities::safe_defaults();

// Full access (use with trusted code only)
let all = Capabilities::all();

// Custom capability set
let custom = Capabilities::none()
    .with(Capability::FsRead)
    .with(Capability::NetRequest);

Resource Limits

Control resource consumption with configurable limits:

use fusabi_host::Limits;
use std::time::Duration;

let limits = Limits::default()
    .with_timeout(Duration::from_secs(5))
    .with_memory_mb(32)
    .with_max_instructions(1_000_000);

// Strict limits for untrusted code
let strict = Limits::strict();

// No limits (trusted code only)
let unlimited = Limits::unlimited();

Sandbox Configuration

Control filesystem and network access:

use fusabi_host::sandbox::{SandboxConfig, PathPolicy, NetPolicy};

let sandbox = SandboxConfig::locked()
    .with_read_paths(["/app/data"])
    .with_allowed_hosts(["api.example.com", "*.trusted.org"]);

Typed Host Functions

Register host functions with automatic argument conversion:

use fusabi_host::{host_fn, Engine, EngineConfig};

let mut engine = Engine::new(EngineConfig::default())?;

// Register a simple function
engine.registry_mut().register("add", host_fn!(add(a: i64, b: i64) -> i64 {
    a + b
}));

// Register with context access
engine.registry_mut().register("log", host_fn!(ctx, log(msg: String) -> () {
    ctx.record_output(msg.len())?;
    println!("{}", msg);
    Ok(())
}));

Compilation API

Compile Fusabi source to bytecode:

use fusabi_host::compile::{compile_source, compile_file, CompileOptions};

// Compile source string
let result = compile_source("fn main() { 42 }", &CompileOptions::default())?;
println!("Bytecode size: {} bytes", result.bytecode.len());

// Compile from file
let result = compile_file("script.fsx".as_ref(), &CompileOptions::production())?;

// Access metadata
for export in &result.metadata.exports {
    println!("Export: {}", export.name);
}

Version Compatibility

This crate is aligned with Fusabi LTS releases:

See compat.md for detailed compatibility information.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.