kino 0.1.2-x86_64-linux → 0.2.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70ea3dc39cb1ed5a61650ab42a83e3a2ebae3d7b2079abcbc20530240750c687
-  data.tar.gz: 8efcd33a04f46a3d74b1ac1a6ffacf0ed82e33ed84602de2e34673cbd2a5c7dc
+  metadata.gz: 48359f37b2ea3ddb9d6535c05d0f75845f6723dfcd92ff35bd15e1b91b7641ae
+  data.tar.gz: 2fd57f5d5fc2e6bad3522a85d76c1fcf17cf43a8be24472aee9847e5bed63440
 SHA512:
-  metadata.gz: de5ad9a1d564811ce1377507422354eb1b0c82df35a28843506fbada9bb0cbc914bcacf428eacdbf0f66fa904f3663c1e71396866374576f4906fcdb7c1f2552
-  data.tar.gz: ae6ce1fb6b2dff351420aa2e2973813bb3cc73dd6af6df5859db7127b0accb4c276f583ea001564b528ebc8a68d13a26fb2675aeb9aeb946d2bc8882486a702b
+  metadata.gz: 3ea2c278e8feb0969c532e54ebd9aa0f5ce5774baf6b954c633c6afbc7605eb2f5ca46b0f879c337aeb8d25f2d97810a55b873b252a74b4bd2c2f8eed3d7b703
+  data.tar.gz: 2aea614aa9da23c4afa0882316de1baf88beb64cd50ec7a1b43b28a92c5c9578caf5d5c5c22c38469efd5478562947faa2a591825b16d2a69b8021b7c724f05e

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