kino 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 390e987542cf3e7fe2a605bdd9905181fa0a0630990433c53b465732650cf6fd
-  data.tar.gz: 128a9da74166473f5682baf461f4eccd3cf39c3f017786ab3bf6c45ed762ce64
+  metadata.gz: f66c88f09e6d65c5b9ca4b0ed4f1a10f735343286dfed32fbd54d13216faf886
+  data.tar.gz: 871d3eeaed7cf34ed8fc83a53fba42d5dfe28b916e9b6c695b332fcf17be5ab8
 SHA512:
-  metadata.gz: 4c7eb584af1dbdc98818a53738dea224952c2980cd2beda5a5ac83cfe695f6bedb82428adcdf29df53fcb3ae7cd995a274e5b6431bbeadc5e1a217073fba01a4
-  data.tar.gz: 896aa7e556f501f91e39cd7b9dccb7edcd53ca9ff20c7788b7a615480274eb13df2e28e9dbb584dd36712ac3672140e4d5a420bbfa1c64a8ecb552a01fcf026c
+  metadata.gz: 22b189c9301618dfe411965cfea6f91cd7511b79265f5826e7e158110752104ec3c8c9da55c0e1dcfa4ad4f883bcca5e392505661244c030e3fac000de06fc18
+  data.tar.gz: 3ef719d98e7fcc5b5570d9dc606f24c51df1651abc4814007e48cdfa46eaf43e49cbc9680b08e344002670a51e2f9d0d29ee6f3ace2327f27cdbe4c15fc6fe6c

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.2.0] - 2026-07-13
+
+- Strip debug info from release builds.
+- A panic in the native layer now raises a RuntimeError on the affected
+  worker (visible to `on_error` and the error log) instead of killing the
+  server process.
+- The pidfile is claimed exclusively: starting refuses (instead of silently
+  overwriting) while the pidfile's owner is alive, a leftover file from a
+  dead process is replaced, symlinks are never followed, and shutdown
+  removes the file only while it still holds our pid.
+- Zero-copy response bodies: bodies of 4 KB and up ride to the network
+  layer by reference instead of being copied at the FFI boundary, in both
+  dispatch modes. A 10 KB-body endpoint now serves at plaintext speed.
+
 ## [0.1.3] - 2026-07-04
 
 - Non-String response header names and values (booleans, numbers, symbols)

data/Cargo.lock

@@ -332,7 +332,7 @@ dependencies = [
 
 [[package]]
 name = "kino"
-version = "0.1.3"
+version = "0.2.0"
 dependencies = [
  "ahash",
  "bytes",

data/Cargo.toml

@@ -7,8 +7,12 @@ members = ["./ext/kino"]
 resolver = "2"
 
 [profile.release]
-# Keep debug symbols in release builds so the final binary stays debuggable.
-debug = true
+# Ship lean artifacts: no debug info, and leftover debug sections (e.g.
+# from the precompiled std) are stripped. The symbol table stays, so
+# crash backtraces keep function names. For a debuggable local build,
+# compile with RB_SYS_CARGO_PROFILE=dev.
+debug = false
+strip = "debuginfo"
 opt-level = 3
 lto = "fat"
 codegen-units = 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
@@ -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

data/ext/kino/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kino"
-version = "0.1.3"
+version = "0.2.0"
 edition = "2021"
 authors = ["Yaroslav Markin <yaroslav@markin.net>"]
 license = "MIT"

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();

data/ext/kino/src/timer.rs

@@ -50,7 +50,7 @@ pub fn sleep_chunk(ruby: &Ruby, seconds: f64) -> Result<f64, Error> {
             func: gvl::ubf_interrupt,
             data: &interrupted as *const _ as *mut c_void,
         }),
-    );
+    )?;
 
     let remaining = requested.saturating_sub(chunk);
     Ok(remaining.as_secs_f64())

data/lib/kino/server.rb

@@ -73,17 +73,28 @@ module Kino
     def start
       raise Error, "server already started" if @started
 
-      @id, @port = Native.server_start(
-        bind: @bind, port: @requested_port,
-        queue_depth: @queue_depth, queue_timeout_ms: @queue_timeout_ms,
-        request_timeout_ms: @request_timeout_ms,
-        max_connections: @max_connections,
-        max_body_size: @max_body_size,
-        tokio_threads: @tokio_threads,
-        tls_cert: @tls&.fetch(:cert), tls_key: @tls&.fetch(:key),
-        lanes: @lanes, log_requests: @log_requests
-      )
-      File.write(@pidfile, "#{Process.pid}\n") if @pidfile
+      # Claim the pidfile before binding: refusing to start (another
+      # instance is alive) must not leave a booted native runtime behind.
+      write_pidfile if @pidfile
+      booted = false
+      begin
+        @id, @port = Native.server_start(
+          bind: @bind, port: @requested_port,
+          queue_depth: @queue_depth, queue_timeout_ms: @queue_timeout_ms,
+          request_timeout_ms: @request_timeout_ms,
+          max_connections: @max_connections,
+          max_body_size: @max_body_size,
+          tokio_threads: @tokio_threads,
+          tls_cert: @tls&.fetch(:cert), tls_key: @tls&.fetch(:key),
+          lanes: @lanes, log_requests: @log_requests
+        )
+        booted = true
+      ensure
+        remove_pidfile if @pidfile && !booted
+      end
+      # GC anchor for zero-copy response buffers: held for the server's
+      # lifetime so in-flight buffers survive even a worker ractor crash.
+      @pin_keeper = Native.pin_keeper(@id)
       if @mode == :ractor
         @supervisor = RactorSupervisor.new(@id, @app, workers: @workers, threads: @threads,
           batch: @batch, on_error: @on_error).start
@@ -133,9 +144,12 @@ module Kino
       end
 
       Native.shutdown_runtime(@id, 1_000)
+      # The runtime is gone, so hyper has dropped every pinned buffer;
+      # the keeper (and the strings it marked) may now be collected.
+      @pin_keeper = nil
       @worker_threads.clear
       @started = false
-      File.delete(@pidfile) if @pidfile && File.exist?(@pidfile)
+      remove_pidfile if @pidfile
       nil
     end
 
@@ -241,6 +255,67 @@ module Kino
       [soft * 8 / 10, 64].max
     end
 
+    # Claim the pidfile for this process. O_EXCL creation fails on ANY
+    # existing directory entry (regular file, symlink, even a dangling
+    # one), so a live instance's pidfile is never overwritten and a
+    # symlink is never followed. A leftover entry whose owner is gone is
+    # replaced; one that does not hold a pid is refused, not clobbered.
+    def write_pidfile
+      claim_pidfile
+    rescue Errno::EEXIST
+      refuse_unless_stale
+      begin
+        # Unlink removes the entry itself; a symlink's target is untouched.
+        File.unlink(@pidfile)
+      rescue Errno::ENOENT
+        # Vanished on its own; the claim below settles any remaining race.
+      end
+      begin
+        claim_pidfile
+      rescue Errno::EEXIST
+        raise Error, "lost the race for #{@pidfile}: another instance is starting"
+      end
+    end
+
+    def claim_pidfile
+      File.open(@pidfile, File::WRONLY | File::CREAT | File::EXCL, 0o644) do |file|
+        file.write("#{Process.pid}\n")
+      end
+    end
+
+    # @raise [Kino::Error] when the pidfile's owner is still alive, or the
+    #   file does not look like a pidfile at all
+    def refuse_unless_stale
+      content = begin
+        File.read(@pidfile)
+      rescue Errno::ENOENT
+        return # already gone; nothing to refuse
+      end
+      pid = Integer(content.strip, exception: false)
+      unless pid&.positive?
+        raise Error, "refusing to overwrite #{@pidfile}: does not hold a pid"
+      end
+      raise Error, "already running (pid #{pid}, per #{@pidfile})" if process_alive?(pid)
+    end
+
+    def process_alive?(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    rescue Errno::EPERM
+      true # exists, just not ours to signal
+    end
+
+    # Delete only a pidfile that is still ours: by shutdown time the path
+    # may belong to a replacement instance, or an operator may have
+    # repointed it at something that is not a pidfile at all.
+    def remove_pidfile
+      File.unlink(@pidfile) if File.read(@pidfile) == "#{Process.pid}\n"
+    rescue Errno::ENOENT
+      nil
+    end
+
     def join_workers(deadline)
       if @supervisor
         @supervisor.shutdown([deadline - monotonic_now, 0].max)

data/lib/kino/version.rb

@@ -2,5 +2,5 @@
 
 module Kino
   # The gem version (single source of truth; ext/kino/Cargo.toml syncs).
-  VERSION = "0.1.3"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kino
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Yaroslav Markin
@@ -165,6 +165,7 @@ files:
 - ext/kino/src/gvl.rs
 - ext/kino/src/lib.rs
 - ext/kino/src/logsink.rs
+- ext/kino/src/pin.rs
 - ext/kino/src/queue.rs
 - ext/kino/src/registry.rs
 - ext/kino/src/request.rs