kino 0.1.0

data/lib/kino/server.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module Kino
+  # Public server API. All network I/O lives in Rust (tokio + hyper); this
+  # class only manages lifecycle and the Ruby worker pool.
+  #
+  # Topology is Puma-style two-level: `workers` ractors × `threads` threads
+  # per ractor in :ractor mode; the same total capacity flattened onto plain
+  # Threads in :threaded mode (which runs ANY Rack app, Rails included).
+  class Server
+    # @return [Integer, nil] the bound port (nil until #start; the actual
+    #   port when configured with port 0)
+    attr_reader :port
+
+    # @return [Symbol] the resolved dispatch mode, :ractor or :threaded
+    attr_reader :mode
+
+    # @return [String] the bind address
+    attr_reader :bind
+
+    # @return [Boolean] whether TLS termination is configured
+    def tls?
+      !@tls.nil?
+    end
+
+    # Settings precedence: explicit kwargs > config_file DSL > defaults.
+    #
+    # @param app [#call] a Rack 3 application
+    # @param config_file [String, nil] path to a kino.rb config file
+    # @param options [Hash] any {Kino::Configuration} setting, e.g. port:,
+    #   workers:, threads:, mode:, request_timeout:, tls: cert/key Hash
+    # @example
+    #   Kino::Server.new(app, config_file: "kino.rb", port: 3000)
+    def initialize(app, config_file: nil, **options)
+      config = Configuration.new
+      config.load_file(config_file) if config_file
+      config.merge!(options)
+      settings = config.to_h
+
+      @app = app
+      @bind = settings[:bind]
+      @requested_port = settings[:port]
+      @workers = Integer(settings[:workers])
+      @threads = Integer(settings[:threads])
+      @mode = resolve_mode(settings[:mode])
+      @queue_depth = Integer(settings[:queue_depth])
+      @queue_timeout_ms = (Float(settings[:queue_timeout]) * 1000).round
+      @request_timeout_ms = settings[:request_timeout] ? (Float(settings[:request_timeout]) * 1000).round : 0
+      @batch = [Integer(settings[:batch]), 1].max
+      @lanes = !!settings[:lanes]
+      @log_requests = !!settings[:log_requests]
+      @shutdown_timeout = settings[:shutdown_timeout]
+      @tokio_threads = settings[:tokio_threads]
+      @tls = validate_tls(settings[:tls])
+      @pidfile = settings[:pidfile]
+      @worker_threads = []
+      @supervisor = nil
+      @started = false
+    end
+
+    # Bind, boot the native front-end, and spawn the worker pool.
+    # @return [self]
+    # @raise [Kino::Error] when already started
+    # @raise [Kino::UnshareableAppError] in forced :ractor mode with an
+    #   unshareable app
+    def start
+      raise Error, "server already started" if @started
+
+      @id, @port = Native.server_start(
+        bind: @bind, port: @requested_port,
+        queue_depth: @queue_depth, queue_timeout_ms: @queue_timeout_ms,
+        request_timeout_ms: @request_timeout_ms,
+        tokio_threads: @tokio_threads,
+        tls_cert: @tls&.fetch(:cert), tls_key: @tls&.fetch(:key),
+        lanes: @lanes, log_requests: @log_requests
+      )
+      File.write(@pidfile, "#{Process.pid}\n") if @pidfile
+      if @mode == :ractor
+        @supervisor = RactorSupervisor.new(@id, @app, workers: @workers, threads: @threads, batch: @batch).start
+      else
+        @worker_threads = (@workers * @threads).times.map do
+          worker_id = Native.register_worker(@id)
+          Thread.new { Worker.run(@id, worker_id, @app, @batch) }
+        end
+      end
+      @started = true
+      self
+    end
+
+    # Graceful shutdown: stop accepting, drain in-flight work up to the
+    # deadline, then escalate: abort remaining clients (500), interrupt
+    # blocked workers, kill stragglers; and tear down the runtime. Always
+    # returns by ~deadline + a small epsilon; idempotent.
+    #
+    # @param timeout [Numeric, nil] drain deadline in seconds (default:
+    #   the configured shutdown_timeout)
+    # @return [nil]
+    def shutdown(timeout: nil)
+      return unless @started
+
+      deadline = monotonic_now + (timeout || @shutdown_timeout)
+      Native.stop_accepting(@id)
+
+      # Drain: wait for queued + in-flight to reach zero, bounded by deadline.
+      until monotonic_now >= deadline
+        queued, in_flight = Native.queue_stats(@id)
+        break if queued.zero? && in_flight.zero?
+
+        sleep 0.01
+      end
+
+      # Idle workers see the closed queue and exit their loops.
+      Native.close_queue(@id)
+      join_workers(deadline)
+
+      unless workers_done?
+        # Past the deadline with stuck handlers: free the clients first,
+        # then try to unblock and reap the workers.
+        Native.abort_all_inflight(@id)
+        Native.interrupt_all_workers(@id)
+        join_workers(monotonic_now + 0.2)
+        kill_stragglers
+      end
+
+      Native.shutdown_runtime(@id, 1_000)
+      @worker_threads.clear
+      @started = false
+      File.delete(@pidfile) if @pidfile && File.exist?(@pidfile)
+      nil
+    end
+
+    # Block until every worker has exited (i.e. until shutdown).
+    # @return [void]
+    def wait
+      @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).
+    #
+    # @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)
+      CLI.opening_credits
+      server.start
+      CLI.action!(server)
+      CLI.fin_at_exit
+      trap_signals(server)
+      server.wait
+      server
+    end
+
+    # Signal handling shared by Server.run and the kino CLI: INT/TERM drain
+    # gracefully (a second signal force-exits), USR1 prints a stats line.
+    #
+    # @param server [Kino::Server]
+    # @return [void]
+    def self.trap_signals(server)
+      # 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) }
+      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")
+          # Trap context forbids mutexes; do the real work on a thread.
+          Thread.new { server.shutdown }
+        end
+      end
+    end
+
+    # Live snapshot. Counters come from the native layer (one relaxed
+    # atomic per request); config echo makes the line self-describing.
+    #
+    # @return [Hash{Symbol => Object}] mode, lanes, workers, threads,
+    #   batch, respawns; plus queued, in_flight, served, rejected,
+    #   timeouts (and lane_depths in lanes mode) once started
+    def stats
+      base = {
+        mode: @mode, lanes: @lanes, workers: @workers, threads: @threads,
+        batch: @batch, respawns: @supervisor ? @supervisor.respawns : 0
+      }
+      return base unless @started
+
+      queued, in_flight, served, rejected, timeouts, lane_depths = Native.server_stats(@id)
+      base.merge!(queued:, in_flight:, served:, rejected:, timeouts:)
+      base[:lane_depths] = lane_depths if lane_depths
+      base
+    end
+
+    private
+
+    def validate_tls(tls)
+      return nil if tls.nil?
+      unless tls.is_a?(Hash) && tls[:cert] && tls[:key]
+        raise ArgumentError, "tls: expects { cert:, key: } (file paths or inline PEM)"
+      end
+
+      {cert: String(tls[:cert]), key: String(tls[:key])}
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def join_workers(deadline)
+      if @supervisor
+        @supervisor.shutdown([deadline - monotonic_now, 0].max)
+      else
+        @worker_threads.each do |thread|
+          thread.join([deadline - monotonic_now, 0.01].max)
+        end
+      end
+    end
+
+    def workers_done?
+      if @supervisor
+        @supervisor.done?
+      else
+        @worker_threads.none?(&:alive?)
+      end
+    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.
+        Native.log_error("shutdown deadline passed with stuck ractor workers") unless @supervisor.done?
+      else
+        @worker_threads.each { |thread| thread.kill if thread.alive? }
+      end
+    end
+
+    # Policy (mode resolution): when is an app safe for ractor
+    # dispatch, and how loudly do we fall back? Current policy: trust
+    # Ractor.shareable? on :auto with a stderr warning on fallback; forcing
+    # :ractor with an unshareable app is an error, and we never
+    # make_shareable the user's app behind their back (deep-freezing
+    # someone's object graph is not a server's call to make).
+    def resolve_mode(requested)
+      case requested
+      when :threaded
+        :threaded
+      when :ractor
+        unless Ractor.shareable?(@app)
+          raise UnshareableAppError,
+            "mode: :ractor requires a Ractor-shareable app (frozen middleware, " \
+            "Ractor.shareable_proc endpoints); try Ractor.make_shareable(app) " \
+            "or mode: :threaded"
+        end
+        :ractor
+      when :auto
+        if Ractor.shareable?(@app)
+          :ractor
+        else
+          warn "Kino: app is not Ractor-shareable; falling back to mode: :threaded"
+          :threaded
+        end
+      else
+        raise ArgumentError, "mode must be :auto, :ractor, or :threaded (got #{requested.inspect})"
+      end
+    end
+  end
+end

data/lib/kino/stream.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Kino
+  # @private
+  # The stream handed to Rack 3 streaming bodies (`body.call(stream)`).
+  # Rack 3 requires it to be full-duplex: writes go to the native response
+  # channel (a slow client blocks the writer with the GVL released), reads
+  # pull the remaining request body through the request's own rack.input.
+  class Stream
+    def initialize(request, input)
+      @request = request
+      @input = input
+      @read_closed = false
+      @write_closed = false
+    end
+
+    def read(length = nil, buffer = nil)
+      raise IOError, "stream is closed for reading" if @read_closed
+
+      @input.read(length, buffer)
+    end
+
+    def write(chunk)
+      raise IOError, "stream is closed for writing" if @write_closed
+
+      @request.write_chunk(chunk)
+      chunk.bytesize
+    end
+
+    def <<(chunk)
+      write(chunk)
+      self
+    end
+
+    def flush
+      self
+    end
+
+    def close_read
+      @read_closed = true
+      nil
+    end
+
+    def close_write
+      return if @write_closed
+
+      @write_closed = true
+      @request.finish
+      nil
+    end
+
+    def close
+      close_read
+      close_write
+    end
+
+    def closed?
+      @read_closed && @write_closed
+    end
+  end
+end

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

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+# Kino configuration.
+# Generated by `kino --init`.
+#
+# Every setting below is shown with its default value, commented out:
+# the file is a valid no-op until you uncomment something. Precedence:
+# explicit Server.new kwargs / CLI flags > this file > built-in defaults.
+
+## Network
+
+# Address to listen on. Use "0.0.0.0" to accept non-local connections.
+# bind "127.0.0.1"
+
+# Port to listen on. 0 picks an ephemeral port (readable via server.port).
+# The `kino` CLI defaults this to 9292 when nothing else sets it.
+# port 9292
+
+# TLS termination (rustls, in Rust; never blocks a Ruby thread).
+# Values are file paths or inline PEM strings. ALPN is http/1.1.
+# tls cert: "config/certs/server.pem", key: "config/certs/server.key"
+
+## Topology
+
+# Puma-style two-level topology: `workers` × `threads`.
+#
+# In :ractor mode, `workers` is the number of worker Ractors: true
+# multi-core parallelism for Ruby CPU work, one per core is a good start.
+# In :threaded mode the same total (workers × threads) runs as plain
+# Threads on the main ractor.
+
+# Defaults to the number of CPU cores (Etc.nprocessors).
+# workers 8
+
+# Threads per worker. Threads inside one ractor share its lock, so they
+# only add concurrency where handlers block on I/O (database calls, HTTP).
+# CPU-bound apps gain nothing past 1 (and pay a lock-handoff tax: threads 1
+# measured +17% on fast handlers). I/O-heavy apps want more SLOTS overall -
+# in :ractor mode prefer raising `workers` over `threads` (slots are cheap,
+# no fork memory): 32 workers x 1 thread beat 8x3 by +35% on waits.
+# threads 3
+
+## Dispatch mode
+#
+# :auto:     :ractor when the app is Ractor-shareable, else :threaded
+#             (with a warning). Note: a Class used as a Rack app always
+#             counts as "shareable" even if calling it touches unshareable
+#             state; force :threaded for those.
+# :ractor:   require a Ractor-shareable app; raises
+#             Kino::UnshareableAppError otherwise. The app must capture
+#             nothing mutable: frozen middleware, Ractor.shareable_proc
+#             endpoints.
+# :threaded: run ANY Rack app (Rails included) on a classic thread pool.
+# mode :auto
+
+## Backpressure
+
+# Bounded request queue between the Rust front-end and Ruby workers.
+# When it stays full past queue_timeout, clients get an immediate 503
+# instead of waiting forever.
+# queue_depth 1024
+
+# Seconds a request may wait for queue space before the 503.
+# queue_timeout 1.0
+
+# Seconds the app gets to produce a response before the client receives a
+# 504 instead. Off by default (nil = wait forever). The handler is NOT
+# killed - its late response is dropped and its slot stays busy until it
+# returns, so size this above your slowest legitimate endpoint.
+# request_timeout 30
+
+# Requests a worker may grab per queue visit. Values above 1 squeeze more
+# throughput out of uniformly fast handlers, but add head-of-line blocking
+# behind slow ones and stretch the effective queue depth - leave at 1
+# unless your handlers are all sub-millisecond.
+# batch 1
+
+# EXPERIMENTAL lane dispatch: per-worker queues with awake-preferring
+# assignment and work stealing. Cuts per-request wakeups for uniformly
+# fast handlers; semantics under overload are slightly different (per-lane
+# caps with brief dispatcher retries instead of one global queue).
+# lanes false
+
+# Native access log: one line per request to stdout, written by a
+# Rust-side flusher thread - request threads never block on the log.
+#
+# On color terminals lines are tinted by status class (2xx green,
+# 3xx yellow, 4xx maroon, 5xx bright red). This is the SERVER's view - it
+# includes the 503 rejections your app never sees - and it interleaves
+# cleanly with your app's own log (e.g. Rails') on stdout. See also
+# Kino::Logger for routing the app log through the same async sink.
+#
+# Try enabling it in the development environment.
+# log_requests false
+
+## Lifecycle
+
+# Graceful-shutdown drain deadline in seconds: in-flight requests get this
+# long to finish; past it, their clients receive 500s and workers are
+# reaped. A second INT/TERM force-exits immediately.
+# shutdown_timeout 30
+
+# Write the master PID here on start; removed on graceful shutdown.
+# pidfile "tmp/pids/kino.pid"
+
+## Runtime
+
+# Threads for the tokio (Rust I/O) runtime. Default (nil) lets tokio use
+# one per core: right for I/O-heavy apps. For CPU-heavy apps this is a
+# real lever: `tokio_threads 1` + `threads 1` measured +26% on a pure-CPU
+# benchmark (every spare thread is Ruby work you didn't run).
+# tokio_threads 4
+
+## App
+
+# Rackup file the `kino` CLI loads (positional CLI argument wins).
+# rackup "config.ru"
+
+# Sets RACK_ENV (unless already set) before the app is loaded by the CLI.
+# environment "production"
+
+## Rails
+#
+# Rails runs on Kino TODAY in :threaded mode; uncomment for a Rails app:
+#
+#   mode :threaded
+#   environment "production"
+#   threads 5                 # match your database pool size
+#
+# Recommended Rails-side settings to pair with Kino:
+#   - config.eager_load = true and no code reloading (production defaults):
+#     Kino's workers serve concurrently; lazy class loading under
+#     concurrency is slow and, in ractor mode, unsafe.
+#   - Database pool >= workers × threads (config/database.yml `pool:`).
+#   - Rails.logger goes to stdout/stderr or a thread-safe device.
+#
+# Rails main is being ractorized, but
+# Rails.application still captures unshareable state at boot; known
+# blockers are documented in Kino's README. Track rails/rails main; when
+# Ractor.make_shareable(Rails.application) succeeds, `mode :ractor` here
+# is all you'll need to change.

data/lib/kino/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Kino
+  # The gem version (single source of truth; ext/kino/Cargo.toml syncs).
+  VERSION = "0.1.0"
+end

data/lib/kino/worker.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Kino
+  # @private
+  # The request loop. Identical for threaded and ractor modes.
+  #
+  # The default (batch 1) hot path allocates one Hash per request: the env
+  # arrives with the native request handle embedded under "kino.request",
+  # and the common complete-body response rides the fused
+  # respond_and_take_one call: ~one FFI crossing per request, no arrays.
+  #
+  # batch > 1 trades fairness for throughput: a worker grabs up to that
+  # many already-queued requests per crossing, adding head-of-line blocking
+  # behind slow handlers and stretching effective queue depth.
+  module Worker
+    RACK_INPUT = "rack.input"
+    KINO_REQUEST = "kino.request"
+
+    module_function
+
+    def run(server_id, worker_id, app, batch_size = 1)
+      if batch_size <= 1
+        env = Native.take_one(server_id, worker_id)
+        env = handle_one(env, server_id, worker_id, app) while env
+      else
+        batch = Native.take_batch(server_id, worker_id, batch_size)
+        batch = process(batch, server_id, worker_id, app, batch_size) while batch
+      end
+    end
+
+    # serve() returns this when the response did NOT ride a fused
+    # respond-and-take (streaming body or app error) and the caller must
+    # take the next request itself. Frozen: worker ractors read it.
+    NOT_FUSED = Object.new.freeze
+
+    # Handle one request; returns the next env (fused take) or nil.
+    def handle_one(env, server_id, worker_id, app)
+      result = serve(env, app) do |request, status, headers, chunks|
+        request.respond_and_take_one(server_id, worker_id, status, headers, chunks)
+      end
+      result.equal?(NOT_FUSED) ? Native.take_one(server_id, worker_id) : result
+    end
+
+    # Handle every env in the batch; returns the next batch (the last
+    # simple response rides the fused respond_and_take) or nil on shutdown.
+    def process(batch, server_id, worker_id, app, batch_size)
+      last = batch.size - 1
+      batch.each_with_index do |env, index|
+        result = serve(env, app) do |request, status, headers, chunks|
+          if index == last
+            request.respond_and_take(server_id, worker_id, batch_size,
+              status, headers, chunks)
+          else
+            request.send_simple(status, headers, chunks)
+            NOT_FUSED
+          end
+        end
+        return result if index == last && !result.equal?(NOT_FUSED)
+      end
+      Native.take_batch(server_id, worker_id, batch_size)
+    end
+
+    # Run one request through the app. Complete bodies are yielded so the
+    # caller picks plain vs fused delivery (the block's return value passes
+    # through after the body is closed); streaming bodies are delivered
+    # here and return NOT_FUSED. App errors must never kill the worker;
+    # hard crashes (Exception) are the supervisor's job; and `abort` does
+    # the right thing whether or not the response head already went out.
+    def serve(env, app)
+      request = env[KINO_REQUEST]
+      env[RACK_INPUT] ||= Input.new(request)
+      status, headers, body = app.call(env)
+
+      if body.respond_to?(:to_ary)
+        result = yield(request, status.to_i, headers, join_chunks(body.to_ary))
+        body.close if body.respond_to?(:close)
+        result
+      else
+        deliver_streaming(request, status.to_i, headers, body, env[RACK_INPUT])
+        NOT_FUSED
+      end
+    rescue => e
+      Native.log_error("#{e.class}: #{e.message}")
+      request.abort
+      NOT_FUSED
+    end
+
+    def deliver_streaming(request, status, headers, body, input)
+      request.send_headers(status, headers)
+      if body.respond_to?(:call) && !body.respond_to?(:each)
+        # Rack 3 streaming body: the app drives a full-duplex stream whose
+        # read side is the request's existing rack.input (a fresh Input
+        # here would strand anything the app already buffered from it).
+        stream = Stream.new(request, input)
+        begin
+          body.call(stream)
+        ensure
+          stream.close
+        end
+      else
+        # Enumerable body: chunked transfer unless the app set content-length.
+        begin
+          body.each { |chunk| request.write_chunk(chunk) }
+        ensure
+          request.finish
+          body.close if body.respond_to?(:close)
+        end
+      end
+    end
+
+    def join_chunks(chunks)
+      # Single-chunk bodies (the common case) skip the join copy entirely:
+      # the native layer reads raw bytes, so encoding doesn't matter.
+      return chunks.first || "" if chunks.size <= 1
+
+      joined = (+"").force_encoding(Encoding::BINARY)
+      chunks.each { |chunk| joined << chunk.b }
+      joined
+    end
+
+    private_class_method :handle_one, :process, :serve, :deliver_streaming,
+      :join_chunks
+  end
+end

data/lib/kino.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "kino/version"
+require "kino/kino"
+
+# A high-performance Ractor web server for Ruby 4.0+: Rack 3-based, with
+# a Rust (tokio + hyper) front-end and Ractor-parallel Ruby workers, plus
+# a threaded fallback mode for apps (such as Rails) that are not
+# Ractor-shareable.
+#
+# The public API is {Kino::Server}, {Kino::Configuration}, {Kino::Check},
+# {Kino::Logger}, and {Kino.sleep}; the `kino` executable is implemented
+# by {Kino::CLI}.
+module Kino
+  # Base class for all errors raised by Kino.
+  class Error < StandardError; end
+
+  # Raised when mode: :ractor is forced but the app is not Ractor-shareable.
+  class UnshareableAppError < Error; end
+
+  # High-resolution sleep that bypasses the VM timer (whose wakeups inside
+  # non-main ractors are coarse: ~+2.5ms on Linux). Sleeps on the OS clock
+  # with the GVL released; chunked so Thread#kill and shutdown interrupts
+  # are honored between chunks.
+  #
+  # @param seconds [Numeric] how long to sleep; must be non-negative
+  # @return [nil]
+  # @raise [ArgumentError] for negative or non-numeric durations
+  def self.sleep(seconds)
+    remaining = Float(seconds)
+    raise ArgumentError, "sleep duration must be non-negative" if remaining.negative?
+
+    remaining = Native.sleep_chunk(remaining) while remaining.positive?
+    nil
+  end
+end
+
+require_relative "kino/cli"
+require_relative "kino/logger"
+require_relative "kino/check"
+require_relative "kino/input"
+require_relative "kino/null_input"
+require_relative "kino/errors_stream"
+require_relative "kino/stream"
+require_relative "kino/configuration"
+require_relative "kino/worker"
+require_relative "kino/ractor_supervisor"
+require_relative "kino/server"
+
+# Hand the frozen shareable singletons to the native layer: it sets them
+# straight into each request's env, so the worker loop allocates neither
+# an errors stream nor (for bodyless requests) an input object.
+Kino::Native.register_defaults(Kino::ErrorsStream::INSTANCE, Kino::NullInput::INSTANCE)