quietquic 0.1.0.alpha.3

data/ext/quietquic/src/conn.rs

@@ -0,0 +1,283 @@
+// SPDX-License-Identifier: 0BSD
+//! `QuietQUIC::Native::Connection` and `QuietQUIC::Native::Stream` — the FFI
+//! wrappers over the crate's [`quietquic_core::conn::Connection`] and
+//! [`quietquic_core::conn::Stream`]. A `NativeConnection` is produced once by
+//! both `Server#accept` and `Client#connect` (the single post-handshake type);
+//! Task 7 grows it into the stream-carrying handle and adds `NativeStream`.
+//!
+//! ## Sharing model — WHY THERE IS NO LOCK AROUND THE CONNECTION
+//!
+//! Every crate `Connection` method (`open_stream`, `accept_stream`, `close`,
+//! `remote_address`) takes `&self`: the `Connection` is a lightweight handle
+//! that talks to the driver over a cloneable `tokio::sync::mpsc` command
+//! channel (see the crate's `conn.rs`). It is `Send` but not `Clone`, so we
+//! park it behind an `Arc` and share `&*conn` into each op's future. Because the
+//! methods are `&self`, concurrent `open_stream`/`accept_stream`/`close` all
+//! share the one handle with NO mutex — there is no `&mut` to guard and thus no
+//! deadlock surface.
+//!
+//! ### No latching-shutdown pattern needed here (unlike `NativeServer`)
+//!
+//! `NativeServer::accept` had to hold an async mutex across `server.accept()`
+//! because the crate `Server::accept` takes `&mut self`; a parked accept then
+//! blocked a `close` that needed the same mutex, forcing the
+//! `closed: AtomicBool` + `Notify` + `select!` latch. Here NOTHING is the case:
+//! - `Connection::accept_stream(&self)` parks in the crate's own driver channel,
+//!   holding no lock on our side.
+//! - `Connection::close(&self)` is a plain `&self` command-send; it needs no
+//!   lock and races nothing. When the driver tears the connection down it fires
+//!   every parked accept/read reply with `ConnError::Closed` (see the crate's
+//!   `ConnState::fail_all`), so a parked `accept_stream`/`read_to_end` wakes on
+//!   its own — we do not have to unpark it.
+//!
+//! So `close` can always proceed for 0/1/N parked stream ops without any latch.
+//!
+//! ### `NativeStream` and the one `&mut self` seam
+//!
+//! The crate `Stream` methods (`write_all`, `finish`, `read_to_end`) take
+//! `&mut self`. A `Stream` is again just a `StreamId` + cloneable `CmdSender`,
+//! but the `&mut` means we need interior mutability to call them from a shared
+//! Ruby object. We wrap it in `Arc<tokio::sync::Mutex<CoreStream>>` and lock it
+//! inside each op's future — an async mutex, so a parked `read_to_end` yields
+//! the worker rather than blocking it, and no `std` lock is ever held across an
+//! await. This lock only serializes ops on the SAME stream (the natural
+//! contract: you don't concurrently read and finish one stream); it never
+//! interacts with the connection's `close`, so the Task 5 deadlock cannot recur.
+//!
+//! FFI thread-safety: every op yields plain Rust data (`()` / `Vec<u8>` / a
+//! `CoreStream` handle); the Ruby `NativeStream` object and the binary `String`
+//! are built by `to_ruby` on the Ruby thread. No magnus `Value` is ever
+//! constructed on a tokio worker thread. Read bytes are returned as a Ruby
+//! `String` forced to `Encoding::BINARY` via `Ruby::str_from_slice`.
+
+use std::net::SocketAddr;
+use std::sync::Arc;
+
+use magnus::{method, prelude::*, Error, IntoValue, RModule, RString, Ruby};
+use tokio::sync::Mutex as AsyncMutex;
+
+use quietquic_core::conn::{
+    Connection as CoreConnection, ConnError, RecvStream as CoreRecvStream,
+    SendStream as CoreSendStream,
+};
+
+use crate::errors::{ErrorKind, MappedError};
+use crate::pending::PendingOp;
+
+/// Map a crate [`ConnError`] to the classified [`MappedError`] the bridge
+/// raises. A stream-level failure (reset/stopped/refused) becomes
+/// `QuietQUIC::StreamError`; the driver being gone (connection closed or lost
+/// after establishment) becomes `QuietQUIC::ConnectionLost`.
+fn map_conn_error(e: ConnError) -> MappedError {
+    match e {
+        ConnError::Closed => MappedError::new(ErrorKind::ConnectionLost, "connection closed"),
+        other => MappedError::new(ErrorKind::Stream, format!("stream error: {other}")),
+    }
+}
+
+/// `QuietQUIC::Native::Connection` — TypedData wrapper over the crate's
+/// post-handshake [`CoreConnection`].
+///
+/// `Send` because the crate `Connection` is `Send` (its command channel +
+/// handle + addr are all `Send`) and `SocketAddr` is `Copy + Send`. Shared
+/// behind an `Arc` (not a mutex): all crate methods are `&self`, so ops just
+/// share the handle. See the module docs for why no lock/latch is needed.
+#[magnus::wrap(class = "QuietQUIC::Native::Connection", free_immediately, size)]
+pub(crate) struct NativeConnection {
+    conn: Arc<CoreConnection>,
+    /// Cached at wrap time so `remote_address` is lock-free and always answers.
+    remote_addr: SocketAddr,
+}
+
+impl NativeConnection {
+    /// Build from the crate `Connection` yielded by `accept` (server) or
+    /// `connect` (client). On the Ruby thread.
+    pub(crate) fn from_core(conn: CoreConnection) -> Self {
+        let remote_addr = conn.remote_address();
+        NativeConnection {
+            conn: Arc::new(conn),
+            remote_addr,
+        }
+    }
+
+    /// `NativeConnection#remote_address -> String`. Synchronous, lock-free.
+    fn remote_address(&self) -> String {
+        self.remote_addr.to_string()
+    }
+
+    /// `NativeConnection#open_stream_op -> PendingOp` (yields a `NativeStream`).
+    ///
+    /// Opens a new bidirectional stream. `open_stream` is `&self`, so we share
+    /// the `Arc<Connection>` into the future with no lock. Yields the crate
+    /// `Stream` as plain Rust data; `to_ruby` wraps it into a `NativeStream` on
+    /// the Ruby thread.
+    fn open_stream_op(&self) -> Result<PendingOp, Error> {
+        let conn = Arc::clone(&self.conn);
+        PendingOp::spawn_op(
+            async move { conn.open_bi().await.map_err(map_conn_error) },
+            |stream: (CoreSendStream, CoreRecvStream)| {
+                let ruby = Ruby::get().expect("to_ruby runs on the Ruby thread");
+                NativeStream::from_core(stream).into_value_with(&ruby)
+            },
+        )
+    }
+
+    /// `NativeConnection#accept_stream_op -> PendingOp` (yields a `NativeStream`).
+    ///
+    /// Parks until the peer opens the next bidirectional stream. Holds NO lock
+    /// while parked (the crate driver holds the wait); a concurrent `close` on
+    /// this connection makes the crate driver fire this accept's reply with
+    /// `Closed`, so the future wakes and maps to `ConnectionLost` — no latch
+    /// needed on our side.
+    fn accept_stream_op(&self) -> Result<PendingOp, Error> {
+        let conn = Arc::clone(&self.conn);
+        PendingOp::spawn_op(
+            async move { conn.accept_bi().await.map_err(map_conn_error) },
+            |stream: (CoreSendStream, CoreRecvStream)| {
+                let ruby = Ruby::get().expect("to_ruby runs on the Ruby thread");
+                NativeStream::from_core(stream).into_value_with(&ruby)
+            },
+        )
+    }
+
+    /// `NativeConnection#close`. Synchronous, lock-free, best-effort.
+    ///
+    /// Sends a CONNECTION_CLOSE via the crate's `&self` `close`, so the peer and
+    /// this side's driver tear down promptly rather than idling out. The crate
+    /// `close` is `async`, but it only enqueues a `Close` command (a single
+    /// non-parking channel send) — we run it to completion on the shared runtime
+    /// with `block_on`. This runs on the Ruby thread and needs no lock, so it
+    /// can never deadlock behind a parked `accept_stream`/`read_to_end` (those
+    /// park in the crate driver, not behind a lock we hold). Idempotent: a
+    /// second close on an already-torn-down connection is a harmless no-op.
+    fn close(&self) {
+        let conn = Arc::clone(&self.conn);
+        crate::runtime::runtime().block_on(async move {
+            let _ = conn.close(0, b"").await;
+        });
+    }
+}
+
+/// `QuietQUIC::Native::Stream` — TypedData wrapper over the crate's split
+/// bidirectional send/receive stream halves.
+///
+/// The alpha.3 crate exposes `SendStream` and `RecvStream`; the Ruby API keeps
+/// one `Stream` facade for compatibility and simplicity. Each half has its own
+/// async mutex because the crate methods take `&mut self`: send operations
+/// serialize with send operations, and receive operations serialize with
+/// receive operations. A send and a receive on the same Ruby object do not
+/// contend on one native lock.
+#[magnus::wrap(class = "QuietQUIC::Native::Stream", free_immediately, size)]
+pub(crate) struct NativeStream {
+    send: Arc<AsyncMutex<CoreSendStream>>,
+    recv: Arc<AsyncMutex<CoreRecvStream>>,
+}
+
+impl NativeStream {
+    /// Wrap crate stream halves yielded by open/accept. On the Ruby thread.
+    fn from_core((send, recv): (CoreSendStream, CoreRecvStream)) -> Self {
+        NativeStream {
+            send: Arc::new(AsyncMutex::new(send)),
+            recv: Arc::new(AsyncMutex::new(recv)),
+        }
+    }
+
+    /// `NativeStream#write_all_op(bytes) -> PendingOp` (yields nil).
+    ///
+    /// Reads the Ruby `String` as raw BYTES (`&[u8]`, encoding-agnostic) and
+    /// copies them out to an owned `Vec<u8>` synchronously on the Ruby thread —
+    /// BEFORE spawning — because the borrowed slice points at Ruby-owned memory
+    /// the GC may move/free once we yield. Writes the whole buffer, waiting out
+    /// flow-control back-pressure inside the crate driver.
+    fn write_all_op(&self, bytes: RString) -> Result<PendingOp, Error> {
+        // Copy the bytes out on the Ruby thread; the slice aliases Ruby memory,
+        // so we must not hold it across the spawn. `unsafe` is sound here: we do
+        // not re-enter Ruby or trigger GC between borrow and copy.
+        let data: Vec<u8> = unsafe { bytes.as_slice().to_vec() };
+        let send = Arc::clone(&self.send);
+        PendingOp::spawn_op(
+            async move {
+                let mut guard = send.lock().await;
+                guard.write_all(&data).await.map_err(map_conn_error)
+            },
+            |_unit: ()| {
+                let ruby = Ruby::get().expect("to_ruby runs on the Ruby thread");
+                ruby.qnil().into_value_with(&ruby)
+            },
+        )
+    }
+
+    /// `NativeStream#finish_op -> PendingOp` (yields nil). Sends FIN.
+    fn finish_op(&self) -> Result<PendingOp, Error> {
+        let send = Arc::clone(&self.send);
+        PendingOp::spawn_op(
+            async move {
+                let mut guard = send.lock().await;
+                guard.finish().await.map_err(map_conn_error)
+            },
+            |_unit: ()| {
+                let ruby = Ruby::get().expect("to_ruby runs on the Ruby thread");
+                ruby.qnil().into_value_with(&ruby)
+            },
+        )
+    }
+
+    /// `NativeStream#finish_and_wait_op(timeout_seconds) -> PendingOp` (yields nil).
+    fn finish_and_wait_op(&self, timeout_seconds: f64) -> Result<PendingOp, Error> {
+        let send = Arc::clone(&self.send);
+        PendingOp::spawn_op(
+            async move {
+                let mut guard = send.lock().await;
+                let duration = std::time::Duration::from_secs_f64(timeout_seconds);
+                tokio::time::timeout(duration, guard.finish_and_wait())
+                    .await
+                    .map_err(|_| MappedError::new(ErrorKind::Stream, "timed out waiting for stream FIN acknowledgement"))?
+                    .map_err(map_conn_error)
+            },
+            |_unit: ()| {
+                let ruby = Ruby::get().expect("to_ruby runs on the Ruby thread");
+                ruby.qnil().into_value_with(&ruby)
+            },
+        )
+    }
+
+    /// `NativeStream#read_to_end_op(limit) -> PendingOp` (yields a BINARY `String`).
+    ///
+    /// Parks until the peer sends FIN, then yields all received bytes as plain
+    /// Rust `Vec<u8>`. `to_ruby` builds the Ruby `String` on the Ruby thread via
+    /// `Ruby::str_from_slice`, which sets `Encoding::BINARY` (ASCII-8BIT) — the
+    /// caller gets exact bytes, never a UTF-8-validated string. Holding the
+    /// receive-half async mutex across this parking await is safe (async mutex)
+    /// and does not interact with the send half or connection `close`.
+    fn read_to_end_op(&self, limit: usize) -> Result<PendingOp, Error> {
+        let recv = Arc::clone(&self.recv);
+        PendingOp::spawn_op(
+            async move {
+                let mut guard = recv.lock().await;
+                guard.read_to_end(limit).await.map_err(map_conn_error)
+            },
+            |bytes: Vec<u8>| {
+                let ruby = Ruby::get().expect("to_ruby runs on the Ruby thread");
+                // BINARY-encoded String: exact bytes, no UTF-8 assumption.
+                ruby.str_from_slice(&bytes).into_value_with(&ruby)
+            },
+        )
+    }
+}
+
+/// Register `Connection` + `Stream` and their methods on `QuietQUIC::Native`.
+pub(crate) fn init(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
+    let connection = native.define_class("Connection", ruby.class_object())?;
+    connection.define_method("remote_address", method!(NativeConnection::remote_address, 0))?;
+    connection.define_method("open_stream_op", method!(NativeConnection::open_stream_op, 0))?;
+    connection.define_method("accept_stream_op", method!(NativeConnection::accept_stream_op, 0))?;
+    connection.define_method("close", method!(NativeConnection::close, 0))?;
+
+    let stream = native.define_class("Stream", ruby.class_object())?;
+    stream.define_method("write_all_op", method!(NativeStream::write_all_op, 1))?;
+    stream.define_method("finish_op", method!(NativeStream::finish_op, 0))?;
+    stream.define_method("finish_and_wait_op", method!(NativeStream::finish_and_wait_op, 1))?;
+    stream.define_method("read_to_end_op", method!(NativeStream::read_to_end_op, 1))?;
+
+    Ok(())
+}

data/ext/quietquic/src/errors.rs

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: 0BSD
+//! Rust-side model of quietquic's Ruby exception hierarchy and the mapping
+//! from a spawned future's failure to the concrete `QuietQUIC::*` class.
+//!
+//! The exception classes are defined once at init and cached in a `OnceLock`
+//! so that [`MappedError::into_ruby_error`] can look them up cheaply on the
+//! Ruby thread. **No Ruby value is ever created on a tokio worker thread** —
+//! a failing future yields a plain-data [`MappedError`], and the conversion to
+//! a magnus `Error` (which carries a Ruby exception class) happens only inside
+//! `PendingOp#take_result`, on the Ruby VM thread.
+
+use std::sync::OnceLock;
+
+use magnus::value::ReprValue;
+use magnus::{prelude::*, value::Opaque, Error, ExceptionClass, RModule, Ruby};
+
+/// The subset of the exception hierarchy a mapped error can select. Each
+/// variant corresponds 1:1 to a class defined under `QuietQUIC`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum ErrorKind {
+    /// `QuietQUIC::Error` — the base class (also the fallback).
+    Base,
+    /// `QuietQUIC::ConfigError`.
+    Config,
+    /// `QuietQUIC::ConnectError`.
+    Connect,
+    /// `QuietQUIC::ConnectionLost`.
+    ConnectionLost,
+    /// `QuietQUIC::StreamError`.
+    Stream,
+}
+
+impl ErrorKind {
+    /// Parse a lowercase kind string (used by the `fail_op` test helper and,
+    /// later, by internal call sites that classify core errors by name).
+    pub(crate) fn from_str(kind: &str) -> Self {
+        match kind {
+            "config" => ErrorKind::Config,
+            "connect" => ErrorKind::Connect,
+            "connection_lost" => ErrorKind::ConnectionLost,
+            "stream" => ErrorKind::Stream,
+            _ => ErrorKind::Base,
+        }
+    }
+}
+
+/// A failure produced by a spawned future. Pure Rust data — safe to move
+/// across the tokio/Ruby thread boundary. Converted to a magnus `Error`
+/// (with a real Ruby exception class) only on the Ruby thread.
+#[derive(Debug, Clone)]
+pub(crate) struct MappedError {
+    pub(crate) kind: ErrorKind,
+    pub(crate) message: String,
+}
+
+impl MappedError {
+    pub(crate) fn new(kind: ErrorKind, message: impl Into<String>) -> Self {
+        MappedError {
+            kind,
+            message: message.into(),
+        }
+    }
+
+    /// Build the magnus `Error` carrying the concrete `QuietQUIC::*` class.
+    /// Must be called on the Ruby thread (it dereferences cached class handles
+    /// and constructs an exception).
+    pub(crate) fn into_ruby_error(self, ruby: &Ruby) -> Error {
+        let class = exception_class(ruby, self.kind);
+        Error::new(class, self.message)
+    }
+}
+
+/// Cached exception classes, populated at init on the Ruby thread. `Opaque`
+/// makes the handles `Send` so they can live in the process-global `OnceLock`;
+/// they are only ever *dereferenced* back on a Ruby thread via `ruby.get_inner`.
+struct Classes {
+    base: Opaque<ExceptionClass>,
+    config: Opaque<ExceptionClass>,
+    connect: Opaque<ExceptionClass>,
+    connection_lost: Opaque<ExceptionClass>,
+    stream: Opaque<ExceptionClass>,
+}
+
+static CLASSES: OnceLock<Classes> = OnceLock::new();
+
+/// The `QuietQUIC::Error` base exception class, resolved on the Ruby thread.
+/// Used by call sites (e.g. the fork guard) that raise the base error directly
+/// without going through a [`MappedError`].
+pub(crate) fn base_error_class(ruby: &Ruby) -> ExceptionClass {
+    exception_class(ruby, ErrorKind::Base)
+}
+
+/// Resolve the concrete `ExceptionClass` for a kind, on the Ruby thread.
+fn exception_class(ruby: &Ruby, kind: ErrorKind) -> ExceptionClass {
+    let classes = CLASSES
+        .get()
+        .expect("errors::init must run before exception_class");
+    let opaque = match kind {
+        ErrorKind::Base => classes.base,
+        ErrorKind::Config => classes.config,
+        ErrorKind::Connect => classes.connect,
+        ErrorKind::ConnectionLost => classes.connection_lost,
+        ErrorKind::Stream => classes.stream,
+    };
+    ruby.get_inner(opaque)
+}
+
+/// Define the exception hierarchy under `QuietQUIC` and cache the classes.
+///
+/// `Error < StandardError`; `ConfigError`, `ConnectError`, `ConnectionLost`,
+/// and `StreamError` all `< QuietQUIC::Error`.
+pub(crate) fn init(ruby: &Ruby, module: &RModule) -> Result<(), Error> {
+    let base = module.define_class("Error", ruby.exception_standard_error().as_r_class())?;
+    let base_exc = ExceptionClass::from_value(base.as_value())
+        .expect("QuietQUIC::Error is an exception class");
+
+    let define = |name: &str| -> Result<Opaque<ExceptionClass>, Error> {
+        let klass = module.define_class(name, base_exc.as_r_class())?;
+        let exc = ExceptionClass::from_value(klass.as_value())
+            .expect("subclass of QuietQUIC::Error is an exception class");
+        Ok(Opaque::from(exc))
+    };
+
+    let config = define("ConfigError")?;
+    let connect = define("ConnectError")?;
+    let connection_lost = define("ConnectionLost")?;
+    let stream = define("StreamError")?;
+
+    CLASSES
+        .set(Classes {
+            base: Opaque::from(base_exc),
+            config,
+            connect,
+            connection_lost,
+            stream,
+        })
+        .ok();
+
+    Ok(())
+}

data/ext/quietquic/src/lib.rs

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: 0BSD
+use magnus::{function, prelude::*, Error, Ruby};
+
+mod client;
+mod config;
+mod conn;
+mod errors;
+mod pending;
+mod runtime;
+mod server;
+
+fn ping() -> &'static str {
+    "pong"
+}
+
+/// `QuietQUIC::Native.sleep_op(millis) -> PendingOp`.
+fn sleep_op(millis: u64) -> Result<pending::PendingOp, Error> {
+    pending::sleep_op(millis)
+}
+
+/// `QuietQUIC::Native.echo_op(str) -> PendingOp`.
+fn echo_op(s: String) -> Result<pending::PendingOp, Error> {
+    pending::echo_op(s)
+}
+
+/// `QuietQUIC::Native.nil_op -> PendingOp`.
+fn nil_op() -> Result<pending::PendingOp, Error> {
+    pending::nil_op()
+}
+
+/// `QuietQUIC::Native.fail_op(kind) -> PendingOp` (test helper).
+fn fail_op(kind: String) -> Result<pending::PendingOp, Error> {
+    pending::fail_op(kind)
+}
+
+/// `QuietQUIC::Native.panic_op -> PendingOp` (dev/test helper).
+fn panic_op() -> Result<pending::PendingOp, Error> {
+    pending::panic_op()
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("QuietQUIC")?;
+    errors::init(ruby, &module)?;
+
+    let native = module.define_module("Native")?;
+    native.define_singleton_method("ping", function!(ping, 0))?;
+    native.define_singleton_method("sleep_op", function!(sleep_op, 1))?;
+    native.define_singleton_method("echo_op", function!(echo_op, 1))?;
+    native.define_singleton_method("nil_op", function!(nil_op, 0))?;
+    native.define_singleton_method("fail_op", function!(fail_op, 1))?;
+    native.define_singleton_method("panic_op", function!(panic_op, 0))?;
+    pending::init(ruby, &native)?;
+    config::init(ruby, &native)?;
+    conn::init(ruby, &native)?;
+    server::init(ruby, &native)?;
+    client::init(ruby, &native)?;
+    Ok(())
+}