puma 3.11.3 → 4.0.0

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
@@ -46,7 +55,7 @@ module Puma
       app = Puma::App::Status.new @launcher
 
       if token = @options[:control_auth_token]
-        app.auth_token = token unless token.empty? or token == :none
+        app.auth_token = token unless token.empty? || token == 'none'
       end
 
       control = Puma::Server.new app, @launcher.events
@@ -165,7 +174,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

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
+
 require 'stringio'
 
 require 'puma/thread_pool'
 require 'puma/const'
 require 'puma/events'
 require 'puma/null_io'
-require 'puma/compat'
 require 'puma/reactor'
 require 'puma/client'
 require 'puma/binder'
@@ -14,15 +15,20 @@ require 'puma/util'
 
 require 'puma/puma_http11'
 
-unless Puma.const_defined? "IOBuffer"
-  require 'puma/io_buffer'
-end
-
 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` instance.
+  #
+  # 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
@@ -68,7 +74,6 @@ module Puma
       @first_data_timeout = options.fetch(:first_data_timeout, FIRST_DATA_TIMEOUT)
 
       @binder = Binder.new(events)
-      @own_binder = true
 
       @leak_stack_on_error = true
 
@@ -91,7 +96,6 @@ module Puma
 
     def inherit_binder(bind)
       @binder = bind
-      @own_binder = false
     end
 
     def tcp_mode!
@@ -159,6 +163,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)
@@ -220,7 +236,11 @@ module Puma
                   # nothing
                 rescue Errno::ECONNABORTED
                   # client closed the socket even before accept
-                  io.close rescue nil
+                  begin
+                    io.close
+                  rescue
+                    Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
+                  end
                 end
               end
             end
@@ -237,11 +257,17 @@ module Puma
         STDERR.puts "Exception handling servers: #{e.message} (#{e.class})"
         STDERR.puts e.backtrace
       ensure
-        @check.close
-        @notify.close
+        begin
+          @check.close
+        rescue
+          Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
+        end
 
-        if @status != :restart and @own_binder
-          @binder.close
+        # Prevent can't modify frozen IOError (RuntimeError)
+        begin
+          @notify.close
+        rescue IOError
+          # no biggy
         end
       end
 
@@ -366,13 +392,20 @@ module Puma
                     end
 
                     pool << client
-                    pool.wait_until_not_full
+                    busy_threads = pool.wait_until_not_full
+                    if busy_threads == 0
+                      @options[:out_of_band].each(&:call) if @options[:out_of_band]
+                    end
                   end
                 rescue SystemCallError
                   # nothing
                 rescue Errno::ECONNABORTED
                   # client closed the socket even before accept
-                  io.close rescue nil
+                  begin
+                    io.close
+                  rescue
+                    Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
+                  end
                 end
               end
             end
@@ -394,10 +427,6 @@ module Puma
       ensure
         @check.close
         @notify.close
-
-        if @status != :restart and @own_binder
-          @binder.close
-        end
       end
 
       @events.fire :state, :done
@@ -563,15 +592,19 @@ module Puma
       env['HTTP_X_FORWARDED_PROTO'] == 'https' ? PORT_443 : PORT_80
     end
 
-    # Given the request +env+ from +client+ and a partial request body
-    # in +body+, finish reading the body if there is one and invoke
-    # the rack app. Then construct the response and write it back to
-    # +client+
+    # Takes the request +req+, invokes the Rack application to construct
+    # the response and writes it back to +req.io+.
+    #
+    # The second parameter +lines+ is a IO-like object unique to this thread.
+    # This is normally an instance of Puma::IOBuffer.
+    #
+    # It'll return +false+ when the connection is closed, this doesn't mean
+    # that the response wasn't successful.
     #
-    # +cl+ is the previously fetched Content-Length header if there
-    # was one. This is an optimization to keep from having to look
-    # it up again.
+    # It'll return +:async+ if the connection remains open but will be handled
+    # elsewhere, i.e. the connection has been hijacked by the Rack application.
     #
+    # Finally, it'll return +true+ on keep-alive connections.
     def handle_request(req, lines)
       env = req.env
       client = req.io
@@ -606,7 +639,7 @@ module Puma
                 fast_write client, "#{k}: #{v}\r\n"
               end
             else
-              fast_write client, "#{k}: #{v}\r\n"
+              fast_write client, "#{k}: #{vs}\r\n"
             end
           end
 
@@ -906,6 +939,10 @@ module Puma
         @events.debug "Drained #{count} additional connections."
       end
 
+      if @status != :restart
+        @binder.close
+      end
+
       if @thread_pool
         if timeout = @options[:force_shutdown_after]
           @thread_pool.shutdown timeout.to_i

data/lib/puma/single.rb

@@ -1,13 +1,24 @@
+# frozen_string_literal: true
+
 require 'puma/runner'
 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
@@ -15,7 +26,7 @@ module Puma
     end
 
     def stop
-      @server.stop false
+      @server.stop(false) if @server
     end
 
     def halt
@@ -25,7 +36,7 @@ module Puma
     def stop_blocked
       log "- Gracefully stopping, waiting for requests to finish"
       @control.stop(true) if @control
-      @server.stop(true)
+      @server.stop(true) if @server
     end
 
     def jruby_daemon?

data/lib/puma/state_file.rb

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

data/lib/puma/tcp_logger.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Puma
   class TCPLogger
     def initialize(logger, app, quiet=false)

data/lib/puma/thread_pool.rb

@@ -1,8 +1,19 @@
+# frozen_string_literal: true
+
 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 +60,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 +75,10 @@ module Puma
       @mutex.synchronize { @todo.size }
     end
 
+    def pool_capacity
+      waiting + (@max - spawned)
+    end
+
     # :nodoc:
     #
     # Must be called with @mutex held!
@@ -153,16 +168,46 @@ 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.
+    #
+    # Returns the current number of busy threads, or +nil+ if shutting down.
+    #
     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
+          busy_threads = @spawned - @waiting + @todo.size
+          return busy_threads if @max > busy_threads
 
           @not_full.wait @mutex
         end

data/lib/puma/util.rb

@@ -1,10 +1,6 @@
-major, minor, patch = RUBY_VERSION.split('.').map { |v| v.to_i }
+# frozen_string_literal: true
 
-if major == 1 && minor == 9 && patch == 3 && RUBY_PATCHLEVEL < 125
-  require 'puma/rack/backports/uri/common_193'
-else
-  require 'uri/common'
-end
+require 'uri/common'
 
 module Puma
   module Util

data/lib/rack/handler/puma.rb

@@ -9,6 +9,7 @@ module Rack
       }
 
       def self.config(app, options = {})
+        require 'puma'
         require 'puma/configuration'
         require 'puma/events'
         require 'puma/launcher'
@@ -48,6 +49,9 @@ module Rack
             self.set_host_port_to_config(host, port, user_config)
           end
 
+          if default_options[:Host]
+            file_config.set_default_host(default_options[:Host])
+          end
           self.set_host_port_to_config(default_options[:Host], default_options[:Port], default_config)
 
           user_config.app app

data/tools/jungle/README.md

@@ -1,9 +1,5 @@
 # Puma as a service
 
-## Init.d
-
-See `/tools/jungle/init.d` for tools to use with init.d and start-stop-daemon.
-
 ## Upstart
 
 See `/tools/jungle/upstart` for Ubuntu's upstart scripts.
@@ -11,3 +7,13 @@ See `/tools/jungle/upstart` for Ubuntu's upstart scripts.
 ## Systemd
 
 See [/docs/systemd](https://github.com/puma/puma/blob/master/docs/systemd.md).
+
+## Init.d
+
+Deprecatation Warning : `init.d` was replaced by `systemd` since Debian 8 and Ubuntu 16.04, you should look into [/docs/systemd](https://github.com/puma/puma/blob/master/docs/systemd.md) unless you are on an older OS.
+
+See `/tools/jungle/init.d` for tools to use with init.d and start-stop-daemon.
+
+## rc.d
+
+See `/tools/jungle/rc.d` for FreeBSD's rc.d scripts

data/tools/jungle/init.d/README.md

@@ -1,5 +1,7 @@
 # Puma daemon service
 
+Deprecatation Warning : `init.d` was replaced by `systemd` since Debian 8 and Ubuntu 16.04, you should look into [/docs/systemd](https://github.com/puma/puma/blob/master/docs/systemd.md) unless you are on an older OS. 
+
 Init script to manage multiple Puma servers on the same box using start-stop-daemon.
 
 ## Installation 

data/tools/jungle/init.d/puma

@@ -47,11 +47,11 @@ do_start_one() {
   PIDFILE=$1/tmp/puma/pid
   if [ -e $PIDFILE ]; then
     PID=`cat $PIDFILE`
-    # If the puma isn't running, run it, otherwise restart it.
-    if [ "`ps -A -o pid= | grep -c $PID`" -eq 0 ]; then
-      do_start_one_do $1
-    else
+    # If the puma is running, restart it, otherwise run it.
+    if ps -p $PID > /dev/null; then
       do_restart_one $1
+    else
+      do_start_one_do $1
     fi
   else
     do_start_one_do $1
@@ -105,9 +105,7 @@ do_stop_one() {
   STATEFILE=$1/tmp/puma/state
   if [ -e $PIDFILE ]; then
     PID=`cat $PIDFILE`
-    if [ "`ps -A -o pid= | grep -c $PID`" -eq 0 ]; then
-      log_daemon_msg "---> Puma $1 isn't running."
-    else
+    if ps -p $PID > /dev/null; then
       log_daemon_msg "---> About to kill PID `cat $PIDFILE`"
       if [ "$USE_LOCAL_BUNDLE" -eq 1 ]; then
         cd $1 && bundle exec pumactl --state $STATEFILE stop
@@ -116,6 +114,8 @@ do_stop_one() {
       fi
       # Many daemons don't delete their pidfiles when they exit.
       rm -f $PIDFILE $STATEFILE
+    else
+      log_daemon_msg "---> Puma $1 isn't running."
     fi
   else
     log_daemon_msg "---> No puma here..."