puma 3.9.0 → 3.12.0

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
-      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,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,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
@@ -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!
@@ -71,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
@@ -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

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'
@@ -21,7 +22,7 @@ module Rack
         # 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, v|
+          (options.keys - user_supplied_options).each do |k|
             default_options[k] = options.delete(k)
           end
         end
@@ -84,6 +85,8 @@ module Rack
       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:\/\//

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 

data/tools/jungle/init.d/puma

@@ -48,7 +48,7 @@ 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
+    if ps -p $PID > /dev/null; then
       do_start_one_do $1
     else
       do_restart_one $1
@@ -105,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`"

data/tools/jungle/init.d/run-puma

@@ -15,4 +15,4 @@ elif [ -f "$HOME/.rvm/scripts/rvm" ]; then
 fi
 
 app=$1; config=$2; log=$3;
-cd $app && exec bundle exec puma -C $config 2>&1 >> $log
+cd $app && exec bundle exec puma -C $config >> $log 2>&1

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

@@ -0,0 +1,74 @@
+# Puma as a service using rc.d
+
+Manage multilpe Puma servers as services on one box using FreeBSD's rc.d service.
+
+## Dependencies
+
+* `jq` - a command-line json parser is needed to parse the json in the config file
+
+## Installation
+
+    # Copy the puma script to the rc.d directory (make sure everyone has read/execute perms)
+    sudo cp puma /usr/local/etc/rc.d/
+
+    # Create an empty configuration file
+    sudo touch /usr/local/etc/puma.conf
+
+    # Enable the puma service
+    sudo echo 'puma_enable="YES"' >> /etc/rc.conf
+
+## Managing the jungle
+
+Puma apps are referenced in /usr/local/etc/puma.conf by default.
+
+Start the jungle running:
+
+`service puma start`
+
+This script will run at boot time.
+
+
+You can also stop the jungle (stops ALL puma instances) by running:
+
+`service puma stop`
+
+
+To restart the jungle:
+
+`service puma restart`
+
+## Conventions
+
+* The script expects:
+  * a config file to exist under `config/puma.rb` in your app. E.g.: `/home/apps/my-app/config/puma.rb`.
+
+You can always change those defaults by editing the scripts.
+
+## Here's what a minimal app's config file should have
+
+```
+{
+	"servers" : [
+		{
+			"dir": "/path/to/rails/project",
+			"user": "deploy-user",
+			"ruby_version": "ruby.version",
+			"ruby_env": "rbenv"
+		}
+	]
+}
+```
+
+## Before starting...
+
+You need to customise `puma.conf` to:
+
+* Set the right user your app should be running on unless you want root to execute it!
+* Set the directory of the app
+* Set the ruby version to execute
+* Set the ruby environment (currently set to rbenv, since that is the only ruby environment currently supported)
+* Add additional server instances following the scheme in the example
+
+## Notes:
+
+Only rbenv is currently supported.

data/tools/jungle/rc.d/puma

@@ -0,0 +1,61 @@
+#!/bin/sh
+#
+
+# PROVIDE: puma
+
+. /etc/rc.subr
+
+name="puma"
+start_cmd="puma_start"
+stop_cmd="puma_stop"
+restart_cmd="puma_restart"
+rcvar=puma_enable
+required_files=/usr/local/etc/puma.conf
+
+puma_start()
+{
+	server_count=$(/usr/local/bin/jq ".servers[] .ruby_env" /usr/local/etc/puma.conf | wc -l)
+	i=0	
+	while [ "$i" -lt "$server_count" ]; do
+		rb_env=$(/usr/local/bin/jq -r ".servers[$i].ruby_env" /usr/local/etc/puma.conf)
+		dir=$(/usr/local/bin/jq -r ".servers[$i].dir" /usr/local/etc/puma.conf)
+		user=$(/usr/local/bin/jq -r ".servers[$i].user" /usr/local/etc/puma.conf)
+		rb_ver=$(/usr/local/bin/jq -r ".servers[$i].ruby_version" /usr/local/etc/puma.conf)
+		case $rb_env in
+			"rbenv")
+				su - $user -c "cd $dir && rbenv shell $rb_ver && bundle exec puma -C $dir/config/puma.rb -d"
+				;;
+			*)
+				;;
+		esac
+		i=$(( i + 1 ))
+	done
+}
+
+puma_stop()
+{
+    pkill ruby
+}
+
+puma_restart()
+{
+	server_count=$(/usr/local/bin/jq ".servers[] .ruby_env" /usr/local/etc/puma.conf | wc -l)
+	i=0	
+	while [ "$i" -lt "$server_count" ]; do
+		rb_env=$(/usr/local/bin/jq -r ".servers[$i].ruby_env" /usr/local/etc/puma.conf)
+		dir=$(/usr/local/bin/jq -r ".servers[$i].dir" /usr/local/etc/puma.conf)
+		user=$(/usr/local/bin/jq -r ".servers[$i].user" /usr/local/etc/puma.conf)
+		rb_ver=$(/usr/local/bin/jq -r ".servers[$i].ruby_version" /usr/local/etc/puma.conf)
+		case $rb_env in
+			"rbenv")
+				su - $user -c "cd $dir && pkill ruby && rbenv shell $ruby_version && bundle exec puma -C $dir/config/puma.rb -d"
+				;;
+			*)
+				;;
+		esac
+		i=$(( i + 1 ))
+	done
+}
+
+load_rc_config $name
+run_rc_command "$1"

data/tools/jungle/rc.d/puma.conf

@@ -0,0 +1,10 @@
+{
+	"servers" : [
+		{
+			"dir": "/path/to/rails/project",
+			"user": "deploy-user",
+			"ruby_version": "ruby.version",
+			"ruby_env": "rbenv"
+		}
+	]
+}

data/tools/trickletest.rb

@@ -31,7 +31,7 @@ st = "GET / HTTP/1.1\r\nHost: www.zedshaw.com\r\nContent-Type: text/plain\r\nCon
 puts "length: #{content.length}"
 
 threads = []
-ARGV[1].to_i.times do 
+ARGV[1].to_i.times do
   t = Thread.new do
     size = 100
     puts ">>>> #{size} sized chunks"

metadata

@@ -1,81 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: puma
 version: !ruby/object:Gem::Version
-  version: 3.9.0
+  version: 3.12.0
 platform: ruby
 authors:
 - Evan Phoenix
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-06-01 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: rack
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.1'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.1'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: rake-compiler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.8'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.8'
-- !ruby/object:Gem::Dependency
-  name: rdoc
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '4.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '4.0'
-- !ruby/object:Gem::Dependency
-  name: hoe
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.15'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.15'
+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
-  environments. In order to get the best throughput, it is highly recommended that
-  you use a  Ruby implementation with real threads like Rubinius or JRuby.
+  environments. It's great for highly concurrent Ruby implementations such as Rubinius
+  and JRuby as well as as providing process worker support to support CRuby well.
 email:
 - evan@phx.io
 executables:
@@ -83,33 +21,22 @@ executables:
 - pumactl
 extensions:
 - ext/puma_http11/extconf.rb
-extra_rdoc_files:
-- ".github/issue_template.md"
-- DEPLOYMENT.md
-- History.md
-- Manifest.txt
-- README.md
-- Release.md
-- docs/nginx.md
-- docs/signals.md
-- docs/systemd.md
-- tools/jungle/README.md
-- tools/jungle/init.d/README.md
-- tools/jungle/upstart/README.md
+extra_rdoc_files: []
 files:
-- ".github/issue_template.md"
-- DEPLOYMENT.md
-- Gemfile
 - History.md
 - LICENSE
-- Manifest.txt
 - README.md
-- Rakefile
-- Release.md
 - bin/puma
 - bin/puma-wild
 - bin/pumactl
+- docs/architecture.md
+- docs/deployment.md
+- docs/images/puma-connection-flow-no-reactor.png
+- docs/images/puma-connection-flow.png
+- docs/images/puma-general-arch.png
 - docs/nginx.md
+- docs/plugins.md
+- docs/restart.md
 - docs/signals.md
 - docs/systemd.md
 - ext/puma_http11/PumaHttp11Service.java
@@ -126,7 +53,6 @@ files:
 - ext/puma_http11/org/jruby/puma/Http11Parser.java
 - ext/puma_http11/org/jruby/puma/MiniSSL.java
 - ext/puma_http11/puma_http11.c
-- gemfiles/2.1-Gemfile
 - lib/puma.rb
 - lib/puma/accept_nonblock.rb
 - lib/puma/app/status.rb
@@ -166,11 +92,13 @@ files:
 - lib/puma/thread_pool.rb
 - lib/puma/util.rb
 - lib/rack/handler/puma.rb
-- puma.gemspec
 - tools/jungle/README.md
 - tools/jungle/init.d/README.md
 - tools/jungle/init.d/puma
 - tools/jungle/init.d/run-puma
+- tools/jungle/rc.d/README.md
+- tools/jungle/rc.d/puma
+- tools/jungle/rc.d/puma.conf
 - tools/jungle/upstart/README.md
 - tools/jungle/upstart/puma-manager.conf
 - tools/jungle/upstart/puma.conf
@@ -178,18 +106,17 @@ files:
 homepage: http://puma.io
 licenses:
 - BSD-3-Clause
-metadata: {}
+metadata:
+  msys2_mingw_dependencies: openssl
 post_install_message: 
-rdoc_options:
-- "--main"
-- README.md
+rdoc_options: []
 require_paths:
 - lib
 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:
   - - ">="
@@ -197,7 +124,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Puma is a simple, fast, threaded, and highly concurrent HTTP 1.1 server for