kino 0.1.1 → 0.1.3

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};
@@ -25,6 +26,12 @@ pub struct RequestCtx {
     /// Request body, streamed from hyper through a bounded channel: hyper is
     /// only polled as Ruby consumes, so inbound backpressure is free.
     pub body_rx: flume::Receiver<Bytes>,
+    /// Set by the body forwarder when the body exceeded max_body_size: turns
+    /// the next read into an error instead of a (truncated) clean EOF.
+    pub body_overflow: Arc<std::sync::atomic::AtomicBool>,
+    /// Set by the body forwarder when the client stalled past the idle
+    /// deadline: the next read raises so the worker reclaims its slot.
+    pub body_timeout: Arc<std::sync::atomic::AtomicBool>,
     /// When a frame is bigger than read_body's max_len, the rest waits here.
     pub leftover: Option<Bytes>,
     /// The owning worker slot (set at admit time, queue.rs); its interrupt
@@ -62,6 +69,20 @@ fn interrupted_error(ruby: &Ruby) -> Error {
     )
 }
 
+fn body_too_large_error(ruby: &Ruby) -> Error {
+    Error::new(
+        ruby.exception_runtime_error(),
+        "Kino: request body exceeded max_body_size",
+    )
+}
+
+fn body_timeout_error(ruby: &Ruby) -> Error {
+    Error::new(
+        ruby.exception_runtime_error(),
+        "Kino: request body read timed out",
+    )
+}
+
 fn invalid_response(ruby: &Ruby, e: impl std::fmt::Display) -> Error {
     Error::new(
         ruby.exception_runtime_error(),
@@ -238,7 +259,17 @@ impl Request {
                 });
                 match outcome {
                     Some(Some(bytes)) => bytes,
-                    Some(None) => return Ok(None), // EOF
+                    Some(None) => {
+                        // Disconnected: a clean EOF, unless the forwarder
+                        // abandoned the body (too large, or the client stalled).
+                        if ctx.body_overflow.load(std::sync::atomic::Ordering::Relaxed) {
+                            return Err(body_too_large_error(ruby));
+                        }
+                        if ctx.body_timeout.load(std::sync::atomic::Ordering::Relaxed) {
+                            return Err(body_timeout_error(ruby));
+                        }
+                        return Ok(None); // EOF
+                    }
                     None => return Err(interrupted_error(ruby)),
                 }
             }
@@ -318,7 +349,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()
@@ -328,16 +360,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() {
@@ -363,6 +406,8 @@ pub fn test_ctx() -> crate::registry::BoxedCtx {
         local_addr: "127.0.0.1:9292".parse().expect("static addr"),
         https: false,
         body_rx,
+        body_overflow: Arc::new(std::sync::atomic::AtomicBool::new(false)),
+        body_timeout: Arc::new(std::sync::atomic::AtomicBool::new(false)),
         leftover: None,
         slot: None,
         responder: Arc::new(Responder::new(head_tx)),

data/ext/kino/src/server.rs

@@ -51,6 +51,8 @@ pub fn server_start(ruby: &Ruby, config: magnus::RHash) -> Result<(u64, u16), Er
     let queue_depth: usize = cfg(ruby, config, "queue_depth")?;
     let queue_timeout_ms: u64 = cfg(ruby, config, "queue_timeout_ms")?;
     let request_timeout_ms: u64 = cfg_opt::<u64>(ruby, config, "request_timeout_ms")?.unwrap_or(0);
+    let max_body_size: usize = cfg_opt::<usize>(ruby, config, "max_body_size")?.unwrap_or(0);
+    let max_connections: usize = cfg_opt::<usize>(ruby, config, "max_connections")?.unwrap_or(1024);
     let tokio_threads: usize = cfg_opt::<usize>(ruby, config, "tokio_threads")?.unwrap_or(0);
     let tls_cert: Option<String> = cfg_opt(ruby, config, "tls_cert")?;
     let tls_key: Option<String> = cfg_opt(ruby, config, "tls_key")?;
@@ -104,6 +106,7 @@ pub fn server_start(ruby: &Ruby, config: magnus::RHash) -> Result<(u64, u16), Er
         rejected: std::sync::atomic::AtomicU64::new(0),
         queue_timeout_ms,
         request_timeout_ms,
+        max_body_size,
         timeouts: std::sync::atomic::AtomicU64::new(0),
         https: acceptor.is_some(),
         access_log: log_requests.then(|| crate::logsink::Sink::new(std::io::stdout())),
@@ -120,6 +123,7 @@ pub fn server_start(ruby: &Ruby, config: magnus::RHash) -> Result<(u64, u16), Er
         tokio_listener,
         acceptor,
         server.clone(),
+        max_connections,
         shutdown_rx,
     ));
     *server.runtime.lock() = Some(runtime);
@@ -129,40 +133,73 @@ pub fn server_start(ruby: &Ruby, config: magnus::RHash) -> Result<(u64, u16), Er
     Ok((id, local_port))
 }
 
+/// Slowloris guard for TLS: a client that completes the TCP connect but then
+/// stalls the handshake would otherwise hold a connection slot indefinitely
+/// (the per-request and header-read deadlines only start once hyper is
+/// serving, i.e. after the handshake). A handshake is a few round trips, so
+/// this is generous even for a high-latency client. Fixed, like the header
+/// timeout: not a knob.
+const TLS_HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(10);
+
 async fn accept_loop(
     listener: tokio::net::TcpListener,
     acceptor: Option<tokio_rustls::TlsAcceptor>,
     server: Arc<ServerInner>,
+    max_connections: usize,
     mut shutdown_rx: tokio::sync::watch::Receiver<bool>,
 ) {
+    // Bound concurrent connections: unbounded, a flood spawns a task and holds
+    // a socket per connection until file descriptors or memory run out. One
+    // permit per live connection; acquiring BEFORE accept leaves the excess in
+    // the kernel backlog (backpressure) rather than accepting then dropping.
+    let conn_limit = Arc::new(tokio::sync::Semaphore::new(max_connections));
     loop {
-        tokio::select! {
+        let permit = tokio::select! {
             _ = shutdown_rx.changed() => break,
-            accepted = listener.accept() => {
-                let Ok((stream, remote_addr)) = accepted else { continue };
-                // Small responses must not wait on Nagle + delayed ACK.
-                let _ = stream.set_nodelay(true);
-                let local_addr = stream
-                    .local_addr()
-                    .unwrap_or_else(|_| SocketAddr::from(([0, 0, 0, 0], 0)));
-                let server = server.clone();
-                let acceptor = acceptor.clone();
-                tokio::spawn(async move {
-                    match acceptor {
-                        Some(acceptor) => {
-                            // Handshake failures (port scans, plain HTTP to a
-                            // TLS port) just drop the connection.
-                            let Ok(tls) = acceptor.accept(stream).await else { return };
-                            serve_connection(tls, server, remote_addr, local_addr).await;
-                        }
-                        None => serve_connection(stream, server, remote_addr, local_addr).await,
-                    }
-                });
+            permit = conn_limit.clone().acquire_owned() => match permit {
+                Ok(permit) => permit,
+                Err(_) => break, // semaphore closed
+            },
+        };
+        let (stream, remote_addr) = tokio::select! {
+            _ = shutdown_rx.changed() => break,
+            accepted = listener.accept() => match accepted {
+                Ok(pair) => pair,
+                Err(_) => continue, // transient accept error; permit drops, retry
+            },
+        };
+        // Small responses must not wait on Nagle + delayed ACK.
+        let _ = stream.set_nodelay(true);
+        let local_addr = stream
+            .local_addr()
+            .unwrap_or_else(|_| SocketAddr::from(([0, 0, 0, 0], 0)));
+        let server = server.clone();
+        let acceptor = acceptor.clone();
+        tokio::spawn(async move {
+            // Held for the connection's lifetime; dropping it frees a slot.
+            let _permit = permit;
+            match acceptor {
+                Some(acceptor) => {
+                    // Handshake failures (port scans, plain HTTP to a TLS
+                    // port) and stalled handshakes (slowloris) just drop the
+                    // connection; the timeout bounds the latter.
+                    let handshake = tokio::time::timeout(TLS_HANDSHAKE_TIMEOUT, acceptor.accept(stream));
+                    let Ok(Ok(tls)) = handshake.await else { return };
+                    serve_connection(tls, server, remote_addr, local_addr).await;
+                }
+                None => serve_connection(stream, server, remote_addr, local_addr).await,
             }
-        }
+        });
     }
 }
 
+/// Slowloris guard: drop a connection that has not sent its complete request
+/// headers within this window. Long enough never to trip a real client (even
+/// on a slow mobile link), short enough to reap a stalled one. Deliberately a
+/// constant, not a config knob: fine-tuning intake limits is the fronting
+/// proxy's job; the actual hazard was having no default at all.
+const HEADER_READ_TIMEOUT: Duration = Duration::from_secs(15);
+
 async fn serve_connection<I>(
     io: I,
     server: Arc<ServerInner>,
@@ -176,7 +213,13 @@ async fn serve_connection<I>(
     // No auto Date header: it costs a clock read per response (together
     // with timer reads, ~7% of tokio-side cycles in the profile); it's a
     // SHOULD not a MUST, and apps that need it can set it themselves.
+    //
+    // The timer is installed so header_read_timeout actually fires: hyper's
+    // slow-header guard is inert without one. It arms only while the request
+    // head is being read, so it adds no per-response cost on the hot path.
     let _ = hyper::server::conn::http1::Builder::new()
+        .timer(hyper_util::rt::TokioTimer::new())
+        .header_read_timeout(HEADER_READ_TIMEOUT)
         .auto_date_header(false)
         .serve_connection(TokioIo::new(io), service)
         .await;
@@ -198,6 +241,25 @@ fn branded(mut response: HyperResponse) -> HyperResponse {
     response
 }
 
+/// A single valid Content-Length as a byte count. hyper has already rejected
+/// conflicting/duplicate values, so the first is authoritative; anything
+/// unparseable yields None and the streaming cap still applies.
+fn content_length(headers: &http::HeaderMap) -> Option<u64> {
+    headers
+        .get(http::header::CONTENT_LENGTH)?
+        .to_str()
+        .ok()?
+        .trim()
+        .parse()
+        .ok()
+}
+
+/// Idle deadline between request-body frames. A client that stalls mid-body
+/// would otherwise hold a worker slot indefinitely (the worker blocks in
+/// read_body). Generous: a real upload sends steadily and resets this each
+/// frame, so only a silent client trips it. Fixed, like the header timeout.
+const BODY_READ_TIMEOUT: Duration = Duration::from_secs(30);
+
 async fn handle_request(
     server: Arc<ServerInner>,
     remote_addr: SocketAddr,
@@ -221,19 +283,50 @@ async fn handle_request(
         )
     });
 
+    // Body-size guard: an honestly-declared oversize body is refused with a
+    // 413 below, before any worker runs. Chunked or lying clients are caught
+    // by the forwarder, which caps cumulative bytes and flags an overflow so
+    // read_body raises instead of letting the app buffer without bound.
+    let max_body = server.max_body_size;
+    let oversize =
+        max_body > 0 && content_length(&parts.headers).is_some_and(|len| len > max_body as u64);
+
     // Stream the request body through a bounded channel: hyper is polled
     // only as fast as the Ruby side consumes (inbound backpressure), and the
     // forwarder dropping the sender is EOF. Bodyless requests (most GETs)
     // skip the forwarder task entirely: dropping the sender IS the EOF.
     let (body_tx, body_rx) = flume::bounded::<bytes::Bytes>(8);
-    if hyper::body::Body::is_end_stream(&body) {
+    let body_overflow = Arc::new(std::sync::atomic::AtomicBool::new(false));
+    let body_timeout = Arc::new(std::sync::atomic::AtomicBool::new(false));
+    if oversize || hyper::body::Body::is_end_stream(&body) {
         drop(body_tx);
     } else {
+        let overflow = body_overflow.clone();
+        let timed_out = body_timeout.clone();
         tokio::spawn(async move {
             let mut body = body;
-            while let Some(frame) = body.frame().await {
-                let Ok(frame) = frame else { break };
+            let mut total: u64 = 0;
+            loop {
+                // Idle deadline between frames: a client that stalls mid-body
+                // would otherwise pin a worker blocked in read_body. Only the
+                // client's silence trips this; a slow APP blocks the forwarder
+                // in send_async below instead, which is not timed.
+                let frame = match tokio::time::timeout(BODY_READ_TIMEOUT, body.frame()).await {
+                    Ok(Some(Ok(frame))) => frame,
+                    Ok(Some(Err(_))) | Ok(None) => break, // body error or clean EOF
+                    Err(_) => {
+                        timed_out.store(true, Ordering::Relaxed);
+                        break;
+                    }
+                };
                 if let Ok(data) = frame.into_data() {
+                    total += data.len() as u64;
+                    if max_body > 0 && total > max_body as u64 {
+                        // Past the cap: flag it and stop pulling. Dropping the
+                        // sender unblocks read_body, which then raises.
+                        overflow.store(true, Ordering::Relaxed);
+                        break;
+                    }
                     if body_tx.send_async(data).await.is_err() {
                         break; // request handle dropped; stop pulling
                     }
@@ -253,6 +346,8 @@ async fn handle_request(
         local_addr,
         https: server.https,
         body_rx,
+        body_overflow,
+        body_timeout,
         leftover: None,
         slot: None,
         responder,
@@ -273,6 +368,9 @@ async fn handle_request(
 
     // Single exit point so the access log sees every outcome, 503s included.
     let response: HyperResponse = 'resp: {
+        if oversize {
+            break 'resp plain_response(413, "Payload Too Large\n");
+        }
         if server.lanes {
             if !dispatch_to_lane(&server, ctx).await {
                 break 'resp unavailable(&server);

data/lib/kino/configuration.rb

@@ -17,9 +17,12 @@ module Kino
       queue_depth: 1024,
       queue_timeout: 5.0,
       request_timeout: nil,
+      max_connections: nil, # nil = derive from the open-file limit
+      max_body_size: 50 * 1024 * 1024, # 50 MB; nil/0 = unlimited
       batch: 1,
       lanes: false,
       log_requests: false,
+      on_error: nil,
       shutdown_timeout: 30,
       tokio_threads: nil,
       tls: nil,
@@ -160,6 +163,14 @@ module Kino
       # Seconds the app gets before the client receives a 504; nil = off.
       def request_timeout(seconds) = @config.set(:request_timeout, seconds && Float(seconds))
 
+      # Max connections served at once; beyond it, new connections wait in
+      # the kernel backlog. Defaults to most of the open-file limit.
+      def max_connections(count) = @config.set(:max_connections, Integer(count))
+
+      # Max request-body bytes before a 413; nil disables (delegate to a
+      # fronting proxy). Default 50 MB.
+      def max_body_size(bytes) = @config.set(:max_body_size, bytes && Integer(bytes))
+
       # Requests a worker may grab per queue visit (default 1).
       def batch(count) = @config.set(:batch, Integer(count))
 
@@ -169,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`
@@ -50,6 +51,8 @@ module Kino
       @queue_depth = Integer(settings[:queue_depth])
       @queue_timeout_ms = (Float(settings[:queue_timeout]) * 1000).round
       @request_timeout_ms = settings[:request_timeout] ? (Float(settings[:request_timeout]) * 1000).round : 0
+      @max_connections = settings[:max_connections] ? Integer(settings[:max_connections]) : default_max_connections
+      @max_body_size = Integer(settings[:max_body_size] || 0)
       @batch = [Integer(settings[:batch]), 1].max
       @lanes = !!settings[:lanes]
       @log_requests = !!settings[:log_requests]
@@ -74,17 +77,20 @@ module Kino
         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
       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
@@ -210,10 +216,31 @@ 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
 
+    # Default connection cap: most of the process open-file limit. A
+    # connection flood's failure mode is descriptor exhaustion, and in
+    # :ractor/:threaded mode the app's own sockets and files share this
+    # process's table, so leave headroom. Scales with `ulimit -n`; raise the
+    # OS limit (or set max_connections) to allow more.
+    def default_max_connections
+      soft, = Process.getrlimit(Process::RLIMIT_NOFILE)
+      return 65_536 if soft == Process::RLIM_INFINITY
+
+      [soft * 8 / 10, 64].max
+    end
+
     def join_workers(deadline)
       if @supervisor
         @supervisor.shutdown([deadline - monotonic_now, 0].max)
@@ -259,13 +286,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

@@ -55,6 +55,17 @@
 # above your slowest legitimate endpoint.
 # request_timeout 30
 
+# Most connections to serve at once. Past this, new connections wait in
+# the kernel backlog instead of piling up until the server runs out of
+# file descriptors. Defaults to most of the open-file limit (ulimit -n),
+# so it scales with the OS limit and only bites under a flood.
+# max_connections 8192
+
+# Reject request bodies larger than this many bytes with a 413, so an
+# oversized or endless upload can't drive your app to run out of memory.
+# Set to nil to disable and let a fronting proxy handle it. Default: 50 MB.
+# max_body_size 50 * 1024 * 1024
+
 # How many requests a worker grabs from the line at once. Leave at 1
 # unless all your endpoints are uniformly fast.
 # batch 1
@@ -68,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.1"
+  VERSION = "0.1.3"
 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

@@ -92,9 +92,12 @@ module Kino
       def queue_depth: (int depth) -> untyped
       def queue_timeout: (Numeric seconds) -> untyped
       def request_timeout: (Numeric? seconds) -> untyped
+      def max_connections: (int count) -> untyped
+      def max_body_size: (int? bytes) -> untyped
       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