pgbus 0.13.1 → 0.13.3

data/config/locales/sv.yml

@@ -65,7 +65,8 @@ sv:
         empty: Inga köer hittades
         headers:
           depth: Djup
-          oldest: Äldst (s)
+          oldest_claimable: Äldsta tillgänglig (s)
+          parked: Parkerade
           queue: Kö
           total: Totalt
           visible: Synliga
@@ -475,7 +476,8 @@ sv:
           actions: Åtgärder
           depth: Djup
           newest: Nyaste (s)
-          oldest: Äldsta (s)
+          oldest_claimable: Äldsta tillgänglig (s)
+          parked: Parkerade
           queue: Kö
           total_ever: Totalt någonsin
           visible: Synliga
@@ -516,6 +518,9 @@ sv:
           scheduled: 'Schemalagt:'
           timezone: 'Tidszon:'
           visible_at: 'Synlig vid:'
+        oldest: 'Äldsta:'
+        oldest_claimable: 'Äldsta tillgänglig:'
+        parked: 'Parkerade:'
         pause: Pausa
         pause_confirm: Pausa bearbetning?
         purge_confirm: Rensa alla meddelanden?

data/exe/pgbus-health

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Container HEALTHCHECK probe (issue #386). Deliberately loads ONLY the
+# probe file — never the pgbus gem, Bundler, or Rails — because a docker
+# HEALTHCHECK runs this every few seconds.
+require_relative "../lib/pgbus/health_probe"
+
+exit Pgbus::HealthProbe.run(ARGV)

data/lib/generators/pgbus/add_processed_event_completion_generator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+require_relative "migration_path"
+
+module Pgbus
+  module Generators
+    class AddProcessedEventCompletionGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+      include MigrationPath
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Add completed_at to pgbus_processed_events for two-phase idempotency claims " \
+           "(crash mid-handler re-runs instead of silently skipping)"
+
+      class_option :database,
+                   type: :string,
+                   default: nil,
+                   desc: "Use a separate database for pgbus tables (e.g. --database=pgbus)"
+
+      def create_migration_file
+        migration_template "add_processed_event_completion.rb.erb",
+                           File.join(pgbus_migrate_path, "add_pgbus_processed_event_completion.rb")
+      end
+
+      def display_post_install
+        say ""
+        say "Pgbus two-phase idempotency claim migration installed!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
+        say "  2. Restart pgbus: bin/pgbus start"
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+    end
+  end
+end

data/lib/generators/pgbus/templates/add_processed_event_completion.rb.erb

@@ -0,0 +1,19 @@
+class AddPgbusProcessedEventCompletion < ActiveRecord::Migration<%= migration_version %>
+  def up
+    add_column :pgbus_processed_events, :completed_at, :datetime
+
+    # Backfill legacy rows as completed: a row written by the single-phase
+    # code means handle() was at least started — treating it as completed
+    # preserves the old skip behavior instead of retroactively re-running
+    # history on the next delivery of an old event.
+    execute <<~SQL
+      UPDATE pgbus_processed_events
+      SET completed_at = processed_at
+      WHERE completed_at IS NULL
+    SQL
+  end
+
+  def down
+    remove_column :pgbus_processed_events, :completed_at
+  end
+end

data/lib/generators/pgbus/templates/migration.rb.erb

@@ -30,6 +30,9 @@ class CreatePgbusTables < ActiveRecord::Migration<%= migration_version %>
       t.string :event_id, null: false
       t.string :handler_class, null: false
       t.datetime :processed_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+      # Two-phase idempotency claim: NULL = claimed but not finished (a crash
+      # mid-handler re-runs on redelivery); set = completed, dedup applies.
+      t.datetime :completed_at
     end
 
     add_index :pgbus_processed_events, [:event_id, :handler_class],

data/lib/pgbus/cli.rb

@@ -177,14 +177,16 @@ module Pgbus
     def list_queues
       Pgbus.client.list_queues
       metrics = Pgbus.client.metrics
+      claimable_ages = Pgbus.client.oldest_claimable_ages
 
-      puts "QUEUE                                    DEPTH      VISIBLE    OLDEST (s)      TOTAL          "
-      puts "-" * 95
+      puts "QUEUE                                    DEPTH      VISIBLE    OLDEST (s)      CLAIMABLE (s)   TOTAL          "
+      puts "-" * 111
 
       Array(metrics).each do |m|
-        puts format("%-40s %-10s %-10s %-15s %-15s",
+        puts format("%-40s %-10s %-10s %-15s %-15s %-15s",
                     m.queue_name, m.queue_length, m.queue_visible_length,
-                    m.oldest_msg_age_sec || "-", m.total_messages)
+                    m.oldest_msg_age_sec || "-", claimable_ages[m.queue_name] || "-",
+                    m.total_messages)
       end
     end
 

data/lib/pgbus/client.rb

@@ -543,6 +543,38 @@ module Pgbus
       end
     end
 
+    # Age (seconds) of the oldest message actually eligible for pickup, i.e.
+    # whose visibility timeout has elapsed. Unlike pgmq's oldest_msg_age_sec
+    # (computed from enqueued_at), a scheduled or backoff-parked message —
+    # future vt — contributes nothing until it comes due, so a queue holding
+    # only parked messages reads nil ("no claimable backlog") instead of an
+    # age growing at wall-clock rate (issue #389). pgmq's metrics_result type
+    # is frozen upstream, so this lives here rather than in the SQL function.
+    #
+    # With a queue name: the age for that (prefixed) queue, or nil.
+    # Without: a hash of every physical queue in pgmq.meta to its age.
+    #
+    # Routes through the pooled @pgmq.with_connection (health-checked, bounded
+    # by the statement/socket timeouts applied at Client#initialize) rather
+    # than a fresh unbounded PG.connect per call — same rationale as
+    # notify_trigger_current?. synchronized: on the shared-Proc path @pgmq
+    # rides the AR raw connection, so the query must serialize against
+    # concurrent PGMQ operations. One checkout spans all per-queue queries;
+    # nothing nests inside it, so the shared pool_size=1 path is safe.
+    def oldest_claimable_ages(queue_name = nil)
+      synchronized do
+        @pgmq.with_connection do |conn|
+          if queue_name
+            claimable_age_for(conn, config.queue_name(queue_name))
+          else
+            names = conn.exec("SELECT queue_name FROM pgmq.meta ORDER BY queue_name")
+                        .map { |row| row["queue_name"] }
+            names.to_h { |name| [name, claimable_age_for(conn, name)] }
+          end
+        end
+      end
+    end
+
     # Snapshot of the PGMQ connection pool: {size:, available:, pool_timeout:}.
     #
     # Reads pgmq-ruby's own pool counters (@pgmq.stats -> {size:, available:})
@@ -948,6 +980,18 @@ module Pgbus
       end
     end
 
+    # queue_name is a physical (already prefixed) queue name; sanitized to a
+    # bare identifier before interpolation, same as the dashboard's DataSource.
+    def claimable_age_for(conn, queue_name)
+      qtable = "q_#{QueueNameValidator.sanitize!(queue_name)}"
+      row = conn.exec(<<~SQL).first
+        SELECT EXTRACT(epoch FROM (NOW() - min(vt)))::int AS age_sec
+        FROM pgmq.#{qtable}
+        WHERE vt <= NOW()
+      SQL
+      row && row["age_sec"]&.to_i
+    end
+
     def with_raw_connection
       opts = config.connection_options
       owned = false

data/lib/pgbus/configuration.rb

@@ -35,6 +35,16 @@ module Pgbus
     # wait, so recycling/deploy never wedges on a permanently-stuck job.
     attr_accessor :stall_threshold, :read_timeout, :drain_timeout
 
+    # shutdown_timeout bounds how long the supervisor waits for its children
+    # after forwarding TERM before escalating to SIGKILL. nil (default) derives
+    # drain_timeout + SHUTDOWN_TIMEOUT_MARGIN, so raising drain_timeout keeps
+    # the supervisor's deadline above the workers' drain window. An orchestrator
+    # stop grace period (Kamal stop_timeout, Kubernetes terminationGracePeriod)
+    # should exceed this value, or docker SIGKILLs the whole tree first.
+    attr_writer :shutdown_timeout
+
+    SHUTDOWN_TIMEOUT_MARGIN = 5
+
     # Dispatcher settings
     attr_accessor :dispatch_interval
 
@@ -238,6 +248,7 @@ module Pgbus
       @stall_threshold = 90
       @read_timeout = 30
       @drain_timeout = 30
+      @shutdown_timeout = nil
 
       @dispatch_interval = 1.0
 
@@ -712,6 +723,8 @@ module Pgbus
       end
       raise Pgbus::ConfigurationError, "drain_timeout must be > 0" unless drain_timeout.is_a?(Numeric) && drain_timeout.positive?
 
+      validate_shutdown_timeout!
+
       unless stats_flush_size.is_a?(Integer) && stats_flush_size.positive?
         raise Pgbus::ConfigurationError, "stats_flush_size must be a positive integer"
       end
@@ -765,6 +778,30 @@ module Pgbus
       self
     end
 
+    # An explicit shutdown_timeout must be a positive number; nil keeps the
+    # derived drain_timeout + margin default. A value below drain_timeout is
+    # legal but self-defeating (the supervisor SIGKILLs workers mid-drain), so
+    # it warns instead of raising.
+    def validate_shutdown_timeout!
+      explicit = @shutdown_timeout
+      # Finite real only: Float::INFINITY would blow up Supervisor#shutdown's
+      # `Time.now + shutdown_timeout` before any child cleanup ran, and a
+      # Complex would crash `positive?` — reject both here, at boot.
+      valid = explicit.is_a?(Numeric) && explicit.real? && explicit.finite? && explicit.positive?
+      unless explicit.nil? || valid
+        raise Pgbus::ConfigurationError,
+              "shutdown_timeout must be a positive finite number or nil " \
+              "(defaults to drain_timeout + #{SHUTDOWN_TIMEOUT_MARGIN})"
+      end
+
+      return unless explicit && explicit < drain_timeout
+
+      Pgbus.logger.warn do
+        "[Pgbus] shutdown_timeout (#{explicit}s) is below drain_timeout (#{drain_timeout}s) — " \
+          "the supervisor will SIGKILL workers before their drain window ends"
+      end
+    end
+
     # Pre-1.0 surface-freeze: reject malformed values for core job-path keys at
     # boot rather than failing deep in a worker/dispatcher/poller/scheduler
     # thread, per-enqueue, or by silently corrupting queue names / leaving the
@@ -1237,6 +1274,12 @@ module Pgbus
     # because only one runs at a time per reactor thread.
     ASYNC_POOL_CONNECTIONS = 3
 
+    # Resolved supervisor SIGKILL deadline: the explicit value when set,
+    # otherwise drain_timeout + SHUTDOWN_TIMEOUT_MARGIN (see attr_writer docs).
+    def shutdown_timeout
+      @shutdown_timeout || (drain_timeout + SHUTDOWN_TIMEOUT_MARGIN)
+    end
+
     def resolved_pool_size
       return pool_size if pool_size
 

data/lib/pgbus/event_bus/handler.rb

@@ -45,6 +45,7 @@ module Pgbus
         Instrumentation.instrument("pgbus.event_processed", instrument_payload) do
           handle(event)
         end
+        complete_claim!(event.event_id) if self.class.idempotent?
         :handled
       rescue StandardError => e
         instrument(
@@ -100,13 +101,25 @@ module Pgbus
         ActiveSupport::Notifications.instrument(event_name, payload)
       end
 
-      # Atomically claim idempotency: INSERT ... ON CONFLICT DO NOTHING.
-      # Returns true if this handler claimed the event (row was inserted),
-      # false if another handler already processed it (conflict, no insert).
+      # Two-phase idempotency claim (issue #385). Phase 1: atomically claim
+      # via INSERT ... ON CONFLICT DO NOTHING with completed_at NULL — a
+      # *pending* claim. Returns true when this delivery should run handle:
       #
-      # Uses an in-memory dedup cache to skip the DB for recently-seen events.
+      #   - insert won → fresh claim
+      #   - insert lost, completed_at NULL → a prior attempt claimed but was
+      #     killed before finishing (SIGKILL mid-handler); re-run so the crash
+      #     doesn't silently drop the execution. Safe: PGMQ's VT means the
+      #     prior holder is dead or wedged past its timeout — the same
+      #     at-least-once window every non-idempotent handler has.
+      #
+      # Returns false (skip) only for a *completed* execution. Phase 2 is
+      # complete_claim! after handle returns; only completed executions enter
+      # the in-memory dedup cache.
+      #
+      # Legacy fallback: without the completed_at column (upgraded gem,
+      # not-yet-migrated table) this degrades to the old single-phase claim.
       def claim_idempotency?(event_id)
-        cache_key = "#{event_id}:#{self.class.name}"
+        cache_key = dedup_key(event_id)
         return false if self.class.dedup_cache.seen?(cache_key)
 
         result = ProcessedEvent.insert(
@@ -114,9 +127,38 @@ module Pgbus
           unique_by: %i[event_id handler_class]
         )
 
-        claimed = result.rows.any?
+        unless ProcessedEvent.completion_column?
+          self.class.dedup_cache.mark!(cache_key)
+          return result.rows.any?
+        end
+
+        return true if result.rows.any?
+
+        completed_at = ProcessedEvent
+                       .where(event_id: event_id, handler_class: self.class.name)
+                       .pick(:completed_at)
+        return true if completed_at.nil? # pending claim (or purged row) → re-run
+
         self.class.dedup_cache.mark!(cache_key)
-        claimed
+        false
+      end
+
+      # Phase 2: stamp the claim completed and only then admit it to the
+      # dedup cache. Skipped on legacy schemas (single-phase claims are
+      # already cached at claim time). If this write fails, process!'s rescue
+      # re-raises, the consumer leaves the message for VT redelivery, and the
+      # still-pending claim re-runs — at-least-once, never a silent drop.
+      def complete_claim!(event_id)
+        return unless ProcessedEvent.completion_column?
+
+        ProcessedEvent
+          .where(event_id: event_id, handler_class: self.class.name)
+          .update_all(completed_at: Time.now.utc)
+        self.class.dedup_cache.mark!(dedup_key(event_id))
+      end
+
+      def dedup_key(event_id)
+        "#{event_id}:#{self.class.name}"
       end
     end
   end

data/lib/pgbus/generators/migration_detector.rb

@@ -77,6 +77,7 @@ module Pgbus
         add_outbox: "pgbus:add_outbox",
         add_recurring: "pgbus:add_recurring",
         add_failed_events_index: "pgbus:add_failed_events_index",
+        add_processed_event_completion: "pgbus:add_processed_event_completion",
         tune_autovacuum: "pgbus:tune_autovacuum",
         tune_fillfactor: "pgbus:tune_fillfactor"
       }.freeze
@@ -95,6 +96,7 @@ module Pgbus
         add_outbox: "outbox entries table (transactional outbox)",
         add_recurring: "recurring tasks + executions tables",
         add_failed_events_index: "unique index on pgbus_failed_events (queue_name, msg_id)",
+        add_processed_event_completion: "completed_at on pgbus_processed_events (two-phase idempotency claim)",
         tune_autovacuum: "autovacuum tuning for PGMQ queue and archive tables",
         tune_fillfactor: "fillfactor=70 on PGMQ queue tables (reduces page density during update churn)"
       }.freeze
@@ -120,6 +122,7 @@ module Pgbus
           *outbox_migrations,
           *recurring_migrations,
           *failed_events_index_migrations,
+          *processed_event_completion_migrations,
           *autovacuum_migrations,
           *fillfactor_migrations
         ]
@@ -210,6 +213,16 @@ module Pgbus
         [:add_failed_events_index]
       end
 
+      # completed_at backs the two-phase idempotency claim (issue #385).
+      # Without it, idempotent handlers fall back to single-phase claims and
+      # a crash mid-handler silently drops the execution on redelivery.
+      def processed_event_completion_migrations
+        return [] unless table_exists?("pgbus_processed_events")
+        return [] if column_names("pgbus_processed_events").include?("completed_at")
+
+        [:add_processed_event_completion]
+      end
+
       # Autovacuum tuning: check if any PGMQ queue table already has
       # custom autovacuum settings applied. If not, queue the migration.
       def autovacuum_migrations

data/lib/pgbus/health_probe.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Pgbus
+  # Dependency-free readiness probe for container HEALTHCHECKs (issue #386).
+  #
+  # exe/pgbus-health loads this file via require_relative and nothing else:
+  # a docker HEALTHCHECK runs the probe every few seconds, so it must never
+  # drag in Bundler, Zeitwerk, Rails, or the rest of the gem. Only Ruby's
+  # bundled socket library is allowed here.
+  #
+  #   healthcheck:
+  #     cmd: bin/pgbus-health            # port from PGBUS_HEALTH_PORT
+  #     cmd: bin/pgbus-health --port 9394 --path /livez
+  #
+  # Exit codes: 0 healthy (HTTP 2xx), 1 unhealthy (non-2xx, refused, timeout),
+  # 2 usage error (no/invalid port).
+  class HealthProbe
+    EXIT_OK = 0
+    EXIT_UNHEALTHY = 1
+    EXIT_USAGE = 2
+
+    DEFAULT_PATH = "/readyz"
+    DEFAULT_TIMEOUT = 2.0
+    HOST = "127.0.0.1"
+
+    USAGE = "usage: pgbus-health [--port PORT] [--path PATH] [--timeout SECONDS]\n       " \
+            "port falls back to the PGBUS_HEALTH_PORT environment variable\n"
+
+    def self.run(argv, env: ENV, out: $stdout, err: $stderr)
+      new(argv, env: env, out: out, err: err).run
+    end
+
+    def initialize(argv, env: ENV, out: $stdout, err: $stderr)
+      @out = out
+      @err = err
+      @path = DEFAULT_PATH
+      @timeout = DEFAULT_TIMEOUT
+      @port = env["PGBUS_HEALTH_PORT"]
+      @usage_error = false
+      parse(argv)
+    end
+
+    def run
+      return usage_failure if @usage_error
+
+      port = Integer(@port, exception: false)
+      # Out-of-range ports would reach Socket.tcp and raise SocketError — a
+      # backtrace where a HEALTHCHECK needs a deterministic exit code.
+      return usage_failure unless port&.between?(1, 65_535)
+
+      probe(port)
+    end
+
+    private
+
+    # Hand-rolled flag parsing: three flags do not justify optparse in a
+    # script whose reason to exist is loading nothing.
+    def parse(argv)
+      args = argv.dup
+      until args.empty?
+        flag = args.shift
+        value = args.shift
+        return @usage_error = true if value.nil?
+
+        case flag
+        when "--port" then @port = value
+        when "--path" then @path = value
+        when "--timeout"
+          # A typo'd timeout must be a usage error, not `to_f`'s silent 0.0 —
+          # a zero deadline reports the container unhealthy on every probe.
+          timeout = Float(value, exception: false)
+          return @usage_error = true unless timeout&.positive?
+
+          @timeout = timeout
+        else
+          return @usage_error = true
+        end
+      end
+    end
+
+    def usage_failure
+      @err.write(USAGE)
+      EXIT_USAGE
+    end
+
+    def probe(port)
+      status = http_status(port)
+      healthy = status&.between?(200, 299)
+      @out.write("pgbus-health: #{@path} -> #{status || "no response"}\n")
+      healthy ? EXIT_OK : EXIT_UNHEALTHY
+    rescue SystemCallError, IOError, SocketError => e
+      @err.write("pgbus-health: #{@path} -> #{e.class}: #{e.message}\n")
+      EXIT_UNHEALTHY
+    end
+
+    # Minimal HTTP/1.0 exchange: send the request, read just the status line.
+    # The deadline covers connect and read together.
+    def http_status(port)
+      deadline = monotonic_now + @timeout
+      Socket.tcp(HOST, port, connect_timeout: @timeout) do |sock|
+        sock.write("GET #{@path} HTTP/1.0\r\nHost: #{HOST}\r\nConnection: close\r\n\r\n")
+        line = read_status_line(sock, deadline)
+        code = line&.split(" ", 3)&.fetch(1, nil)
+        Integer(code, exception: false)
+      end
+    end
+
+    def read_status_line(sock, deadline)
+      buffer = +""
+      until buffer.include?("\n")
+        remaining = deadline - monotonic_now
+        return nil if remaining <= 0 || !sock.wait_readable(remaining)
+
+        chunk = sock.read_nonblock(1024, exception: false)
+        return nil if chunk.nil? # EOF before a full status line
+        next if chunk == :wait_readable # spurious wakeup — re-wait on the deadline
+
+        buffer << chunk
+      end
+      buffer[/\A[^\r\n]*/]
+    end
+
+    # ::Process, not Process — inside the Pgbus namespace the bare constant
+    # resolves to Pgbus::Process (the process model), which is also why this
+    # file must never be renamed into that namespace.
+    def monotonic_now
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/pgbus/integrations/appsignal/probe.rb

@@ -85,10 +85,14 @@ module Pgbus
               gauge "queue_visible_depth", q[:queue_visible_length], tags
               gauge "queue_paused", q[:paused] ? 1 : 0, tags
               age = q[:oldest_msg_age_sec]
-              if age
-                gauge "queue_oldest_message_age_seconds", age, tags
-                gauge "queue_latency", age * 1_000, tags
-              end
+              gauge "queue_oldest_message_age_seconds", age, tags if age
+              claimable_age = q[:oldest_claimable_age_sec]
+              gauge "queue_oldest_claimable_age_seconds", claimable_age, tags if claimable_age
+              # Latency = time the oldest *claimable* message has waited for
+              # pickup; a queue holding only vt-parked (scheduled/backoff)
+              # messages is healthy, so 0 — not the raw enqueued_at age, which
+              # grows at wall-clock rate on a parked message (issue #389).
+              gauge "queue_latency", (claimable_age || 0) * 1_000, tags
             end
           rescue StandardError => e
             log_failure("queue metrics", e)

data/lib/pgbus/mcp/tools/queues_tool.rb

@@ -14,6 +14,12 @@ module Pgbus
           (messages whose visibility timeout has expired and are ready to be
           claimed), oldest/newest message age in seconds, lifetime total, and
           paused state. Use this to answer "are any queues backed up?".
+          oldest_claimable_age_sec is the age of the oldest message actually
+          eligible for pickup — nil means no message is currently claimable:
+          every remaining message is scheduled, backoff-parked, or in flight
+          with a future visibility timeout. A queue whose oldest_msg_age_sec
+          keeps growing while oldest_claimable_age_sec stays nil has no
+          starving backlog — nothing is waiting for a worker.
         DESC
 
         input_schema(properties: {}, required: [])

data/lib/pgbus/process/consumer.rb

@@ -480,7 +480,10 @@ module Pgbus
       def shutdown
         stop_wake_source
         @pool.shutdown
-        @pool.wait_for_termination(30)
+        # The consumer has no quiesce-gated drain loop like Worker's, so this
+        # wait IS its drain window — bound it by the same knob workers use
+        # instead of a hardcoded 30s (issue #386).
+        @pool.wait_for_termination(config.drain_timeout)
         @stat_buffer&.stop
         @heartbeat&.stop
         restore_signals

data/lib/pgbus/process/readiness_snapshot.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Process
+    # Immutable container-local readiness state, published by the supervisor
+    # (one atomic swap per monitor pass) and read by the standalone health
+    # server's accept thread — the immutability is what makes the cross-thread
+    # handoff safe without a lock (issue #386).
+    #
+    # `expected` is the child count forked by boot_processes; `live` is the
+    # current fork-table size. A child sitting in crash-restart backoff keeps
+    # `live < expected`, which is exactly the signal a rolling deploy's health
+    # gate needs to fail on: the replacement container never goes ready, and
+    # the orchestrator keeps the old container running.
+    ReadinessSnapshot = Data.define(:booted, :shutting_down, :expected, :live) do
+      def ready?
+        booted && !shutting_down && live >= expected
+      end
+
+      # DRAINING wins over BOOTING: a supervisor told to stop mid-boot is
+      # leaving, not arriving, and must never look like it will become ready.
+      def status
+        return "DRAINING" if shutting_down
+        return "BOOTING" unless booted
+
+        ready? ? "OK" : "DEGRADED"
+      end
+    end
+  end
+end