pgbus 0.15.2 → 0.15.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13ec61547a6821edab1a7aa96e794d522cc6fdcd38dd354bf601c9c760a2fded
-  data.tar.gz: b79ef51aa82c336ba98e3df071d40e9de5467bec196fb53edaf8a4fa5507327d
+  metadata.gz: 9ccee33eff147c5f62d51634db10d7d2529806a9b84d3373c8e66c4b93dfe68d
+  data.tar.gz: b3ebfda680231e62bc65a92822af22bcbb33a6666bfa9997be15387dcf2100cf
 SHA512:
-  metadata.gz: 8647f5cff936fae72bc95ea49c793fc68e514c29c2955d88b668dd6e5905a95418f7efdb8082e77048a584b9a0c86aa2cea42bbcd1f0777df349606ddbd4db08
-  data.tar.gz: ee10d3f15f0e03a8a46d359c5aaf19f3329ed628dd4ae72d98fe00aec4b9689ee43005b73884b62e997fb3305c0b2c5ec2ce9a747646e558a1ade1cbeca27f0e
+  metadata.gz: 76e267110b0064e3b257fa10d0dab5a05f9705b6dabc5b86884cf3655df5125498cc5957c589662d04603653d40b516c5f8d073db9d1937829bc012979c91f00
+  data.tar.gz: ddb7653b85459ff790f48386932f9096950386cb52643eb146c3f3f6c3dd53a8383935df80b69efa124874f7018884c9211264c35aa656494c0e8ff760bf7bd2

data/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ### Fixed
 
+- **`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 +72,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
 

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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pgbus
-  VERSION = "0.15.2"
+  VERSION = "0.15.3"
 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

metadata

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