pgbus 0.15.3 → 0.15.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ccee33eff147c5f62d51634db10d7d2529806a9b84d3373c8e66c4b93dfe68d
-  data.tar.gz: b3ebfda680231e62bc65a92822af22bcbb33a6666bfa9997be15387dcf2100cf
+  metadata.gz: 385f64fc61d6cb0c6c7c2cb1ae9e7286a73bdf1da97545ff7d409884243085e8
+  data.tar.gz: ea244f460ce992e31d234ab30d1ad9d083a20ae3493f745c04abee2e1a389a39
 SHA512:
-  metadata.gz: 76e267110b0064e3b257fa10d0dab5a05f9705b6dabc5b86884cf3655df5125498cc5957c589662d04603653d40b516c5f8d073db9d1937829bc012979c91f00
-  data.tar.gz: ddb7653b85459ff790f48386932f9096950386cb52643eb146c3f3f6c3dd53a8383935df80b69efa124874f7018884c9211264c35aa656494c0e8ff760bf7bd2
+  metadata.gz: a9a3926554aec518d1c59c14749ebb345eb8cce02467dfed0df4c9bb0778eee2e3899517bd1d2533446269bee9bf2e1ed2a935a0658c1b727973aa68d1c7f4c7
+  data.tar.gz: 939083f3a554c6539da4f15167517c21ccee8314dcc732b9b29abf4e2271c97f1d1ef48e24d3b64bbe91e7956c177210e57a692b327d720730f340f205330b59

data/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ### Fixed
 
+- **`Pgbus::Testing.disabled!` can no longer turn a Capybara teardown race into a hung test process (issue #443).** The `streams_test_mode` stub closed immediately, so a page on a stream-bearing layout had its `EventSource` reconnect every ~3s for the whole example; a reconnect landing after `disabled!` had switched test mode off — a config-level `after` hook runs *before* `Capybara.reset_sessions!` — took the real path and started a live `Streamer` (listener/dispatcher/heartbeat threads + a LISTEN connection) inside the RSpec process. Its orphaned threads then shared the test's pinned AR connection and CI died at the job timeout with only `message type 0x5a arrived from server while idle`. Three changes: the stub now emits `retry: 86400000` so the browser does not reconnect at all; `Streamer::Instance#shutdown!` snapshots every component's threads (`#threads` on Listener/Dispatcher/Heartbeat/OutboundPump/HubClient/FailoverListener), logs one error naming those still alive after their bounded joins, and returns that list (`Streamer.reset!` forwards it, `nil` when nothing was live); and `Testing.disabled!` raises `Pgbus::Testing::StreamerLeakError` — pointing at `config.append_after` — when threads leaked, while a live streamer that shut down cleanly is only logged. README and docs now recommend `config.append_after` for the teardown hook.
 - **`Pgbus::MCP.rack_app` works on a real hostname again with `mcp` 0.23+ / 1.x.** Since mcp 0.23 the `StreamableHTTPTransport` validates the `Host` header (DNS-rebinding protection, on by default, loopback hosts only) and pgbus had no way to pass the transport's options through — so a gated mount at `https://app.example.com/pgbus/mcp` answered every request `403 "Invalid Host header"`, and consumers pinned `mcp < 1.0` to dodge it (which only helps while the lock stays on 0.22). The rack app now exposes `allowed_hosts:`, `allowed_origins:` and `dns_rebinding_protection:`; the check **follows the gate by default** — off when `token:`/`auth:` is configured (a rebound browser page can never carry the bearer secret, so the check is redundant there), on for the warned-about unauthenticated mount — and `true`/`false` forces it. `mcp >= 0.23` is the floor for `rack_app` (older gems raise `Pgbus::Error` naming the fix); the gem's own bundle now tracks `mcp` 1.x, so lift that `< 1.0` pin. Stdio (`pgbus mcp`) is unaffected.
 
 - **Worker forks no longer kill the supervisor's shared LISTEN connection (issue #437).** Under `worker_notify_scope = :supervisor` every fork produced one `[Pgbus::NotifyListener] connection error (PG::ConnectionBad: PQconsumeInput() server closed the connection unexpectedly …) — reconnecting` in the supervisor ~2 s after `Worker started`, and a LISTEN gap (polling fallback) until `reconnect!` completed. The child's fork hygiene closed the Ruby `IO` wrapper of the inherited LISTEN socket, but pg builds `socket_io` with `autoclose=false`, so the fd stayed open — and when the child's GC freed the inherited `PG::Connection`, its `PQfinish` sent a libpq Terminate down that fd, i.e. down the **parent's** connection. `NotifyListener#close_inherited_socket!` now repoints the fd at `/dev/null` (`socket_io.reopen(IO::NULL)`, the ActiveRecord `PostgreSQLAdapter#discard!` idiom) so the eventual `PQfinish` is harmless. Regression-covered by a real-fork integration spec that asserts the parent's `pgbus-listen` backend pid is unchanged and no reconnect is logged. Refs #437.

data/README.md

@@ -1751,7 +1751,12 @@ require "pgbus/testing/rspec"
 
 RSpec.configure do |config|
   config.before { Pgbus::Testing.fake! }
-  config.after do
+  # append_after, not after: config-level `after` hooks run in reverse
+  # registration order, so one registered after `capybara/rspec` runs BEFORE
+  # Capybara.reset_sessions! — while the browser page is still open.
+  # append_after runs once the page is closed and its pending SSE requests
+  # are drained (see "SSE streams in tests" below).
+  config.append_after do
     Pgbus::Testing.disabled!
     Pgbus::Testing.store.clear!
   end
@@ -1763,7 +1768,7 @@ Or scope it to specific groups:
 ```ruby
 RSpec.configure do |config|
   config.before(:each, :pgbus) { Pgbus::Testing.fake! }
-  config.after(:each, :pgbus) do
+  config.append_after(:each, :pgbus) do
     Pgbus::Testing.disabled!
     Pgbus::Testing.store.clear!
   end
@@ -1934,10 +1939,14 @@ HTTP/1.1 200 OK
 Content-Type: text/event-stream
 Cache-Control: no-cache, no-transform
 
+retry: 86400000
+
 : pgbus test mode — connection accepted, no polling
 ```
 
-This is a valid SSE response that the browser's EventSource will accept. No `Streamer` singleton is created, no PG LISTEN connection is opened, and no dispatcher/heartbeat/listener threads are spawned.
+This is a valid SSE response that the browser's EventSource will accept. No `Streamer` singleton is created, no PG LISTEN connection is opened, and no dispatcher/heartbeat/listener threads are spawned. The `retry:` directive tells `EventSource` to wait 24 hours before reconnecting: without it a page left open re-requests the closed stub every ~3 seconds for the whole example, and that reconnect storm is what turns a teardown race into a real streamer running inside the test process.
+
+**Hook ordering with Capybara:** `Pgbus::Testing.disabled!` turns `streams_test_mode` back off. If it runs while the browser page is still open, a reconnect landing in that window takes the real stream path and starts a live `Streamer` — with listener/dispatcher/heartbeat threads and a LISTEN connection — inside your RSpec process. RSpec runs config-level `after` hooks in reverse registration order, so a plain `config.after { Pgbus::Testing.disabled! }` registered after `capybara/rspec` fires *before* `Capybara.reset_sessions!`. Register it with `config.append_after` (as in the snippet above) so the page is closed first. If a live streamer does get started and its threads outlive the bounded shutdown, `disabled!` raises `Pgbus::Testing::StreamerLeakError` with this diagnosis rather than letting the suite hang on a corrupted shared connection; a streamer that shut down cleanly is only logged as a warning, because that is expected inside `Pgbus::Testing.disabled! do ... end` real-stream tests.
 
 **Testing actual stream delivery:** If you need to verify end-to-end SSE message delivery in integration tests, disable `streams_test_mode` and use the `PumaTestHarness` from the pgbus test support:
 

data/lib/pgbus/testing.rb

@@ -18,6 +18,11 @@ module Pgbus
     MODES = %i[fake inline disabled].freeze
     MODE_KEY = :__pgbus_test_mode
 
+    # Raised by `disabled!` when a live Pgbus::Web::Streamer had to be torn
+    # down and some of its threads did not stop within their join budget —
+    # a red spec with a diagnosis instead of a hung test process (issue #443).
+    class StreamerLeakError < Pgbus::Error; end
+
     # Thread-safe in-memory store for events captured in fake/inline mode.
     class EventStore
       def initialize
@@ -70,15 +75,17 @@ module Pgbus
       def mode!(mode, &block)
         raise ArgumentError, "Unknown mode: #{mode}. Valid modes: #{MODES.join(", ")}" unless MODES.include?(mode)
 
-        sync_streams_test_mode!(mode)
-
+        # Record the mode BEFORE syncing streams: a StreamerLeakError raised
+        # by the teardown must still leave the process in the requested mode.
         unless block
           Thread.main[MODE_KEY] = mode
+          sync_streams_test_mode!(mode)
           return
         end
 
         old = Thread.current[MODE_KEY]
         Thread.current[MODE_KEY] = mode
+        sync_streams_test_mode!(mode)
         yield
       ensure
         if block
@@ -112,11 +119,34 @@ module Pgbus
 
         if mode == :disabled
           Pgbus.configuration.streams_test_mode = false
-          Pgbus::Web::Streamer.reset! if defined?(Pgbus::Web::Streamer)
+          reset_streamer!
         else
           Pgbus.configuration.streams_test_mode = true
         end
       end
+
+      # A live streamer at this point is legitimate inside a
+      # `disabled! do ... end` real-stream test, so a clean teardown only
+      # warns. Threads that outlived shutdown! are a different matter: left
+      # alone they share the test's pinned AR connection with the test thread
+      # and the suite hangs with no diagnosis (issue #443) — so raise.
+      def reset_streamer!
+        return unless defined?(Pgbus::Web::Streamer)
+
+        leaked = Pgbus::Web::Streamer.reset!
+        return if leaked.nil?
+
+        if leaked.empty?
+          Pgbus.logger.warn { "[Pgbus::Testing] disabled! tore down a live Pgbus::Web::Streamer that was started during the test" }
+          return
+        end
+
+        raise StreamerLeakError, <<~MSG
+          Pgbus::Testing.disabled! shut down a live Pgbus::Web::Streamer but its #{leaked.join(", ")} thread(s) did not stop within their join budget.
+          A live streamer inside the test process means an SSE request reached the real stream path while streams_test_mode was off — usually because Pgbus::Testing.disabled! ran in an RSpec `after` hook before Capybara reset the browser session (page still open, EventSource still reconnecting).
+          Register the hook with `config.append_after { Pgbus::Testing.disabled! }` so it runs after Capybara.reset_sessions!. See the README section "SSE streams in tests".
+        MSG
+      end
     end
   end
 end

data/lib/pgbus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pgbus
-  VERSION = "0.15.3"
+  VERSION = "0.15.4"
 end

data/lib/pgbus/web/stream_app.rb

@@ -31,6 +31,8 @@ module Pgbus
     # full request lifecycle.
     class StreamApp
       PATH_PREFIX = "/pgbus/streams"
+      # EventSource reconnect delay handed to the streams_test_mode stub (24h).
+      TEST_MODE_RETRY_MS = 86_400_000
       private_constant :PATH_PREFIX
 
       def initialize(streamer: nil, config: nil, logger: nil, authorize: nil)
@@ -221,8 +223,15 @@ module Pgbus
         [500, { "content-type" => "text/plain" }, ["pgbus: internal error"]]
       end
 
+      # A closed SSE response makes EventSource reconnect every ~3s by default.
+      # In a browser-driven test that storm keeps hitting the endpoint for the
+      # whole example, so a reconnect landing after the harness has turned
+      # streams_test_mode back off (teardown ordering) would start a LIVE
+      # streamer inside the test process (issue #443). Telling the browser to
+      # wait a day before retrying closes that window.
       def test_mode_stub
-        body = ": pgbus test mode — connection accepted, no polling\n\n"
+        retry_line = Pgbus::Streams::Envelope.retry_directive(TEST_MODE_RETRY_MS)
+        body = "#{retry_line}: pgbus test mode — connection accepted, no polling\n\n"
         [200, sse_headers, [body]]
       end
     end

data/lib/pgbus/web/streamer/failover_listener.rb

@@ -115,6 +115,13 @@ module Pgbus
           end
         end
 
+        # Snapshot of this component's live thread(s). Instance#shutdown! captures
+        # it BEFORE calling #stop so a join that timed out is still observable
+        # after #stop has cleared the reference (issue #443).
+        def threads
+          current_impl.threads
+        end
+
         def stop
           current_impl.stop
         end

data/lib/pgbus/web/streamer/heartbeat.rb

@@ -47,6 +47,13 @@ module Pgbus
           self
         end
 
+        # Snapshot of this component's live thread(s). Instance#shutdown! captures
+        # it BEFORE calling #stop so a join that timed out is still observable
+        # after #stop has cleared the reference (issue #443).
+        def threads
+          [@thread].compact
+        end
+
         def stop
           return unless @running
 

data/lib/pgbus/web/streamer/hub_client.rb

@@ -98,6 +98,13 @@ module Pgbus
           nil
         end
 
+        # Snapshot of this component's live thread(s). Instance#shutdown! captures
+        # it BEFORE calling #stop so a join that timed out is still observable
+        # after #stop has cleared the reference (issue #443).
+        def threads
+          [@reader].compact
+        end
+
         def stop
           @stopping = true
           close_quietly(@sock)

data/lib/pgbus/web/streamer/instance.rb

@@ -135,16 +135,28 @@ module Pgbus
         #
         # Bounded by the configured write deadline per connection; a dead
         # client drops instantly, a slow one stalls for at most write_deadline_ms.
+        #
+        # Every component join is bounded, so a thread blocked in a slow
+        # client write or a libpq call can outlive its #stop. That is not
+        # silent any more (issue #443): the names of the components whose
+        # threads are still alive afterwards are logged once and RETURNED
+        # (empty array = clean shutdown, also on a repeat call). The sentinel
+        # + socket close still run — Connection#close takes the same mutex as
+        # the writer, so it cannot fire mid-write even under a stuck thread.
         def shutdown!
           @shutdown_mutex.synchronize do
-            return unless @started
+            return [] unless @started
 
             @started = false
+            threads = component_threads
             safely { @heartbeat.stop }
             safely { @listener.stop }
             safely { @dispatcher.stop }
             safely { @pump&.stop }
+            leaked = threads.select { |_, list| list.any?(&:alive?) }.keys
+            report_leaked_threads(leaked) if leaked.any?
             close_all_connections
+            leaked
           end
         end
 
@@ -224,6 +236,25 @@ module Pgbus
           @logger.warn { "[Pgbus::Streamer::Instance] component stop raised: #{e.class}: #{e.message}" }
         end
 
+        # Captured BEFORE the stops: every component nils its thread
+        # reference in #stop whether or not the join succeeded.
+        def component_threads
+          {
+            "heartbeat" => @heartbeat.threads,
+            "listener" => @listener.threads,
+            "dispatcher" => @dispatcher.threads,
+            "pump" => @pump ? @pump.threads : []
+          }
+        end
+
+        def report_leaked_threads(leaked)
+          @logger.error do
+            "[Pgbus::Streamer::Instance] shutdown! finished but the #{leaked.join(", ")} thread(s) are " \
+              "still running past their join budget; they exit on their own once their current blocking " \
+              "call returns. In a test process this means a live streamer was started mid-suite (issue #443)."
+          end
+        end
+
         # Off-thread durable fanout writer (issue #321). nil (the default) keeps
         # fanout writes inline on the dispatcher thread. When on_dead fires
         # (a write failed), the pump posts a DisconnectMessage onto the shared

data/lib/pgbus/web/streamer/listener.rb

@@ -117,6 +117,13 @@ module Pgbus
           !@conn.nil?
         end
 
+        # Snapshot of this component's live thread(s). Instance#shutdown! captures
+        # it BEFORE calling #stop so a join that timed out is still observable
+        # after #stop has cleared the reference (issue #443).
+        def threads
+          [@thread].compact
+        end
+
         def stop
           return unless @running
 

data/lib/pgbus/web/streamer/outbound_pump.rb

@@ -99,6 +99,13 @@ module Pgbus
         # join each worker bounded by the write deadline. Never Thread#kill — a
         # kill mid write_nonblock corrupts IO state (mirrors
         # StreamEventDispatcher#stop). Idempotent.
+        # Snapshot of this component's live thread(s). Instance#shutdown! captures
+        # it BEFORE calling #stop so a join that timed out is still observable
+        # after #stop has cleared the reference (issue #443).
+        def threads
+          @threads.dup
+        end
+
         def stop
           return self unless @started
 

data/lib/pgbus/web/streamer/stream_event_dispatcher.rb

@@ -150,6 +150,13 @@ module Pgbus
           self
         end
 
+        # Snapshot of this component's live thread(s). Instance#shutdown! captures
+        # it BEFORE calling #stop so a join that timed out is still observable
+        # after #stop has cleared the reference (issue #443).
+        def threads
+          [@thread].compact
+        end
+
         def stop
           return unless @running
 

data/lib/pgbus/web/streamer.rb

@@ -41,6 +41,9 @@ module Pgbus
           @current_mutex.synchronize { @current&.stream_counter }
         end
 
+        # Tears down the current instance, if any. Returns nil when there was
+        # nothing to reset, otherwise Instance#shutdown!'s list of component
+        # names whose threads survived their bounded joins ([] = clean).
         def reset!
           instance = nil
           @current_mutex.synchronize do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.15.3
+  version: 0.15.4
 platform: ruby
 authors:
 - Mikael Henriksson