puma 3.11.4 → 3.12.6

data/lib/puma/const.rb

@@ -1,4 +1,6 @@
 #encoding: utf-8
+# frozen_string_literal: true
+
 module Puma
   class UnsupportedOption < RuntimeError
   end
@@ -98,8 +100,8 @@ module Puma
   # too taxing on performance.
   module Const
 
-    PUMA_VERSION = VERSION = "3.11.4".freeze
-    CODE_NAME = "Love Song".freeze
+    PUMA_VERSION = VERSION = "3.12.6".freeze
+    CODE_NAME = "Llamas in Pajamas".freeze
     PUMA_SERVER_STRING = ['puma', PUMA_VERSION, CODE_NAME].join(' ').freeze
 
     FAST_TRACK_KA_TIMEOUT = 0.2
@@ -116,6 +118,13 @@ module Puma
     # sending data back
     WRITE_TIMEOUT = 10
 
+    # How many requests to attempt inline before sending a client back to
+    # the reactor to be subject to normal ordering. The idea here is that
+    # we amortize the cost of going back to the reactor for a well behaved
+    # but very "greedy" client across 10 requests. This prevents a not
+    # well behaved client from monopolizing the thread forever.
+    MAX_FAST_INLINE = 10
+
     # The original URI requested by the client.
     REQUEST_URI= 'REQUEST_URI'.freeze
     REQUEST_PATH = 'REQUEST_PATH'.freeze
@@ -219,6 +228,7 @@ module Puma
     COLON = ": ".freeze
 
     NEWLINE = "\n".freeze
+    HTTP_INJECTION_REGEX = /[\r\n]/.freeze
 
     HIJACK_P = "rack.hijack?".freeze
     HIJACK = "rack.hijack".freeze

data/lib/puma/control_cli.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 require 'optparse'
-require 'puma/state_file'
-require 'puma/const'
-require 'puma/detect'
-require 'puma/configuration'
+require_relative 'state_file'
+require_relative 'const'
+require_relative 'detect'
+require_relative 'configuration'
 require 'uri'
 require 'socket'
 
@@ -129,7 +131,7 @@ module Puma
       uri = URI.parse @control_url
 
       # create server object by scheme
-      @server = case uri.scheme
+      server = case uri.scheme
                 when "tcp"
                   TCPSocket.new uri.host, uri.port
                 when "unix"
@@ -147,9 +149,9 @@ module Puma
           url = url + "?token=#{@control_auth_token}"
         end
 
-        @server << "GET #{url} HTTP/1.0\r\n\r\n"
+        server << "GET #{url} HTTP/1.0\r\n\r\n"
 
-        unless data = @server.read
+        unless data = server.read
           raise "Server closed connection before responding"
         end
 
@@ -172,8 +174,8 @@ module Puma
         message "Command #{@command} sent success"
         message response.last if @command == "stats" || @command == "gc-stats"
       end
-
-      @server.close
+    ensure
+      server.close if server && !server.closed?
     end
 
     def send_signal
@@ -220,7 +222,7 @@ module Puma
     end
 
     def run
-      start if @command == "start"
+      return start if @command == "start"
 
       prepare_configuration
 

data/lib/puma/convenient.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puma/launcher'
 require 'puma/configuration'
 

data/lib/puma/daemon_ext.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Process
 
   # This overrides the default version because it is broken if it

data/lib/puma/delegation.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Puma
   module Delegation
     def forward(what, who)

data/lib/puma/detect.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Puma
   IS_JRUBY = defined?(JRUBY_VERSION)
 

data/lib/puma/dsl.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Puma
   # The methods that are available for use inside the config file.
   # These same methods are used in Puma cli and the rack handler
@@ -55,6 +57,14 @@ module Puma
       @plugins.clear
     end
 
+    def set_default_host(host)
+      @options[:default_host] = host
+    end
+
+    def default_host
+      @options[:default_host] || Configuration::DefaultTCPHost
+    end
+
     def inject(&blk)
       instance_eval(&blk)
     end
@@ -138,7 +148,7 @@ module Puma
     # Define the TCP port to bind to. Use +bind+ for more advanced options.
     #
     def port(port, host=nil)
-      host ||= Configuration::DefaultTCPHost
+      host ||= default_host
       bind "tcp://#{host}:#{port}"
     end
 
@@ -493,7 +503,7 @@ module Puma
       when Hash
         if hdr = val[:header]
           @options[:remote_address] = :header
-          @options[:remote_address_header] = "HTTP_" + hdr.upcase.gsub("-", "_")
+          @options[:remote_address_header] = "HTTP_" + hdr.upcase.tr("-", "_")
         else
           raise "Invalid value for set_remote_address - #{val.inspect}"
         end

data/lib/puma/events.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puma/const'
 require "puma/null_io"
 require 'stringio'

data/lib/puma/io_buffer.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puma/detect'
 
 if Puma.jruby?

data/lib/puma/java_io_buffer.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'java'
 
 # Conservative native JRuby/Java implementation of IOBuffer

data/lib/puma/jruby_restart.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'ffi'
 
 module Puma

data/lib/puma/launcher.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puma/events'
 require 'puma/detect'
 
@@ -63,8 +65,8 @@ module Puma
 
       generate_restart_data
 
-      if clustered? && (Puma.jruby? || Puma.windows?)
-        unsupported 'worker mode not supported on JRuby or Windows'
+      if clustered? && !Process.respond_to?(:fork)
+        unsupported "worker mode not supported on #{RUBY_ENGINE} on this platform"
       end
 
       if @options[:daemon] && Puma.windows?

data/lib/puma/minissl.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 begin
   require 'io/wait'
   rescue LoadError
@@ -124,7 +126,7 @@ module Puma
 
       def read_and_drop(timeout = 1)
         return :timeout unless IO.select([@socket], nil, nil, timeout)
-        read_nonblock(1024)
+        return :eof unless read_nonblock(1024)
         :drop
       rescue Errno::EAGAIN
         # do nothing
@@ -141,7 +143,7 @@ module Puma
           # Don't let this socket hold this loop forever.
           # If it can't send more packets within 1s, then give up.
           while should_drop_bytes?
-            return if read_and_drop(1) == :timeout
+            return if [:timeout, :eof].include?(read_and_drop(1))
           end
         rescue IOError, SystemCallError
           Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
@@ -180,6 +182,7 @@ module Puma
         # jruby-specific Context properties: java uses a keystore and password pair rather than a cert/key pair
         attr_reader :keystore
         attr_accessor :keystore_pass
+        attr_accessor :ssl_cipher_list
 
         def keystore=(keystore)
           raise ArgumentError, "No such keystore file '#{keystore}'" unless File.exist? keystore
@@ -195,6 +198,7 @@ module Puma
         attr_reader :key
         attr_reader :cert
         attr_reader :ca
+        attr_accessor :ssl_cipher_filter
 
         def key=(key)
           raise ArgumentError, "No such key file '#{key}'" unless File.exist? key

data/lib/puma/null_io.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Puma
   # Provides an IO-like object that always appears to contain no data.
   # Used as the value for rack.input when the request has no body.

data/lib/puma/plugin.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Puma
   class UnknownPlugin < RuntimeError; end
 

data/lib/puma/rack/builder.rb

@@ -110,7 +110,8 @@ module Puma::Rack
 
           has_options = false
           server.valid_options.each do |name, description|
-            next if name.to_s.match(/^(Host|Port)[^a-zA-Z]/) # ignore handler's host and port options, we do our own.
+            next if name.to_s =~ /^(Host|Port)[^a-zA-Z]/ # ignore handler's host and port options, we do our own.
+
             info << "  -O %-21s %s" % [name, description]
             has_options = true
           end

data/lib/puma/reactor.rb

@@ -1,16 +1,57 @@
+# frozen_string_literal: true
+
 require 'puma/util'
 require 'puma/minissl'
 
 module Puma
+  # Internal Docs, Not a public interface.
+  #
+  # The Reactor object is responsible for ensuring that a request has been
+  # completely received before it starts to be processed. This may be known as read buffering.
+  # If read buffering is not done, and no other read buffering is performed (such as by an application server
+  # such as nginx) then the application would be subject to a slow client attack.
+  #
+  # Each Puma "worker" process has its own Reactor. For example if you start puma with `$ puma -w 5` then
+  # it will have 5 workers and each worker will have it's own reactor.
+  #
+  # For a graphical representation of how the reactor works see [architecture.md](https://github.com/puma/puma/blob/master/docs/architecture.md#connection-pipeline).
+  #
+  # ## Reactor Flow
+  #
+  # A request comes into a `Puma::Server` instance, it is then passed to a `Puma::Reactor` instance.
+  # The reactor stores the request in an array and calls `IO.select` on the array in a loop.
+  #
+  # When the request is written to by the client then the `IO.select` will "wake up" and
+  # return the references to any objects that caused it to "wake". The reactor
+  # then loops through each of these request objects, and sees if they're  complete. If they
+  # have a full header and body then the reactor passes the request to a thread pool.
+  # Once in a thread pool, a "worker thread" can run the the application's Ruby code against the request.
+  #
+  # If the request is not complete, then it stays in the array, and the next time any
+  # data is written to that socket reference, then the loop is woken up and it is checked for completeness again.
+  #
+  # A detailed example is given in the docs for `run_internal` which is where the bulk
+  # of this logic lives.
   class Reactor
     DefaultSleepFor = 5
 
+    # Creates an instance of Puma::Reactor
+    #
+    # The `server` argument is an instance of `Puma::Server`
+    # this is used to write a response for "low level errors"
+    # when there is an exception inside of the reactor.
+    #
+    # The `app_pool` is an instance of `Puma::ThreadPool`.
+    # Once a request is fully formed (header and body are received)
+    # it will be passed to the `app_pool`.
     def initialize(server, app_pool)
       @server = server
       @events = server.events
       @app_pool = app_pool
 
       @mutex = Mutex.new
+
+      # Read / Write pipes to wake up internal while loop
       @ready, @trigger = Puma::Util.pipe
       @input = []
       @sleep_for = DefaultSleepFor
@@ -21,6 +62,64 @@ module Puma
 
     private
 
+
+    # Until a request is added via the `add` method this method will internally
+    # loop, waiting on the `sockets` array objects. The only object in this
+    # array at first is the `@ready` IO object, which is the read end of a pipe
+    # connected to `@trigger` object. When `@trigger` is written to, then the loop
+    # will break on `IO.select` and return an array.
+    #
+    # ## When a request is added:
+    #
+    # When the `add` method is called, an instance of `Puma::Client` is added to the `@input` array.
+    # Next the `@ready` pipe is "woken" by writing a string of `"*"` to `@trigger`.
+    #
+    # When that happens, the internal loop stops blocking at `IO.select` and returns a reference
+    # to whatever "woke" it up. On the very first loop, the only thing in `sockets` is `@ready`.
+    # When `@trigger` is written-to, the loop "wakes" and the `ready`
+    # variable returns an array of arrays that looks like `[[#<IO:fd 10>], [], []]` where the
+    # first IO object is the `@ready` object. This first array `[#<IO:fd 10>]`
+    # is saved as a `reads` variable.
+    #
+    # The `reads` variable is iterated through. In the case that the object
+    # is the same as the `@ready` input pipe, then we know that there was a `trigger` event.
+    #
+    # If there was a trigger event, then one byte of `@ready` is read into memory. In the case of the first request,
+    # the reactor sees that it's a `"*"` value and the reactor adds the contents of `@input` into the `sockets` array.
+    # The while then loop continues to iterate again, but now the `sockets` array contains a `Puma::Client` instance in addition
+    # to the `@ready` IO object. For example: `[#<IO:fd 10>, #<Puma::Client:0x3fdc1103bee8 @ready=false>]`.
+    #
+    # Since the `Puma::Client` in this example has data that has not been read yet,
+    # the `IO.select` is immediately able to "wake" and read from the `Puma::Client`. At this point the
+    # `ready` output looks like this: `[[#<Puma::Client:0x3fdc1103bee8 @ready=false>], [], []]`.
+    #
+    # Each element in the first entry is iterated over. The `Puma::Client` object is not
+    # the `@ready` pipe, so the reactor checks to see if it has the fully header and body with
+    # the `Puma::Client#try_to_finish` method. If the full request has been sent,
+    # then the request is passed off to the `@app_pool` thread pool so that a "worker thread"
+    # can pick up the request and begin to execute application logic. This is done
+    # via `@app_pool << c`. The `Puma::Client` is then removed from the `sockets` array.
+    #
+    # If the request body is not present then nothing will happen, and the loop will iterate
+    # again. When the client sends more data to the socket the `Puma::Client` object will
+    # wake up the `IO.select` and it can again be checked to see if it's ready to be
+    # passed to the thread pool.
+    #
+    # ## Time Out Case
+    #
+    # In addition to being woken via a write to one of the sockets the `IO.select` will
+    # periodically "time out" of the sleep. One of the functions of this is to check for
+    # any requests that have "timed out". At the end of the loop it's checked to see if
+    # the first element in the `@timeout` array has exceed it's allowed time. If so,
+    # the client object is removed from the timeout aray, a 408 response is written.
+    # Then it's connection is closed, and the object is removed from the `sockets` array
+    # that watches for new data.
+    #
+    # This behavior loops until all the objects that have timed out have been removed.
+    #
+    # Once all the timeouts have been processed, the next duration of the `IO.select` sleep
+    # will be set to be equal to the amount of time it will take for the next timeout to occur.
+    # This calculation happens in `calculate_sleep`.
     def run_internal
       sockets = @sockets
 
@@ -163,6 +262,16 @@ module Puma
       end
     end
 
+    # The `calculate_sleep` sets the value that the `IO.select` will
+    # sleep for in the main reactor loop when no sockets are being written to.
+    #
+    # The values kept in `@timeouts` are sorted so that the first timeout
+    # comes first in the array. When there are no timeouts the default timeout is used.
+    #
+    # Otherwise a sleep value is set that is the same as the amount of time it
+    # would take for the first element to time out.
+    #
+    # If that value is in the past, then a sleep value of zero is used.
     def calculate_sleep
       if @timeouts.empty?
         @sleep_for = DefaultSleepFor
@@ -177,6 +286,31 @@ module Puma
       end
     end
 
+    # This method adds a connection to the reactor
+    #
+    # Typically called by `Puma::Server` the value passed in
+    # is usually a `Puma::Client` object that responds like an IO
+    # object.
+    #
+    # The main body of the reactor loop is in `run_internal` and it
+    # will sleep on `IO.select`. When a new connection is added to the
+    # reactor it cannot be added directly to the `sockets` aray, because
+    # the `IO.select` will not be watching for it yet.
+    #
+    # Instead what needs to happen is that `IO.select` needs to be woken up,
+    # the contents of `@input` added to the `sockets` array, and then
+    # another call to `IO.select` needs to happen. Since the `Puma::Client`
+    # object can be read immediately, it does not block, but instead returns
+    # right away.
+    #
+    # This behavior is accomplished by writing to `@trigger` which wakes up
+    # the `IO.select` and then there is logic to detect the value of `*`,
+    # pull the contents from `@input` and add them to the sockets array.
+    #
+    # If the object passed in has a timeout value in `timeout_at` then
+    # it is added to a `@timeouts` array. This array is then re-arranged
+    # so that the first element to timeout will be at the front of the
+    # array. Then a value to sleep for is derived in the call to `calculate_sleep`
     def add(c)
       @mutex.synchronize do
         @input << c

data/lib/puma/runner.rb

@@ -1,7 +1,12 @@
+# frozen_string_literal: true
+
 require 'puma/server'
 require 'puma/const'
 
 module Puma
+  # Generic class that is used by `Puma::Cluster` and `Puma::Single` to
+  # serve requests. This class spawns a new instance of `Puma::Server` via
+  # a call to `start_server`.
   class Runner
     def initialize(cli, events)
       @launcher = cli
@@ -19,6 +24,10 @@ module Puma
       @options[:environment] == "development"
     end
 
+    def test?
+      @options[:environment] == "test"
+    end
+
     def log(str)
       @events.log str
     end
@@ -165,7 +174,7 @@ module Puma
         server.early_hints = true
       end
 
-      unless development?
+      unless development? || test?
         server.leak_stack_on_error = false
       end