oxide_browser/

runtime.rs

//! Guest WebAssembly lifecycle for the Oxide browser.
//!
//! This module coordinates fetching `.wasm` binaries (HTTP/HTTPS and `file://`), compiling them
//! with Wasmtime, applying the sandbox policy, and linking the `oxide` import module (memory,
//! host capabilities). After `start_app()` runs, interactive guests may export `on_frame(dt_ms:
//! u32)` for a per-frame render loop; optional `on_timer(callback_id: u32)` callbacks run when
//! timers expire, immediately before each frame.

use std::sync::{Arc, Mutex};

use anyhow::{Context, Result};
use wasmtime::*;

use crate::bookmarks::BookmarkStore;
use crate::capabilities::{
    drain_animation_frame_requests, drain_expired_timers, register_host_functions, HostState,
};
use crate::engine::{ModuleLoader, SandboxPolicy, WasmEngine};
use crate::events::{drain_pending_events, set_current_event};
use crate::history::HistoryStore;
use crate::url::OxideUrl;

/// Current lifecycle state of a browser tab, reflected in the UI and shared across threads.
#[derive(Clone, Debug, PartialEq)]
pub enum PageStatus {
    /// No navigation in progress; ready for a new load.
    Idle,
    /// A URL is being resolved and the `.wasm` module fetched or read (the string is the URL or path being loaded).
    Loading(String),
    /// Guest code is active after a successful load; the string identifies the page (URL or a local placeholder).
    Running(String),
    /// Load, compile, or `start_app` failed; the string is a human-readable error message.
    Error(String),
}

const FRAME_FUEL_LIMIT: u64 = 50_000_000;

/// A Wasmtime [`Store`] and typed guest exports kept alive across frames for interactive apps.
///
/// Constructed when the module exports `on_frame`. The store holds [`HostState`] (canvas, console,
/// timers, animation requests, etc.) for the lifetime of the tab.
pub struct LiveModule {
    store: Store<HostState>,
    on_frame_fn: TypedFunc<u32, ()>,
    on_timer_fn: Option<TypedFunc<u32, ()>>,
    on_event_fn: Option<TypedFunc<u32, ()>>,
}

impl LiveModule {
    /// Advances one frame: drains animation frame requests and expired timers (both invoke
    /// `on_timer(callback_id)`), then calls `on_frame(dt_ms)`.
    ///
    /// Animation requests (from `request_animation_frame`) are one-shot and fire every frame
    /// they are queued. All callbacks run with bounded fuel. Errors are logged to console.
    pub fn tick(&mut self, dt_ms: u32) -> Result<()> {
        // Event dispatch first: gives the guest a chance to react to resize,
        // input, and custom events before the next frame is composed.
        if let Some(ref on_event) = self.on_event_fn {
            let data = self.store.data();
            let canvas_size = {
                let c = data.canvas.lock().unwrap();
                (c.width, c.height)
            };
            let focused = data.focused.load(std::sync::atomic::Ordering::Relaxed);
            let (mouse_down, mouse_pos) = {
                let i = data.input_state.lock().unwrap();
                (i.mouse_buttons_down[0], (i.mouse_x, i.mouse_y))
            };
            let events = data.events.clone();
            let pending =
                drain_pending_events(&events, canvas_size, focused, mouse_down, mouse_pos);
            for (callback_id, evt_type, evt_data) in pending {
                set_current_event(&events, evt_type.clone(), evt_data);
                self.store
                    .set_fuel(FRAME_FUEL_LIMIT)
                    .context("failed to set event fuel")?;
                if let Err(e) = on_event.call(&mut self.store, callback_id) {
                    let msg = if e.to_string().contains("fuel") {
                        format!("on_event({evt_type}:{callback_id}) fuel limit exceeded")
                    } else {
                        format!("on_event({evt_type}:{callback_id}) trapped: {e}")
                    };
                    crate::capabilities::console_log(
                        &self.store.data().console,
                        crate::capabilities::ConsoleLevel::Error,
                        msg,
                    );
                }
            }
        }

        if let Some(ref on_timer) = self.on_timer_fn {
            // Animation frames first (vsync-aligned, one-shot).
            let anim = self.store.data().animation_requests.clone();
            let fired_anim = drain_animation_frame_requests(&anim);
            for callback_id in fired_anim {
                self.store
                    .set_fuel(FRAME_FUEL_LIMIT)
                    .context("failed to set animation frame fuel")?;
                if let Err(e) = on_timer.call(&mut self.store, callback_id) {
                    let msg = if e.to_string().contains("fuel") {
                        format!("on_timer(raf:{callback_id}) fuel limit exceeded")
                    } else {
                        format!("on_timer(raf:{callback_id}) trapped: {e}")
                    };
                    crate::capabilities::console_log(
                        &self.store.data().console,
                        crate::capabilities::ConsoleLevel::Error,
                        msg,
                    );
                }
            }

            // Regular timers.
            let timers = self.store.data().timers.clone();
            let fired = drain_expired_timers(&timers);
            for callback_id in fired {
                self.store
                    .set_fuel(FRAME_FUEL_LIMIT)
                    .context("failed to set timer fuel")?;
                if let Err(e) = on_timer.call(&mut self.store, callback_id) {
                    let msg = if e.to_string().contains("fuel") {
                        format!("on_timer({callback_id}) fuel limit exceeded")
                    } else {
                        format!("on_timer({callback_id}) trapped: {e}")
                    };
                    crate::capabilities::console_log(
                        &self.store.data().console,
                        crate::capabilities::ConsoleLevel::Error,
                        msg,
                    );
                }
            }
        }

        self.store
            .set_fuel(FRAME_FUEL_LIMIT)
            .context("failed to set per-frame fuel")?;
        self.on_frame_fn
            .call(&mut self.store, dt_ms)
            .context("on_frame trapped")?;
        Ok(())
    }
}

/// Main host-side entry point: Wasmtime engine, shared tab status, and guest-facing host state.
///
/// Use [`BrowserHost::new`] on the UI thread, then [`BrowserHost::fetch_and_run`] or
/// [`BrowserHost::run_bytes`] to load modules. [`BrowserHost::recreate`] builds a second host
/// that shares [`HostState`] and [`PageStatus`] for background workers.
pub struct BrowserHost {
    wasm_engine: WasmEngine,
    /// Latest [`PageStatus`] for this tab, safe to share with worker threads via [`Arc`] and [`Mutex`].
    pub status: Arc<Mutex<PageStatus>>,
    /// Sandbox resources and host imports: module loader, KV/bookmarks, canvas, timers, console, etc.
    pub host_state: HostState,
}

impl BrowserHost {
    /// Creates a new host with default [`SandboxPolicy`], a persistent KV store under the platform
    /// data directory, and an initialized [`BookmarkStore`].
    pub fn new() -> Result<Self> {
        let policy = SandboxPolicy::default();
        let wasm_engine = WasmEngine::new(policy.clone())?;

        let loader = Arc::new(ModuleLoader {
            engine: wasm_engine.engine().clone(),
            max_memory_pages: policy.max_memory_pages,
            fuel_limit: policy.fuel_limit,
        });

        let kv_path = dirs::data_dir()
            .unwrap_or_else(|| std::path::PathBuf::from("."))
            .join("oxide")
            .join("kv_store.db");
        let kv_db = sled::open(&kv_path)
            .with_context(|| format!("failed to open KV store at {}", kv_path.display()))?;

        let kv_db = Arc::new(kv_db);

        let bookmark_store =
            BookmarkStore::open(&kv_db).context("failed to initialize bookmark store")?;
        let history_store =
            HistoryStore::open(&kv_db).context("failed to initialize history store")?;

        let host_state = HostState {
            module_loader: Some(loader),
            kv_db: Some(kv_db.clone()),
            bookmark_store: Arc::new(Mutex::new(Some(bookmark_store))),
            history_store: Arc::new(Mutex::new(Some(history_store))),
            ..Default::default()
        };

        Ok(Self {
            wasm_engine,
            status: Arc::new(Mutex::new(PageStatus::Idle)),
            host_state,
        })
    }

    /// Re-creates a [`BrowserHost`] that shares the given [`HostState`] and [`PageStatus`].
    ///
    /// Used when worker threads need their own [`WasmEngine`] / Wasmtime instance while keeping
    /// bookmarks, KV, canvas handles, and tab status in sync with the main host.
    pub fn recreate(mut host_state: HostState, status: Arc<Mutex<PageStatus>>) -> Self {
        let policy = SandboxPolicy::default();
        let wasm_engine = WasmEngine::new(policy.clone()).expect("failed to create engine");

        if host_state.module_loader.is_none() {
            host_state.module_loader = Some(Arc::new(ModuleLoader {
                engine: wasm_engine.engine().clone(),
                max_memory_pages: policy.max_memory_pages,
                fuel_limit: policy.fuel_limit,
            }));
        }

        Self {
            wasm_engine,
            status,
            host_state,
        }
    }

    /// Fetches a `.wasm` from `url`, compiles it, links the `oxide` imports, runs `start_app()`,
    /// and returns a [`LiveModule`] if the guest exports `on_frame`.
    ///
    /// Updates [`PageStatus`] to [`PageStatus::Loading`] then [`PageStatus::Running`] on success.
    /// Supports `http`/`https` (network fetch) and `file://` (local read) via [`OxideUrl`] parsing;
    /// other schemes error.
    pub async fn fetch_and_run(&mut self, url: &str) -> Result<Option<LiveModule>> {
        let url = resolve_wasm_url(url);
        *self.status.lock().unwrap() = PageStatus::Loading(url.to_string());
        self.host_state.canvas.lock().unwrap().commands.clear();
        self.host_state.console.lock().unwrap().clear();
        self.host_state.hyperlinks.lock().unwrap().clear();
        *self.host_state.current_url.lock().unwrap() = url.to_string();

        let parsed = OxideUrl::parse(&url).map_err(|e| anyhow::anyhow!("{e}"))?;

        let wasm_bytes = if parsed.is_fetchable() {
            fetch_wasm(parsed.as_str()).await?
        } else if parsed.is_local_file() {
            let path = parsed
                .to_file_path()
                .ok_or_else(|| anyhow::anyhow!("cannot convert file URL to path: {url}"))?;
            std::fs::read(&path)
                .with_context(|| format!("failed to read local file: {}", path.display()))?
        } else if parsed.is_internal() {
            anyhow::bail!("oxide:// internal pages are not yet implemented");
        } else {
            anyhow::bail!("unsupported URL scheme: {}", parsed.scheme());
        };

        // Optional sibling manifest (app.wasm → app.toml): metadata + declared permissions.
        let manifest = match crate::manifest::fetch_manifest(&parsed).await {
            Ok(m) => m,
            Err(e) => {
                crate::capabilities::console_log(
                    &self.host_state.console,
                    crate::capabilities::ConsoleLevel::Warn,
                    format!("[MANIFEST] {e} — loading app without a manifest"),
                );
                None
            }
        };
        *self.host_state.manifest.lock().unwrap() = manifest;

        *self.status.lock().unwrap() = PageStatus::Running(url.to_string());

        self.run_module(&wasm_bytes)
    }

    /// Compiles and runs `wasm_bytes` like [`fetch_and_run`](Self::fetch_and_run), but without a
    /// network fetch—useful for in-memory or locally read modules.
    ///
    /// `source_url` and `manifest` are set on the shared [`HostState`] before the module runs,
    /// so a reused `BrowserHost` never scopes storage or permissions to the *previous* app's
    /// origin/manifest. Pass a `file://` URL for picked files or a synthetic identifier (e.g.
    /// `oxide://forge/run/<slug>`) for in-memory modules.
    ///
    /// Sets [`PageStatus::Running`] with `source_url` (or `"(local)"` when empty). Returns
    /// `Some` with a [`LiveModule`] when `on_frame` is exported, otherwise [`None`].
    pub fn run_bytes(
        &mut self,
        wasm_bytes: &[u8],
        source_url: &str,
        manifest: Option<crate::manifest::AppManifest>,
    ) -> Result<Option<LiveModule>> {
        self.host_state.canvas.lock().unwrap().commands.clear();
        self.host_state.console.lock().unwrap().clear();
        self.host_state.hyperlinks.lock().unwrap().clear();
        *self.host_state.current_url.lock().unwrap() = source_url.to_string();
        *self.host_state.manifest.lock().unwrap() = manifest;
        let label = if source_url.is_empty() {
            "(local)".to_string()
        } else {
            source_url.to_string()
        };
        *self.status.lock().unwrap() = PageStatus::Running(label);
        self.run_module(wasm_bytes)
    }

    fn run_module(&mut self, wasm_bytes: &[u8]) -> Result<Option<LiveModule>> {
        // Capture the app origin for storage/permission scoping. Done once per load so guest
        // `push_state` calls (which mutate `current_url`) can't shift the origin afterwards.
        {
            let url = self.host_state.current_url.lock().unwrap().clone();
            crate::capabilities::set_module_origin(&self.host_state, &url);
        }

        let module = self.wasm_engine.compile_module(wasm_bytes)?;

        let mut linker = Linker::new(self.wasm_engine.engine());
        register_host_functions(&mut linker)?;

        let mut host_state = self.host_state.clone();
        let mut store = self.wasm_engine.create_store(host_state.clone())?;

        let memory = self.wasm_engine.create_bounded_memory(&mut store)?;
        linker.define(&store, "oxide", "memory", memory)?;

        host_state.memory = Some(memory);
        *store.data_mut() = host_state;

        let instance = linker
            .instantiate(&mut store, &module)
            .context("failed to instantiate wasm module")?;

        if let Some(guest_mem) = instance.get_memory(&mut store, "memory") {
            store.data_mut().memory = Some(guest_mem);
        }

        let start_app = instance
            .get_typed_func::<(), ()>(&mut store, "start_app")
            .context("module must export `start_app` as extern \"C\" fn()")?;

        match start_app.call(&mut store, ()) {
            Ok(()) => {
                if let Ok(on_frame_fn) = instance.get_typed_func::<u32, ()>(&mut store, "on_frame")
                {
                    let on_timer_fn = instance
                        .get_typed_func::<u32, ()>(&mut store, "on_timer")
                        .ok();
                    let on_event_fn = instance
                        .get_typed_func::<u32, ()>(&mut store, "on_event")
                        .ok();
                    Ok(Some(LiveModule {
                        store,
                        on_frame_fn,
                        on_timer_fn,
                        on_event_fn,
                    }))
                } else {
                    Ok(None)
                }
            }
            Err(e) => {
                let msg = if e.to_string().contains("fuel") {
                    "Execution halted: fuel limit exceeded (possible infinite loop)".to_string()
                } else {
                    format!("Runtime error: {e}")
                };
                *self.status.lock().unwrap() = PageStatus::Error(msg.clone());
                Err(anyhow::anyhow!(msg))
            }
        }
    }
}

/// If the URL path doesn't already end with `.wasm`, treat it as a directory
/// and append `/index.wasm` (like `index.html` in a traditional web server).
fn resolve_wasm_url(url: &str) -> String {
    let trimmed = url.trim();
    if trimmed.is_empty() {
        return trimmed.to_string();
    }
    let path_part = if let Some(pos) = trimmed.find("://") {
        &trimmed[pos + 3..]
    } else {
        trimmed
    };
    let path = if let Some(slash) = path_part.find('/') {
        &path_part[slash..]
    } else {
        "/"
    };
    let path_no_query = path.split('?').next().unwrap_or(path);
    let path_no_frag = path_no_query.split('#').next().unwrap_or(path_no_query);

    if path_no_frag.ends_with(".wasm") {
        return trimmed.to_string();
    }

    let base = trimmed.trim_end_matches('/');
    format!("{base}/index.wasm")
}

/// Maximum size of a `.wasm` module that can be fetched over the network.
const MAX_WASM_MODULE_SIZE: u64 = 50 * 1024 * 1024; // 50 MB

async fn fetch_wasm(url: &str) -> Result<Vec<u8>> {
    let client = reqwest::Client::builder()
        .timeout(std::time::Duration::from_secs(30))
        .build()
        .context("failed to build HTTP client")?;

    let response = client
        .get(url)
        .header("Accept", "application/wasm")
        .send()
        .await
        .context("network request failed")?;

    if !response.status().is_success() {
        anyhow::bail!("server returned HTTP {} for {}", response.status(), url);
    }

    // Reject responses with an obviously wrong Content-Type.
    if let Some(ct) = response.headers().get("content-type") {
        let ct_str = ct.to_str().unwrap_or("");
        if !ct_str.is_empty()
            && !ct_str.contains("application/wasm")
            && !ct_str.contains("application/octet-stream")
        {
            anyhow::bail!("unexpected Content-Type for .wasm module: {ct_str}");
        }
    }

    // Enforce size limit early via Content-Length when available.
    if let Some(len) = response.content_length() {
        anyhow::ensure!(
            len <= MAX_WASM_MODULE_SIZE,
            "module too large ({len} bytes, limit is {MAX_WASM_MODULE_SIZE})"
        );
    }

    let bytes = response
        .bytes()
        .await
        .context("failed to read response body")?;

    // Content-Length can be absent or spoofed, so check actual size too.
    anyhow::ensure!(
        (bytes.len() as u64) <= MAX_WASM_MODULE_SIZE,
        "module body exceeds size limit ({} bytes)",
        bytes.len()
    );

    Ok(bytes.to_vec())
}