otp-rails 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23149af487fee17bd68538aa5af0d5d0fa4bafc4d652be8ebc75b36038a36b56
-  data.tar.gz: a9569a4de603358e2b13b3e3a5f4e9b816436eefc7b5256d3553a58aa0d7ee25
+  metadata.gz: 3d868a6f4f17b7af27c7af0cf1cceba00e124067d669861b963aaebcfb8ef25b
+  data.tar.gz: c2306307b5a08c6e2938f75eae9ec903453de9459b6f0922468ed155e57a597c
 SHA512:
-  metadata.gz: feb5ffee5725414004061ec389d68cd78da9c0dafe9173da72a5bc7ba341adfa52667a59d279323a161bb49d17243c8d746ef124f6f46fb9497332dd603d0bf7
-  data.tar.gz: 37d797974e06728dbb760b6e5685bfdb77681fc04237ae789363e26181d4fdc1ae854febbf0f411686edd82fa0498dd5c7cb6f821492f16aea573d6d9aded95b
+  metadata.gz: eef3e14394aedb500715af4c4381294b1b152cb86d0a295e7be62fbd1b141ca7e2e7fd94ea9b1f71b82ac8b0bede158cca412a80d127c1581b9cdf5ee9ea2260
+  data.tar.gz: bbb2544d92d370d5a55f57d642cd0e2145d48ca2e903a2645457f837e42bda62866c278c85ed7e8bc064b48db3c0ebadeb794963257fb1f719d9c780f53b88bd

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## v0.2.0 — 2026-09-13
+
+**Puma plugin (DESIGN §4.2 step 2)** — `plugin :otp_rails` in `config/puma.rb`: the master
+heartbeats worker-level state over the §5 socket; a missing worker reports `"degraded"`
+(⇒ `child.degraded` telemetry, `meta: {workers, booted, phase}`) while puma replaces it —
+visibility only, no lifecycle change. The `:puma` and `:solid_queue` adapters now export
+`OTP_RAILS_CHILD_ID=<id>` to their children (explicit `env:` wins).
+
+**Hardening from a three-track QA pass** (adversarial review + soak/stress + a Ruby⇄Elixir
+contract harness now permanent in the sidecar's CI):
+- Drain signals the whole process group — shell-wrapped cmds (`"a && b"`) no longer leave
+  their real workload running after a "clean" shutdown, or duplicate it on restart (#24).
+- Fan-out follows OTP: all affected children stop in reverse start order before any
+  restart; declaration-order dependencies hold during `rest_for_one`/`one_for_all` (#14).
+- One spawn path everywhere (fork → setsid → exec): an unspawnable `cmd:` is a child crash
+  (exit 127 → strategy → escalation), not a supervisor crash; identical on macOS/Linux (#15).
+- Socket hardening: 64 KiB line cap, string-typed `token`/`cmd`/`id`/`state`, unknown-id
+  heartbeats dropped at intake, 64-connection cap, listen backlog 128, connection threads
+  torn down on stop, unusable socket path ⇒ exit 78. A well-formed heartbeat naming a
+  subtree id no longer crashes the tree (#25, #27, #16, #17, #30, #31).
+- `stop` is prompt during stuck starts, restart fan-outs, and backoff sleeps — no more
+  blowing platform grace periods (#28). One healthy interval resets the backoff ladder
+  (#19). Non-restarted children leave no stale state or corpse telemetry (#20).
+- `Heartbeat`: the beat thread survives raising/unencodable `state:`/`meta:` lambdas
+  (falls back to last-good state / `{}`), and closes failed sockets — no fd growth while
+  the supervisor is away (#26, #29).
+- DESIGN §5 wire rules documented (token in the example, string fields, line cap, `ts`
+  informational); the Elixir sidecar mirrors them byte-for-byte.
+
+**Breaking:** `OtpRails::Heartbeat.start` returns the `Heartbeat` instance (so `#stop`
+works) instead of the raw Thread; still `nil` when unsupervised (#23).
+
 ## v0.1.1 — 2026-09-12
 
 - Gemspec only: author listed as `timimsms`. No code changes.

data/README.md

@@ -76,6 +76,18 @@ Adapters:
 - **`:solid_queue`** — wraps `bin/jobs` (`cmd:` overrides). Health = the active heartbeat
   below, never the `solid_queue_processes` table.
 
+For worker-level visibility on a cluster-mode `:puma` child, add the plugin to
+`config/puma.rb`:
+
+```ruby
+plugin :otp_rails
+```
+
+The master then heartbeats worker state over the socket: any missing worker is reported
+`"degraded"` (⇒ `[:otp_rails, :child, :degraded]` telemetry, `meta: {workers:, booted:,
+phase:}`) while puma replaces the worker itself — visibility only, no lifecycle change.
+Both adapters export `OTP_RAILS_CHILD_ID` so plugins and hooks heartbeat under the right id.
+
 ## Health & heartbeats
 
 Passive children are probed (PID, TCP, HTTP). Active children report themselves: the
@@ -87,8 +99,10 @@ supervisor listens on a Unix socket (mode 0600) and exports `OTP_RAILS_SOCK` /
 ```
 
 A child that has heartbeated is judged by heartbeat freshness: 3 missed `health_interval`s
-⇒ `:degraded`, 6 ⇒ `:dead` ⇒ the strategy applies. Wrong token ⇒ the line is silently
-dropped. The same socket accepts `{"cmd":"restart","id":"jobs","token":"…"}`.
+⇒ `:degraded`, 6 ⇒ `:dead` ⇒ the strategy applies. Wrong token, non-string fields, or
+lines over 64 KiB ⇒ silently dropped. The same socket accepts
+`{"cmd":"restart","id":"jobs","token":"…"}` — a control restart is deliberate remediation
+(DESIGN §7: restarting is a feature), so it does not count toward restart intensity.
 
 From any child process (a Rails initializer, a Solid Queue hook — no Rails required):
 
@@ -137,6 +151,11 @@ subscriber and a JSON-lines exporter ship by default (`Telemetry::Subscribers`).
   restarts the supervisor; each child runs in its own session/process group, so stale
   orphans are findable and killable by pgid.
 - macOS also caps Unix socket paths at ~104 bytes — keep `socket PATH` short.
+- Compound commands (`cmd: "a && b"`) run under an `sh` wrapper. Drain and kill signal the
+  whole process group, so supervised shutdown covers the real workload — but SIGKILL-of-
+  the-supervisor orphan prevention (pdeathsig) arms only the wrapper: on Linux the wrapper
+  gets SIGTERM and its children are orphaned. Prefer single-exec commands for children
+  that must never outlive the supervisor.
 
 ## Development
 

data/lib/otp_rails/adapters/command.rb

@@ -9,21 +9,21 @@ module OtpRails
         cmd = spec.opts.fetch(:cmd) { raise ConfigError, "#{spec.id}: :command adapter requires cmd:" }
         env = spec.opts.fetch(:env, {}).transform_keys(&:to_s)
         spawn_opts = spec.opts.fetch(:spawn_opts, {})
-        pid =
-          if OrphanGuard.available?
-            parent = Process.pid
-            Process.fork do
-              Process.setsid # own session ⇒ own pgroup, same as pgroup: true below
-              OrphanGuard.arm!(parent)
-              begin
-                Process.exec(env, cmd, **spawn_opts)
-              rescue SystemCallError
-                Process.exit!(127)
-              end
-            end
-          else
-            Process.spawn(env, cmd, pgroup: true, **spawn_opts)
+        # One spawn path on every platform (#15): fork → setsid → exec, with
+        # exec failure becoming exit 127 through the normal link → crash →
+        # strategy machinery. Process.spawn raised Errno::ENOENT into the
+        # supervisor loop for a bad cmd on macOS (whole tree crashed, exit 1)
+        # while the Linux fork path restart-looped to escalation (exit 70).
+        parent = Process.pid
+        pid = Process.fork do
+          Process.setsid # own session ⇒ own pgroup (drain/kill signal the group)
+          OrphanGuard.arm!(parent)
+          begin
+            Process.exec(env, cmd, **spawn_opts)
+          rescue StandardError
+            Process.exit!(127)
           end
+        end
         Handle.new(pid, spec, Process.clock_gettime(Process::CLOCK_MONOTONIC), nil, nil)
       end
 
@@ -53,7 +53,12 @@ module OtpRails
       end
 
       def drain(handle, timeout:)
-        Process.kill("TERM", handle.pid)
+        # Signal the whole process group, not just handle.pid: children are
+        # group leaders (setsid / pgroup: true), and a shell-wrapped cmd
+        # ("a && b") is an sh wrapper whose real workload is a grandchild in
+        # that group — TERM to the wrapper alone orphans the workload while
+        # reporting a clean drain (issue #24).
+        group_signal("TERM", handle.pid)
         handle.waiter&.join(timeout)
         !handle.exit_status.nil?
       rescue Errno::ESRCH
@@ -66,6 +71,16 @@ module OtpRails
       rescue Errno::ESRCH
         nil
       end
+
+      private
+
+      # TERM the group; fall back to the pid alone if the group is already
+      # gone by the time we signal (pure pid death races to the outer ESRCH).
+      def group_signal(sig, pid)
+        Process.kill(sig, -pid)
+      rescue Errno::ESRCH
+        Process.kill(sig, pid)
+      end
     end
   end
   Adapter.register(:command, Adapters::Command)

data/lib/otp_rails/adapters/puma.rb

@@ -36,7 +36,10 @@ module OtpRails
           shutdown: spec.shutdown, start_timeout: spec.start_timeout,
           opts: spec.opts.merge(
             cmd: "bundle exec puma -C #{config}",
-            probe: { http: "http://127.0.0.1:#{port}#{HEALTH_PATH}" }
+            probe: { http: "http://127.0.0.1:#{port}#{HEALTH_PATH}" },
+            # Tag the child so the otp_rails puma plugin (and any app hook)
+            # heartbeats under the right id; explicit env still wins.
+            env: { "OTP_RAILS_CHILD_ID" => spec.id.to_s }.merge(spec.opts.fetch(:env, {}))
           )
         )
       end

data/lib/otp_rails/adapters/solid_queue.rb

@@ -31,7 +31,12 @@ module OtpRails
         ChildSpec.new(
           id: spec.id, adapter: spec.adapter, restart: spec.restart,
           shutdown: spec.shutdown, start_timeout: spec.start_timeout,
-          opts: spec.opts.merge(cmd: spec.opts.fetch(:cmd, DEFAULT_CMD))
+          opts: spec.opts.merge(
+            cmd: spec.opts.fetch(:cmd, DEFAULT_CMD),
+            # Tag the child so the Heartbeat hook picks up its id from env;
+            # explicit env still wins.
+            env: { "OTP_RAILS_CHILD_ID" => spec.id.to_s }.merge(spec.opts.fetch(:env, {}))
+          )
         )
       end
     end

data/lib/otp_rails/heartbeat.rb

@@ -9,16 +9,25 @@ require "json"
 module OtpRails
   # Sends DESIGN §5 NDJSON heartbeats to the supervising socket:
   #
-  #   OtpRails::Heartbeat.start(id: "jobs")
+  #   beat = OtpRails::Heartbeat.start(id: "jobs")   # => Heartbeat or nil
+  #   beat&.stop
+  #
   #   OtpRails::Heartbeat.start(id: "jobs", interval: 2,
   #                             state: -> { queue_backlog_ok? ? "healthy" : "degraded" },
   #                             meta:  -> { { backlog: backlog_size } })
   #
-  # Silently a no-op when OTP_RAILS_SOCK / OTP_RAILS_TOKEN are absent — the
-  # child is running unsupervised (plain `bin/jobs` in development) and that
-  # must not be an error. Reconnects on socket loss; never raises into the
-  # host process.
+  # Silently a no-op (returns nil) when OTP_RAILS_SOCK / OTP_RAILS_TOKEN are
+  # absent — the child is running unsupervised and that must not be an error.
+  #
+  # The beating thread is unkillable by bad input (issue #26): a raising
+  # state/meta lambda falls back to the last good state / empty meta, an
+  # unencodable payload (bad UTF-8) drops down to a bare healthy beat, and
+  # socket failures close the socket (issue #29) and retry next beat. Going
+  # silent is the one thing this thread must never do while its process is
+  # healthy — silence is what gets the child restarted.
   class Heartbeat
+    # Returns the Heartbeat (so #stop works — issue #23), or nil when
+    # unsupervised.
     def self.start(id:, interval: 2, state: -> { "healthy" }, meta: -> { {} })
       new(id: id, interval: interval, state: state, meta: meta).start
     end
@@ -26,26 +35,64 @@ module OtpRails
     def initialize(id:, interval: 2, state: -> { "healthy" }, meta: -> { {} })
       @id, @interval, @state, @meta = id.to_s, interval, state, meta
       @sock_path, @token = ENV["OTP_RAILS_SOCK"], ENV["OTP_RAILS_TOKEN"]
+      @last_state = "healthy"
     end
 
-    # Returns the beating thread, or nil when unsupervised.
     def start
       return nil unless @sock_path && @token
-      @thread = Thread.new do
-        sock = nil
-        loop do
-          begin
-            sock ||= UNIXSocket.new(@sock_path)
-            sock.puts(JSON.generate(id: @id, state: @state.call, ts: Time.now.to_i,
-                                    token: @token, meta: @meta.call))
-          rescue IOError, SystemCallError
-            sock = nil # supervisor gone or restarting; try again next beat
-          end
-          sleep @interval
+      @thread ||= Thread.new { run_loop }
+      self
+    end
+
+    def stop
+      @thread&.kill
+      close_socket
+    end
+
+    def alive? = !!@thread&.alive?
+
+    private
+
+    def run_loop
+      loop do
+        begin
+          payload = build_payload
+          @sock ||= UNIXSocket.new(@sock_path)
+          @sock.puts(payload)
+        rescue StandardError
+          close_socket # supervisor gone or restarting; reconnect next beat
         end
+        sleep @interval
       end
     end
 
-    def stop = @thread&.kill
+    def build_payload
+      state = safe_state
+      meta = begin
+        @meta.call
+      rescue StandardError
+        {}
+      end
+      encode(state, meta) || encode(state, {}) || encode("healthy", {})
+    end
+
+    def safe_state
+      @last_state = @state.call.to_s
+    rescue StandardError
+      @last_state
+    end
+
+    def encode(state, meta)
+      JSON.generate(id: @id, state: state, ts: Time.now.to_i, token: @token, meta: meta)
+    rescue StandardError
+      nil
+    end
+
+    def close_socket
+      @sock&.close
+      @sock = nil
+    rescue IOError, SystemCallError
+      @sock = nil
+    end
   end
 end

data/lib/otp_rails/socket_server.rb

@@ -14,26 +14,41 @@ module OtpRails
   # Control:    {"cmd":"restart","id":"jobs","token":"…"}
   # Any line with a missing or wrong token is dropped without a reply.
   class SocketServer
+    MAX_LINE = 64 * 1024 # §5: longer lines are malformed and dropped
+    MAX_CONNS = 64       # excess connections are refused (closed immediately)
+
     attr_reader :path, :token
 
     def initialize(path:, on_heartbeat:, on_control:)
       @path, @on_heartbeat, @on_control = path, on_heartbeat, on_control
       @token = SecureRandom.hex(16)
+      @conns = []
     end
 
     # Binds, chmods, and exports OTP_RAILS_SOCK / OTP_RAILS_TOKEN so children
     # spawned afterwards inherit them (DESIGN §9). Call before starting children.
     def start
-      FileUtils.mkdir_p(File.dirname(@path))
-      File.unlink(@path) if File.exist?(@path) # stale socket from a dead boot
-      @server = UNIXServer.new(@path)
+      begin
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.unlink(@path) if File.exist?(@path) # stale socket from a dead boot
+        @server = UNIXServer.new(@path)
+      rescue ArgumentError, SystemCallError => e
+        # e.g. > ~104-byte path on macOS, unwritable dir: config problem, not a crash
+        raise ConfigError, "heartbeat socket #{@path.inspect}: #{e.message}"
+      end
+      @server.listen(128) # default backlog is 5 on macOS; bursts got ECONNREFUSED
       File.chmod(0o600, @path)
       ENV["OTP_RAILS_SOCK"] = @path
       ENV["OTP_RAILS_TOKEN"] = @token
       @acceptor = Thread.new do
         loop do
           conn = @server.accept
-          Thread.new { serve(conn) }
+          @conns.reject! { |c| !c[:thread].alive? }
+          if @conns.size >= MAX_CONNS
+            close_quietly(conn)
+            next
+          end
+          @conns << { conn: conn, thread: Thread.new { serve(conn) } }
         rescue IOError, SystemCallError
           break # server closed during shutdown
         end
@@ -43,6 +58,11 @@ module OtpRails
     def stop
       @server&.close
       @acceptor&.kill
+      @conns.each do |c| # connection threads must not outlive the server
+        c[:thread].kill
+        close_quietly(c[:conn])
+      end
+      @conns.clear
       File.unlink(@path) if File.exist?(@path)
     rescue SystemCallError
       nil
@@ -51,27 +71,45 @@ module OtpRails
     private
 
     def serve(conn)
-      conn.each_line do |line|
-        msg = begin
-          JSON.parse(line)
-        rescue JSON::ParserError
+      loop do
+        line = conn.gets("\n", MAX_LINE)
+        break if line.nil?
+        unless line.end_with?("\n")
+          # over-long line: memory stays capped at MAX_LINE — discard the rest
+          # of the line, then resume at the next newline
+          line = conn.gets("\n", MAX_LINE) while !line.nil? && !line.end_with?("\n")
+          break if line.nil?
           next
         end
-        next unless msg["token"] == @token # bad token ⇒ dropped
-        if msg["cmd"]
-          @on_control.call(msg)
-        elsif msg["id"] && msg["state"]
-          @on_heartbeat.call(msg)
-        end
+        handle_line(line)
       end
     rescue IOError, SystemCallError
       nil
     ensure
-      begin
-        conn.close
-      rescue IOError
-        nil
+      close_quietly(conn)
+    end
+
+    # §5: token, cmd, id, and state are JSON strings; anything else in those
+    # fields is malformed and silently dropped — same as a bad token. A bad
+    # line must never take the connection (or the supervisor) down.
+    def handle_line(line)
+      msg = begin
+        JSON.parse(line)
+      rescue StandardError
+        return
+      end
+      return unless msg.is_a?(Hash) && msg["token"] == @token
+      if msg.key?("cmd")
+        @on_control.call(msg) if msg["cmd"].is_a?(String)
+      elsif msg["id"].is_a?(String) && msg["state"].is_a?(String)
+        @on_heartbeat.call(msg)
       end
     end
+
+    def close_quietly(conn)
+      conn.close
+    rescue IOError, SystemCallError
+      nil
+    end
   end
 end

data/lib/otp_rails/supervisor.rb

@@ -14,11 +14,19 @@ module OtpRails
       @live = {}     # id => { adapter:, handle:, attempts:, generation:, monitor: }
       @queue = Queue.new
       @stopping = false
+      @stop_requested = false
       @heartbeats = {} # id => { at: monotonic ts of last heartbeat, state: reported state }
       return unless socket_path
       @socket = SocketServer.new(
         path: socket_path,
-        on_heartbeat: ->(msg) { @heartbeats[msg["id"].to_sym] = { at: mono_now, state: msg["state"] } },
+        # Heartbeats for ids that aren't children of THIS supervisor are
+        # dropped at intake: ghost ids must not grow the table unboundedly
+        # (issue #16/#27). Subtree-grandchild routing is the open flat-id
+        # question — until it's decided, their beats are dropped, not hoarded.
+        on_heartbeat: lambda { |msg|
+          id = msg["id"].to_sym
+          @heartbeats[id] = { at: mono_now, state: msg["state"] } if @children.any? { |c| c.id == id }
+        },
         on_control: ->(msg) { @queue << { type: :control, cmd: msg["cmd"], id: msg["id"].to_s.to_sym } }
       )
     end
@@ -37,7 +45,10 @@ module OtpRails
     def run
       Telemetry.emit(:"supervisor.start", {}, { strategy: strategy, children: ids })
       @socket&.start # before children, so they inherit OTP_RAILS_SOCK/_TOKEN
-      @children.each { |spec| start_child(spec) }
+      @children.each do |spec|
+        break if @stop_requested
+        start_child(spec)
+      end
       loop do
         msg = @queue.pop
         case msg[:type]
@@ -53,7 +64,14 @@ module OtpRails
       Telemetry.emit(:"supervisor.stop")
     end
 
-    def stop = @queue << { type: :stop }
+    # Sets the flag first: the main loop may be stuck in a wait_healthy poll
+    # or a backoff sleep for up to start_timeout/backoff seconds, and shutdown
+    # must not wait for those (issue #28 — platforms SIGKILL after their grace
+    # period, which resurrects the orphan problem).
+    def stop
+      @stop_requested = true
+      @queue << { type: :stop }
+    end
 
     # Public remediation API (DESIGN §7). Over IPC in the real thing; direct call here.
     def restart!(id)
@@ -100,6 +118,11 @@ module OtpRails
           case effective_health(spec, adapter, handle)
           when :healthy
             degraded = 0
+            # One healthy interval resets the backoff ladder (#19): a child
+            # that crashes rarely should not converge to permanent max
+            # backoff. Crash-looping children never reach a monitor, so flap
+            # damping is unaffected.
+            entry[:attempts] = 0
           when :degraded
             degraded += 1
             Telemetry.emit(:"child.degraded", { consecutive: degraded }, { id: spec.id })
@@ -118,6 +141,7 @@ module OtpRails
     def wait_healthy(spec, adapter, handle)
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + spec.start_timeout
       loop do
+        return :stopping if @stop_requested # shutdown must not wait out start_timeout (#28)
         case effective_health(spec, adapter, handle)
         when :healthy then Telemetry.emit(:"child.healthy", {}, { id: spec.id }); return :healthy
         when :dead    then return :dead # the exit message arrives via link
@@ -142,7 +166,10 @@ module OtpRails
     # back to the adapter's passive probe.
     def effective_health(spec, adapter, handle)
       hb = @heartbeats[spec.id]
-      return adapter.health(handle) unless hb
+      # No heartbeat ⇒ passive probe. A nil health_interval (subtree specs)
+      # also falls through: freshness aging needs an interval, and dividing
+      # by nil crashed the whole tree when a heartbeat named such an id (#25).
+      return adapter.health(handle) unless hb && spec.health_interval
       missed = (mono_now - hb[:at]) / spec.health_interval
       return :dead if missed >= 6
       return :degraded if missed >= 3
@@ -178,21 +205,46 @@ module OtpRails
 
       uptime = Process.clock_gettime(Process::CLOCK_MONOTONIC) - entry[:handle].started_at
       Telemetry.emit(:"child.exit", { exit_code: status&.exitstatus, uptime_ms: (uptime * 1000).round }, { id: id })
-      return unless spec.restart?(status)
+      unless spec.restart?(status)
+        # The child is gone for good: keep no stale entry, or stop_all and the
+        # monitor emit spurious drains for a corpse later (issue #20).
+        entry[:monitor]&.kill
+        @live.delete(id)
+        return
+      end
 
       if intensity.record!
         Telemetry.emit(:"supervisor.escalate", { restarts: intensity.count }, { within: intensity.within })
         raise Escalation, "restart intensity exceeded (#{intensity.count} in #{intensity.within}s)"
       end
 
-      Strategy.affected(strategy, ids, id).each do |aid|
-        aspec = spec_for(aid)
-        stop_child(aspec) unless aid == id
-        attempts = (@live[aid][:attempts] += 1)
+      affected = Strategy.affected(strategy, ids, id)
+      # OTP semantics (#14): declaration order encodes dependency, so first
+      # terminate ALL affected children in reverse start order — a
+      # replacement :b must never boot while an old :c that depended on the
+      # dead :b is still running — then restart them in start order.
+      affected.reverse_each do |aid|
+        stop_child(spec_for(aid)) unless aid == id
+      end
+      affected.each do |aid|
+        break if @stop_requested # shutdown preempts the restart fan-out (#28)
+        entry = @live[aid]
+        next unless entry # a temporary/clean-transient sibling is gone for good (#20)
+        attempts = (entry[:attempts] += 1)
         delay = backoff.delay(attempts)
         Telemetry.emit(:"child.restart", { backoff_ms: (delay * 1000).round }, { id: aid, attempt: attempts, strategy: strategy })
-        sleep delay
-        start_child(aspec)
+        interruptible_sleep(delay)
+        break if @stop_requested
+        start_child(spec_for(aid))
+      end
+    end
+
+    # Backoff must not delay shutdown (#28): sleep in slices, bail on stop.
+    def interruptible_sleep(seconds)
+      deadline = mono_now + seconds
+      while mono_now < deadline
+        return if @stop_requested
+        sleep [0.1, deadline - mono_now].min
       end
     end
 

data/lib/otp_rails/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module OtpRails
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/puma/plugin/otp_rails.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+# Puma plugin (DESIGN §4.2 step 2, PLAN 2.5): worker-level visibility for a
+# :puma child, over the §5 heartbeat socket. Enable with `plugin :otp_rails`
+# in config/puma.rb.
+#
+# Lives under lib/puma/ (NOT lib/otp_rails/) because it may require puma —
+# it is only ever loaded BY puma, so hard rule 1 (the supervisor has zero
+# dependencies) holds. It reuses the frozen heartbeat protocol untouched:
+# worker detail travels in `state` and `meta`, never in new fields.
+#
+# The master heartbeats every OTP_RAILS_HEARTBEAT_INTERVAL (default 2s):
+#   state = "degraded" while any worker is missing (booted < configured),
+#           "healthy" otherwise (single mode is always "healthy"),
+#   meta  = { workers:, booted:, phase: } (cluster) | { mode: "single" }.
+# The supervisor turns a reported "degraded" into [:otp_rails, :child,
+# :degraded] telemetry via its normal health loop — no event added, and no
+# lifecycle change: puma still replaces its own workers.
+require "puma/plugin"
+require "otp_rails/heartbeat"
+
+Puma::Plugin.create do
+  def start(launcher)
+    beat = OtpRails::Heartbeat.start(
+      id: ENV["OTP_RAILS_CHILD_ID"] || "web",
+      interval: Float(ENV.fetch("OTP_RAILS_HEARTBEAT_INTERVAL", 2)),
+      state: -> { otp_rails_state(launcher) },
+      meta: -> { otp_rails_meta(launcher) }
+    )
+    launcher.events.on_stopped { beat.stop } if beat
+  end
+
+  private
+
+  # Raising inside the heartbeat thread would silently kill it, so both
+  # lambdas degrade to a safe value instead (stats can raise mid-boot).
+  def otp_rails_state(launcher)
+    stats = launcher.stats
+    return "healthy" unless stats[:workers] # single mode
+    stats[:booted_workers] < stats[:workers] ? "degraded" : "healthy"
+  rescue StandardError
+    "starting"
+  end
+
+  def otp_rails_meta(launcher)
+    stats = launcher.stats
+    return { mode: "single" } unless stats[:workers]
+    { workers: stats[:workers], booted: stats[:booted_workers], phase: stats[:phase] }
+  rescue StandardError
+    {}
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: otp-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - timimsms
@@ -41,6 +41,7 @@ files:
 - lib/otp_rails/supervisor.rb
 - lib/otp_rails/telemetry.rb
 - lib/otp_rails/version.rb
+- lib/puma/plugin/otp_rails.rb
 homepage: https://github.com/shishi-odoshi/otp-rails
 licenses:
 - MIT