puma 3.11.4 → 3.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f451a7278034b23b2a1537d6bde82ae318cd58750dbab2c0a6aa4eb0e72efb0
-  data.tar.gz: 3841d52680598006e72b92c37c358d0f185980bfca81cdc55c19e25673156f61
+  metadata.gz: bff4687b24c136075e00b45d5314fd6326b6240733fff22c706096d10d8ec965
+  data.tar.gz: db2020f983ba02f7403e50f9f9391bd2f20e811fa42121147d4cbaf619e1d8d3
 SHA512:
-  metadata.gz: 6273588bb47a3f85b40a358dc445733de687707111dd5aaffe4004be32a82eef00c227495abd9e68bd0b3f398395b64b685e8b78f5b428e3aee87be50f91cb1f
-  data.tar.gz: 167dc9b6bdcf05050cff4d80af977ede8c4cd9b5fb0dd3397f8075e4657402cf5e7e084c248c2e23d06669cbce52cd13a84155612a3451c0ac5df6d0cff36730
+  metadata.gz: d6d7efcb9aeb437c07f49cb5a589ed016d888acab08f130bb382f2d470b301ec40ce3df90fbe4cf989bc84468633b180894c60daca377346d283210e6fedba98
+  data.tar.gz: 2d45380434e8d88d534a27db1a1f843d70b925a64065d55ee637153669b3c78f1539bf4c84ee166ec90636ba3ee948a97540c0bdbac5cc3d68809c86874038f8

data/History.md

@@ -1,3 +1,16 @@
+## 3.12.0 / 2018-07-13
+
+* 5 features:
+  * You can now specify which SSL ciphers the server should support, default is unchanged (#1478)
+  * The setting for Puma's `max_threads` is now in `Puma.stats` (#1604)
+  * Pool capacity is now in `Puma.stats` (#1579)
+  * Installs restricted to Ruby 2.2+ (#1506)
+  * `--control` is now deprecated in favor of `--control-url` (#1487)
+
+* 2 bugfixes:
+  * Workers will no longer accept more web requests than they have capacity to process. This prevents an issue where one worker would accept lots of requests while starving other workers (#1563)
+  * In a test env puma now emits the stack on an exception (#1557)
+
 ## 3.11.4 / 2018-04-12
 
 * 2 features:
@@ -7,7 +20,7 @@
   * Fix parsing CLI options (#1482)
   * Order of stderr and stdout is made before redirecting to a log file (#1511)
   * Init.d fix of `ps -p` to check if pid exists (#1545)
-  * Early hits bugfix (#1550)
+  * Early hints bugfix (#1550)
   * Purge interrupt queue when closing socket fails (#1553)
 
 ## 3.11.3 / 2018-03-05

data/README.md

@@ -157,17 +157,27 @@ $ puma -b 'unix:///var/run/puma.sock?umask=0111'
 ```
 
 Need a bit of security? Use SSL sockets:
-
 ```
 $ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert'
 ```
+#### Controlling SSL Cipher Suites
+Need to use or avoid specific SSL cipher suites? Use ssl_cipher_filter or ssl_cipher_list options.
+#####Ruby:
+```
+$ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert&ssl_cipher_filter=!aNULL:AES+SHA'
+```
+#####JRuby:
+```
+$ puma -b 'ssl://127.0.0.1:9292?keystore=path_to_keystore&keystore-pass=keystore_password&ssl_cipher_list=TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA'
+```
+See https://www.openssl.org/docs/man1.0.2/apps/ciphers.html for cipher filter format and full list of cipher suites.
 
 ### Control/Status Server
 
 Puma has a built-in status/control app that can be used to query and control Puma itself.
 
 ```
-$ puma --control tcp://127.0.0.1:9293 --control-token foo
+$ puma --control-url tcp://127.0.0.1:9293 --control-token foo
 ```
 
 Puma will start the control server on localhost port 9293. All requests to the control server will need to include `token=foo` as a query parameter. This allows for simple authentication. Check out [status.rb](https://github.com/puma/puma/blob/master/lib/puma/app/status.rb) to see what the app has available.
@@ -175,7 +185,7 @@ Puma will start the control server on localhost port 9293. All requests to the c
 You can also interact with the control server via `pumactl`. This command will restart Puma:
 
 ```
-$ pumactl -C 'tcp://127.0.0.1:9293' --control-token foo restart
+$ pumactl --control-url 'tcp://127.0.0.1:9293' --control-token foo restart
 ```
 
 To see a list of `pumactl` options, use `pumactl --help`.
@@ -217,10 +227,10 @@ Some platforms do not support all Puma features.
 
 ## Known Bugs
 
-For MRI versions 2.2.7, 2.2.8, 2.2.9, 2.3.4 and 2.4.1, you may see ```stream closed in another thread (IOError)```. It may be caused by a [Ruby bug](https://bugs.ruby-lang.org/issues/13632). It can be fixed with the gem https://rubygems.org/gems/stopgap_13632:
+For MRI versions 2.2.7, 2.2.8, 2.2.9, 2.2.10 2.3.4 and 2.4.1, you may see ```stream closed in another thread (IOError)```. It may be caused by a [Ruby bug](https://bugs.ruby-lang.org/issues/13632). It can be fixed with the gem https://rubygems.org/gems/stopgap_13632:
 
 ```ruby
-if %w(2.2.7 2.2.8 2.2.9 2.3.4 2.4.1).include? RUBY_VERSION
+if %w(2.2.7 2.2.8 2.2.9 2.2.10 2.3.4 2.4.1).include? RUBY_VERSION
   begin
     require 'stopgap_13632'
   rescue LoadError

data/ext/puma_http11/mini_ssl.c

@@ -161,6 +161,9 @@ VALUE engine_init_server(VALUE self, VALUE mini_ssl_ctx) {
   ID sym_verify_mode = rb_intern("verify_mode");
   VALUE verify_mode = rb_funcall(mini_ssl_ctx, sym_verify_mode, 0);
 
+  ID sym_ssl_cipher_filter = rb_intern("ssl_cipher_filter");
+  VALUE ssl_cipher_filter = rb_funcall(mini_ssl_ctx, sym_ssl_cipher_filter, 0);
+
   ctx = SSL_CTX_new(SSLv23_server_method());
   conn->ctx = ctx;
 
@@ -175,7 +178,13 @@ VALUE engine_init_server(VALUE self, VALUE mini_ssl_ctx) {
   SSL_CTX_set_options(ctx, SSL_OP_CIPHER_SERVER_PREFERENCE | SSL_OP_NO_SSLv2 | SSL_OP_NO_SSLv3 | SSL_OP_SINGLE_DH_USE | SSL_OP_SINGLE_ECDH_USE | SSL_OP_NO_COMPRESSION);
   SSL_CTX_set_session_cache_mode(ctx, SSL_SESS_CACHE_OFF);
 
-  SSL_CTX_set_cipher_list(ctx, "HIGH:!aNULL@STRENGTH");
+  if (!NIL_P(ssl_cipher_filter)) {
+    StringValue(ssl_cipher_filter);
+    SSL_CTX_set_cipher_list(ctx, RSTRING_PTR(ssl_cipher_filter));
+  }
+  else {
+    SSL_CTX_set_cipher_list(ctx, "HIGH:!aNULL@STRENGTH");
+  }
 
   DH *dh = get_dh1024();
   SSL_CTX_set_tmp_dh(ctx, dh);

data/ext/puma_http11/org/jruby/puma/MiniSSL.java

@@ -170,6 +170,12 @@ public class MiniSSL extends RubyObject {
         engine.setNeedClientAuth(true);
     }
 
+    IRubyObject sslCipherListObject = miniSSLContext.callMethod(threadContext, "ssl_cipher_list");
+    if (!sslCipherListObject.isNil()) {
+      String[] sslCipherList = sslCipherListObject.convertToString().asJavaString().split(",");
+      engine.setEnabledCipherSuites(sslCipherList);
+    }
+
     SSLSession session = engine.getSession();
     inboundNetData = new MiniSSLBuffer(session.getPacketBufferSize());
     outboundAppData = new MiniSSLBuffer(session.getApplicationBufferSize());

data/lib/puma/binder.rb

@@ -162,6 +162,7 @@ module Puma
             end
 
             ctx.keystore_pass = params['keystore-pass']
+            ctx.ssl_cipher_list = params['ssl_cipher_list'] if params['ssl_cipher_list']
           else
             unless params['key']
               @events.error "Please specify the SSL key via 'key='"
@@ -182,6 +183,7 @@ module Puma
             end
 
             ctx.ca = params['ca'] if params['ca']
+            ctx.ssl_cipher_filter = params['ssl_cipher_filter'] if params['ssl_cipher_filter']
           end
 
           if params['verify_mode']
@@ -313,6 +315,7 @@ module Puma
       s.setsockopt(Socket::SOL_SOCKET,Socket::SO_REUSEADDR, true)
       s.listen backlog
 
+
       ssl = MiniSSL::Server.new s, ctx
       env = @proto_env.dup
       env[HTTPS_KEY] = HTTPS

data/lib/puma/cli.rb

@@ -84,6 +84,14 @@ module Puma
       raise UnsupportedOption
     end
 
+    def configure_control_url(command_line_arg)
+      if command_line_arg
+        @control_url = command_line_arg
+      elsif Puma.jruby?
+        unsupported "No default url available on JRuby"
+      end
+    end
+
     # Build the OptionParser object to handle the available options.
     #
 
@@ -98,13 +106,13 @@ module Puma
             file_config.load arg
           end
 
-          o.on "--control URL", "The bind url to use for the control server",
-            "Use 'auto' to use temp unix server" do |arg|
-            if arg
-              @control_url = arg
-            elsif Puma.jruby?
-              unsupported "No default url available on JRuby"
-            end
+          o.on "--control-url URL", "The bind url to use for the control server. Use 'auto' to use temp unix server" do |arg|
+            configure_control_url(arg)
+          end
+
+          # alias --control-url for backwards-compatibility
+          o.on "--control URL", "DEPRECATED alias for --control-url" do |arg|
+            configure_control_url(arg)
           end
 
           o.on "--control-token TOKEN",

data/lib/puma/client.rb

@@ -21,6 +21,17 @@ module Puma
 
   class ConnectionError < RuntimeError; end
 
+  # An instance of this class represents a unique request from a client.
+  # For example a web request from a browser or from CURL. This
+  #
+  # An instance of `Puma::Client` can be used as if it were an IO object
+  # for example it is passed into `IO.select` inside of the `Puma::Reactor`.
+  # This is accomplished by the `to_io` method which gets called on any
+  # non-IO objects being used with the IO api such as `IO.select.
+  #
+  # Instances of this class are responsible for knowing if
+  # the header and body are fully buffered via the `try_to_finish` method.
+  # They can be used to "time out" a response via the `timeout_at` reader.
   class Client
     include Puma::Const
     extend  Puma::Delegation

data/lib/puma/cluster.rb

@@ -5,6 +5,17 @@ require 'puma/plugin'
 require 'time'
 
 module Puma
+  # This class is instantiated by the `Puma::Launcher` and used
+  # to boot and serve a Ruby application when puma "workers" are needed
+  # i.e. when using multi-processes. For example `$ puma -w 5`
+  #
+  # At the core of this class is running an instance of `Puma::Server` which
+  # gets created via the `start_server` method from the `Puma::Runner` class
+  # that this inherits from.
+  #
+  # An instance of this class will spawn the number of processes passed in
+  # via the `spawn_workers` method call. Each worker will have it's own
+  # instance of a `Puma::Server`.
   class Cluster < Runner
     WORKER_CHECK_INTERVAL = 5
 
@@ -281,7 +292,9 @@ module Puma
           begin
             b = server.backlog || 0
             r = server.running || 0
-            payload = %Q!#{base_payload}{ "backlog":#{b}, "running":#{r} }\n!
+            t = server.pool_capacity || 0
+            m = server.max_threads || 0
+            payload = %Q!#{base_payload}{ "backlog":#{b}, "running":#{r}, "pool_capacity":#{t}, "max_threads": #{m} }\n!
             io << payload
           rescue IOError
             Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue

data/lib/puma/const.rb

@@ -98,8 +98,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.0".freeze
+    CODE_NAME = "Llamas in Pajamas".freeze
     PUMA_SERVER_STRING = ['puma', PUMA_VERSION, CODE_NAME].join(' ').freeze
 
     FAST_TRACK_KA_TIMEOUT = 0.2

data/lib/puma/control_cli.rb

@@ -220,7 +220,7 @@ module Puma
     end
 
     def run
-      start if @command == "start"
+      return start if @command == "start"
 
       prepare_configuration
 

data/lib/puma/minissl.rb

@@ -124,7 +124,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 +141,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 +180,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 +196,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/reactor.rb

@@ -2,15 +2,54 @@ 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 +60,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 +260,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 +284,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

@@ -2,6 +2,9 @@ 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 +22,10 @@ module Puma
       @options[:environment] == "development"
     end
 
+    def test?
+      @options[:environment] == "test"
+    end
+
     def log(str)
       @events.log str
     end
@@ -165,7 +172,7 @@ module Puma
         server.early_hints = true
       end
 
-      unless development?
+      unless development? || test?
         server.leak_stack_on_error = false
       end
 

data/lib/puma/server.rb

@@ -23,6 +23,15 @@ require 'socket'
 module Puma
 
   # The HTTP Server itself. Serves out a single Rack app.
+  #
+  # This class is used by the `Puma::Single` and `Puma::Cluster` classes
+  # to generate one or more `Puma::Server` instances capable of handling requests.
+  # Each Puma process will contain one `Puma::Server` instacne.
+  #
+  # The `Puma::Server` instance pulls requests from the socket, adds them to a
+  # `Puma::Reactor` where they get eventually passed to a `Puma::ThreadPool`.
+  #
+  # Each `Puma::Server` will have one reactor and one thread pool.
   class Server
 
     include Puma::Const
@@ -159,6 +168,18 @@ module Puma
       @thread_pool and @thread_pool.spawned
     end
 
+
+    # This number represents the number of requests that
+    # the server is capable of taking right now.
+    #
+    # For example if the number is 5 then it means
+    # there are 5 threads sitting idle ready to take
+    # a request. If one request comes in, then the
+    # value would be 4 until it finishes processing.
+    def pool_capacity
+      @thread_pool and @thread_pool.pool_capacity
+    end
+
     # Lopez Mode == raw tcp apps
 
     def run_lopez_mode(background=true)
@@ -241,7 +262,12 @@ module Puma
         STDERR.puts "Exception handling servers: #{e.message} (#{e.class})"
         STDERR.puts e.backtrace
       ensure
-        @check.close
+        begin
+          @check.close
+        rescue
+          Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
+        end
+
         @notify.close
 
         if @status != :restart and @own_binder

data/lib/puma/single.rb

@@ -3,11 +3,20 @@ require 'puma/detect'
 require 'puma/plugin'
 
 module Puma
+  # This class is instantiated by the `Puma::Launcher` and used
+  # to boot and serve a Ruby application when no puma "workers" are needed
+  # i.e. only using "threaded" mode. For example `$ puma -t 1:5`
+  #
+  # At the core of this class is running an instance of `Puma::Server` which
+  # gets created via the `start_server` method from the `Puma::Runner` class
+  # that this inherits from.
   class Single < Runner
     def stats
       b = @server.backlog || 0
       r = @server.running || 0
-      %Q!{ "backlog": #{b}, "running": #{r} }!
+      t = @server.pool_capacity || 0
+      m = @server.max_threads || 0
+      %Q!{ "backlog": #{b}, "running": #{r}, "pool_capacity": #{t}, "max_threads": #{m} }!
     end
 
     def restart

data/lib/puma/thread_pool.rb

@@ -1,8 +1,17 @@
 require 'thread'
 
 module Puma
-  # A simple thread pool management object.
+  # Internal Docs for A simple thread pool management object.
   #
+  # Each Puma "worker" has a thread pool to process requests.
+  #
+  # First a connection to a client is made in `Puma::Server`. It is wrapped in a
+  # `Puma::Client` instance and then passed to the `Puma::Reactor` to ensure
+  # the whole request is buffered into memory. Once the request is ready, it is passed into
+  # a thread pool via the `Puma::ThreadPool#<<` operator where it is stored in a `@todo` array.
+  #
+  # Each thread in the pool has an internal loop where it pulls a request from the `@todo` array
+  # and proceses it.
   class ThreadPool
     class ForceShutdown < RuntimeError
     end
@@ -49,7 +58,7 @@ module Puma
       @clean_thread_locals = false
     end
 
-    attr_reader :spawned, :trim_requested
+    attr_reader :spawned, :trim_requested, :waiting
     attr_accessor :clean_thread_locals
 
     def self.clean_thread_locals
@@ -64,6 +73,10 @@ module Puma
       @mutex.synchronize { @todo.size }
     end
 
+    def pool_capacity
+      waiting + (@max - spawned)
+    end
+
     # :nodoc:
     #
     # Must be called with @mutex held!
@@ -153,16 +166,42 @@ module Puma
       end
     end
 
+    # This method is used by `Puma::Server` to let the server know when
+    # the thread pool can pull more requests from the socket and
+    # pass to the reactor.
+    #
+    # The general idea is that the thread pool can only work on a fixed
+    # number of requests at the same time. If it is already processing that
+    # number of requests then it is at capacity. If another Puma process has
+    # spare capacity, then the request can be left on the socket so the other
+    # worker can pick it up and process it.
+    #
+    # For example: if there are 5 threads, but only 4 working on
+    # requests, this method will not wait and the `Puma::Server`
+    # can pull a request right away.
+    #
+    # If there are 5 threads and all 5 of them are busy, then it will
+    # pause here, and wait until the `not_full` condition variable is
+    # signaled, usually this indicates that a request has been processed.
+    #
+    # It's important to note that even though the server might accept another
+    # request, it might not be added to the `@todo` array right away.
+    # For example if a slow client has only sent a header, but not a body
+    # then the `@todo` array would stay the same size as the reactor works
+    # to try to buffer the request. In tha scenario the next call to this
+    # method would not block and another request would be added into the reactor
+    # by the server. This would continue until a fully bufferend request
+    # makes it through the reactor and can then be processed by the thread pool.
     def wait_until_not_full
       @mutex.synchronize do
         while true
           return if @shutdown
-          return if @waiting > 0
 
           # If we can still spin up new threads and there
-          # is work queued, then accept more work until we would
+          # is work queued that cannot be handled by waiting
+          # threads, then accept more work until we would
           # spin up the max number of threads.
-          return if @todo.size < @max - @spawned
+          return if @todo.size - @waiting < @max - @spawned
 
           @not_full.wait @mutex
         end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puma
 version: !ruby/object:Gem::Version
-  version: 3.11.4
+  version: 3.12.0
 platform: ruby
 authors:
 - Evan Phoenix
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-12 00:00:00.000000000 Z
+date: 2018-07-13 00:00:00.000000000 Z
 dependencies: []
 description: Puma is a simple, fast, threaded, and highly concurrent HTTP 1.1 server
   for Ruby/Rack applications. Puma is intended for use in both development and production
@@ -116,7 +116,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 1.9.3
+      version: '2.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="