puma-plus 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aa68ce5c2a9260719885681158aaef4faa2b8f70187232bb3b78d7d5fb0d7b9a
+  data.tar.gz: 14505256a7bae7411c669edfce2428a319cd2e7f5b4dd8b321e8909cb126dabe
+SHA512:
+  metadata.gz: b012201b85d423d11882ab801193bacc46b7a0a6fc0a69680a6bc4a4ebec4b615fdb9b7d1e13a9a7187f950dba7a95296c99aa62774814cedae084878872349b
+  data.tar.gz: 5439a0c1e43df45dba7525509b54eeefbdf76def6d7e1fa30d765b82658dda6a59201647fe360fa35f4b70229b26d2612d9fb042425b65850cfe50ef599d8384

data/exe/puma-plus

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# The puma-plus command.
+#
+# Reads configuration the way puma does -- a Ruby file, CLI flags overriding it
+# -- and then execs the Go server. See PumaPlus::Launcher for why Ruby parses
+# the config and why this execs rather than supervises.
+
+require "puma_plus/launcher"
+
+exit(PumaPlus::Launcher.new(ARGV).run || 0)

data/exe/puma-plus-worker

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Entry point for a puma-plus Ruby worker process.
+#
+# Normally spawned by the Go server, which passes the worker socket path. Can be
+# run by hand against `puma-plus -spawn=false` for debugging.
+
+require "optparse"
+require "puma_plus/worker"
+require "puma_plus/ractor_worker"
+require "puma_plus/shepherd"
+
+# PUMA_PLUS_CONFIG is set by the `puma-plus` launcher before it execs the Go
+# server, and inherited from there. Lifecycle hooks are blocks, so they cannot
+# arrive as flags -- this process has to read the config file itself.
+options = { threads: 5, worker_id: 0, workers: 0, ractors: 0,
+            config: ENV["PUMA_PLUS_CONFIG"] }
+
+OptionParser.new do |opts|
+  opts.banner = "usage: puma-plus-worker --socket PATH --app PATH [--threads N]"
+
+  opts.on("--socket PATH", "unix socket to dial") { |v| options[:socket] = v }
+  opts.on("--app PATH", "Rack app (config.ru or .rb)") { |v| options[:app] = v }
+  opts.on("--threads N", Integer, "threads to run (default 5)") { |v| options[:threads] = v }
+  opts.on("--ractors N", Integer,
+          "serve from N Ractors instead of N threads (real parallelism; needs a "\
+          "deep-freezable app)") do |v|
+    options[:ractors] = v
+  end
+  opts.on("--config PATH", "config file to read lifecycle hooks from") { |v| options[:config] = v }
+  opts.on("--worker-id N", Integer, "worker index (default 0)") { |v| options[:worker_id] = v }
+  opts.on("--workers N", Integer,
+          "run a shepherd managing N worker processes (0 = single process, no shepherd)") do |v|
+    options[:workers] = v
+  end
+  opts.on("-h", "--help") { puts opts; exit }
+end.parse!
+
+abort "--socket is required" unless options[:socket]
+abort "--app is required" unless options[:app]
+abort "app not found: #{options[:app]}" unless File.exist?(options[:app])
+
+# With --workers 0 this process serves directly, which keeps the Phase 1 debug
+# path working. With --workers N it becomes a shepherd: it preloads the app,
+# forks N children so they inherit a warm heap, and takes scaling commands from
+# the Go server over the control connection.
+if options[:ractors].positive? && options[:workers].positive?
+  abort "--ractors and --workers cannot be combined: the shepherd forks processes "\
+        "that run threads, and Ractor mode is one process. Use one or the other."
+end
+
+if options[:ractors].positive?
+  # Ractors are units of real parallelism, so N ractors in one process is the
+  # in-process analogue of N forked workers -- without the fork dead time.
+  PumaPlus::RactorWorker.new(
+    socket_path: options[:socket],
+    app_path: options[:app],
+    ractors: options[:ractors],
+    worker_id: options[:worker_id],
+    config_path: options[:config]
+  ).run
+elsif options[:workers].positive?
+  PumaPlus::Shepherd.new(
+    socket_path: options[:socket],
+    app_path: options[:app],
+    workers: options[:workers],
+    threads: options[:threads],
+    config_path: options[:config]
+  ).run
+else
+  PumaPlus::Worker.new(
+    socket_path: options[:socket],
+    app_path: options[:app],
+    threads: options[:threads],
+    worker_id: options[:worker_id],
+    config_path: options[:config]
+  ).run
+end

data/ext/puma_plus_gvl/extconf.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+# The whole extension is one API. Without it there is nothing to build, so bail
+# out gracefully rather than emitting a Makefile that produces a useless .so --
+# the Ruby wrapper falls back to the cheaper heuristics.
+unless have_func("rb_internal_thread_add_event_hook", "ruby/thread.h")
+  warn "puma-plus: rb_internal_thread_add_event_hook is unavailable " \
+       "(needs Ruby >= 3.0); GVL instrumentation will be disabled"
+  File.write("Makefile", "install:\n\t@true\nclean:\n\t@true\nall:\n\t@true\n")
+  exit 0
+end
+
+have_func("clock_gettime")
+create_makefile("puma_plus_gvl")

data/ext/puma_plus_gvl/puma_plus_gvl.c

@@ -0,0 +1,160 @@
+/*
+ * GVL wait instrumentation for puma-plus.
+ *
+ * Measures how long each thread spends RUNNABLE BUT UNABLE TO RUN because
+ * another thread in the same process holds the GVL. Ruby exposes no other way
+ * to see this, and without it the scaling controller cannot tell two very
+ * different situations apart:
+ *
+ *   - a thread blocked on a database socket   -> more threads WILL help
+ *   - a thread queued behind the GVL          -> more threads will NOT help,
+ *                                                and may make latency worse
+ *
+ * Both look identical to every cheaper heuristic, because a thread waiting for
+ * the GVL accrues neither CPU time nor IO wait: it is not on CPU, and it is not
+ * blocked on a file descriptor. It is simply queued. That is the blind spot
+ * this closes.
+ *
+ * Implementation constraint: the callback fires BETWEEN GVL states, so it must
+ * not touch the Ruby VM at all -- no allocation, no VALUEs, no calling back into
+ * Ruby. It does exactly two things: read a monotonic clock and add to a counter.
+ */
+
+#include <ruby.h>
+#include <ruby/thread.h>
+#include <stdatomic.h>
+#include <time.h>
+
+/*
+ * Ruby 3.2's rb_internal_thread_event_data_t is `void` -- it carries no thread
+ * identity yet. That is fine, because the callback runs ON the thread the event
+ * concerns, so a thread-local is exactly the right place to stash the timestamp.
+ */
+static _Thread_local uint64_t tl_ready_at = 0;
+static _Thread_local uint64_t tl_wait_ns = 0;
+static _Thread_local uint64_t tl_waits = 0;
+
+/* Process-wide totals, for the per-second heartbeat. */
+static _Atomic uint64_t g_wait_ns = 0;
+static _Atomic uint64_t g_waits = 0;
+
+static rb_internal_thread_event_hook_t *g_hook = NULL;
+
+static inline uint64_t monotonic_ns(void) {
+    struct timespec ts;
+    clock_gettime(CLOCK_MONOTONIC, &ts);
+    return (uint64_t)ts.tv_sec * 1000000000ULL + (uint64_t)ts.tv_nsec;
+}
+
+static void on_thread_event(rb_event_flag_t event,
+                            const rb_internal_thread_event_data_t *data,
+                            void *user_data) {
+    (void)data;
+    (void)user_data;
+
+    switch (event) {
+      case RUBY_INTERNAL_THREAD_EVENT_READY:
+        /* This thread now wants the GVL. Start the clock. */
+        tl_ready_at = monotonic_ns();
+        break;
+
+      case RUBY_INTERNAL_THREAD_EVENT_RESUMED: {
+        /* It got the GVL. The gap is time it was runnable but blocked. */
+        if (tl_ready_at != 0) {
+            uint64_t waited = monotonic_ns() - tl_ready_at;
+            tl_ready_at = 0;
+            tl_wait_ns += waited;
+            tl_waits += 1;
+            atomic_fetch_add_explicit(&g_wait_ns, waited, memory_order_relaxed);
+            atomic_fetch_add_explicit(&g_waits, 1, memory_order_relaxed);
+        }
+        break;
+      }
+
+      case RUBY_INTERNAL_THREAD_EVENT_EXITED:
+        tl_ready_at = 0;
+        break;
+
+      default:
+        break;
+    }
+}
+
+static VALUE gvl_start(VALUE self) {
+    if (g_hook != NULL) return Qfalse;
+
+    g_hook = rb_internal_thread_add_event_hook(
+        on_thread_event,
+        RUBY_INTERNAL_THREAD_EVENT_READY |
+        RUBY_INTERNAL_THREAD_EVENT_RESUMED |
+        RUBY_INTERNAL_THREAD_EVENT_EXITED,
+        NULL);
+    return g_hook != NULL ? Qtrue : Qfalse;
+}
+
+static VALUE gvl_stop(VALUE self) {
+    if (g_hook == NULL) return Qfalse;
+    bool removed = rb_internal_thread_remove_event_hook(g_hook);
+    g_hook = NULL;
+    return removed ? Qtrue : Qfalse;
+}
+
+static VALUE gvl_running_p(VALUE self) {
+    return g_hook != NULL ? Qtrue : Qfalse;
+}
+
+/* Nanoseconds this process has spent waiting for the GVL, all threads. */
+static VALUE gvl_wait_ns(VALUE self) {
+    return ULL2NUM(atomic_load_explicit(&g_wait_ns, memory_order_relaxed));
+}
+
+static VALUE gvl_waits(VALUE self) {
+    return ULL2NUM(atomic_load_explicit(&g_waits, memory_order_relaxed));
+}
+
+/*
+ * Nanoseconds THIS thread has spent waiting for the GVL.
+ *
+ * Read around app.call, the delta is directly comparable to that request's
+ * service time: gvl_wait/service is the fraction of the request spent queued
+ * behind other Ruby threads rather than doing work.
+ */
+static VALUE gvl_thread_wait_ns(VALUE self) {
+    return ULL2NUM(tl_wait_ns);
+}
+
+static VALUE gvl_thread_waits(VALUE self) {
+    return ULL2NUM(tl_waits);
+}
+
+void Init_puma_plus_gvl(void) {
+    /* Callable from a Ractor. Ruby assumes a C extension is Ractor-unsafe until
+     * told otherwise, so without this every method here raises
+     * Ractor::UnsafeError from a Ractor worker -- and RactorWorker reads
+     * thread_wait_ns on the request path.
+     *
+     * The claim is true by construction rather than by inspection: every piece
+     * of state this extension owns is either _Thread_local (tl_ready_at,
+     * tl_wait_ns, tl_waits) or _Atomic (g_wait_ns, g_waits, g_running). It
+     * allocates nothing, touches no VALUE, and calls into no VM function from
+     * the hook -- which it already had to guarantee, since the hook runs on
+     * threads that do not hold the GVL.
+     *
+     * What the numbers MEAN does change under Ractors, though the code does
+     * not. Ractors hold separate locks, so sibling Ractors no longer contend;
+     * a high fraction here now indicates contention between threads within one
+     * Ractor rather than across the process. */
+    rb_ext_ractor_safe(true);
+
+    VALUE mPumaPlus = rb_define_module("PumaPlus");
+    VALUE mGVL = rb_define_module_under(mPumaPlus, "GVL");
+
+    rb_define_singleton_method(mGVL, "native_start!", gvl_start, 0);
+    rb_define_singleton_method(mGVL, "native_stop!", gvl_stop, 0);
+    rb_define_singleton_method(mGVL, "running?", gvl_running_p, 0);
+    rb_define_singleton_method(mGVL, "wait_ns", gvl_wait_ns, 0);
+    rb_define_singleton_method(mGVL, "waits", gvl_waits, 0);
+    rb_define_singleton_method(mGVL, "thread_wait_ns", gvl_thread_wait_ns, 0);
+    rb_define_singleton_method(mGVL, "thread_waits", gvl_thread_waits, 0);
+    rb_define_const(mGVL, "NATIVE", Qtrue);
+}

data/lib/puma_plus/address.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PumaPlus
+  # Address parsing shared by the config DSL and the command line.
+  #
+  # Its own file because both the launcher and the worker need it, and the
+  # worker loads the DSL without the launcher -- it reads the config only for
+  # lifecycle hooks. Having the DSL reach back into Launcher made that
+  # combination raise NameError on any config using activate_control_app, which
+  # no test caught because every launcher test loads the launcher.
+  module Address
+    module_function
+
+    # Normalize whatever someone typed for an address into "host:port".
+    #
+    # Accepts "tcp://127.0.0.1:9293", "127.0.0.1:9293", ":9293" and "9293",
+    # because all four are things people type and three of them are not URLs.
+    # URI.parse alone rejects the bare forms with a message about RFC 3986 that
+    # tells you nothing about what to do instead.
+    def host_port(value, default_port, what)
+      s = value.to_s.strip.sub(%r{\A[a-zA-Z][a-zA-Z0-9+.-]*://}, "")
+      case s
+      when /\A\[([^\]]+)\]:(\d+)\z/ then "[#{Regexp.last_match(1)}]:#{Regexp.last_match(2)}"
+      when /\A(.*):(\d+)\z/
+        host = Regexp.last_match(1)
+        "#{host.empty? ? '0.0.0.0' : host}:#{Regexp.last_match(2)}"
+      when /\A\d+\z/ then "0.0.0.0:#{s}"
+      when "" then raise(ConfigError, "#{what}: expected an address like 127.0.0.1:#{default_port}")
+      else "#{s}:#{default_port}"
+      end
+    end
+  end
+end

data/lib/puma_plus/app_loader.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module PumaPlus
+  # Loading a Rack app from a path.
+  #
+  # Extracted from Worker so the thread-backed and Ractor-backed workers load
+  # apps identically -- if they diverged, a benchmark comparing them would be
+  # comparing app loading as much as concurrency.
+  module AppLoader
+    module_function
+
+    # Load a Rack app from a .ru or a plain .rb.
+    #
+    # The .ru path uses Rack::Builder when the rack gem is available, and falls
+    # back to a minimal builder otherwise. The spike must be runnable before
+    # `gem install rack`, and a Rack app is only an object responding to #call.
+    def load(app_path)
+      source = File.read(app_path)
+
+      if app_path.end_with?(".ru")
+        begin
+          require "rack"
+          return Rack::Builder.new_from_string(source, app_path)
+        rescue LoadError
+          return MiniBuilder.build(source, app_path)
+        end
+      end
+
+      require File.expand_path(app_path)
+      unless defined?(::App) && ::App.respond_to?(:call)
+        raise "#{app_path} must define an App constant responding to #call"
+      end
+
+      ::App
+    end
+
+    # A stand-in for Rack::Builder supporting just `run` and `use`, so an example
+    # config.ru works with no gems installed. Not a Rack::Builder replacement --
+    # real apps should install rack.
+    module MiniBuilder
+      def self.build(source, path)
+        builder = new_builder
+        builder.instance_eval(source, path, 1)
+        builder.to_app
+      end
+
+      def self.new_builder
+        Object.new.tap do |o|
+          o.instance_variable_set(:@run, nil)
+          o.instance_variable_set(:@use, [])
+          def o.run(app) = @run = app
+          def o.use(middleware, *args, &blk) = @use << [middleware, args, blk]
+          def o.map(*) = raise(NotImplementedError, "map requires the rack gem")
+
+          def o.to_app
+            raise "config.ru never called run()" unless @run
+
+            @use.reverse.inject(@run) do |app, (mw, args, blk)|
+              mw.new(app, *args, &blk)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/puma_plus/config_file.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require "puma_plus/address"
+
+module PumaPlus
+  # Three-layer option lookup: command line beats config file beats default.
+  #
+  # Same precedence as puma's UserFileDefaultOptions, and for the same reason --
+  # a config file is checked in and shared, a command line is what you type to
+  # override it right now. Kept as three separate hashes rather than one merged
+  # one so `puma-plus --port 3000` still wins over a `port 9292` in the file no
+  # matter which was read first.
+  class Options
+    def initialize(defaults = {})
+      @default = defaults
+      @file    = {}
+      @user    = {}
+    end
+
+    attr_reader :default, :file, :user
+
+    def [](key)
+      return @user[key] if @user.key?(key)
+      return @file[key] if @file.key?(key)
+
+      @default[key]
+    end
+
+    def key?(key) = @user.key?(key) || @file.key?(key) || @default.key?(key)
+
+    # Where a value came from. Used by `--dry-run` so a surprising setting can be
+    # traced to the line that set it.
+    def origin(key)
+      return :cli if @user.key?(key)
+      return :config if @file.key?(key)
+      return :default if @default.key?(key)
+
+      nil
+    end
+
+    def to_h
+      @default.merge(@file).merge(@user)
+    end
+  end
+
+  # The config-file DSL, evaluated against a plain Ruby file the way puma
+  # evaluates config/puma.rb.
+  #
+  # A Ruby file rather than YAML because the interesting things are not values.
+  # Lifecycle hooks are blocks, worker counts are routinely computed from
+  # `Etc.nprocessors` or an env var, and a config that can branch on
+  # `environment` is the reason anyone tolerates a config file at all.
+  #
+  # Names follow puma wherever the concept exists, so a config can be ported by
+  # deleting the lines that no longer apply rather than rewritten. Where puma has
+  # no equivalent -- autoscaling, Ractors, HTTP/2 and /3 -- the names are ours.
+  class ConfigFile
+    # Options a puma config sets that puma-plus has no equivalent for, mapped to
+    # why. Accepted and ignored with a warning rather than raising: a config
+    # ported from puma should boot, and then tell you what it dropped.
+    IGNORED = {
+      preload_app!: "puma-plus always preloads; the shepherd loads the app once and forks",
+      prune_bundler: "the Go server is not a gem, so there is no bundler to prune",
+      queue_requests: "requests are always queued, in Go -- that is the whole design",
+      wait_for_less_busy_worker: "Go dispatches to an idle worker by construction",
+      fork_worker: "not implemented",
+      nakayoshi_fork: "not implemented",
+      set_remote_address: "Go builds REMOTE_ADDR when it constructs the env"
+    }.freeze
+
+    def initialize(options, path: nil)
+      @options = options
+      @path = path
+      @hooks = Hash.new { |h, k| h[k] = [] }
+      @warnings = []
+    end
+
+    attr_reader :hooks, :warnings
+
+    def self.load(path, options)
+      dsl = new(options, path: path)
+      dsl.instance_eval(File.read(path), path, 1)
+      dsl
+    end
+
+    # --- listeners ------------------------------------------------------
+
+    # bind "tcp://0.0.0.0:9292"
+    # bind "ssl://0.0.0.0:9443"
+    #
+    # Unix sockets are deliberately unsupported for the *client* listener: the
+    # unix socket in this design is how workers dial in, and letting a config
+    # point a public listener at one invites confusing the two.
+    def bind(url)
+      uri = begin
+        URI.parse(url)
+      rescue URI::Error => e
+        raise ConfigError, "bind #{url.inspect}: #{e.message}"
+      end
+      case uri.scheme
+      when "tcp", "http"
+        set :listen, "#{uri.host}:#{uri.port || 9292}"
+      when "ssl", "https"
+        set :listen_tls, "#{uri.host}:#{uri.port || 9443}"
+        apply_ssl_params(URI.decode_www_form(uri.query.to_s).to_h, url)
+      when "unix"
+        raise ConfigError, "bind #{url.inspect}: unix sockets are not supported for " \
+                           "the HTTP listener (the unix socket is how workers dial in)"
+      else
+        raise ConfigError, "bind #{url.inspect}: unknown scheme #{uri.scheme.inspect}"
+      end
+    end
+
+    def port(port, host = nil)
+      set :listen, "#{host || '0.0.0.0'}:#{Integer(port)}"
+    end
+
+    # HTTP/2 cleartext on the main listener. Nothing in puma to mirror.
+    def h2c(enabled = true) = set(:h2c, !!enabled)
+
+    # HTTP/3 needs its own address because QUIC is UDP.
+    def http3(addr) = set(:listen_h3, addr.to_s)
+
+    def tls_hosts(*names) = set(:tls_hosts, names.flatten.join(","))
+
+    # ssl_bind "0.0.0.0", 9443, cert: "...", key: "..."
+    #
+    # puma's signature, so an existing ssl_bind line ports unchanged. The
+    # equivalent query-string form on `bind` works too, since both end up here.
+    def ssl_bind(host, port, opts = {})
+      set :listen_tls, "#{host}:#{Integer(port)}"
+      apply_ssl_params(opts.transform_keys(&:to_s), "ssl_bind")
+    end
+
+    # Certificate and key paths for the TLS and HTTP/3 listeners.
+    def tls_cert(cert, key) = (set(:tls_cert, expand(cert)); set(:tls_key, expand(key)))
+
+    # --- concurrency ----------------------------------------------------
+
+    def workers(count) = set(:workers, Integer(count))
+
+    # threads min, max
+    #
+    # puma-plus has no thread pool to grow and shrink: a thread is a connection
+    # to Go, dialed at boot and held. So only the max is meaningful, and a
+    # config that asks for a range gets told which number was used rather than
+    # silently having one picked.
+    def threads(min, max = min)
+      min = Integer(min)
+      max = Integer(max)
+      raise ConfigError, "threads: min (#{min}) must be <= max (#{max})" if min > max
+
+      if min != max
+        @warnings << "threads #{min},#{max}: puma-plus holds a fixed number of " \
+                     "worker connections, so #{max} is used and #{min} ignored"
+      end
+      set :threads, max
+    end
+
+    # Serve from N Ractors in one process instead of threads across forks.
+    def ractors(count) = set(:ractors, Integer(count))
+
+    def max_connections(n) = set(:max_conns, Integer(n))
+
+    # --- autoscaling ----------------------------------------------------
+
+    # autoscale min: 1, max: 8, target_queue_p95: "25ms"
+    def autoscale(min: nil, max: nil, target_queue_p95: nil, enabled: true)
+      set :autoscale, !!enabled
+      set :min_workers, Integer(min) if min
+      set :max_workers, Integer(max) if max
+      set :target_queue_p95, duration(target_queue_p95, "target_queue_p95") if target_queue_p95
+    end
+
+    def mem_limit(mb) = set(:mem_limit_mb, Integer(mb))
+    def decision_log(path) = set(:decision_log, path.to_s)
+    def acquire_timeout(d) = set(:acquire_timeout, duration(d, "acquire_timeout"))
+
+    # --- app ------------------------------------------------------------
+
+    def rackup(path) = set(:app, path.to_s)
+    def environment(env) = set(:environment, env.to_s)
+    def directory(dir) = set(:directory, File.expand_path(dir.to_s))
+    def tag(name) = set(:tag, name.to_s)
+    def pidfile(path) = set(:pidfile, path.to_s)
+
+    # Where /stats, /metrics and /health are served.
+    def activate_control_app(url = "tcp://127.0.0.1:9293", _opts = {})
+      set :control, Address.host_port(url, 9293, "activate_control_app")
+    end
+
+    def websockets(enabled = true) = set(:websockets, !!enabled)
+    def webtransport(enabled = true) = set(:webtransport, !!enabled)
+    def debug_headers(enabled = true) = set(:debug_headers, !!enabled)
+
+    # --- lifecycle hooks ------------------------------------------------
+    #
+    # Blocks, so they cannot be translated into flags for the Go process. The
+    # worker re-reads this same config file and runs them itself; the launcher
+    # only records that they exist so it can pass the path along.
+
+    def before_fork(&blk) = @hooks[:before_fork] << blk
+    def on_worker_boot(&blk) = @hooks[:on_worker_boot] << blk
+    def on_worker_shutdown(&blk) = @hooks[:on_worker_shutdown] << blk
+
+    # --- accepted and ignored -------------------------------------------
+
+    IGNORED.each do |name, why|
+      define_method(name) do |*_args, &_blk|
+        @warnings << "#{name}: ignored -- #{why}"
+        nil
+      end
+    end
+
+    private
+
+    # Shared by `bind "ssl://..."` and `ssl_bind`, so the two forms cannot drift.
+    #
+    # Only cert and key are honoured. The rest of puma's SSL options configure a
+    # TLS stack this server does not have, and quietly accepting `verify_mode`
+    # would imply client-certificate verification that is not happening.
+    def apply_ssl_params(params, where)
+      cert = params["cert"] || params["cert_pem"]
+      key  = params["key"] || params["key_pem"]
+
+      if cert && key
+        set :tls_cert, expand(cert)
+        set :tls_key, expand(key)
+      elsif cert || key
+        raise ConfigError, "#{where}: cert and key must be given together " \
+                           "(got only #{cert ? 'cert' : 'key'})"
+      end
+
+      ignored = params.keys - %w[cert key cert_pem key_pem]
+      return if ignored.empty?
+
+      @warnings << "#{where}: ignored SSL options #{ignored.join(', ')} -- only " \
+                   "cert and key are supported"
+    end
+
+    def expand(path) = File.expand_path(path.to_s)
+
+    def set(key, value)
+      @options.file[key] = value
+    end
+
+    # Accepts "25ms", "1s", 0.25 (seconds), or an Integer of seconds, and always
+    # emits a Go-parseable duration string.
+    def duration(value, what)
+      case value
+      when Numeric then "#{(value * 1000).round}ms"
+      when String
+        unless value =~ /\A\d+(\.\d+)?(ns|us|ms|s|m|h)\z/
+          raise ConfigError, "#{what}: #{value.inspect} is not a duration like \"25ms\" or \"1s\""
+        end
+
+        value
+      else
+        raise ConfigError, "#{what}: expected a duration, got #{value.class}"
+      end
+    end
+  end
+
+  class ConfigError < StandardError; end
+end
+
+require "uri"