puma 3.10.0 → 3.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ae7ad36143f718016374d543d84e480b182d0684
-  data.tar.gz: 4209350d304e18ee7144ff07461041479259a205
+  metadata.gz: fc80f23863511d940c0cd4139b67605fda3e943a
+  data.tar.gz: 26362306ddc252d008e729e517ec6821a62c6f4c
 SHA512:
-  metadata.gz: 534b17d2b7ed7ad4917f7587707f7088d8b917d5ce0a08c5b31688088d0447fc013ca084adea61447c6c6463b99cada93ade7457fcd543b4240c72787b07d2dc
-  data.tar.gz: 24cd789a7a1233972c4b52d28743ababe5d3cee3cba963c45ec013cf3cd40f9c0388e40e9145538b5e414a2dc05e97a48a729fa5db3a0cf3f1838dc19da23aa9
+  metadata.gz: d103e80ccccc54908cee56769221c8533b6d0ab366e1d4b749a309a082be23be8440656058f39e39fc59b9ae8f33d957f954c734b5badbfd7c90d056f9e45136
+  data.tar.gz: e0f2dd434998331662ac42e38694eecebf32f836769aef6e6d3815ff3cdb8089de3b743aae44f72a92bd86292a5b1e189cb176aa824a426a7e6e41047f91cf7f

data/History.md

@@ -1,3 +1,24 @@
+## 3.11.0 / 2017-11-20
+
+* 2 features:
+  * HTTP 203 Early Hints (#1403)
+  * 421/451 status codes now have correct status messages attached (#1435)
+
+* 9 bugfixes:
+  * Environment config files (/config/puma/<ENV>.rb) load correctly (#1340)
+  * Specify windows dependencies correctly (#1434, #1436)
+  * puma/events required in test helper (#1418)
+  * Correct control CLI's option help text (#1416)
+  * Remove a warning for unused variable in mini_ssl (#1409)
+  * Correct pumactl docs argument ordering (#1427)
+  * Fix an uninitialized variable warning in server.rb (#1430)
+  * Fix docs typo/error in Launcher init (#1429)
+  * Deal with leading spaces in RUBYOPT (#1455)
+
+* 2 other:
+  * Add docs about internals (#1425, #1452)
+  * Tons of test fixes from @MSP-Greg (#1439, #1442, #1464)
+
 ## 3.10.0 / 2017-08-17
 
 * 3 features:

data/README.md

@@ -74,6 +74,8 @@ $ puma -t 8:32
 
 Puma will automatically scale the number of threads, from the minimum until it caps out at the maximum, based on how much traffic is present. The current default is `0:16`. Feel free to experiment, but be careful not to set the number of maximum threads to a large number, as you may exhaust resources on the system (or hit resource limits).
 
+Be aware that additionally Puma creates threads on its own for internal purposes (e.g. handling slow clients). So even if you specify -t 1:1, expect around 7 threads created in your application.
+
 ### Clustered mode
 
 Puma also offers "clustered mode". Clustered mode `fork`s workers from a master process. Each child process still has its own thread pool. You can tune the number of workers with the `-w` (or `--workers`) flag:
@@ -173,7 +175,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 restart --control-token foo
+$ pumactl -C 'tcp://127.0.0.1:9293' --control-token foo restart
 ```
 
 To see a list of `pumactl` options, use `pumactl --help`.
@@ -215,11 +217,14 @@ Some platforms do not support all Puma features.
 
 ## Known Bugs
 
-For MRI versions 2.2.7, 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.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.3.4 2.4.1).include? RUBY_VERSION
-  gem "stopgap_13632", "~> 1.0", :platforms => ["mri", "mingw", "x64_mingw"]
+if %w(2.2.7 2.2.8 2.3.4 2.4.1).include? RUBY_VERSION
+  begin
+    require 'stopgap_13632'
+  rescue LoadError
+  end
 end
 ```
 

data/docs/architecture.md

@@ -0,0 +1,36 @@
+# Architecture
+
+## Overview
+
+![http://bit.ly/2iJuFky](images/puma-general-arch.png)
+
+Puma is a threaded web server, processing requests across a TCP or UNIX socket.
+
+Workers accept connections from the socket and a thread in the worker's thread pool processes the client's request.
+
+Clustered mode is shown/discussed here. Single mode is analogous to having a single worker process.
+
+## Connection pipeline
+
+![http://bit.ly/2zwzhEK](images/puma-connection-flow.png)
+
+* Upon startup, Puma listens on a TCP or UNIX socket.
+  * The backlog of this socket is configured (with a default of 1024), determining how many established but unaccepted connections can exist concurrently.
+  * This socket backlog is distinct from the "backlog" of work as reported by the control server stats. The latter is the number of connections in that worker's "todo" set waiting for a worker thread.
+* By default, a single, separate thread is used to receive HTTP requests across the socket.
+  * When at least one worker thread is available for work, a connection is accepted and placed in this request buffer
+  * This thread waits for entire HTTP requests to be received over the connection
+  * Once received, the connection is pushed into the "todo" set
+* Worker threads pop work off the "todo" set for processing
+  * The thread processes the request via the rack application (which generates the HTTP response)
+  * The thread writes the response to the connection
+  * Finally, the thread become available to process another connection in the "todo" set
+
+### Disabling `queue_requests`
+
+![http://bit.ly/2zxCJ1Z](images/puma-connection-flow-no-reactor.png)
+
+The `queue_requests` option is `true` by default, enabling the separate thread used to buffer requests as described above.
+
+If set to `false`, this buffer will not be used for connections while waiting for the request to arrive.
+In this mode, when a connection is accepted, it is added to the "todo" queue immediately, and a worker will syncronously do any waiting necessarry to read the HTTP request from the socket.

data/docs/deployment.md

@@ -0,0 +1,91 @@
+# Deployment engineering for puma
+
+Puma is software that is expected to be run in a deployed environment eventually.
+You can certainly use it as your dev server only, but most people look to use
+it in their production deployments as well.
+
+To that end, this is meant to serve as a foundation of wisdom how to do that
+in a way that increases happiness and decreases downtime.
+
+## Specifying puma
+
+Most people want to do this by putting `gem "puma"` into their Gemfile, so we'll
+go ahead and assume that. Go add it now... we'll wait.
+
+
+Welcome back!
+
+## Single vs Cluster mode
+
+Puma was originally conceived as a thread-only webserver, but grew the ability to
+also use processes in version 2.
+
+Here are some rules of thumb:
+
+### MRI
+
+* Use cluster mode and set the number of workers to 1.5x the number of cpu cores
+  in the machine, minimum 2.
+* Set the number of threads to desired concurrent requests / number of workers.
+  Puma defaults to 16 and that's a decent number.
+
+#### Migrating from Unicorn
+
+* If you're migrating from unicorn though, here are some settings to start with:
+  * Set workers to half the number of unicorn workers you're using
+  * Set threads to 2
+  * Enjoy 50% memory savings
+* As you grow more confident in the thread safety of your app, you can tune the
+  workers down and the threads up.
+
+#### Worker utilization
+
+**How do you know if you're got enough (or too many workers)?**
+
+A good question. Due to MRI's GIL, only one thread can be executing Ruby code at a time.
+But since so many apps are waiting on IO from DBs, etc., they can utilize threads
+to make better use of the process.
+
+The rule of thumb is you never want processes that are pegged all the time. This
+means that there is more work to do that the process can get through. On the other
+hand, if you have processes that sit around doing nothing, then they're just eating
+up resources.
+
+Watching your CPU utilization over time and aim for about 70% on average. This means
+you've got capacity still but aren't starving threads.
+
+## Daemonizing
+
+I prefer to not daemonize my servers and use something like `runit` or `upstart` to
+monitor them as child processes. This gives them fast response to crashes and
+makes it easy to figure out what is going on. Additionally, unlike `unicorn`,
+puma does not require daemonization to do zero-downtime restarts.
+
+I see people using daemonization because they start puma directly via capistrano
+task and thus want it to live on past the `cap deploy`. To this people I said:
+You need to be using a process monitor. Nothing is making sure puma stays up in
+this scenario! You're just waiting for something weird to happen, puma to die,
+and to get paged at 3am. Do yourself a favor, at least the process monitoring
+your OS comes with, be it `sysvinit`, `upstart`, or `systemd`. Or branch out
+and use `runit` or hell, even `monit`.
+
+## Restarting
+
+You probably will want to deploy some new code at some point, and you'd like
+puma to start running that new code. Minimizing the amount of time the server
+is unavailable would be nice as well. Here's how to do it:
+
+1. Don't use `preload!`. This dirties the master process and means it will have
+to shutdown all the workers and re-exec itself to get your new code. It is not compatible with phased-restart and `prune_bundler` as well.
+
+1. Use `prune_bundler`. This makes it so that the cluster master will detach itself
+from a Bundler context on start. This allows the cluster workers to load your app
+and start a brand new Bundler context within the worker only. This means your
+master remains pristine and can live on between new releases of your code.
+
+1. Use phased-restart (`SIGUSR1` or `pumactl phased-restart`). This tells the master
+to kill off one worker at a time and restart them in your new code. This minimizes
+downtime and staggers the restart nicely. **WARNING** This means that both your
+old code and your new code will be running concurrently. Most deployment solutions
+already cause that, but it's worth warning you about it again. Be careful with your
+migrations, etc!

data/ext/puma_http11/mini_ssl.c

@@ -411,6 +411,11 @@ VALUE noop(VALUE self) {
 void Init_mini_ssl(VALUE puma) {
   VALUE mod, eng;
 
+/* Fake operation for documentation (RDoc, YARD) */
+#if 0 == 1
+  puma = rb_define_module("Puma");
+#endif
+
   SSL_library_init();
   OpenSSL_add_ssl_algorithms();
   SSL_load_error_strings();
@@ -447,7 +452,7 @@ VALUE raise_error(VALUE self) {
 }
 
 void Init_mini_ssl(VALUE puma) {
-  VALUE mod, eng;
+  VALUE mod;
 
   mod = rb_define_module_under(puma, "MiniSSL");
   rb_define_class_under(mod, "SSLError", rb_eStandardError);

data/lib/puma/cli.rb

@@ -181,6 +181,10 @@ module Puma
             user_config.tcp_mode!
           end
 
+          o.on "--early-hints", "Enable early hints support" do
+            user_config.early_hints
+          end
+
           o.on "-V", "--version", "Print the version information" do
             puts "puma version #{Puma::Const::VERSION}"
             exit 0

data/lib/puma/cluster.rb

@@ -24,7 +24,7 @@ module Puma
       @workers.each { |x| x.term }
 
       begin
-        Process.waitall
+        @workers.each { |w| Process.waitpid(w.pid) }
       rescue Interrupt
         log "! Cancelled waiting for workers"
       end

data/lib/puma/configuration.rb

@@ -189,22 +189,22 @@ module Puma
     end
 
     def load
+      config_files.each { |config_file| @file_dsl._load_from(config_file) }
+
+      @options
+    end
+
+    def config_files
       files = @options.all_of(:config_files)
 
-      if files.empty?
-        imp = %W(config/puma/#{@options[:environment]}.rb config/puma.rb).find { |f|
-          File.exist?(f)
-        }
+      return [] if files == ['-']
+      return files if files.any?
 
-        files << imp
-      elsif files == ["-"]
-        files = []
+      first_default_file = %W(config/puma/#{environment_str}.rb config/puma.rb).find do |f|
+        File.exist?(f)
       end
 
-      files.each do |f|
-        @file_dsl._load_from(f)
-      end
-      @options
+      [first_default_file]
     end
 
     # Call once all configuration (included from rackup files)
@@ -264,6 +264,10 @@ module Puma
       @options[:environment]
     end
 
+    def environment_str
+      environment.respond_to?(:call) ? environment.call : environment
+    end
+
     def load_plugin(name)
       @plugins.create name
     end

data/lib/puma/const.rb

@@ -54,6 +54,7 @@ module Puma
     416 => 'Range Not Satisfiable',
     417 => 'Expectation Failed',
     418 => 'I\'m A Teapot',
+    421 => 'Misdirected Request',
     422 => 'Unprocessable Entity',
     423 => 'Locked',
     424 => 'Failed Dependency',
@@ -61,6 +62,7 @@ module Puma
     428 => 'Precondition Required',
     429 => 'Too Many Requests',
     431 => 'Request Header Fields Too Large',
+    451 => 'Unavailable For Legal Reasons',
     500 => 'Internal Server Error',
     501 => 'Not Implemented',
     502 => 'Bad Gateway',
@@ -96,8 +98,8 @@ module Puma
   # too taxing on performance.
   module Const
 
-    PUMA_VERSION = VERSION = "3.10.0".freeze
-    CODE_NAME = "Russell's Teapot".freeze
+    PUMA_VERSION = VERSION = "3.11.0".freeze
+    CODE_NAME = "Love Song".freeze
     PUMA_SERVER_STRING = ['puma', PUMA_VERSION, CODE_NAME].join(' ').freeze
 
     FAST_TRACK_KA_TIMEOUT = 0.2
@@ -221,5 +223,7 @@ module Puma
     HIJACK_P = "rack.hijack?".freeze
     HIJACK = "rack.hijack".freeze
     HIJACK_IO = "rack.hijack_io".freeze
+
+    EARLY_HINTS = "rack.early_hints".freeze
   end
 end

data/lib/puma/control_cli.rb

@@ -245,7 +245,7 @@ module Puma
       run_args += ["-S", @state]  if @state
       run_args += ["-q"] if @quiet
       run_args += ["--pidfile", @pidfile] if @pidfile
-      run_args += ["--control", @control_url] if @control_url
+      run_args += ["--control-url", @control_url] if @control_url
       run_args += ["--control-token", @control_auth_token] if @control_auth_token
       run_args += ["-C", @config_file] if @config_file
 

data/lib/puma/dsl.rb

@@ -241,6 +241,10 @@ module Puma
       @options[:mode] = :tcp
     end
 
+    def early_hints(answer=true)
+      @options[:early_hints] = answer
+    end
+
     # Redirect STDOUT and STDERR to files specified.
     def stdout_redirect(stdout=nil, stderr=nil, append=false)
       @options[:redirect_stdout] = stdout

data/lib/puma/launcher.rb

@@ -40,7 +40,7 @@ module Puma
     #       [200, {}, ["hello world"]]
     #     end
     #   end
-    #   Puma::Launcher.new(conf, argv: Puma::Events.stdio).run
+    #   Puma::Launcher.new(conf, events: Puma::Events.stdio).run
     def initialize(conf, launcher_args={})
       @runner        = nil
       @events        = launcher_args[:events] || Events::DEFAULT
@@ -168,7 +168,7 @@ module Puma
           env = Bundler::ORIGINAL_ENV.dup
           # add -rbundler/setup so we load from Gemfile when restarting
           bundle = "-rbundler/setup"
-          env["RUBYOPT"] = [env["RUBYOPT"], bundle].join(" ") unless env["RUBYOPT"].to_s.include?(bundle)
+          env["RUBYOPT"] = [env["RUBYOPT"], bundle].join(" ").lstrip unless env["RUBYOPT"].to_s.include?(bundle)
           env
         else
           ENV.to_h

data/lib/puma/minissl.rb

@@ -1,3 +1,8 @@
+begin
+  require 'io/wait'
+  rescue LoadError
+end
+
 module Puma
   module MiniSSL
     class Socket
@@ -43,7 +48,20 @@ module Puma
           output = engine_read_all
           return output if output
 
-          data = @socket.read_nonblock(size)
+          begin
+            data = @socket.read_nonblock(size, exception: false)
+            if data == :wait_readable || data == :wait_writable
+              if @socket.to_io.respond_to?(data)
+                @socket.to_io.__send__(data)
+              elsif data == :wait_readable
+                IO.select([@socket.to_io])
+              else
+                IO.select(nil, [@socket.to_io])
+              end
+            else
+              break
+            end
+          end while true
 
           @engine.inject(data)
           output = engine_read_all

data/lib/puma/runner.rb

@@ -161,6 +161,10 @@ module Puma
         server.tcp_mode!
       end
 
+      if @options[:early_hints]
+        server.early_hints = true
+      end
+
       unless development?
         server.leak_stack_on_error = false
       end

data/lib/puma/server.rb

@@ -62,6 +62,7 @@ module Puma
 
       @thread = nil
       @thread_pool = nil
+      @early_hints = nil
 
       @persistent_timeout = options.fetch(:persistent_timeout, PERSISTENT_TIMEOUT)
       @first_data_timeout = options.fetch(:first_data_timeout, FIRST_DATA_TIMEOUT)
@@ -81,7 +82,7 @@ module Puma
       @precheck_closing = true
     end
 
-    attr_accessor :binder, :leak_stack_on_error
+    attr_accessor :binder, :leak_stack_on_error, :early_hints
 
     forward :add_tcp_listener,  :@binder
     forward :add_ssl_listener,  :@binder
@@ -595,6 +596,24 @@ module Puma
       env[RACK_INPUT] = body
       env[RACK_URL_SCHEME] =  env[HTTPS_KEY] ? HTTPS : HTTP
 
+      if @early_hints
+        env[EARLY_HINTS] = lambda { |headers|
+          fast_write client, "HTTP/1.1 103 Early Hints\r\n".freeze
+
+          headers.each_pair do |k, vs|
+            if vs.respond_to?(:to_s) && !vs.to_s.empty?
+              vs.to_s.split(NEWLINE).each do |v|
+                fast_write client, "#{k}: #{v}\r\n"
+              end
+            else
+              fast_write client, "#{k}: #{v}\r\n"
+            end
+          end
+
+          fast_write client, "\r\n".freeze
+        }
+      end
+
       # A rack extension. If the app writes #call'ables to this
       # array, we will invoke them when the request is done.
       #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puma
 version: !ruby/object:Gem::Version
-  version: 3.10.0
+  version: 3.11.0
 platform: ruby
 authors:
 - Evan Phoenix
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-17 00:00:00.000000000 Z
+date: 2017-11-20 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
@@ -29,6 +29,11 @@ files:
 - 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
@@ -98,7 +103,8 @@ files:
 homepage: http://puma.io
 licenses:
 - BSD-3-Clause
-metadata: {}
+metadata:
+  msys2_mingw_dependencies: openssl
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -115,7 +121,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: Puma is a simple, fast, threaded, and highly concurrent HTTP 1.1 server for