tokra 0.0.1.pre.1 → 0.0.1.pre.2

data/ext/tokra/src/proxy.rs

@@ -0,0 +1,142 @@
+// SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! Proxy wrapper for cross-Ractor communication.
+//!
+//! This module provides the Ruby-facing `Tokra::Native::Proxy` class,
+//! which wraps `tao::event_loop::EventLoopProxy<UserEvent>`.
+//!
+//! The Proxy is the ONLY Tokra native type that is genuinely thread-safe
+//! and Ractor-shareable, as `EventLoopProxy` is designed to be `Send+Sync`.
+
+use magnus::{method, prelude::*, Error, Ruby};
+use tao::event_loop::EventLoopProxy;
+
+use crate::runtime_error;
+use crate::user_event::UserEvent;
+
+/// Ruby wrapper for `tao::event_loop::EventLoopProxy<UserEvent>`.
+///
+/// Thread-safe handle for waking up the event loop from Ractors.
+/// This is the ONLY type that is genuinely designed to be Send+Sync safe by tao.
+///
+/// This type uses `frozen_shareable` to be Ractor-shareable when frozen.
+/// Ruby automatically freezes objects shared across Ractors.
+#[derive(Clone)]
+pub struct RbProxy {
+    inner: EventLoopProxy<UserEvent>,
+}
+
+impl RbProxy {
+    /// Create a new `RbProxy` from an `EventLoopProxy`.
+    #[must_use]
+    pub const fn new(inner: EventLoopProxy<UserEvent>) -> Self {
+        Self { inner }
+    }
+
+    /// Get a reference to the inner `EventLoopProxy`.
+    #[must_use]
+    pub const fn inner(&self) -> &EventLoopProxy<UserEvent> {
+        &self.inner
+    }
+
+    /// Wake up the event loop with a payload.
+    ///
+    /// This is the critical method for Worker Ractor → Main Ractor communication.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the event loop has been closed.
+    pub fn wake_up(&self, payload: String) -> Result<(), Error> {
+        self.inner
+            .send_event(UserEvent::WakeUp(payload))
+            .map_err(|_| {
+                Error::new(
+                    runtime_error(),
+                    "Failed to send wake up event: event loop closed",
+                )
+            })
+    }
+
+    /// Send an HTTP response for a pending async protocol request.
+    ///
+    /// This is used by Ruby to respond to `tokra://` requests.
+    /// The `request_id` must match a pending `HttpRequest` event.
+    /// Headers should be an array of [name, value] pairs.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the event loop has been closed.
+    pub fn respond(
+        &self,
+        request_id: u64,
+        status: u16,
+        headers: Vec<(String, String)>,
+        body: String,
+    ) -> Result<(), Error> {
+        self.inner
+            .send_event(UserEvent::HttpResponse {
+                request_id,
+                status,
+                headers,
+                body,
+            })
+            .map_err(|_| {
+                Error::new(
+                    runtime_error(),
+                    "Failed to send HTTP response: event loop closed",
+                )
+            })
+    }
+}
+
+// RbProxy is genuinely Send+Sync because EventLoopProxy<T> is Send+Sync
+// This is NOT an unsafe impl - tao guarantees this.
+// SAFETY note: Sync is required for frozen_shareable in Magnus.
+// EventLoopProxy is explicitly designed to be used from any thread.
+
+impl magnus::DataTypeFunctions for RbProxy {}
+
+// SAFETY: RbProxy wraps EventLoopProxy which is Send+Sync by design.
+// This impl enables the frozen_shareable flag which makes the Ruby object
+// Ractor-shareable when frozen. Ruby automatically freezes shareable objects.
+#[allow(unsafe_code)]
+unsafe impl magnus::TypedData for RbProxy {
+    fn class(ruby: &magnus::Ruby) -> magnus::RClass {
+        use magnus::Class;
+        static CLASS: magnus::value::Lazy<magnus::RClass> = magnus::value::Lazy::new(|ruby| {
+            let tokra = ruby.define_module("Tokra").unwrap();
+            let native = tokra.define_module("Native").unwrap();
+            let class = native.define_class("Proxy", ruby.class_object()).unwrap();
+            class.undef_default_alloc_func();
+            class
+        });
+        ruby.get_inner(&CLASS)
+    }
+
+    fn data_type() -> &'static magnus::DataType {
+        static DATA_TYPE: magnus::DataType =
+            magnus::typed_data::DataTypeBuilder::<RbProxy>::new(c"Tokra::Native::Proxy")
+                .free_immediately()
+                .size()
+                .frozen_shareable()
+                .build();
+        &DATA_TYPE
+    }
+}
+
+/// Define the `Proxy` class methods on the given Ruby module.
+///
+/// # Errors
+///
+/// Returns an error if class or method definition fails.
+pub fn define_class(ruby: &Ruby, native: magnus::RModule) -> Result<(), Error> {
+    use magnus::Class;
+    let proxy_class = native.define_class("Proxy", ruby.class_object())?;
+    // Prevent Ruby from allocating uninitialized Proxy objects
+    // This fixes the "undefining the allocator of T_DATA class" warning
+    proxy_class.undef_default_alloc_func();
+    proxy_class.define_method("wake_up", method!(RbProxy::wake_up, 1))?;
+    proxy_class.define_method("respond", method!(RbProxy::respond, 4))?;
+    Ok(())
+}

data/ext/tokra/src/responders.rs

@@ -0,0 +1,86 @@
+// SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! Async protocol responder storage.
+//!
+//! This module manages pending HTTP responses for the tokra:// custom protocol.
+//! When the `WebView` makes a request via the custom protocol, we store a responder
+//! that will be used later when Ruby sends back an `HttpResponse` event.
+//!
+//! # Pattern Origin
+//!
+//! This pattern is adapted from Tauri's `register_asynchronous_uri_scheme_protocol`
+//! in tauri/app.rs.
+
+// SPDX-SnippetBegin
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+// SPDX-SnippetCopyrightText: 2020-2023 Tauri Programme within The Commons Conservancy
+// SPDX-SnippetComment: Async responder pattern adapted from tauri/app.rs register_asynchronous_uri_scheme_protocol
+
+use std::collections::HashMap;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Mutex;
+
+use wry::RequestAsyncResponder;
+
+/// Global counter for generating unique request IDs
+static NEXT_REQUEST_ID: AtomicU64 = AtomicU64::new(1);
+
+/// Thread-safe storage for pending async responders
+/// Maps `request_id` -> `RequestAsyncResponder`
+static PENDING_RESPONDERS: std::sync::OnceLock<Mutex<HashMap<u64, RequestAsyncResponder>>> =
+    std::sync::OnceLock::new();
+
+/// Get the global responders map, initializing if needed.
+#[must_use]
+pub fn get_responders() -> &'static Mutex<HashMap<u64, RequestAsyncResponder>> {
+    PENDING_RESPONDERS.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+/// Generate the next unique request ID.
+#[must_use]
+pub fn next_request_id() -> u64 {
+    NEXT_REQUEST_ID.fetch_add(1, Ordering::SeqCst)
+}
+
+// SPDX-SnippetEnd
+
+// =============================================================================
+// Unit Tests
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_next_request_id_increments() {
+        let first = next_request_id();
+        let second = next_request_id();
+        assert_eq!(second, first + 1);
+    }
+
+    #[test]
+    fn test_next_request_id_is_unique_across_calls() {
+        let ids: Vec<u64> = (0..100).map(|_| next_request_id()).collect();
+        let unique: std::collections::HashSet<u64> = ids.iter().cloned().collect();
+        assert_eq!(ids.len(), unique.len(), "All IDs should be unique");
+    }
+
+    #[test]
+    fn test_get_responders_returns_same_instance() {
+        let first = get_responders();
+        let second = get_responders();
+        assert!(std::ptr::eq(first, second), "Should return same instance");
+    }
+
+    #[test]
+    fn test_get_responders_is_empty_initially() {
+        // Note: This may fail if other tests have added responders.
+        // The responders map is global, so this test verifies the HashMap exists.
+        let responders = get_responders();
+        let guard = responders.lock().unwrap();
+        // Just verify we can access it - can't guarantee empty due to other tests
+        let _ = guard.len();
+    }
+}

data/ext/tokra/src/user_event.rs

@@ -0,0 +1,313 @@
+// SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! User events for cross-thread/Ractor communication.
+//!
+//! This module defines the `UserEvent` enum that carries messages between
+//! different parts of the Tokra runtime: from `WebView` to Ruby, from Ractors
+//! to the main thread, and from Ruby back to pending protocol requests.
+
+/// Custom event type for cross-thread/Ractor communication.
+///
+/// This is the payload type for `tao::EventLoopProxy<UserEvent>`.
+#[derive(Debug, Clone)]
+pub enum UserEvent {
+    /// IPC message received from `WebView` JavaScript
+    IpcMessage(String),
+
+    /// HTTP request received from `WebView` (via custom protocol)
+    /// Contains: (`request_id`, method, uri, headers, body)
+    /// The `request_id` is used to correlate with the async response
+    HttpRequest {
+        request_id: u64,
+        method: String,
+        uri: String,
+        headers: Vec<(String, String)>,
+        body: String,
+    },
+
+    /// HTTP response from Ruby (for async protocol handling)
+    /// Contains: (`request_id`, status, headers, body)
+    HttpResponse {
+        request_id: u64,
+        status: u16,
+        headers: Vec<(String, String)>,
+        body: String,
+    },
+
+    /// Page load event (Started or Finished)
+    /// Matches Tauri's `on_page_load` API
+    PageLoad {
+        event: String, // "started" or "finished"
+        url: String,
+    },
+
+    /// Wake-up signal from a Ractor (via Proxy)
+    WakeUp(String),
+
+    /// Exit signal (from ctrlc handler)
+    Exit,
+}
+
+// =============================================================================
+// Unit Tests
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_user_event_ipc_message_stores_string() {
+        let event = UserEvent::IpcMessage("hello from JS".to_string());
+        match event {
+            UserEvent::IpcMessage(msg) => assert_eq!(msg, "hello from JS"),
+            _ => panic!("Expected IpcMessage variant"),
+        }
+    }
+
+    #[test]
+    fn test_user_event_ipc_message_preserves_unicode() {
+        let event = UserEvent::IpcMessage("こんにちは 🎌".to_string());
+        match event {
+            UserEvent::IpcMessage(msg) => assert_eq!(msg, "こんにちは 🎌"),
+            _ => panic!("Expected IpcMessage variant"),
+        }
+    }
+
+    #[test]
+    fn test_user_event_http_request_stores_all_fields() {
+        let headers = vec![
+            ("cookie".to_string(), "session=abc123".to_string()),
+            ("content-type".to_string(), "application/json".to_string()),
+        ];
+        let event = UserEvent::HttpRequest {
+            request_id: 42,
+            method: "POST".to_string(),
+            uri: "tokra://localhost/api".to_string(),
+            headers: headers.clone(),
+            body: r#"{"key":"value"}"#.to_string(),
+        };
+
+        match event {
+            UserEvent::HttpRequest {
+                request_id,
+                method,
+                uri,
+                headers: h,
+                body,
+            } => {
+                assert_eq!(request_id, 42);
+                assert_eq!(method, "POST");
+                assert_eq!(uri, "tokra://localhost/api");
+                assert_eq!(h.len(), 2);
+                assert_eq!(h[0].0, "cookie");
+                assert_eq!(h[0].1, "session=abc123");
+                assert_eq!(body, r#"{"key":"value"}"#);
+            }
+            _ => panic!("Expected HttpRequest variant"),
+        }
+    }
+
+    #[test]
+    fn test_user_event_http_response_stores_all_fields() {
+        let headers = vec![
+            ("content-type".to_string(), "text/html".to_string()),
+            ("x-custom".to_string(), "value".to_string()),
+        ];
+
+        let event = UserEvent::HttpResponse {
+            request_id: 99,
+            status: 200,
+            headers: headers.clone(),
+            body: "<h1>Hello</h1>".to_string(),
+        };
+
+        match event {
+            UserEvent::HttpResponse {
+                request_id,
+                status,
+                headers: h,
+                body,
+            } => {
+                assert_eq!(request_id, 99);
+                assert_eq!(status, 200);
+                assert_eq!(h.len(), 2);
+                assert_eq!(h[0].0, "content-type");
+                assert_eq!(h[0].1, "text/html");
+                assert_eq!(body, "<h1>Hello</h1>");
+            }
+            _ => panic!("Expected HttpResponse variant"),
+        }
+    }
+
+    #[test]
+    fn test_user_event_page_load_started() {
+        let event = UserEvent::PageLoad {
+            event: "started".to_string(),
+            url: "https://example.com/".to_string(),
+        };
+
+        match event {
+            UserEvent::PageLoad { event, url } => {
+                assert_eq!(event, "started");
+                assert_eq!(url, "https://example.com/");
+            }
+            _ => panic!("Expected PageLoad variant"),
+        }
+    }
+
+    #[test]
+    fn test_user_event_page_load_finished() {
+        let event = UserEvent::PageLoad {
+            event: "finished".to_string(),
+            url: "https://example.com/page".to_string(),
+        };
+
+        match event {
+            UserEvent::PageLoad { event, url } => {
+                assert_eq!(event, "finished");
+                assert_eq!(url, "https://example.com/page");
+            }
+            _ => panic!("Expected PageLoad variant"),
+        }
+    }
+
+    #[test]
+    fn test_user_event_wake_up_stores_payload() {
+        let event = UserEvent::WakeUp("worker response".to_string());
+        match event {
+            UserEvent::WakeUp(payload) => assert_eq!(payload, "worker response"),
+            _ => panic!("Expected WakeUp variant"),
+        }
+    }
+
+    #[test]
+    fn test_user_event_exit_variant_exists() {
+        let event = UserEvent::Exit;
+        assert!(matches!(event, UserEvent::Exit));
+    }
+
+    #[test]
+    fn test_user_event_clone_preserves_ipc_message() {
+        let original = UserEvent::IpcMessage("test".to_string());
+        let cloned = original.clone();
+
+        match (original, cloned) {
+            (UserEvent::IpcMessage(a), UserEvent::IpcMessage(b)) => {
+                assert_eq!(a, b);
+            }
+            _ => panic!("Clone should preserve variant"),
+        }
+    }
+
+    #[test]
+    fn test_user_event_clone_preserves_http_request() {
+        let original = UserEvent::HttpRequest {
+            request_id: 123,
+            method: "GET".to_string(),
+            uri: "tokra://test".to_string(),
+            headers: vec![("accept".to_string(), "text/html".to_string())],
+            body: "".to_string(),
+        };
+        let cloned = original.clone();
+
+        match cloned {
+            UserEvent::HttpRequest {
+                request_id,
+                headers,
+                ..
+            } => {
+                assert_eq!(request_id, 123);
+                assert_eq!(headers.len(), 1);
+            }
+            _ => panic!("Clone should preserve variant"),
+        }
+    }
+
+    #[test]
+    fn test_user_event_debug_format_ipc() {
+        let event = UserEvent::IpcMessage("debug test".to_string());
+        let debug_str = format!("{:?}", event);
+        assert!(debug_str.contains("IpcMessage"));
+        assert!(debug_str.contains("debug test"));
+    }
+
+    #[test]
+    fn test_user_event_debug_format_exit() {
+        let event = UserEvent::Exit;
+        let debug_str = format!("{:?}", event);
+        assert!(debug_str.contains("Exit"));
+    }
+
+    #[test]
+    fn test_http_request_id_can_be_zero() {
+        let event = UserEvent::HttpRequest {
+            request_id: 0,
+            method: "GET".to_string(),
+            uri: "tokra://test".to_string(),
+            headers: vec![],
+            body: "".to_string(),
+        };
+
+        match event {
+            UserEvent::HttpRequest { request_id, .. } => assert_eq!(request_id, 0),
+            _ => panic!("Expected HttpRequest"),
+        }
+    }
+
+    #[test]
+    fn test_http_request_id_can_be_max_u64() {
+        let event = UserEvent::HttpRequest {
+            request_id: u64::MAX,
+            method: "GET".to_string(),
+            uri: "tokra://test".to_string(),
+            headers: vec![],
+            body: "".to_string(),
+        };
+
+        match event {
+            UserEvent::HttpRequest { request_id, .. } => assert_eq!(request_id, u64::MAX),
+            _ => panic!("Expected HttpRequest"),
+        }
+    }
+
+    #[test]
+    fn test_http_response_status_boundary_low() {
+        let event = UserEvent::HttpResponse {
+            request_id: 1,
+            status: 100,
+            headers: vec![],
+            body: "".to_string(),
+        };
+
+        match event {
+            UserEvent::HttpResponse { status, .. } => assert_eq!(status, 100),
+            _ => panic!("Expected HttpResponse"),
+        }
+    }
+
+    #[test]
+    fn test_http_response_status_boundary_high() {
+        let event = UserEvent::HttpResponse {
+            request_id: 1,
+            status: 599,
+            headers: vec![],
+            body: "".to_string(),
+        };
+
+        match event {
+            UserEvent::HttpResponse { status, .. } => assert_eq!(status, 599),
+            _ => panic!("Expected HttpResponse"),
+        }
+    }
+
+    #[test]
+    fn test_empty_strings_are_preserved() {
+        let event = UserEvent::IpcMessage("".to_string());
+        match event {
+            UserEvent::IpcMessage(msg) => assert!(msg.is_empty()),
+            _ => panic!("Expected IpcMessage"),
+        }
+    }
+}