@mobrowser/native 2.17.0 → 2.18.0

package/README.md

@@ -1 +1,2 @@
-This package contains the configuration files for MōBrowser native integration.
+This package contains the configuration files for MōBrowser native integration: the CMake toolchain
+and headers for C++ modules, and the `mobrowser` and `mobrowser-build` crates for Rust modules.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mobrowser/native",
-  "version": "2.17.0",
+  "version": "2.18.0",
   "description": "Configuration files for MōBrowser native integration",
   "mobrowserSbomRelationship": "BUILD_DEPENDENCY_OF",
   "main": "cmake/MoBrowser.cmake",
@@ -11,7 +11,11 @@
     "cmake/ProtobufCompat.cmake",
     "cmake/ProtobufDownload.cmake",
     "include",
-    "internal"
+    "internal",
+    "rust/mobrowser/Cargo.toml",
+    "rust/mobrowser/src",
+    "rust/mobrowser-build/Cargo.toml",
+    "rust/mobrowser-build/src"
   ],
   "keywords": [
     "mobrowser",

package/rust/mobrowser/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "mobrowser"
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.85"
+description = "MōBrowser native module runtime"
+publish = false
+
+[dependencies]
+prost = "0.14"
+prost-types = "0.14"
+tokio = { version = "1", default-features = false, features = ["rt-multi-thread"] }

package/rust/mobrowser/src/ffi.rs

@@ -0,0 +1,104 @@
+// Copyright (c) 2000-2026 TeamDev. All rights reserved.
+// TeamDev PROPRIETARY and CONFIDENTIAL.
+// Use is subject to license terms.
+
+//! The C ABI between MōBrowser and the native module. Used by [`crate::main!`].
+
+use std::any::Any;
+use std::borrow::Cow;
+use std::cell::RefCell;
+use std::ffi::{c_char, CStr};
+use std::panic::{catch_unwind, AssertUnwindSafe};
+use std::sync::Once;
+
+use crate::responder::Responder;
+use crate::transport;
+
+pub type ReplyCallback = unsafe extern "C" fn(id: u64, data: *const c_char, size: usize);
+pub type RejectCallback = unsafe extern "C" fn(id: u64, error: *const c_char);
+pub type HostInvokeCallback = unsafe extern "C" fn(
+    id: u64,
+    service: *const c_char,
+    method: *const c_char,
+    data: *const c_char,
+    size: usize,
+    reply: ReplyCallback,
+    reject: RejectCallback,
+);
+
+thread_local! {
+    static LAST_PANIC: RefCell<String> = const { RefCell::new(String::new()) };
+}
+
+/// Records each panic's message for the rejection of the call it aborts,
+/// keeping the previous hook, which reports it.
+fn install_panic_hook() {
+    static ONCE: Once = Once::new();
+    ONCE.call_once(|| {
+        let previous = std::panic::take_hook();
+        std::panic::set_hook(Box::new(move |info| {
+            let message = panic_message(info.payload());
+            LAST_PANIC.with(|last| message.clone_into(&mut last.borrow_mut()));
+            previous(info);
+        }));
+    });
+}
+
+pub(crate) fn panic_message(payload: &(dyn Any + Send)) -> &str {
+    payload
+        .downcast_ref::<&str>()
+        .copied()
+        .or_else(|| payload.downcast_ref::<String>().map(String::as_str))
+        .unwrap_or("unknown panic")
+}
+
+pub(crate) fn last_panic_message() -> String {
+    LAST_PANIC.with(|last| last.borrow().clone())
+}
+
+pub fn app_main(launch: fn()) {
+    install_panic_hook();
+    if let Err(panic) = catch_unwind(launch) {
+        transport::set_launch_error(format!("panic: {}", panic_message(&*panic)));
+    }
+}
+
+/// # Safety
+///
+/// `service` and `method` must be valid C strings and `data` must point to
+/// `size` readable bytes, all for the duration of the call.
+pub unsafe fn invoke(
+    id: u64,
+    service: *const c_char,
+    method: *const c_char,
+    data: *const c_char,
+    size: usize,
+    reply: ReplyCallback,
+    reject: RejectCallback,
+) {
+    install_panic_hook();
+    let responder = Responder::new(id, reply, reject);
+    let service = unsafe { c_str(service) };
+    let method = unsafe { c_str(method) };
+    let data = if data.is_null() || size == 0 {
+        &[]
+    } else {
+        unsafe { std::slice::from_raw_parts(data.cast::<u8>(), size) }
+    };
+    // A panicking handler drops the responder while unwinding, which rejects
+    // the call with the panic message.
+    let _ =
+        catch_unwind(AssertUnwindSafe(|| transport::invoke(&service, &method, data, responder)));
+}
+
+pub fn set_host_invoke(host_invoke: Option<HostInvokeCallback>) {
+    install_panic_hook();
+    transport::set_host_invoke(host_invoke);
+}
+
+unsafe fn c_str<'a>(s: *const c_char) -> Cow<'a, str> {
+    if s.is_null() {
+        return Cow::Borrowed("");
+    }
+    unsafe { CStr::from_ptr(s) }.to_string_lossy()
+}

package/rust/mobrowser/src/lib.rs

@@ -0,0 +1,103 @@
+// Copyright (c) 2000-2026 TeamDev. All rights reserved.
+// TeamDev PROPRIETARY and CONFIDENTIAL.
+// Use is subject to license terms.
+
+//! Runtime for MōBrowser native modules written in Rust.
+//!
+//! The module is a `cdylib` named `mobrowser_client` that MōBrowser loads on
+//! startup. Declare the entry point with [`main!`], register services in it with
+//! [`register_service`], and include the code generated by `mobrowser-build`
+//! with [`include_proto!`]:
+//!
+//! ```ignore
+//! mod proto {
+//!     mobrowser::include_proto!();
+//! }
+//!
+//! mobrowser::main!(launch);
+//!
+//! fn launch() {
+//!     mobrowser::register_service(proto::GreetServiceServer::new(Greeter));
+//! }
+//! ```
+//!
+//! Service methods are `async fn`s that run on the Tokio [`runtime`].
+
+mod oneshot;
+mod responder;
+mod transport;
+
+pub mod runtime;
+
+#[doc(hidden)]
+pub mod ffi;
+
+pub use responder::Responder;
+pub use transport::{register_service, request};
+
+pub use prost;
+pub use prost_types;
+pub use tokio;
+
+/// A native service the main process can call.
+///
+/// Implemented by the `<Name>Server` wrappers that `mobrowser-build` generates;
+/// there is no need to implement it by hand.
+pub trait Service: Send + Sync + 'static {
+    /// The fully qualified Protobuf name of the service, `package.Service`.
+    fn full_name(&self) -> &'static str;
+
+    /// Decodes `data` as the request of `method` and dispatches it. The
+    /// `responder` is completed or rejected exactly once.
+    fn call(&self, method: &str, data: &[u8], responder: Responder);
+}
+
+/// Includes the Rust code that `mobrowser-build` generated from the project's
+/// `.proto` files. Messages and services of a `.proto` without a `package` end
+/// up at the top level; the others in a module per package.
+#[macro_export]
+macro_rules! include_proto {
+    () => {
+        include!(concat!(env!("OUT_DIR"), "/mobrowser_proto.rs"));
+    };
+}
+
+/// Exports the entry points MōBrowser looks up in the native module and makes
+/// `$launch` the function it calls once, on startup.
+///
+/// Must be invoked exactly once, in the root of the `mobrowser_client` crate.
+#[macro_export]
+macro_rules! main {
+    ($launch:path) => {
+        #[unsafe(no_mangle)]
+        pub extern "C" fn AppMain() {
+            $crate::ffi::app_main($launch);
+        }
+
+        /// # Safety
+        ///
+        /// Called by MōBrowser with valid C strings and a buffer of `size` bytes.
+        #[unsafe(no_mangle)]
+        pub unsafe extern "C" fn invoke(
+            id: u64,
+            service: *const ::std::ffi::c_char,
+            method: *const ::std::ffi::c_char,
+            data: *const ::std::ffi::c_char,
+            size: usize,
+            reply: $crate::ffi::ReplyCallback,
+            reject: $crate::ffi::RejectCallback,
+        ) {
+            unsafe { $crate::ffi::invoke(id, service, method, data, size, reply, reject) }
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "C" fn set_host_invoke(
+            host_invoke: ::std::option::Option<$crate::ffi::HostInvokeCallback>,
+        ) {
+            $crate::ffi::set_host_invoke(host_invoke);
+        }
+    };
+}
+
+#[cfg(test)]
+mod tests;

package/rust/mobrowser/src/oneshot.rs

@@ -0,0 +1,65 @@
+// Copyright (c) 2000-2026 TeamDev. All rights reserved.
+// TeamDev PROPRIETARY and CONFIDENTIAL.
+// Use is subject to license terms.
+
+//! A minimal, runtime-agnostic one-shot channel.
+
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
+use std::task::{Context, Poll, Waker};
+
+struct Shared<T> {
+    value: Option<T>,
+    closed: bool,
+    waker: Option<Waker>,
+}
+
+pub(crate) struct Sender<T>(Arc<Mutex<Shared<T>>>);
+
+/// Resolves to the sent value, or to `None` if the sender was dropped without
+/// sending.
+pub(crate) struct Receiver<T>(Arc<Mutex<Shared<T>>>);
+
+pub(crate) fn channel<T>() -> (Sender<T>, Receiver<T>) {
+    let shared = Arc::new(Mutex::new(Shared { value: None, closed: false, waker: None }));
+    (Sender(shared.clone()), Receiver(shared))
+}
+
+fn lock<T>(shared: &Mutex<Shared<T>>) -> MutexGuard<'_, Shared<T>> {
+    shared.lock().unwrap_or_else(PoisonError::into_inner)
+}
+
+impl<T> Sender<T> {
+    pub(crate) fn send(self, value: T) {
+        lock(&self.0).value = Some(value);
+    }
+}
+
+impl<T> Drop for Sender<T> {
+    fn drop(&mut self) {
+        let mut shared = lock(&self.0);
+        shared.closed = true;
+        let waker = shared.waker.take();
+        drop(shared);
+        if let Some(waker) = waker {
+            waker.wake();
+        }
+    }
+}
+
+impl<T> Future for Receiver<T> {
+    type Output = Option<T>;
+
+    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<T>> {
+        let mut shared = lock(&self.0);
+        if let Some(value) = shared.value.take() {
+            Poll::Ready(Some(value))
+        } else if shared.closed {
+            Poll::Ready(None)
+        } else {
+            shared.waker = Some(cx.waker().clone());
+            Poll::Pending
+        }
+    }
+}

package/rust/mobrowser/src/responder.rs

@@ -0,0 +1,63 @@
+// Copyright (c) 2000-2026 TeamDev. All rights reserved.
+// TeamDev PROPRIETARY and CONFIDENTIAL.
+// Use is subject to license terms.
+
+use std::ffi::{c_char, CString};
+
+use crate::ffi::{self, RejectCallback, ReplyCallback};
+
+const CANCELED: &str = "RPC canceled: callback destroyed without completion.";
+
+/// The untyped, one-shot reply channel of a single call from the main process.
+///
+/// Dropping it without replying rejects the call.
+pub struct Responder {
+    id: u64,
+    handlers: Option<(ReplyCallback, RejectCallback)>,
+}
+
+impl Responder {
+    pub(crate) fn new(id: u64, reply: ReplyCallback, reject: RejectCallback) -> Self {
+        Self { id, handlers: Some((reply, reject)) }
+    }
+
+    /// Completes the call with a serialized response.
+    pub fn reply(mut self, data: &[u8]) {
+        if let Some((reply, _)) = self.handlers.take() {
+            // The host copies the bytes before returning.
+            let ptr = if data.is_empty() { b"".as_ptr() } else { data.as_ptr() };
+            unsafe { reply(self.id, ptr.cast::<c_char>(), data.len()) };
+        }
+    }
+
+    /// Fails the call with an error message.
+    pub fn reject(mut self, error: impl AsRef<str>) {
+        self.reject_with(error.as_ref());
+    }
+
+    fn reject_with(&mut self, error: &str) {
+        if let Some((_, reject)) = self.handlers.take() {
+            let error = to_cstring(error);
+            unsafe { reject(self.id, error.as_ptr()) };
+        }
+    }
+}
+
+impl Drop for Responder {
+    fn drop(&mut self) {
+        if self.handlers.is_none() {
+            return;
+        }
+        if std::thread::panicking() {
+            let message = format!("panic: {}", ffi::last_panic_message());
+            self.reject_with(&message);
+        } else {
+            self.reject_with(CANCELED);
+        }
+    }
+}
+
+/// Converts `s` to a C string, replacing interior NULs that would truncate it.
+pub(crate) fn to_cstring(s: &str) -> CString {
+    CString::new(s.replace('\0', "\u{FFFD}")).expect("NULs were replaced")
+}

package/rust/mobrowser/src/runtime.rs

@@ -0,0 +1,66 @@
+// Copyright (c) 2000-2026 TeamDev. All rights reserved.
+// TeamDev PROPRIETARY and CONFIDENTIAL.
+// Use is subject to license terms.
+
+//! The Tokio runtime that async service methods run on.
+
+use std::future::Future;
+use std::panic::{catch_unwind, AssertUnwindSafe};
+use std::sync::OnceLock;
+use std::task::Poll;
+
+use tokio::runtime::{Builder, Handle};
+
+use crate::ffi::panic_message;
+use crate::Responder;
+
+static HANDLE: OnceLock<Handle> = OnceLock::new();
+
+/// Makes async service methods run on the runtime of `handle` instead of the
+/// one MōBrowser creates. Call it in the entry point, before registering
+/// services. Fails with `handle` if a runtime is already in use.
+pub fn set_handle(handle: Handle) -> Result<(), Handle> {
+    HANDLE.set(handle)
+}
+
+/// The runtime async service methods run on: the one passed to [`set_handle`],
+/// or a multi-threaded runtime created on first use.
+pub fn handle() -> &'static Handle {
+    HANDLE.get_or_init(|| {
+        let runtime = Builder::new_multi_thread()
+            .enable_all()
+            .thread_name("mobrowser-tokio")
+            .build()
+            .expect("failed to start the Tokio runtime");
+        let handle = runtime.handle().clone();
+        // Keep the runtime until the process exits.
+        std::mem::forget(runtime);
+        handle
+    })
+}
+
+/// Runs `future` on the runtime and completes the call with its result. A panic
+/// in `future` rejects the call with `panic: <message>`.
+#[doc(hidden)]
+pub fn spawn_call<T, F>(future: F, responder: Responder)
+where
+    T: prost::Message,
+    F: Future<Output = Result<T, String>> + Send + 'static,
+{
+    let mut future = Box::pin(future);
+    handle().spawn(async move {
+        let result = std::future::poll_fn(|cx| {
+            match catch_unwind(AssertUnwindSafe(|| future.as_mut().poll(cx))) {
+                Ok(Poll::Pending) => Poll::Pending,
+                Ok(Poll::Ready(result)) => Poll::Ready(Ok(result)),
+                Err(panic) => Poll::Ready(Err(panic)),
+            }
+        })
+        .await;
+        match result {
+            Ok(Ok(response)) => responder.reply(&response.encode_to_vec()),
+            Ok(Err(error)) => responder.reject(error),
+            Err(panic) => responder.reject(format!("panic: {}", panic_message(&*panic))),
+        }
+    });
+}

package/rust/mobrowser/src/tests.rs

@@ -0,0 +1,223 @@
+// Copyright (c) 2000-2026 TeamDev. All rights reserved.
+// TeamDev PROPRIETARY and CONFIDENTIAL.
+// Use is subject to license terms.
+
+use std::ffi::{c_char, CStr};
+use std::future::Future;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::{Arc, Mutex};
+use std::task::{Context, Poll, Wake, Waker};
+use std::thread::Thread;
+
+use crate::{ffi, register_service, request, Responder, Service};
+
+#[derive(Debug, PartialEq)]
+enum Outcome {
+    Reply(Vec<u8>),
+    Reject(String),
+}
+
+static OUTCOMES: Mutex<Vec<(u64, Outcome)>> = Mutex::new(Vec::new());
+static NEXT_ID: AtomicU64 = AtomicU64::new(1);
+
+unsafe extern "C" fn record_reply(id: u64, data: *const c_char, size: usize) {
+    let data = unsafe { std::slice::from_raw_parts(data.cast::<u8>(), size) }.to_vec();
+    OUTCOMES.lock().unwrap().push((id, Outcome::Reply(data)));
+}
+
+unsafe extern "C" fn record_reject(id: u64, error: *const c_char) {
+    let error = unsafe { CStr::from_ptr(error) }.to_string_lossy().into_owned();
+    OUTCOMES.lock().unwrap().push((id, Outcome::Reject(error)));
+}
+
+fn outcomes(id: u64) -> Vec<Outcome> {
+    let mut all = OUTCOMES.lock().unwrap();
+    let (mine, rest) = all.drain(..).partition(|(i, _)| *i == id);
+    *all = rest;
+    mine.into_iter().map(|(_, outcome)| outcome).collect()
+}
+
+/// Echoes the request of "Echo", drops the responder of "Drop", and panics in
+/// "Panic", without the runtime.
+struct TestService;
+
+impl Service for TestService {
+    fn full_name(&self) -> &'static str {
+        "test.TestService"
+    }
+
+    fn call(&self, method: &str, data: &[u8], responder: Responder) {
+        match method {
+            "Echo" => responder.reply(data),
+            "Drop" => drop(responder),
+            "Panic" => panic!("boom"),
+            _ => responder.reject("Method not found."),
+        }
+    }
+}
+
+fn call(service: &str, method: &str, data: &[u8]) -> Vec<Outcome> {
+    let id = start_call(service, method, data);
+    outcomes(id)
+}
+
+/// Invokes `method` and returns the id of the call without waiting for it.
+fn start_call(service: &str, method: &str, data: &[u8]) -> u64 {
+    register_service(TestService);
+    register_service(AsyncTestService);
+    let id = NEXT_ID.fetch_add(1, Ordering::Relaxed);
+    let service = crate::responder::to_cstring(service);
+    let method = crate::responder::to_cstring(method);
+    unsafe {
+        ffi::invoke(
+            id,
+            service.as_ptr(),
+            method.as_ptr(),
+            data.as_ptr().cast(),
+            data.len(),
+            record_reply,
+            record_reject,
+        )
+    };
+    id
+}
+
+fn encode(s: &str) -> Vec<u8> {
+    prost::Message::encode_to_vec(&s.to_owned())
+}
+
+#[test]
+fn completes_once() {
+    assert_eq!(call("test.TestService", "Echo", &encode("hi")), [Outcome::Reply(encode("hi"))]);
+}
+
+#[test]
+fn dropped_responder_rejects() {
+    assert_eq!(
+        call("test.TestService", "Drop", &[]),
+        [Outcome::Reject("RPC canceled: callback destroyed without completion.".into())]
+    );
+}
+
+#[test]
+fn panic_rejects() {
+    assert_eq!(call("test.TestService", "Panic", &[]), [Outcome::Reject("panic: boom".into())]);
+}
+
+#[test]
+fn unknown_service_rejects() {
+    assert_eq!(call("test.Missing", "Echo", &[]), [Outcome::Reject("Service not found.".into())]);
+}
+
+#[test]
+fn unknown_method_rejects() {
+    assert_eq!(
+        call("test.TestService", "Missing", &[]),
+        [Outcome::Reject("Method not found.".into())]
+    );
+}
+
+/// Replies to "Echo" with the request and rejects everything else.
+unsafe extern "C" fn fake_host(
+    id: u64,
+    _service: *const c_char,
+    method: *const c_char,
+    data: *const c_char,
+    size: usize,
+    reply: ffi::ReplyCallback,
+    reject: ffi::RejectCallback,
+) {
+    if unsafe { CStr::from_ptr(method) } == c"Echo" {
+        unsafe { reply(id, data, size) };
+    } else {
+        unsafe { reject(id, c"no such method".as_ptr()) };
+    }
+}
+
+/// Runs `future` to completion on the current thread.
+fn block_on<F: Future>(future: F) -> F::Output {
+    struct ThreadWaker(Thread);
+    impl Wake for ThreadWaker {
+        fn wake(self: Arc<Self>) {
+            self.0.unpark();
+        }
+    }
+    let waker = Waker::from(Arc::new(ThreadWaker(std::thread::current())));
+    let mut cx = Context::from_waker(&waker);
+    let mut future = std::pin::pin!(future);
+    loop {
+        match future.as_mut().poll(&mut cx) {
+            Poll::Ready(output) => return output,
+            Poll::Pending => std::thread::park(),
+        }
+    }
+}
+
+// One test, since the host is global.
+#[test]
+fn host_requests() {
+    let call = |method, text: &str| block_on(request::<_, String>("s", method, &text.to_owned()));
+
+    ffi::set_host_invoke(None);
+    assert_eq!(call("Echo", "a"), Err("Native RPC host is not available.".into()));
+
+    ffi::set_host_invoke(Some(fake_host));
+    assert_eq!(call("Echo", "b"), Ok("b".into()));
+    assert_eq!(call("Other", "c"), Err("no such method".into()));
+}
+
+/// Echoes the request of "Echo" after yielding, fails "Fail", and panics in
+/// "Panic", like a generated async server.
+struct AsyncTestService;
+
+impl Service for AsyncTestService {
+    fn full_name(&self) -> &'static str {
+        "test.AsyncTestService"
+    }
+
+    fn call(&self, method: &str, data: &[u8], responder: Responder) {
+        let method = method.to_owned();
+        let request: String = prost::Message::decode(data).unwrap_or_default();
+        crate::runtime::spawn_call(
+            async move {
+                tokio::task::yield_now().await;
+                match method.as_str() {
+                    "Echo" => Ok(request),
+                    "Panic" => panic!("async boom"),
+                    _ => Err("async failure".to_owned()),
+                }
+            },
+            responder,
+        );
+    }
+}
+
+/// Waits for the outcome of an async call.
+fn wait_outcomes(id: u64) -> Vec<Outcome> {
+    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(10);
+    loop {
+        let found = outcomes(id);
+        if !found.is_empty() || std::time::Instant::now() > deadline {
+            return found;
+        }
+        std::thread::sleep(std::time::Duration::from_millis(1));
+    }
+}
+
+#[test]
+fn async_completes() {
+    let id = start_call("test.AsyncTestService", "Echo", &encode("hi"));
+    assert_eq!(wait_outcomes(id), [Outcome::Reply(encode("hi"))]);
+}
+
+#[test]
+fn async_error_rejects() {
+    let id = start_call("test.AsyncTestService", "Fail", &[]);
+    assert_eq!(wait_outcomes(id), [Outcome::Reject("async failure".into())]);
+}
+
+#[test]
+fn async_panic_rejects() {
+    let id = start_call("test.AsyncTestService", "Panic", &[]);
+    assert_eq!(wait_outcomes(id), [Outcome::Reject("panic: async boom".into())]);
+}

package/rust/mobrowser/src/transport.rs

@@ -0,0 +1,145 @@
+// Copyright (c) 2000-2026 TeamDev. All rights reserved.
+// TeamDev PROPRIETARY and CONFIDENTIAL.
+// Use is subject to license terms.
+
+use std::collections::HashMap;
+use std::ffi::c_char;
+use std::future::Future;
+use std::panic::{catch_unwind, AssertUnwindSafe};
+use std::sync::{Arc, LazyLock, Mutex, MutexGuard, OnceLock, PoisonError, RwLock};
+
+use crate::ffi::HostInvokeCallback;
+use crate::oneshot;
+use crate::responder::{to_cstring, Responder};
+use crate::Service;
+
+type ServiceMap = HashMap<&'static str, Arc<dyn Service>>;
+
+static SERVICES: LazyLock<RwLock<ServiceMap>> = LazyLock::new(Default::default);
+
+/// Why the entry point failed, if it did; calls to services it didn't register
+/// are rejected with it.
+static LAUNCH_ERROR: OnceLock<String> = OnceLock::new();
+
+type PendingRequest = Box<dyn FnOnce(Result<Vec<u8>, String>) + Send>;
+
+#[derive(Default)]
+struct Host {
+    invoke: Option<HostInvokeCallback>,
+    next_id: u64,
+    pending: HashMap<u64, PendingRequest>,
+}
+
+static HOST: LazyLock<Mutex<Host>> = LazyLock::new(Default::default);
+
+fn host() -> MutexGuard<'static, Host> {
+    HOST.lock().unwrap_or_else(PoisonError::into_inner)
+}
+
+/// Makes `service` callable from the main process. Registering a service with
+/// the name of one registered earlier replaces it.
+pub fn register_service(service: impl Service) {
+    let service = Arc::new(service);
+    SERVICES.write().unwrap_or_else(PoisonError::into_inner).insert(service.full_name(), service);
+}
+
+pub(crate) fn invoke(service: &str, method: &str, data: &[u8], responder: Responder) {
+    let service = SERVICES.read().unwrap_or_else(PoisonError::into_inner).get(service).cloned();
+    match service {
+        Some(service) => service.call(method, data, responder),
+        None => match LAUNCH_ERROR.get() {
+            Some(error) => responder.reject(format!("Native module failed to start: {error}")),
+            None => responder.reject("Service not found."),
+        },
+    }
+}
+
+pub(crate) fn set_launch_error(error: String) {
+    let _ = LAUNCH_ERROR.set(error);
+}
+
+pub(crate) fn set_host_invoke(invoke: Option<HostInvokeCallback>) {
+    host().invoke = invoke;
+}
+
+/// Calls `method` of the main-process `service` with a typed request and
+/// resolves to its response. Works with any async runtime.
+pub fn request<Req, Resp>(
+    service: &str,
+    method: &str,
+    request: &Req,
+) -> impl Future<Output = Result<Resp, String>> + Send + 'static
+where
+    Req: prost::Message,
+    Resp: prost::Message + Default + 'static,
+{
+    let (sender, receiver) = oneshot::channel();
+    request_raw(service, method, &request.encode_to_vec(), move |result| sender.send(result));
+    async move {
+        let data = receiver.await.unwrap_or_else(|| Err("RPC canceled.".to_owned()))?;
+        Resp::decode(data.as_slice()).map_err(|_| "Failed to parse RPC response.".to_owned())
+    }
+}
+
+/// Calls `method` of the main-process `service` with a serialized request.
+/// `callback` runs exactly once, on the main process's UI thread.
+fn request_raw(
+    service: &str,
+    method: &str,
+    data: &[u8],
+    callback: impl FnOnce(Result<Vec<u8>, String>) + Send + 'static,
+) {
+    let mut host = host();
+    let Some(host_invoke) = host.invoke else {
+        drop(host);
+        callback(Err("Native RPC host is not available.".to_owned()));
+        return;
+    };
+    host.next_id += 1;
+    let id = host.next_id;
+    host.pending.insert(id, Box::new(callback));
+    drop(host);
+
+    let service = to_cstring(service);
+    let method = to_cstring(method);
+    let ptr = if data.is_empty() { b"".as_ptr() } else { data.as_ptr() };
+    // The host copies all arguments before returning.
+    unsafe {
+        host_invoke(
+            id,
+            service.as_ptr(),
+            method.as_ptr(),
+            ptr.cast::<c_char>(),
+            data.len(),
+            on_host_reply,
+            on_host_reject,
+        )
+    };
+}
+
+fn complete_request(id: u64, result: Result<Vec<u8>, String>) {
+    let Some(callback) = host().pending.remove(&id) else {
+        return;
+    };
+    // Unwinding into the host is undefined behavior; the panic hook has already
+    // reported the panic.
+    let _ = catch_unwind(AssertUnwindSafe(|| callback(result)));
+}
+
+unsafe extern "C" fn on_host_reply(id: u64, data: *const c_char, size: usize) {
+    let data = if data.is_null() || size == 0 {
+        Vec::new()
+    } else {
+        unsafe { std::slice::from_raw_parts(data.cast::<u8>(), size) }.to_vec()
+    };
+    complete_request(id, Ok(data));
+}
+
+unsafe extern "C" fn on_host_reject(id: u64, error: *const c_char) {
+    let error = if error.is_null() {
+        String::new()
+    } else {
+        unsafe { std::ffi::CStr::from_ptr(error) }.to_string_lossy().into_owned()
+    };
+    complete_request(id, Err(error));
+}

package/rust/mobrowser-build/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "mobrowser-build"
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.85"
+description = "Generates Rust code for MōBrowser native services from .proto files"
+publish = false
+
+[dependencies]
+prost-build = "0.14"

package/rust/mobrowser-build/src/lib.rs

@@ -0,0 +1,314 @@
+// Copyright (c) 2000-2026 TeamDev. All rights reserved.
+// TeamDev PROPRIETARY and CONFIDENTIAL.
+// Use is subject to license terms.
+
+//! Generates Rust messages and native service bindings from the `.proto` files
+//! of a MōBrowser project. Call it from `build.rs`:
+//!
+//! ```ignore
+//! fn main() -> std::io::Result<()> {
+//!     mobrowser_build::compile("src/native/proto")
+//! }
+//! ```
+//!
+//! and include the result with `mobrowser::include_proto!()`.
+//!
+//! For every service, the generated code has:
+//! - `trait <Service>`: implement it, with `async fn`s, to serve calls from the
+//!   main process;
+//! - `struct <Service>Server`: pass it to `mobrowser::register_service`;
+//! - `mod <name>_client`: async functions that call the main-process
+//!   implementation of the service.
+
+use std::fmt::Write as _;
+use std::fs;
+use std::io::{Error, ErrorKind, Result};
+use std::path::{Path, PathBuf};
+
+use prost_build::{Config, Method, Service, ServiceGenerator};
+
+/// The file in `OUT_DIR` that `mobrowser::include_proto!` includes.
+const INCLUDE_FILE: &str = "mobrowser_proto.rs";
+
+/// Compiles every `.proto` file under `proto_dir`, relative to the crate root,
+/// with the `protoc` of the MōBrowser SDK installed in `node_modules`. Set the
+/// `PROTOC` environment variable to use another one.
+pub fn compile(proto_dir: impl AsRef<Path>) -> Result<()> {
+    let manifest_dir = PathBuf::from(env("CARGO_MANIFEST_DIR")?);
+    let out_dir = PathBuf::from(env("OUT_DIR")?);
+    let proto_dir = manifest_dir.join(proto_dir);
+    println!("cargo:rerun-if-changed={}", proto_dir.display());
+    println!("cargo:rerun-if-env-changed=PROTOC");
+
+    let mut protos = Vec::new();
+    if proto_dir.is_dir() {
+        find_protos(&proto_dir, &mut protos)?;
+    }
+    protos.sort();
+    if protos.is_empty() {
+        // Keep include_proto!() compiling in a module without services yet.
+        return fs::write(out_dir.join(INCLUDE_FILE), "");
+    }
+
+    let mut includes = vec![proto_dir];
+    let mut config = Config::new();
+    if std::env::var_os("PROTOC").is_none() {
+        let sdk_dir = find_sdk_dir(&manifest_dir)?;
+        config.protoc_executable(sdk_dir.join("bin").join(protoc_name()));
+        // The well-known types, e.g. google/protobuf/wrappers.proto.
+        includes.push(sdk_dir.join("proto"));
+    }
+    config
+        .prost_path("::mobrowser::prost")
+        .prost_types_path("::mobrowser::prost_types")
+        .include_file(INCLUDE_FILE)
+        .service_generator(Box::new(NativeServiceGenerator))
+        .compile_protos(&protos, &includes)
+}
+
+fn env(name: &str) -> Result<String> {
+    std::env::var(name).map_err(|_| {
+        Error::new(ErrorKind::NotFound, format!("{name} is not set; call compile() from build.rs"))
+    })
+}
+
+fn find_protos(dir: &Path, protos: &mut Vec<PathBuf>) -> Result<()> {
+    for entry in fs::read_dir(dir)? {
+        let path = entry?.path();
+        if path.is_dir() {
+            find_protos(&path, protos)?;
+        } else if path.extension().is_some_and(|ext| ext == "proto") {
+            protos.push(path);
+        }
+    }
+    Ok(())
+}
+
+fn protoc_name() -> &'static str {
+    if cfg!(windows) {
+        "protoc.exe"
+    } else {
+        "protoc"
+    }
+}
+
+/// Finds the SDK package with a `protoc` for this machine in the project's own
+/// `node_modules`, where `Cargo.toml` finds the crates too; a `protoc` elsewhere
+/// is never run. On Apple Silicon, the x64 SDK runs under Rosetta, so it is a
+/// fallback.
+fn find_sdk_dir(project_dir: &Path) -> Result<PathBuf> {
+    let packages: &[&str] = match (std::env::consts::OS, std::env::consts::ARCH) {
+        ("macos", "aarch64") => &["sdk-darwin-arm64", "sdk-darwin-x64"],
+        ("macos", _) => &["sdk-darwin-x64"],
+        ("windows", _) => &["sdk-win-x64"],
+        _ => &["sdk-linux-x64"],
+    };
+    for package in packages {
+        let sdk_dir = project_dir.join("node_modules").join("@mobrowser").join(package);
+        if sdk_dir.join("bin").join(protoc_name()).is_file() {
+            return Ok(sdk_dir);
+        }
+    }
+    Err(Error::new(
+        ErrorKind::NotFound,
+        format!(
+            "protoc not found in node_modules/@mobrowser/{}. Run `npm install`, \
+             or point the PROTOC environment variable at a protoc executable.",
+            packages[0]
+        ),
+    ))
+}
+
+struct NativeServiceGenerator;
+
+impl ServiceGenerator for NativeServiceGenerator {
+    fn generate(&mut self, service: Service, buf: &mut String) {
+        if let Some(method) =
+            service.methods.iter().find(|m| m.client_streaming || m.server_streaming)
+        {
+            panic!(
+                "{}.{}: streaming methods are not supported by native modules",
+                service.proto_name, method.proto_name
+            );
+        }
+        let full_name = if service.package.is_empty() {
+            service.proto_name.clone()
+        } else {
+            format!("{}.{}", service.package, service.proto_name)
+        };
+        generate_trait(&service, buf);
+        generate_server(&service, &full_name, buf);
+        generate_client(&service, &full_name, buf);
+    }
+
+    fn finalize_package(&mut self, package: &str, buf: &mut String) {
+        if let Some(name) = find_duplicate_item(buf) {
+            let package = if package.is_empty() { "the root package" } else { package };
+            panic!(
+                "`{name}` is defined twice in the code generated for {package}. For service \
+                 `Foo`, it also defines `FooServer` and `mod foo_client`; rename a service or \
+                 message so that the names don't clash."
+            );
+        }
+    }
+}
+
+/// Finds a top-level item defined twice, e.g. `foo_client` for services `Foo`
+/// and `FooService`, which rustc would report against the generated file.
+fn find_duplicate_item(buf: &str) -> Option<&str> {
+    const KINDS: &[&str] = &["pub struct ", "pub enum ", "pub trait ", "pub mod "];
+    let mut names = std::collections::HashSet::new();
+    buf.lines()
+        .filter_map(|line| KINDS.iter().find_map(|kind| line.strip_prefix(kind)))
+        .map(|rest| {
+            rest.split(|c: char| !(c.is_alphanumeric() || c == '_' || c == '#'))
+                .next()
+                .unwrap_or("")
+        })
+        .find(|name| !names.insert(*name))
+}
+
+fn generate_trait(service: &Service, buf: &mut String) {
+    service.comments.append_with_indent(0, buf);
+    let _ = writeln!(
+        buf,
+        "#[allow(clippy::all)]\npub trait {}: Send + Sync + 'static {{",
+        service.name
+    );
+    for method in &service.methods {
+        method.comments.append_with_indent(1, buf);
+        let _ = writeln!(
+            buf,
+            "    fn {}(&self, request: {}) -> impl ::core::future::Future<Output = ::core::result::Result<{}, ::std::string::String>> + ::core::marker::Send;",
+            method.name, method.input_type, method.output_type
+        );
+    }
+    buf.push_str("}\n\n");
+}
+
+fn generate_server(service: &Service, full_name: &str, buf: &mut String) {
+    let name = &service.name;
+    let _ = write!(
+        buf,
+        "/// Makes a [`{name}`] implementation callable from the main process:\n\
+         /// `mobrowser::register_service({name}Server::new(service))`. Its methods\n\
+         /// run on `mobrowser::runtime`.\n\
+         pub struct {name}Server<T>(::std::sync::Arc<T>);\n\n\
+         #[allow(clippy::all)]\n\
+         impl<T: {name}> {name}Server<T> {{\n    \
+             pub fn new(service: T) -> Self {{\n        Self(::std::sync::Arc::new(service))\n    }}\n\
+         }}\n\n\
+         #[allow(clippy::all)]\n\
+         impl<T: {name}> ::mobrowser::Service for {name}Server<T> {{\n    \
+             fn full_name(&self) -> &'static str {{\n        \"{full_name}\"\n    }}\n\n    \
+             fn call(&self, method: &str, data: &[u8], responder: ::mobrowser::Responder) {{\n        \
+                 match method {{\n"
+    );
+    for method in &service.methods {
+        let _ = write!(
+            buf,
+            "            \"{proto_name}\" => match <{input} as ::mobrowser::prost::Message>::decode(data) {{\n                \
+                 ::core::result::Result::Ok(request) => {{\n                    \
+                     let service = ::std::sync::Arc::clone(&self.0);\n                    \
+                     ::mobrowser::runtime::spawn_call(async move {{ <T as {name}>::{rust_name}(&*service, request).await }}, responder)\n                \
+                 }}\n                \
+                 ::core::result::Result::Err(error) => responder.reject(::std::format!(\"Failed to parse request: {{error}}\")),\n            \
+             }},\n",
+            proto_name = method.proto_name,
+            input = method.input_type,
+            rust_name = method.name,
+            name = service.name,
+        );
+    }
+    buf.push_str(
+        "            _ => responder.reject(\"Method not found.\"),\n        }\n    }\n}\n\n",
+    );
+}
+
+fn generate_client(service: &Service, full_name: &str, buf: &mut String) {
+    let _ = writeln!(
+        buf,
+        "/// Calls the main-process implementation of `{full_name}`.\n\
+         #[allow(clippy::all)]\n\
+         pub mod {}_client {{",
+        client_module_name(&service.proto_name)
+    );
+    for method in &service.methods {
+        write_client_method(full_name, method, buf);
+    }
+    buf.push_str("}\n\n");
+}
+
+fn write_client_method(full_name: &str, method: &Method, buf: &mut String) {
+    let input = outer_type(&method.input_type);
+    let output = outer_type(&method.output_type);
+    method.comments.append_with_indent(1, buf);
+    let _ = write!(
+        buf,
+        "    pub fn {name}(\n        \
+             request: &{input},\n    \
+         ) -> impl ::core::future::Future<Output = ::core::result::Result<{output}, ::std::string::String>> + ::core::marker::Send + 'static {{\n        \
+             ::mobrowser::request::<{input}, {output}>(\"{full_name}\", \"{proto_name}\", request)\n    \
+         }}\n",
+        name = method.name,
+        proto_name = method.proto_name,
+    );
+}
+
+/// Resolves a type path that prost made relative to the package module from the
+/// client module nested in it.
+fn outer_type(rust_type: &str) -> String {
+    const PRIMITIVES: &[&str] = &["()", "bool", "f32", "f64", "i32", "i64", "u32", "u64"];
+    if rust_type.starts_with("::") || PRIMITIVES.contains(&rust_type) {
+        rust_type.to_owned()
+    } else {
+        format!("super::{rust_type}")
+    }
+}
+
+/// `GreetService` → `greet`, `HTTPClientService` → `http_client`; the same name
+/// as the C++ client instance.
+fn client_module_name(service: &str) -> String {
+    let name = match service.strip_suffix("Service") {
+        Some(stripped) if !stripped.is_empty() => stripped,
+        _ => service,
+    };
+    let chars: Vec<char> = name.chars().collect();
+    let mut result = String::new();
+    for (i, &c) in chars.iter().enumerate() {
+        if c.is_ascii_uppercase() && !result.is_empty() {
+            let previous_is_lower_or_digit =
+                chars[i - 1].is_ascii_lowercase() || chars[i - 1].is_ascii_digit();
+            let next_is_lower = chars.get(i + 1).is_some_and(char::is_ascii_lowercase);
+            if previous_is_lower_or_digit || next_is_lower {
+                result.push('_');
+            }
+        }
+        result.push(c.to_ascii_lowercase());
+    }
+    result
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn client_module_names() {
+        assert_eq!(client_module_name("GreetService"), "greet");
+        assert_eq!(client_module_name("HTTPClientService"), "http_client");
+        assert_eq!(client_module_name("Service"), "service");
+        assert_eq!(client_module_name("Files2Service"), "files2");
+    }
+
+    #[test]
+    fn outer_types() {
+        assert_eq!(outer_type("Person"), "super::Person");
+        assert_eq!(outer_type("super::other::Msg"), "super::super::other::Msg");
+        assert_eq!(outer_type("()"), "()");
+        assert_eq!(
+            outer_type("::mobrowser::prost::alloc::string::String"),
+            "::mobrowser::prost::alloc::string::String"
+        );
+    }
+}