kino 0.1.0

data/lib/kino/configuration.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "etc"
+
+module Kino
+  # Server settings with Puma-style precedence:
+  #   explicit Server.new kwargs > config file DSL > defaults.
+  class Configuration
+    # Every setting and its default; the full reference lives in the
+    # generated sample config (`kino --init`).
+    DEFAULTS = {
+      bind: "127.0.0.1",
+      port: 0,
+      workers: nil, # resolved to Etc.nprocessors in #to_h
+      threads: 3,
+      mode: :auto,
+      queue_depth: 1024,
+      queue_timeout: 1.0,
+      request_timeout: nil,
+      batch: 1,
+      lanes: false,
+      log_requests: false,
+      shutdown_timeout: 30,
+      tokio_threads: nil,
+      tls: nil,
+      environment: nil,
+      pidfile: nil,
+      rackup: nil
+    }.freeze
+
+    # The known setting names.
+    SETTINGS = DEFAULTS.keys.freeze
+
+    # Source template for {.sample}.
+    SAMPLE_TEMPLATE = File.expand_path("templates/kino.rb.tt", __dir__)
+
+    # The fully-commented sample config (see `kino --init`).
+    # @return [String]
+    def self.sample
+      File.read(SAMPLE_TEMPLATE)
+    end
+
+    # Write the sample config to +path+. Refuses to clobber an existing
+    # file unless force: true.
+    #
+    # @param path [String]
+    # @param force [Boolean] overwrite an existing file
+    # @return [String] the path written
+    # @raise [Kino::Error] when the file exists and force is false
+    def self.write_sample(path, force: false)
+      if File.exist?(path) && !force
+        raise Error, "#{path} already exists (use force: true to overwrite)"
+      end
+
+      File.write(path, sample)
+      path
+    end
+
+    def initialize
+      @values = {}
+    end
+
+    # @param key [Symbol] a key from DEFAULTS
+    # @return [Object] the explicit value, or the default
+    def [](key)
+      @values.fetch(key) { DEFAULTS.fetch(key) }
+    end
+
+    # @param key [Symbol] a key from DEFAULTS
+    # @param value [Object]
+    # @raise [ArgumentError] for unknown settings
+    def set(key, value)
+      raise ArgumentError, "unknown setting #{key.inspect}" unless DEFAULTS.key?(key)
+
+      @values[key] = value
+    end
+
+    # @return [Boolean] whether the key was explicitly set
+    def set?(key)
+      @values.key?(key)
+    end
+
+    # Load a config file (Ruby DSL) into this configuration.
+    # @param path [String]
+    # @return [self]
+    # @raise [Kino::Error] when the file does not exist
+    def load_file(path)
+      raise Error, "config file not found: #{path}" unless File.exist?(path)
+
+      DSL.new(self).instance_eval(File.read(path), path, 1)
+      self
+    end
+
+    # Explicit kwargs win over everything already set.
+    # @param options [Hash{Symbol => Object}]
+    # @return [self]
+    def merge!(options)
+      options.each { |key, value| set(key, value) }
+      self
+    end
+
+    # @return [Hash{Symbol => Object}] every setting, defaults filled in
+    def to_h
+      SETTINGS.to_h { |key| [key, self[key]] }.tap do |h|
+        h[:workers] ||= Etc.nprocessors
+      end
+    end
+
+    # The settings Server.new accepts: everything except the keys only the
+    # CLI consumes (rackup file selection, RACK_ENV).
+    # @return [Hash{Symbol => Object}]
+    def server_options
+      to_h.except(:rackup, :environment)
+    end
+
+    # The config-file DSL, deliberately Puma-shaped:
+    #
+    #   # kino.rb
+    #   bind "0.0.0.0"
+    #   port 9292
+    #   workers 8           # ractors (or thread groups in :threaded mode)
+    #   threads 3           # threads per worker
+    #   mode :ractor        # :auto | :ractor | :threaded
+    #   queue_depth 2048
+    #   queue_timeout 0.5
+    #   shutdown_timeout 15
+    #   tokio_threads 4
+    #   tls cert: "cert.pem", key: "key.pem"
+    #
+    # Every directive is documented in the generated sample config
+    # (`kino --init`); the one-liners here only state the value each
+    # directive expects.
+    class DSL
+      def initialize(config)
+        @config = config
+      end
+
+      # Address to listen on ("0.0.0.0" accepts non-local connections).
+      def bind(host) = @config.set(:bind, host)
+
+      # 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.
+      def workers(count) = @config.set(:workers, Integer(count))
+
+      # Threads per worker (I/O concurrency inside one ractor).
+      def threads(count) = @config.set(:threads, Integer(count))
+
+      # Dispatch mode: :auto, :ractor, or :threaded.
+      def mode(mode) = @config.set(:mode, mode.to_sym)
+
+      # Bounded request-queue depth; overflow earns clients a 503.
+      def queue_depth(depth) = @config.set(:queue_depth, Integer(depth))
+
+      # Seconds a request may wait for queue space before the 503.
+      def queue_timeout(seconds) = @config.set(:queue_timeout, Float(seconds))
+
+      # Seconds the app gets before the client receives a 504; nil = off.
+      def request_timeout(seconds) = @config.set(:request_timeout, seconds && Float(seconds))
+
+      # Requests a worker may grab per queue visit (default 1).
+      def batch(count) = @config.set(:batch, Integer(count))
+
+      # EXPERIMENTAL per-worker lane dispatch.
+      def lanes(enabled) = @config.set(:lanes, !!enabled)
+
+      # Native access log: one status-colored line per request to stdout.
+      def log_requests(enabled) = @config.set(:log_requests, !!enabled)
+
+      # Graceful-shutdown drain deadline in seconds.
+      def shutdown_timeout(seconds) = @config.set(:shutdown_timeout, seconds)
+
+      # Threads for the tokio (Rust I/O) runtime; default: one per core.
+      def tokio_threads(count) = @config.set(:tokio_threads, Integer(count))
+
+      # TLS termination; file paths or inline PEM strings.
+      def tls(cert:, key:) = @config.set(:tls, {cert: cert, key: key})
+
+      # Sets RACK_ENV (unless already set) before the CLI loads the app.
+      def environment(env) = @config.set(:environment, env.to_s)
+
+      # Write the master PID here on start.
+      def pidfile(path) = @config.set(:pidfile, path.to_s)
+
+      # Rackup file the `kino` CLI loads (positional argument wins).
+      def rackup(path) = @config.set(:rackup, path.to_s)
+    end
+  end
+end

data/lib/kino/errors_stream.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Kino
+  # @private
+  # rack.errors: stateless writer into the native logger. Frozen singleton,
+  # which also makes it Ractor-shareable; one instance serves all workers.
+  class ErrorsStream
+    def puts(message)
+      Native.log_error(message.to_s)
+      nil
+    end
+
+    def write(message)
+      message = message.to_s
+      Native.log_error(message)
+      message.bytesize
+    end
+
+    def flush
+      self
+    end
+
+    INSTANCE = new.freeze
+  end
+end

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