kino 0.1.3 → 0.2.1

data/README.md

@@ -21,6 +21,8 @@ and a threaded fallback mode runs everything else, Rails included.
   small process.
 * **Production plumbing included.** Graceful drain, crash supervision
   and respawn, bounded queues with 503 backpressure, request timeouts,
+  hardened intake (slowloris and TLS-handshake deadlines, connection
+  and body-size caps), an `on_error` hook for your error tracker,
   TLS (rustls), live stats, async access and app logging.
 * **Tells you why.** `kino --check` lists exactly what blocks your app
   from ractor mode, finding by finding, so you do not have to decode
@@ -181,7 +183,7 @@ bundle add kino      # or: gem install kino (outside a bundle)
 or put it in the `Gemfile` yourself:
 
 ```ruby
-gem "kino", "~> 0.1"
+gem "kino"
 ```
 
 Then generate a config and serve:
@@ -224,6 +226,9 @@ server = Kino::Server.new(app,
   queue_depth: 1024,          # bounded queue; overflow → 503
   queue_timeout: 5.0,         # seconds before 503 on a full queue
   request_timeout: nil,       # seconds before a slow response becomes a 504 (nil = off)
+  max_connections: 8192,      # cap concurrent connections; default: most of ulimit -n
+  max_body_size: 50 * 1024 * 1024,  # bytes before a 413; nil = let a proxy handle it
+  on_error: ->(e, env) { ErrorTracker.capture(e) },  # after the client got its 500
   shutdown_timeout: 30,       # drain deadline
   tls: { cert: "cert.pem", key: "key.pem" },  # file paths or inline PEM
 )
@@ -303,6 +308,18 @@ is unsafe. A stuck handler still occupies its worker slot until it
 returns, so set the deadline above your slowest legitimate endpoint and
 watch `stats[:timeouts]`.
 
+Timeouts guard your app; the network intake guards itself. New
+connections past `max_connections` (default: most of `ulimit -n`) wait
+in the kernel backlog; request bodies past `max_body_size` (default
+50 MB, `nil` delegates to a fronting proxy) get a **413**; and fixed
+deadlines drop slow-header clients (15 s), stalled TLS handshakes
+(10 s), and uploads stalled mid-body (30 s). When a worker catches an
+app or delivery error,
+`on_error ->(error, env) { ErrorTracker.capture(error) }` is called
+after the client got its 500—the only place a tracker sees errors
+raised while the response was being written (in `:ractor` mode, build
+the handler with `Ractor.shareable_proc`).
+
 ## Stats
 
 `server.stats` returns a live snapshot: the configuration plus counters
@@ -415,6 +432,14 @@ bundle exec rake                       # compile, Rust tests, specs, RBS, lint
 RB_SYS_CARGO_PROFILE=dev bundle exec rake compile   # fast dev rebuilds
 ```
 
+## Acknowledgements
+
+Thanks to [Mat Sadler](https://github.com/matsadler) for [magnus](https://github.com/matsadler/magnus).
+
+For ractors, thanks to [Koichi Sasada](https://github.com/ko1), [John Hawthorn](https://github.com/jhawthorn), [Jean Boussier](https://github.com/byroot), [Luke Gruber](https://github.com/luke-gruber), and other Ruby core contributors.
+
+For the Rust network stack, thanks to [Sean McArthur](https://github.com/seanmonstar) for [hyper](https://github.com/hyperium/hyper), and to [Carl Lerche](https://github.com/carllerche), [Alice Ryhl](https://github.com/Darksonn), and the other [Tokio](https://github.com/tokio-rs/tokio) maintainers for the runtime underneath it. Thanks to [Joshua Barretto](https://github.com/zesterer) for [flume](https://github.com/zesterer/flume)—its channels carry every request between the network side and the workers.
+
 ## Assisted by
 
 Claude Code (Mythos, Opus).

data/ext/kino/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kino"
-version = "0.1.3"
+version = "0.2.1"
 edition = "2021"
 authors = ["Yaroslav Markin <yaroslav@markin.net>"]
 license = "MIT"
@@ -14,11 +14,11 @@ crate-type = ["cdylib", "rlib"]
 [dependencies]
 magnus = { version = "0.8.2", features = ["rb-sys"] }
 rb-sys = { version = "0.9", features = ["stable-api-compiled-fallback"] }
-flume = "0.11"
+flume = "0.12"
 parking_lot = "0.12"
 ahash = "0.8"
 smallvec = "1"
-lru = "0.12"
+lru = "0.18"
 mimalloc = { version = "0.1", default-features = false }
 tokio = { version = "1.45", features = ["rt-multi-thread", "net", "time", "sync", "io-util", "macros"] }
 hyper = { version = "1.6", features = ["http1", "server"] }

data/ext/kino/src/gvl.rs

@@ -5,7 +5,11 @@
 //! body reads/writes) must go through `without_gvl` so other Ruby threads
 //! in the same ractor keep running and the VM can interrupt us via the UBF.
 
+use std::any::Any;
 use std::ffi::c_void;
+use std::panic::{catch_unwind, AssertUnwindSafe};
+
+use magnus::{Error, Ruby};
 
 /// An unblock function: called by the Ruby VM from another thread when it
 /// needs to interrupt the blocking region (Thread#kill, VM shutdown, ...).
@@ -20,23 +24,48 @@ unsafe extern "C" fn trampoline<F, R>(arg: *mut c_void) -> *mut c_void
 where
     F: FnOnce() -> R,
 {
-    let slot = unsafe { &mut *(arg as *mut (Option<F>, Option<R>)) };
+    let slot = unsafe { &mut *(arg as *mut (Option<F>, Option<std::thread::Result<R>>)) };
     let f = slot.0.take().expect("without_gvl trampoline called twice");
-    slot.1 = Some(f());
+    // A panic must not unwind into the VM's C frame beneath us (that
+    // aborts the process); catch it here and let without_gvl rethrow it
+    // as a Ruby exception once the GVL is held again.
+    slot.1 = Some(catch_unwind(AssertUnwindSafe(f)));
     std::ptr::null_mut()
 }
 
+/// The caught panic payload as a plain RuntimeError, built with the GVL
+/// held. Deliberately not magnus's own panic conversion: that raises
+/// `fatal`, which still ends the process; a RuntimeError flows through
+/// the worker's normal rescue path (500, on_error, error log, respawn).
+fn panic_error(payload: Box<dyn Any + Send>) -> Error {
+    let msg = if let Some(m) = payload.downcast_ref::<&'static str>() {
+        (*m).to_string()
+    } else if let Some(m) = payload.downcast_ref::<String>() {
+        m.clone()
+    } else {
+        "opaque panic payload".to_string()
+    };
+    let ruby = Ruby::get().expect("without_gvl requires a Ruby thread");
+    Error::new(
+        ruby.exception_runtime_error(),
+        format!("Kino: panic in native blocking call: {msg}"),
+    )
+}
+
 /// Run `f` with the GVL released. Blocks the current Ruby thread but lets
 /// every other Ruby thread (in this ractor) run in parallel.
 ///
 /// `f` MUST NOT touch any Ruby API. If `ubf` fires, `f` is responsible for
 /// noticing (e.g. a message on an interrupt channel) and returning promptly;
 /// pending VM interrupts are then delivered once we're back in Ruby.
-pub fn without_gvl<F, R>(f: F, ubf: Option<Ubf>) -> R
+///
+/// A panic in `f` comes back as `Err` (RuntimeError with the panic
+/// message); the default panic hook still reports it to stderr first.
+pub fn without_gvl<F, R>(f: F, ubf: Option<Ubf>) -> Result<R, Error>
 where
     F: FnOnce() -> R,
 {
-    let mut slot: (Option<F>, Option<R>) = (Some(f), None);
+    let mut slot: (Option<F>, Option<std::thread::Result<R>>) = (Some(f), None);
     let (ubf_func, ubf_data) = match ubf {
         Some(u) => (Some(u.func), u.data),
         None => (None, std::ptr::null_mut()),
@@ -49,7 +78,10 @@ where
             ubf_data,
         );
     }
-    slot.1.expect("without_gvl block did not run")
+    match slot.1.expect("without_gvl block did not run") {
+        Ok(value) => Ok(value),
+        Err(payload) => Err(panic_error(payload)),
+    }
 }
 
 /// The standard UBF used across this crate: `data` points at an `AtomicBool`
@@ -64,12 +96,13 @@ pub unsafe extern "C" fn ubf_interrupt(data: *mut c_void) {
 /// The crate's one blocking idiom: release the GVL and run `attempt` in a
 /// loop (`Some(T)` finishes, `None` means "tick elapsed, go around"), and
 /// wake within a tick when `flag` is raised (by the VM's UBF or by
-/// interrupt_all_workers). Returns None on interruption. `attempt` must
-/// bound each wait (recv_timeout-style) and must not touch the Ruby API.
+/// interrupt_all_workers). Returns Ok(None) on interruption, Err when
+/// `attempt` panicked. `attempt` must bound each wait (recv_timeout-style)
+/// and must not touch the Ruby API.
 pub fn interruptible<T>(
     flag: &std::sync::atomic::AtomicBool,
     mut attempt: impl FnMut() -> Option<T>,
-) -> Option<T> {
+) -> Result<Option<T>, Error> {
     use std::sync::atomic::Ordering;
 
     without_gvl(

data/ext/kino/src/lib.rs

@@ -7,6 +7,7 @@ static GLOBAL: mimalloc::MiMalloc = mimalloc::MiMalloc;
 mod env_strings;
 mod gvl;
 mod logsink;
+mod pin;
 mod queue;
 mod registry;
 mod request;
@@ -59,6 +60,9 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         function!(env_strings::register_defaults, 2),
     )?;
 
+    native.define_class("PinKeeper", ruby.class_object())?;
+    native.define_singleton_method("pin_keeper", function!(server::pin_keeper, 1))?;
+
     let request = native.define_class("Request", ruby.class_object())?;
     request.define_method("respond_and_take", method!(queue::respond_and_take, 6))?;
     request.define_method(
@@ -85,6 +89,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     native.define_singleton_method("_test_push", function!(test_support::push, 2))?;
     native.define_singleton_method("_test_take", function!(test_support::take, 1))?;
     native.define_singleton_method("_test_close", function!(test_support::close, 1))?;
+    native.define_singleton_method("_test_panic", function!(test_support::panic_in_release, 0))?;
 
     Ok(())
 }

data/ext/kino/src/pin.rs

@@ -0,0 +1,223 @@
+//! Zero-copy response bodies: a large body's bytes ride to hyper in
+//! place instead of being copied at the FFI boundary, with the backing
+//! Ruby string kept alive until hyper drops the buffer.
+//!
+//! Buffer stability is the same mechanism io.c uses to hold a string
+//! across a GVL-released write: `rb_str_tmp_frozen_acquire` returns a
+//! frozen string sharing the original's byte buffer (a frozen original
+//! is returned as-is). Mutating the original afterwards copy-on-writes
+//! the ORIGINAL side, so the shared buffer stays byte-stable for as
+//! long as the acquired string lives.
+//!
+//! Liveness is a fixed slab of atomic VALUE slots per server, marked
+//! from a `PinKeeper` TypedData object that the Ruby `Kino::Server`
+//! holds for the server's lifetime (pin.rs never registers global GC
+//! roots: `rb_gc_register_address` is not ractor-safe in Ruby 4.0).
+//! The mark hook uses the pinning `rb_gc_mark`, so compaction never
+//! moves a pinned string either. Because the keeper lives on the main
+//! ractor, pinned buffers survive worker-ractor crashes while hyper is
+//! still flushing them.
+//!
+//! Concurrency: inserts happen on worker threads (any ractor, its own
+//! GVL held), release is a single atomic store from whatever tokio
+//! thread drops the buffer, and the mark hook only loads atomics, so
+//! no path takes a lock. A full slab degrades to the copy path.
+
+use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
+use std::sync::Arc;
+
+use bytes::Bytes;
+use magnus::rb_sys::AsRawValue;
+use magnus::RString;
+
+/// Floor for the zero-copy path. Below it the pin machinery costs more
+/// than the memcpy it saves. It is also a SOUNDNESS bound: it must
+/// exceed the largest embeddable string (a 640-byte GC slot in Ruby
+/// 4.0), so the acquired string's bytes are guaranteed to live in a
+/// stable malloc'd buffer rather than inside a movable RVALUE, and the
+/// string can never be re-embedded by compaction.
+pub const ZERO_COPY_MIN: usize = 4096;
+
+/// In-flight pins per server. Bounds slab memory (8 bytes per slot) and
+/// GC mark work; overflow falls back to copying, so the cap is a
+/// throughput heuristic, not a limit on concurrency.
+const SLAB_CAPACITY: usize = 4096;
+
+extern "C" {
+    // Exported by libruby but absent from the public headers: io.c's
+    // buffer-stabilizing primitive (see module docs). Signature per
+    // string.c: VALUE rb_str_tmp_frozen_acquire(VALUE orig).
+    fn rb_str_tmp_frozen_acquire(orig: rb_sys::VALUE) -> rb_sys::VALUE;
+}
+
+/// GC roots for in-flight response buffers. Slot value 0 = empty (a
+/// VALUE of 0 is Qfalse, which can never be a pinned string).
+pub struct PinSlab {
+    slots: Box<[AtomicU64]>,
+    /// Rotating claim cursor: keeps the free-slot scan O(1) amortized.
+    cursor: AtomicUsize,
+}
+
+impl PinSlab {
+    pub fn new() -> Self {
+        PinSlab {
+            slots: (0..SLAB_CAPACITY).map(|_| AtomicU64::new(0)).collect(),
+            cursor: AtomicUsize::new(0),
+        }
+    }
+
+    /// Root `value`; None when the slab is full (caller copies instead).
+    fn insert(&self, value: rb_sys::VALUE) -> Option<usize> {
+        let start = self.cursor.fetch_add(1, Ordering::Relaxed);
+        for offset in 0..self.slots.len() {
+            let index = (start + offset) % self.slots.len();
+            if self.slots[index]
+                .compare_exchange(0, value, Ordering::SeqCst, Ordering::Relaxed)
+                .is_ok()
+            {
+                return Some(index);
+            }
+        }
+        None
+    }
+
+    /// Drop the root. Called from tokio threads: a plain atomic store,
+    /// no Ruby API. The string stays alive until the next GC sweep.
+    fn release(&self, index: usize) {
+        self.slots[index].store(0, Ordering::SeqCst);
+    }
+
+    /// GC mark hook (PinKeeper). Runs during stop-the-world, so it must
+    /// not allocate, lock, or panic: it only loads atomics. A slot
+    /// concurrently released by a tokio thread is seen as either the
+    /// live value (marked one cycle longer, harmless) or 0 (skipped).
+    pub fn mark_all(&self) {
+        for slot in self.slots.iter() {
+            let value = slot.load(Ordering::SeqCst);
+            if value != 0 {
+                // SAFETY: non-zero slots hold VALUEs inserted by
+                // pinned_bytes and not yet released, i.e. live objects;
+                // rb_gc_mark is the pinning mark, callable from a mark
+                // hook by design.
+                unsafe { rb_sys::rb_gc_mark(value) };
+            }
+        }
+    }
+
+    #[cfg(test)]
+    fn occupied(&self) -> usize {
+        self.slots
+            .iter()
+            .filter(|s| s.load(Ordering::SeqCst) != 0)
+            .count()
+    }
+}
+
+/// The GC-visible face of a server's PinSlab: `Kino::Server` holds one
+/// for its lifetime (surviving worker-ractor crashes), and Ruby's GC
+/// marks every pinned string through it.
+#[derive(magnus::TypedData)]
+#[magnus(class = "Kino::Native::PinKeeper", free_immediately, mark)]
+pub struct PinKeeper(pub Arc<PinSlab>);
+
+impl magnus::DataTypeFunctions for PinKeeper {
+    fn mark(&self, _marker: &magnus::gc::Marker) {
+        self.0.mark_all();
+    }
+}
+
+/// Owns one in-flight buffer: the raw view plus the slab slot rooting
+/// the acquired string.
+struct PinnedBuf {
+    slab: Arc<PinSlab>,
+    index: usize,
+    ptr: *const u8,
+    len: usize,
+}
+
+// SAFETY: the only operations performed off the Ruby thread are reading
+// the byte buffer (the acquired string is frozen and slab-rooted: no
+// writer exists and the buffer neither moves nor frees while the slot
+// holds it) and Drop's atomic store. No Ruby API is called off-thread.
+unsafe impl Send for PinnedBuf {}
+
+impl AsRef<[u8]> for PinnedBuf {
+    fn as_ref(&self) -> &[u8] {
+        // SAFETY: ptr/len were captured under the GVL from the acquired
+        // frozen string, which stays alive and byte-stable until this
+        // owner releases its slot (see module docs).
+        unsafe { std::slice::from_raw_parts(self.ptr, self.len) }
+    }
+}
+
+impl Drop for PinnedBuf {
+    fn drop(&mut self) {
+        self.slab.release(self.index);
+    }
+}
+
+/// Bytes borrowing `body`'s buffer, with the string rooted until hyper
+/// drops it; None when the body is below ZERO_COPY_MIN or the slab is
+/// full (caller copies). Requires the calling worker's GVL; safe from
+/// any ractor.
+pub fn pinned_bytes(slab: &Arc<PinSlab>, body: RString) -> Option<Bytes> {
+    if body.len() < ZERO_COPY_MIN {
+        return None;
+    }
+    // SAFETY: this worker's GVL is held; body is a live RString rooted
+    // by the caller. The acquired tmp is rooted by this thread's machine
+    // stack (conservatively scanned) until the slab insert publishes it.
+    let tmp = unsafe { rb_str_tmp_frozen_acquire(body.as_raw()) };
+    let index = slab.insert(tmp)?;
+    // SAFETY: tmp is frozen, alive, and slab-rooted; len >= ZERO_COPY_MIN
+    // rules out an embedded buffer, so ptr is a stable heap allocation.
+    let (ptr, len) = unsafe {
+        (
+            rb_sys::macros::RSTRING_PTR(tmp) as *const u8,
+            rb_sys::macros::RSTRING_LEN(tmp) as usize,
+        )
+    };
+    Some(Bytes::from_owner(PinnedBuf {
+        slab: slab.clone(),
+        index,
+        ptr,
+        len,
+    }))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn insert_release_reuse_cycle() {
+        let slab = PinSlab::new();
+        let a = slab.insert(0x1000).expect("slot free");
+        let b = slab.insert(0x2000).expect("slot free");
+        assert_ne!(a, b);
+        assert_eq!(slab.occupied(), 2);
+
+        slab.release(a);
+        assert_eq!(slab.occupied(), 1);
+
+        // The freed slot is claimable again.
+        let c = slab.insert(0x3000).expect("slot free");
+        assert_eq!(slab.occupied(), 2);
+        slab.release(b);
+        slab.release(c);
+        assert_eq!(slab.occupied(), 0);
+    }
+
+    #[test]
+    fn full_slab_refuses_instead_of_evicting() {
+        let slab = PinSlab::new();
+        let indexes: Vec<usize> = (0..SLAB_CAPACITY)
+            .map(|i| slab.insert(0x1000 + i as rb_sys::VALUE).expect("capacity"))
+            .collect();
+        assert_eq!(slab.occupied(), SLAB_CAPACITY);
+        assert!(slab.insert(0x9999).is_none());
+
+        slab.release(indexes[7]);
+        assert_eq!(slab.insert(0x9999), Some(indexes[7]));
+    }
+}

data/ext/kino/src/queue.rs

@@ -30,7 +30,7 @@ type Taken = Option<BoxedCtx>;
 /// cost is real (~20% of cycles at saturation, per perf), but a measured
 /// 20µs spin made things WORSE on oversubscribed cores: spinners steal
 /// exactly the CPU the tokio threads need.
-fn block_take(server: &ServerInner, slot: &Arc<WorkerSlot>) -> Taken {
+fn block_take(server: &ServerInner, slot: &Arc<WorkerSlot>) -> Result<Taken, Error> {
     if slot.lane_rx.is_some() {
         return lane_take(server, slot);
     }
@@ -40,15 +40,16 @@ fn block_take(server: &ServerInner, slot: &Arc<WorkerSlot>) -> Taken {
     // try_recv never blocks, so the whole GVL release/reacquire (two
     // scheduler round-trips per request) is skipped entirely.
     match req_rx.try_recv() {
-        Ok(ctx) => Some(ctx),
-        Err(flume::TryRecvError::Disconnected) => None,
+        Ok(ctx) => Ok(Some(ctx)),
+        Err(flume::TryRecvError::Disconnected) => Ok(None),
         Err(flume::TryRecvError::Empty) => {
-            gvl::interruptible(&slot.interrupted, || match req_rx.recv_timeout(TICK) {
-                Ok(ctx) => Some(Some(ctx)),
-                Err(flume::RecvTimeoutError::Timeout) => None,
-                Err(flume::RecvTimeoutError::Disconnected) => Some(None),
-            })
-            .flatten()
+            let taken =
+                gvl::interruptible(&slot.interrupted, || match req_rx.recv_timeout(TICK) {
+                    Ok(ctx) => Some(Some(ctx)),
+                    Err(flume::RecvTimeoutError::Timeout) => None,
+                    Err(flume::RecvTimeoutError::Disconnected) => Some(None),
+                })?;
+            Ok(taken.flatten())
         }
     }
 }
@@ -56,7 +57,7 @@ fn block_take(server: &ServerInner, slot: &Arc<WorkerSlot>) -> Taken {
 /// Lane-mode take: own lane first (no wake needed while the dispatcher
 /// keeps feeding an awake lane), then steal from siblings, then park on
 /// the own lane with the parked flag raised so the dispatcher avoids it.
-fn lane_take(server: &ServerInner, slot: &Arc<WorkerSlot>) -> Taken {
+fn lane_take(server: &ServerInner, slot: &Arc<WorkerSlot>) -> Result<Taken, Error> {
     let lane_rx = slot.lane_rx.as_ref().expect("lane_take without lane");
 
     let steal = || -> Option<BoxedCtx> {
@@ -76,12 +77,12 @@ fn lane_take(server: &ServerInner, slot: &Arc<WorkerSlot>) -> Taken {
 
     // Hot path, GVL still held: own lane, then a steal sweep.
     match lane_rx.try_recv() {
-        Ok(ctx) => return Some(ctx),
-        Err(flume::TryRecvError::Disconnected) => return None,
+        Ok(ctx) => return Ok(Some(ctx)),
+        Err(flume::TryRecvError::Disconnected) => return Ok(None),
         Err(flume::TryRecvError::Empty) => {}
     }
     if let Some(ctx) = steal() {
-        return Some(ctx);
+        return Ok(Some(ctx));
     }
 
     // Park. The flag-then-recheck order closes the race with a dispatcher
@@ -96,10 +97,11 @@ fn lane_take(server: &ServerInner, slot: &Arc<WorkerSlot>) -> Taken {
             Err(flume::RecvTimeoutError::Timeout) => steal().map(Some),
             Err(flume::RecvTimeoutError::Disconnected) => Some(None),
         }
-    })
-    .flatten();
+    });
+    // Unpark before propagating any panic, or the dispatcher shuns this
+    // lane for good.
     slot.parked.store(false, Ordering::SeqCst);
-    taken
+    Ok(taken?.flatten())
 }
 
 /// Wrap a ctx into its env Hash, with the Ruby request handle embedded
@@ -137,7 +139,7 @@ fn checkout(ruby: &Ruby, server_id: u64, worker_id: usize) -> Result<Option<Chec
     slot.current.lock().clear();
     slot.interrupted.store(false, Ordering::SeqCst);
 
-    Ok(block_take(&server, &slot).map(|ctx| (server, slot, ctx)))
+    Ok(block_take(&server, &slot)?.map(|ctx| (server, slot, ctx)))
 }
 
 /// Take one request; returns its env Hash (request handle inside under

data/ext/kino/src/registry.rs

@@ -52,6 +52,9 @@ pub struct ServerInner {
     pub lanes: bool,
     /// Round-robin cursor for lane dispatch.
     pub lane_cursor: AtomicUsize,
+    /// GC roots for zero-copy response buffers (pin.rs). The Ruby Server
+    /// object holds the marking PinKeeper for this slab.
+    pub pin_slab: Arc<crate::pin::PinSlab>,
 }
 
 /// One per worker *thread* (slot count = workers × threads). The interrupt
@@ -189,6 +192,7 @@ pub fn test_server(lanes: bool, queue_depth: usize) -> Arc<ServerInner> {
         access_log: None,
         lanes,
         lane_cursor: AtomicUsize::new(0),
+        pin_slab: Arc::new(crate::pin::PinSlab::new()),
     })
 }
 

data/ext/kino/src/request.rs

@@ -37,6 +37,9 @@ pub struct RequestCtx {
     /// The owning worker slot (set at admit time, queue.rs); its interrupt
     /// flag makes blocked body reads/writes interruptible like the queue pop.
     pub slot: Option<Arc<crate::registry::WorkerSlot>>,
+    /// The server's zero-copy roots: large response bodies are pinned
+    /// here and ride to hyper without a copy (pin.rs).
+    pub pin_slab: Arc<crate::pin::PinSlab>,
     pub responder: Arc<Responder>,
 }
 
@@ -52,12 +55,12 @@ impl Drop for RequestCtx {
 
 /// Block on a channel operation with the GVL released, waking on the
 /// slot's interrupt flag. `attempt` performs one bounded tick and returns
-/// Some when done; None on timeout. Outer None = interrupted. Every Ruby
+/// Some when done; None on timeout. Ok(None) = interrupted. Every Ruby
 /// handle is created by `admit` (queue.rs), which always sets the slot.
 fn block_on<T>(
     slot: &Option<Arc<crate::registry::WorkerSlot>>,
     attempt: impl FnMut() -> Option<T>,
-) -> Option<T> {
+) -> Result<Option<T>, Error> {
     let slot = slot.as_ref().expect("slot set by admit");
     gvl::interruptible(&slot.interrupted, attempt)
 }
@@ -228,13 +231,23 @@ pub fn respond_simple(
 ) -> Result<bool, Error> {
     let ctx = request.0.borrow();
     let builder = build_head(status, headers)?;
-    let bytes = Bytes::copy_from_slice(unsafe { body.as_slice() });
+    let bytes = body_bytes(&ctx, body);
     let response = builder
         .body(full_body(bytes))
         .map_err(|e| invalid_response(ruby, e))?;
     Ok(ctx.responder.send_response(response))
 }
 
+/// Body bytes for hyper: large bodies are pinned in place (zero-copy),
+/// everything else is copied out of the Ruby string, which may be
+/// mutated or collected the moment we return.
+fn body_bytes(ctx: &RequestCtx, body: RString) -> Bytes {
+    if let Some(bytes) = crate::pin::pinned_bytes(&ctx.pin_slab, body) {
+        return bytes;
+    }
+    Bytes::copy_from_slice(unsafe { body.as_slice() })
+}
+
 impl Request {
     /// Next chunk of the request body, at most `max_len` bytes; nil at EOF.
     /// Blocks (GVL released) until the client sends more.
@@ -256,7 +269,7 @@ impl Request {
                         Err(flume::RecvTimeoutError::Timeout) => None,
                         Err(flume::RecvTimeoutError::Disconnected) => Some(None),
                     }
-                });
+                })?;
                 match outcome {
                     Some(Some(bytes)) => bytes,
                     Some(None) => {
@@ -306,7 +319,7 @@ impl Request {
                 "Kino: response stream not started or already finished",
             ));
         };
-        let bytes = Bytes::copy_from_slice(unsafe { chunk.as_slice() });
+        let bytes = body_bytes(&ctx, chunk);
         let mut pending = Some(Ok(BodyFrame::data(bytes)));
 
         let outcome = block_on(&ctx.slot, || {
@@ -319,7 +332,7 @@ impl Request {
                 }
                 Err(flume::SendTimeoutError::Disconnected(_)) => Some(false),
             }
-        });
+        })?;
         match outcome {
             // Receiver dropped = client went away; the app keeps writing
             // into the void harmlessly (Rack has no error contract here).
@@ -410,6 +423,7 @@ pub fn test_ctx() -> crate::registry::BoxedCtx {
         body_timeout: Arc::new(std::sync::atomic::AtomicBool::new(false)),
         leftover: None,
         slot: None,
+        pin_slab: Arc::new(crate::pin::PinSlab::new()),
         responder: Arc::new(Responder::new(head_tx)),
     })
 }

data/ext/kino/src/server.rs

@@ -112,6 +112,7 @@ pub fn server_start(ruby: &Ruby, config: magnus::RHash) -> Result<(u64, u16), Er
         access_log: log_requests.then(|| crate::logsink::Sink::new(std::io::stdout())),
         lanes,
         lane_cursor: std::sync::atomic::AtomicUsize::new(0),
+        pin_slab: Arc::new(crate::pin::PinSlab::new()),
     });
 
     let tokio_listener = {
@@ -350,6 +351,7 @@ async fn handle_request(
         body_timeout,
         leftover: None,
         slot: None,
+        pin_slab: server.pin_slab.clone(),
         responder,
     });
 
@@ -589,6 +591,16 @@ pub fn shutdown_runtime(_ruby: &Ruby, server_id: u64, timeout_ms: u64) -> Result
     Ok(())
 }
 
+/// The GC anchor for this server's zero-copy pins: the Ruby Server holds
+/// it for its lifetime, so pinned buffers survive worker-ractor crashes.
+pub fn pin_keeper(
+    ruby: &Ruby,
+    server_id: u64,
+) -> Result<magnus::typed_data::Obj<crate::pin::PinKeeper>, Error> {
+    let server = registry::get(ruby, server_id)?;
+    Ok(ruby.obj_wrap(crate::pin::PinKeeper(server.pin_slab.clone())))
+}
+
 /// Errors print in red on color terminals. Covers worker errors,
 /// supervisor crash reports, and everything apps write to rack.errors.
 pub fn log_error(message: String) {

data/ext/kino/src/test_support.rs

@@ -71,10 +71,22 @@ pub fn take(ruby: &magnus::Ruby, id: u64) -> Result<Option<String>, magnus::Erro
             Err(flume::RecvTimeoutError::Timeout) => None,
             Err(flume::RecvTimeoutError::Disconnected) => Some(None),
         }
-    });
+    })?;
     Ok(taken.flatten())
 }
 
+/// Panic inside a GVL-released block: proves it surfaces as a Ruby
+/// exception instead of unwinding into the VM and killing the process.
+/// The default panic hook is silenced around the intentional panic so
+/// spec output stays clean.
+pub fn panic_in_release() -> Result<(), magnus::Error> {
+    let hook = std::panic::take_hook();
+    std::panic::set_hook(Box::new(|_| {}));
+    let result = gvl::without_gvl(|| panic!("intentional test panic"), None);
+    std::panic::set_hook(hook);
+    result
+}
+
 pub fn close(ruby: &magnus::Ruby, id: u64) -> Result<(), magnus::Error> {
     let chan = lookup(ruby, id)?;
     chan.tx.lock().take();