kino 0.1.2-x86_64-linux → 0.1.3-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70ea3dc39cb1ed5a61650ab42a83e3a2ebae3d7b2079abcbc20530240750c687
-  data.tar.gz: 8efcd33a04f46a3d74b1ac1a6ffacf0ed82e33ed84602de2e34673cbd2a5c7dc
+  metadata.gz: 0e89009156b5b57396e3a81ecff7d919b4e206be58e4f628b7160709195f673c
+  data.tar.gz: 50eefb990a1caae2c7ff60b7ed37666d000e876755cc0e13e0296ca5073c7b6b
 SHA512:
-  metadata.gz: de5ad9a1d564811ce1377507422354eb1b0c82df35a28843506fbada9bb0cbc914bcacf428eacdbf0f66fa904f3663c1e71396866374576f4906fcdb7c1f2552
-  data.tar.gz: ae6ce1fb6b2dff351420aa2e2973813bb3cc73dd6af6df5859db7127b0accb4c276f583ea001564b528ebc8a68d13a26fb2675aeb9aeb946d2bc8882486a702b
+  metadata.gz: 87b66b367bd7571fdc1aff11c20ee74133aa369b54162e3319940ce153643f3ff6dea53d9954d96375d7bb0030772f92c337e615bb12121d3753b5f66f76bcb2
+  data.tar.gz: f3a17b0eb0fa91fb68fd521d7b37ef0bc5939004ecbf3a6c5486f971d82c0cefbea9162ae7b542302dcae372340869a4322fe184b987b970e4ec5ac9314334ab

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [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 +106,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/README.md

@@ -14,7 +14,7 @@ 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

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`
@@ -84,11 +85,12 @@ module Kino
       )
       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
@@ -214,6 +216,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
@@ -275,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

@@ -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.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

@@ -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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kino
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: x86_64-linux
 authors:
 - Yaroslav Markin
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-06-21 00:00:00.000000000 Z
+date: 2026-07-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger