kino 0.2.1 → 0.4.0

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,13 +20,27 @@ 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?
     attr_reader mode: Symbol
     attr_reader bind: String
 
     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
 
@@ -41,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
@@ -52,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
@@ -98,11 +121,19 @@ module Kino
       def lanes: (boolish enabled) -> untyped
       def log_requests: (boolish enabled) -> untyped
       def on_error: (?^(Exception, Hash[String, untyped]) -> void handler) ?{ (Exception, Hash[String, untyped]) -> void } -> untyped
+      def after_boot: (?^() -> void handler) ?{ () -> void } -> untyped
+      def after_worker_boot: (?^(Integer) -> void handler) ?{ (Integer) -> void } -> untyped
+      def after_request_complete: (?^(Hash[String, untyped], Integer) -> void handler) ?{ (Hash[String, untyped], Integer) -> void } -> untyped
+      def on_worker_exit: (?^(Integer, Exception?) -> void handler) ?{ (Integer, Exception?) -> void } -> untyped
       def shutdown_timeout: (Numeric seconds) -> untyped
       def tokio_threads: (int count) -> untyped
       def tls: (cert: String, key: String) -> untyped
       def environment: (String | Symbol env) -> untyped
       def pidfile: (String path) -> untyped
+      def control_bind: (String addr) -> String
+      def control_token: (String token) -> String
+      def quarantine_timeout: (Numeric? seconds) -> untyped
+      def quarantine_max: (int count) -> untyped
       def rackup: (String path) -> untyped
     end
   end
@@ -159,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.
@@ -179,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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kino
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Yaroslav Markin
@@ -51,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.9.128
+- !ruby/object:Gem::Dependency
+  name: rackup
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -161,10 +175,16 @@ files:
 - ext/kino/Cargo.toml
 - ext/kino/build.rs
 - ext/kino/extconf.rb
+- ext/kino/src/access_log.rs
+- ext/kino/src/control.rs
+- ext/kino/src/cpus.rs
 - ext/kino/src/env_strings.rs
 - ext/kino/src/gvl.rs
 - ext/kino/src/lib.rs
+- ext/kino/src/listen.rs
+- ext/kino/src/log.rs
 - ext/kino/src/logsink.rs
+- ext/kino/src/mono.rs
 - ext/kino/src/pin.rs
 - ext/kino/src/queue.rs
 - ext/kino/src/registry.rs
@@ -180,15 +200,20 @@ files:
 - lib/kino/cli.rb
 - lib/kino/configuration.rb
 - lib/kino/errors_stream.rb
+- lib/kino/hook_fire.rb
 - lib/kino/input.rb
+- lib/kino/log.rb
 - lib/kino/logger.rb
 - lib/kino/null_input.rb
+- lib/kino/quarantine_monitor.rb
 - lib/kino/ractor_supervisor.rb
 - lib/kino/server.rb
 - lib/kino/stream.rb
 - lib/kino/templates/kino.rb.tt
 - lib/kino/version.rb
 - lib/kino/worker.rb
+- lib/kino/worker_hooks.rb
+- lib/rackup/handler/kino.rb
 - sig/kino.rbs
 homepage: https://github.com/yaroslav/kino
 licenses: