kino 0.3.0-aarch64-linux → 0.4.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18bb12fa02179c4c2e164cf83e605ac893094650fcaee119132b48b2eea0ae2e
-  data.tar.gz: 56c6652d6671f2872e0399f82a789e6b4cc5b0ea018f5503bb91ed575f187985
+  metadata.gz: 145273ae455b0822a24794c25d449376b3ba5122f3f275c00b4a959fdafd5183
+  data.tar.gz: c20ae1c2f111a4f6329ea25a4d9c9a0579dfa1b77765ff11e35572f8e32925ca
 SHA512:
-  metadata.gz: 1c3f92ba0bd339f2415ae94024f4afc5666a356c69b7721bb36deeccc492521d7f75a5ef064f994306a771924a42ccb00ff6e3ce138754b797ef5e2263144622
-  data.tar.gz: ae5f7535f0fc9ef4b9398a1fdd57723aae445d49ef7705fb1cab907d6b8ab01bb25338394509467e7cc755b37105b306ab08f89f755d4496e186e63f32cd6ace
+  metadata.gz: ed2ef3b3d79817b67da62e8271f0a420d4ee0c8976780d97e6e91ba15cddff2e1d34e830d41a8c4c8c63d65fecbeab32bec8d8568777b399c684cdfce00624f0
+  data.tar.gz: 6d695d16998c2bdb9fe44ac709a311990c53c88ae980f136757db926ba370e5a8e379fdd098f675beae4fb126a0ce7d663b36b0a602d6933b1c2b6d3f6cdc02b

data/CHANGELOG.md

@@ -1,3 +1,48 @@
+## [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

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
@@ -255,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
@@ -374,11 +382,11 @@ server.stats
 # 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
@@ -422,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`,
@@ -473,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
@@ -491,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.

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,14 +100,14 @@ module Kino
       end.join
     end
 
-    # One-line stats dump (the SIGUSR1 handler's output). Excludes
+    # 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.except(:worker_status).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
@@ -119,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]
@@ -200,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
@@ -236,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
 
@@ -252,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,
@@ -45,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
@@ -113,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
 
@@ -146,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.

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

@@ -4,9 +4,8 @@ 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
-  # Native.log_error (already called from inside worker ractors today), so
-  # it is safe to call from worker context: no main-ractor state is
-  # captured.
+  # 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
 
@@ -16,7 +15,7 @@ module Kino
       begin
         hook.call(*args)
       rescue => e
-        Native.log_error("#{name} hook raised #{e.class}: #{e.message}")
+        Log.error("#{name} hook raised #{e.class}: #{e.message}")
       end
     end
   end

data/lib/kino/log.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Kino
+  # Server log lines: the lifecycle notices, crash and respawn reports,
+  # hook failures, the failed-request report, and whatever apps write to
+  # `rack.errors`, all in one shape:
+  #
+  #   kino[4213] worker-3: after_worker_boot hook raised RuntimeError: boom
+  #
+  # The label is syslog's `ident[pid]` tag plus the source that spoke: the
+  # worker ractor and/or thread by name, `main` for neither. On color
+  # terminals the label is dim, yellow, or red by level; the message stays
+  # plain. Notes go to stdout, warnings and errors to stderr.
+  #
+  # Hooks may log through here too (`Kino::Log.info "cache warm"`). Every
+  # method is safe inside a worker ractor: the line is handed to the
+  # native layer, which owns the streams, so no ractor touches `$stdout`
+  # or `$stderr` itself.
+  module Log
+    # Frames shown in a failed-request report before the rest are folded.
+    FRAMES = 12
+
+    # The working directory at boot, stripped from backtrace frames so the
+    # app's own code reads `app/controllers/x.rb:9` rather than an
+    # absolute path (frozen: worker ractors read it).
+    WORKING_DIR = File.join(Dir.pwd, "").freeze
+
+    module_function
+
+    # @param message [#to_s]
+    # @return [void]
+    def info(message)
+      Native.log_line("info", source, message.to_s)
+    end
+
+    # @param message [#to_s]
+    # @return [void]
+    def warn(message)
+      Native.log_line("warn", source, message.to_s)
+    end
+
+    # @param message [#to_s]
+    # @return [void]
+    def error(message)
+      Native.log_line("error", source, message.to_s)
+    end
+
+    # The failed-request report: the request line, the error, and where it
+    # raised in the app, then the backtrace with the app's own frames
+    # first (relative to the working directory) and the rest folded.
+    #
+    #   500 GET /boom · RuntimeError: kaboom (app.rb:12:in 'explode')
+    #       app.rb:12:in 'explode'
+    #       /gems/rack-3.2.7/lib/rack/builder.rb:...
+    #       … 38 more
+    #
+    # @param error [Exception]
+    # @param env [Hash] the Rack env of the failed request
+    # @param status [Integer] the status the client got
+    # @return [void]
+    def exception(error, env, status: 500)
+      frames, depth = trace(error)
+      site = frames.first ? " (#{frames.first})" : ""
+      lines = ["#{status} #{env["REQUEST_METHOD"]} #{env["PATH_INFO"]} · #{error.class}: #{error.message}#{site}"]
+      frames.each { |frame| lines << "    #{frame}" }
+      lines << "    … #{depth - frames.size} more" if depth > frames.size
+      error(lines.join("\n"))
+    end
+
+    # The `kino[<pid>] <source>:` tag a line from here carries.
+    # @return [String]
+    def label
+      "kino[#{Process.pid}] #{source}:"
+    end
+
+    # Who is speaking: the ractor's name, the thread's name, both joined
+    # with a slash, or `main` when neither is named. Kino names its
+    # worker ractors and threads `worker-N`.
+    # @return [String]
+    def source
+      parts = [Ractor.current.name, Thread.current.name].compact
+      parts.empty? ? "main" : parts.join("/")
+    end
+
+    # The backtrace as [frames, depth]: each frame relativized to the
+    # working directory, the app's own frames floated to the front (the
+    # raise site in your code reads first; gem and stdlib frames keep
+    # their order below), capped at FRAMES; depth is the real length.
+    def trace(error)
+      raw = error.backtrace || []
+      app, rest = raw.map { |frame| frame.delete_prefix(WORKING_DIR) }.partition { |frame| app_frame?(frame) }
+      [(app + rest).first(FRAMES), raw.size]
+    end
+
+    # A project-relative path (the working-directory prefix came off, so
+    # it does not start with `/`) that is not a synthetic frame (`(eval)`,
+    # `<internal:...>`). Gem and stdlib frames stay absolute.
+    def app_frame?(frame)
+      !frame.start_with?("/", "<", "(")
+    end
+
+    private_class_method :trace, :app_frame?
+  end
+end

data/lib/kino/quarantine_monitor.rb

@@ -21,7 +21,10 @@ module Kino
 
     def start
       @running = true
-      @thread = Thread.new { run }
+      @thread = Thread.new do
+        Thread.current.name = "quarantine"
+        run
+      end
       self
     end
 
@@ -35,14 +38,14 @@ module Kino
     def run
       tick while @running
     rescue => e
-      Native.log_error("quarantine monitor crashed: #{e.class}: #{e.message}")
+      Log.error("quarantine monitor crashed: #{e.class}: #{e.message}")
     end
 
     def tick
       scan_slots
     rescue => e
       # A bad tick must never kill the monitor.
-      Native.log_error("quarantine tick error: #{e.class}: #{e.message}")
+      Log.error("quarantine tick error: #{e.class}: #{e.message}")
     ensure
       sleep @tick
     end
@@ -53,7 +56,7 @@ module Kino
 
         if @outstanding >= @max
           unless @at_cap_logged
-            Native.log_error("quarantine at cap (#{@max}); serving at reduced capacity")
+            Log.warn("quarantine at cap (#{@max}); serving at reduced capacity")
             @at_cap_logged = true
           end
           next

data/lib/kino/ractor_supervisor.rb

@@ -91,6 +91,7 @@ module Kino
 
     def supervise(index)
       Thread.new do
+        Thread.current.name = "supervisor-#{index}"
         crashes = 0
         loop do
           ractor, worker_ids = spawn_worker(index)
@@ -109,7 +110,7 @@ module Kino
 
             crashes += 1
             Native.record_respawn(@server_id)
-            Native.log_error("worker ractor #{index} crashed (#{cause.class}: #{cause.message}); respawning")
+            Log.error("worker-#{index} crashed (#{cause.class}: #{cause.message}); respawning")
             # Policy (crash recovery): unlimited respawn
             # keeps the server up under rare crashes but turns a
             # crash-on-every-request bug into a busy loop. A circuit breaker
@@ -129,12 +130,16 @@ module Kino
         @worker_slots[worker_index] = worker_ids
         worker_ids.each { |id| @slot_to_worker[id] = worker_index }
       end
-      ractor = Ractor.new(@server_id, worker_ids, @app, @batch, @hooks) do |server_id, ids, app, batch, hooks|
-        ids.map do |id|
+      # Named so log lines from inside say which worker spoke: the ractor
+      # alone for a single thread, `worker-N/thread-M` for more.
+      ractor = Ractor.new(@server_id, worker_ids, @app, @batch, @hooks,
+        name: "worker-#{worker_index}") do |server_id, ids, app, batch, hooks|
+        ids.each_with_index.map do |id, position|
           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
+            Thread.current.name = "thread-#{position + 1}" if ids.size > 1
             Kino::Worker.run(server_id, id, app, batch, hooks)
           end
         end.each(&:join)

data/lib/kino/server.rb

@@ -27,6 +27,29 @@ module Kino
       !@tls.nil?
     end
 
+    # @return [Boolean] whether the bind is a unix domain socket
+    #   ("unix:///path/to.sock")
+    def unix?
+      @bind.start_with?("unix://")
+    end
+
+    # Where the server listens, once started: `http://host:port`
+    # (`https` under TLS), or the `unix://` socket path.
+    # @return [String]
+    def url
+      unix? ? @bind : "http#{"s" if tls?}://#{@bind}:#{@port}"
+    end
+
+    # Where the control plane listens, once started, or nil when it is
+    # off: `http://host:port`, or its `unix://` socket path.
+    # @return [String, nil]
+    def control_url
+      return nil unless @control_bind
+      return @control_bind if @control_bind.start_with?("unix://")
+
+      "http://#{@control_bind.rpartition(":").first}:#{@control_port}"
+    end
+
     # Settings precedence: explicit kwargs > config_file DSL > defaults.
     #
     # @param app [#call] a Rack 3 application
@@ -54,7 +77,12 @@ module Kino
       @worker_hooks = WorkerHooks.new(
         on_error: @on_error,
         after_worker_boot: @after_worker_boot,
-        after_request_complete: @after_request_complete
+        after_request_complete: @after_request_complete,
+        # The access log's GC and allocation figures come from the VM's
+        # process-wide counters, so they are measured only where one
+        # request at a time can own them: the GVL serializes :threaded
+        # mode, and a single ractor has nothing to race.
+        access_timing: !!settings[:log_requests] && (@mode == :threaded || @workers == 1)
       )
       # Default threads per mode: 1 in :ractor (threads inside a ractor
       # share its lock; a measured +17% on fast handlers; raise `workers`
@@ -72,6 +100,9 @@ module Kino
       @shutdown_timeout = settings[:shutdown_timeout]
       @tokio_threads = settings[:tokio_threads]
       @tls = validate_tls(settings[:tls])
+      if @tls && unix?
+        raise ArgumentError, "TLS is not supported on a unix socket bind; terminate TLS at the proxy in front"
+      end
       @pidfile = settings[:pidfile]
       @control_bind = settings[:control_bind]&.to_s
       @control_token = settings[:control_token]&.to_s
@@ -195,22 +226,34 @@ module Kino
       @supervisor ? @supervisor.join : @worker_threads.each(&:join)
     end
 
-    # Production entry point: start, print the banner, trap INT/TERM for
-    # graceful shutdown (second signal force-exits), block until done.
-    # The `kino` CLI funnels into this too (CLI#serve).
+    # Production entry point: build the server and {#run} it. The `kino`
+    # CLI funnels into this too (CLI#serve).
     #
     # @param app [#call] a Rack 3 application
     # @param opts [Hash] see #initialize
     # @return [Kino::Server] the (stopped) server, after shutdown
     def self.run(app, **opts)
-      server = new(app, **opts)
+      new(app, **opts).run
+    end
+
+    # Serve until shut down: start, print the banner, trap INT/TERM for
+    # graceful shutdown (second signal force-exits), block until done.
+    # The Rack handler calls this on a server it built itself.
+    #
+    # @return [self] after shutdown
+    def run
+      # Startup output must land immediately even when stdout is a pipe or
+      # file (process supervisors, `kino > server.log`, `rails server`
+      # under Docker); block buffering would hold the banner back until
+      # exit.
+      $stdout.sync = true
       CLI.opening_credits
-      server.start
-      CLI.action!(server)
+      start
+      CLI.action!(self)
       CLI.fin_at_exit
-      trap_signals(server)
-      server.wait
-      server
+      self.class.trap_signals(self)
+      wait
+      self
     end
 
     # Signal handling shared by Server.run and the kino CLI: INT/TERM drain
@@ -222,14 +265,14 @@ module Kino
       # kill -USR1 <pid> prints a one-line stats snapshot (find the pid in
       # the pidfile when configured).
       trap("USR1") do
-        Thread.new { $stdout.puts Kino::CLI.stats_line(server.stats) }
+        Thread.new { Log.info(CLI.stats_line(server.stats)) }
       end
       signaled = false
       %w[INT TERM].each do |signal|
         trap(signal) do
           Process.exit!(1) if signaled
           signaled = true
-          $stderr.write("Kino: draining (signal again to force exit)\n")
+          Log.warn("draining (signal again to force exit)")
           # Trap context forbids mutexes; do the real work on a thread.
           Thread.new { server.shutdown }
         end
@@ -270,6 +313,8 @@ module Kino
     def spawn_worker_thread
       worker_id = Native.register_worker(@id)
       Thread.new do
+        # Named so log lines from inside say which worker spoke.
+        Thread.current.name = "worker-#{worker_id}"
         error = nil
         begin
           Worker.run(@id, worker_id, @app, @batch, @worker_hooks)
@@ -442,7 +487,7 @@ module Kino
       if @supervisor
         # Ractors cannot be force-killed; their clients were already freed
         # by abort_all_inflight. The stuck ractor leaks until process exit.
-        Native.log_error("shutdown deadline passed with stuck ractor workers") unless @supervisor.done?
+        Log.error("shutdown deadline passed with stuck ractor workers") unless @supervisor.done?
       else
         threads = @worker_threads_lock.synchronize { @worker_threads.dup }
         threads.each { |thread| thread.kill if thread.alive? }
@@ -474,10 +519,10 @@ module Kino
         :ractor
       when :auto
         if !Ractor.shareable?(@app)
-          warn "Kino: app is not Ractor-shareable; falling back to mode: :threaded"
+          Log.warn("app is not Ractor-shareable; falling back to mode: :threaded")
           :threaded
         elsif (name = unshareable_worker_hook_name)
-          warn "Kino: #{name} hook is not Ractor-shareable; falling back to mode: :threaded"
+          Log.warn("#{name} hook is not Ractor-shareable; falling back to mode: :threaded")
           :threaded
         else
           :ractor

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

@@ -8,7 +8,9 @@
 ## Network
 
 # Address to listen on. Use "0.0.0.0" to accept connections from other
-# machines.
+# machines, or "unix:///run/kino.sock" to listen on a unix domain socket
+# behind a proxy such as nginx (the port below is then unused; a stale
+# socket file is reclaimed, a live one refused).
 # bind "127.0.0.1"
 
 # Port to listen on.
@@ -22,7 +24,8 @@
 
 # How many workers to run. Each worker handles requests independently;
 # in :ractor mode every worker runs Ruby in parallel on its own core.
-# Default: one per CPU core.
+# Default: the CPUs this process may use (Kino.available_parallelism:
+# the affinity mask and, in a container, the cgroup CPU quota).
 # workers 8
 
 # Threads inside each worker. More threads help when your app spends
@@ -74,9 +77,12 @@
 # for quick handlers; behavior under heavy overload differs slightly.
 # lanes false
 
-# Print one line per request to stdout, colored by status on a
-# terminal. This is the server's view: it includes requests your app
-# never saw, such as 503s. Recommended in development.
+# Log every request to stdout: an arrival line before the app runs and a
+# completion line after it, colored by status on a terminal, with a
+# timing breakdown (time in Ruby with its GC pause and allocations, the
+# server's own overhead, and queue wait). This is the server's view: it
+# includes requests your app never saw, such as 503s. Recommended in
+# development; cheap enough for production.
 # log_requests false
 
 # Called when a worker catches an app or delivery error, after the client

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.3.0"
+  VERSION = "0.4.0"
 end

data/lib/kino/worker.rb

@@ -70,7 +70,16 @@ module Kino
     def serve(env, app, hooks)
       request = env[KINO_REQUEST]
       env[RACK_INPUT] ||= Input.new(request)
-      status, headers, body = app.call(env)
+      if hooks&.access_timing
+        # The access log's breakdown: the VM's cumulative GC time and
+        # allocation count, differenced around the app call.
+        gc_before = GC.total_time
+        allocated_before = GC.stat(:total_allocated_objects)
+        status, headers, body = app.call(env)
+        request.timing(GC.total_time - gc_before, GC.stat(:total_allocated_objects) - allocated_before)
+      else
+        status, headers, body = app.call(env)
+      end
 
       if body.respond_to?(:to_ary)
         chunks = join_chunks(body.to_ary)
@@ -99,21 +108,12 @@ module Kino
       # 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))
+      Log.exception(e, env)
       request.abort
       HookFire.fire(hooks&.on_error, "on_error", e, env)
       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)
@@ -159,7 +159,6 @@ module Kino
     end
 
     private_class_method :handle_one, :process, :serve, :deliver_streaming,
-      :join_chunks, :error_log_line, :fire_after_worker_boot,
-      :fire_after_request_complete
+      :join_chunks, :fire_after_worker_boot, :fire_after_request_complete
   end
 end

data/lib/kino/worker_hooks.rb

@@ -7,5 +7,7 @@ module Kino
   # several bare procs. Any member may be nil. A Data instance is frozen,
   # so it is Ractor.shareable? exactly when its members are (nil, or a
   # Ractor.shareable_proc), letting it ride the ractor boundary like the app.
-  WorkerHooks = Data.define(:on_error, :after_worker_boot, :after_request_complete)
+  # `access_timing` rides along: whether the worker measures the GC pause
+  # and allocations around each app call for the access log's breakdown.
+  WorkerHooks = Data.define(:on_error, :after_worker_boot, :after_request_complete, :access_timing)
 end

data/lib/kino.rb

@@ -33,9 +33,20 @@ module Kino
     remaining = Native.sleep_chunk(remaining) while remaining.positive?
     nil
   end
+
+  # How many CPUs this process may actually use: the `workers` default.
+  # Unlike `Etc.nprocessors`, this honours a cgroup CPU quota (a container
+  # limited to 2 CPUs on a 64-core host gets 2, not 64) as well as the
+  # affinity mask; a fractional quota rounds up. Never below 1.
+  #
+  # @return [Integer]
+  def self.available_parallelism
+    Native.available_parallelism
+  end
 end
 
 require_relative "kino/cli"
+require_relative "kino/log"
 require_relative "kino/logger"
 require_relative "kino/check"
 require_relative "kino/input"

data/lib/rackup/handler/kino.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Rackup
+  module Handler
+    # The Rack handler: lets any host that speaks the rackup protocol boot
+    # Kino, which is what `rackup -s kino` and `rails server -u kino` do.
+    # Loaded on demand by Rackup::Handler.get(:kino), so Rackup itself is
+    # already defined here; Kino is required only when the host calls in.
+    module Kino
+      # Host option name => Kino setting plus the coercion it needs: rackup
+      # hands `-O NAME=VALUE` values (and its own -p) over as strings.
+      OPTION_MAP = {
+        Host: [:bind, ->(value) { value.to_s }],
+        Port: [:port, ->(value) { Integer(value) }],
+        Workers: [:workers, ->(value) { Integer(value) }],
+        Threads: [:threads, ->(value) { Integer(value) }],
+        Mode: [:mode, ->(value) { value.to_sym }]
+      }.freeze
+      private_constant :OPTION_MAP
+
+      # Boot a server for `app` and block until it shuts down, the way the
+      # `kino` executable does (banner, INT/TERM drain, stats on USR1).
+      #
+      # @param app [#call] the Rack application the host built
+      # @param options [Hash] the host's options (see {.server_options})
+      # @yield [server] the built, not yet started server, for hosts that
+      #   want a handle on it
+      # @return [::Kino::Server] the stopped server, after shutdown
+      def self.run(app, **options)
+        require "kino"
+        server = ::Kino::Server.new(app, **server_options(options))
+        yield server if block_given?
+        server.run
+      end
+
+      # The `-O NAME=VALUE` options `rackup -s kino --help` lists (rackup
+      # shows its own -o/-p in place of Host and Port).
+      # @return [Hash{String => String}]
+      def self.valid_options
+        {
+          "Host=HOST" => "Address to bind (default: 127.0.0.1)",
+          "Port=PORT" => "Port to listen on (default: 9292)",
+          "Workers=COUNT" => "Workers: ractors in :ractor mode, thread groups in :threaded (default: one per CPU)",
+          "Threads=COUNT" => "Threads per worker (default: 1 in :ractor, 3 in :threaded)",
+          "Mode=MODE" => "auto | ractor | threaded (default: auto)",
+          "Config=PATH" => "Kino config file (default: kino.rb, then config/kino.rb)"
+        }
+      end
+
+      # Translate host options into {::Kino::Server#initialize} kwargs.
+      # Precedence: options the user typed > the config file > defaults the
+      # host supplied (rackup's and Rails' own Host and Port) > Kino's
+      # defaults. Hosts that say which options were typed pass
+      # `user_supplied_options`; when that list is absent every option
+      # counts as typed. Keys outside OPTION_MAP (the host's bookkeeping:
+      # environment, pid, config, ...) are ignored.
+      #
+      # @param options [Hash{Symbol => Object}]
+      # @return [Hash{Symbol => Object}]
+      def self.server_options(options)
+        require "kino"
+        options = options.dup
+        host_defaults = {}
+        if (typed = options.delete(:user_supplied_options))
+          (options.keys - typed).each { |key| host_defaults[key] = options.delete(key) }
+        end
+
+        config = ::Kino::Configuration.new
+        path = options.delete(:Config) || host_defaults.delete(:Config) || ::Kino::Configuration.default_path
+        config.load_file(path) if path
+        translate(host_defaults).each { |key, value| config.set(key, value) unless config.set?(key) }
+        config.merge!(translate(options))
+        config.set(:port, ::Kino::Configuration::DEFAULT_SERVING_PORT) unless config.set?(:port)
+        config.server_options
+      end
+
+      def self.translate(options)
+        options.filter_map do |key, value|
+          setting, coerce = OPTION_MAP[key]
+          [setting, coerce.call(value)] if setting
+        end.to_h
+      end
+      private_class_method :translate
+    end
+
+    register :kino, Kino
+  end
+end

data/sig/kino.rbs

@@ -20,6 +20,9 @@ module Kino
   # High-resolution sleep on the OS clock with the GVL released.
   def self.sleep: (Numeric seconds) -> nil
 
+  # CPUs this process may use (affinity mask and cgroup quota); never below 1.
+  def self.available_parallelism: () -> Integer
+
   class Server
     attr_reader port: Integer?
     attr_reader control_port: Integer?
@@ -28,6 +31,16 @@ module Kino
 
     def tls?: () -> bool
 
+    # Whether the bind is a unix domain socket ("unix:///path/to.sock").
+    def unix?: () -> bool
+
+    # Where the server listens once started: http(s)://host:port or the
+    # unix:// socket path.
+    def url: () -> String
+
+    # Where the control plane listens once started, or nil when it is off.
+    def control_url: () -> String?
+
     # Settings precedence: explicit kwargs > config_file DSL > defaults.
     def initialize: (rack_app app, ?config_file: String?, **untyped options) -> void
 
@@ -42,9 +55,12 @@ module Kino
     # served, rejected, timeouts, respawns, lane_depths when lanes are on).
     def stats: () -> stats_hash
 
-    # Production entry point: start, banner, signal traps, block until done.
+    # Production entry point: build the server and #run it.
     def self.run: (rack_app app, **untyped opts) -> Server
 
+    # Serve until shut down: start, banner, signal traps, block until done.
+    def run: () -> self
+
     # INT/TERM drain gracefully (second signal force-exits); USR1 prints stats.
     def self.trap_signals: (Server server) -> void
   end
@@ -53,6 +69,12 @@ module Kino
     DEFAULTS: Hash[Symbol, untyped]
     SETTINGS: Array[Symbol]
     SAMPLE_TEMPLATE: String
+    DEFAULT_PATHS: Array[String]
+    DEFAULT_SERVING_PORT: Integer
+
+    # The first of DEFAULT_PATHS (kino.rb, config/kino.rb) present in the
+    # working directory.
+    def self.default_path: () -> String?
 
     # The fully commented sample config (see `kino --init`).
     def self.sample: () -> String
@@ -168,6 +190,27 @@ module Kino
     def self.print_report: (rack_app app, ?io: IO) -> bool
   end
 
+  # Server log lines, `kino[<pid>] <source>: message`; safe inside worker
+  # ractors, so hooks may log through it.
+  module Log
+    FRAMES: Integer
+    WORKING_DIR: String
+
+    def self.info: (untyped message) -> void
+    def self.warn: (untyped message) -> void
+    def self.error: (untyped message) -> void
+
+    # The failed-request report: request line, error, and an app-first
+    # backtrace relative to the working directory.
+    def self.exception: (Exception error, Hash[String, untyped] env, ?status: Integer) -> void
+
+    # The `kino[<pid>] <source>:` tag.
+    def self.label: () -> String
+
+    # The ractor and/or thread name, or `main`.
+    def self.source: () -> String
+  end
+
   # A ::Logger writing through the native async sink.
   class Logger < ::Logger
     # path: a file (created/appended) or nil for stdout.
@@ -188,3 +231,21 @@ module Kino
     end
   end
 end
+
+module Rackup
+  module Handler
+    # The Rack handler behind `rackup -s kino` and `rails server -u kino`.
+    module Kino
+      # Boot a server for app and block until shutdown; yields the built,
+      # not yet started server to hosts that want a handle on it.
+      def self.run: (::Kino::rack_app app, **untyped options) ?{ (::Kino::Server) -> void } -> ::Kino::Server
+
+      # The -O options rackup lists for this handler.
+      def self.valid_options: () -> Hash[String, String]
+
+      # Host options translated into Kino::Server kwargs, with precedence
+      # typed > config file > host defaults > Kino defaults.
+      def self.server_options: (Hash[Symbol, untyped] options) -> Hash[Symbol, untyped]
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kino
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: aarch64-linux
 authors:
 - Yaroslav Markin
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-08-13 00:00:00.000000000 Z
+date: 2026-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -38,6 +38,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rackup
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -150,6 +164,7 @@ files:
 - lib/kino/hook_fire.rb
 - lib/kino/input.rb
 - lib/kino/kino.so
+- lib/kino/log.rb
 - lib/kino/logger.rb
 - lib/kino/null_input.rb
 - lib/kino/quarantine_monitor.rb
@@ -160,6 +175,7 @@ files:
 - lib/kino/version.rb
 - lib/kino/worker.rb
 - lib/kino/worker_hooks.rb
+- lib/rackup/handler/kino.rb
 - sig/kino.rbs
 homepage: https://github.com/yaroslav/kino
 licenses: