kino 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bd8e6e3b295832fa1d87743b4c9a121cdb5687287011b29f1140814fdae0575
-  data.tar.gz: f21305459e857d366159ee258d873e2109b7a7715bb0cbe8d23c47e458ae2b33
+  metadata.gz: f66c88f09e6d65c5b9ca4b0ed4f1a10f735343286dfed32fbd54d13216faf886
+  data.tar.gz: 871d3eeaed7cf34ed8fc83a53fba42d5dfe28b916e9b6c695b332fcf17be5ab8
 SHA512:
-  metadata.gz: 04e95f9ee2133b4d15bdd2069977e73791a16b033e57a3bdb88478d0048b0bb5d8f56eff1963813bbf8d9399461bb80bf9c33a2039f98805e4f129b3e42b28ef
-  data.tar.gz: 8eb131cdbbe5bdbd29d188ab4ff43dbbec2f8c791aacf85586ba69c7208b2f74cc05d4007c469a4de61c4578ef08214e56a4fd080b9ad655af3a01d208b4c752
+  metadata.gz: 22b189c9301618dfe411965cfea6f91cd7511b79265f5826e7e158110752104ec3c8c9da55c0e1dcfa4ad4f883bcca5e392505661244c030e3fac000de06fc18
+  data.tar.gz: 3ef719d98e7fcc5b5570d9dc606f24c51df1651abc4814007e48cdfa46eaf43e49cbc9680b08e344002670a51e2f9d0d29ee6f3ace2327f27cdbe4c15fc6fe6c

data/CHANGELOG.md

@@ -1,3 +1,34 @@
+## [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)
+  are now serialized with `to_s`, matching Puma, instead of failing the
+  request with a `TypeError`. (Fixes [#3], reported by Max Erkin @rus-max)
+- New `on_error` directive: a callable invoked with `(exception, env)` when
+  a worker catches an app or delivery error, after the client got its 500.
+  Delivery errors (unserializable header, a body that raised mid-stream)
+  happen after the middleware stack returned, so this hook is the only
+  place an error tracker can see them. Handler failures are logged and
+  swallowed; in :ractor mode the handler must be Ractor-shareable. (Fixes [#3], reported by Max Erkin @rus-max)
+- Worker error log lines now include the exception backtrace (first 12
+  frames), not just the exception class and message.
+- A streaming body that raises mid-stream now aborts the connection
+  instead of finishing the chunked response cleanly, so a client can no
+  longer mistake a truncated response for a complete one.
+
 ## [0.1.2] - 2026-06-22
 
 - Drop a connection that has not sent its complete request headers
@@ -89,3 +120,5 @@ Initial release.
 - Request timeouts: `request_timeout: seconds` (off by default) returns an
   immediate 504 when the app misses the deadline; the late response is
   dropped and the handler is never killed. Counted as `stats[:timeouts]`.
+
+[#3]: https://github.com/yaroslav/kino/issues/3

data/Cargo.lock

@@ -332,7 +332,7 @@ dependencies = [
 
 [[package]]
 name = "kino"
-version = "0.1.2"
+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

@@ -14,13 +14,15 @@ and a threaded fallback mode runs everything else, Rails included.
 * **Fast.** On a real 8-core server, every Kino mode is **1.5-2×**
   ahead of a Puma fork cluster on I/O-light endpoints. Ractor mode also
   wins on pure CPU, **30%+**. [Benchmarks](#benchmarks) below.
-* **A fraction of the memory.** Aabout **~7×** on the simplistic bench 
+* **A fraction of the memory.** About **~7×** on the simplistic bench 
   Ractor app, and about **4× less memory** than a Puma cluster serving Rails in fallback threaded mode.
 * **Parallel without forking.** Ractor mode runs CPU work **more than
   5× faster** than Kino's own GVL-bound threaded mode, in the same
   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.2"
+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

@@ -9,7 +9,8 @@ use std::sync::Arc;
 
 use bytes::Bytes;
 use magnus::r_hash::ForEach;
-use magnus::{Error, RArray, RHash, RString, Ruby, TryConvert, Value};
+use magnus::value::ReprValue;
+use magnus::{Error, RArray, RHash, RString, Ruby, Value};
 
 use crate::gvl;
 use crate::response::{full_body, BodyFrame, Responder};
@@ -36,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>,
 }
 
@@ -51,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)
 }
@@ -227,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.
@@ -255,7 +269,7 @@ impl Request {
                         Err(flume::RecvTimeoutError::Timeout) => None,
                         Err(flume::RecvTimeoutError::Disconnected) => Some(None),
                     }
-                });
+                })?;
                 match outcome {
                     Some(Some(bytes)) => bytes,
                     Some(None) => {
@@ -305,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, || {
@@ -318,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).
@@ -348,7 +362,8 @@ impl Request {
 /// copies the bytes immediately.
 fn build_head(status: u16, headers: RHash) -> Result<hyper::http::response::Builder, Error> {
     let mut builder = Some(hyper::Response::builder().status(status));
-    headers.foreach(|name: RString, value: Value| {
+    headers.foreach(|name: Value, value: Value| {
+        let name = coerce_str(name)?;
         let take = |b: &mut Option<hyper::http::response::Builder>, v: RString| {
             let next = b
                 .take()
@@ -358,16 +373,27 @@ fn build_head(status: u16, headers: RHash) -> Result<hyper::http::response::Buil
         };
         if let Some(values) = RArray::from_value(value) {
             for i in 0..values.len() {
-                take(&mut builder, values.entry::<RString>(i as isize)?);
+                take(&mut builder, coerce_str(values.entry(i as isize)?)?);
             }
         } else {
-            take(&mut builder, RString::try_convert(value)?);
+            take(&mut builder, coerce_str(value)?);
         }
         Ok(ForEach::Continue)
     })?;
     Ok(builder.expect("builder always present"))
 }
 
+/// Rack SPEC says header names and values are Strings, but real apps set
+/// booleans, numbers, and symbols, and Puma serves them via to_s. Match
+/// that: Strings pass through untouched (the hot path), anything else pays
+/// one to_s call back into Ruby.
+fn coerce_str(value: Value) -> Result<RString, Error> {
+    match RString::from_value(value) {
+        Some(s) => Ok(s),
+        None => value.funcall("to_s", ()),
+    }
+}
+
 fn split_host_port(host: &str, default_port: u16) -> (String, u16) {
     match host.rsplit_once(':') {
         Some((name, port)) if !name.is_empty() => match port.parse() {
@@ -397,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/configuration.rb

@@ -22,6 +22,7 @@ module Kino
       batch: 1,
       lanes: false,
       log_requests: false,
+      on_error: nil,
       shutdown_timeout: 30,
       tokio_threads: nil,
       tls: nil,
@@ -179,6 +180,11 @@ module Kino
       # Native access log: one status-colored line per request to stdout.
       def log_requests(enabled) = @config.set(:log_requests, !!enabled)
 
+      # Called with (exception, env) when a worker catches an app or
+      # delivery error; wire your error tracker here. Takes a callable
+      # or a block. Must be Ractor-shareable in :ractor mode.
+      def on_error(handler = nil, &block) = @config.set(:on_error, handler || block)
+
       # Graceful-shutdown drain deadline in seconds.
       def shutdown_timeout(seconds) = @config.set(:shutdown_timeout, seconds)
 

data/lib/kino/ractor_supervisor.rb

@@ -9,12 +9,13 @@ module Kino
   class RactorSupervisor
     attr_reader :respawns
 
-    def initialize(server_id, app, workers:, threads:, batch: 1)
+    def initialize(server_id, app, workers:, threads:, batch: 1, on_error: nil)
       @server_id = server_id
       @app = app
       @workers = workers
       @threads = threads
       @batch = batch
+      @on_error = on_error
       @respawns = 0
       @draining = false
       @lock = Mutex.new
@@ -83,13 +84,13 @@ module Kino
     # old slot.
     def spawn_worker
       worker_ids = Array.new(@threads) { Native.register_worker(@server_id) }
-      ractor = Ractor.new(@server_id, worker_ids, @app, @batch) do |server_id, ids, app, batch|
+      ractor = Ractor.new(@server_id, worker_ids, @app, @batch, @on_error) do |server_id, ids, app, batch, on_error|
         ids.map do |id|
           Thread.new do
             # Crashes surface via Ractor#value in the supervisor; don't also
             # spray the backtrace to stderr from inside the dying ractor.
             Thread.current.report_on_exception = false
-            Kino::Worker.run(server_id, id, app, batch)
+            Kino::Worker.run(server_id, id, app, batch, on_error)
           end
         end.each(&:join)
       end

data/lib/kino/server.rb

@@ -41,6 +41,7 @@ module Kino
       @bind = settings[:bind]
       @requested_port = settings[:port]
       @workers = Integer(settings[:workers])
+      @on_error = validate_on_error(settings[:on_error])
       @mode = resolve_mode(settings[:mode])
       # Default threads per mode: 1 in :ractor (threads inside a ractor
       # share its lock; a measured +17% on fast handlers; raise `workers`
@@ -72,23 +73,35 @@ 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).start
+        @supervisor = RactorSupervisor.new(@id, @app, workers: @workers, threads: @threads,
+          batch: @batch, on_error: @on_error).start
       else
         @worker_threads = (@workers * @threads).times.map do
           worker_id = Native.register_worker(@id)
-          Thread.new { Worker.run(@id, worker_id, @app, @batch) }
+          Thread.new { Worker.run(@id, worker_id, @app, @batch, @on_error) }
         end
       end
       @started = true
@@ -131,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
 
@@ -214,6 +230,15 @@ module Kino
       {cert: String(tls[:cert]), key: String(tls[:key])}
     end
 
+    def validate_on_error(handler)
+      return nil if handler.nil?
+      unless handler.respond_to?(:call)
+        raise ArgumentError, "on_error must respond to #call (got #{handler.class})"
+      end
+
+      handler
+    end
+
     def monotonic_now
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
@@ -230,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)
@@ -275,13 +361,21 @@ module Kino
             "Ractor.shareable_proc endpoints); try Ractor.make_shareable(app) " \
             "or mode: :threaded"
         end
+        unless @on_error.nil? || Ractor.shareable?(@on_error)
+          raise Error,
+            "mode: :ractor requires a Ractor-shareable on_error handler " \
+            "(build it with Ractor.shareable_proc, or use mode: :threaded)"
+        end
         :ractor
       when :auto
-        if Ractor.shareable?(@app)
-          :ractor
-        else
+        if !Ractor.shareable?(@app)
           warn "Kino: app is not Ractor-shareable; falling back to mode: :threaded"
           :threaded
+        elsif !(@on_error.nil? || Ractor.shareable?(@on_error))
+          warn "Kino: on_error handler is not Ractor-shareable; falling back to mode: :threaded"
+          :threaded
+        else
+          :ractor
         end
       else
         raise ArgumentError, "mode must be :auto, :ractor, or :threaded (got #{requested.inspect})"

data/lib/kino/templates/kino.rb.tt

@@ -79,6 +79,14 @@
 # never saw, such as 503s. Recommended in development.
 # log_requests false
 
+# Called when a worker catches an app or delivery error, after the client
+# got its 500. This is the only place that sees errors raised while the
+# response was being written (bad header, body that died mid-stream):
+# they happen after your middleware returned, so only the server can
+# report them. Wire your error tracker here. In :ractor mode the handler
+# must be Ractor-shareable (build it with Ractor.shareable_proc).
+# on_error ->(error, env) { ExceptionService.capture(error) }
+
 ## Lifecycle
 
 # On shutdown, give in-flight requests this many seconds to finish.

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.2"
+  VERSION = "0.2.0"
 end

data/lib/kino/worker.rb

@@ -18,13 +18,13 @@ module Kino
 
     module_function
 
-    def run(server_id, worker_id, app, batch_size = 1)
+    def run(server_id, worker_id, app, batch_size = 1, on_error = nil)
       if batch_size <= 1
         env = Native.take_one(server_id, worker_id)
-        env = handle_one(env, server_id, worker_id, app) while env
+        env = handle_one(env, server_id, worker_id, app, on_error) while env
       else
         batch = Native.take_batch(server_id, worker_id, batch_size)
-        batch = process(batch, server_id, worker_id, app, batch_size) while batch
+        batch = process(batch, server_id, worker_id, app, batch_size, on_error) while batch
       end
     end
 
@@ -34,8 +34,8 @@ module Kino
     NOT_FUSED = Object.new.freeze
 
     # Handle one request; returns the next env (fused take) or nil.
-    def handle_one(env, server_id, worker_id, app)
-      result = serve(env, app) do |request, status, headers, chunks|
+    def handle_one(env, server_id, worker_id, app, on_error)
+      result = serve(env, app, on_error) do |request, status, headers, chunks|
         request.respond_and_take_one(server_id, worker_id, status, headers, chunks)
       end
       result.equal?(NOT_FUSED) ? Native.take_one(server_id, worker_id) : result
@@ -43,10 +43,10 @@ module Kino
 
     # Handle every env in the batch; returns the next batch (the last
     # simple response rides the fused respond_and_take) or nil on shutdown.
-    def process(batch, server_id, worker_id, app, batch_size)
+    def process(batch, server_id, worker_id, app, batch_size, on_error)
       last = batch.size - 1
       batch.each_with_index do |env, index|
-        result = serve(env, app) do |request, status, headers, chunks|
+        result = serve(env, app, on_error) do |request, status, headers, chunks|
           if index == last
             request.respond_and_take(server_id, worker_id, batch_size,
               status, headers, chunks)
@@ -66,7 +66,7 @@ module Kino
     # here and return NOT_FUSED. App errors must never kill the worker;
     # hard crashes (Exception) are the supervisor's job; and `abort` does
     # the right thing whether or not the response head already went out.
-    def serve(env, app)
+    def serve(env, app, on_error)
       request = env[KINO_REQUEST]
       env[RACK_INPUT] ||= Input.new(request)
       status, headers, body = app.call(env)
@@ -80,11 +80,32 @@ module Kino
         NOT_FUSED
       end
     rescue => e
-      Native.log_error("#{e.class}: #{e.message}")
+      # Abort before the hook: the client's 500 must never wait on a
+      # reporting round-trip. The hook is the app's only window onto
+      # delivery errors (they happen after app.call returned, so no
+      # middleware can see them); its own failures are logged, not raised,
+      # because nothing may escape this block and kill the worker.
+      Native.log_error(error_log_line(e))
       request.abort
+      if on_error
+        begin
+          on_error.call(e, env)
+        rescue => hook_error
+          Native.log_error("on_error hook raised #{hook_error.class}: #{hook_error.message}")
+        end
+      end
       NOT_FUSED
     end
 
+    # First frames only: the raise site is at the top, and Rails stacks
+    # run hundreds of middleware frames deep. Hooks get the full exception.
+    BACKTRACE_FRAMES = 12
+
+    def error_log_line(error)
+      ["#{error.class}: #{error.message}",
+        *(error.backtrace || []).first(BACKTRACE_FRAMES)].join("\n  ")
+    end
+
     def deliver_streaming(request, status, headers, body, input)
       request.send_headers(status, headers)
       if body.respond_to?(:call) && !body.respond_to?(:each)
@@ -99,10 +120,13 @@ module Kino
         end
       else
         # Enumerable body: chunked transfer unless the app set content-length.
+        # finish only on success: a body that raised must abort the
+        # connection (serve's rescue), not fake a clean end of stream that
+        # the client cannot tell from a complete response.
         begin
           body.each { |chunk| request.write_chunk(chunk) }
-        ensure
           request.finish
+        ensure
           body.close if body.respond_to?(:close)
         end
       end
@@ -119,6 +143,6 @@ module Kino
     end
 
     private_class_method :handle_one, :process, :serve, :deliver_streaming,
-      :join_chunks
+      :join_chunks, :error_log_line
   end
 end

data/sig/kino.rbs

@@ -97,6 +97,7 @@ module Kino
       def batch: (int count) -> untyped
       def lanes: (boolish enabled) -> untyped
       def log_requests: (boolish enabled) -> untyped
+      def on_error: (?^(Exception, Hash[String, untyped]) -> void handler) ?{ (Exception, Hash[String, untyped]) -> void } -> untyped
       def shutdown_timeout: (Numeric seconds) -> untyped
       def tokio_threads: (int count) -> untyped
       def tls: (cert: String, key: String) -> untyped

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kino
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  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