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).
-
#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.
328 329 330 |
# File 'lib/puma/dsl.rb', line 328 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.
290 291 292 |
# File 'lib/puma/dsl.rb', line 290 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
139 140 141 |
# File 'lib/puma/dsl.rb', line 139 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
.
145 146 147 |
# File 'lib/puma/dsl.rb', line 145 def daemonize(which=true) @options[:daemon] = which end |
#debug ⇒ Object
Show debugging info
218 219 220 |
# File 'lib/puma/dsl.rb', line 218 def debug @options[:debug] = true end |
#directory(dir) ⇒ Object
The directory to operate out of.
335 336 337 |
# File 'lib/puma/dsl.rb', line 335 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.
153 154 155 |
# File 'lib/puma/dsl.rb', line 153 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.
158 159 160 |
# File 'lib/puma/dsl.rb', line 158 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.
169 170 171 172 173 174 175 176 177 178 179 180 |
# File 'lib/puma/dsl.rb', line 169 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
212 213 214 |
# File 'lib/puma/dsl.rb', line 212 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.
361 362 363 364 365 |
# File 'lib/puma/dsl.rb', line 361 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.
187 188 189 |
# File 'lib/puma/dsl.rb', line 187 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.
299 300 301 |
# File 'lib/puma/dsl.rb', line 299 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.
319 320 321 |
# File 'lib/puma/dsl.rb', line 319 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.
310 311 312 |
# File 'lib/puma/dsl.rb', line 310 def on_worker_shutdown(&block) _ary(:before_worker_shutdown) << block end |
#pidfile(path) ⇒ Object
Store the pid of the server in the file at path
.
200 201 202 |
# File 'lib/puma/dsl.rb', line 200 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.
354 355 356 |
# File 'lib/puma/dsl.rb', line 354 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.
379 380 381 |
# File 'lib/puma/dsl.rb', line 379 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.
419 420 421 |
# File 'lib/puma/dsl.rb', line 419 def queue_requests(answer=true) @options[:queue_requests] = answer end |
#quiet(which = true) ⇒ Object
Disable request logging.
206 207 208 |
# File 'lib/puma/dsl.rb', line 206 def quiet(which=true) @options[:log_requests] = !which end |
#rackup(path) ⇒ Object
Load path
as a rackup file.
224 225 226 |
# File 'lib/puma/dsl.rb', line 224 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.
195 196 197 |
# File 'lib/puma/dsl.rb', line 195 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.
449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 |
# File 'lib/puma/dsl.rb', line 449 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.
426 427 428 |
# File 'lib/puma/dsl.rb', line 426 def shutdown_debug(val=true) @options[:shutdown_debug] = val end |
#ssl_bind(host, port, opts) ⇒ Object
259 260 261 262 263 264 265 266 |
# File 'lib/puma/dsl.rb', line 259 def ssl_bind(host, port, opts) 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}" else bind "ssl://#{host}:#{port}?cert=#{opts[:cert]}&key=#{opts[:key]}" 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.
271 272 273 |
# File 'lib/puma/dsl.rb', line 271 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.
235 236 237 238 239 |
# File 'lib/puma/dsl.rb', line 235 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
384 385 386 |
# File 'lib/puma/dsl.rb', line 384 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
346 347 348 |
# File 'lib/puma/dsl.rb', line 346 def tcp_mode @options[:mode] = :tcp end |
#tcp_mode! ⇒ Object
Run Puma in TCP mode
230 231 232 |
# File 'lib/puma/dsl.rb', line 230 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.
244 245 246 247 248 249 250 251 252 253 254 255 256 257 |
# File 'lib/puma/dsl.rb', line 244 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
397 398 399 |
# File 'lib/puma/dsl.rb', line 397 def worker_boot_timeout(timeout) @options[:worker_boot_timeout] = timeout end |
#worker_directory(dir) ⇒ Object
DEPRECATED: The directory to operate out of.
340 341 342 343 |
# File 'lib/puma/dsl.rb', line 340 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
402 403 404 |
# File 'lib/puma/dsl.rb', line 402 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.
392 393 394 |
# File 'lib/puma/dsl.rb', line 392 def worker_timeout(timeout) @options[:worker_timeout] = timeout end |
#workers(count) ⇒ Object
*Cluster mode only* How many worker processes to run.
277 278 279 |
# File 'lib/puma/dsl.rb', line 277 def workers(count) @options[:workers] = count.to_i end |