pgbus 0.15.2 → 0.15.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13ec61547a6821edab1a7aa96e794d522cc6fdcd38dd354bf601c9c760a2fded
-  data.tar.gz: b79ef51aa82c336ba98e3df071d40e9de5467bec196fb53edaf8a4fa5507327d
+  metadata.gz: 385f64fc61d6cb0c6c7c2cb1ae9e7286a73bdf1da97545ff7d409884243085e8
+  data.tar.gz: ea244f460ce992e31d234ab30d1ad9d083a20ae3493f745c04abee2e1a389a39
 SHA512:
-  metadata.gz: 8647f5cff936fae72bc95ea49c793fc68e514c29c2955d88b668dd6e5905a95418f7efdb8082e77048a584b9a0c86aa2cea42bbcd1f0777df349606ddbd4db08
-  data.tar.gz: ee10d3f15f0e03a8a46d359c5aaf19f3329ed628dd4ae72d98fe00aec4b9689ee43005b73884b62e997fb3305c0b2c5ec2ce9a747646e558a1ade1cbeca27f0e
+  metadata.gz: a9a3926554aec518d1c59c14749ebb345eb8cce02467dfed0df4c9bb0778eee2e3899517bd1d2533446269bee9bf2e1ed2a935a0658c1b727973aa68d1c7f4c7
+  data.tar.gz: 939083f3a554c6539da4f15167517c21ccee8314dcc732b9b29abf4e2271c97f1d1ef48e24d3b64bbe91e7956c177210e57a692b327d720730f340f205330b59

data/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ### 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.
 - **A process whose `pgbus_processes` row is deleted underneath it now re-registers instead of staying invisible forever (issue #438).** `Heartbeat#beat` updated its row by id; when the row was gone — the dispatcher's stale-process reaper after a ≥ 5-minute heartbeat gap, a manual cleanup, another host's clock skew — `update_all` matched 0 rows, raised nothing, and the process (healthy, logging, serving `/readyz`) was absent from `pgbus_processes` until it restarted, so the supervisor's DB loop-tick check silently fell back to the pipe and `ConsumerPriority` could not see it. The beat now treats an affected-row count of 0 as "row is gone": it logs one WARN naming the old id, kind and pid (so whatever deleted the row can be hunted), re-registers through the existing boot path, and lands that beat's `last_heartbeat_at` / metadata on the new row. A mutex plus a stopped flag keep a beat that races `stop` from resurrecting a row `deregister_process` just deleted. Zero extra queries on the happy path. Refs #438.
 - **Supervisor logs a worker recycle as a clean exit, not a crash (issue #438).** A worker or consumer hitting `max_jobs` / `max_memory` / `max_lifetime` exits 0 by design, but the supervisor logged `Child worker pid=N exited unexpectedly (status=0)`, burying real crashes. A clean exit outside shutdown is now INFO `exited cleanly (status=0) — restarting (worker recycle)`; non-zero exits keep the WARN, and a signaled exit reports `signal=N` instead of an empty status so an OOM SIGKILL is distinguishable. Restart policy is unchanged. Refs #438.
@@ -70,6 +73,9 @@
 
 ### Changed
 
+- **The gem root's `Gemfile.lock` is now committed.** Every checkout and CI leg resolves the same gem set (the main-Gemfile legs and `release.yml` install it frozen, like the Rails 7.1 and docs locks already were), so a fresh checkout can no longer silently pick up a newer dev dependency than the last green run. The gemspec builds `spec.files` from a path allowlist, so the lock never ships in the gem (verified with `gem build`). `rake release` bumps the `pgbus (X.Y.Z)` pin in all three tracked lockfiles in the bump commit, and `spec/pgbus/frozen_lockfile_sync_spec.rb` guards the root lock too. Contributors: after pulling, `bundle install` is a no-op unless the lock moved; run `bundle install` (not `bundle lock`) when you change a dependency, and commit the lock with it.
+- **Client build toolchain: bun 1.3.11 → 1.4.0.** `.bun-version`, the root `engines.bun` floor, and the docs-site CI job (now pinned to the same `.bun-version` file instead of `latest`) move together. Both `bun.lock` files install `--frozen-lockfile` unchanged; pgbus ships no bun-built artifacts, so nothing in the gem changes.
+
 - **Shutdown budgets are now alignable end-to-end (issue #386).** New `config.shutdown_timeout` bounds how long the supervisor waits for children after forwarding TERM before escalating to SIGKILL — previously a hardcoded 30s, which silently SIGKILLed workers mid-drain the moment `drain_timeout` was raised past it. Default derives `drain_timeout + 5` so the deadline tracks the drain window automatically; an explicit value below `drain_timeout` logs a boot warning. `Consumer#shutdown`'s pool wait (its only drain bound) now follows `config.drain_timeout` instead of a hardcoded 30s, and `Worker#shutdown`'s post-drain residual wait drops from a second full 30s window to 5s — the drain loop already waited `drain_timeout`, and a job still running has proven it won't finish. Rule of thumb: orchestrator stop grace period > `shutdown_timeout` > `drain_timeout`. Refs #386.
 
 - **Streams: one LISTEN connection per web host — `streams_listen_scope` (issue #382).** ⚠️ **Default behavior change.** Previously every Puma worker lazily opened its own dedicated streams LISTEN connection on first SSE use, so a web host pinned one direct connection per worker. Under the new default (`streams_listen_scope = :master`) the `pgbus_streams` Puma plugin runs a **MasterHub** in the preforking master: ONE `Web::Streamer::Listener` on the refcounted union of every worker's stream channels, fanning wakes — **including ephemeral payloads** — out to workers over a Unix domain socket with length-prefixed frames (`Streamer::HubProtocol`). Workers connect lazily (nothing is inherited across fork) and the synchronous `ensure_listening` ack contract is preserved cross-process: a sub is registered before LISTEN executes and acked only after, so the no-lost-broadcast guarantee holds. Backpressure follows the streams rules: durable wakes are droppable at a per-worker cap (they self-heal via `read_after`), **ephemeral wakes are never dropped** — a worker that stops draining is evicted, which triggers its own fallback. **Fallback is per-worker listeners, not loss**: whenever the hub is absent or dies (no `preload_app!`, single-mode Puma, crash, eviction) each worker's `FailoverListener` swaps in a real per-worker `Listener` and re-LISTENs its recorded subscriptions — connection footprint balloons back to pre-#382 levels (census-visible) but no broadcast semantics change; the worker stays local until it recycles. Measured (local PG, n=50): the master→worker hop is noise-level free — single-broadcast SSE roundtrip p50 16.00ms via the hub vs 16.93ms per-worker. **`:master` effectively requires `preload_app!`** (the hub waits for the app's pgbus initializer; without it the deadline expires quietly and workers stay per-worker). **Rollback:** `config.streams_listen_scope = :process`. Refs #382, builds on the #381 patterns.

data/README.md

@@ -6,7 +6,7 @@ PostgreSQL-native job processing and event bus for Rails, built on [PGMQ](https:
 
 📖 **Documentation:** [pgbus.zoolutions.llc](https://pgbus.zoolutions.llc) — guides, flow diagrams, and a full configuration reference. (This README stays the canonical GitHub reference.)
 
-[![Ruby](https://github.com/mhenrixon/pgbus/actions/workflows/main.yml/badge.svg)](https://github.com/mhenrixon/pgbus/actions/workflows/main.yml)
+[![Ruby](https://github.com/zoolutions/pgbus/actions/workflows/main.yml/badge.svg)](https://github.com/zoolutions/pgbus/actions/workflows/main.yml)
 
 ## Table of contents
 
@@ -1035,7 +1035,7 @@ When `config.metrics_enabled = true` (default), the dashboard exposes Prometheus
 
 Pgbus ships an optional, **read-only** [MCP](https://modelcontextprotocol.io) server so an AI agent (or any MCP client) can diagnose pgbus directly — "are queues backed up?", "is `read_ct` advancing?", "are workers heart-beating but not claiming?" — instead of hand-writing `pgmq` / `pg_stat_activity` SQL against production. It is a thin adapter over the same read layer the dashboard uses, so it adds no new database access path.
 
-Add the optional `mcp` gem to your `Gemfile` first (`gem "mcp"`); both entry points below tell you if it's missing.
+Add the optional `mcp` gem to your `Gemfile` first (`gem "mcp"`, 0.23 or newer — 1.x is fully supported); both entry points below tell you if it's missing.
 
 #### Choosing a deployment
 
@@ -1075,9 +1075,14 @@ Options:
 | `token:` | `nil` | Shared secret. When set, requests must send `Authorization: Bearer <token>` (constant-time compared). |
 | `auth:` | `nil` | A callable `->(rack_request) { ... }` returning truthy to allow — mirrors `config.web_auth`. Wins over `token:`. |
 | `allow_payloads:` | `false` | When true, tools honor a per-call `include_payloads` flag (see Security). |
+| `dns_rebinding_protection:` | `nil` | The `mcp` gem's Host/Origin validation (on by default since mcp 0.23, loopback hosts only). `nil` follows the gate: **off when `token:`/`auth:` is set, on when unauthenticated.** `true`/`false` forces it. |
+| `allowed_hosts:` | `nil` | Extra `Host` values accepted when the check is on (`"app.example.com"` matches any port, `"app.example.com:8443"` exactly). |
+| `allowed_origins:` | `nil` | Extra `Origin` values accepted beyond same-origin when the check is on. |
 
 If you set neither `token:` nor `auth:`, pgbus logs a warning — an unauthenticated diagnostic endpoint exposes operational metadata to anyone who can reach it.
 
+> **Why the Host check follows the gate.** DNS-rebinding protection defends a server bound to `localhost` against a browser page whose DNS name was re-pointed at `127.0.0.1`. Such a page can never carry your bearer token (the secret doesn't exist at the attacker's origin), so on a gated mount the check is redundant — and left on, it rejects every request to a real hostname (`https://app.example.com/pgbus/mcp` → `403 Invalid Host header`). Pgbus therefore turns it off when a gate is configured and keeps it on for the (warned-about) unauthenticated mount. If your `auth:` callable trusts something a rebound page *would* have — a source-IP allowlist, say — pass `dns_rebinding_protection: true` plus `allowed_hosts:` for your hostname. Requires `mcp >= 0.23`; older gems raise `Pgbus::Error` naming the floor.
+
 > Clients must send `Accept: application/json` and `Content-Type: application/json` on every POST, or the transport replies `406 Not Acceptable`. MCP clients do this automatically.
 
 Need a **standalone HTTP pod** instead of mounting in your main app? The same Rack app works under any Rack server, e.g. a one-line `config.ru`:
@@ -1220,9 +1225,9 @@ pgbus-health --port 9394              # or PGBUS_HEALTH_PORT=9394 pgbus-health
 pgbus-health --port 9394 --path /livez --timeout 2
 ```
 
-### Rolling restarts (Kamal, docker)
+### Rolling restarts (dash, docker)
 
-Kamal distributions with per-role health checks (for example the [`dash` branch](https://github.com/mhenrixon/kamal)) can rolling-restart a non-proxied job role: start the new container, poll its docker `HEALTHCHECK` until healthy, and only then `docker stop` the old one. Wire the pgbus container into that gate:
+[dash](https://github.com/zoolutions/dash) (per-role health checks) can rolling-restart a non-proxied job role: start the new container, poll its docker `HEALTHCHECK` until healthy, and only then `docker stop` the old one. Wire the pgbus container into that gate:
 
 ```yaml
 # config/deploy.yml
@@ -1253,7 +1258,7 @@ If the orchestrator's stop grace period is *shorter* than `shutdown_timeout`, do
 
 **The overlap window is safe by construction.** Between "new container healthy" and "old container stopped", two supervisors run against the same database. Nothing double-fires: queue claims use `FOR UPDATE SKIP LOCKED`, `single_active_consumer` queues arbitrate via session-level advisory locks (released the instant a killed process's connection dies), two live recurring schedulers dedup on the `(task_key, run_at)` unique record, and dispatcher maintenance is idempotent. "One scheduler per deployment" is a steady-state rule; a deploy window may briefly violate it without consequence.
 
-**What a hard kill still costs.** Jobs killed past the drain window are redelivered after their visibility timeout (at-least-once holds) — but PGMQ's `read_ct` increments exactly like a logical failure, so a long-running job that straddles *repeated* deploy kills can be pushed to the DLQ without its code ever raising. `zombie_detection` logs exactly this pattern (`read_ct > 1` with no recorded failure). Keep jobs shorter than `drain_timeout`, or raise it (and `stop_timeout`) for queues that can't be. For `idempotent!` event handlers there is a separate crash-window caveat tracked in [#385](https://github.com/mhenrixon/pgbus/issues/385).
+**What a hard kill still costs.** Jobs killed past the drain window are redelivered after their visibility timeout (at-least-once holds) — but PGMQ's `read_ct` increments exactly like a logical failure, so a long-running job that straddles *repeated* deploy kills can be pushed to the DLQ without its code ever raising. `zombie_detection` logs exactly this pattern (`read_ct > 1` with no recorded failure). Keep jobs shorter than `drain_timeout`, or raise it (and `stop_timeout`) for queues that can't be. For `idempotent!` event handlers there is a separate crash-window caveat tracked in [#385](https://github.com/zoolutions/pgbus/issues/385).
 
 ### Boot diagnostics banner
 
@@ -1746,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
@@ -1758,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
@@ -1929,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/Rakefile

@@ -232,9 +232,11 @@ task :release, %i[version force] do |_t, args|
 
   # Step 1b: Regenerate the frozen lockfiles that pin the pgbus path gem, so the
   # bump ships with them in sync. These are installed with `--frozen`/deployment
-  # in CI, so if they still name the OLD version they instant-fail (the Rails 7.1
-  # leg with exit 16, and docs-CI on any docs change). Regenerating here keeps the
-  # version-pin drift out of the release commit instead of surfacing on the next PR.
+  # in CI, so if they still name the OLD version they instant-fail (the root
+  # Gemfile.lock on every main-Gemfile leg AND release.yml's own `bundle install`,
+  # the Rails 7.1 leg with exit 16, and docs-CI on any docs change). Regenerating
+  # here keeps the version-pin drift out of the release commit instead of
+  # surfacing on the next PR — or, worse, in the Release workflow itself.
   header "Frozen lockfiles"
   # The ONLY thing a version bump changes in these frozen lockfiles is the pgbus
   # path-gem pin — so bump exactly that line, in place, with a string edit.
@@ -249,7 +251,7 @@ task :release, %i[version force] do |_t, args|
   # fetch). A targeted pin edit sidesteps all of it, is deterministic on any
   # machine, and produces the minimal 2-line diff (the PATH spec + the
   # DEPENDENCIES pin). See #338/#341 and the surgical-bump fix.
-  frozen_lockfiles = %w[gemfiles/rails_7_1.gemfile.lock docs/Gemfile.lock]
+  frozen_lockfiles = %w[Gemfile.lock gemfiles/rails_7_1.gemfile.lock docs/Gemfile.lock]
   regenerated_lockfiles = []
   frozen_lockfiles.each do |lockfile|
     unless File.exist?(lockfile)

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Pgbus configuration — https://github.com/mhenrixon/pgbus
+# Pgbus configuration — https://github.com/zoolutions/pgbus
 #
 # This is the real config surface. Every setting has a sensible default, so an
 # empty block gives you a working install; uncomment and edit what you need.

data/lib/pgbus/mcp/rack_app.rb

@@ -20,8 +20,24 @@ module Pgbus
     # Security: requests are rejected with 401 unless they carry the configured
     # token (or pass the supplied auth callable). Run it on an internal network
     # / behind your VPN, never internet-exposed.
+    #
+    # DNS-rebinding protection: since mcp 0.23 the transport validates the Host
+    # header (loopback only, by default) and the Origin header (same-origin
+    # only). That defends a server bound to localhost against a browser page
+    # whose DNS name was re-pointed at 127.0.0.1 — a page that can carry no
+    # bearer token, because the secret never reaches the attacker's origin. So
+    # when this app is gated (+token+ or +auth+) the check is redundant, and
+    # left on it rejects every request to a real hostname
+    # (https://app.example.com/pgbus/mcp → 403 "Invalid Host header"). The
+    # default therefore follows the gate: off when gated, on when unauthenticated.
+    # Override with +dns_rebinding_protection:+, and widen the accepted hosts /
+    # origins with +allowed_hosts:+ / +allowed_origins:+ when the check is on.
     class RackApp
       BEARER_PREFIX = "Bearer "
+      # First mcp release with the transport's allowed_hosts / allowed_origins /
+      # dns_rebinding_protection options. Older gems would raise ArgumentError
+      # on the pass-through; fail with the fix spelled out instead.
+      MIN_MCP_VERSION = Gem::Version.new("0.23.0")
       # Only the JSON body string is frozen and reused. The outer response triple
       # and its headers hash MUST be built fresh per call (#unauthorized) so
       # downstream Rack middleware can mutate them — Rack::TempfileReaper assigns
@@ -40,14 +56,27 @@ module Pgbus
       # @param auth [#call, nil] custom authenticator taking a Rack::Request and
       #   returning truthy to allow. Mirrors Pgbus.configuration.web_auth. Takes
       #   precedence over +token+ when both are given.
-      def initialize(data_source: Pgbus::Web::DataSource.new, allow_payloads: false, token: nil, auth: nil)
+      # @param allowed_hosts [Array<String>, nil] extra Host values the
+      #   transport accepts beyond loopback when DNS-rebinding protection is on;
+      #   a bare name matches any port, "host:port" matches exactly.
+      # @param allowed_origins [Array<String>, nil] extra Origin values accepted
+      #   beyond same-origin when DNS-rebinding protection is on.
+      # @param dns_rebinding_protection [Boolean, nil] nil (default) = on only
+      #   when the app is unauthenticated; true/false forces it. See the class
+      #   docs for why the gate makes the check redundant.
+      def initialize(data_source: Pgbus::Web::DataSource.new, allow_payloads: false, token: nil, auth: nil,
+                     allowed_hosts: nil, allowed_origins: nil, dns_rebinding_protection: nil)
+        check_mcp_version!
         @token = token
         @auth = auth
         @server = Server.build(data_source: data_source, allow_payloads: allow_payloads)
         @transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(
-          @server, stateless: true, enable_json_response: true
+          @server,
+          stateless: true, enable_json_response: true,
+          allowed_hosts: allowed_hosts, allowed_origins: allowed_origins,
+          dns_rebinding_protection: dns_rebinding_protection.nil? ? unauthenticated? : dns_rebinding_protection
         )
-        warn_unauthenticated! if @token.nil? && @auth.nil?
+        warn_unauthenticated! if unauthenticated?
       end
 
       # Mount THIS object, never the bare transport. The auth gate lives here
@@ -90,20 +119,36 @@ module Pgbus
         Runner.secure_compare?(@token, header.delete_prefix(BEARER_PREFIX))
       end
 
+      def unauthenticated?
+        @token.nil? && @auth.nil?
+      end
+
       def warn_unauthenticated!
         Pgbus.logger.warn do
           "[Pgbus::MCP] HTTP diagnostic server mounted without authentication. " \
             "Pass token: or auth: to Pgbus::MCP.rack_app, and keep it on an internal network."
         end
       end
+
+      def check_mcp_version!
+        installed = Gem::Version.new(::MCP::VERSION)
+        return if installed >= MIN_MCP_VERSION
+
+        raise Pgbus::Error,
+              "Pgbus::MCP.rack_app requires mcp >= #{MIN_MCP_VERSION} (the transport's DNS-rebinding " \
+              "options); mcp #{installed} is installed. Run `bundle update mcp`."
+      end
     end
 
     module_function
 
     # Build a gated Rack app serving the read-only diagnostic tools over HTTP.
     # See {RackApp} for the parameters and deployment guidance.
-    def rack_app(data_source: Pgbus::Web::DataSource.new, allow_payloads: false, token: nil, auth: nil)
-      RackApp.new(data_source: data_source, allow_payloads: allow_payloads, token: token, auth: auth)
+    def rack_app(data_source: Pgbus::Web::DataSource.new, allow_payloads: false, token: nil, auth: nil,
+                 allowed_hosts: nil, allowed_origins: nil, dns_rebinding_protection: nil)
+      RackApp.new(data_source: data_source, allow_payloads: allow_payloads, token: token, auth: auth,
+                  allowed_hosts: allowed_hosts, allowed_origins: allowed_origins,
+                  dns_rebinding_protection: dns_rebinding_protection)
     end
   end
 end

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.2"
+  VERSION = "0.15.4"
 end

data/lib/pgbus/web/authentication.rb

@@ -44,7 +44,7 @@ module Pgbus
         Pgbus.logger.warn do
           "[Pgbus] Dashboard is accessible without authentication. " \
             "Configure Pgbus.configuration.web_auth to restrict access. " \
-            "See: https://github.com/mhenrixon/pgbus#dashboard-authentication"
+            "See: https://github.com/zoolutions/pgbus#dashboard-authentication"
         end
         Pgbus::Web::Authentication.auth_warned = true
       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.2
+  version: 0.15.4
 platform: ruby
 authors:
 - Mikael Henriksson