puma 3.12.0 → 4.3.8

data/docs/architecture.md

@@ -20,6 +20,7 @@ Clustered mode is shown/discussed here. Single mode is analogous to having a sin
 * 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
+    * The time spent waiting for the HTTP request body to be received is exposed to the Rack app as `env['puma.request_body_wait']` (milliseconds)
   * 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)

data/docs/deployment.md

@@ -38,22 +38,42 @@ Here are some rules of thumb:
 * As you grow more confident in the thread safety of your app, you can tune the
   workers down and the threads up.
 
+#### Ubuntu / Systemd (Systemctl) Installation
+
+See [systemd.md](systemd.md)
+
 #### Worker utilization
 
-**How do you know if you're got enough (or too many workers)?**
+**How do you know if you've 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
+means that there is more work to do than 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
+Watch your CPU utilization over time and aim for about 70% on average. This means
 you've got capacity still but aren't starving threads.
 
+**Measuring utilization**
+
+Using a timestamp header from an upstream proxy server (eg. nginx or haproxy), it's
+possible to get an indication of how long requests have been waiting for a Puma
+thread to become available.
+
+* Have your upstream proxy set a header with the time it received the request:
+    * nginx: `proxy_set_header X-Request-Start "${msec}";`
+    * haproxy: `http-request set-header X-Request-Start "%t";`
+* In your Rack middleware, determine the amount of time elapsed since `X-Request-Start`.
+* To improve accuracy, you will want to subtract time spent waiting for slow clients:
+    * `env['puma.request_body_wait']` contains the number of milliseconds Puma spent
+      waiting for the client to send the request body.
+    * haproxy: `%Th` (TLS handshake time) and `%Ti` (idle time before request) can
+      can also be added as headers.
+
 ## Daemonizing
 
 I prefer to not daemonize my servers and use something like `runit` or `upstart` to
@@ -62,7 +82,7 @@ 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:
+task and thus want it to live on past the `cap deploy`. To these people I say:
 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

data/docs/plugins.md

@@ -1,15 +1,22 @@
 ## Plugins
 
-Puma 3.0 added support for plugins that can augment configuration and service operations.
+Puma 3.0 added support for plugins that can augment configuration and service
+operations.
 
 2 canonical plugins to look to aid in development of further plugins:
 
-* [tmp\_restart](https://github.com/puma/puma/blob/master/lib/puma/plugin/tmp_restart.rb): Restarts the server if the file `tmp/restart.txt` is touched
-* [heroku](https://github.com/puma/puma-heroku/blob/master/lib/puma/plugin/heroku.rb): Packages up the default configuration used by puma on Heroku
+* [tmp\_restart](https://github.com/puma/puma/blob/master/lib/puma/plugin/tmp_restart.rb):
+  Restarts the server if the file `tmp/restart.txt` is touched
+* [heroku](https://github.com/puma/puma-heroku/blob/master/lib/puma/plugin/heroku.rb):
+  Packages up the default configuration used by puma on Heroku
 
-Plugins are activated in a puma configuration file (such as `config/puma.rb'`) by adding `plugin "name"`, such as `plugin "heroku"`.
+Plugins are activated in a puma configuration file (such as `config/puma.rb'`)
+by adding `plugin "name"`, such as `plugin "heroku"`.
 
-Plugins are activated based simply on path requirements so, activating the `heroku` plugin will simply be doing `require "puma/plugin/heroku"`. This allows gems to provide multiple plugins (as well as unrelated gems to provide puma plugins).
+Plugins are activated based simply on path requirements so, activating the
+`heroku` plugin will simply be doing `require "puma/plugin/heroku"`. This
+allows gems to provide multiple plugins (as well as unrelated gems to provide
+puma plugins).
 
 The `tmp_restart` plugin is bundled with puma, so it can always be used.
 
@@ -17,12 +24,15 @@ To use the `heroku` plugin, add `puma-heroku` to your Gemfile or install it.
 
 ### API
 
-At present, there are 2 hooks that plugins can use: `start` and `config`.
+## Server-wide hooks
 
-`start` runs when the server has started and allows the plugin to start other functionality to augment puma.
+Plugins can use a couple of hooks at server level: `start` and `config`.
 
-`config` runs when the server is being configured and is passed a `Puma::DSL` object that can be used to add additional configuration.
+`start` runs when the server has started and allows the plugin to start other
+functionality to augment puma.
 
-Any public methods in `Puma::Plugin` are the public API that any plugin may use.
+`config` runs when the server is being configured and is passed a `Puma::DSL`
+object that can be used to add additional configuration.
 
-In the future, more hooks and APIs will be added.
+Any public methods in `Puma::Plugin` are the public API that any plugin may
+use.

data/docs/restart.md

@@ -2,8 +2,8 @@
 
 To perform a restart, there are 3 builtin mechanisms:
 
-  * Send the `puma` process the `SIGUSR2` signal
-  * Send the `puma` process the `SIGUSR1` signal (rolling restart, cluster mode only)
+  * Send the `puma` process the `SIGUSR2` signal (normal restart)
+  * Send the `puma` process the `SIGUSR1` signal (restart in phases (a "rolling restart"), cluster mode only)
   * Use the status server and issue `/restart`
 
 No code is shared between the current and restarted process, so it should be safe to issue a restart any place where you would manually stop Puma and start it again.
@@ -22,6 +22,8 @@ But again beware, upgrading an application sometimes involves upgrading the data
 
 If you perform a lot of database migrations, you probably should not use phased restart and use a normal/hot restart instead (`pumactl restart`). That way, no code is shared while deploying (in that case, `preload_app!` might help for quicker deployment, see ["Clustered Mode" in the README](../README.md#clustered-mode)).
 
+**Note**: Hot and phased restarts are only available on MRI, not on JRuby. They are also unavailable on Windows servers.
+
 ### Release Directory
 
 If your symlink releases into a common working directory (i.e., `/current` from Capistrano), Puma won't pick up your new changes when running phased restarts without additional configuration. You should set your working directory within Puma's config to specify the directory it should use. This is a change from earlier versions of Puma (< 2.15) that would infer the directory for you.

data/docs/systemd.md

@@ -32,21 +32,26 @@ Type=simple
 # Preferably configure a non-privileged user
 # User=
 
-# The path to the puma application root
-# Also replace the "<WD>" place holders below with this path.
-WorkingDirectory=
+# The path to the your application code root directory.
+# Also replace the "<YOUR_APP_PATH>" place holders below with this path.
+# Example /home/username/myapp
+WorkingDirectory=<YOUR_APP_PATH>
 
 # Helpful for debugging socket activation, etc.
 # Environment=PUMA_DEBUG=1
 
-# The command to start Puma. This variant uses a binstub generated via
-# `bundle binstubs puma --path ./sbin` in the WorkingDirectory
-# (replace "<WD>" below)
-ExecStart=<WD>/sbin/puma -b tcp://0.0.0.0:9292 -b ssl://0.0.0.0:9293?key=key.pem&cert=cert.pem
+# SystemD will not run puma even if it is in your path. You must specify
+# an absolute URL to puma. For example /usr/local/bin/puma
+# Alternatively, create a binstub with `bundle binstubs puma --path ./sbin` in the WorkingDirectory
+ExecStart=/<FULLPATH>/bin/puma -C <YOUR_APP_PATH>/puma.rb
+
+# Variant: Rails start.
+# ExecStart=/<FULLPATH>/bin/puma -C <YOUR_APP_PATH>/config/puma.rb ../config.ru
 
-# Variant: Use config file with `bind` directives instead:
-# ExecStart=<WD>/sbin/puma -C config.rb
 # Variant: Use `bundle exec --keep-file-descriptors puma` instead of binstub
+# Variant: Specify directives inline.
+# ExecStart=/<FULLPATH>/puma -b tcp://0.0.0.0:9292 -b ssl://0.0.0.0:9293?key=key.pem&cert=cert.pem
+
 
 Restart=always
 
@@ -66,6 +71,13 @@ listening sockets open across puma restarts and achieves graceful
 restarts, including when upgraded puma, and is compatible with both
 clustered mode and application preload.
 
+**Note:** Any wrapper scripts which `exec`, or other indirections in
+`ExecStart`, may result in activated socket file descriptors being closed
+before they reach the puma master process. For example, if using `bundle exec`,
+pass the `--keep-file-descriptors` flag. `bundle exec` can be avoided by using a
+`puma` executable generated by `bundle binstubs puma`. This is tracked in
+[#1499].
+
 **Note:** Socket activation doesn't currently work on jruby. This is
 tracked in [#1367].
 
@@ -247,6 +259,12 @@ PIDFile=<WD>/shared/tmp/pids/puma.pid
 # reconsider if you actually need the forking config.
 Restart=no
 
+# `puma_ctl restart` wouldn't work without this. It's because `pumactl`
+# changes PID on restart and systemd stops the service afterwards
+# because of the PID change. This option prevents stopping after PID
+# change.
+RemainAfterExit=yes
+
 [Install]
 WantedBy=multi-user.target
 ~~~~

data/docs/tcp_mode.md

@@ -0,0 +1,96 @@
+# TCP mode
+
+Puma also could be used as a TCP server to process incoming TCP
+connections.
+
+
+## Configuration
+
+TCP mode can be enabled with CLI option `--tcp-mode`:
+
+```
+$ puma --tcp-mode
+```
+
+Default ip and port to listen to are `0.0.0.0` and `9292`. You can configure
+them with `--port` and `--bind` options:
+
+```
+$ puma --tcp-mode --bind tcp://127.0.0.1:9293
+$ puma --tcp-mode --port 9293
+```
+
+TCP mode could be set with a configuration file as well with `tcp_mode`
+and `tcp_mode!` methods:
+
+```
+# config/puma.rb
+tcp_mode
+```
+
+When Puma starts in the TCP mode it prints the corresponding message:
+
+```
+puma --tcp-mode
+Puma starting in single mode...
+...
+* Mode: Lopez Express (tcp)
+```
+
+
+## How to declare an application
+
+An application to process TCP connections should be declared as a
+callable object which accepts `env` and `socket` arguments.
+
+`env` argument is a Hash with following structure:
+
+```ruby
+{ "thread" => {}, "REMOTE_ADDR" => "127.0.0.1:51133", "log" => "#<Proc:0x000..." }
+```
+
+It consists of:
+* `thread` - a Hash for each thread in the thread pool that could be
+  used to store information between requests
+* `REMOTE_ADDR` - a client ip address
+* `log` - a proc object to write something down
+
+`log` object could be used this way:
+
+```ruby
+env['log'].call('message to log')
+#> 19/Oct/2019 20:28:53 - 127.0.0.1:51266 - message to log
+```
+
+
+## Example of an application
+
+Let's look at an example of a simple application which just echoes
+incoming string:
+
+```ruby
+# config/puma.rb
+app do |env, socket|
+  s = socket.gets
+  socket.puts "Echo #{s}"
+end
+```
+
+We can easily access the TCP server with `telnet` command and receive an
+echo:
+
+```shell
+telnet 0.0.0.0 9293
+Trying 0.0.0.0...
+Connected to 0.0.0.0.
+Escape character is '^]'.
+sssss
+Echo sssss
+^CConnection closed by foreign host.
+```
+
+
+## Socket management
+
+After the application finishes, Puma closes the socket. In order to
+prevent this, the application should set `env['detach'] = true`.

data/ext/puma_http11/PumaHttp11Service.java

@@ -6,11 +6,13 @@ import org.jruby.Ruby;
 import org.jruby.runtime.load.BasicLibraryService;
 
 import org.jruby.puma.Http11;
+import org.jruby.puma.IOBuffer;
 import org.jruby.puma.MiniSSL;
 
 public class PumaHttp11Service implements BasicLibraryService { 
     public boolean basicLoad(final Ruby runtime) throws IOException {
         Http11.createHttp11(runtime);
+        IOBuffer.createIOBuffer(runtime);
         MiniSSL.createMiniSSL(runtime);
         return true;
     }

data/ext/puma_http11/extconf.rb

@@ -1,6 +1,11 @@
 require 'mkmf'
 
 dir_config("puma_http11")
+if $mingw && RUBY_VERSION >= '2.4'
+  append_cflags '-D_FORTIFY_SOURCE=2'
+  append_ldflags '-fstack-protector'
+  have_library 'ssp'
+end
 
 unless ENV["DISABLE_SSL"]
   dir_config("openssl")
@@ -9,6 +14,14 @@ unless ENV["DISABLE_SSL"]
       %w'ssl ssleay32'.find {|ssl| have_library(ssl, 'SSL_CTX_new')}
 
     have_header "openssl/bio.h"
+
+    # below is  yes for 1.0.2 & later
+    have_func  "DTLS_method"                  , "openssl/ssl.h"
+
+    # below are yes for 1.1.0 & later, may need to check func rather than macro
+    # with versions after 1.1.1
+    have_func  "TLS_server_method"            , "openssl/ssl.h"
+    have_macro "SSL_CTX_set_min_proto_version", "openssl/ssl.h"
   end
 end
 

data/ext/puma_http11/http11_parser.c

@@ -14,12 +14,14 @@
 
 /*
  * capitalizes all lower-case ASCII characters,
- * converts dashes to underscores.
+ * converts dashes to underscores, and underscores to commas.
  */
 static void snake_upcase_char(char *c)
 {
     if (*c >= 'a' && *c <= 'z')
       *c &= ~0x20;
+    else if (*c == '_')
+      *c = ',';
     else if (*c == '-')
       *c = '_';
 }
@@ -38,7 +40,7 @@ static void snake_upcase_char(char *c)
 
 #line 40 "ext/puma_http11/http11_parser.c"
 static const int puma_parser_start = 1;
-static const int puma_parser_first_final = 47;
+static const int puma_parser_first_final = 46;
 static const int puma_parser_error = 0;
 
 static const int puma_parser_en_main = 1;
@@ -117,17 +119,17 @@ case 2:
 #line 118 "ext/puma_http11/http11_parser.c"
 	switch( (*p) ) {
 		case 32: goto tr2;
-		case 36: goto st28;
-		case 95: goto st28;
+		case 36: goto st27;
+		case 95: goto st27;
 	}
 	if ( (*p) < 48 ) {
 		if ( 45 <= (*p) && (*p) <= 46 )
-			goto st28;
+			goto st27;
 	} else if ( (*p) > 57 ) {
 		if ( 65 <= (*p) && (*p) <= 90 )
-			goto st28;
+			goto st27;
 	} else
-		goto st28;
+		goto st27;
 	goto st0;
 tr2:
 #line 48 "ext/puma_http11/http11_parser.rl"
@@ -199,7 +201,7 @@ tr37:
     parser->request_uri(parser, PTR_TO(mark), LEN(mark, p));
   }
 	goto st5;
-tr44:
+tr41:
 #line 58 "ext/puma_http11/http11_parser.rl"
 	{ MARK(query_start, p); }
 #line 59 "ext/puma_http11/http11_parser.rl"
@@ -211,7 +213,7 @@ tr44:
     parser->request_uri(parser, PTR_TO(mark), LEN(mark, p));
   }
 	goto st5;
-tr47:
+tr44:
 #line 59 "ext/puma_http11/http11_parser.rl"
 	{
     parser->query_string(parser, PTR_TO(query_start), LEN(query_start, p));
@@ -362,13 +364,13 @@ tr22:
 	{
     parser->body_start = p - buffer + 1;
     parser->header_done(parser, p + 1, pe - p - 1);
-    {p++; cs = 47; goto _out;}
+    {p++; cs = 46; goto _out;}
   }
-	goto st47;
-st47:
+	goto st46;
+st46:
 	if ( ++p == pe )
-		goto _test_eof47;
-case 47:
+		goto _test_eof46;
+case 46:
 #line 373 "ext/puma_http11/http11_parser.c"
 	goto st0;
 tr21:
@@ -458,7 +460,7 @@ tr38:
     parser->request_uri(parser, PTR_TO(mark), LEN(mark, p));
   }
 	goto st20;
-tr45:
+tr42:
 #line 58 "ext/puma_http11/http11_parser.rl"
 	{ MARK(query_start, p); }
 #line 59 "ext/puma_http11/http11_parser.rl"
@@ -470,7 +472,7 @@ tr45:
     parser->request_uri(parser, PTR_TO(mark), LEN(mark, p));
   }
 	goto st20;
-tr48:
+tr45:
 #line 59 "ext/puma_http11/http11_parser.rl"
 	{
     parser->query_string(parser, PTR_TO(query_start), LEN(query_start, p));
@@ -576,10 +578,9 @@ case 24:
 		case 32: goto tr37;
 		case 34: goto st0;
 		case 35: goto tr38;
-		case 59: goto tr39;
 		case 60: goto st0;
 		case 62: goto st0;
-		case 63: goto tr40;
+		case 63: goto tr39;
 		case 127: goto st0;
 	}
 	if ( 0 <= (*p) && (*p) <= 31 )
@@ -595,30 +596,27 @@ st25:
 	if ( ++p == pe )
 		goto _test_eof25;
 case 25:
-#line 599 "ext/puma_http11/http11_parser.c"
+#line 598 "ext/puma_http11/http11_parser.c"
 	switch( (*p) ) {
-		case 32: goto tr8;
+		case 32: goto tr41;
 		case 34: goto st0;
-		case 35: goto tr9;
+		case 35: goto tr42;
 		case 60: goto st0;
 		case 62: goto st0;
-		case 63: goto st26;
 		case 127: goto st0;
 	}
 	if ( 0 <= (*p) && (*p) <= 31 )
 		goto st0;
-	goto st25;
+	goto tr40;
 tr40:
-#line 67 "ext/puma_http11/http11_parser.rl"
-	{
-    parser->request_path(parser, PTR_TO(mark), LEN(mark,p));
-  }
+#line 58 "ext/puma_http11/http11_parser.rl"
+	{ MARK(query_start, p); }
 	goto st26;
 st26:
 	if ( ++p == pe )
 		goto _test_eof26;
 case 26:
-#line 622 "ext/puma_http11/http11_parser.c"
+#line 618 "ext/puma_http11/http11_parser.c"
 	switch( (*p) ) {
 		case 32: goto tr44;
 		case 34: goto st0;
@@ -629,27 +627,25 @@ case 26:
 	}
 	if ( 0 <= (*p) && (*p) <= 31 )
 		goto st0;
-	goto tr43;
-tr43:
-#line 58 "ext/puma_http11/http11_parser.rl"
-	{ MARK(query_start, p); }
-	goto st27;
+	goto st26;
 st27:
 	if ( ++p == pe )
 		goto _test_eof27;
 case 27:
-#line 642 "ext/puma_http11/http11_parser.c"
 	switch( (*p) ) {
-		case 32: goto tr47;
-		case 34: goto st0;
-		case 35: goto tr48;
-		case 60: goto st0;
-		case 62: goto st0;
-		case 127: goto st0;
+		case 32: goto tr2;
+		case 36: goto st28;
+		case 95: goto st28;
 	}
-	if ( 0 <= (*p) && (*p) <= 31 )
-		goto st0;
-	goto st27;
+	if ( (*p) < 48 ) {
+		if ( 45 <= (*p) && (*p) <= 46 )
+			goto st28;
+	} else if ( (*p) > 57 ) {
+		if ( 65 <= (*p) && (*p) <= 90 )
+			goto st28;
+	} else
+		goto st28;
+	goto st0;
 st28:
 	if ( ++p == pe )
 		goto _test_eof28;
@@ -960,24 +956,6 @@ st45:
 	if ( ++p == pe )
 		goto _test_eof45;
 case 45:
-	switch( (*p) ) {
-		case 32: goto tr2;
-		case 36: goto st46;
-		case 95: goto st46;
-	}
-	if ( (*p) < 48 ) {
-		if ( 45 <= (*p) && (*p) <= 46 )
-			goto st46;
-	} else if ( (*p) > 57 ) {
-		if ( 65 <= (*p) && (*p) <= 90 )
-			goto st46;
-	} else
-		goto st46;
-	goto st0;
-st46:
-	if ( ++p == pe )
-		goto _test_eof46;
-case 46:
 	if ( (*p) == 32 )
 		goto tr2;
 	goto st0;
@@ -997,7 +975,7 @@ case 46:
 	_test_eof14: cs = 14; goto _test_eof; 
 	_test_eof15: cs = 15; goto _test_eof; 
 	_test_eof16: cs = 16; goto _test_eof; 
-	_test_eof47: cs = 47; goto _test_eof; 
+	_test_eof46: cs = 46; goto _test_eof; 
 	_test_eof17: cs = 17; goto _test_eof; 
 	_test_eof18: cs = 18; goto _test_eof; 
 	_test_eof19: cs = 19; goto _test_eof; 
@@ -1027,7 +1005,6 @@ case 46:
 	_test_eof43: cs = 43; goto _test_eof; 
 	_test_eof44: cs = 44; goto _test_eof; 
 	_test_eof45: cs = 45; goto _test_eof; 
-	_test_eof46: cs = 46; goto _test_eof; 
 
 	_test_eof: {}
 	_out: {}