Class: Puma::DSL
Overview
The methods that are available for use inside the config file.
Constant Summary
Constants included from ConfigDefault
ConfigDefault::DefaultRackup, ConfigDefault::DefaultTCPHost, ConfigDefault::DefaultTCPPort, ConfigDefault::DefaultWorkerShutdownTimeout, ConfigDefault::DefaultWorkerTimeout
Class Method Summary collapse
Instance Method Summary collapse
- #_load_from(path) ⇒ Object
- #_offer_plugins ⇒ Object
- #_run(&blk) ⇒ Object
-
#activate_control_app(url = "auto", opts = {}) ⇒ Object
Start the Puma control rack app on
url
. -
#after_worker_fork(&block) ⇒ Object
(also: #after_worker_boot)
*Cluster mode only* Code to run in the master after it starts a worker.
-
#app(obj = nil, &block) ⇒ Object
Use
obj
orblock
as the Rack app. -
#before_fork(&block) ⇒ Object
*Cluster mode only* Code to run immediately before master process forks workers (once on boot).
-
#bind(url) ⇒ Object
Bind the server to
url
. -
#clean_thread_locals(which = true) ⇒ Object
Work around leaky apps that leave garbage in Thread locals across requests.
-
#daemonize(which = true) ⇒ Object
Daemonize the server into the background.
-
#debug ⇒ Object
Show debugging info.
-
#directory(dir) ⇒ Object
The directory to operate out of.
-
#drain_on_shutdown(which = true) ⇒ Object
When shutting down, drain the accept socket of pending connections and proces them.
-
#environment(environment) ⇒ Object
Set the environment in which the Rack’s app will run.
-
#force_shutdown_after(val = :forever) ⇒ Object
How long to wait for threads to stop when shutting them down.
- #get(key, default = nil) ⇒ Object
-
#import(file) ⇒ Object
Load configuration from another named file.
-
#initialize(options, config) ⇒ DSL
constructor
A new instance of DSL.
- #inject(&blk) ⇒ Object
-
#load(file) ⇒ Object
Load additional configuration from a file.
-
#log_requests(which = true) ⇒ Object
Enable request logging.
-
#lowlevel_error_handler(obj = nil, &block) ⇒ Object
Use
obj
orblock
as the low level error handler. -
#on_restart(&block) ⇒ Object
Code to run before doing a restart.
-
#on_worker_boot(&block) ⇒ Object
*Cluster mode only* Code to run in a worker when it boots to setup the process before booting the app.
-
#on_worker_fork(&block) ⇒ Object
*Cluster mode only* Code to run in the master when it is about to create the worker by forking itself.
-
#on_worker_shutdown(&block) ⇒ Object
*Cluster mode only* Code to run immediately before a worker shuts down (after it has finished processing HTTP requests).
-
#persistent_timeout(seconds) ⇒ Object
Define how long persistent connections can be idle before puma closes them.
-
#pidfile(path) ⇒ Object
Store the pid of the server in the file at
path
. -
#plugin(name) ⇒ Object
Load the named plugin for use by this configuration.
-
#port(port, host = nil) ⇒ Object
Define the TCP port to bind to.
-
#preload_app!(answer = true) ⇒ Object
*Cluster mode only* Preload the application before starting the workers and setting up the listen ports.
-
#prune_bundler(answer = true) ⇒ Object
This option is used to allow your app and its gems to be properly reloaded when not using preload.
-
#queue_requests(answer = true) ⇒ Object
When set to true (the default), workers accept all requests and queue them before passing them to the handlers.
-
#quiet(which = true) ⇒ Object
Disable request logging.
-
#rackup(path) ⇒ Object
Load
path
as a rackup file. -
#restart_command(cmd) ⇒ Object
Command to use to restart puma.
-
#set_remote_address(val = :socket) ⇒ Object
Control how the remote address of the connection is set.
-
#shutdown_debug(val = true) ⇒ Object
When a shutdown is requested, the backtraces of all the threads will be written to $stdout.
- #ssl_bind(host, port, opts) ⇒ Object
-
#state_path(path) ⇒ Object
Use
path
as the file to store the server info state. -
#stdout_redirect(stdout = nil, stderr = nil, append = false) ⇒ Object
Redirect STDOUT and STDERR to files specified.
-
#tag(string) ⇒ Object
Additional text to display in process listing.
-
#tcp_mode ⇒ Object
Run the app as a raw TCP app instead of an HTTP rack app.
-
#tcp_mode! ⇒ Object
Run Puma in TCP mode.
-
#threads(min, max) ⇒ Object
Configure
min
to be the minimum number of threads to use to answer requests andmax
the maximum. -
#worker_boot_timeout(timeout) ⇒ Object
*Cluster mode only* Set the timeout for workers to boot.
-
#worker_directory(dir) ⇒ Object
DEPRECATED: The directory to operate out of.
-
#worker_shutdown_timeout(timeout) ⇒ Object
*Cluster mode only* Set the timeout for worker shutdown.
-
#worker_timeout(timeout) ⇒ Object
*Cluster mode only* Set the timeout for workers in seconds When set the master process will terminate any workers that have not checked in within the given
timeout
. -
#workers(count) ⇒ Object
*Cluster mode only* How many worker processes to run.
Constructor Details
#initialize(options, config) ⇒ DSL
Returns a new instance of DSL.
16 17 18 19 20 21 |
# File 'lib/puma/dsl.rb', line 16 def initialize(, config) @config = config @options = @plugins = [] end |
Class Method Details
.load(options, cfg, path) ⇒ Object
7 8 9 10 11 12 13 14 |
# File 'lib/puma/dsl.rb', line 7 def self.load(, cfg, path) d = new(, cfg) d._load_from(path) ensure d._offer_plugins end |
Instance Method Details
#_load_from(path) ⇒ Object
23 24 25 26 27 28 29 30 |
# File 'lib/puma/dsl.rb', line 23 def _load_from(path) if path @path = path instance_eval(File.read(path), path, 1) end ensure _offer_plugins end |
#_offer_plugins ⇒ Object
32 33 34 35 36 37 38 39 40 41 |
# File 'lib/puma/dsl.rb', line 32 def _offer_plugins @plugins.each do |o| if o.respond_to? :config @options.shift o.config self end end @plugins.clear end |
#_run(&blk) ⇒ Object
43 44 45 46 47 |
# File 'lib/puma/dsl.rb', line 43 def _run(&blk) blk.call self ensure _offer_plugins end |
#activate_control_app(url = "auto", opts = {}) ⇒ Object
Start the Puma control rack app on url
. This app can be communicated with to control the main server.
97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 |
# File 'lib/puma/dsl.rb', line 97 def activate_control_app(url="auto", opts={}) if url == "auto" path = Configuration.temp_path @options[:control_url] = "unix://#{path}" @options[:control_url_temp] = path else @options[:control_url] = url end if opts[:no_token] auth_token = :none else auth_token = opts[:auth_token] auth_token ||= Configuration.random_token end @options[:control_auth_token] = auth_token @options[:control_url_umask] = opts[:umask] if opts[:umask] end |
#after_worker_fork(&block) ⇒ Object Also known as: after_worker_boot
*Cluster mode only* Code to run in the master after it starts a worker.
This can be called multiple times to add hooks.
337 338 339 |
# File 'lib/puma/dsl.rb', line 337 def after_worker_fork(&block) _ary(:after_worker_fork) << 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.
86 87 88 89 90 91 92 |
# File 'lib/puma/dsl.rb', line 86 def app(obj=nil, &block) obj ||= block raise "Provide either a #call'able or a block" unless obj @options[:app] = obj end |
#before_fork(&block) ⇒ Object
*Cluster mode only* Code to run immediately before master process forks workers (once on boot). These hooks can block if necessary to wait for background operations unknown to puma to finish before the process terminates. This can be used to close any connections to remote servers (database, redis, …) that were opened when preloading the code
This can be called multiple times to add hooks.
299 300 301 |
# File 'lib/puma/dsl.rb', line 299 def before_fork(&block) _ary(:before_fork) << block end |
#bind(url) ⇒ Object
Bind the server to url
. tcp:// and unix:// are the only accepted protocols.
125 126 127 |
# File 'lib/puma/dsl.rb', line 125 def bind(url) _ary(:binds) << url end |
#clean_thread_locals(which = true) ⇒ Object
Work around leaky apps that leave garbage in Thread locals across requests
146 147 148 |
# File 'lib/puma/dsl.rb', line 146 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
.
152 153 154 |
# File 'lib/puma/dsl.rb', line 152 def daemonize(which=true) @options[:daemon] = which end |
#debug ⇒ Object
Show debugging info
225 226 227 |
# File 'lib/puma/dsl.rb', line 225 def debug @options[:debug] = true end |
#directory(dir) ⇒ Object
The directory to operate out of.
344 345 346 |
# File 'lib/puma/dsl.rb', line 344 def directory(dir) @options[: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.
160 161 162 |
# File 'lib/puma/dsl.rb', line 160 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.
165 166 167 |
# File 'lib/puma/dsl.rb', line 165 def environment(environment) @options[:environment] = environment end |
#force_shutdown_after(val = :forever) ⇒ Object
How long to wait for threads to stop when shutting them down. Defaults to :forever. Specifying :immediately will cause Puma to kill the threads immediately. Otherwise the value is the number of seconds to wait.
Puma always waits a few seconds after killing a thread for it to try to finish up it’s work, even in :immediately mode.
176 177 178 179 180 181 182 183 184 185 186 187 |
# File 'lib/puma/dsl.rb', line 176 def force_shutdown_after(val=:forever) i = case val when :forever -1 when :immediately 0 else Integer(val) end @options[:force_shutdown_after] = i end |
#get(key, default = nil) ⇒ Object
73 74 75 |
# File 'lib/puma/dsl.rb', line 73 def get(key,default=nil) @options[key.to_sym] || default end |
#import(file) ⇒ Object
Load configuration from another named file. If the file name is absolute, load the file as an absolute path. Otherwise load it relative to the current config file.
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 |
# File 'lib/puma/dsl.rb', line 57 def import(file) if File.extname(file) == "" file += ".rb" end if file[0,1] == "/" path = file elsif @path path = File.join File.dirname(@path), file else raise "No original configuration path to import relative to" end DSL.new(@options, @config)._load_from(path) end |
#inject(&blk) ⇒ Object
49 50 51 |
# File 'lib/puma/dsl.rb', line 49 def inject(&blk) instance_eval(&blk) end |
#load(file) ⇒ Object
Load additional configuration from a file
118 119 120 |
# File 'lib/puma/dsl.rb', line 118 def load(file) _ary(:config_files) << file end |
#log_requests(which = true) ⇒ Object
Enable request logging
219 220 221 |
# File 'lib/puma/dsl.rb', line 219 def log_requests(which=true) @options[:log_requests] = which 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.
370 371 372 373 374 |
# File 'lib/puma/dsl.rb', line 370 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.
194 195 196 |
# File 'lib/puma/dsl.rb', line 194 def on_restart(&block) _ary(:on_restart) << block end |
#on_worker_boot(&block) ⇒ Object
*Cluster mode only* Code to run in a worker when it boots to setup the process before booting the app.
This can be called multiple times to add hooks.
308 309 310 |
# File 'lib/puma/dsl.rb', line 308 def on_worker_boot(&block) _ary(:before_worker_boot) << block end |
#on_worker_fork(&block) ⇒ Object
*Cluster mode only* Code to run in the master when it is about to create the worker by forking itself.
This can be called multiple times to add hooks.
328 329 330 |
# File 'lib/puma/dsl.rb', line 328 def on_worker_fork(&block) _ary(:before_worker_fork) << 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.
319 320 321 |
# File 'lib/puma/dsl.rb', line 319 def on_worker_shutdown(&block) _ary(:before_worker_shutdown) << block end |
#persistent_timeout(seconds) ⇒ Object
Define how long persistent connections can be idle before puma closes them
139 140 141 |
# File 'lib/puma/dsl.rb', line 139 def persistent_timeout(seconds) @options[:persistent_timeout] = seconds end |
#pidfile(path) ⇒ Object
Store the pid of the server in the file at path
.
207 208 209 |
# File 'lib/puma/dsl.rb', line 207 def pidfile(path) @options[:pidfile] = path.to_s end |
#plugin(name) ⇒ Object
Load the named plugin for use by this configuration
79 80 81 |
# File 'lib/puma/dsl.rb', line 79 def plugin(name) @plugins << @config.load_plugin(name) end |
#port(port, host = nil) ⇒ Object
Define the TCP port to bind to. Use bind
for more advanced options.
131 132 133 134 |
# File 'lib/puma/dsl.rb', line 131 def port(port, host=nil) host ||= Configuration::DefaultTCPHost bind "tcp://#{host}:#{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.
363 364 365 |
# File 'lib/puma/dsl.rb', line 363 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.
388 389 390 |
# File 'lib/puma/dsl.rb', line 388 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.
428 429 430 |
# File 'lib/puma/dsl.rb', line 428 def queue_requests(answer=true) @options[:queue_requests] = answer end |
#quiet(which = true) ⇒ Object
Disable request logging.
213 214 215 |
# File 'lib/puma/dsl.rb', line 213 def quiet(which=true) @options[:log_requests] = !which end |
#rackup(path) ⇒ Object
Load path
as a rackup file.
231 232 233 |
# File 'lib/puma/dsl.rb', line 231 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.
202 203 204 |
# File 'lib/puma/dsl.rb', line 202 def restart_command(cmd) @options[:restart_cmd] = cmd.to_s end |
#set_remote_address(val = :socket) ⇒ Object
Control how the remote address of the connection is set. This is configurable because to calculate the true socket peer address a kernel syscall is required which for very fast rack handlers slows down the handling significantly.
There are 4 possible values:
-
:socket (the default) - read the peername from the socket using the
syscall. This is the normal behavior.
-
:localhost - set the remote address to “127.0.0.1”
-
header: http_header - set the remote address to the value of the
provided http header. For instance: `set_remote_address header: "X-Real-IP"`. Only the first word (as separated by spaces or comma) is used, allowing headers such as X-Forwarded-For to be used as well.
-
Any string - this allows you to hardcode remote address to any value
you wish. Because puma never uses this field anyway, it's format is entirely in your hands.
458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 |
# File 'lib/puma/dsl.rb', line 458 def set_remote_address(val=:socket) case val when :socket @options[:remote_address] = val when :localhost @options[:remote_address] = :value @options[:remote_address_value] = "127.0.0.1".freeze when String @options[:remote_address] = :value @options[:remote_address_value] = val when Hash if hdr = val[:header] @options[:remote_address] = :header @options[:remote_address_header] = "HTTP_" + hdr.upcase.gsub("-", "_") else raise "Invalid value for set_remote_address - #{val.inspect}" end else raise "Invalid value for set_remote_address - #{val}" end end |
#shutdown_debug(val = true) ⇒ Object
When a shutdown is requested, the backtraces of all the threads will be written to $stdout. This can help figure out why shutdown is hanging.
435 436 437 |
# File 'lib/puma/dsl.rb', line 435 def shutdown_debug(val=true) @options[:shutdown_debug] = val end |
#ssl_bind(host, port, opts) ⇒ Object
266 267 268 269 270 271 272 273 274 275 |
# File 'lib/puma/dsl.rb', line 266 def ssl_bind(host, port, opts) verify = opts.fetch(:verify_mode, 'none') if defined?(JRUBY_VERSION) keystore_additions = "keystore=#{opts[:keystore]}&keystore-pass=#{opts[:keystore_pass]}" bind "ssl://#{host}:#{port}?cert=#{opts[:cert]}&key=#{opts[:key]}&#{keystore_additions}&verify_mode=#{verify}" else bind "ssl://#{host}:#{port}?cert=#{opts[:cert]}&key=#{opts[:key]}&verify_mode=#{verify}" end 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.
280 281 282 |
# File 'lib/puma/dsl.rb', line 280 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.
242 243 244 245 246 |
# File 'lib/puma/dsl.rb', line 242 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
393 394 395 |
# File 'lib/puma/dsl.rb', line 393 def tag(string) @options[:tag] = string.to_s end |
#tcp_mode ⇒ Object
Run the app as a raw TCP app instead of an HTTP rack app
355 356 357 |
# File 'lib/puma/dsl.rb', line 355 def tcp_mode @options[:mode] = :tcp end |
#tcp_mode! ⇒ Object
Run Puma in TCP mode
237 238 239 |
# File 'lib/puma/dsl.rb', line 237 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.
251 252 253 254 255 256 257 258 259 260 261 262 263 264 |
# File 'lib/puma/dsl.rb', line 251 def threads(min, max) min = Integer(min) max = Integer(max) if min > max raise "The minimum (#{min}) number of threads must be less than or equal to the max (#{max})" end if max < 1 raise "The maximum number of threads (#{max}) must be greater than 0" end @options[:min_threads] = min @options[:max_threads] = max end |
#worker_boot_timeout(timeout) ⇒ Object
*Cluster mode only* Set the timeout for workers to boot
406 407 408 |
# File 'lib/puma/dsl.rb', line 406 def worker_boot_timeout(timeout) @options[:worker_boot_timeout] = timeout end |
#worker_directory(dir) ⇒ Object
DEPRECATED: The directory to operate out of.
349 350 351 352 |
# File 'lib/puma/dsl.rb', line 349 def worker_directory(dir) $stderr.puts "worker_directory is deprecated. Please use `directory`" directory dir end |
#worker_shutdown_timeout(timeout) ⇒ Object
*Cluster mode only* Set the timeout for worker shutdown
411 412 413 |
# File 'lib/puma/dsl.rb', line 411 def worker_shutdown_timeout(timeout) @options[:worker_shutdown_timeout] = timeout end |
#worker_timeout(timeout) ⇒ Object
*Cluster mode only* Set the timeout for workers in seconds When set the master process will terminate any workers that have not checked in within the given timeout
. This mitigates hung processes. Default value is 60 seconds.
401 402 403 |
# File 'lib/puma/dsl.rb', line 401 def worker_timeout(timeout) @options[:worker_timeout] = timeout end |
#workers(count) ⇒ Object
*Cluster mode only* How many worker processes to run.
286 287 288 |
# File 'lib/puma/dsl.rb', line 286 def workers(count) @options[:workers] = count.to_i end |