kino 0.1.0-aarch64-linux

data/lib/kino/check.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Kino
+  # The shareability doctor behind `kino --check`: explains WHY an app
+  # can't run in :ractor mode, instead of leaving you to decode
+  # Ractor::IsolationError one ivar at a time.
+  #
+  # The walk is strictly non-mutating: Ractor.make_shareable would freeze
+  # the user's object graph, so we never call it. Instead we recurse into
+  # whatever Ractor.shareable? rejects and name the leaves: instance
+  # variables by path, proc captures by variable name and definition site,
+  # and the class-ivar trap that bites class-style apps (a Class is always
+  # "shareable", but reading its unshareable ivars from a worker ractor
+  # raises on the first request).
+  module Check
+    # Stop after this many findings: the first few name the problem.
+    MAX_FINDINGS = 20
+    # Walk budget, so a pathological object graph cannot hang the check.
+    MAX_NODES = 5_000
+
+    # One named blocker: a path into the object graph plus what is wrong
+    # there.
+    Finding = Struct.new(:path, :message) do
+      # @return [String] "path — message", as printed by the CLI
+      def to_s
+        "#{path} — #{message}"
+      end
+    end
+
+    module_function
+
+    # @param app [#call] a Rack application (or a Class/Module used as one)
+    # @return [Hash] +{shareable: Boolean, findings: Array<Finding>}+
+    def report(app)
+      findings = []
+      seen = {}.compare_by_identity
+      budget = {nodes: 0}
+
+      if app.is_a?(Module)
+        # Classes/modules pass Ractor.shareable? unconditionally, but their
+        # unshareable class-level state is main-ractor-only at runtime.
+        scan_module(app, "app (#{app.inspect})", findings)
+        {shareable: findings.empty?, findings: findings}
+      elsif Ractor.shareable?(app)
+        {shareable: true, findings: []}
+      else
+        walk(app, "app", findings, seen, budget)
+        findings << Finding.new(path: "app", message: unshareable_note(app)) if findings.empty?
+        {shareable: false, findings: findings}
+      end
+    end
+
+    # Pretty-printed report; returns true when the app is ractor-ready.
+    # @param app [#call] a Rack application
+    # @param io [IO] where to print
+    # @return [Boolean]
+    def print_report(app, io: $stdout)
+      result = report(app)
+      if result[:shareable]
+        io.puts CLI.paint("32", "check: app is Ractor-shareable — mode :ractor will work", io: io)
+        true
+      else
+        io.puts CLI.red("check: app is NOT Ractor-shareable", io: io)
+        result[:findings].each { |finding| io.puts "  - #{finding}" }
+        io.puts dim_hint(io)
+        false
+      end
+    end
+
+    def dim_hint(io)
+      CLI.dim(
+        "  hints: freeze config at boot; build endpoints with " \
+        "Ractor.shareable_proc; keep per-worker resources in " \
+        "Ractor.store_if_absent; or run mode :threaded.",
+        io: io
+      )
+    end
+
+    # Recurse into an unshareable object and name its blockers. Shareable
+    # objects return immediately, so callers never need their own guard.
+    def walk(obj, path, findings, seen, budget)
+      return if Ractor.shareable?(obj)
+      return if findings.size >= MAX_FINDINGS
+      return if seen[obj]
+      seen[obj] = true
+      return if (budget[:nodes] += 1) > MAX_NODES
+
+      case obj
+      when Proc
+        scan_proc(obj, path, findings, seen, budget)
+      when Hash
+        scan_ivars(obj, path, findings, seen, budget)
+        obj.each do |key, value|
+          walk(key, "#{path} key #{key.inspect}", findings, seen, budget)
+          walk(value, "#{path}[#{key.inspect}]", findings, seen, budget)
+        end
+        report_leaf(obj, path, findings)
+      when Array
+        scan_ivars(obj, path, findings, seen, budget)
+        obj.each_with_index do |value, index|
+          walk(value, "#{path}[#{index}]", findings, seen, budget)
+        end
+        report_leaf(obj, path, findings)
+      else
+        scan_ivars(obj, path, findings, seen, budget)
+        report_leaf(obj, path, findings)
+      end
+    end
+
+    # A finding is recorded only for leaves: unshareable objects whose
+    # innards gave us nothing more specific to point at.
+    def report_leaf(obj, path, findings)
+      return if obj.instance_variables.any? || obj.is_a?(Proc)
+      return if (obj.is_a?(Hash) || obj.is_a?(Array)) && !obj.frozen?
+
+      findings << Finding.new(path: path, message: unshareable_note(obj))
+    end
+
+    def scan_ivars(obj, path, findings, seen, budget)
+      obj.instance_variables.each do |name|
+        value = obj.instance_variable_get(name)
+        next if Ractor.shareable?(value)
+
+        findings << Finding.new(
+          path: "#{path}.#{name}",
+          message: unshareable_note(value)
+        )
+        walk(value, "#{path}.#{name}", findings, seen, budget)
+        break if findings.size >= MAX_FINDINGS
+      end
+      unless obj.frozen? || obj.is_a?(Proc) || obj.is_a?(Module)
+        findings << Finding.new(path: path, message: "#{obj.class} instance is not frozen")
+      end
+    end
+
+    def scan_proc(proc_obj, path, findings, seen, budget)
+      where = proc_obj.source_location&.join(":") || "native"
+      binding = begin
+        proc_obj.binding
+      rescue
+        nil
+      end
+      return unless binding
+
+      receiver = binding.receiver
+      unless Ractor.shareable?(receiver)
+        findings << Finding.new(
+          path: "#{path} (Proc at #{where})",
+          message: "self is not shareable: #{brief(receiver)} — use Ractor.shareable_proc"
+        )
+      end
+      binding.local_variables.each do |name|
+        value = binding.local_variable_get(name)
+        next if Ractor.shareable?(value)
+
+        findings << Finding.new(
+          path: "#{path} (Proc at #{where})",
+          message: "captures `#{name}` = #{brief(value)} (unshareable)"
+        )
+        walk(value, "#{path} capture `#{name}`", findings, seen, budget)
+        break if findings.size >= MAX_FINDINGS
+      end
+    end
+
+    def scan_module(mod, path, findings)
+      mod.instance_variables.each do |name|
+        value = mod.instance_variable_get(name)
+        next if Ractor.shareable?(value)
+
+        findings << Finding.new(
+          path: "#{path}.#{name}",
+          message: "class-level ivar holds #{brief(value)} — classes pass " \
+                   "Ractor.shareable?, but reading this from a worker ractor " \
+                   "raises Ractor::IsolationError on the first request"
+        )
+        break if findings.size >= MAX_FINDINGS
+      end
+    end
+
+    def unshareable_note(obj)
+      if obj.frozen?
+        "#{brief(obj)} is frozen but holds unshareable contents"
+      else
+        "#{brief(obj)} is not frozen"
+      end
+    end
+
+    def brief(obj)
+      inspected = obj.inspect
+      inspected = "#{inspected[0, 60]}..." if inspected.size > 60
+      "#{inspected} (#{obj.class})"
+    rescue
+      "#<#{obj.class}>"
+    end
+
+    private_class_method :dim_hint, :walk, :report_leaf, :scan_ivars,
+      :scan_proc, :scan_module, :unshareable_note, :brief
+  end
+end

data/lib/kino/cli.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "version"
+
+module Kino
+  # The `kino` executable (CLI.start) plus startup presentation shared with
+  # Server.run: the banner, ANSI styling, and the exit credit. Nothing here
+  # is part of the serving API. (The native layer has a twin of `paint` in
+  # style.rs for the few places Rust writes to the terminal.)
+  #
+  # This file deliberately loads no native code: `require "kino"` happens
+  # inside the actions that need it, so --help and --version stay instant.
+  module CLI
+    # The plain banner art: "Kino" in TheDraw's Mindbenders font; {motd}
+    # adds the original three-tone shading.
+    MOTD = <<~BANNER
+      ggg    .o
+      $$$_,o$$P aaa $$$eea,.   .,aaa,.
+      %$$`4eP'  $$$ $$$``$$$% $$$```$$$
+      $$$--`$$o ggg $$$---$$$ $$$---$$$
+      $$$ ░ $$$ $$$ $$$ ░ $$$ $$$ ░ $$$
+      $$$---$$$ $$$ $$$---$$$ $$$---$$$
+      $$$   $$$ $$' $$$   $$$ ^$$aaaS$'
+    BANNER
+
+    # Tone stencil aligned with MOTD, character by character: 1 bright
+    # white, 2 light gray, 3 dark gray; spaces follow the art.
+    MOTD_TONES = <<~BANNER
+      111    11
+      111111111 111 11111111   1111111
+      11111111  111 111111111 111111111
+      111331111 111 111333111 111333111
+      111 3 322 122 111 3 322 112 3 122
+      111333322 223 111333223 123333223
+      112   233 333 222   333 122233332
+    BANNER
+
+    # The basic-palette SGR code for each stencil tone.
+    TONE_SGR = {"1" => "97", "2" => "37", "3" => "90"}.freeze
+
+    private_constant :MOTD_TONES, :TONE_SGR
+
+    module_function
+
+    # True when output to `io` may use ANSI styling.
+    # @param io [IO]
+    # @return [Boolean]
+    def color?(io = $stdout)
+      io.tty? && ENV["NO_COLOR"].nil? && ENV["TERM"] != "dumb"
+    end
+
+    # Wrap `text` in an SGR code ("1" bold, "31" red, "38;5;N" 256-color),
+    # resetting at the end; plain when `io` is not a color terminal.
+    #
+    # @param code [String] an SGR code
+    # @param text [String]
+    # @param io [IO] the stream the text is destined for (gates coloring)
+    # @return [String]
+    def paint(code, text, io: $stdout)
+      color?(io) ? "\e[#{code}m#{text}\e[0m" : text
+    end
+
+    # Startup-output styling, same gray family as the banner.
+    # @return [String]
+    def dim(text, io: $stdout)
+      paint("38;5;243", text, io: io)
+    end
+
+    # Bold styling for headings and the Action!/Fin. bookends.
+    # @return [String]
+    def bold(text, io: $stdout)
+      paint("1", text, io: io)
+    end
+
+    # Errors are red (gated on stderr unless another io is given).
+    # @return [String]
+    def red(text, io: $stderr)
+      paint("91", text, io: io)
+    end
+
+    # The banner with its three-tone shading applied per character.
+    # @param color [Boolean]
+    # @return [String]
+    def motd(color: color?)
+      return MOTD unless color
+
+      MOTD.lines.zip(MOTD_TONES.lines).map do |art, tones|
+        current = nil
+        line = art.chomp.each_char.with_index.map { |char, i|
+          sgr = TONE_SGR[tones.to_s[i]]
+          if char != " " && sgr && sgr != current
+            current = sgr
+            "\e[#{sgr}m#{char}"
+          else
+            char
+          end
+        }.join
+        "#{line}\e[0m\n"
+      end.join
+    end
+
+    # One-line stats dump (the SIGUSR1 handler's output).
+    # @param stats [Hash{Symbol => Object}] see {Kino::Server#stats}
+    # @return [String]
+    def stats_line(stats)
+      dim("Kino stats: #{stats.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")}")
+    end
+
+    # The two banner halves around Server#start: credits before, the ready
+    # block plus a bold "Action!" after, once mode and port are known.
+    # Server.run is the one caller; the kino CLI funnels into it.
+    # @return [void]
+    def opening_credits
+      puts motd
+      puts dim("\nKino #{VERSION} presents:")
+    end
+
+    # @param server [Kino::Server] a started server
+    # @return [void]
+    def action!(server)
+      puts dim("- mode:      #{server.mode}")
+      puts dim("- listening: http#{"s" if server.tls?}://#{server.bind}:#{server.port}")
+      puts dim("- Ctrl-C to drain and stop")
+      puts "\n#{bold("Action!")}\n\n"
+    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]
+    def fin_at_exit
+      return if @fin_registered
+
+      @fin_registered = true
+      at_exit { $stdout.puts bold("\nFin.\n") }
+    end
+
+    # The `kino` executable: parse flags, then init/check/serve. Returns
+    # the process exit status (exe/kino passes it to Kernel#exit), except
+    # for -v and -h, which print and exit in place per optparse convention.
+    #
+    # @param argv [Array<String>] command-line arguments (consumed)
+    # @return [Integer] process exit status
+    def start(argv)
+      options = {overrides: {}}
+      parser = option_parser(options)
+      parser.parse!(argv)
+
+      return write_sample(options[:init_path]) if options[:init_path]
+
+      config = resolve_config(options)
+
+      # Precedence for the rackup file: positional arg > `rackup` in config > config.ru
+      rackup_file = argv.first || config[:rackup] || "config.ru"
+      unless File.exist?(rackup_file)
+        warn red("Kino: #{rackup_file} not found")
+        puts
+        print_help(parser)
+        return 1
+      end
+
+      ENV["RACK_ENV"] ||= config[:environment] if config[:environment]
+
+      app = Rack::Builder.parse_file(rackup_file)
+      app = app.first if app.is_a?(Array) # rack < 3 compat
+
+      return Check.print_report(app) ? 0 : 1 if options[:check]
+
+      serve(app, config)
+      0
+    end
+
+    # Bun-style colored help, generated from the parser's own switch list
+    # so it can never drift from the real options.
+    def print_help(parser)
+      puts "#{bold("Kino")}#{dim(": high-performance Ractor web server for Ruby")}"
+      puts
+      puts "#{bold("Usage:")} kino #{paint("36",
+        "[options]")} #{paint("36",
+          "[rackup file]")}#{dim("   (default: config.ru)")}"
+      puts
+      puts bold("Options:")
+      parser.top.list.each do |switch|
+        next unless switch.is_a?(OptionParser::Switch) && switch.desc.any?
+
+        flags = [*switch.short, *switch.long].join(", ")
+        flags += " #{switch.arg.strip}" if switch.arg
+        puts "  #{paint("36", flags.ljust(24))} #{dim(switch.desc.join(" "))}"
+      end
+      puts
+      puts bold("Examples:")
+      puts "  #{paint("36", "kino --init")}#{dim("              write a documented kino.rb")}"
+      puts "  #{paint("36", "kino")}#{dim("                     serve config.ru on :9292")}"
+      puts "  #{paint("36", "kino --check app.ru")}#{dim("      explain Ractor-shareability")}"
+    end
+
+    def option_parser(options)
+      OptionParser.new do |opts|
+        opts.banner = "Usage: kino [options] [rackup file (default: config.ru)]"
+        opts.on("-C", "--config FILE", "Config file (default: kino.rb if present)") { |v| options[:config_file] = v }
+        opts.on("--init [PATH]", "Write a commented sample config (default: kino.rb) and exit") do |v|
+          options[:init_path] = v || "kino.rb"
+        end
+        opts.on("--check", "Load the app and report Ractor-shareability, then exit") { options[:check] = true }
+        opts.on("-b", "--bind HOST", "Bind address") { |v| options[:overrides][:bind] = v }
+        opts.on("-p", "--port PORT", Integer, "Port") { |v| options[:overrides][:port] = v }
+        opts.on("-w", "--workers COUNT", Integer, "Worker count") { |v| options[:overrides][:workers] = v }
+        opts.on("-t", "--threads COUNT", Integer, "Threads per worker") { |v| options[:overrides][:threads] = v }
+        opts.on("-m", "--mode MODE", "auto | ractor | threaded") { |v| options[:overrides][:mode] = v.to_sym }
+        opts.on("-v", "--version") do
+          puts "kino #{VERSION}"
+          exit
+        end
+        opts.on_tail("-h", "--help", "Show this help") do
+          print_help(opts)
+          exit
+        end
+      end
+    end
+
+    def write_sample(path)
+      require "kino"
+      Configuration.write_sample(path)
+      puts "Kino: wrote sample config to #{path}"
+      0
+    rescue Kino::Error => e
+      warn red("kino: #{e.message}")
+      1
+    end
+
+    # Resolve the full configuration once: file + CLI flag overrides.
+    def resolve_config(options)
+      require "kino"
+      require "rack"
+
+      config_file = options[:config_file]
+      config_file ||= ("kino.rb" if File.exist?("kino.rb"))
+
+      config = Configuration.new
+      config.load_file(config_file) if config_file
+      config.merge!(options[:overrides])
+      # Default port 9292 when neither the file nor a flag chose one.
+      config.set(:port, 9292) unless config.set?(:port)
+      config
+    end
+
+    def serve(app, config)
+      Server.run(app, **config.server_options)
+    end
+
+    private_class_method :print_help, :option_parser, :write_sample,
+      :resolve_config, :serve
+  end
+end

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