puma 7.1.0 → 7.2.0

data/ext/puma_http11/puma_http11.c

@@ -8,25 +8,12 @@
 
 #include "ruby.h"
 #include "ruby/encoding.h"
-#include "ext_help.h"
 #include <assert.h>
 #include <string.h>
 #include <ctype.h>
 #include "http11_parser.h"
 
-#ifndef MANAGED_STRINGS
-
-#ifndef RSTRING_PTR
-#define RSTRING_PTR(s) (RSTRING(s)->ptr)
-#endif
-#ifndef RSTRING_LEN
-#define RSTRING_LEN(s) (RSTRING(s)->len)
-#endif
-
-#define rb_extract_chars(e, sz) (*sz = RSTRING_LEN(e), RSTRING_PTR(e))
-#define rb_free_chars(e) /* nothing */
-
-#endif
+#define ARRAY_SIZE(x) (sizeof(x)/sizeof(x[0]))
 
 static VALUE eHttpParserError;
 
@@ -51,8 +38,8 @@ static VALUE global_request_path;
 /** Defines global strings in the init method. */
 static inline void DEF_GLOBAL(VALUE *var, const char *cstr)
 {
-    rb_global_variable(var);
-    *var = rb_enc_interned_str_cstr(cstr, rb_utf8_encoding());
+  rb_global_variable(var);
+  *var = rb_enc_interned_str_cstr(cstr, rb_utf8_encoding());
 }
 
 /* Defines the maximum allowed lengths for various input elements.*/
@@ -77,10 +64,10 @@ DEF_MAX_LENGTH(QUERY_STRING, PUMA_QUERY_STRING_MAX_LENGTH);
 DEF_MAX_LENGTH(HEADER, (1024 * (80 + 32)));
 
 struct common_field {
-	const size_t len;
-	const char *name;
+  const size_t len;
+  const char *name;
   int raw;
-	VALUE value;
+  VALUE value;
 };
 
 /*
@@ -91,42 +78,42 @@ struct common_field {
 static struct common_field common_http_fields[] = {
 # define f(N) { (sizeof(N) - 1), N, 0, Qnil }
 # define fr(N) { (sizeof(N) - 1), N, 1, Qnil }
-	f("ACCEPT"),
-	f("ACCEPT_CHARSET"),
-	f("ACCEPT_ENCODING"),
-	f("ACCEPT_LANGUAGE"),
-	f("ALLOW"),
-	f("AUTHORIZATION"),
-	f("CACHE_CONTROL"),
-	f("CONNECTION"),
-	f("CONTENT_ENCODING"),
-	fr("CONTENT_LENGTH"),
-	fr("CONTENT_TYPE"),
-	f("COOKIE"),
-	f("DATE"),
-	f("EXPECT"),
-	f("FROM"),
-	f("HOST"),
-	f("IF_MATCH"),
-	f("IF_MODIFIED_SINCE"),
-	f("IF_NONE_MATCH"),
-	f("IF_RANGE"),
-	f("IF_UNMODIFIED_SINCE"),
-	f("KEEP_ALIVE"), /* Firefox sends this */
-	f("MAX_FORWARDS"),
-	f("PRAGMA"),
-	f("PROXY_AUTHORIZATION"),
-	f("RANGE"),
-	f("REFERER"),
-	f("TE"),
-	f("TRAILER"),
-	f("TRANSFER_ENCODING"),
-	f("UPGRADE"),
-	f("USER_AGENT"),
-	f("VIA"),
-	f("X_FORWARDED_FOR"), /* common for proxies */
-	f("X_REAL_IP"), /* common for proxies */
-	f("WARNING")
+  f("ACCEPT"),
+  f("ACCEPT_CHARSET"),
+  f("ACCEPT_ENCODING"),
+  f("ACCEPT_LANGUAGE"),
+  f("ALLOW"),
+  f("AUTHORIZATION"),
+  f("CACHE_CONTROL"),
+  f("CONNECTION"),
+  f("CONTENT_ENCODING"),
+  fr("CONTENT_LENGTH"),
+  fr("CONTENT_TYPE"),
+  f("COOKIE"),
+  f("DATE"),
+  f("EXPECT"),
+  f("FROM"),
+  f("HOST"),
+  f("IF_MATCH"),
+  f("IF_MODIFIED_SINCE"),
+  f("IF_NONE_MATCH"),
+  f("IF_RANGE"),
+  f("IF_UNMODIFIED_SINCE"),
+  f("KEEP_ALIVE"), /* Firefox sends this */
+  f("MAX_FORWARDS"),
+  f("PRAGMA"),
+  f("PROXY_AUTHORIZATION"),
+  f("RANGE"),
+  f("REFERER"),
+  f("TE"),
+  f("TRAILER"),
+  f("TRANSFER_ENCODING"),
+  f("UPGRADE"),
+  f("USER_AGENT"),
+  f("VIA"),
+  f("X_FORWARDED_FOR"), /* common for proxies */
+  f("X_REAL_IP"), /* common for proxies */
+  f("WARNING")
 # undef f
 };
 
@@ -140,10 +127,10 @@ static void init_common_fields(void)
   for(i = 0; i < ARRAY_SIZE(common_http_fields); cf++, i++) {
     rb_global_variable(&cf->value);
     if(cf->raw) {
-      cf->value = rb_str_new(cf->name, cf->len);
+      cf->value = rb_enc_interned_str(cf->name, cf->len, rb_utf8_encoding());
     } else {
       memcpy(tmp + HTTP_PREFIX_LEN, cf->name, cf->len + 1);
-      cf->value = rb_str_new(tmp, HTTP_PREFIX_LEN + cf->len);
+      cf->value = rb_enc_interned_str(tmp, HTTP_PREFIX_LEN + cf->len, rb_utf8_encoding());
     }
   }
 }
@@ -163,7 +150,7 @@ static int is_ows(const char c) {
     return c == ' ' || c == '\t';
 }
 
-void http_field(puma_parser* hp, const char *field, size_t flen,
+static void http_field(puma_parser* hp, const char *field, size_t flen,
                                  const char *value, size_t vlen)
 {
   VALUE f = Qnil;
@@ -186,7 +173,7 @@ void http_field(puma_parser* hp, const char *field, size_t flen,
     memcpy(hp->buf, HTTP_PREFIX, HTTP_PREFIX_LEN);
     memcpy(hp->buf + HTTP_PREFIX_LEN, field, flen);
 
-    f = rb_str_new(hp->buf, new_size);
+    f = rb_enc_interned_str(hp->buf, new_size, rb_utf8_encoding());
   }
 
   while (vlen > 0 && is_ows(value[vlen - 1])) vlen--;
@@ -208,7 +195,7 @@ void http_field(puma_parser* hp, const char *field, size_t flen,
   }
 }
 
-void request_method(puma_parser* hp, const char *at, size_t length)
+static void request_method(puma_parser* hp, const char *at, size_t length)
 {
   VALUE val = Qnil;
 
@@ -216,7 +203,7 @@ void request_method(puma_parser* hp, const char *at, size_t length)
   rb_hash_aset(hp->request, global_request_method, val);
 }
 
-void request_uri(puma_parser* hp, const char *at, size_t length)
+static void request_uri(puma_parser* hp, const char *at, size_t length)
 {
   VALUE val = Qnil;
 
@@ -226,7 +213,7 @@ void request_uri(puma_parser* hp, const char *at, size_t length)
   rb_hash_aset(hp->request, global_request_uri, val);
 }
 
-void fragment(puma_parser* hp, const char *at, size_t length)
+static void fragment(puma_parser* hp, const char *at, size_t length)
 {
   VALUE val = Qnil;
 
@@ -236,7 +223,7 @@ void fragment(puma_parser* hp, const char *at, size_t length)
   rb_hash_aset(hp->request, global_fragment, val);
 }
 
-void request_path(puma_parser* hp, const char *at, size_t length)
+static void request_path(puma_parser* hp, const char *at, size_t length)
 {
   VALUE val = Qnil;
 
@@ -246,7 +233,7 @@ void request_path(puma_parser* hp, const char *at, size_t length)
   rb_hash_aset(hp->request, global_request_path, val);
 }
 
-void query_string(puma_parser* hp, const char *at, size_t length)
+static void query_string(puma_parser* hp, const char *at, size_t length)
 {
   VALUE val = Qnil;
 
@@ -256,7 +243,7 @@ void query_string(puma_parser* hp, const char *at, size_t length)
   rb_hash_aset(hp->request, global_query_string, val);
 }
 
-void server_protocol(puma_parser* hp, const char *at, size_t length)
+static void server_protocol(puma_parser* hp, const char *at, size_t length)
 {
   VALUE val = rb_str_new(at, length);
   rb_hash_aset(hp->request, global_server_protocol, val);
@@ -265,36 +252,42 @@ void server_protocol(puma_parser* hp, const char *at, size_t length)
 /** Finalizes the request header to have a bunch of stuff that's
   needed. */
 
-void header_done(puma_parser* hp, const char *at, size_t length)
+static void header_done(puma_parser* hp, const char *at, size_t length)
 {
   hp->body = rb_str_new(at, length);
 }
 
 
-void HttpParser_free(void *data) {
-  TRACE();
+static void HttpParser_mark(void *ptr) {
+  puma_parser *hp = ptr;
+  rb_gc_mark_movable(hp->request);
+  rb_gc_mark_movable(hp->body);
+}
 
-  if(data) {
-    xfree(data);
-  }
+static size_t HttpParser_size(const void *ptr) {
+  return sizeof(puma_parser);
 }
 
-void HttpParser_mark(void *ptr) {
+static void HttpParser_compact(void *ptr) {
   puma_parser *hp = ptr;
-  if(hp->request) rb_gc_mark(hp->request);
-  if(hp->body) rb_gc_mark(hp->body);
+  hp->request = rb_gc_location(hp->request);
+  hp->body = rb_gc_location(hp->body);
 }
 
-const rb_data_type_t HttpParser_data_type = {
-    "HttpParser",
-    { HttpParser_mark, HttpParser_free, 0 },
-    0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+static const rb_data_type_t HttpParser_data_type = {
+    .wrap_struct_name = "Puma::HttpParser",
+    .function = {
+      .dmark = HttpParser_mark,
+      .dfree = RUBY_TYPED_DEFAULT_FREE,
+      .dsize = HttpParser_size,
+      .dcompact = HttpParser_compact,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
 };
 
-VALUE HttpParser_alloc(VALUE klass)
+static VALUE HttpParser_alloc(VALUE klass)
 {
   puma_parser *hp = ALLOC_N(puma_parser, 1);
-  TRACE();
   hp->http_field = http_field;
   hp->request_method = request_method;
   hp->request_uri = request_uri;
@@ -310,16 +303,25 @@ VALUE HttpParser_alloc(VALUE klass)
   return TypedData_Wrap_Struct(klass, &HttpParser_data_type, hp);
 }
 
+static inline puma_parser *HttpParser_unwrap(VALUE self)
+{
+  puma_parser *http;
+  TypedData_Get_Struct(self, puma_parser, &HttpParser_data_type, http);
+  if (http == NULL) {
+    rb_raise(rb_eArgError, "%s", "NULL http_parser found");
+  }
+  return http;
+}
+
 /**
  * call-seq:
  *    parser.new -> parser
  *
  * Creates a new parser.
  */
-VALUE HttpParser_init(VALUE self)
+static VALUE HttpParser_init(VALUE self)
 {
-  puma_parser *http = NULL;
-  DATA_GET(self, puma_parser, &HttpParser_data_type, http);
+  puma_parser *http = HttpParser_unwrap(self);
   puma_parser_init(http);
 
   return self;
@@ -333,10 +335,9 @@ VALUE HttpParser_init(VALUE self)
  * Resets the parser to it's initial state so that you can reuse it
  * rather than making new ones.
  */
-VALUE HttpParser_reset(VALUE self)
+static VALUE HttpParser_reset(VALUE self)
 {
-  puma_parser *http = NULL;
-  DATA_GET(self, puma_parser, &HttpParser_data_type, http);
+  puma_parser *http = HttpParser_unwrap(self);
   puma_parser_init(http);
 
   return Qnil;
@@ -350,10 +351,9 @@ VALUE HttpParser_reset(VALUE self)
  * Finishes a parser early which could put in a "good" or bad state.
  * You should call reset after finish it or bad things will happen.
  */
-VALUE HttpParser_finish(VALUE self)
+static VALUE HttpParser_finish(VALUE self)
 {
-  puma_parser *http = NULL;
-  DATA_GET(self, puma_parser, &HttpParser_data_type, http);
+  puma_parser *http = HttpParser_unwrap(self);
   puma_parser_finish(http);
 
   return puma_parser_is_finished(http) ? Qtrue : Qfalse;
@@ -377,26 +377,22 @@ VALUE HttpParser_finish(VALUE self)
  * the parsing from that position.  It needs all of the original data as well
  * so you have to append to the data buffer as you read.
  */
-VALUE HttpParser_execute(VALUE self, VALUE req_hash, VALUE data, VALUE start)
+static VALUE HttpParser_execute(VALUE self, VALUE req_hash, VALUE data, VALUE start)
 {
-  puma_parser *http = NULL;
+  puma_parser *http = HttpParser_unwrap(self);
   int from = 0;
   char *dptr = NULL;
   long dlen = 0;
 
-  DATA_GET(self, puma_parser, &HttpParser_data_type, http);
-
   from = FIX2INT(start);
-  dptr = rb_extract_chars(data, &dlen);
+  RSTRING_GETMEM(data, dptr, dlen);
 
   if(from >= dlen) {
-    rb_free_chars(dptr);
     rb_raise(eHttpParserError, "%s", "Requested start is after data buffer end.");
   } else {
     http->request = req_hash;
     puma_parser_execute(http, dptr, dlen, from);
 
-    rb_free_chars(dptr);
     VALIDATE_MAX_LENGTH(puma_parser_nread(http), HEADER);
 
     if(puma_parser_has_error(http)) {
@@ -415,10 +411,9 @@ VALUE HttpParser_execute(VALUE self, VALUE req_hash, VALUE data, VALUE start)
  *
  * Tells you whether the parser is in an error state.
  */
-VALUE HttpParser_has_error(VALUE self)
+static VALUE HttpParser_has_error(VALUE self)
 {
-  puma_parser *http = NULL;
-  DATA_GET(self, puma_parser, &HttpParser_data_type, http);
+  puma_parser *http = HttpParser_unwrap(self);
 
   return puma_parser_has_error(http) ? Qtrue : Qfalse;
 }
@@ -430,10 +425,9 @@ VALUE HttpParser_has_error(VALUE self)
  *
  * Tells you whether the parser is finished or not and in a good state.
  */
-VALUE HttpParser_is_finished(VALUE self)
+static VALUE HttpParser_is_finished(VALUE self)
 {
-  puma_parser *http = NULL;
-  DATA_GET(self, puma_parser, &HttpParser_data_type, http);
+  puma_parser *http = HttpParser_unwrap(self);
 
   return puma_parser_is_finished(http) ? Qtrue : Qfalse;
 }
@@ -446,10 +440,9 @@ VALUE HttpParser_is_finished(VALUE self)
  * Returns the amount of data processed so far during this processing cycle.  It is
  * set to 0 on initialize or reset calls and is incremented each time execute is called.
  */
-VALUE HttpParser_nread(VALUE self)
+static VALUE HttpParser_nread(VALUE self)
 {
-  puma_parser *http = NULL;
-  DATA_GET(self, puma_parser, &HttpParser_data_type, http);
+  puma_parser *http = HttpParser_unwrap(self);
 
   return INT2FIX(http->nread);
 }
@@ -460,9 +453,8 @@ VALUE HttpParser_nread(VALUE self)
  *
  * If the request included a body, returns it.
  */
-VALUE HttpParser_body(VALUE self) {
-  puma_parser *http = NULL;
-  DATA_GET(self, puma_parser, &HttpParser_data_type, http);
+static VALUE HttpParser_body(VALUE self) {
+  puma_parser *http = HttpParser_unwrap(self);
 
   return http->body;
 }
@@ -471,7 +463,7 @@ VALUE HttpParser_body(VALUE self) {
 void Init_mini_ssl(VALUE mod);
 #endif
 
-void Init_puma_http11(void)
+RUBY_FUNC_EXPORTED void Init_puma_http11(void)
 {
 #ifdef HAVE_RB_EXT_RACTOR_SAFE
   rb_ext_ractor_safe(true);

data/lib/puma/app/status.rb

@@ -7,13 +7,16 @@ module Puma
     # can respond to.
     class Status
       OK_STATUS = '{ "status": "ok" }'.freeze
+      READ_ONLY_COMMANDS = %w[gc-stats stats].freeze
 
       # @param launcher [::Puma::Launcher]
       # @param token [String, nil] the token used for authentication
+      # @param data_only [Boolean] if true, restrict to read-only data commands
       #
-      def initialize(launcher, token = nil)
+      def initialize(launcher, token: nil, data_only: false)
         @launcher = launcher
         @auth_token = token
+        @enabled_commands = READ_ONLY_COMMANDS if data_only
       end
 
       # most commands call methods in `::Puma::Launcher` based on command in
@@ -25,8 +28,13 @@ module Puma
 
         # resp_type is processed by following case statement, return
         # is a number (status) or a string used as the body of a 200 response
+        command = env['PATH_INFO'][/\/([^\/]+)$/, 1]
+        if @enabled_commands && !@enabled_commands.include?(command)
+          return rack_response(404, "Command #{command.inspect} unavailable", 'text/plain')
+        end
+
         resp_type =
-          case env['PATH_INFO'][/\/([^\/]+)$/, 1]
+          case command
           when 'stop'
             @launcher.stop ; 200
 

data/lib/puma/cluster/worker.rb

@@ -14,7 +14,7 @@ module Puma
     class Worker < Puma::Runner # :nodoc:
       attr_reader :index, :master
 
-      def initialize(index:, master:, launcher:, pipes:, server: nil)
+      def initialize(index:, master:, launcher:, pipes:, app: nil)
         super(launcher)
 
         @index = index
@@ -23,7 +23,8 @@ module Puma
         @worker_write = pipes[:worker_write]
         @fork_pipe = pipes[:fork_pipe]
         @wakeup = pipes[:wakeup]
-        @server = server
+        @app = app
+        @server = nil
         @hook_data = {}
       end
 
@@ -57,7 +58,7 @@ module Puma
         @config.run_hooks(:before_worker_boot, index, @log_writer, @hook_data)
 
         begin
-        server = @server ||= start_server
+          @server = start_server
         rescue Exception => e
           log "! Unable to start worker"
           log e
@@ -85,7 +86,7 @@ module Puma
               if idx == -1 # stop server
                 if restart_server.length > 0
                   restart_server.clear
-                  server.begin_restart(true)
+                  @server.begin_restart(true)
                   @config.run_hooks(:before_refork, nil, @log_writer, @hook_data)
                 end
               elsif idx == -2 # refork cycle is done
@@ -103,7 +104,7 @@ module Puma
         Signal.trap "SIGTERM" do
           @worker_write << "#{PIPE_EXTERNAL_TERM}#{Process.pid}\n" rescue nil
           restart_server.clear
-          server.stop
+          @server.stop
           restart_server << false
         end
 
@@ -115,7 +116,7 @@ module Puma
         end
 
         while restart_server.pop
-          server_thread = server.run
+          server_thread = @server.run
 
           if @log_writer.debug? && index == 0
             debug_loaded_extensions "Loaded Extensions - worker 0:"
@@ -129,13 +130,13 @@ module Puma
               begin
                 payload = base_payload.dup
 
-                hsh = server.stats
+                hsh = @server.stats
                 hsh.each do |k, v|
                   payload << %Q! "#{k}":#{v || 0},!
                 end
                 # sub call properly adds 'closing' string
                 io << payload.sub(/,\z/, " }\n")
-                server.reset_max
+                @server.reset_max
               rescue IOError
                 break
               end
@@ -164,7 +165,7 @@ module Puma
                                   launcher: @launcher,
                                   pipes: { check_pipe: @check_pipe,
                                            worker_write: @worker_write },
-                                  server: @server
+                                  app: @app
           new_worker.run
         end
 

data/lib/puma/cluster.rb

@@ -186,7 +186,7 @@ module Puma
         # we need to phase any workers out (which will restart
         # in the right phase).
         #
-        w = @workers.find { |x| x.phase != @phase }
+        w = @workers.find { |x| x.phase < @phase }
 
         if w
           if refork
@@ -221,12 +221,11 @@ module Puma
         pipes[:wakeup] = @wakeup
       end
 
-      server = start_server if preload?
       new_worker = Worker.new index: index,
                               master: master,
                               launcher: @launcher,
                               pipes: pipes,
-                              server: server
+                              app: (app if preload?)
       new_worker.run
     end
 

data/lib/puma/configuration.rb

@@ -197,7 +197,7 @@ module Puma
       @clamped = false
     end
 
-    attr_reader :plugins, :events, :hooks
+    attr_reader :plugins, :events, :hooks, :_options
 
     def options
       raise NotClampedError, "ensure clamp is called before accessing options" unless @clamped
@@ -238,18 +238,14 @@ module Puma
       min = env['PUMA_MIN_THREADS'] || env['MIN_THREADS']
       max = env['PUMA_MAX_THREADS'] || env['MAX_THREADS']
       persistent_timeout = env['PUMA_PERSISTENT_TIMEOUT']
-      workers = if env['WEB_CONCURRENCY'] == 'auto'
-        require_processor_counter
-        ::Concurrent.available_processor_count
-      else
-        env['WEB_CONCURRENCY']
-      end
+      workers_env = env['WEB_CONCURRENCY']
+      workers = workers_env && workers_env.strip != "" ? parse_workers(workers_env.strip) : nil
 
       {
         min_threads: min && min != "" && Integer(min),
         max_threads: max && max != "" && Integer(max),
         persistent_timeout: persistent_timeout && persistent_timeout != "" && Integer(persistent_timeout),
-        workers: workers && workers != "" && Integer(workers),
+        workers: workers,
         environment: env['APP_ENV'] || env['RACK_ENV'] || env['RAILS_ENV'],
       }
     end
@@ -380,12 +376,23 @@ module Puma
       require 'concurrent/utility/processor_counter'
     rescue LoadError
       warn <<~MESSAGE
-        WEB_CONCURRENCY=auto requires the "concurrent-ruby" gem to be installed.
+        WEB_CONCURRENCY=auto or workers(:auto) requires the "concurrent-ruby" gem to be installed.
         Please add "concurrent-ruby" to your Gemfile.
       MESSAGE
       raise
     end
 
+    def parse_workers(value)
+      if value == :auto || value == 'auto'
+        require_processor_counter
+        Integer(::Concurrent.available_processor_count)
+      else
+        Integer(value)
+      end
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "workers must be an Integer or :auto"
+    end
+
     # Load and use the normal Rack builder if we can, otherwise
     # fallback to our minimal version.
     def rack_builder

data/lib/puma/const.rb

@@ -100,8 +100,8 @@ module Puma
   # too taxing on performance.
   module Const
 
-    PUMA_VERSION = VERSION = "7.1.0"
-    CODE_NAME = "Neon Witch"
+    PUMA_VERSION = VERSION = "7.2.0"
+    CODE_NAME = "On The Corner"
 
     PUMA_SERVER_STRING = ["puma", PUMA_VERSION, CODE_NAME].join(" ").freeze
 

data/lib/puma/dsl.rb

@@ -216,6 +216,8 @@ module Puma
     #   activate_control_app 'unix:///var/run/pumactl.sock', { auth_token: '12345' }
     # @example
     #   activate_control_app 'unix:///var/run/pumactl.sock', { no_token: true }
+    # @example
+    #   activate_control_app 'unix:///var/run/pumactl.sock', { no_token: true, data_only: true}
     #
     def activate_control_app(url="auto", opts={})
       if url == "auto"
@@ -240,6 +242,7 @@ module Puma
 
       @options[:control_auth_token] = auth_token
       @options[:control_url_umask] = opts[:umask] if opts[:umask]
+      @options[:control_data_only] = opts[:data_only] if opts[:data_only]
     end
 
     # Load additional configuration from a file.
@@ -666,21 +669,27 @@ module Puma
       @options[:state_permission] = permission
     end
 
-    # How many worker processes to run.  Typically this is set to
-    # the number of available cores.
+    # How many worker processes to run. Typically this is set to the number of
+    # available cores.
     #
     # The default is the value of the environment variable +WEB_CONCURRENCY+ if
-    # set, otherwise 0.
+    # set, otherwise 0. Passing +:auto+ will set the value to
+    # +Concurrent.available_processor_count+ (requires the concurrent-ruby gem).
+    # On some platforms (e.g. under CPU quotas) this may be fractional, and Puma
+    # will round down. If it rounds down to 0, Puma will run in single mode and
+    # cluster-only hooks like +before_worker_boot+ will not execute.
+    # If you rely on cluster-only hooks, set an explicit worker count.
     #
-    # @note Cluster mode only.
+    # A value of 0 or nil means run in single mode.
     #
     # @example
     #   workers 2
+    #   workers :auto
     #
     # @see Puma::Cluster
     #
     def workers(count)
-      @options[:workers] = count.to_i
+      @options[:workers] = count.nil? ? 0 : @config.send(:parse_workers, count)
     end
 
     # Disable warning message when running in cluster mode with a single worker.
@@ -995,6 +1004,7 @@ module Puma
     # The default is +true+ if your app uses more than 1 worker.
     #
     # @note Cluster mode only.
+    # @note When using `fork_worker`, this only applies to worker 0.
     #
     # @example
     #   preload_app!
@@ -1378,7 +1388,7 @@ module Puma
     #
     # The default is +:auto+.
     #
-    # @see https://github.com/socketry/nio4r/blob/master/lib/nio/selector.rb
+    # @see https://github.com/socketry/nio4r/blob/main/lib/nio/selector.rb
     #
     def io_selector_backend(backend)
       @options[:io_selector_backend] = backend.to_sym