Class: Kino::Configuration

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

Overview

Server settings with Puma-style precedence:

explicit Server.new kwargs > config file DSL > defaults.

Defined Under Namespace

Classes: DSL

Constant Summary collapse

DEFAULTS =

Every setting and its default; the full reference lives in the generated sample config (kino --init).

{
  bind: "127.0.0.1",
  port: 0,
  workers: nil, # resolved to Kino.available_parallelism in #to_h
  max_workers: nil, # nil = fixed pool; above workers = elastic pool
  scale_down_after: nil, # resolved to 30 seconds in Server
  threads: nil, # resolved per mode in Server: 1 in :ractor, 3 in :threaded
  mode: :auto,
  queue_depth: 1024,
  queue_timeout: 5.0,
  request_timeout: nil,
  max_connections: nil, # nil = derive from the open-file limit
  max_body_size: 50 * 1024 * 1024, # 50 MB; nil/0 = unlimited
  batch: 1,
  lanes: false,
  log_requests: false,
  on_error: nil,
  after_boot: nil,
  after_worker_boot: nil,
  after_request_complete: nil,
  on_worker_exit: nil,
  shutdown_timeout: 30,
  io_shards: false,
  io_threads: nil,
  tokio_threads: nil,
  tls: nil,
  http2: true,
  environment: nil,
  pidfile: nil,
  control_bind: nil,
  control_token: nil,
  quarantine_timeout: nil,
  quarantine_max: nil,
  rackup: nil
}.freeze
SETTINGS =

The known setting names.

DEFAULTS.keys.freeze
SAMPLE_TEMPLATE =

Source template for sample.

File.expand_path("templates/kino.rb.tt", __dir__).freeze
DEFAULT_PATHS =

Where the kino CLI and the Rack handler look for a config file when none is named: the project root first, then the Rails-style config/.

%w[kino.rb config/kino.rb].freeze
DEFAULT_SERVING_PORT =

The port the CLI and the Rack handler serve on when neither a flag nor the file chose one (Server.new itself defaults to an ephemeral port, for embedding).

9292

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



88
89
90
 
# File 'lib/kino/configuration.rb', line 88

def initialize
  @values = {}
end

Class Method Details

.default_path ⇒ String?

The first of DEFAULT_PATHS that exists in the working directory.

Returns:

  • (String, nil) 


62
63
64
 
# File 'lib/kino/configuration.rb', line 62

def self.default_path
  DEFAULT_PATHS.find { |path| File.exist?(path) }
end

.sample ⇒ String

The fully-commented sample config (see kino --init).

Returns:

  • (String) 


68
69
70
 
# File 'lib/kino/configuration.rb', line 68

def self.sample
  File.read(SAMPLE_TEMPLATE)
end

.write_sample(path, force: false) ⇒ String

Write the sample config to path. Refuses to clobber an existing file unless force: true.

Parameters:

  • path (String)
  • force (Boolean) (defaults to: false) —

    overwrite an existing file

Returns:

  • (String) —

    the path written

Raises:

  • (Kino::Error) —

    when the file exists and force is false



79
80
81
82
83
84
85
86
 
# File 'lib/kino/configuration.rb', line 79

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

Instance Method Details

#[](key) ⇒ Object

Returns the explicit value, or the default.

Parameters:

  • key (Symbol) —

    a key from DEFAULTS

Returns:

  • (Object) —

    the explicit value, or the default



94
95
96
 
# File 'lib/kino/configuration.rb', line 94

def [](key)
  @values.fetch(key) { DEFAULTS.fetch(key) }
end

#load_file(path) ⇒ self

Load a config file (Ruby DSL) into this configuration.

Parameters:

  • path (String)

Returns:

  • (self)

Raises:



116
117
118
119
120
121
 
# File 'lib/kino/configuration.rb', line 116

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

#merge!(options) ⇒ self

Explicit kwargs win over everything already set.

Parameters:

  • options (Hash{Symbol => Object})

Returns:

  • (self) 


126
127
128
129
 
# File 'lib/kino/configuration.rb', line 126

def merge!(options)
  options.each { |key, value| set(key, value) }
  self
end

#server_options ⇒ Hash{Symbol => Object}

The settings Server.new accepts: everything except the keys only the CLI consumes (rackup file selection, RACK_ENV).

Returns:

  • (Hash{Symbol => Object}) 


141
142
143
 
# File 'lib/kino/configuration.rb', line 141

def server_options
  to_h.except(:rackup, :environment)
end

#set(key, value) ⇒ Object

Parameters:

  • key (Symbol) —

    a key from DEFAULTS

  • value (Object)

Raises:

  • (ArgumentError) —

    for unknown settings



101
102
103
104
105
 
# File 'lib/kino/configuration.rb', line 101

def set(key, value)
  raise ArgumentError, "unknown setting #{key.inspect}" unless DEFAULTS.key?(key)

  @values[key] = value
end

#set?(key) ⇒ Boolean

Returns whether the key was explicitly set.

Returns:

  • (Boolean) —

    whether the key was explicitly set



108
109
110
 
# File 'lib/kino/configuration.rb', line 108

def set?(key)
  @values.key?(key)
end

#to_h ⇒ Hash{Symbol => Object}

Returns every setting, defaults filled in.

Returns:

  • (Hash{Symbol => Object}) —

    every setting, defaults filled in



132
133
134
135
136
 
# File 'lib/kino/configuration.rb', line 132

def to_h
  SETTINGS.to_h { |key| [key, self[key]] }.tap do |h|
    h[:workers] ||= Kino.available_parallelism
  end
end