Trait Bridge

Source

pub trait Bridge: Send + Sync {
    // Required methods
    fn call(&self, api: &str, args: &[Value]) -> Result<Value, String>;
    fn get_property(
        &self,
        object: &str,
        property: &str,
    ) -> Result<Value, String>;
    fn set_property(
        &self,
        object: &str,
        property: &str,
        value: &Value,
    ) -> Result<(), String>;
    fn provided_globals(&self) -> Vec<String>;
    fn bootstrap_js(&self) -> String;
}

Expand description

The bridge interface between JavaScript and the host.

Consumers implement this trait to provide fake API surfaces. Sear implements browser bridges (document, window, navigator, fetch). Soleno implements Chrome extension bridges (chrome.tabs, chrome.cookies, etc.).

Every call through the bridge is observable — the sandbox records what function was called, with what arguments, and what was returned.

§Design

The bridge is intentionally stringly-typed. JS APIs are a massive surface and encoding every possible API as a Rust enum would be both fragile and incomplete. Instead, the bridge receives the API name as a string and the arguments as Vec<Value>. The consumer pattern-matches on the string.

§Thread safety

Bridge implementations must be Send + Sync because the sandbox may run on a different thread from the caller. For single-threaded use, wrap interior state in RefCell behind a Mutex.

Required Methods§

Source

fn call(&self, api: &str, args: &[Value]) -> Result<Value, String>

Handle a function call from JavaScript.

api is the fully qualified name: "document.createElement", "chrome.tabs.query", "fetch", etc.

Return Ok(value) to provide a return value to JS. Return Err(message) to throw a JS exception.

§Errors

Returns an error if the API throws a JS exception.

Source

fn get_property(&self, object: &str, property: &str) -> Result<Value, String>

Handle a property read from JavaScript.

object is the object name: "navigator", "document", "chrome.runtime". property is the property name: "userAgent", "cookie", "id".

§Errors

Returns an error if the property is undefined or reading it throws an exception.

Source

fn set_property( &self, object: &str, property: &str, value: &Value, ) -> Result<(), String>

Handle a property write from JavaScript.

§Errors

Returns an error if writing the property throws an exception.

Source

fn provided_globals(&self) -> Vec<String>

Return the list of global objects this bridge provides.

These become globalThis.{name} in the JS environment. Example: ["document", "window", "navigator", "fetch", "XMLHttpRequest"] Example: ["chrome"]

Source