Class: Kino::Configuration::DSL

Inherits:
Object
  • Object
show all
Defined in:
lib/kino/configuration.rb

Overview

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.

Instance Method Summary collapse

Constructor Details

#initialize(config) ⇒ DSL

Returns a new instance of DSL.



158
159
160
 
# File 'lib/kino/configuration.rb', line 158

def initialize(config)
  @config = config
end

Instance Method Details

#after_boot(handler = nil, &block) ⇒ Object

Called once on the main thread after the worker pool is up. The readiness seam (wire sd_notify or a "server ready" metric here).



213
 
# File 'lib/kino/configuration.rb', line 213

def after_boot(handler = nil, &block) = @config.set(:after_boot, handler || block)

#after_request_complete(handler = nil, &block) ⇒ Object

Called inside the worker after each successful response with (env, status). Hot path: leave unset for zero cost. Must be Ractor-shareable in :ractor mode.



223
 
# File 'lib/kino/configuration.rb', line 223

def after_request_complete(handler = nil, &block) = @config.set(:after_request_complete, handler || block)

#after_worker_boot(handler = nil, &block) ⇒ Object

Called once inside each worker (a ractor in :ractor mode) before it serves, with the worker's slot id. Must be Ractor-shareable in :ractor mode (build it with Ractor.shareable_proc).



218
 
# File 'lib/kino/configuration.rb', line 218

def after_worker_boot(handler = nil, &block) = @config.set(:after_worker_boot, handler || block)

#batch(count) ⇒ Object

Requests a worker may grab per queue visit (default 1).



198
 
# File 'lib/kino/configuration.rb', line 198

def batch(count) = @config.set(:batch, Integer(count))

#bind(host) ⇒ Object

Address to listen on: a host ("0.0.0.0" accepts non-local connections), or "unix:///path/to.sock" for a unix domain socket (then port is unused).



165
 
# File 'lib/kino/configuration.rb', line 165

def bind(host) = @config.set(:bind, host)

#control_bind(addr) ⇒ Object

Serve the read-only control plane (live stats as JSON at /stats, Prometheus text at /metrics, /ready and /live probes) on this address: "host:port" or "unix://path". Off unless set.



247
 
# File 'lib/kino/configuration.rb', line 247

def control_bind(addr) = @config.set(:control_bind, addr.to_s)

#control_token(token) ⇒ Object

When set, /stats and /metrics require "Authorization: Bearer ". The probes stay open; they carry no data.



251
 
# File 'lib/kino/configuration.rb', line 251

def control_token(token) = @config.set(:control_token, token.to_s)

#environment(env) ⇒ Object

Sets RACK_ENV (unless already set) before the CLI loads the app.



239
 
# File 'lib/kino/configuration.rb', line 239

def environment(env) = @config.set(:environment, env.to_s)

#lanes(enabled) ⇒ Object

EXPERIMENTAL per-worker lane dispatch.



201
 
# File 'lib/kino/configuration.rb', line 201

def lanes(enabled) = @config.set(:lanes, !!enabled)

#log_requests(enabled) ⇒ Object

Native access log: one status-colored line per request to stdout.



204
 
# File 'lib/kino/configuration.rb', line 204

def log_requests(enabled) = @config.set(:log_requests, !!enabled)

#max_body_size(bytes) ⇒ Object

Max request-body bytes before a 413; nil disables (delegate to a fronting proxy). Default 50 MB.



195
 
# File 'lib/kino/configuration.rb', line 195

def max_body_size(bytes) = @config.set(:max_body_size, bytes && Integer(bytes))

#max_connections(count) ⇒ Object

Max connections served at once; beyond it, new connections wait in the kernel backlog. Defaults to most of the open-file limit.



191
 
# File 'lib/kino/configuration.rb', line 191

def max_connections(count) = @config.set(:max_connections, Integer(count))

#mode(mode) ⇒ Object

Dispatch mode: :auto, :ractor, or :threaded.



178
 
# File 'lib/kino/configuration.rb', line 178

def mode(mode) = @config.set(:mode, mode.to_sym)

#on_error(handler = nil, &block) ⇒ Object

Called with (exception, env) when a worker catches an app or delivery error; wire your error tracker here. Takes a callable or a block. Must be Ractor-shareable in :ractor mode.



209
 
# File 'lib/kino/configuration.rb', line 209

def on_error(handler = nil, &block) = @config.set(:on_error, handler || block)

#on_worker_exit(handler = nil, &block) ⇒ Object

Called on the main thread when a worker exits, with (worker_index, error_or_nil). error is the crash cause, or nil on a clean exit.



227
 
# File 'lib/kino/configuration.rb', line 227

def on_worker_exit(handler = nil, &block) = @config.set(:on_worker_exit, handler || block)

#pidfile(path) ⇒ Object

Write the master PID here on start.



242
 
# File 'lib/kino/configuration.rb', line 242

def pidfile(path) = @config.set(:pidfile, path.to_s)

#port(port) ⇒ Object

Port to listen on; 0 picks an ephemeral port.



168
 
# File 'lib/kino/configuration.rb', line 168

def port(port) = @config.set(:port, Integer(port))

#quarantine_max(count) ⇒ Object

Cap on the total number of replacement events over the process lifetime. Past the cap the monitor stops replacing and the server runs at reduced capacity. Default: the worker count in :ractor mode, workers x threads in :threaded.

Raises:

  • (ArgumentError) 


269
270
271
272
273
 
# File 'lib/kino/configuration.rb', line 269

def quarantine_max(count)
  count = Integer(count)
  raise ArgumentError, "quarantine_max must be >= 1 (got #{count})" if count < 1
  @config.set(:quarantine_max, count)
end

#quarantine_timeout(seconds) ⇒ Object

Quarantine a dispatch slot whose current request has run longer than this many seconds, spawning a replacement to restore capacity. Off unless set. Set it above your slowest legitimate endpoint (and typically above request_timeout).



257
258
259
260
261
262
263
 
# File 'lib/kino/configuration.rb', line 257

def quarantine_timeout(seconds)
  seconds &&= Float(seconds)
  if seconds && seconds <= 0
    raise ArgumentError, "quarantine_timeout must be greater than 0 (got #{seconds})"
  end
  @config.set(:quarantine_timeout, seconds)
end

#queue_depth(depth) ⇒ Object

Bounded request-queue depth; overflow earns clients a 503.



181
 
# File 'lib/kino/configuration.rb', line 181

def queue_depth(depth) = @config.set(:queue_depth, Integer(depth))

#queue_timeout(seconds) ⇒ Object

Seconds a request may wait for queue space before the 503.



184
 
# File 'lib/kino/configuration.rb', line 184

def queue_timeout(seconds) = @config.set(:queue_timeout, Float(seconds))

#rackup(path) ⇒ Object

Rackup file the kino CLI loads (positional argument wins).



276
 
# File 'lib/kino/configuration.rb', line 276

def rackup(path) = @config.set(:rackup, path.to_s)

#request_timeout(seconds) ⇒ Object

Seconds the app gets before the client receives a 504; nil = off.



187
 
# File 'lib/kino/configuration.rb', line 187

def request_timeout(seconds) = @config.set(:request_timeout, seconds && Float(seconds))

#shutdown_timeout(seconds) ⇒ Object

Graceful-shutdown drain deadline in seconds.



230
 
# File 'lib/kino/configuration.rb', line 230

def shutdown_timeout(seconds) = @config.set(:shutdown_timeout, seconds)

#threads(count) ⇒ Object

Threads per worker (I/O concurrency inside one ractor); default is mode-dependent: 1 in :ractor mode, 3 in :threaded.



175
 
# File 'lib/kino/configuration.rb', line 175

def threads(count) = @config.set(:threads, Integer(count))

#tls(cert:, key:) ⇒ Object

TLS termination; file paths or inline PEM strings.



236
 
# File 'lib/kino/configuration.rb', line 236

def tls(cert:, key:) = @config.set(:tls, {cert: cert, key: key})

#tokio_threads(count) ⇒ Object

Threads for the tokio (Rust I/O) runtime; default: one per core.



233
 
# File 'lib/kino/configuration.rb', line 233

def tokio_threads(count) = @config.set(:tokio_threads, Integer(count))

#workers(count) ⇒ Object

Worker count (ractors in :ractor mode); defaults to CPU cores.



171
 
# File 'lib/kino/configuration.rb', line 171

def workers(count) = @config.set(:workers, Integer(count))