Class: Puma::DSL

### Home Classes Methods

### In Files

- lib/puma/dsl.rb

### Parent

Object

### Methods

- ::load
- ::new
- #_load_from
- #activate_control_app
- #after_worker_boot
- #app
- #before_fork
- #bind
- #clean_thread_locals
- #daemonize
- #directory
- #drain_on_shutdown
- #environment
- #lowlevel_error_handler
- #on_restart
- #on_worker_boot
- #on_worker_fork
- #on_worker_shutdown
- #pidfile
- #port
- #preload_app!
- #prune_bundler
- #queue_requests
- #quiet
- #rackup
- #restart_command
- #shutdown_debug
- #ssl_bind
- #state_path
- #stdout_redirect
- #tag
- #tcp_mode
- #threads
- #worker_shutdown_timeout
- #worker_timeout
- #workers

### Included Modules

- Puma::ConfigDefault

### Files

- Manifest.txt

### Class/Module Index

Quicksearch

- Puma
- Puma::App
- Puma::App::Status
- Puma::Binder
- Puma::CLI
- Puma::Client
- Puma::Cluster
- Puma::Cluster::Worker
- Puma::CommonLogger
- Puma::ConfigDefault
- Puma::Configuration
- Puma::Configuration::ConfigMiddleware
- Puma::ConnectionError
- Puma::Const
- Puma::ControlCLI
- Puma::DSL
- Puma::Delegation
- Puma::Events
- Puma::Events::DefaultFormatter
- Puma::Events::PidFormatter
- Puma::IOBuffer
- Puma::JRubyRestart
- Puma::JavaIOBuffer
- Puma::MiniSSL
- Puma::MiniSSL::Context
- Puma::MiniSSL::SSLError
- Puma::MiniSSL::Server
- Puma::MiniSSL::Socket
- Puma::NullIO
- Puma::Rack
- Puma::Rack::Builder
- Puma::Rack::Options
- Puma::Rack::URLMap
- Puma::Reactor
- Puma::Runner
- Puma::Server
- Puma::Single
- Puma::TCPLogger
- Puma::ThreadPool
- Puma::ThreadPool::AutoTrim
- Puma::ThreadPool::Reaper
- Puma::UnsupportedOption
- Puma::Util
- Puma::Util::HeaderHash
- OpenSSL
- OpenSSL::SSL
- OpenSSL::SSL::SSLServer
- Rack
- Rack::Handler
- Rack::Handler::Puma
- IO
- IO::WaitReadable
- Object
- Process
- String

No matching classes.

# Puma::DSL

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

### Public Class Methods

load(options, path) click to toggle source

    # File lib/puma/dsl.rb, line 7
    def self.load(options, path)
      new(options).tap do |obj|
        obj._load_from(path)
      end

      options
    end

new(options) click to toggle source

    # File lib/puma/dsl.rb, line 15
    def initialize(options)
      @options = options
    end

### Public Instance Methods

_load_from(path) click to toggle source

    # File lib/puma/dsl.rb, line 19
    def _load_from(path)
      instance_eval(File.read(path), path, 1) if path
    end

activate_control_app(url="auto", opts=nil) click to toggle source

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

    # File lib/puma/dsl.rb, line 37
    def activate_control_app(url="auto", opts=nil)
      @options[:control_url] = url

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

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

after_worker_boot(&block) click to toggle source

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

    # File lib/puma/dsl.rb, line 206
    def after_worker_boot(&block)
      @options[:after_worker_boot] << block
    end

app(obj=nil, &block) click to toggle source

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

    # File lib/puma/dsl.rb, line 26
    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) click to toggle source

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

    # File lib/puma/dsl.rb, line 168
    def before_fork(&block)
      @options[:before_fork] << block
    end

bind(url) click to toggle source

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

    # File lib/puma/dsl.rb, line 51
    def bind(url)
      @options[:binds] << url
    end

clean_thread_locals(which=true) click to toggle source

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

    # File lib/puma/dsl.rb, line 64
    def clean_thread_locals(which=true)
      @options[:clean_thread_locals] = which
    end

daemonize(which=true) click to toggle source

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

    # File lib/puma/dsl.rb, line 70
    def daemonize(which=true)
      @options[:daemon] = which
    end

directory(dir) click to toggle source

The directory to operate out of.

    # File lib/puma/dsl.rb, line 211
    def directory(dir)
      @options[:directory] = dir.to_s
      @options[:worker_directory] = dir.to_s
    end

drain_on_shutdown(which=true) click to toggle source

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.

    # File lib/puma/dsl.rb, line 78
    def drain_on_shutdown(which=true)
      @options[:drain_on_shutdown] = which
    end

environment(environment) click to toggle source

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

    # File lib/puma/dsl.rb, line 83
    def environment(environment)
      @options[:environment] = environment
    end

lowlevel_error_handler(obj=nil, &block) click to toggle source

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

    # File lib/puma/dsl.rb, line 232
    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) click to toggle source

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.

    # File lib/puma/dsl.rb, line 92
    def on_restart(&block)
      @options[:on_restart] << block
    end

on_worker_boot(&block) click to toggle source

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

    # File lib/puma/dsl.rb, line 188
    def on_worker_boot(&block)
      @options[:before_worker_boot] << block
    end

on_worker_fork(&block) click to toggle source

*Cluster mode only* Code to run when a master process is about to create the worker by forking itself.

This can be called multiple times to add hooks.

    # File lib/puma/dsl.rb, line 197
    def on_worker_fork(&block)
      @options[:before_worker_fork] << block
    end

on_worker_shutdown(&block) click to toggle source

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

    # File lib/puma/dsl.rb, line 179
    def on_worker_shutdown(&block)
      @options[:before_worker_shutdown] << block
    end

pidfile(path) click to toggle source

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

    # File lib/puma/dsl.rb, line 105
    def pidfile(path)
      @options[:pidfile] = path
    end

port(port) click to toggle source

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

    # File lib/puma/dsl.rb, line 57
    def port(port)
      @options[:binds] << "tcp://#{Configuration::DefaultTCPHost}:#{port}"
    end

preload_app!(answer=true) click to toggle source

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

    # File lib/puma/dsl.rb, line 225
    def preload_app!(answer=true)
      @options[:preload_app] = answer
    end

prune_bundler(answer=true) click to toggle source

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.

    # File lib/puma/dsl.rb, line 250
    def prune_bundler(answer=true)
      @options[:prune_bundler] = answer
    end

queue_requests(answer=true) click to toggle source

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.

    # File lib/puma/dsl.rb, line 282
    def queue_requests(answer=true)
      @options[:queue_requests] = answer
    end

quiet() click to toggle source

Disable request logging.

    # File lib/puma/dsl.rb, line 111
    def quiet
      @options[:quiet] = true
    end

rackup(path) click to toggle source

Load `path` as a rackup file.

    # File lib/puma/dsl.rb, line 117
    def rackup(path)
      @options[:rackup] = path.to_s
    end

restart_command(cmd) click to toggle source

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.

    # File lib/puma/dsl.rb, line 100
    def restart_command(cmd)
      @options[:restart_cmd] = cmd
    end

shutdown_debug(val=true) click to toggle source

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.

    # File lib/puma/dsl.rb, line 289
    def shutdown_debug(val=true)
      @options[:shutdown_debug] = val
    end

ssl_bind(host, port, opts) click to toggle source

    # File lib/puma/dsl.rb, line 142
    def ssl_bind(host, port, opts)
      @options[:binds] << "ssl://#{host}:#{port}?cert=#{opts[:cert]}&key=#{opts[:key]}"
    end

state_path(path) click to toggle source

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

    # File lib/puma/dsl.rb, line 149
    def state_path(path)
      @options[:state] = path.to_s
    end

stdout_redirect(stdout=nil, stderr=nil, append=false) click to toggle source

Redirect STDOUT and STDERR to files specified.

    # File lib/puma/dsl.rb, line 122
    def stdout_redirect(stdout=nil, stderr=nil, append=false)
      @options[:redirect_stdout] = stdout
      @options[:redirect_stderr] = stderr
      @options[:redirect_append] = append
    end

tag(string) click to toggle source

Additional text to display in process listing

    # File lib/puma/dsl.rb, line 255
    def tag(string)
      @options[:tag] = string
    end

tcp_mode() click to toggle source

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

    # File lib/puma/dsl.rb, line 217
    def tcp_mode
      @options[:mode] = :tcp
    end

threads(min, max) click to toggle source

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

    # File lib/puma/dsl.rb, line 131
    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) click to toggle source

*Cluster mode only* Set the timeout for worker shutdown

    # File lib/puma/dsl.rb, line 265
    def worker_shutdown_timeout(timeout)
      @options[:worker_shutdown_timeout] = timeout
    end

worker_timeout(timeout) click to toggle source

*Cluster mode only* Set the timeout for workers

    # File lib/puma/dsl.rb, line 260
    def worker_timeout(timeout)
      @options[:worker_timeout] = timeout
    end

workers(count) click to toggle source

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

    # File lib/puma/dsl.rb, line 155
    def workers(count)
      @options[:workers] = count.to_i
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.