quietquic 0.1.0.alpha.3

data/ext/quietquic/src/pending.rs

@@ -0,0 +1,386 @@
+// SPDX-License-Identifier: 0BSD
+//! [`PendingOp`]: the bridge object handed to Ruby for an in-flight async op.
+//!
+//! Mechanism:
+//! - On start we create a self-pipe (`pipe(2)`). Rust owns both ends.
+//! - The future is spawned on the shared tokio runtime. On completion the task
+//!   (1) stores a *result producer* into a `Mutex<Option<..>>` slot, then (2)
+//!   writes one byte to the pipe write end. The write establishes a
+//!   happens-before edge: once the reader observes the fd readable, the slot is
+//!   populated.
+//! - `#fd` returns the *read* end as an `Integer`. Ruby waits on it with
+//!   `IO#wait_readable`, which is fiber-scheduler aware (Ruby >= 3.0): under
+//!   `Async` it parks the fiber; otherwise it blocks with the GVL released.
+//! - `#take_result` locks the slot, takes the producer, and runs it **on the
+//!   Ruby thread** to build the Ruby `Value` (or raise the mapped exception).
+//! - `#close` (and `Drop`) abort the tokio task and close both fds — no leak.
+//!   The write fd is shared with the task (`Arc<Mutex<i32>>`) and both `wake`
+//!   and dispose operate on it only under that lock, so the wake-write and the
+//!   dispose-close are mutually exclusive: a wake racing a close either writes
+//!   before close, or sees the `-1` close swapped in and skips — never writing
+//!   to a closed (and possibly reused) fd number.
+//!
+//! ## FFI thread-safety invariant
+//! Ruby `Value`s may only be created on the Ruby VM thread. The spawned future
+//! therefore yields **plain Rust data** (`Result<T, MappedError>`); the stored
+//! producer closure captures that data plus a `to_ruby` converter and is only
+//! ever invoked inside `take_result`, on the Ruby thread. No `magnus` value is
+//! constructed on a tokio worker thread.
+
+use std::future::Future;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+
+use magnus::{Error, IntoValue, Ruby, Value};
+use tokio::task::JoinHandle;
+
+use crate::errors::{ErrorKind, MappedError};
+use crate::runtime::runtime;
+
+/// A closure that converts the task's stored outcome into a Ruby value (or a
+/// mapped exception). Built on the tokio thread from pure Rust data, but only
+/// *called* on the Ruby thread inside `take_result`.
+type ResultProducer = Box<dyn FnOnce(&Ruby) -> Result<Value, Error> + Send>;
+
+/// Result slot shared between the tokio task and the Ruby thread.
+/// `None` = not yet complete. `Some(producer)` = completed; run the producer on
+/// the Ruby thread to obtain the value (or raise the mapped error).
+type Slot = Arc<Mutex<Option<ResultProducer>>>;
+
+/// Disposal-guarded write end of the self-pipe, shared between the tokio task
+/// (which writes the wake byte) and the Ruby thread (which closes it on
+/// dispose). Holding the lock makes wake-write and dispose-close mutually
+/// exclusive so they can never touch the same fd number concurrently: a
+/// concurrent wake either writes-then-dispose-closes, or observes `-1` (already
+/// swapped out by dispose) and skips the write entirely. Set to `-1` once
+/// disposed.
+type WriteFd = Arc<Mutex<i32>>;
+
+#[magnus::wrap(class = "QuietQUIC::Native::PendingOp", free_immediately, size)]
+pub(crate) struct PendingOp {
+    /// Read end of the self-pipe. Set to `-1` once disposed.
+    read_fd: Mutex<i32>,
+    /// Write end of the self-pipe (see [`WriteFd`]). Shared with the tokio task.
+    write_fd: WriteFd,
+    /// Set once `close`/`Drop` has released the fds + aborted the task, so the
+    /// operations are idempotent and `Drop` never double-closes after `close`.
+    disposed: AtomicBool,
+    slot: Slot,
+    handle: JoinHandle<()>,
+}
+
+impl PendingOp {
+    /// Spawn `future` (yielding `Result<T, MappedError>`) on the shared runtime,
+    /// returning a `PendingOp` whose fd becomes readable when it resolves. The
+    /// `to_ruby` converter runs later, on the Ruby thread, inside `take_result`.
+    ///
+    /// This is the generic op-spawning primitive used by every quietquic async
+    /// operation; only `future` and `to_ruby` change per op.
+    pub(crate) fn spawn_op<F, T>(future: F, to_ruby: fn(T) -> Value) -> Result<Self, Error>
+    where
+        F: Future<Output = Result<T, MappedError>> + Send + 'static,
+        T: Send + 'static,
+    {
+        // Create the self-pipe. `pipe(2)` is portable across macOS / FreeBSD /
+        // Linux (unlike `pipe2`, which is absent on macOS). fds[0] = read end,
+        // fds[1] = write end.
+        let mut fds: [i32; 2] = [0; 2];
+        let rc = unsafe { libc::pipe(fds.as_mut_ptr()) };
+        if rc != 0 {
+            return Err(setup_error(&format!(
+                "pipe failed: {}",
+                std::io::Error::last_os_error()
+            )));
+        }
+        let read_fd = fds[0];
+        let write_fd = fds[1];
+
+        // Set FD_CLOEXEC on both ends so the fds don't leak into forked
+        // children. CLOEXEC is security-relevant, so a failure is fatal to op
+        // setup: close the fds we opened and raise rather than proceed.
+        if let Err(e) = set_cloexec(read_fd).and_then(|()| set_cloexec(write_fd)) {
+            unsafe {
+                libc::close(read_fd);
+                libc::close(write_fd);
+            }
+            return Err(setup_error(&e));
+        }
+
+        // Guard against a fork(2) between runtime init and this spawn: the
+        // global runtime's worker threads do not survive a fork, so a spawn from
+        // a post-fork child would never run — the await would hang forever.
+        // Detect it here (on the Ruby thread, before spawning) and raise a clear
+        // `QuietQUIC::Error` instead. Close the raw fds we just opened first.
+        if let Err(e) = crate::runtime::ensure_same_process() {
+            unsafe {
+                libc::close(read_fd);
+                libc::close(write_fd);
+            }
+            return Err(e);
+        }
+
+        let slot: Slot = Arc::new(Mutex::new(None));
+        let task_slot = Arc::clone(&slot);
+
+        // The write fd is shared, not copied, into the task. `wake` writes to it
+        // only while holding this lock and only if it is still valid (>= 0), so
+        // dispose (which swaps it to -1 under the same lock before closing) and
+        // wake are mutually exclusive — no stray write into a reused fd number.
+        let write_fd: WriteFd = Arc::new(Mutex::new(write_fd));
+        let task_write_fd = Arc::clone(&write_fd);
+
+        // Spawn onto the shared runtime. On completion: store then signal.
+        let handle = runtime().spawn(async move {
+            // Catch a panic inside the op's future so it becomes a stored error
+            // + a wake, instead of leaving the slot empty (which would park the
+            // awaiting fiber/thread forever). `AssertUnwindSafe` is sound here:
+            // on the unwind path we discard the payload and produce a fresh
+            // `MappedError` — no possibly-inconsistent captured state is
+            // observed across the catch.
+            use futures_util::future::FutureExt;
+            let outcome = match std::panic::AssertUnwindSafe(future).catch_unwind().await {
+                Ok(outcome) => outcome,
+                Err(_panic_payload) => Err(MappedError::new(
+                    ErrorKind::Base,
+                    "quietquic internal error: the async operation panicked",
+                )),
+            };
+            // Build the *producer* on this (tokio) thread from plain Rust data
+            // only. It captures `outcome` + `to_ruby` and defers all Ruby-value
+            // creation to when it is called on the Ruby thread.
+            let producer: ResultProducer = Box::new(move |_ruby: &Ruby| match outcome {
+                Ok(value) => Ok(to_ruby(value)),
+                Err(mapped) => Err(mapped.into_ruby_error(_ruby)),
+            });
+            // Store the producer BEFORE writing the wake byte so the reader
+            // always sees a populated slot once the fd is readable.
+            {
+                let mut guard = task_slot.lock().unwrap();
+                *guard = Some(producer);
+            }
+            wake(&task_write_fd);
+        });
+
+        Ok(PendingOp {
+            read_fd: Mutex::new(read_fd),
+            write_fd,
+            disposed: AtomicBool::new(false),
+            slot,
+            handle,
+        })
+    }
+
+    /// The read end of the self-pipe, as an integer fd. Becomes readable when
+    /// the operation completes. Returns `-1` once disposed.
+    fn fd(&self) -> i32 {
+        *self.read_fd.lock().unwrap()
+    }
+
+    /// Take and run the completed result producer on the Ruby thread, returning
+    /// the Ruby value or raising the mapped `QuietQUIC::*` exception. Raises if
+    /// the op has not completed yet, or if it was already taken (drained).
+    fn take_result(ruby: &Ruby, rb_self: &Self) -> Result<Value, Error> {
+        let producer = {
+            let mut guard = rb_self.slot.lock().unwrap();
+            guard.take()
+        };
+        match producer {
+            Some(producer) => producer(ruby),
+            None => Err(Error::new(
+                ruby.exception_runtime_error(),
+                "take_result called before completion (or already taken)",
+            )),
+        }
+    }
+
+    /// Abort the task and close both fds immediately. Idempotent: safe to call
+    /// twice, and `Drop` will not double-close after an explicit `close`.
+    fn close(&self) {
+        self.dispose();
+    }
+
+    /// Shared disposal path for `close` and `Drop`.
+    fn dispose(&self) {
+        // Ensure the abort+close body runs exactly once.
+        if self.disposed.swap(true, Ordering::AcqRel) {
+            return;
+        }
+        // Abort the tokio task if still running (best-effort; can't preempt a
+        // synchronous `wake` already past its `.await`).
+        self.handle.abort();
+        // Close the write fd under its lock so a concurrent `wake` either wrote
+        // its byte before we swap (and we close after), or observes the -1 we
+        // swapped in and skips the write. Either way, no write lands on the fd
+        // number after we close it. Swap+close happen while holding the lock.
+        {
+            let mut guard = self.write_fd.lock().unwrap();
+            let write_fd = std::mem::replace(&mut *guard, -1);
+            if write_fd >= 0 {
+                unsafe {
+                    libc::close(write_fd);
+                }
+            }
+        }
+        // Swap the read fd out to -1 under its lock, then close what we took.
+        let read_fd = std::mem::replace(&mut *self.read_fd.lock().unwrap(), -1);
+        unsafe {
+            if read_fd >= 0 {
+                libc::close(read_fd);
+            }
+        }
+    }
+}
+
+impl Drop for PendingOp {
+    fn drop(&mut self) {
+        self.dispose();
+    }
+}
+
+/// Set `FD_CLOEXEC` on `fd`, preserving any existing flags. Returns a message
+/// on failure so the caller can turn it into a setup error.
+fn set_cloexec(fd: i32) -> Result<(), String> {
+    let flags = unsafe { libc::fcntl(fd, libc::F_GETFD) };
+    if flags < 0 {
+        return Err(format!(
+            "fcntl(F_GETFD) failed: {}",
+            std::io::Error::last_os_error()
+        ));
+    }
+    let rc = unsafe { libc::fcntl(fd, libc::F_SETFD, flags | libc::FD_CLOEXEC) };
+    if rc < 0 {
+        return Err(format!(
+            "fcntl(F_SETFD, FD_CLOEXEC) failed: {}",
+            std::io::Error::last_os_error()
+        ));
+    }
+    Ok(())
+}
+
+/// Write one wake byte to the shared write fd, retrying on EINTR. Called on the
+/// tokio thread after the slot is populated.
+///
+/// The lock is held for the duration of the write so it is mutually exclusive
+/// with `dispose`'s swap-to-`-1`-then-close: if we get the lock first we write
+/// to a still-open fd and dispose closes it afterwards; if dispose got it first
+/// the fd is already `-1` and we skip entirely — never writing to a closed (and
+/// possibly reused) fd number. The write is a single-byte, non-blocking write on
+/// a self-pipe, so the lock is held only briefly.
+fn wake(write_fd: &WriteFd) {
+    let guard = write_fd.lock().unwrap();
+    let fd = *guard;
+    if fd < 0 {
+        // Already disposed; the reader is gone. Nothing to do.
+        return;
+    }
+    let byte: [u8; 1] = [1];
+    loop {
+        let n = unsafe { libc::write(fd, byte.as_ptr() as *const libc::c_void, 1) };
+        if n == 1 {
+            break;
+        }
+        if n < 0 {
+            let e = std::io::Error::last_os_error();
+            if e.raw_os_error() == Some(libc::EINTR) {
+                continue;
+            }
+            // Write end broken (e.g. reader closed). Nothing to do.
+            break;
+        }
+        // n == 0 shouldn't happen for a 1-byte write; retry.
+    }
+}
+
+/// Build a magnus setup error (raised on the Ruby thread during op creation).
+fn setup_error(message: &str) -> Error {
+    let ruby = Ruby::get().expect("PendingOp setup called off a Ruby thread");
+    Error::new(ruby.exception_runtime_error(), message.to_string())
+}
+
+/// `QuietQUIC::Native.sleep_op(millis) -> PendingOp`.
+/// Spawns `tokio::time::sleep(millis)`, then yields `millis` as an integer.
+pub(crate) fn sleep_op(millis: u64) -> Result<PendingOp, Error> {
+    PendingOp::spawn_op(
+        async move {
+            tokio::time::sleep(std::time::Duration::from_millis(millis)).await;
+            Ok::<i64, MappedError>(millis as i64)
+        },
+        |millis: i64| {
+            let ruby = Ruby::get().expect("to_ruby runs on the Ruby thread");
+            millis.into_value_with(&ruby)
+        },
+    )
+}
+
+/// `QuietQUIC::Native.echo_op(str) -> PendingOp`.
+/// Yields the given string back through the generalized slot (a `String`
+/// payload exercises the byte/text conversion path Tasks 4-8 will use).
+pub(crate) fn echo_op(s: String) -> Result<PendingOp, Error> {
+    PendingOp::spawn_op(
+        async move { Ok::<String, MappedError>(s) },
+        |s: String| {
+            let ruby = Ruby::get().expect("to_ruby runs on the Ruby thread");
+            s.into_value_with(&ruby)
+        },
+    )
+}
+
+/// `QuietQUIC::Native.nil_op -> PendingOp`.
+/// Yields `nil` through the generalized slot (the unit/`nil` payload path).
+pub(crate) fn nil_op() -> Result<PendingOp, Error> {
+    PendingOp::spawn_op(
+        async move { Ok::<(), MappedError>(()) },
+        |_unit: ()| {
+            let ruby = Ruby::get().expect("to_ruby runs on the Ruby thread");
+            ruby.qnil().into_value_with(&ruby)
+        },
+    )
+}
+
+/// `QuietQUIC::Native.fail_op(kind) -> PendingOp`.
+/// Test helper: yields a `MappedError` classified by `kind`, so `take_result`
+/// raises the corresponding `QuietQUIC::*` exception. Exercises the error path.
+pub(crate) fn fail_op(kind: String) -> Result<PendingOp, Error> {
+    let error_kind = ErrorKind::from_str(&kind);
+    let message = format!("simulated {kind} failure");
+    PendingOp::spawn_op(
+        async move { Err::<(), MappedError>(MappedError::new(error_kind, message)) },
+        // Never reached for the error path, but the type must line up.
+        |_unit: ()| {
+            let ruby = Ruby::get().expect("to_ruby runs on the Ruby thread");
+            ruby.qnil().into_value_with(&ruby)
+        },
+    )
+}
+
+/// `QuietQUIC::Native.panic_op -> PendingOp` (dev/test helper).
+/// Spawns a future that `panic!`s. Exercises the panic-catch path: awaiting it
+/// must raise `QuietQUIC::Error` (never hang), because the spawn wrapper turns
+/// a panic into a stored error + a wake byte.
+pub(crate) fn panic_op() -> Result<PendingOp, Error> {
+    PendingOp::spawn_op(
+        async move {
+            panic!("simulated async-op panic");
+            #[allow(unreachable_code)]
+            Ok::<(), MappedError>(())
+        },
+        // Never reached: the panic path stores a base-class MappedError.
+        |_unit: ()| {
+            let ruby = Ruby::get().expect("to_ruby runs on the Ruby thread");
+            ruby.qnil().into_value_with(&ruby)
+        },
+    )
+}
+
+/// Register `PendingOp` and its instance methods on `QuietQUIC::Native`.
+pub(crate) fn init(ruby: &Ruby, native: &magnus::RModule) -> Result<(), Error> {
+    use magnus::{method, Module};
+
+    let class = native.define_class("PendingOp", ruby.class_object())?;
+    class.define_method("fd", method!(PendingOp::fd, 0))?;
+    class.define_method("take_result", method!(PendingOp::take_result, 0))?;
+    class.define_method("close", method!(PendingOp::close, 0))?;
+    // `dispose` is an alias for `close` (explicit-disposal API).
+    class.define_method("dispose", method!(PendingOp::close, 0))?;
+    Ok(())
+}

data/ext/quietquic/src/runtime.rs

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: 0BSD
+//! Process-global multi-thread tokio runtime shared by all async operations.
+//!
+//! The runtime is created lazily on first use and lives for the life of the
+//! process. Ruby threads spawn futures onto it and wait for completion via a
+//! self-pipe fd (see [`crate::pending`]).
+//!
+//! ## Fork safety
+//! A tokio multi-thread runtime's worker threads do **not** survive `fork(2)`:
+//! only the forking thread is duplicated into the child, so any work spawned
+//! from a child that inherited an already-initialized runtime would never run
+//! and the awaiting fiber/thread would hang forever. This is the classic
+//! pre-forking-server (Puma/Unicorn/Spring) hazard. To turn that silent hang
+//! into an actionable error we record the PID at runtime initialization and
+//! check it before every spawn (see [`ensure_same_process`]); a child that
+//! inherited the parent's runtime gets a clear `QuietQUIC::Error` telling it
+//! to initialize the runtime *after* forking.
+
+use std::sync::atomic::{AtomicI32, Ordering};
+use std::sync::OnceLock;
+
+use magnus::{Error, Ruby};
+use tokio::runtime::{Builder, Runtime};
+
+static RUNTIME: OnceLock<Runtime> = OnceLock::new();
+
+/// PID of the process that first initialized the runtime. `-1` until set.
+/// Recorded once, inside the `OnceLock` initializer, so it always reflects the
+/// process whose worker threads actually back the runtime.
+static INIT_PID: AtomicI32 = AtomicI32::new(-1);
+
+/// Return a reference to the process-global tokio runtime, initializing it on
+/// first call. Subsequent calls return the same runtime.
+pub(crate) fn runtime() -> &'static Runtime {
+    RUNTIME.get_or_init(|| {
+        // Record the PID of the process that owns the runtime's worker threads.
+        // Done inside the initializer so it is set exactly once, together with
+        // the threads it describes.
+        INIT_PID.store(unsafe { libc::getpid() }, Ordering::SeqCst);
+        Builder::new_multi_thread()
+            .enable_all()
+            .thread_name("quietquic-rt")
+            .build()
+            .expect("failed to build quietquic tokio runtime")
+    })
+}
+
+/// Verify the current process is the one that initialized the runtime.
+///
+/// Called on the Ruby thread just before spawning an op. Forcing initialization
+/// here (via [`runtime`]) means a fresh child that never touched the runtime
+/// initializes it in *its own* process — no false positive; only a child that
+/// inherited an already-built runtime from its parent trips the guard.
+///
+/// On mismatch, returns a `QuietQUIC::Error` (the base class) rather than
+/// letting the spawn silently hang forever on a dead runtime.
+pub(crate) fn ensure_same_process() -> Result<(), Error> {
+    // Ensure the runtime (and thus INIT_PID) is initialized in *some* process.
+    let _ = runtime();
+    let init_pid = INIT_PID.load(Ordering::SeqCst);
+    let current = unsafe { libc::getpid() };
+    if init_pid != current {
+        let ruby = Ruby::get().expect("ensure_same_process runs on a Ruby thread");
+        return Err(Error::new(
+            crate::errors::base_error_class(&ruby),
+            "quietquic's async runtime does not survive fork(); initialize it \
+             after forking (e.g. in a Puma on_worker_boot / after_fork hook) \
+             rather than before",
+        ));
+    }
+    Ok(())
+}