kino 0.1.0-x86_64-linux

data/lib/kino/input.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Kino
+  # @private
+  # rack.input: forward-only reader over the native streaming body.
+  # Rack 3 dropped the rewindability requirement, which is exactly what makes
+  # streaming legal here. All output is binary, per spec.
+  class Input
+    CHUNK_SIZE = 65_536
+
+    def initialize(request)
+      @request = request
+      @buffer = (+"").force_encoding(Encoding::BINARY)
+      @eof = false
+    end
+
+    # IO#read semantics, as Rack::Lint enforces them:
+    #   read         -> String ("" at EOF)
+    #   read(n)      -> String of up to n bytes, nil at EOF
+    #   read(n, buf) -> fills buf, returns it (or nil at EOF)
+    def read(length = nil, buffer = nil)
+      out = buffer ? buffer.clear.force_encoding(Encoding::BINARY) : (+"").force_encoding(Encoding::BINARY)
+
+      if length.nil?
+        fill_all
+        out << @buffer
+        @buffer.clear
+        return out
+      end
+
+      fill(length)
+      return nil if @buffer.empty? && length.positive?
+
+      out << @buffer.slice!(0, length)
+      out
+    end
+
+    def gets
+      fill_until_newline
+      return nil if @buffer.empty?
+
+      index = @buffer.index("\n")
+      index ? @buffer.slice!(0..index) : @buffer.slice!(0, @buffer.bytesize)
+    end
+
+    def each
+      while (chunk = read(CHUNK_SIZE))
+        yield chunk
+      end
+    end
+
+    def close
+      nil
+    end
+
+    private
+
+    def pull
+      return if @eof
+
+      chunk = @request.read_body(CHUNK_SIZE)
+      chunk ? @buffer << chunk : @eof = true
+    end
+
+    def fill(length)
+      pull while @buffer.bytesize < length && !@eof
+    end
+
+    def fill_all
+      pull until @eof
+    end
+
+    def fill_until_newline
+      pull until @buffer.index("\n") || @eof
+    end
+  end
+end

data/lib/kino/logger.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Kino
+  # A ::Logger writing through the native async sink: formatted lines go
+  # onto a lock-free channel and a Rust flusher thread batches them into
+  # the output: no per-line mutex (which serializes every worker thread)
+  # and no write syscall on request threads.
+  #
+  #   # e.g. Rails, config/environments/production.rb:
+  #   config.logger = Kino::Logger.new                       # stdout
+  #   config.logger = Kino::Logger.new("log/production.log")
+  #
+  # Durability: a graceful shutdown drains everything; a hard crash can
+  # lose the tail of the buffer (the standard async-logging trade-off).
+  class Logger < ::Logger
+    # @param path [String, nil] log file path (created/appended), or nil
+    #   for stdout
+    # @param options [Hash] passed through to ::Logger#initialize
+    #   (progname:, level:, formatter:, ...)
+    def initialize(path = nil, **options)
+      super(Device.new(path), **options)
+    end
+
+    # The raw IO-like device for integrations that want bytes without
+    # ::Logger's formatting: Rack::CommonLogger, ActiveSupport::Logger.new,
+    # a BroadcastLogger arm, ... Frozen and holding only an Integer id, so
+    # it is Ractor-shareable; one device can serve every worker.
+    class Device
+      # @param path [String, nil] a file (created/appended) or nil for stdout
+      def initialize(path = nil)
+        @id = Native.log_device_open(path&.to_s)
+        freeze
+      end
+
+      # Queue one formatted line on the async sink; never blocks.
+      # @param message [String]
+      # @return [void]
+      def write(message)
+        Native.log_device_write(@id, message.to_s)
+      end
+
+      # Close the device: the flusher drains its queue and exits. Writes
+      # after close are ignored.
+      # @return [void]
+      def close
+        Native.log_device_close(@id)
+      end
+
+      # ::Logger probes these on its device.
+      def reopen(*) = self
+      alias_method :<<, :write
+    end
+  end
+end

data/lib/kino/null_input.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Kino
+  # @private
+  # rack.input for requests that can carry no body (most GETs). A single
+  # frozen, Ractor-shareable instance is set by the native layer directly
+  # into the env, so bodyless requests allocate no input object at all.
+  class NullInput
+    EMPTY = String.new("", encoding: Encoding::BINARY).freeze
+
+    # IO#read semantics at permanent EOF: read and read(0) return "",
+    # read(n > 0) returns nil. Mirrors what Input does on an empty body,
+    # since the native layer swaps the two classes invisibly per request.
+    def read(length = nil, buffer = nil)
+      empty = length.nil? || length.zero?
+      if buffer
+        buffer.clear.force_encoding(Encoding::BINARY)
+        return empty ? buffer : nil
+      end
+      empty ? EMPTY : nil
+    end
+
+    def gets
+      nil
+    end
+
+    def each
+      # no chunks, ever
+    end
+
+    def close
+      nil
+    end
+
+    INSTANCE = new.freeze
+  end
+end

data/lib/kino/ractor_supervisor.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Kino
+  # @private
+  # 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.
+  class RactorSupervisor
+    attr_reader :respawns
+
+    def initialize(server_id, app, workers:, threads:, batch: 1)
+      @server_id = server_id
+      @app = app
+      @workers = workers
+      @threads = threads
+      @batch = batch
+      @respawns = 0
+      @draining = false
+      @lock = Mutex.new
+      @supervisor_threads = []
+    end
+
+    def start
+      @supervisor_threads = Array.new(@workers) { |index| supervise(index) }
+      self
+    end
+
+    # Flag the drain and join supervisors up to the (numeric) deadline;
+    # callers wanting an unbounded wait use #join instead.
+    def shutdown(timeout)
+      @lock.synchronize { @draining = true }
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      @supervisor_threads.each do |thread|
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        thread.join([remaining, 0.01].max)
+      end
+    end
+
+    def done?
+      @supervisor_threads.none?(&:alive?)
+    end
+
+    # Block until the workers exit on their own (drain elsewhere): join
+    # without flipping the draining flag.
+    def join
+      @supervisor_threads.each(&:join)
+    end
+
+    private
+
+    def supervise(index)
+      Thread.new do
+        crashes = 0
+        loop do
+          ractor, worker_ids = spawn_worker
+          begin
+            ractor.value # blocks until the ractor terminates
+            break        # clean exit: queue closed, workers drained
+          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
+            # around to dropping the dead heap), then decide on respawn.
+            worker_ids.each { |id| Native.abort_inflight(@server_id, id) }
+            break if draining?
+
+            crashes += 1
+            @lock.synchronize { @respawns += 1 }
+            cause = (e.respond_to?(:cause) && e.cause) ? e.cause : e
+            Native.log_error("worker ractor #{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
+            # (give up / cool down after N crashes in T seconds) trades
+            # availability for fail-fast. Current policy: respawn forever.
+          end
+        end
+      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.
+    def spawn_worker
+      worker_ids = Array.new(@threads) { Native.register_worker(@server_id) }
+      ractor = Ractor.new(@server_id, worker_ids, @app, @batch) do |server_id, ids, app, batch|
+        ids.map do |id|
+          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
+            Kino::Worker.run(server_id, id, app, batch)
+          end
+        end.each(&:join)
+      end
+      [ractor, worker_ids]
+    end
+
+    def draining?
+      @lock.synchronize { @draining }
+    end
+  end
+end

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