Initial implementation of puma-plugin-delayed_stop

danschmidt5189 · danschmidt5189 · commit 3cf0ac41acf2 · 2026-03-19T23:33:48.000Z
Puma plugin that delays shutdown after a configurable signal (default
SIGQUIT) to give container orchestrators time to drain traffic before
connections close. Includes RSpec test suite with integration tests that
boot a real Puma server, CI workflow for Ruby 3.0-3.3 x Puma 5-6, and
a GitHub Actions release workflow for publishing to RubyGems.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ["3.0", "3.1", "3.2", "3.3"]
+        puma-version: ["5", "6"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+
+      - name: Override Puma version
+        run: |
+          echo "gem 'puma', '~> ${{ matrix.puma-version }}.0'" >> Gemfile
+          bundle install
+
+      - name: Run tests
+        run: bundle exec rspec
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -0,0 +1,33 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Build gem
+        run: gem build puma-plugin-delayed_stop.gemspec
+
+      - name: Publish to RubyGems
+        uses: rubygems/release-gem@v1
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "${{ github.ref_name }}" *.gem --generate-notes
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,32 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# Gem-specific
+Gemfile.lock
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
diff --git a/.rspec b/.rspec
@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 (Unreleased)
+
+- Initial release
+- Configurable signal via `PUMA_DELAYED_STOP_SIGNAL` (default: `QUIT`)
+- Configurable drain period via `PUMA_DELAYED_STOP_DRAIN_SECONDS` (default: `5`)
diff --git a/Gemfile b/Gemfile
@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+# The MIT License (MIT)
+
+Copyright © 2026 The Regents of the University of California
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -0,0 +1,62 @@
+# puma-plugin-delayed_stop
+
+A [Puma](https://puma.io) plugin that delays shutdown after receiving a signal, giving container orchestrators (Kubernetes, Docker Swarm, ECS, etc.) time to remove the instance from load balancing before connections are closed.
+
+## The problem
+
+When Puma receives `SIGTERM`, it begins shutting down immediately. In orchestrated environments, the termination signal often arrives *before* the orchestrator has finished removing the container from its service mesh or load balancer. Requests routed to the container during this window are dropped.
+
+## The solution
+
+This plugin intercepts a configurable signal (default: `SIGQUIT`) and waits a configurable number of seconds before telling Puma to stop. This gives the orchestrator time to update its routing tables.
+
+A typical Kubernetes setup would configure the pod's `preStop` hook or `terminationGracePeriodSeconds` to send `SIGQUIT`, then later `SIGTERM`:
+
+```yaml
+lifecycle:
+  preStop:
+    exec:
+      command: ["kill", "-QUIT", "1"]
+```
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "puma-plugin-delayed_stop"
+```
+
+Then in your `config/puma.rb`:
+
+```ruby
+plugin :delayed_stop
+```
+
+## Configuration
+
+Configuration is via environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `PUMA_DELAYED_STOP_SIGNAL` | `QUIT` | Signal name (without `SIG` prefix) that triggers the delayed stop |
+| `PUMA_DELAYED_STOP_DRAIN_SECONDS` | `5` | Seconds to wait before telling Puma to stop |
+
+**Warning:** Do not set `PUMA_DELAYED_STOP_SIGNAL` to a signal that Puma already handles (`TERM`, `INT`, `HUP`, `USR1`, `USR2`). Puma registers its own handlers for these signals *after* plugins start, so the plugin's handler will be silently overwritten. The default (`QUIT`) is safe because Puma does not trap it. See [Puma's signal handling documentation](https://github.com/puma/puma/blob/master/docs/signals.md) for the full list of reserved signals.
+
+## How it works
+
+1. On startup, the plugin registers a signal handler for the configured signal.
+2. When the signal is received, the handler sleeps for the configured drain period.
+3. After sleeping, it calls `launcher.stop`, which initiates Puma's normal graceful shutdown.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## License
+
+[MIT](LICENSE)
diff --git a/Rakefile b/Rakefile
@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
diff --git a/lib/puma-plugin-delayed_stop.rb b/lib/puma-plugin-delayed_stop.rb
@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# This file exists so that `require "puma-plugin-delayed_stop"` works, but
+# Puma discovers plugins via lib/puma/plugin/<name>.rb automatically.
+require_relative "puma/plugin/delayed_stop"
diff --git a/lib/puma/plugin/delayed_stop.rb b/lib/puma/plugin/delayed_stop.rb
@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Graceful termination in Swarm/Kubernetes
+#
+# Puma immediately closes its incoming socket upon receipt of SIGTERM.
+# When running in an orchestrator like Kubernetes or Docker Swarm, this
+# can happen before the orchestrator has stopped routing requests to
+# the terminated container, causing dropped requests. This plugin adds
+# a configurable delay so the orchestrator has time to remove the
+# terminated container before Puma exits as usual and stops serving requests.
+
+Puma::Plugin.create do
+  # Signals Puma registers handlers for. It overwrites plugin handlers for these
+  # after plugins start, so using one here would silently break the delayed stop.
+  PUMA_SIGNALS = %w[TERM INT USR1 USR2 HUP].freeze
+
+  # POSIX signal that triggers a delayed stop.
+  # Defaults to QUIT so as not to interfere with Puma's default signal handling.
+  # Accepts both "QUIT" and "SIGQUIT" forms; the SIG prefix is stripped.
+  STOP_SIGNAL = ENV.fetch("PUMA_DELAYED_STOP_SIGNAL", "QUIT").sub(/\ASIG/i, "")
+
+  # Time to wait in seconds before stopping.
+  DRAIN_SECONDS = Integer(ENV.fetch("PUMA_DELAYED_STOP_DRAIN_SECONDS", "5"))
+
+  def start(launcher)
+    if PUMA_SIGNALS.include?(STOP_SIGNAL)
+      raise ArgumentError,
+        "[delayed_stop] PUMA_DELAYED_STOP_SIGNAL=#{STOP_SIGNAL} conflicts with " \
+        "Puma's built-in SIG#{STOP_SIGNAL} handler. Use a signal Puma does not " \
+        "reserve (e.g. QUIT). Puma reserves: #{PUMA_SIGNALS.map { |s| "SIG#{s}" }.join(', ')}"
+    end
+
+    Signal.trap(STOP_SIGNAL) do
+      Thread.new do
+        launcher.log_writer.log("[delayed_stop] Received SIG#{STOP_SIGNAL}, sleeping #{DRAIN_SECONDS}s before stopping")
+        sleep(DRAIN_SECONDS)
+        launcher.stop
+      end
+    end
+  end
+end
diff --git a/lib/puma/plugin/delayed_stop/version.rb b/lib/puma/plugin/delayed_stop/version.rb
@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PumaPluginDelayedStop
+  VERSION = "0.1.0"
+end
diff --git a/puma-plugin-delayed_stop.gemspec b/puma-plugin-delayed_stop.gemspec
@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/puma/plugin/delayed_stop/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "puma-plugin-delayed_stop"
+  spec.version = PumaPluginDelayedStop::VERSION
+  spec.authors = ["Dan Schmidt"]
+  spec.email = ["danschmidt5189@berkeley.edu"]
+  spec.summary = "Puma plugin that delays shutdown for graceful container draining"
+  spec.description = <<~DESC
+    A Puma plugin that intercepts a configurable signal (default: SIGQUIT) and
+    waits a configurable number of seconds before telling Puma to stop. This
+    gives orchestrators like Kubernetes and Docker Swarm time to remove the
+    container from load balancing before connections are closed.
+  DESC
+  spec.homepage = "https://github.com/BerkeleyLibrary/puma-plugin-delayed_stop"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir["lib/**/*.rb", "LICENSE", "README.md", "CHANGELOG.md"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "puma", ">= 5.0", "< 7"
+
+  spec.add_development_dependency "bundler", ">= 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end
diff --git a/spec/fixtures/config.ru b/spec/fixtures/config.ru
@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Minimal Rack app used by integration tests.
+app = lambda do |_env|
+  [200, { "content-type" => "text/plain" }, ["OK"]]
+end
+
+run app
diff --git a/spec/integration/delayed_stop_spec.rb b/spec/integration/delayed_stop_spec.rb
diff --git a/spec/puma/plugin/delayed_stop_spec.rb b/spec/puma/plugin/delayed_stop_spec.rb
diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+--require spec_helper`
	`2`	`+--format documentation`
	`3`	`+--color`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +# frozen_string_literal: true
++
 +source "https://rubygems.org"
++
 +gemspec