puma 5.0.4 → 5.6.4

data/lib/puma/dsl.rb

@@ -34,6 +34,42 @@ module Puma
   class DSL
     include ConfigDefault
 
+    # convenience method so logic can be used in CI
+    # @see ssl_bind
+    #
+    def self.ssl_bind_str(host, port, opts)
+      verify = opts.fetch(:verify_mode, 'none').to_s
+
+      tls_str =
+        if opts[:no_tlsv1_1]  then '&no_tlsv1_1=true'
+        elsif opts[:no_tlsv1] then '&no_tlsv1=true'
+        else ''
+        end
+
+      ca_additions = "&ca=#{opts[:ca]}" if ['peer', 'force_peer'].include?(verify)
+
+      backlog_str = opts[:backlog] ? "&backlog=#{Integer(opts[:backlog])}" : ''
+
+      if defined?(JRUBY_VERSION)
+        ssl_cipher_list = opts[:ssl_cipher_list] ?
+          "&ssl_cipher_list=#{opts[:ssl_cipher_list]}" : nil
+
+        keystore_additions = "keystore=#{opts[:keystore]}&keystore-pass=#{opts[:keystore_pass]}"
+
+        "ssl://#{host}:#{port}?#{keystore_additions}#{ssl_cipher_list}" \
+          "&verify_mode=#{verify}#{tls_str}#{ca_additions}#{backlog_str}"
+      else
+        ssl_cipher_filter = opts[:ssl_cipher_filter] ?
+          "&ssl_cipher_filter=#{opts[:ssl_cipher_filter]}" : nil
+
+        v_flags = (ary = opts[:verification_flags]) ?
+          "&verification_flags=#{Array(ary).join ','}" : nil
+
+        "ssl://#{host}:#{port}?cert=#{opts[:cert]}&key=#{opts[:key]}" \
+          "#{ssl_cipher_filter}&verify_mode=#{verify}#{tls_str}#{ca_additions}#{v_flags}#{backlog_str}"
+      end
+    end
+
     def initialize(options, config)
       @config  = config
       @options = options
@@ -157,7 +193,7 @@ module Puma
     end
 
     # Bind the server to +url+. "tcp://", "unix://" and "ssl://" are the only
-    # accepted protocols. Multiple urls can be bound to, calling `bind` does
+    # accepted protocols. Multiple urls can be bound to, calling +bind+ does
     # not overwrite previous bindings.
     #
     # The default is "tcp://0.0.0.0:9292".
@@ -167,7 +203,7 @@ module Puma
     # * Set the socket backlog depth with +backlog+, default is 1024.
     # * Set up an SSL certificate with +key+ & +cert+.
     # * Set whether to optimize for low latency instead of throughput with
-    #   +low_latency+, default is to optimize for low latency. This is done
+    #   +low_latency+, default is to not optimize for low latency. This is done
     #   via +Socket::TCP_NODELAY+.
     # * Set socket permissions with +umask+.
     #
@@ -191,13 +227,39 @@ module Puma
       @options[:binds] = []
     end
 
+    # Bind to (systemd) activated sockets, regardless of configured binds.
+    #
+    # Systemd can present sockets as file descriptors that are already opened.
+    # By default Puma will use these but only if it was explicitly told to bind
+    # to the socket. If not, it will close the activated sockets. This means
+    # all configuration is duplicated.
+    #
+    # Binds can contain additional configuration, but only SSL config is really
+    # relevant since the unix and TCP socket options are ignored.
+    #
+    # This means there is a lot of duplicated configuration for no additional
+    # value in most setups. This method tells the launcher to bind to all
+    # activated sockets, regardless of existing bind.
+    #
+    # To clear configured binds, the value only can be passed. This will clear
+    # out any binds that may have been configured.
+    #
+    # @example Use any systemd activated sockets as well as configured binds
+    #   bind_to_activated_sockets
+    #
+    # @example Only bind to systemd activated sockets, ignoring other binds
+    #   bind_to_activated_sockets 'only'
+    def bind_to_activated_sockets(bind=true)
+      @options[:bind_to_activated_sockets] = bind
+    end
+
     # Define the TCP port to bind to. Use +bind+ for more advanced options.
     #
     # @example
     #   port 9292
     def port(port, host=nil)
       host ||= default_host
-      bind "tcp://#{host}:#{port}"
+      bind URI::Generic.build(scheme: 'tcp', host: host, port: Integer(port)).to_s
     end
 
     # Define how long persistent connections can be idle before Puma closes them.
@@ -321,6 +383,13 @@ module Puma
       @options[:rackup] ||= path.to_s
     end
 
+    # Allows setting `env['rack.url_scheme']`.
+    # Only necessary if X-Forwarded-Proto is not being set by your proxy
+    # Normal values are 'http' or 'https'.
+    def rack_url_scheme(scheme=nil)
+      @options[:rack_url_scheme] = scheme
+    end
+
     def early_hints(answer=true)
       @options[:early_hints] = answer
     end
@@ -345,7 +414,10 @@ module Puma
     # Configure +min+ to be the minimum number of threads to use to answer
     # requests and +max+ the maximum.
     #
-    # The default is "0, 16".
+    # The default is the environment variables +PUMA_MIN_THREADS+ / +PUMA_MAX_THREADS+
+    # (or +MIN_THREADS+ / +MAX_THREADS+ if the +PUMA_+ variables aren't set).
+    #
+    # If these environment variables aren't set, the default is "0, 5" in MRI or "0, 16" for other interpreters.
     #
     # @example
     #   threads 0, 16
@@ -366,8 +438,15 @@ module Puma
       @options[:max_threads] = max
     end
 
-    # Instead of `bind 'ssl://127.0.0.1:9292?key=key_path&cert=cert_path'` you
-    # can also use the this method.
+    # Instead of using +bind+ and manually constructing a URI like:
+    #
+    #    bind 'ssl://127.0.0.1:9292?key=key_path&cert=cert_path'
+    #
+    # you can use the this method.
+    #
+    # When binding on localhost you don't need to specify +cert+ and +key+,
+    # Puma will assume you are using the +localhost+ gem and try to load the
+    # appropriate files.
     #
     # @example
     #   ssl_bind '127.0.0.1', '9292', {
@@ -375,29 +454,28 @@ module Puma
     #     key: path_to_key,
     #     ssl_cipher_filter: cipher_filter, # optional
     #     verify_mode: verify_mode,         # default 'none'
+    #     verification_flags: flags,        # optional, not supported by JRuby
     #   }
-    # @example For JRuby additional keys are required: keystore & keystore_pass.
+    #
+    # @example Using self-signed certificate with the +localhost+ gem:
+    #   ssl_bind '127.0.0.1', '9292'
+    #
+    # @example Alternatively, you can provide +cert_pem+ and +key_pem+:
+    #   ssl_bind '127.0.0.1', '9292', {
+    #     cert_pem: File.read(path_to_cert),
+    #     key_pem: File.read(path_to_key),
+    #   }
+    #
+    # @example For JRuby, two keys are required: +keystore+ & +keystore_pass+
     #   ssl_bind '127.0.0.1', '9292', {
-    #     cert: path_to_cert,
-    #     key: path_to_key,
-    #     ssl_cipher_filter: cipher_filter, # optional
-    #     verify_mode: verify_mode,         # default 'none'
     #     keystore: path_to_keystore,
-    #     keystore_pass: password
+    #     keystore_pass: password,
+    #     ssl_cipher_list: cipher_list,     # optional
+    #     verify_mode: verify_mode          # default 'none'
     #   }
-    def ssl_bind(host, port, opts)
-      verify = opts.fetch(:verify_mode, 'none').to_s
-      no_tlsv1 = opts.fetch(:no_tlsv1, 'false')
-      no_tlsv1_1 = opts.fetch(:no_tlsv1_1, 'false')
-      ca_additions = "&ca=#{opts[:ca]}" if ['peer', 'force_peer'].include?(verify)
-
-      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}&no_tlsv1=#{no_tlsv1}&no_tlsv1_1=#{no_tlsv1_1}#{ca_additions}"
-      else
-        ssl_cipher_filter = "&ssl_cipher_filter=#{opts[:ssl_cipher_filter]}" if opts[:ssl_cipher_filter]
-        bind "ssl://#{host}:#{port}?cert=#{opts[:cert]}&key=#{opts[:key]}#{ssl_cipher_filter}&verify_mode=#{verify}&no_tlsv1=#{no_tlsv1}&no_tlsv1_1=#{no_tlsv1_1}#{ca_additions}"
-      end
+    def ssl_bind(host, port, opts = {})
+      add_pem_values_to_options_store(opts)
+      bind self.class.ssl_bind_str(host, port, opts)
     end
 
     # Use +path+ as the file to store the server info state. This is
@@ -422,7 +500,8 @@ module Puma
     # How many worker processes to run.  Typically this is set to
     # the number of available cores.
     #
-    # The default is 0.
+    # The default is the value of the environment variable +WEB_CONCURRENCY+ if
+    # set, otherwise 0.
     #
     # @note Cluster mode only.
     # @see Puma::Cluster
@@ -430,6 +509,24 @@ module Puma
       @options[:workers] = count.to_i
     end
 
+    # Disable warning message when running in cluster mode with a single worker.
+    #
+    # Cluster mode has some overhead of running an additional 'control' process
+    # in order to manage the cluster. If only running a single worker it is
+    # likely not worth paying that overhead vs running in single mode with
+    # additional threads instead.
+    #
+    # There are some scenarios where running cluster mode with a single worker
+    # may still be warranted and valid under certain deployment scenarios, see
+    # https://github.com/puma/puma/issues/2534
+    #
+    # Moving from workers = 1 to workers = 0 will save 10-30% of memory use.
+    #
+    # @note Cluster mode only.
+    def silence_single_worker_warning
+      @options[:silence_single_worker_warning] = true
+    end
+
     # 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
@@ -508,7 +605,7 @@ module Puma
     #   end
     def after_worker_fork(&block)
       @options[:after_worker_fork] ||= []
-      @options[:after_worker_fork] = block
+      @options[:after_worker_fork] << block
     end
 
     alias_method :after_worker_boot, :after_worker_fork
@@ -561,7 +658,7 @@ module Puma
     end
 
     # Preload the application before starting the workers; this conflicts with
-    # phased restart feature. This is off by default.
+    # phased restart feature. On by default if your app uses more than 1 worker.
     #
     # @note Cluster mode only.
     # @example
@@ -650,6 +747,19 @@ module Puma
       @options[:tag] = string.to_s
     end
 
+    # Change the default interval for checking workers.
+    #
+    # The default value is 5 seconds.
+    #
+    # @note Cluster mode only.
+    # @example
+    #   worker_check_interval 5
+    # @see Puma::Cluster#check_workers
+    #
+    def worker_check_interval(interval)
+      @options[:worker_check_interval] = Integer(interval)
+    end
+
     # Verifies that all workers have checked in to the master process within
     # the given timeout. If not the worker process will be restarted. This is
     # not a request timeout, it is to protect against a hung or dead process.
@@ -664,7 +774,7 @@ module Puma
     #
     def worker_timeout(timeout)
       timeout = Integer(timeout)
-      min = Const::WORKER_CHECK_INTERVAL
+      min = @options.fetch(:worker_check_interval, Puma::ConfigDefault::DefaultWorkerCheckInterval)
 
       if timeout <= min
         raise "The minimum worker_timeout must be greater than the worker reporting interval (#{min})"
@@ -696,6 +806,30 @@ module Puma
       @options[:worker_shutdown_timeout] = Integer(timeout)
     end
 
+    # Set the strategy for worker culling.
+    #
+    # There are two possible values:
+    #
+    # 1. **:youngest** - the youngest workers (i.e. the workers that were
+    #    the most recently started) will be culled.
+    # 2. **:oldest** - the oldest workers (i.e. the workers that were started
+    #    the longest time ago) will be culled.
+    #
+    # @note Cluster mode only.
+    # @example
+    #   worker_culling_strategy :oldest
+    # @see Puma::Cluster#cull_workers
+    #
+    def worker_culling_strategy(strategy)
+      stategy = strategy.to_sym
+
+      if ![:youngest, :oldest].include?(strategy)
+        raise "Invalid value for worker_culling_strategy - #{stategy}"
+      end
+
+      @options[:worker_culling_strategy] = strategy
+    end
+
     # 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
@@ -741,7 +875,7 @@ module Puma
     # a kernel syscall is required which for very fast rack handlers
     # slows down the handling significantly.
     #
-    # There are 4 possible values:
+    # There are 5 possible values:
     #
     # 1. **:socket** (the default) - read the peername from the socket using the
     #    syscall. This is the normal behavior.
@@ -751,7 +885,10 @@ module Puma
     #    `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.
-    # 4. **\<Any string\>** - this allows you to hardcode remote address to any value
+    # 4. **proxy_protocol: :v1**- set the remote address to the value read from the
+    #    HAproxy PROXY protocol, version 1. If the request does not have the PROXY
+    #    protocol attached to it, will fall back to :socket
+    # 5. **\<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.
     #
@@ -769,6 +906,13 @@ module Puma
         if hdr = val[:header]
           @options[:remote_address] = :header
           @options[:remote_address_header] = "HTTP_" + hdr.upcase.tr("-", "_")
+        elsif protocol_version = val[:proxy_protocol]
+          @options[:remote_address] = :proxy_protocol
+          protocol_version = protocol_version.downcase.to_sym
+          unless [:v1].include?(protocol_version)
+            raise "Invalid value for proxy_protocol - #{protocol_version.inspect}"
+          end
+          @options[:remote_address_proxy_protocol] = protocol_version
         else
           raise "Invalid value for set_remote_address - #{val.inspect}"
         end
@@ -810,5 +954,55 @@ module Puma
     def nakayoshi_fork(enabled=true)
       @options[:nakayoshi_fork] = enabled
     end
+
+    # The number of requests to attempt inline before sending a client back to
+    # the reactor to be subject to normal ordering.
+    #
+    def max_fast_inline(num_of_requests)
+      @options[:max_fast_inline] = Float(num_of_requests)
+    end
+
+    # Specify the backend for the IO selector.
+    #
+    # Provided values will be passed directly to +NIO::Selector.new+, with the
+    # exception of +:auto+ which will let nio4r choose the backend.
+    #
+    # Check the documentation of +NIO::Selector.backends+ for the list of valid
+    # options. Note that the available options on your system will depend on the
+    # operating system. If you want to use the pure Ruby backend (not
+    # recommended due to its comparatively low performance), set environment
+    # variable +NIO4R_PURE+ to +true+.
+    #
+    # The default is +:auto+.
+    #
+    # @see https://github.com/socketry/nio4r/blob/master/lib/nio/selector.rb
+    #
+    def io_selector_backend(backend)
+      @options[:io_selector_backend] = backend.to_sym
+    end
+
+    def mutate_stdout_and_stderr_to_sync_on_write(enabled=true)
+      @options[:mutate_stdout_and_stderr_to_sync_on_write] = enabled
+    end
+
+    private
+
+    # To avoid adding cert_pem and key_pem as URI params, we store them on the
+    # options[:store] from where Puma binder knows how to find and extract them.
+    def add_pem_values_to_options_store(opts)
+      return if defined?(JRUBY_VERSION)
+
+      @options[:store] ||= []
+
+      # Store cert_pem and key_pem to options[:store] if present
+      [:cert, :key].each do |v|
+        opt_key = :"#{v}_pem"
+        if opts[opt_key]
+          index = @options[:store].length
+          @options[:store] << opts[opt_key]
+          opts[v] = "store:#{index}"
+        end
+      end
+    end
   end
 end

data/lib/puma/error_logger.rb

@@ -15,7 +15,6 @@ module Puma
 
     def initialize(ioerr)
       @ioerr = ioerr
-      @ioerr.sync = true
 
       @debug = ENV.key? 'PUMA_DEBUG'
     end
@@ -24,7 +23,7 @@ module Puma
       new $stderr
     end
 
-    # Print occured error details.
+    # Print occurred error details.
     # +options+ hash with additional options:
     # - +error+ is an exception object
     # - +req+ the http request
@@ -32,10 +31,10 @@ module Puma
     #   and before all remaining info.
     #
     def info(options={})
-      ioerr.puts title(options)
+      log title(options)
     end
 
-    # Print occured error details only if
+    # Print occurred error details only if
     # environment variable PUMA_DEBUG is defined.
     # +options+ hash with additional options:
     # - +error+ is an exception object
@@ -54,7 +53,7 @@ module Puma
       string_block << request_dump(req) if request_parsed?(req)
       string_block << error.backtrace if error
 
-      ioerr.puts string_block.join("\n")
+      log string_block.join("\n")
     end
 
     def title(options={})
@@ -93,5 +92,13 @@ module Puma
     def request_parsed?(req)
       req && req.env[REQUEST_METHOD]
     end
+
+    private
+
+    def log(str)
+      ioerr.puts str
+
+      ioerr.flush unless ioerr.sync
+    end
   end
 end

data/lib/puma/events.rb

@@ -30,9 +30,6 @@ module Puma
       @stdout = stdout
       @stderr = stderr
 
-      @stdout.sync = true
-      @stderr.sync = true
-
       @debug = ENV.key? 'PUMA_DEBUG'
       @error_logger = ErrorLogger.new(@stderr)
 
@@ -66,6 +63,8 @@ module Puma
     #
     def log(str)
       @stdout.puts format(str) if @stdout.respond_to? :puts
+
+      @stdout.flush unless @stdout.sync
     rescue Errno::EPIPE
     end
 
@@ -137,10 +136,26 @@ module Puma
       register(:on_booted, &block)
     end
 
+    def on_restart(&block)
+      register(:on_restart, &block)
+    end
+
+    def on_stopped(&block)
+      register(:on_stopped, &block)
+    end
+
     def fire_on_booted!
       fire(:on_booted)
     end
 
+    def fire_on_restart!
+      fire(:on_restart)
+    end
+
+    def fire_on_stopped!
+      fire(:on_stopped)
+    end
+
     DEFAULT = new(STDOUT, STDERR)
 
     # Returns an Events object which writes its status to 2 StringIO

data/lib/puma/json_serialization.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+require 'stringio'
+
+module Puma
+
+  # Puma deliberately avoids the use of the json gem and instead performs JSON
+  # serialization without any external dependencies. In a puma cluster, loading
+  # any gem into the puma master process means that operators cannot use a
+  # phased restart to upgrade their application if the new version of that
+  # application uses a different version of that gem. The json gem in
+  # particular is additionally problematic because it leverages native
+  # extensions. If the puma master process relies on a gem with native
+  # extensions and operators remove gems from disk related to old releases,
+  # subsequent phased restarts can fail.
+  #
+  # The implementation of JSON serialization in this module is not designed to
+  # be particularly full-featured or fast. It just has to handle the few places
+  # where Puma relies on JSON serialization internally.
+
+  module JSONSerialization
+    QUOTE = /"/
+    BACKSLASH = /\\/
+    CONTROL_CHAR_TO_ESCAPE = /[\x00-\x1F]/ # As required by ECMA-404
+    CHAR_TO_ESCAPE = Regexp.union QUOTE, BACKSLASH, CONTROL_CHAR_TO_ESCAPE
+
+    class SerializationError < StandardError; end
+
+    class << self
+      def generate(value)
+        StringIO.open do |io|
+          serialize_value io, value
+          io.string
+        end
+      end
+
+      private
+
+      def serialize_value(output, value)
+        case value
+        when Hash
+          output << '{'
+          value.each_with_index do |(k, v), index|
+            output << ',' if index != 0
+            serialize_object_key output, k
+            output << ':'
+            serialize_value output, v
+          end
+          output << '}'
+        when Array
+          output << '['
+          value.each_with_index do |member, index|
+            output << ',' if index != 0
+            serialize_value output, member
+          end
+          output << ']'
+        when Integer, Float
+          output << value.to_s
+        when String
+          serialize_string output, value
+        when true
+          output << 'true'
+        when false
+          output << 'false'
+        when nil
+          output << 'null'
+        else
+          raise SerializationError, "Unexpected value of type #{value.class}"
+        end
+      end
+
+      def serialize_string(output, value)
+        output << '"'
+        output << value.gsub(CHAR_TO_ESCAPE) do |character|
+          case character
+          when BACKSLASH
+            '\\\\'
+          when QUOTE
+            '\\"'
+          when CONTROL_CHAR_TO_ESCAPE
+            '\u%.4X' % character.ord
+          end
+        end
+        output << '"'
+      end
+
+      def serialize_object_key(output, value)
+        case value
+        when Symbol, String
+          serialize_string output, value.to_s
+        else
+          raise SerializationError, "Could not serialize object of type #{value.class} as object key"
+        end
+      end
+    end
+  end
+end