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)
max_workers 32      # elastic pool ceiling; unset = fixed pool
scale_down_after 30 # seconds idle before an extra worker retires
threads 3           # threads per worker
mode :ractor        # :auto | :ractor | :threaded
queue_depth 2048
queue_timeout 0.5
shutdown_timeout 15
io_shards true
io_threads 6
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.



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

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).



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

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.



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

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).



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

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).



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

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).



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

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.



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

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.



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

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.



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

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

#http2(enabled = true) ⇒ Object

HTTP/2: negotiated via ALPN on TLS binds, served to prior-knowledge clients on plaintext. On by default; set false to serve HTTP/1 only.



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

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

#io_shards(enabled = true) ⇒ Object

Run native HTTP I/O on current-thread shards instead of Tokio's shared pool.



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

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

#io_threads(count) ⇒ Object

Native HTTP I/O shard count; default with io_shards: half available CPUs.



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

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

#lanes(enabled) ⇒ Object

EXPERIMENTAL per-worker lane dispatch.



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

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

#log_requests(enabled) ⇒ Object

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



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

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.



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

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.



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

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

#max_workers(count) ⇒ Object

Pool ceiling: under sustained queue pressure the pool grows past workers, one worker at a time, up to this many. Unset (the default) keeps the pool fixed at workers.



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

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

#mode(mode) ⇒ Object

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



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

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.



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

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.



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

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

#pidfile(path) ⇒ Object

Write the master PID here on start.



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

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

#port(port) ⇒ Object

Port to listen on; 0 picks an ephemeral port.



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

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) 


299
300
301
302
303
 
# File 'lib/kino/configuration.rb', line 299

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).



287
288
289
290
291
292
293
 
# File 'lib/kino/configuration.rb', line 287

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.



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

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.



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

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

#rackup(path) ⇒ Object

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



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

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.



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

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

#scale_down_after(seconds) ⇒ Object

Seconds a worker above the floor must sit idle before it is retired (default 30). Only meaningful with max_workers.



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

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

#shutdown_timeout(seconds) ⇒ Object

Graceful-shutdown drain deadline in seconds.



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

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.



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

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

#tls(cert:, key:) ⇒ Object

TLS termination; file paths or inline PEM strings.



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

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.



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

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

#workers(count) ⇒ Object

Worker count (ractors in :ractor mode); defaults to CPU cores. The pool floor when max_workers is set.



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

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