puma-plugin-delayed_stop 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 960c22d0477d4a3fc18be9e9cf3e0a1ba32ee622aabee83cf810abaec8746e6a
+  data.tar.gz: 2f2e4b5884ecc1854e8ddd473f569cf9bd4a0e0b3d6e1ea421dfe5f8e8f6bcb5
+SHA512:
+  metadata.gz: da26be51c235e68f1595f85bb6fca5ef42f71a01fcabe9e9fff44c620d4d9e3e380f027367d593a0a781fc50a7700c4b20f5dbc2a2de2b8b228163cd8f13fe80
+  data.tar.gz: 59b545e4b85684c5c69df706870c74d7c688dfd161750007db407bbf2eb6c96438804889d1ea05d0ff7331cb5706f47814c047248476b7a1be377133c8ae6f94

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 (2026/03/19)
+
+- Initial release
+- Supports Puma 5, 6, and 7
+- Configurable signal via `PUMA_DELAYED_STOP_SIGNAL` (default: `QUIT`)
+- Configurable drain period via `PUMA_DELAYED_STOP_DRAIN_SECONDS` (default: `5`)
+- Validates that the configured signal does not conflict with Puma's built-in signal handlers

data/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.

data/README.md

@@ -0,0 +1,76 @@
+# 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 to send `SIGQUIT` before the kubelet sends `SIGTERM`:
+
+```yaml
+lifecycle:
+  preStop:
+    exec:
+      command: ["kill", "-QUIT", "1"]
+```
+
+In Docker Swarm, configure `stop_signal` to send `SIGQUIT` first and set `stop_grace_period` long enough to cover both the drain and Puma's graceful shutdown:
+
+```yaml
+services:
+  web:
+    image: myapp:latest
+    stop_signal: SIGQUIT
+    stop_grace_period: 30s
+    environment:
+      PUMA_DELAYED_STOP_DRAIN_SECONDS: "5"
+```
+
+Swarm sends `stop_signal` when removing a task, then waits up to `stop_grace_period` before sending `SIGKILL`. The plugin sleeps through the drain period while Swarm updates its routing mesh, then tells Puma to shut down gracefully with the remaining time.
+
+## 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)

data/lib/puma/plugin/delayed_stop/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PumaPluginDelayedStop
+  VERSION = "0.1.0"
+end

data/lib/puma/plugin/delayed_stop.rb

@@ -0,0 +1,45 @@
+# 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.
+  # INFO (BSD/macOS) and PWR (Linux) were added in Puma 7.
+  PUMA_SIGNALS = %w[TERM INT USR1 USR2 HUP INFO PWR].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
+
+    # Puma 6 renamed `events` to `log_writer` for logging.
+    logger = launcher.respond_to?(:log_writer) ? launcher.log_writer : launcher.events
+
+    Signal.trap(STOP_SIGNAL) do
+      Thread.new do
+        logger.log("[delayed_stop] Received SIG#{STOP_SIGNAL}, sleeping #{DRAIN_SECONDS}s before stopping")
+        sleep(DRAIN_SECONDS)
+        launcher.stop
+      end
+    end
+  end
+end

data/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"

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: puma-plugin-delayed_stop
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dan Schmidt
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: |
+  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.
+email:
+- danschmidt5189@berkeley.edu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/puma-plugin-delayed_stop.rb
+- lib/puma/plugin/delayed_stop.rb
+- lib/puma/plugin/delayed_stop/version.rb
+homepage: https://github.com/BerkeleyLibrary/puma-plugin-delayed_stop
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/BerkeleyLibrary/puma-plugin-delayed_stop
+  source_code_uri: https://github.com/BerkeleyLibrary/puma-plugin-delayed_stop
+  changelog_uri: https://github.com/BerkeleyLibrary/puma-plugin-delayed_stop/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Puma plugin that delays shutdown for graceful container draining
+test_files: []