kino 0.6.0-aarch64-linux → 0.7.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47797b5264a1cdd29fcccc4e370cbf8e92fc71b46daaf3831e7bca69c51affea
-  data.tar.gz: 98b264a8a72224f37136e4ec14154e35c1b378844bbe73f35c6110dee59ffde9
+  metadata.gz: b101408a972721dec1c1041f195c4c56a18a8ca31e586903215382e54acc5fb0
+  data.tar.gz: '0386e61aa5dcbb60ce1bba381f5733b86d74e0352a47494273a575ca49ef0b47'
 SHA512:
-  metadata.gz: 9035020f4e0f2a47666391c05c8a7992176258f186ccc0613fb97de3609bdd98866ab015bd1263246245dc9be0622dfbd93880516bca2d818f5d5bf2ea65739c
-  data.tar.gz: fd323d0e09a40124a91b19f1142f335c41f2e97fc8d33369fc437e5a1cb50fcf91bd82aeb74f85d3c6f577533e1345f1cf323b2004784a6ab21df9d7b5839648
+  metadata.gz: 5dd12ec5e0bfb20e14f2d6aa5da9f3ea38168a6f9308559a1e7f9e115ce8eaaeda1050d1be514a6263a283f70b7dcd004e4eb12f66dbce4884be2ae73a7cae02
+  data.tar.gz: 7c30dbd7e644e6dbb5436c049c831e35e6032b3ef4b56ea4777ce0bb0d20bcdd12c236a85e60bfc35c97c354e2a63909bda1fb5b787b47a4d46ca13714a97d68

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [0.7.0] - 2026-09-08
+
+- Experimental elastic worker pool. Set `max_workers` above `workers`
+  and the pool grows under load, one worker at a time, then shrinks
+  back to `workers` once the extra workers have sat idle for
+  `scale_down_after` seconds (default 30). Works in both modes; a
+  retiring worker finishes its request first. `stats`, `/stats` and
+  `/metrics` gain `max_workers`, `active_workers`, `scale_ups` and
+  `scale_downs`, and each `worker_status` row gains `retired`. Leave
+  `max_workers` unset and the pool is fixed, as before.
+- Ractor mode warns at boot when `max_workers` (or `workers`) exceeds
+  `RUBY_MAX_CPU` (default 8), Ruby's cap on how many ractors run Ruby
+  code at once. Set the variable to your worker count to lift it.
+- Ractor-readiness fixes, so external Ractor audits of Kino pass: the
+  env string caches root their strings through the lock-free pin slab
+  instead of per-value GC registration (unsynchronized across ractors
+  in Ruby 4.0, a crash) and no longer call into Ruby while locked (a
+  GC-barrier deadlock); the shared rack.errors and rack.input
+  singletons must be Ractor-shareable, not just frozen; the Rack
+  handler's option table is shareable. Throughput is unchanged.
+
 ## [0.6.0] - 2026-09-01
 
 - HTTP/2 support. Kino now speaks HTTP/2 natively, on by default:

data/README.md

@@ -259,6 +259,8 @@ server = Kino::Server.new(app,
   bind: "127.0.0.1",          # or "unix:///run/kino.sock" behind a proxy
   port: 9292,                 # 0 = ephemeral; read back via server.port
   workers: Kino.available_parallelism, # ractors (parallelism); the default
+  max_workers: nil,           # experimental: grow past workers under load (see Elastic pool)
+  scale_down_after: 30,       # seconds idle before an extra worker retires
   threads: 1,                 # per worker; ractor default 1, threaded default 3
   mode: :auto,                # :auto | :ractor | :threaded
   queue_depth: 1024,          # bounded queue; overflow → 503
@@ -418,6 +420,56 @@ Kino fires four lifecycle hooks alongside `on_error`, split by firing context.
 
 A raising hook is logged and never kills a worker.
 
+## Elastic pool (experimental)
+
+Size the pool for the quiet hours and let it grow for the busy ones:
+
+```ruby
+# kino.rb
+workers 4            # always running
+max_workers 16       # reached only under load
+scale_down_after 30  # seconds idle before an extra worker retires
+```
+
+Or `Kino::Server.new(app, workers: 4, max_workers: 16)`. Leave
+`max_workers` unset and the pool is fixed at `workers`, as before.
+
+While requests wait in the queue, Kino adds a worker every 100 ms until
+the queue clears or the pool hits `max_workers`. When the load passes,
+workers above `workers` retire one at a time after `scale_down_after`
+seconds idle, each finishing its current request first. Same behavior
+in `:ractor` and `:threaded` mode.
+
+**Use it when your app waits**: on databases, upstream services, slow
+clients. With `workers` at your core count, all workers can be blocked
+on I/O while cores sit idle; a higher ceiling puts those cores to work,
+and a ractor starts in microseconds, so the pool follows load closely.
+Pure CPU work gains nothing past the core count. In `:ractor` mode Ruby
+itself runs at most `RUBY_MAX_CPU` ractors' Ruby code at once (default
+8), and Kino warns at boot when the pool can exceed it. On a bigger box:
+
+```sh
+RUBY_MAX_CPU=16 kino
+```
+
+**Watch it breathe** in `server.stats`, `GET /stats` and `GET /metrics`:
+
+```sh
+$ curl -s localhost:9293/stats | jq '{workers, max_workers, active_workers, scale_ups, scale_downs}'
+{
+  "workers": 4,
+  "max_workers": 16,
+  "active_workers": 9,
+  "scale_ups": 12,
+  "scale_downs": 7
+}
+```
+
+Prometheus gets `kino_max_workers`, `kino_active_workers`,
+`kino_scale_ups_total` and `kino_scale_downs_total`. `after_worker_boot`
+fires for every worker the pool adds, `on_worker_exit` (with a nil
+cause) for every one it retires.
+
 ## Stuck-worker quarantine
 
 `quarantine_timeout: seconds` (or `quarantine_timeout 60` in `kino.rb`)

data/doc/architecture.md

@@ -31,6 +31,16 @@ Puma-style two-level: `workers × threads`.
 - Identical machinery either way: the flume queue is MPMC, a "worker slot"
   is per-thread, and the worker loop (`lib/kino/worker.rb`) is shared
   verbatim.
+- Elastic pool (`max_workers`): a scaler thread on the main ractor
+  samples queue depth and the per-slot sensors every 100 ms, adds one
+  worker per sample while requests wait, and retires the longest-idle
+  worker above the floor after `scale_down_after`. Retirement is a
+  per-slot flag raised under the slot's lane lock: the lane dispatcher
+  skips the slot, the take loop honors the flag at its next idle tick (a
+  request already taken finishes first, a lane worker drains its own
+  lane), and the slot is reset and reused by the next worker, so the
+  slot table never grows with churn. Both pools (the ractor supervisor
+  and the threaded pool) expose the same grow/retire/groups seam.
 - Experimental `lanes true` replaces the one shared queue with a small
   private queue per worker slot (awake-preferring dispatch, work
   stealing); see [benchmarks](benchmarks.md#lane-dispatch-experimental-lanes-true).

data/lib/kino/cli.rb

@@ -127,7 +127,7 @@ module Kino
       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("- mode:      #{server.mode}, #{workers_label(stats)} × #{count(stats[:threads], "thread")}")
       puts dim("- pid:       #{Process.pid}")
       puts dim("- listening: #{server.url}")
       puts dim("- control:   #{server.control_url}") if server.control_url
@@ -140,6 +140,14 @@ module Kino
       "#{number} #{noun}#{"s" unless number == 1}"
     end
 
+    # The pool as configured: "8 workers", or "8-32 workers" when it can
+    # grow.
+    def workers_label(stats)
+      return count(stats[:workers], "worker") if stats[:max_workers] == stats[:workers]
+
+      "#{stats[:workers]}-#{stats[:max_workers]} workers"
+    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]
@@ -234,7 +242,7 @@ module Kino
     end
 
     def write_sample(path)
-      require "kino"
+      require "kino" # audition:disable runtime-require
       Configuration.write_sample(path)
       puts "Kino: wrote sample config to #{path}"
       0
@@ -245,8 +253,8 @@ module Kino
 
     # Resolve the full configuration once: file + CLI flag overrides.
     def resolve_config(options)
-      require "kino"
-      require "rack"
+      require "kino" # audition:disable runtime-require
+      require "rack" # audition:disable runtime-require
 
       config_file = options[:config_file] || Configuration.default_path
 

data/lib/kino/configuration.rb

@@ -10,6 +10,8 @@ module Kino
       bind: "127.0.0.1",
       port: 0,
       workers: nil, # resolved to Kino.available_parallelism in #to_h
+      max_workers: nil, # nil = fixed pool; above workers = elastic pool
+      scale_down_after: nil, # resolved to 30 seconds in Server
       threads: nil, # resolved per mode in Server: 1 in :ractor, 3 in :threaded
       mode: :auto,
       queue_depth: 1024,
@@ -44,7 +46,7 @@ module Kino
     SETTINGS = DEFAULTS.keys.freeze
 
     # Source template for {.sample}.
-    SAMPLE_TEMPLATE = File.expand_path("templates/kino.rb.tt", __dir__)
+    SAMPLE_TEMPLATE = File.expand_path("templates/kino.rb.tt", __dir__).freeze
 
     # 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/.
@@ -146,6 +148,8 @@ module Kino
     #   bind "0.0.0.0"
     #   port 9292
     #   workers 8           # ractors (or thread groups in :threaded mode)
+    #   max_workers 32      # elastic pool ceiling; unset = fixed pool
+    #   scale_down_after 30 # seconds idle before an extra worker retires
     #   threads 3           # threads per worker
     #   mode :ractor        # :auto | :ractor | :threaded
     #   queue_depth 2048
@@ -172,9 +176,19 @@ module Kino
       # Port to listen on; 0 picks an ephemeral port.
       def port(port) = @config.set(:port, Integer(port))
 
-      # Worker count (ractors in :ractor mode); defaults to CPU cores.
+      # Worker count (ractors in :ractor mode); defaults to CPU cores. The
+      # pool floor when max_workers is set.
       def workers(count) = @config.set(:workers, Integer(count))
 
+      # Pool ceiling: under sustained queue pressure the pool grows past
+      # `workers`, one worker at a time, up to this many. Unset (the
+      # default) keeps the pool fixed at `workers`.
+      def max_workers(count) = @config.set(:max_workers, Integer(count))
+
+      # Seconds a worker above the floor must sit idle before it is
+      # retired (default 30). Only meaningful with max_workers.
+      def scale_down_after(seconds) = @config.set(:scale_down_after, seconds)
+
       # Threads per worker (I/O concurrency inside one ractor); default is
       # mode-dependent: 1 in :ractor mode, 3 in :threaded.
       def threads(count) = @config.set(:threads, Integer(count))

data/lib/kino/monitor.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Kino
+  # @private
+  # A thread on the main ractor that calls `scan` every `tick` seconds
+  # until stopped. Main-ractor so it stays responsive when worker ractors
+  # are wedged. A scan that raises is logged and skipped, never fatal:
+  # monitors keep the server healthy, they must not take it down.
+  class Monitor
+    def initialize(name:, tick:)
+      @name = name
+      @tick = tick
+      @running = false
+      @thread = nil
+    end
+
+    def start
+      @running = true
+      @thread = Thread.new do
+        Thread.current.name = @name
+        run
+      end
+      self
+    end
+
+    def stop
+      @running = false
+      @thread&.join(@tick * 2)
+    end
+
+    private
+
+    def run
+      tick while @running
+    rescue => e
+      Log.error("#{@name} crashed: #{e.class}: #{e.message}")
+    end
+
+    def tick
+      scan
+    rescue => e
+      Log.error("#{@name} tick error: #{e.class}: #{e.message}")
+    ensure
+      sleep @tick
+    end
+
+    # One poll; subclasses define it.
+    def scan
+      raise NotImplementedError, "#{self.class} must define scan"
+    end
+  end
+end

data/lib/kino/pool_scaler.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Kino
+  # @private
+  # Grows and shrinks the worker pool between `floor` and `ceiling`. One
+  # thread on the main ractor polls the native queue and per-slot sensors
+  # every tick and drives a pool (RactorSupervisor or ThreadedPool) through
+  # three methods: `active_count`, `groups` (worker index => slot ids for
+  # every worker that may be retired), `grow`, and `retire(index)`.
+  #
+  # Policy: grow by one worker per tick once requests have been waiting in
+  # the queue on two consecutive ticks (a burst that clears within a tick
+  # is not pressure); retire one worker per tick, the one idle longest,
+  # once it has been idle for `scale_down_after`. "Idle" means no slot of
+  # the worker held a request at two consecutive samples and its served
+  # count did not move between them, so a worker serving short requests
+  # between samples is never mistaken for an idle one.
+  class PoolScaler < Monitor
+    TICK = 0.1
+    # Consecutive ticks with a non-empty queue before the pool grows.
+    PRESSURE_TICKS = 2
+
+    def initialize(server_id:, pool:, floor:, ceiling:, scale_down_after:, tick: TICK)
+      super(name: "pool scaler", tick: tick)
+      @server_id = server_id
+      @pool = pool
+      @floor = floor
+      @ceiling = ceiling
+      @scale_down_after = scale_down_after
+      @pressure = 0
+      @last_served = {}
+      @idle_since = {}
+    end
+
+    # One policy step over one set of observations: the monotonic time,
+    # the queue depth, and worker_stats rows ([slot, served, in_flight,
+    # busy_ms, quarantined, retired]). Public so the policy is testable
+    # without a server.
+    def step(now, queued, rows)
+      @pressure = queued.positive? ? @pressure + 1 : 0
+      if @pressure >= PRESSURE_TICKS
+        grow if @pool.active_count < @ceiling
+        return
+      end
+
+      observe_idle(now, rows)
+      return unless @pool.active_count > @floor
+
+      index, since = @idle_since.min_by { |_index, at| at }
+      return unless index && now - since >= @scale_down_after
+
+      retire(index)
+    end
+
+    private
+
+    def scan
+      queued, _in_flight = Native.queue_stats(@server_id)
+      step(Process.clock_gettime(Process::CLOCK_MONOTONIC), queued, Native.worker_stats(@server_id))
+    end
+
+    def grow
+      index = @pool.grow
+      return unless index
+
+      Native.record_scale_up(@server_id)
+      Log.info("pool grew to #{@pool.active_count} workers (queue pressure)")
+    end
+
+    def retire(index)
+      return unless @pool.retire(index)
+
+      forget(index)
+      Native.record_scale_down(@server_id)
+      Log.info("pool shrank to #{@pool.active_count} workers (worker-#{index} idle)")
+    end
+
+    # Per worker: idle when no slot holds a request at this sample and the
+    # served total did not move since the previous one. First sighting of
+    # a worker is never idle (it takes two samples to know).
+    def observe_idle(now, rows)
+      by_slot = rows.to_h { |row| [row[0], row] }
+      groups = @pool.groups
+      (@idle_since.keys - groups.keys).each { |index| forget(index) }
+      groups.each do |index, slot_ids|
+        served = slot_ids.sum { |id| by_slot.dig(id, 1) || 0 }
+        busy = slot_ids.any? { |id| (by_slot.dig(id, 2) || 0).positive? }
+        idle = !busy && @last_served[index] == served
+        @last_served[index] = served
+        if idle
+          @idle_since[index] ||= now
+        else
+          @idle_since.delete(index)
+        end
+      end
+    end
+
+    def forget(index)
+      @idle_since.delete(index)
+      @last_served.delete(index)
+    end
+  end
+end

data/lib/kino/quarantine_monitor.rb

@@ -3,54 +3,22 @@
 module Kino
   # @private
   # Polls per-slot busy_ms and, past the timeout, quarantines a wedged slot
-  # and asks the replacer to spawn a fresh worker. Runs one thread on the
-  # main ractor (uncontended by wedged worker ractors, so it stays
-  # responsive in :ractor mode). Never interrupts the wedged worker.
-  class QuarantineMonitor
+  # and asks the replacer to spawn a fresh worker. Never interrupts the
+  # wedged worker.
+  class QuarantineMonitor < Monitor
     def initialize(server_id:, timeout_ms:, max:, replacer:, tick: 0.5)
+      super(name: "quarantine monitor", tick: tick)
       @server_id = server_id
       @timeout_ms = timeout_ms
       @max = max
       @replacer = replacer
-      @tick = tick
       @outstanding = 0
       @at_cap_logged = false
-      @running = false
-      @thread = nil
-    end
-
-    def start
-      @running = true
-      @thread = Thread.new do
-        Thread.current.name = "quarantine"
-        run
-      end
-      self
-    end
-
-    def stop
-      @running = false
-      @thread&.join(@tick * 2)
     end
 
     private
 
-    def run
-      tick while @running
-    rescue => e
-      Log.error("quarantine monitor crashed: #{e.class}: #{e.message}")
-    end
-
-    def tick
-      scan_slots
-    rescue => e
-      # A bad tick must never kill the monitor.
-      Log.error("quarantine tick error: #{e.class}: #{e.message}")
-    ensure
-      sleep @tick
-    end
-
-    def scan_slots
+    def scan
       Native.worker_stats(@server_id).each do |index, _served, _in_flight, busy_ms, quarantined|
         next if quarantined || busy_ms <= @timeout_ms
 

data/lib/kino/ractor_supervisor.rb

@@ -5,7 +5,12 @@ module Kino
   # Spawns worker ractors and keeps them alive. One supervisor thread per
   # ractor: it blocks in Ractor#value, and a crash (anything that kills the
   # ractor, Exception from app code included) wakes it to 500 the in-flight
-  # requests and respawn. Clean exits (queue drained) end supervision.
+  # requests and respawn. Clean exits (queue drained at shutdown, or the
+  # worker retired by the pool scaler) end supervision.
+  #
+  # Also the :ractor-mode pool behind PoolScaler: `grow` adds a worker,
+  # `retire` sends one home, `groups` lists the ones that may be retired,
+  # and `active_count` is what the control plane reports.
   class RactorSupervisor
     def initialize(server_id, app, workers:, threads:, batch: 1, hooks: nil, on_worker_exit: nil)
       @server_id = server_id
@@ -21,6 +26,12 @@ module Kino
       @worker_slots = {}
       @slot_to_worker = {}
       @replaced = {}
+      # Worker index => true while its ractor runs, and => true once the
+      # scaler asked it to leave. Retired workers hand their slots back to
+      # the bank for the next worker to take over.
+      @live = {}
+      @retiring = {}
+      @bank = SlotBank.new(server_id)
       # The first replacement's index; `replace` increments before using it,
       # so this starts one below the first free index (@workers).
       @next_worker_index = @workers - 1
@@ -28,6 +39,7 @@ module Kino
 
     def start
       @supervisor_threads = Array.new(@workers) { |index| supervise(index) }
+      report_active
       self
     end
 
@@ -52,6 +64,61 @@ module Kino
       @lock.synchronize { @supervisor_threads.dup }.each(&:join)
     end
 
+    # Ractors cannot be force-killed; their clients were already freed by
+    # abort_all_inflight. A stuck ractor leaks until process exit.
+    def kill_stragglers
+      Log.error("shutdown deadline passed with stuck ractor workers") unless done?
+    end
+
+    # Workers that are staying: the live ones minus those the quarantine
+    # monitor abandoned as wedged (their replacements count instead) and
+    # minus those already told to leave. A retiring worker leaves the
+    # count at once, not when its ractor finally exits, so the scaler
+    # never sees a stale surplus and retires past its floor.
+    def active_count
+      @lock.synchronize do
+        @live.count { |index, _| !@replaced.key?(index) && !@retiring.key?(index) }
+      end
+    end
+
+    # Worker index => slot ids for every worker the scaler may retire:
+    # live, not already leaving, not quarantined, and past its spawn (a
+    # worker marked live whose supervisor thread has not assigned slots
+    # yet is not listed until it has).
+    def groups
+      @lock.synchronize do
+        @live.keys
+          .reject { |index| @retiring.key?(index) || @replaced.key?(index) || !@worker_slots.key?(index) }
+          .to_h { |index| [index, @worker_slots[index].dup] }
+      end
+    end
+
+    # Add one supervised worker; returns its index.
+    def grow
+      new_index = @lock.synchronize { @next_worker_index += 1 }
+      thread = supervise(new_index)
+      @lock.synchronize { @supervisor_threads << thread }
+      report_active
+      new_index
+    end
+
+    # Send a worker home. Its slots stop receiving work now; the worker
+    # finishes what it holds, leaves at its next idle tick, and its slots
+    # come back to the free list once the ractor has exited. Returns
+    # false when there is no such live worker to retire.
+    def retire(worker_index)
+      slot_ids = @lock.synchronize do
+        next nil unless @live.key?(worker_index) && !@retiring.key?(worker_index)
+
+        @retiring[worker_index] = true
+        @worker_slots[worker_index]
+      end
+      return false unless slot_ids
+
+      slot_ids.each { |id| Native.retire_slot(@server_id, id) }
+      true
+    end
+
     # Replace the ractor owning slot `worker_id`: spawn a fresh supervised
     # ractor, then quarantine the old ractor's slots. The old supervisor
     # thread stays blocked in ractor.value on the wedged ractor (it and the
@@ -90,6 +157,9 @@ module Kino
     private
 
     def supervise(index)
+      # Live from the moment it is asked for, not from when its thread gets
+      # around to spawning: `grow` reports the count right after this.
+      @lock.synchronize { @live[index] = true }
       Thread.new do
         Thread.current.name = "supervisor-#{index}"
         crashes = 0
@@ -97,8 +167,9 @@ module Kino
           ractor, worker_ids = spawn_worker(index)
           begin
             ractor.value # blocks until the ractor terminates
-            HookFire.fire(@on_worker_exit, "on_worker_exit", index, nil) # clean exit: queue drained
-            break        # clean exit: queue closed, workers drained
+            HookFire.fire(@on_worker_exit, "on_worker_exit", index, nil) # clean exit: drained or retired
+            exited(index, worker_ids)
+            break
           rescue Ractor::Error => e
             # The ractor died mid-flight. Anything it was serving will never
             # be answered by Ruby: 500 those clients NOW (not when GC gets
@@ -106,11 +177,17 @@ module Kino
             worker_ids.each { |id| Native.abort_inflight(@server_id, id) }
             cause = (e.respond_to?(:cause) && e.cause) ? e.cause : e
             HookFire.fire(@on_worker_exit, "on_worker_exit", index, cause)
-            break if draining?
+            if draining?
+              exited(index, nil)
+              break
+            end
 
             crashes += 1
             Native.record_respawn(@server_id)
             Log.error("worker-#{index} crashed (#{cause.class}: #{cause.message}); respawning")
+            # A crashed worker that was on its way out respawns on fresh
+            # slots like any other; the scaler retires it again when idle.
+            @lock.synchronize { @retiring.delete(index) }
             # 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
@@ -121,11 +198,10 @@ module Kino
       end
     end
 
-    # Fresh ractor + fresh native slots. Slots are never reused across
-    # respawns: stale interrupt kicks and dead weak refs go down with the
-    # old slot.
+    # Fresh ractor on slots from the bank: fresh ones, or ones a retired
+    # worker handed back.
     def spawn_worker(worker_index)
-      worker_ids = Array.new(@threads) { Native.register_worker(@server_id) }
+      worker_ids = Array.new(@threads) { @bank.claim }
       @lock.synchronize do
         @worker_slots[worker_index] = worker_ids
         worker_ids.each { |id| @slot_to_worker[id] = worker_index }
@@ -147,6 +223,24 @@ module Kino
       [ractor, worker_ids]
     end
 
+    # Bookkeeping for a supervisor thread that is done: the worker is no
+    # longer live, a retired worker's slots go back to the bank, and the
+    # thread leaves the join set so a long-lived elastic pool does not
+    # accumulate dead threads.
+    def exited(index, worker_ids)
+      retired = @lock.synchronize do
+        @live.delete(index)
+        @supervisor_threads.delete(Thread.current)
+        @retiring.delete(index)
+      end
+      @bank.release(worker_ids) if retired && worker_ids
+      report_active
+    end
+
+    def report_active
+      Native.set_active_workers(@server_id, active_count)
+    end
+
     def draining?
       @lock.synchronize { @draining }
     end

data/lib/kino/server.rb

@@ -68,6 +68,16 @@ module Kino
       @bind = settings[:bind]
       @requested_port = settings[:port]
       @workers = Integer(settings[:workers])
+      # The pool ceiling; equal to the floor for a fixed pool.
+      @max_workers = settings[:max_workers].nil? ? @workers : Integer(settings[:max_workers])
+      if @max_workers < @workers
+        raise ArgumentError, "max_workers (#{@max_workers}) must be at least workers (#{@workers})"
+      end
+      @scale_down_after = settings[:scale_down_after].nil? ? 30.0 : Float(settings[:scale_down_after])
+      raise ArgumentError, "scale_down_after must be positive" unless @scale_down_after.positive?
+      if !settings[:scale_down_after].nil? && !elastic?
+        Log.warn("scale_down_after has no effect unless max_workers is above workers")
+      end
       @on_error = validate_hook(settings[:on_error], :on_error)
       @after_worker_boot = validate_hook(settings[:after_worker_boot], :after_worker_boot)
       @after_request_complete = validate_hook(settings[:after_request_complete], :after_request_complete)
@@ -81,8 +91,9 @@ module Kino
         # 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)
+        # mode, and a single ractor (a pool that can never grow past one)
+        # has nothing to race.
+        access_timing: !!settings[:log_requests] && (@mode == :threaded || @max_workers == 1)
       )
       # Default threads per mode: 1 in :ractor (threads inside a ractor
       # share its lock; a measured +17% on fast handlers; raise `workers`
@@ -126,10 +137,10 @@ module Kino
         else
           @workers * @threads
         end
-      @worker_threads = []
-      @worker_threads_lock = Mutex.new
       @supervisor = nil
+      @threaded_pool = nil
       @quarantine_monitor = nil
+      @pool_scaler = nil
       @started = false
     end
 
@@ -158,7 +169,8 @@ module Kino
           tls_cert: @tls&.fetch(:cert), tls_key: @tls&.fetch(:key),
           http2: @http2,
           lanes: @lanes, log_requests: @log_requests,
-          mode: @mode.to_s, workers: @workers, threads: @threads, batch: @batch,
+          mode: @mode.to_s, workers: @workers, max_workers: @max_workers,
+          threads: @threads, batch: @batch,
           control_bind: @control_bind, control_token: @control_token
         )
         booted = true
@@ -169,12 +181,15 @@ module Kino
       # lifetime so in-flight buffers survive even a worker ractor crash.
       @pin_keeper = Native.pin_keeper(@id)
       if @mode == :ractor
+        warn_scheduler_cap
         @supervisor = RactorSupervisor.new(@id, @app, workers: @workers, threads: @threads,
           batch: @batch, hooks: @worker_hooks, on_worker_exit: @on_worker_exit).start
       else
-        @worker_threads = (@workers * @threads).times.map { spawn_worker_thread }
+        @threaded_pool = ThreadedPool.new(@id, @app, threads: @threads, batch: @batch,
+          hooks: @worker_hooks, on_worker_exit: @on_worker_exit).start(@workers)
       end
       start_quarantine_monitor if @quarantine_timeout_ms
+      start_pool_scaler if elastic?
       Native.control_ready(@id)
       HookFire.fire(@after_boot, "after_boot")
       @started = true
@@ -192,6 +207,7 @@ module Kino
     def shutdown(timeout: nil)
       return unless @started
 
+      @pool_scaler&.stop
       @quarantine_monitor&.stop
       deadline = monotonic_now + (timeout || @shutdown_timeout)
       Native.stop_accepting(@id)
@@ -224,7 +240,6 @@ module Kino
       # 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
       remove_pidfile if @pidfile
       nil
@@ -233,7 +248,7 @@ module Kino
     # Block until every worker has exited (i.e. until shutdown).
     # @return [void]
     def wait
-      @supervisor ? @supervisor.join : @worker_threads.each(&:join)
+      pool.join
     end
 
     # Production entry point: build the server and {#run} it. The `kino`
@@ -298,19 +313,22 @@ module Kino
     #   lanes mode) once started
     def stats
       base = {
-        mode: @mode, lanes: @lanes, workers: @workers, threads: @threads,
-        batch: @batch, respawns: 0
+        mode: @mode, lanes: @lanes, workers: @workers, max_workers: @max_workers,
+        threads: @threads, batch: @batch, respawns: 0,
+        active_workers: @workers, scale_ups: 0, scale_downs: 0
       }
       return base unless @started
 
       queued, in_flight, served, rejected, timeouts, respawns, lane_depths = Native.server_stats(@id)
       base.merge!(queued:, in_flight:, served:, rejected:, timeouts:, respawns:)
       base[:lane_depths] = lane_depths if lane_depths
+      active_workers, _max_workers, scale_ups, scale_downs = Native.pool_stats(@id)
+      base.merge!(active_workers:, scale_ups:, scale_downs:)
       rows = Native.worker_stats(@id)
-      base[:worker_status] = rows.map do |index, served, in_flight, busy_ms, quarantined|
-        {index:, served:, in_flight:, busy_ms:, quarantined:}
+      base[:worker_status] = rows.map do |index, served, in_flight, busy_ms, quarantined, retired|
+        {index:, served:, in_flight:, busy_ms:, quarantined:, retired:}
       end
-      base[:quarantined] = rows.count { |_index, _served, _in_flight, _busy_ms, quarantined| quarantined }
+      base[:quarantined] = rows.count { |row| row[4] }
       count, sum_seconds = Native.queue_time(@id)
       base[:queue_time] = {count:, sum_seconds:}
       base
@@ -318,63 +336,38 @@ module Kino
 
     private
 
-    # Register a fresh dispatch slot and run a worker thread on it; returns
-    # the thread. Used at boot and by the quarantine replacer.
-    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)
-        rescue Exception => e # rubocop:disable Lint/RescueException -- a hard crash in a threaded worker thread
-          error = e
-          raise
-        ensure
-          HookFire.fire(@on_worker_exit, "on_worker_exit", worker_id, error)
-        end
-      end
+    # The worker pool this mode runs: the ractor supervisor, or the
+    # threaded pool. Both spawn, retire, replace and join workers behind
+    # the same methods.
+    def pool
+      @supervisor || @threaded_pool
     end
 
-    # Track a replacement thread spawned outside the initial pool assignment
-    # (the quarantine replacer) so shutdown's join/done?/kill sweeps see it.
-    def track_replacement_thread(thread)
-      @worker_threads_lock.synchronize { @worker_threads << thread }
+    # Both pools are quarantine replacers: replace(worker_id) spawns a
+    # replacement worker, then quarantines the wedged slot.
+    def start_quarantine_monitor
+      @quarantine_monitor = QuarantineMonitor.new(
+        server_id: @id, timeout_ms: @quarantine_timeout_ms,
+        max: @quarantine_max, replacer: pool
+      ).start
     end
 
-    # @private
-    # The :threaded-mode quarantine replacer: spawns a replacement worker
-    # thread, quarantines the wedged slot, then tracks the new thread so
-    # shutdown's join/done?/kill sweeps see it. Built from bound Method
-    # objects instead of a server reference, so it drives the server
-    # through those methods without send or instance_variable_get.
-    class ThreadedReplacer
-      def initialize(server_id:, spawner:, tracker:)
-        @server_id = server_id
-        @spawner = spawner
-        @tracker = tracker
-      end
+    # Ruby's M:N scheduler runs non-main ractors' Ruby code on at most
+    # RUBY_MAX_CPU native threads (default 8). Workers past that cap share
+    # timeslices instead of adding parallelism, and a fresh ractor can wait
+    # seconds for its first one while the others are CPU-bound.
+    def warn_scheduler_cap
+      cap = Integer(ENV.fetch("RUBY_MAX_CPU", "8"), exception: false) || 8
+      return if @max_workers <= cap
 
-      def replace(worker_id)
-        thread = @spawner.call # spawn FIRST (may raise ThreadError)
-        Native.quarantine_slot(@server_id, worker_id) # quarantine after success
-        @tracker.call(thread)
-        true
-      end
+      Log.warn("#{@max_workers} ractor workers exceed RUBY_MAX_CPU=#{cap}: only #{cap} can run " \
+        "Ruby code at once; set RUBY_MAX_CPU=#{@max_workers} for CPU-bound apps")
     end
-    private_constant :ThreadedReplacer
 
-    # A replacer.replace(worker_id) spawns a replacement worker, then
-    # quarantines the wedged slot, mode-appropriately. In :ractor the
-    # supervisor is the replacer; in :threaded a small object over
-    # spawn_worker_thread.
-    def start_quarantine_monitor
-      replacer = @supervisor || ThreadedReplacer.new(server_id: @id, spawner: method(:spawn_worker_thread),
-        tracker: method(:track_replacement_thread))
-      @quarantine_monitor = QuarantineMonitor.new(
-        server_id: @id, timeout_ms: @quarantine_timeout_ms,
-        max: @quarantine_max, replacer: replacer
+    def start_pool_scaler
+      @pool_scaler = PoolScaler.new(
+        server_id: @id, pool: pool, floor: @workers, ceiling: @max_workers,
+        scale_down_after: @scale_down_after
       ).start
     end
 
@@ -400,6 +393,11 @@ module Kino
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
+    # A pool that can grow: the ceiling is above the floor.
+    def elastic?
+      @max_workers > @workers
+    end
+
     # Default connection cap: most of the process open-file limit. A
     # connection flood's failure mode is descriptor exhaustion, and in
     # :ractor/:threaded mode the app's own sockets and files share this
@@ -474,34 +472,15 @@ module Kino
     end
 
     def join_workers(deadline)
-      if @supervisor
-        @supervisor.shutdown([deadline - monotonic_now, 0].max)
-      else
-        threads = @worker_threads_lock.synchronize { @worker_threads.dup }
-        threads.each do |thread|
-          thread.join([deadline - monotonic_now, 0.01].max)
-        end
-      end
+      pool.shutdown([deadline - monotonic_now, 0].max)
     end
 
     def workers_done?
-      if @supervisor
-        @supervisor.done?
-      else
-        threads = @worker_threads_lock.synchronize { @worker_threads.dup }
-        threads.none?(&:alive?)
-      end
+      pool.done?
     end
 
     def kill_stragglers
-      if @supervisor
-        # Ractors cannot be force-killed; their clients were already freed
-        # by abort_all_inflight. The stuck ractor leaks until process exit.
-        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? }
-      end
+      pool.kill_stragglers
     end
 
     # Policy (mode resolution): when is an app safe for ractor

data/lib/kino/slot_bank.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Kino
+  # @private
+  # Dispatch slots for a worker pool: fresh ones from the native registry,
+  # or ones that retired workers handed back, reset for their next
+  # occupant. The native side never removes a slot, so recycling is what
+  # keeps the slot table from growing as an elastic pool breathes. Only
+  # cleanly exited workers return slots; a crashed worker's slots are
+  # abandoned (stale interrupt kicks and dead weak refs go down with
+  # them).
+  class SlotBank
+    def initialize(server_id)
+      @server_id = server_id
+      @free = []
+      @lock = Mutex.new
+    end
+
+    def claim
+      id = @lock.synchronize { @free.pop }
+      return Native.register_worker(@server_id) unless id
+
+      Native.reset_slot(@server_id, id)
+      id
+    end
+
+    def release(ids)
+      @lock.synchronize { @free.concat(ids) }
+    end
+  end
+end

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

@@ -40,6 +40,21 @@
 # `workers` instead.
 # threads 1
 
+## Elastic pool (experimental)
+#
+# Let the pool grow past `workers` under load and shrink back when
+# idle: one worker is added every 100 ms while requests wait in the
+# queue, and a worker above `workers` retires after `scale_down_after`
+# seconds idle. Helps apps that wait on databases or other services;
+# pure CPU work gains nothing past the core count. Unset (the default)
+# keeps the pool fixed. In :ractor mode, Ruby runs at most RUBY_MAX_CPU
+# (default 8) ractors' Ruby code at once; set that variable to match
+# `max_workers` on bigger boxes.
+# max_workers 32
+
+# Seconds an extra worker must sit idle before it is retired.
+# scale_down_after 30
+
 ## Dispatch mode
 #
 # :auto     - picks :ractor when your app supports it, else :threaded.

data/lib/kino/threaded_pool.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Kino
+  # @private
+  # The :threaded-mode worker pool: `workers` groups of `threads` plain
+  # Threads, each thread on its own dispatch slot. A group is one ractor's
+  # worth of capacity, so `workers` and `max_workers` mean the same thing
+  # in both modes. Behind PoolScaler here (`grow`, `retire`, `groups`,
+  # `active_count`), the quarantine monitor's replacer (`replace`), and
+  # the join/kill sweeps Server#shutdown runs.
+  class ThreadedPool
+    def initialize(server_id, app, threads:, batch: 1, hooks: nil, on_worker_exit: nil)
+      @server_id = server_id
+      @app = app
+      @threads = threads
+      @batch = batch
+      @hooks = hooks
+      @on_worker_exit = on_worker_exit
+      @lock = Mutex.new
+      # index => {slots:, threads:}; the groups asked to leave; quarantine
+      # replacements (one thread each, standing in for a wedged slot:
+      # neither counted nor retired, so the wedged group keeps counting as
+      # the capacity it still is). Retired groups hand their slots back to
+      # the bank.
+      @groups = {}
+      @slot_to_group = {}
+      @retiring = {}
+      @bank = SlotBank.new(server_id)
+      @replacements = {}
+      @wedged = {}
+      @next_index = -1
+    end
+
+    def start(workers)
+      workers.times { spawn_group }
+      report_active
+      self
+    end
+
+    # Groups that are staying: quarantine replacements aside, and minus
+    # those already told to leave. A retiring group leaves the count at
+    # once, not when its last thread exits, so the scaler never sees a
+    # stale surplus and retires past its floor.
+    def active_count
+      @lock.synchronize do
+        @groups.count { |index, _| !@replacements.key?(index) && !@retiring.key?(index) }
+      end
+    end
+
+    # Group index => slot ids for every group the scaler may retire: not
+    # already leaving, not wedged, not a quarantine replacement.
+    def groups
+      reap
+      @lock.synchronize do
+        @groups
+          .reject { |index, _| @retiring.key?(index) || @wedged.key?(index) || @replacements.key?(index) }
+          .transform_values { |group| group[:slots].dup }
+      end
+    end
+
+    # Add one group; returns its index.
+    def grow
+      reap
+      index = spawn_group
+      report_active
+      index
+    end
+
+    # Send a group home: its slots stop receiving work now, each thread
+    # finishes what it holds and leaves at its next idle tick, and the
+    # slots come back to the free list once every thread has exited.
+    def retire(index)
+      slots = @lock.synchronize do
+        next nil unless @groups.key?(index) && !@retiring.key?(index)
+
+        @retiring[index] = true
+        @groups[index][:slots]
+      end
+      return false unless slots
+
+      slots.each { |id| Native.retire_slot(@server_id, id) }
+      true
+    end
+
+    # The quarantine replacer: spawn a replacement thread on a fresh slot
+    # FIRST (may raise ThreadError), then quarantine the wedged slot.
+    def replace(worker_id)
+      spawn_group(slots: 1, replacement: true)
+      Native.quarantine_slot(@server_id, worker_id)
+      @lock.synchronize do
+        wedged = @slot_to_group[worker_id]
+        @wedged[wedged] = true if wedged
+      end
+      true
+    end
+
+    # Join every thread up to the (numeric) deadline.
+    def shutdown(timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      all_threads.each do |thread|
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        thread.join([remaining, 0.01].max)
+      end
+    end
+
+    def done?
+      all_threads.none?(&:alive?)
+    end
+
+    # Block until every thread exits on its own (drain elsewhere).
+    def join
+      all_threads.each(&:join)
+    end
+
+    def kill_stragglers
+      all_threads.each { |thread| thread.kill if thread.alive? }
+    end
+
+    private
+
+    def all_threads
+      @lock.synchronize { @groups.values.flat_map { |group| group[:threads] } }
+    end
+
+    # The group is in the table before its first thread starts, so a
+    # ThreadError partway through leaves nothing untracked for shutdown.
+    def spawn_group(slots: @threads, replacement: false)
+      group = {slots: [], threads: []}
+      index = @lock.synchronize do
+        @next_index += 1
+        @groups[@next_index] = group
+        @replacements[@next_index] = true if replacement
+        @next_index
+      end
+      slots.times do
+        id = @bank.claim
+        @lock.synchronize do
+          group[:slots] << id
+          @slot_to_group[id] = index
+        end
+        thread = spawn_thread(id)
+        @lock.synchronize { group[:threads] << thread }
+      end
+      index
+    end
+
+    def spawn_thread(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(@server_id, worker_id, @app, @batch, @hooks)
+        rescue Exception => e # rubocop:disable Lint/RescueException -- a hard crash in a threaded worker thread
+          error = e
+          raise
+        ensure
+          HookFire.fire(@on_worker_exit, "on_worker_exit", worker_id, error)
+        end
+      end
+    end
+
+    # Retiring groups whose threads have all exited give their slots back
+    # and leave the table. Runs before every pool decision, so the count
+    # the control plane sees never lags by more than a scaler tick.
+    def reap
+      freed = @lock.synchronize do
+        done = @retiring.keys.select { |index| @groups[index][:threads].none?(&:alive?) }
+        done.flat_map do |index|
+          group = @groups.delete(index)
+          @retiring.delete(index)
+          group[:slots].each { |id| @slot_to_group.delete(id) }
+          group[:slots]
+        end
+      end
+      return if freed.empty?
+
+      @bank.release(freed)
+      report_active
+    end
+
+    def report_active
+      Native.set_active_workers(@server_id, active_count)
+    end
+  end
+end

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.6.0"
+  VERSION = "0.7.0"
 end

data/lib/kino.rb

@@ -57,8 +57,12 @@ require_relative "kino/configuration"
 require_relative "kino/hook_fire"
 require_relative "kino/worker_hooks"
 require_relative "kino/worker"
+require_relative "kino/slot_bank"
 require_relative "kino/ractor_supervisor"
+require_relative "kino/threaded_pool"
+require_relative "kino/monitor"
 require_relative "kino/quarantine_monitor"
+require_relative "kino/pool_scaler"
 require_relative "kino/server"
 
 # Hand the frozen shareable singletons to the native layer: it sets them

data/lib/rackup/handler/kino.rb

@@ -9,13 +9,13 @@ module Rackup
     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 = {
+      OPTION_MAP = Ractor.make_shareable({
         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
@@ -27,7 +27,7 @@ module Rackup
       #   want a handle on it
       # @return [::Kino::Server] the stopped server, after shutdown
       def self.run(app, **options)
-        require "kino"
+        require "kino" # audition:disable runtime-require
         server = ::Kino::Server.new(app, **server_options(options))
         yield server if block_given?
         server.run
@@ -58,7 +58,7 @@ module Rackup
       # @param options [Hash{Symbol => Object}]
       # @return [Hash{Symbol => Object}]
       def self.server_options(options)
-        require "kino"
+        require "kino" # audition:disable runtime-require
         options = options.dup
         host_defaults = {}
         if (typed = options.delete(:user_supplied_options))

data/sig/kino.rbs

@@ -110,6 +110,8 @@ module Kino
       def bind: (String host) -> untyped
       def port: (int port) -> untyped
       def workers: (int count) -> untyped
+      def max_workers: (int count) -> untyped
+      def scale_down_after: (Numeric seconds) -> untyped
       def threads: (int count) -> untyped
       def mode: (Symbol | String mode) -> untyped
       def queue_depth: (int depth) -> untyped

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kino
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: aarch64-linux
 authors:
 - Yaroslav Markin
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-09-01 00:00:00.000000000 Z
+date: 2026-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -180,12 +180,16 @@ files:
 - lib/kino/kino.so
 - lib/kino/log.rb
 - lib/kino/logger.rb
+- lib/kino/monitor.rb
 - lib/kino/null_input.rb
+- lib/kino/pool_scaler.rb
 - lib/kino/quarantine_monitor.rb
 - lib/kino/ractor_supervisor.rb
 - lib/kino/server.rb
+- lib/kino/slot_bank.rb
 - lib/kino/stream.rb
 - lib/kino/templates/kino.rb.tt
+- lib/kino/threaded_pool.rb
 - lib/kino/version.rb
 - lib/kino/worker.rb
 - lib/kino/worker_hooks.rb