puma 3.6.0 → 3.12.0

data/lib/puma/single.rb

@@ -1,11 +1,22 @@
 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
-      r = @server.running
-      %Q!{ "backlog": #{b}, "running": #{r} }!
+      b = @server.backlog || 0
+      r = @server.running || 0
+      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,13 +1,26 @@
 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
 
+    # How long, after raising the ForceShutdown of a thread during
+    # forced shutdown mode, to wait for the thread to try and finish
+    # up its work before leaving the thread to die on the vine.
+    SHUTDOWN_GRACE_TIME = 5 # seconds
+
     # Maintain a minimum of +min+ and maximum of +max+ threads
     # in the pool.
     #
@@ -45,11 +58,11 @@ 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
-      Thread.current.keys.each do |key|
+      Thread.current.keys.each do |key| # rubocop: disable Performance/HashEachMethods
         Thread.current[key] = nil unless key == :__recursive_key__
       end
     end
@@ -60,6 +73,10 @@ module Puma
       @mutex.synchronize { @todo.size }
     end
 
+    def pool_capacity
+      waiting + (@max - spawned)
+    end
+
     # :nodoc:
     #
     # Must be called with @mutex held!
@@ -67,9 +84,9 @@ module Puma
     def spawn_thread
       @spawned += 1
 
-      th = Thread.new do
+      th = Thread.new(@spawned) do |spawned|
         # Thread name is new in Ruby 2.3
-        Thread.current.name = 'puma %03i' % @spawned if Thread.current.respond_to?(:name=)
+        Thread.current.name = 'puma %03i' % spawned if Thread.current.respond_to?(:name=)
         todo  = @todo
         block = @block
         mutex = @mutex
@@ -149,9 +166,43 @@ 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
-        until @todo.size - @waiting < @max - @spawned or @shutdown
+        while true
+          return if @shutdown
+
+          # If we can still spin up new threads and there
+          # 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 - @waiting < @max - @spawned
+
           @not_full.wait @mutex
         end
       end
@@ -181,7 +232,9 @@ module Puma
           @spawned -= 1
         end
 
-        @workers -= dead_workers
+        @workers.delete_if do |w|
+          dead_workers.include?(w)
+        end
       end
     end
 
@@ -209,7 +262,7 @@ module Puma
       end
     end
 
-    def auto_trim!(timeout=5)
+    def auto_trim!(timeout=30)
       @auto_trim = AutoTrim.new(self, timeout)
       @auto_trim.start!
     end
@@ -257,18 +310,12 @@ module Puma
         @workers.dup
       end
 
-      case timeout
-      when -1
+      if timeout == -1
+        # Wait for threads to finish without force shutdown.
         threads.each(&:join)
-      when 0
-        threads.each do |t|
-          t.raise ForceShutdown
-        end
-
-        threads.each do |t|
-          t.join Const::SHUTDOWN_GRACE_TIME
-        end
       else
+        # Wait for threads to finish after n attempts (+timeout+).
+        # If threads are still running, it will forcefully kill them.
         timeout.times do
           threads.delete_if do |t|
             t.join 1
@@ -286,7 +333,7 @@ module Puma
         end
 
         threads.each do |t|
-          t.join Const::SHUTDOWN_GRACE_TIME
+          t.join SHUTDOWN_GRACE_TIME
         end
       end
 

data/lib/puma/util.rb

@@ -1,10 +1,6 @@
 major, minor, patch = RUBY_VERSION.split('.').map { |v| v.to_i }
 
-if major == 1 && minor < 9
-  require 'puma/rack/backports/uri/common_18'
-elsif major == 1 && minor == 9 && patch == 2 && RUBY_PATCHLEVEL <= 328 && RUBY_ENGINE != 'jruby'
-  require 'puma/rack/backports/uri/common_192'
-elsif major == 1 && minor == 9 && patch == 3 && RUBY_PATCHLEVEL < 125
+if major == 1 && minor == 9 && patch == 3 && RUBY_PATCHLEVEL < 125
   require 'puma/rack/backports/uri/common_193'
 else
   require 'uri/common'

data/lib/rack/handler/puma.rb

@@ -1,5 +1,4 @@
 require 'rack/handler'
-require 'puma'
 
 module Rack
   module Handler
@@ -9,38 +8,58 @@ module Rack
         :Silent  => false
       }
 
-      def self.run(app, options = {})
-        options  = DEFAULT_OPTIONS.merge(options)
+      def self.config(app, options = {})
+        require 'puma'
+        require 'puma/configuration'
+        require 'puma/events'
+        require 'puma/launcher'
+
+        default_options = DEFAULT_OPTIONS.dup
+
+        # Libraries pass in values such as :Port and there is no way to determine
+        # if it is a default provided by the library or a special value provided
+        # by the user. A special key `user_supplied_options` can be passed. This
+        # contains an array of all explicitly defined user options. We then
+        # know that all other values are defaults
+        if user_supplied_options = options.delete(:user_supplied_options)
+          (options.keys - user_supplied_options).each do |k|
+            default_options[k] = options.delete(k)
+          end
+        end
 
-        conf = ::Puma::Configuration.new(options) do |c|
-          c.quiet
+        conf = ::Puma::Configuration.new(options, default_options) do |user_config, file_config, default_config|
+          user_config.quiet
 
           if options.delete(:Verbose)
             app = Rack::CommonLogger.new(app, STDOUT)
           end
 
           if options[:environment]
-            c.environment options[:environment]
+            user_config.environment options[:environment]
           end
 
           if options[:Threads]
             min, max = options.delete(:Threads).split(':', 2)
-            c.threads min, max
+            user_config.threads min, max
           end
 
-          host = options[:Host]
-
-          if host && (host[0,1] == '.' || host[0,1] == '/')
-            c.bind "unix://#{host}"
-          else
-            host ||= ::Puma::Configuration::DefaultTCPHost
-            port = options[:Port] || ::Puma::Configuration::DefaultTCPPort
-
-            c.port port, host
+          if options[:Host] || options[:Port]
+            host = options[:Host] || default_options[:Host]
+            port = options[:Port] || default_options[:Port]
+            self.set_host_port_to_config(host, port, user_config)
           end
 
-          c.app app
+          self.set_host_port_to_config(default_options[:Host], default_options[:Port], default_config)
+
+          user_config.app app
         end
+        conf
+      end
+
+
+
+      def self.run(app, options = {})
+        conf   = self.config(app, options)
 
         events = options.delete(:Silent) ? ::Puma::Events.strings : ::Puma::Events.stdio
 
@@ -64,6 +83,28 @@ module Rack
           "Verbose"         => "Don't report each request (default: false)"
         }
       end
+    private
+      def self.set_host_port_to_config(host, port, config)
+        config.clear_binds! if host || port
+
+        if host && (host[0,1] == '.' || host[0,1] == '/')
+          config.bind "unix://#{host}"
+        elsif host && host =~ /^ssl:\/\//
+          uri = URI.parse(host)
+          uri.port ||= port || ::Puma::Configuration::DefaultTCPPort
+          config.bind uri.to_s
+        else
+
+          if host
+            port ||= ::Puma::Configuration::DefaultTCPPort
+          end
+
+          if port
+            host ||= ::Puma::Configuration::DefaultTCPHost
+            config.port port, host
+          end
+        end
+      end
     end
 
     register :puma, Puma

data/tools/jungle/README.md

@@ -1,9 +1,19 @@
 # Puma as a service
 
+## Upstart
+
+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.
 
-## Upstart
+## rc.d
 
-See `/tools/jungle/upstart` for Ubuntu's upstart scripts.
+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 
@@ -22,16 +24,21 @@ Init script to manage multiple Puma servers on the same box using start-stop-dae
 
 Puma apps are held in /etc/puma.conf by default. It's mainly a CSV file and every line represents one app. Here's the syntax:
 
-    app-path,user,config-file-path,log-file-path
+    app-path,user,config-file-path,log-file-path,environment-variables
 
 You can add an instance by editing the file or running the following command:
 
     sudo /etc/init.d/puma add /path/to/app user /path/to/app/config/puma.rb /path/to/app/log/puma.log
 
-The config and log paths are optional parameters and default to:
+The config and log paths, as well as the environment variables, are optional parameters and default to:
 
 * config: /path/to/app/*config/puma.rb*
 * log: /path/to/app/*log/puma.log*
+* environment: (empty)
+
+Multiple environment variables need to be separated by a semicolon, e.g.
+
+    FOO=1;BAR=2
 
 To remove an app, simply delete the line from the config file or run:
 

data/tools/jungle/init.d/puma

@@ -5,9 +5,9 @@
 # Required-Stop:     $remote_fs $syslog
 # Default-Start:     2 3 4 5
 # Default-Stop:      0 1 6
-# Short-Description: Example initscript
-# Description:       This file should be used to construct scripts to be
-#                    placed in /etc/init.d.
+# Short-Description: Puma web server
+# Description:       A ruby web server built for concurrency http://puma.io
+#                    initscript to be placed in /etc/init.d.
 ### END INIT INFO
 
 # Author: Darío Javier Cravero <dario@exordo.com>
@@ -39,17 +39,7 @@ do_start() {
   log_daemon_msg "=> Running the jungle..."
   for i in $JUNGLE; do
     dir=`echo $i | cut -d , -f 1`
-    user=`echo $i | cut -d , -f 2`
-    config_file=`echo $i | cut -d , -f 3`
-    if [ "$config_file" = "" ]; then
-      config_file="$dir/config/puma.rb"
-    fi
-    log_file=`echo $i | cut -d , -f 4`
-    if [ "$log_file" = "" ]; then
-      log_file="$dir/log/puma.log"
-    fi
-    environment=`echo $i | cut -d , -f 5`
-    do_start_one $dir $user $config_file $log_file $environment
+    do_start_one $dir
   done
 }
 
@@ -58,29 +48,42 @@ do_start_one() {
   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 $2 $3 $4 $5
+    if ps -p $PID > /dev/null; then
+      do_start_one_do $1
     else
       do_restart_one $1
     fi
   else
-    do_start_one_do $1 $2 $3 $4 $5
+    do_start_one_do $1
   fi
 }
 
 do_start_one_do() {
-  log_daemon_msg "--> Woke up puma $1"
-  log_daemon_msg "user $2"
-  log_daemon_msg "log to $4"
+  i=`grep $1 $CONFIG`
+  dir=`echo $i | cut -d , -f 1`
+  user=`echo $i | cut -d , -f 2`
+  config_file=`echo $i | cut -d , -f 3`
+  if [ "$config_file" = "" ]; then
+    config_file="$dir/config/puma.rb"
+  fi
+  log_file=`echo $i | cut -d , -f 4`
+  if [ "$log_file" = "" ]; then
+    log_file="$dir/log/puma.log"
+  fi
+  environment=`echo $i | cut -d , -f 5`
+
+  log_daemon_msg "--> Woke up puma $dir"
+  log_daemon_msg "user $user"
+  log_daemon_msg "log to $log_file"
 
-  if [ ! -z "$5" ]; then
-    for e in $(echo "$5" | tr ';' '\n'); do
+  if [ ! -z "$environment" ]; then
+    for e in $(echo "$environment" | tr ';' '\n'); do
         log_daemon_msg "environment $e"
         v=${e%%\=*} ;  eval "$e" ; export $v
     done
   fi
 
-  start-stop-daemon --verbose --start --chdir $1 --chuid $2 --background --exec $RUNPUMA -- $1 $3 $4
+  start-stop-daemon --verbose --start --chdir $dir --chuid $user --background --exec $RUNPUMA -- $dir $config_file $log_file
 }
 
 #
@@ -102,7 +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
+    if ps -p $PID > /dev/null; then
       log_daemon_msg "---> Puma $1 isn't running."
     else
       log_daemon_msg "---> About to kill PID `cat $PIDFILE`"
@@ -135,8 +138,6 @@ do_restart() {
 #
 do_restart_one() {
   PIDFILE=$1/tmp/puma/pid
-  i=`grep $1 $CONFIG`
-  dir=`echo $i | cut -d , -f 1`
 
   if [ -e $PIDFILE ]; then
     log_daemon_msg "--> About to restart puma $1"
@@ -144,17 +145,7 @@ do_restart_one() {
     # TODO Check if process exist
   else
     log_daemon_msg "--> Your puma was never playing... Let's get it out there first"
-    user=`echo $i | cut -d , -f 2`
-    config_file=`echo $i | cut -d , -f 3`
-    if [ "$config_file" = "" ]; then
-      config_file="$dir/config/puma.rb"
-    fi
-    log_file=`echo $i | cut -d , -f 4`
-    if [ "$log_file" = "" ]; then
-      log_file="$dir/log/puma.log"
-    fi
-    environment=`echo $i | cut -d , -f 5`
-    do_start_one $dir $user $config_file $log_file $environment
+    do_start_one $1
   fi
 	return 0
 }
@@ -174,26 +165,14 @@ do_phased_restart() {
 #
 do_phased_restart_one() {
   PIDFILE=$1/tmp/puma/pid
-  i=`grep $1 $CONFIG`
-  dir=`echo $i | cut -d , -f 1`
 
   if [ -e $PIDFILE ]; then
     log_daemon_msg "--> About to restart puma $1"
     kill -s USR1 `cat $PIDFILE`
     # TODO Check if process exist
   else
-    log_daemon_msg "--> Your puma was never playing... Let's get it out there first" 
-    user=`echo $i | cut -d , -f 2`
-    config_file=`echo $i | cut -d , -f 3`
-    if [ "$config_file" = "" ]; then
-      config_file="$dir/config/puma.rb"
-    fi
-    log_file=`echo $i | cut -d , -f 4`
-    if [ "$log_file" = "" ]; then
-      log_file="$dir/log/puma.log"
-    fi
-    environment=`echo $i | cut -d , -f 5`
-    do_start_one $dir $user $config_file $log_file $environment
+    log_daemon_msg "--> Your puma was never playing... Let's get it out there first"
+    do_start_one $1
   fi
 	return 0
 }
@@ -339,16 +318,7 @@ case "$1" in
     else
       i=`grep $2 $CONFIG`
       dir=`echo $i | cut -d , -f 1`
-      user=`echo $i | cut -d , -f 2`
-      config_file=`echo $i | cut -d , -f 3`
-      if [ "$config_file" = "" ]; then
-        config_file="$dir/config/puma.rb"
-      fi
-      log_file=`echo $i | cut -d , -f 4`
-      if [ "$log_file" = "" ]; then
-        log_file="$dir/log/puma.log"
-      fi
-      do_start_one $dir $user $config_file $log_file
+      do_start_one $dir
     fi
     case "$?" in
       0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
@@ -444,7 +414,7 @@ case "$1" in
     echo "  Add a Puma: $SCRIPTNAME add /path/to/app user /path/to/app/config/puma.rb /path/to/app/config/log/puma.log"
     echo "    config and log are optionals."
     echo "  Remove a Puma: $SCRIPTNAME remove /path/to/app"
-    echo "  On a Puma: $SCRIPTNAME {start|stop|status|restart} PUMA-NAME" >&2
+    echo "  On a Puma: $SCRIPTNAME {start|stop|status|restart|phased-restart} PUMA-NAME" >&2
     exit 3
   ;;
 esac