kino 0.3.0 → 0.4.0

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