kino 0.6.0 → 0.7.0

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