kino 0.2.1-aarch64-linux → 0.4.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d664928d6dfad3b60c6fdcbd27c2dffc008a9485a224bda3b7179f033c4c7cf5
-  data.tar.gz: d52e42477237ff7e65ea5f8752a63c6ac1d1f20cfa3f9189ad3a80a4d5e51f69
+  metadata.gz: 145273ae455b0822a24794c25d449376b3ba5122f3f275c00b4a959fdafd5183
+  data.tar.gz: c20ae1c2f111a4f6329ea25a4d9c9a0579dfa1b77765ff11e35572f8e32925ca
 SHA512:
-  metadata.gz: e0a0a7ac4cfc422143b11938423cd1b9022e4e065bf131548b485a95d1cd88042798f778b5b87f3fc6a51a12814cf564be8bce8d4ed61366e68c6133e775a3e1
-  data.tar.gz: 1d52a5e4715075b324cd9997e525be33c4edf69c4fe0547dcbf8633228783b3f7414699a88a70caeab2d7f1122d80283f4ab7c5cd7f45669bd67b3dae190a12c
+  metadata.gz: ed2ef3b3d79817b67da62e8271f0a420d4ee0c8976780d97e6e91ba15cddff2e1d34e830d41a8c4c8c63d65fecbeab32bec8d8568777b399c684cdfce00624f0
+  data.tar.gz: 6d695d16998c2bdb9fe44ac709a311990c53c88ae980f136757db926ba370e5a8e379fdd098f675beae4fb126a0ce7d663b36b0a602d6933b1c2b6d3f6cdc02b

data/CHANGELOG.md

@@ -1,3 +1,75 @@
+## [0.4.0] - 2026-08-22
+
+- Rack handler: `rails server -u kino` and `rackup -s kino` boot Kino
+  through `Rackup::Handler::Kino`, reading the same config file as the
+  `kino` CLI with the host's flags on top; `rackup -s kino --help` lists
+  the `-O` options (Workers, Threads, Mode, Config).
+- The config file is also looked up at `config/kino.rb` (the Rails
+  layout) when there is no `kino.rb`, by the CLI and the handler alike.
+- `Kino::Server#run` serves an already built server the way
+  `Kino::Server.run` does (banner, signal traps, block until shutdown),
+  and syncs stdout there so the banner is never held back by block
+  buffering under a pipe, whichever entry point booted the server.
+- `workers` now defaults to `Kino.available_parallelism`, the CPUs the
+  process may actually use: the affinity mask and, in a container, the
+  cgroup CPU quota (a pod limited to 2 CPUs on a 64-core node gets 2
+  workers, not 64). `Etc.nprocessors` only ever saw the mask.
+- `bind "unix:///path/to.sock"` listens on a unix domain socket, the
+  usual shape behind nginx: a stale socket file is reclaimed, a live one
+  is refused, and the file is removed on shutdown. `port` is unused on
+  it and TLS is rejected (terminate TLS at the proxy). Requests arriving
+  over the socket report `REMOTE_ADDR` 127.0.0.1.
+- `Kino::Server#url`, `#control_url`, and `#unix?` report where a started
+  server and its control plane listen.
+- The access log is two records per request: an arrival line queued
+  before the app runs (a hang shows as an arrow with no answer) and a
+  status-tinted completion line with a timing breakdown of `ruby`,
+  `kino`, and `wait`, the `ruby` part carrying the GC pause and objects
+  allocated where one request at a time can own the VM's counters
+  (`:threaded`, or `:ractor` with `workers 1`). Local timestamps with
+  their UTC offset; a blank line between requests. The former one-line
+  format is gone.
+- A failed request is reported as `500 GET /path · Class: message (site)`
+  followed by its backtrace relative to the working directory, the app's
+  own frames first, the rest folded into `… N more`.
+- Every line Kino logs about itself (draining, a crash and its respawn,
+  hook failures, quarantine, the USR1 stats line, `rack.errors`) reads
+  `kino[<pid>] <source>: message`, the source naming the worker that
+  spoke (`worker-3`, `worker-3/thread-2`) or `main`; worker ractors and
+  threads now carry those names. The label is dim, yellow, or red by
+  level on color terminals. `Kino::Log.info`, `.warn`, and `.error` are
+  public, for hooks.
+- The startup banner lists the Ruby build with its JIT and parser flags,
+  the environment, the topology, the pid, and the control-plane address
+  when one is bound.
+
+## [0.3.0] - 2026-08-13
+
+- Queue-time histogram: `/metrics` exposes `kino_request_queue_seconds`, a
+  histogram of how long each request waited for a free worker (the
+  saturation signal), and `server.stats`/`/stats` gain `queue_time`
+  (count and summed seconds). Measured internally with a monotonic clock,
+  so it needs no proxy header and is immune to clock skew.
+- Lifecycle hooks: `after_boot`, `after_worker_boot`,
+  `after_request_complete`, and `on_worker_exit` join `on_error`, so apps
+  can wire their own metrics, readiness, and error tracking. The
+  worker-context hooks must be Ractor-shareable in `:ractor` mode; a raising
+  hook is logged and never kills a worker.
+- Stuck-worker quarantine: past `quarantine_timeout`, a wedged dispatch
+  slot is quarantined and a replacement worker is spawned to restore
+  capacity (capped by `quarantine_max`), surfaced via `/stats`, `/metrics`,
+  and `server.stats`. The wedged worker is never force-killed.
+- Control plane: a read-only monitoring listener (`control_bind`,
+  optional `control_token`) serving live stats as JSON at `/stats`,
+  Prometheus metrics at `/metrics`, and `/ready`/`/live` probes, answered
+  from the native layer on a dedicated thread so it stays responsive
+  while workers are busy, stuck, or draining.
+- Per-worker stats: `/stats`, `/metrics`, and `server.stats` now break the
+  counters down per dispatch slot (served, in-flight, and `busy_ms`, the
+  age of the slot's current request), so a stuck slot is visible
+  individually.
+- Update Rust and Ruby dependencies.
+
 ## [0.2.1] - 2026-07-27
 
 - Update Rust dependencies for Kino.

data/README.md

@@ -196,6 +196,12 @@ bundle exec kino           # picks up config.ru + kino.rb, serves on :9292
 (After a standalone `gem install`, the `kino` command works without
 `bundle exec`.)
 
+Prefer your framework's own command? Kino ships a Rack handler, so
+`rails server -u kino` and `rackup -s kino` boot it too. They read the
+same `kino.rb` (or `config/kino.rb`), the host's `-p`/`-b` flags win over
+the file, and `rackup -s kino -O Workers=4 -O Mode=threaded` reaches the
+rest (`rackup -s kino --help` lists them).
+
 No Rust compiler needed: released versions ship precompiled native gems
 for Linux (x86_64/aarch64, glibc and musl) and macOS (arm64). On other
 platforms the gem compiles at install time; that needs a Rust toolchain,
@@ -218,9 +224,9 @@ Or embedded, with everything spelled out:
 
 ```ruby
 server = Kino::Server.new(app,
-  bind: "127.0.0.1",
+  bind: "127.0.0.1",          # or "unix:///run/kino.sock" behind a proxy
   port: 9292,                 # 0 = ephemeral; read back via server.port
-  workers: Etc.nprocessors,   # ractors (parallelism)
+  workers: Kino.available_parallelism, # ractors (parallelism); the default
   threads: 1,                 # per worker; ractor default 1, threaded default 3
   mode: :auto,                # :auto | :ractor | :threaded
   queue_depth: 1024,          # bounded queue; overflow → 503
@@ -230,6 +236,8 @@ server = Kino::Server.new(app,
   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
+  control_bind: "127.0.0.1:9293",   # monitoring: /stats /metrics /ready /live; port 0 reads back via server.control_port
+  control_token: ENV["KINO_CONTROL_TOKEN"],  # optional Bearer auth for /stats + /metrics
   tls: { cert: "cert.pem", key: "key.pem" },  # file paths or inline PEM
 )
 server.start
@@ -253,8 +261,10 @@ server.shutdown               # graceful: drain → deadline → abort straggler
 
 ## Config file and CLI
 
-Settings can live in a Puma-style Ruby DSL file. Precedence: explicit
-kwargs and CLI flags > config file > defaults.
+Settings can live in a Puma-style Ruby DSL file: `kino.rb` in the
+working directory, or `config/kino.rb` (the Rails layout), is picked up
+automatically; `-C PATH` names any other. Precedence: explicit kwargs
+and CLI flags > config file > defaults.
 
 ```ruby
 # kino.rb
@@ -320,6 +330,44 @@ 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`).
 
+## Lifecycle hooks
+
+Kino fires four lifecycle hooks alongside `on_error`, split by firing context.
+
+**Worker-context hooks** run inside the worker and are available to all workers:
+- `after_worker_boot { |worker_id| }`: runs once before the worker begins serving, with its slot id. In `:ractor` mode it runs inside the worker ractor and must be `Ractor.shareable_proc`.
+- `after_request_complete { |env, status| }`: fires inside the worker after each successful response. This is the hot path—leave it unset for zero cost. In `:ractor` mode it must be `Ractor.shareable_proc`.
+
+**Main-context hooks** run on the main thread, outside workers, and are plain procs:
+- `after_boot { }`: fires once after the worker pool is up. Wire readiness here—sd_notify, a "server ready" metric, and so on.
+- `on_worker_exit { |worker_index, error| }`: fires when a worker exits, with its index and the crash cause (or nil on a clean exit).
+
+`after_worker_boot`'s argument is the worker's slot id, while in `:ractor` mode `on_worker_exit`'s argument identifies the exited ractor (`0`..`workers - 1`)—a different number space—so don't correlate boot and exit by that number in `:ractor` mode.
+
+A raising hook is logged and never kills a worker.
+
+## Stuck-worker quarantine
+
+`quarantine_timeout: seconds` (or `quarantine_timeout 60` in `kino.rb`)
+quarantines a dispatch slot whose request has run longer than the deadline
+and spawns a replacement worker to restore capacity—distinct from
+`request_timeout`, which gives the client a 504 but leaves the slot
+occupied. `quarantine_max` (default: the worker count in `:ractor` mode,
+workers × threads in `:threaded`) caps the total number of replacement
+events over the process lifetime—past it the monitor stops replacing and
+the server runs at reduced capacity.
+
+The wedged worker is never interrupted or force-killed, and its slot stays
+quarantined for good. In `:threaded` mode, if the blocked thread
+eventually returns, it keeps serving requests on that same slot—but the
+slot itself stays flagged quarantined (busy_ms reported as 0) for the rest
+of the process; in `:ractor` mode the wedged ractor (and its supervisor
+thread) leaks until the process exits, since a wedged ractor cannot be
+safely interrupted. Monitor quarantine activity via `server.stats`
+(top-level `quarantined` count and per-slot `worker_status[].quarantined`
+flag), `GET /stats` (same), and `GET /metrics` (`kino_quarantined_workers`
+gauge and `kino_quarantine_replacements_total` counter).
+
 ## Stats
 
 `server.stats` returns a live snapshot: the configuration plus counters
@@ -330,17 +378,50 @@ cost):
 server.stats
 # => {mode: :ractor, lanes: false, workers: 8, threads: 1, batch: 1,
 #     respawns: 0, queued: 0, in_flight: 2, served: 1041, rejected: 0,
-#     timeouts: 0}
+#     timeouts: 0, worker_status: [...]}
 # plus lane_depths: [...] when lane dispatch is on
 ```
 
-From the outside, `kill -USR1 <pid>` prints the same snapshot as one line
+From the outside, `kill -USR1 <pid>` logs the same snapshot as one line
 (pair it with `pidfile` to find the pid):
 
 ```
-Kino stats: mode=:ractor lanes=false workers=8 threads=1 batch=1 respawns=0 queued=0 in_flight=2 served=1041 rejected=0 timeouts=0
+kino[4213] main: stats mode=:ractor lanes=false workers=8 threads=1 batch=1 respawns=0 queued=0 in_flight=2 served=1041 rejected=0 timeouts=0
 ```
 
+For pull-based monitoring, `control_bind "127.0.0.1:9293"` (or a
+`unix://` path) serves a read-only **control plane** from the native
+layer on its own thread—it keeps answering even while every Ruby worker
+is busy or stuck, and reports `draining` through a graceful shutdown:
+
+- `GET /stats`—the same snapshot as `server.stats`, as JSON (plus
+  `state` and `version`).
+- `GET /metrics`—Prometheus text format (`kino_requests_served_total`,
+  `kino_queue_depth`, `kino_ready`, …).
+
+Both `/stats` and `/metrics` also break the counters down per dispatch
+slot: `/stats` carries a `worker_status` array (`index`, `served`,
+`in_flight`, `busy_ms`) and `/metrics` emits `kino_worker_*{worker="N"}`
+series, one entry per execution slot (`workers × threads`)—a crashed
+worker's slot is never reused, so it stays in the list with its counters
+frozen where they stopped, meaning the array (and its `worker="N"` metric
+series) grows by one across every respawn. `busy_ms` is how long the
+slot's current request has been running (0 when idle), so a single slot
+climbing while the rest sit at 0 is your stuck worker.
+
+The `/stats` response and `server.stats` carry `queue_time` (count and
+summed seconds), and `/metrics` exposes `kino_request_queue_seconds`—a
+Prometheus histogram of queue-wait time, the worker-saturation signal.
+Counts admitted requests only; a 503 after queue wait goes to `rejected`,
+not `queue_time`.
+
+- `GET /ready`—`200` when serving, `503` while booting or draining:
+  wire it to your load balancer or Kubernetes readiness probe.
+- `GET /live`—`200` whenever the process is alive: the liveness probe.
+
+`control_token "..."` puts `/stats` and `/metrics` behind
+`Authorization: Bearer`; the probes stay open.
+
 ## Logging
 
 With one log line per request, `Kino::Logger` sustained **2.4× the
@@ -349,16 +430,28 @@ box). There are two native pieces. Both write through a lock-free
 channel to a Rust flusher thread, so request threads never take a log
 mutex and never make a write syscall:
 
-- **Access log** (`log_requests true`): one line per request to stdout,
-  including the 503s that never reach your app. Recommended in
-  development; cheap enough for production. On color terminals the
-  lines are tinted by status class: 2xx green, 3xx yellow, 4xx maroon,
-  5xx bright red:
+- **Access log** (`log_requests true`): two records per request to
+  stdout, including the 503s that never reach your app. The arrival line
+  is queued before the app runs, so a request that hangs shows as an
+  arrow with no answer; the completion line carries the status, the
+  total, and a timing breakdown: `ruby` is the time the request spent in
+  Ruby (with the GC pause and the objects allocated during it), `kino`
+  the server's own overhead, `wait` the queue time before a worker took
+  it. Recommended in development; cheap enough for production. On color
+  terminals the completion line is tinted by status class: 2xx green,
+  3xx yellow, 4xx maroon, 5xx bright red:
 
   ```
-  127.0.0.1 [Tue, 10 Jun 2026 13:39:56 GMT] "GET / HTTP/1.1" 200 0.1ms
+  2026-08-22 14:03:11 +0300 → GET /users?q=1  from 127.0.0.1
+  2026-08-22 14:03:11 +0300 ← 200 GET /users?q=1  12.4ms (ruby 9.1ms [gc 0.8ms; 1.5k obj]; kino 3.2ms; wait 0.1ms)
   ```
 
+  The GC and allocation figures come from the VM's process-wide
+  counters, so they appear only where one request at a time can own
+  them: in `:threaded` mode, or in `:ractor` mode with `workers 1`.
+  Parallel ractors would bill each other's work, so there the breakdown
+  is `(ruby; kino; wait)` alone.
+
 - **`Kino::Logger`**: a `::Logger` over the same async sink, for your
   app's own logging (`Kino::Logger.new("log/production.log")`, or no
   argument for stdout). The raw IO-like device is `Kino::Logger::Device`,
@@ -400,6 +493,27 @@ lines/s), the sink drops lines instead of blocking request threads.
 These trade-offs are measured in
 [doc/benchmarks.md](doc/benchmarks.md#logging-costs).
 
+**Server lines.** Everything Kino says about itself (draining, a crash
+and its respawn, a hook that raised, quarantine, the stats line,
+`rack.errors`) reads `kino[<pid>] <source>: message`, the source being
+the worker that spoke, `worker-3` (or `worker-3/thread-2` in a
+multi-threaded ractor), or `main`. On color terminals the label is dim
+for notes, yellow for warnings, red for errors; the message stays plain.
+A failed request gets a report instead of a bare backtrace: the request
+line, the error, and where it raised in your code, then the trace with
+your frames first, relative to the working directory, and the rest
+folded:
+
+```
+kino[4213] worker-2: 500 GET /boom · RuntimeError: kaboom (app.rb:12:in 'explode')
+    app.rb:12:in 'explode'
+    /usr/lib/ruby/gems/4.0.0/gems/rack-3.2.7/lib/rack/builder.rb:...
+    … 38 more
+```
+
+Hooks can log through the same channel with `Kino::Log.info`, `.warn`,
+and `.error`; it is safe inside worker ractors.
+
 ## Timer waits
 
 `Kino.sleep(seconds)` is a high-resolution sleep on the OS clock with
@@ -418,8 +532,9 @@ optional in Rack 3.
 
 ## Rails
 
-Rails (edge) runs on Kino today in `:threaded` mode; see
-`examples/rails-hello`. Ractor-mode Rails is blocked upstream. The exact
+Rails (edge) runs on Kino today in `:threaded` mode (`rails server -u
+kino`, or the `kino` CLI); see `examples/rails-hello`. Ractor-mode Rails
+is blocked upstream. The exact
 blockers, the `Ruby::Box` findings, and what would unlock it are written
 up in [doc/rails-on-ractors.md](doc/rails-on-ractors.md). The example
 ships a probe script that re-tests against whatever Rails you bundle.
@@ -442,7 +557,7 @@ For the Rust network stack, thanks to [Sean McArthur](https://github.com/seanmon
 
 ## Assisted by
 
-Claude Code (Mythos, Opus).
+Claude Code (Fable 5, Opus 4.8).
 
 ## Contributing
 

data/exe/kino

@@ -9,10 +9,6 @@
 # process-global bits an executable owns.
 
 Warning[:experimental] = false
-# Startup output must land immediately even when stdout is a pipe or file
-# (process supervisors, `kino > server.log`); block buffering would hold
-# the banner back until exit.
-$stdout.sync = true
 
 # Running from a git checkout (no installed gem, no bundler context):
 # prefer the checkout's own lib so `require "kino"` resolves.

data/lib/kino/cli.rb

@@ -100,11 +100,14 @@ module Kino
       end.join
     end
 
-    # One-line stats dump (the SIGUSR1 handler's output).
+    # One-line stats dump (what the SIGUSR1 handler logs). Excludes
+    # worker_status: it's an array with one entry per execution slot, and
+    # printing it inline would break the one-line contract (see /stats for
+    # per-worker detail).
     # @param stats [Hash{Symbol => Object}] see {Kino::Server#stats}
     # @return [String]
     def stats_line(stats)
-      dim("Kino stats: #{stats.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")}")
+      "stats #{stats.except(:worker_status).map { |k, v| "#{k}=#{v.inspect}" }.join(" ")}"
     end
 
     # The two banner halves around Server#start: credits before, the ready
@@ -116,15 +119,27 @@ module Kino
       puts dim("\nKino #{VERSION} presents:")
     end
 
+    # The ready block: what this process is (Ruby build with its JIT and
+    # parser flags, environment, topology, pid) and where it listens.
     # @param server [Kino::Server] a started server
     # @return [void]
     def action!(server)
-      puts dim("- mode:      #{server.mode}")
-      puts dim("- listening: http#{"s" if server.tls?}://#{server.bind}:#{server.port}")
+      stats = server.stats
+      puts dim("- ruby:      #{RUBY_DESCRIPTION}")
+      puts dim("- env:       #{ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"}")
+      puts dim("- mode:      #{server.mode}, #{count(stats[:workers], "worker")} × #{count(stats[:threads], "thread")}")
+      puts dim("- pid:       #{Process.pid}")
+      puts dim("- listening: #{server.url}")
+      puts dim("- control:   #{server.control_url}") if server.control_url
       puts dim("- Ctrl-C to drain and stop")
       puts "\n#{bold("Action!")}\n\n"
     end
 
+    # "1 worker", "8 workers".
+    def count(number, noun)
+      "#{number} #{noun}#{"s" unless number == 1}"
+    end
+
     # Roll credits when the process ends: normal exit or crash (at_exit
     # also runs after an uncaught exception; only a force-exit skips it).
     # @return [void]
@@ -197,7 +212,7 @@ module Kino
     def option_parser(options)
       OptionParser.new do |opts|
         opts.banner = "Usage: kino [options] [rackup file (default: config.ru)]"
-        opts.on("-C", "--config FILE", "Config file (default: kino.rb if present)") { |v| options[:config_file] = v }
+        opts.on("-C", "--config FILE", "Config file (default: kino.rb, then config/kino.rb)") { |v| options[:config_file] = v }
         opts.on("--init [PATH]", "Write a commented sample config (default: kino.rb) and exit") do |v|
           options[:init_path] = v || "kino.rb"
         end
@@ -233,14 +248,13 @@ module Kino
       require "kino"
       require "rack"
 
-      config_file = options[:config_file]
-      config_file ||= ("kino.rb" if File.exist?("kino.rb"))
+      config_file = options[:config_file] || Configuration.default_path
 
       config = Configuration.new
       config.load_file(config_file) if config_file
       config.merge!(options[:overrides])
       # Default port 9292 when neither the file nor a flag chose one.
-      config.set(:port, 9292) unless config.set?(:port)
+      config.set(:port, Configuration::DEFAULT_SERVING_PORT) unless config.set?(:port)
       config
     end
 
@@ -249,6 +263,6 @@ module Kino
     end
 
     private_class_method :print_help, :option_parser, :write_sample,
-      :resolve_config, :serve
+      :resolve_config, :serve, :count
   end
 end

data/lib/kino/configuration.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "etc"
-
 module Kino
   # Server settings with Puma-style precedence:
   #   explicit Server.new kwargs > config file DSL > defaults.
@@ -11,7 +9,7 @@ module Kino
     DEFAULTS = {
       bind: "127.0.0.1",
       port: 0,
-      workers: nil, # resolved to Etc.nprocessors in #to_h
+      workers: nil, # resolved to Kino.available_parallelism in #to_h
       threads: nil, # resolved per mode in Server: 1 in :ractor, 3 in :threaded
       mode: :auto,
       queue_depth: 1024,
@@ -23,11 +21,19 @@ module Kino
       lanes: false,
       log_requests: false,
       on_error: nil,
+      after_boot: nil,
+      after_worker_boot: nil,
+      after_request_complete: nil,
+      on_worker_exit: nil,
       shutdown_timeout: 30,
       tokio_threads: nil,
       tls: nil,
       environment: nil,
       pidfile: nil,
+      control_bind: nil,
+      control_token: nil,
+      quarantine_timeout: nil,
+      quarantine_max: nil,
       rackup: nil
     }.freeze
 
@@ -37,6 +43,21 @@ module Kino
     # Source template for {.sample}.
     SAMPLE_TEMPLATE = File.expand_path("templates/kino.rb.tt", __dir__)
 
+    # Where the `kino` CLI and the Rack handler look for a config file when
+    # none is named: the project root first, then the Rails-style config/.
+    DEFAULT_PATHS = %w[kino.rb config/kino.rb].freeze
+
+    # The port the CLI and the Rack handler serve on when neither a flag
+    # nor the file chose one (Server.new itself defaults to an ephemeral
+    # port, for embedding).
+    DEFAULT_SERVING_PORT = 9292
+
+    # The first of {DEFAULT_PATHS} that exists in the working directory.
+    # @return [String, nil]
+    def self.default_path
+      DEFAULT_PATHS.find { |path| File.exist?(path) }
+    end
+
     # The fully-commented sample config (see `kino --init`).
     # @return [String]
     def self.sample
@@ -105,7 +126,7 @@ module Kino
     # @return [Hash{Symbol => Object}] every setting, defaults filled in
     def to_h
       SETTINGS.to_h { |key| [key, self[key]] }.tap do |h|
-        h[:workers] ||= Etc.nprocessors
+        h[:workers] ||= Kino.available_parallelism
       end
     end
 
@@ -138,7 +159,9 @@ module Kino
         @config = config
       end
 
-      # Address to listen on ("0.0.0.0" accepts non-local connections).
+      # Address to listen on: a host ("0.0.0.0" accepts non-local
+      # connections), or "unix:///path/to.sock" for a unix domain socket
+      # (then `port` is unused).
       def bind(host) = @config.set(:bind, host)
 
       # Port to listen on; 0 picks an ephemeral port.
@@ -185,6 +208,24 @@ module Kino
       # or a block. Must be Ractor-shareable in :ractor mode.
       def on_error(handler = nil, &block) = @config.set(:on_error, handler || block)
 
+      # Called once on the main thread after the worker pool is up. The
+      # readiness seam (wire sd_notify or a "server ready" metric here).
+      def after_boot(handler = nil, &block) = @config.set(:after_boot, handler || block)
+
+      # Called once inside each worker (a ractor in :ractor mode) before it
+      # serves, with the worker's slot id. Must be Ractor-shareable in
+      # :ractor mode (build it with Ractor.shareable_proc).
+      def after_worker_boot(handler = nil, &block) = @config.set(:after_worker_boot, handler || block)
+
+      # Called inside the worker after each successful response with
+      # (env, status). Hot path: leave unset for zero cost. Must be
+      # Ractor-shareable in :ractor mode.
+      def after_request_complete(handler = nil, &block) = @config.set(:after_request_complete, handler || block)
+
+      # Called on the main thread when a worker exits, with (worker_index,
+      # error_or_nil). error is the crash cause, or nil on a clean exit.
+      def on_worker_exit(handler = nil, &block) = @config.set(:on_worker_exit, handler || block)
+
       # Graceful-shutdown drain deadline in seconds.
       def shutdown_timeout(seconds) = @config.set(:shutdown_timeout, seconds)
 
@@ -200,6 +241,37 @@ module Kino
       # Write the master PID here on start.
       def pidfile(path) = @config.set(:pidfile, path.to_s)
 
+      # Serve the read-only control plane (live stats as JSON at /stats,
+      # Prometheus text at /metrics, /ready and /live probes) on this
+      # address: "host:port" or "unix://path". Off unless set.
+      def control_bind(addr) = @config.set(:control_bind, addr.to_s)
+
+      # When set, /stats and /metrics require "Authorization: Bearer <token>".
+      # The probes stay open; they carry no data.
+      def control_token(token) = @config.set(:control_token, token.to_s)
+
+      # Quarantine a dispatch slot whose current request has run longer
+      # than this many seconds, spawning a replacement to restore capacity.
+      # Off unless set. Set it above your slowest legitimate endpoint (and
+      # typically above request_timeout).
+      def quarantine_timeout(seconds)
+        seconds &&= Float(seconds)
+        if seconds && seconds <= 0
+          raise ArgumentError, "quarantine_timeout must be greater than 0 (got #{seconds})"
+        end
+        @config.set(:quarantine_timeout, seconds)
+      end
+
+      # Cap on the total number of replacement events over the process
+      # lifetime. Past the cap the monitor stops replacing and the server
+      # runs at reduced capacity. Default: the worker count in :ractor
+      # mode, workers x threads in :threaded.
+      def quarantine_max(count)
+        count = Integer(count)
+        raise ArgumentError, "quarantine_max must be >= 1 (got #{count})" if count < 1
+        @config.set(:quarantine_max, count)
+      end
+
       # Rackup file the `kino` CLI loads (positional argument wins).
       def rackup(path) = @config.set(:rackup, path.to_s)
     end

data/lib/kino/errors_stream.rb

@@ -2,17 +2,18 @@
 
 module Kino
   # @private
-  # rack.errors: stateless writer into the native logger. Frozen singleton,
+  # rack.errors: stateless writer into the server log (one line per
+  # call, labelled like every other line Kino writes). Frozen singleton,
   # which also makes it Ractor-shareable; one instance serves all workers.
   class ErrorsStream
     def puts(message)
-      Native.log_error(message.to_s)
+      Log.error(message.to_s.chomp)
       nil
     end
 
     def write(message)
       message = message.to_s
-      Native.log_error(message)
+      Log.error(message.chomp)
       message.bytesize
     end
 

data/lib/kino/hook_fire.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Kino
+  # @private
+  # Fires a lifecycle hook and turns a raise into a logged line instead of
+  # letting it escape. Stateless and touches only its arguments plus
+  # Kino::Log (safe inside worker ractors), so it is safe to call from
+  # worker context: no main-ractor state is captured.
+  module HookFire
+    module_function
+
+    def fire(hook, name, *args)
+      return unless hook
+
+      begin
+        hook.call(*args)
+      rescue => e
+        Log.error("#{name} hook raised #{e.class}: #{e.message}")
+      end
+    end
+  end
+end