Class: Puma::Configuration::DSL

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

Overview

The methods that are available for use inside the config file.

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ DSL



176
177
178
# File 'lib/puma/configuration.rb', line 176

def initialize(options)
  @options = options
end

Instance Method Details

#_load_from(path) ⇒ Object



180
181
182
# File 'lib/puma/configuration.rb', line 180

def _load_from(path)
  instance_eval File.read(path), path, 1
end

#activate_control_app(url = "auto", opts = nil) ⇒ Object

Start the Puma control rack app on url. This app can be communicated with to control the main server.



198
199
200
201
202
203
204
205
206
207
208
209
210
# File 'lib/puma/configuration.rb', line 198

def activate_control_app(url="auto", opts=nil)
  @options[:control_url] = url

  if opts
    if tok = opts[:auth_token]
      @options[:control_auth_token] = tok
    end

    if opts[:no_token]
      @options[:control_auth_token] = :none
    end
  end
end

#after_worker_boot(&block) ⇒ Object

*Cluster mode only* Code to run when a worker boots to setup the process after booting the app.

This can be called multiple times to add hooks.



353
354
355
# File 'lib/puma/configuration.rb', line 353

def after_worker_boot(&block)
  @options[:after_worker_boot] << block
end

#app(obj = nil, &block) ⇒ Object

Use obj or block as the Rack app. This allows a config file to be the app itself.



187
188
189
190
191
192
193
# File 'lib/puma/configuration.rb', line 187

def app(obj=nil, &block)
  obj ||= block

  raise "Provide either a #call'able or a block" unless obj

  @options[:app] = obj
end

#bind(url) ⇒ Object

Bind the server to url. tcp:// and unix:// are the only accepted protocols.



215
216
217
# File 'lib/puma/configuration.rb', line 215

def bind(url)
  @options[:binds] << url
end

#clean_thread_locals(which = true) ⇒ Object

Work around leaky apps that leave garbage in Thread locals across requests



228
229
230
# File 'lib/puma/configuration.rb', line 228

def clean_thread_locals(which=true)
  @options[:clean_thread_locals] = which
end

#daemonize(which = true) ⇒ Object

Daemonize the server into the background. Highly suggest that this be combined with pidfile and stdout_redirect.



234
235
236
# File 'lib/puma/configuration.rb', line 234

def daemonize(which=true)
  @options[:daemon] = which
end

#directory(dir) ⇒ Object

The directory to operate out of.



358
359
360
361
# File 'lib/puma/configuration.rb', line 358

def directory(dir)
  @options[:directory] = dir.to_s
  @options[:worker_directory] = dir.to_s
end

#drain_on_shutdown(which = true) ⇒ Object

When shutting down, drain the accept socket of pending connections and proces them. This loops over the accept socket until there are no more read events and then stops looking and waits for the requests to finish.



242
243
244
# File 'lib/puma/configuration.rb', line 242

def drain_on_shutdown(which=true)
  @options[:drain_on_shutdown] = which
end

#environment(environment) ⇒ Object

Set the environment in which the Rack's app will run.



247
248
249
# File 'lib/puma/configuration.rb', line 247

def environment(environment)
  @options[:environment] = environment
end

#lowlevel_error_handler(obj = nil, &block) ⇒ Object

Use obj or block as the low level error handler. This allows a config file to change the default error on the server.



379
380
381
382
383
# File 'lib/puma/configuration.rb', line 379

def lowlevel_error_handler(obj=nil, &block)
  obj ||= block
  raise "Provide either a #call'able or a block" unless obj
  @options[:lowlevel_error_handler] = obj
end

#on_restart(&block) ⇒ Object

Code to run before doing a restart. This code should close logfiles, database connections, etc.

This can be called multiple times to add code each time.



256
257
258
# File 'lib/puma/configuration.rb', line 256

def on_restart(&block)
  @options[:on_restart] << block
end

#on_worker_boot(&block) ⇒ Object

*Cluster mode only* Code to run when a worker boots to setup the process before booting the app.

This can be called multiple times to add hooks.



344
345
346
# File 'lib/puma/configuration.rb', line 344

def on_worker_boot(&block)
  @options[:before_worker_boot] << block
end

#on_worker_shutdown(&block) ⇒ Object

*Cluster mode only* Code to run immediately before a worker shuts down (after it has finished processing HTTP requests). These hooks can block if necessary to wait for background operations unknown to puma to finish before the process terminates.

This can be called multiple times to add hooks.



335
336
337
# File 'lib/puma/configuration.rb', line 335

def on_worker_shutdown(&block)
  @options[:before_worker_shutdown] << block
end

#pidfile(path) ⇒ Object

Store the pid of the server in the file at path.



269
270
271
# File 'lib/puma/configuration.rb', line 269

def pidfile(path)
  @options[:pidfile] = path
end

#port(port) ⇒ Object

Define the TCP port to bind to. Use bind for more advanced options.



221
222
223
# File 'lib/puma/configuration.rb', line 221

def port(port)
  @options[:binds] << "tcp://#{Configuration::DefaultTCPHost}:#{port}"
end

#preload_app!(answer = true) ⇒ Object

*Cluster mode only* Preload the application before starting the workers and setting up the listen ports. This conflicts with using the phased restart feature, you can't use both.



372
373
374
# File 'lib/puma/configuration.rb', line 372

def preload_app!(answer=true)
  @options[:preload_app] = answer
end

#prune_bundler(answer = true) ⇒ Object

This option is used to allow your app and its gems to be properly reloaded when not using preload.

When set, if puma detects that it's been invoked in the context of Bundler, it will cleanup the environment and re-run itself outside the Bundler environment, but directly using the files that Bundler has setup.

This means that puma is now decoupled from your Bundler context and when each worker loads, it will be loading a new Bundler context and thus can float around as the release dictates.



397
398
399
# File 'lib/puma/configuration.rb', line 397

def prune_bundler(answer=true)
  @options[:prune_bundler] = answer
end

#queue_requests(answer = true) ⇒ Object

When set to true (the default), workers accept all requests and queue them before passing them to the handlers. When set to false, each worker process accepts exactly as many requests as it is configured to simultaneously handle.

Queueing requests generally improves performance. In some cases, such as a single threaded application, it may be better to ensure requests get balanced across workers.

Note that setting this to false disables HTTP keepalive and slow clients will occupy a handler thread while the request is being sent. A reverse proxy, such as nginx, can handle slow clients and queue requests before they reach puma.



429
430
431
# File 'lib/puma/configuration.rb', line 429

def queue_requests(answer=true)
  @options[:queue_requests] = answer
end

#quietObject

Disable request logging.



275
276
277
# File 'lib/puma/configuration.rb', line 275

def quiet
  @options[:quiet] = true
end

#rackup(path) ⇒ Object

Load path as a rackup file.



281
282
283
# File 'lib/puma/configuration.rb', line 281

def rackup(path)
  @options[:rackup] = path.to_s
end

#restart_command(cmd) ⇒ Object

Command to use to restart puma. This should be just how to load puma itself (ie. 'ruby -Ilib bin/puma'), not the arguments to puma, as those are the same as the original process.



264
265
266
# File 'lib/puma/configuration.rb', line 264

def restart_command(cmd)
  @options[:restart_cmd] = cmd
end

#ssl_bind(host, port, opts) ⇒ Object



306
307
308
309
310
311
312
313
# File 'lib/puma/configuration.rb', line 306

def ssl_bind(host, port, opts)
  o = [
    "cert=#{opts[:cert]}",
    "key=#{opts[:key]}"
  ]

  @options[:binds] << "ssl://#{host}:#{port}?#{o.join('&')}"
end

#state_path(path) ⇒ Object

Use path as the file to store the server info state. This is used by pumactl to query and control the server.



318
319
320
# File 'lib/puma/configuration.rb', line 318

def state_path(path)
  @options[:state] = path.to_s
end

#stdout_redirect(stdout = nil, stderr = nil, append = false) ⇒ Object

Redirect STDOUT and STDERR to files specified.



286
287
288
289
290
# File 'lib/puma/configuration.rb', line 286

def stdout_redirect(stdout=nil, stderr=nil, append=false)
  @options[:redirect_stdout] = stdout
  @options[:redirect_stderr] = stderr
  @options[:redirect_append] = append
end

#tag(string) ⇒ Object

Additional text to display in process listing



402
403
404
# File 'lib/puma/configuration.rb', line 402

def tag(string)
  @options[:tag] = string
end

#tcp_modeObject

Run the app as a raw TCP app instead of an HTTP rack app



364
365
366
# File 'lib/puma/configuration.rb', line 364

def tcp_mode
  @options[:mode] = :tcp
end

#threads(min, max) ⇒ Object

Configure min to be the minimum number of threads to use to answer requests and max the maximum.



295
296
297
298
299
300
301
302
303
304
# File 'lib/puma/configuration.rb', line 295

def threads(min, max)
  min = Integer(min)
  max = Integer(max)
  if min > max
    raise "The minimum (#{min}) number of threads must be less than the max (#{max})"
  end

  @options[:min_threads] = min
  @options[:max_threads] = max
end

#worker_shutdown_timeout(timeout) ⇒ Object

*Cluster mode only* Set the timeout for worker shutdown



412
413
414
# File 'lib/puma/configuration.rb', line 412

def worker_shutdown_timeout(timeout)
  @options[:worker_shutdown_timeout] = timeout
end

#worker_timeout(timeout) ⇒ Object

*Cluster mode only* Set the timeout for workers



407
408
409
# File 'lib/puma/configuration.rb', line 407

def worker_timeout(timeout)
  @options[:worker_timeout] = timeout
end

#workers(count) ⇒ Object

*Cluster mode only* How many worker processes to run.



324
325
326
# File 'lib/puma/configuration.rb', line 324

def workers(count)
  @options[:workers] = count.to_i
end