pgbus 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d927ac10d70c354f2624eb9495c0e21d6913a3f6a074e94705e32ac69a5f51db
-  data.tar.gz: 36c12b3e6cb620f9443bde0a3cdc0137072076ee38e40381d5a3cc3960504596
+  metadata.gz: 44b8e6016eb94d129ba3f90831ee6e3f8eb213c928e61766c35fa4641f0a518b
+  data.tar.gz: d35475deb1eaaf59e893c7096b10bc85498482f5940fc099e5add48af54aecbd
 SHA512:
-  metadata.gz: c1381157be5c95baab7d9fa9097d18d212c74a3262887ddb31629c54c2cab42c0ca8d699f7da6565a8649fd41d5f4eda63b5b77660cd28cfb8a4516eb04d852d
-  data.tar.gz: c36c9c2012f2ccf315e3102bbfc61cbddf3462134782687670bcdebf72f7bae7d639b2b0824b2fd1339ef9836d0b68e7a106169148d324a486652c1770e14665
+  metadata.gz: db2122fe97f2b77dd6812e5e9a5264850b4eb84ff3c6094cc2c0e11a148989fa3ae502664e040da26b1ea1bf11b764c2b1f9659a58f9d4a6b663be54c1027cba
+  data.tar.gz: 597210a0238131f0a7912b0cf135dc4d89ce66ab830354dca3b3805dbc70a9ccbd2106830dea85b17c68be73fb79868ff9c43d27813e84e6f457dfbe996107d3

data/CHANGELOG.md

@@ -2,11 +2,16 @@
 
 ### Breaking Changes
 
+- **`config.validate!` now rejects malformed values for 12 core config keys at boot instead of failing deep in a worker or silently misbehaving (issue #335).** Before the 1.0 surface freeze, these headline job-path keys had **zero** validation while streams keys had 14 checks — so a bad value surfaced as a crash inside a worker/dispatcher/poller/scheduler thread, per-enqueue, or by silently corrupting every derived queue name / leaving the dashboard open. `Pgbus.configure` (eager-validating by default) now raises `Pgbus::ConfigurationError` naming the key for: the worker-recycling trio `max_jobs_per_worker`/`max_memory_mb`/`max_worker_lifetime` (positive number or `nil` to disable); the intervals `dispatch_interval`/`outbox_poll_interval`/`recurring_schedule_interval` (positive number); `outbox_batch_size` (positive integer); `default_priority` (non-negative integer — `0` is a valid level); `queue_prefix`/`default_queue` (non-empty String — an empty prefix silently produced malformed queue names); `web_auth` (a callable or `nil` — a non-callable silently left the dashboard open); `error_reporters` (an Array); and `connects_to` (a Hash or `nil` — previously a malformed value raised a raw `TypeError` deep in engine boot). This only rejects configuration that was already broken; if a `Pgbus.configure` block set one of these to an invalid value it will now fail loudly at boot (the intended pre-freeze tightening). Set `config.eager_validation = false` to defer. Refs #335, #282.
+- **`config.streams_queue_prefix` is removed (issue #335).** It had been an inert no-op since #308 — stream queues are named like job queues (`#{queue_prefix}_<name>`) and identified via the `pgbus_stream_queues` registry, so the prefix affected nothing — yet it was still a writable accessor documented as "Prefix for stream queues" (false). Rather than carry a dead, misleadingly-documented key into the 1.0 semver promise, the accessor is **removed**: `c.streams_queue_prefix = ...` now raises `NoMethodError`. **Action:** delete the line from your initializer — it never did anything. Refs #335, #308.
+- **`ensures_uniqueness strategy: :until_executed` with no `key:` now raises when the job is enqueued *with arguments* — the class-name default silently collapsed per-record jobs (issue #333).** Without an explicit `key:`, the uniqueness key defaulted to the job class name. For a job that takes per-record arguments (`ImportOrderJob.perform_later(order_id)`), every distinct `order_id` resolved to the same class-name key and collapsed into ONE per-class singleton — order 1 and order 2 shared a lock, so the second was silently discarded/rejected — with no warning. The guard is at **resolve time, argument-aware**: a no-key `:until_executed` job enqueued **with arguments** now raises `ArgumentError` naming the collapse and pointing at the upgrade guide; **a no-argument job keeps the class-name default** (a legitimate "one logical instance at a time" — e.g. a recurring `CleanupJob` that must not overlap itself — is unaffected). `:while_executing` is unaffected (it acquires per-invocation at execution start, not by class-name identity at enqueue). Fix: pass `key: ->(*args) { "job-#{args.first}" }` on any argument-taking `:until_executed` job. Refs #333.
 - **YAML config (`config/pgbus.yml`) is removed for 1.0 — the Ruby initializer is the only config surface.** Ruby was always the real config surface (every production setup is a `Pgbus.configure` initializer); `config/pgbus.yml` was only ever a legacy convenience, and pre-1.0 is the last low-risk moment to drop it before the config shape becomes a compatibility promise. Concretely: the engine no longer loads `config/pgbus.yml` at boot (the `pgbus.configure` initializer and `Pgbus::ConfigLoader` are deleted); `rails generate pgbus:install` generates `config/initializers/pgbus.rb` (done for 1.0, see below); and `rails generate pgbus:update` no longer converts YAML → initializer (`Pgbus::Generators::ConfigConverter`, its `--source`/`--destination`/`--skip-config` options, and the `pgbus.yml.erb` template are deleted) — `pgbus:update` now only detects and installs missing migrations. **If you still have a `config/pgbus.yml`, it is no longer loaded** — the engine warns once at boot (pointing at the docs) so the inert file doesn't quietly diverge from your real config. Port its settings into `config/initializers/pgbus.rb` as a `Pgbus.configure` block and delete the YAML; the last release that auto-converts it via `pgbus:update` is 0.9.x, so run that conversion (or port by hand) **before** upgrading to 1.0. The recurring-tasks YAML (`config/recurring.yml`, `Pgbus::Recurring::ConfigLoader`) is a separate surface and is unchanged. Refs #317.
 - **The error hierarchy is unified under `Pgbus::Error` for the 1.0 API freeze.** Several call sites raised bare stdlib errors that no `rescue Pgbus::Error` could catch, freezing an inconsistent contract into 1.0. Now: **`Configuration#validate!` and every config setter raise `Pgbus::ConfigurationError`** (was `ArgumentError`) — this is the one that can break existing code: a `rescue ArgumentError` around `Pgbus.configure` or a boot-time config read will no longer catch config failures; switch to `rescue Pgbus::Error` (or `rescue Pgbus::ConfigurationError`). The ActiveJob adapter's `perform_all_later` msg_id-count mismatch now raises **`Pgbus::EnqueueError`** (new, was `RuntimeError`); `ExecutionPools::AsyncPool` shutdown/at-capacity raises now use **`Pgbus::ExecutionPoolError`** (new, was `RuntimeError`); `Serializer#locate_global_id` GlobalID rejections raise **`Pgbus::SerializationError`** (was `ArgumentError`). Three error classes that bypassed the base — `PgmqSchema::VersionNotFoundError` and `Streams::SignedName::InvalidSignedName`/`MissingSecret` — are re-parented under `Pgbus::Error`. Three classes that reject a malformed *argument shape* — `Configuration::CapsuleDSL::ParseError`, `Streams::Cursor::InvalidCursor`, `Streams::StreamNameTooLong` — **deliberately stay `ArgumentError` subclasses**; the policy ("argument-shape errors are `ArgumentError`, operational errors are `Pgbus::Error`") is documented in `lib/pgbus.rb` and pinned by `spec/pgbus/error_hierarchy_spec.rb`. Messages are unchanged. Refs #282.
 
 ### Added
 
+- **`Pgbus::Streams::PhlexHelpers` — a Phlex-includable `pgbus_stream_from`, and `Pgbus.stream_name_budget` (issue #334).** Two small helpers that stop consuming apps reimplementing pgbus glue. (1) `pgbus_stream_from` is a Rails view helper, so a Phlex component couldn't call it without hand-registering an output-helper macro (phlex-rails ships no `Phlex::Rails::Helpers::PgbusStreamFrom`). `include Pgbus::Streams::PhlexHelpers` now bridges it exactly like phlex-rails' own `TurboStreamFrom`. phlex-rails stays an **optional** dependency — the module references its `HelperMacros` and is loaded on demand (`require "pgbus/streams/phlex_helpers"`), never eagerly. (2) `Pgbus.stream_name_budget` exposes the maximum stream-name length (the pgmq queue-name cap minus the queue prefix) so apps size/truncate stream identifiers up front instead of hand-computing `MAX_QUEUE_NAME_LENGTH - queue_prefix.length - 1` at every call site. Refs #334.
+- **`EventBus::Registry#setup_all!(safe: true)` — a boot/rake-safe way to eagerly set up event subscribers (issue #334).** Calling `setup_all!` opens a PGMQ connection per subscriber (to create its queue + bind its topic), which is wrong during a `db:`/schema rake task (a live connection blocks `DROP DATABASE`) and crashes boot if the database isn't up yet — so apps wrapped it in a hand-rolled multi-class rescue plus a rake-task skip. `setup_all!(safe: true)` bakes that in: it skips entirely in a schema/asset rake context and swallows a connection error with a warning instead of raising. The default `setup_all!` is unchanged (raises). Refs #334.
 - **Connection-pooler safety (`config.require_primary`, `config.connection_guc_mode`) — pgbus is now correct-and-loud behind a transaction/read-write-splitting pooler instead of silently stalling (issue #332).** Three linked fixes. (1) **Primary affinity:** a read/write-splitting pooler (pgdog/pgcat) can route pgmq's VOLATILE `read`/`archive`/`delete` to a read replica, where workers read nothing (`read_ct=0`) and jobs stop with a **healthy heartbeat** — the supervisor watchdog keys on loop advancement, not read progress, so nothing surfaced the stall. The job read path had zero primary-affinity defense (only the LISTEN/streamer paths validated the primary via `PrimaryValidator`). Setting `config.require_primary = true` (default **false** — a single-primary deployment is byte-identical) makes `verify_connection!` reject a connection that lands on a replica (`pg_is_in_recovery() => t`) at supervisor boot, raising a clear `ConfigurationError` instead of forking children that read nothing. (2) **GUC forwarding:** pgbus's AR-config extraction dropped database.yml's `variables:` block, so `client_min_messages` (and any GUC) never reached pgmq's dedicated raw connections (NOTICE flooding that three consuming apps hand-patched via `connection_params`). GUCs are now forwarded, on both the AR-extracted and explicit-`connection_params` paths, by `config.connection_guc_mode`: `:options` (default) bakes them into the libpq `options` STARTUP param (byte-compatible with today for the read-timeout `statement_timeout`, now also carrying `variables:`), while `:session` applies them via post-connect `SET` on a fresh connection instead — for a transaction-mode PgBouncer that **rejects** the `options` startup param with a FATAL. `pgbus doctor` gains a ninth check ("Primary affinity") that warns (never fails) when the job connection is currently on a replica, naming the direct-port remediation. DB-gated integration tests prove both GUC modes round-trip a forwarded GUC and that `require_primary` verifies on a real primary. Refs #332.
 - **Job-burst tuning guidance + gate benchmark (`rake bench:job_burst`), and a decision NOT to autoscale the job pool (issue #323 phase 3).** Following the issue's measure-first mandate, `benchmarks/job_burst_bench.rb` sweeps worker thread count under a job burst in two connection regimes (pool matched to threads vs. pool fixed small). Measured finding: a job holds a pgmq connection only for the `read_batch` + `archive` round-trip (not the job body), so **the DB connection pool is the hard burst ceiling, not the thread count** — in the fixed-pool regime `peak_busy` never exceeds `pool_size` no matter how many threads run (extra threads just queue on checkout, latency climbs, throughput plateaus), while matching the pool to the thread count scales throughput ~linearly (≈8× from 2→16). The conclusion — issue #323's explicitly sanctioned outcome — is that **elastic job threads on a fixed connection pool cannot help**, so pgbus does *not* autoscale the job execution pool; the fix for job bursts is **static headroom**: raise `threads` (and let `pool_size` follow, or keep it ≥ `threads`). Documented in the Performance & tuning docs. The streams-pool autoscaling below stays the elastic story where it *does* pay off (the streams pool's connection cost genuinely scales with its size). Refs #323.
 - **Fan-out writer throughput gate benchmark (`writer_burst_bench.rb`), and a decision NOT to make the writer pool elastic (issue #323 phase 1).** Following the issue's measure-first mandate, `benchmarks/writer_burst_bench.rb` drives a sustained fan-out burst (a fleet of connections × many wakes) through the `OutboundPump` while sweeping `streams_writer_threads`, across fast/typical socket-write profiles. Measured finding: throughput scales ~linearly with writer count (≈6× from 2→16) — but that is generic parallelism (N workers finish N independent blocking writes ~N× faster), which argues for the **existing static `streams_writer_threads` knob**, not for elastic writers: a fixed-N sweep can't demonstrate the *spikiness* that would make a static count wasteful enough to justify dynamic resize, and the genuinely harmful case (a slow/congested client) is already **shed** by the #320/#322 fan-out deadline + mark-dead path rather than absorbed by scaling writers. Given the elastic-writer rewrite is the issue's highest-risk phase (it would touch the ordering/cursor invariant #321's whole review exists to protect — mis-sizing risks out-of-order SSE frames), the conclusion — issue #323's sanctioned outcome — is that pgbus does **not** autoscale the writer pool; the fan-out-throughput knob is **static `streams_writer_threads`, sized for your peak fan-out fleet**. Documented in the Performance & tuning docs. Refs #323.
@@ -27,6 +32,10 @@
 
 ### Fixed
 
+- **`config.log_format` no longer breaks `ActiveSupport::TaggedLogging` — tags are preserved instead of dropped, and `logger.tagged` no longer raises (issue #334).** TaggedLogging works by extending the logger's formatter instance with a module that prepends the current tags. Installing a fresh pgbus formatter (`LogFormatter::JSON`/`Text`) stripped that extension, so `logger.tagged("req-42") { ... }` dropped the tag — and, worse, raised `NoMethodError: undefined method 'tagged'` on the pgbus formatter (a deploy-breaker several apps hit, then worked around with a dedicated `$stdout` logger). `log_format=` now re-extends the replacement formatter with `ActiveSupport::TaggedLogging::Formatter` when the previous one carried it, so tagging keeps working. Refs #334.
+- **The "Dashboard is accessible without authentication" warning is no longer a false positive when a gating `base_controller_class` is set (issue #334).** The warning fired whenever `web_auth` was nil, ignoring that a non-default `base_controller_class` (e.g. an `AdminController` with its own `before_action`) already gates the dashboard — so apps set a redundant `web_auth` lambda purely to silence the log line. The warning now stays quiet when `base_controller_class` is anything other than the default `::ActionController::Base`. Refs #334.
+- **`retry_on` on an `:until_executed` job no longer dead-letters the job instead of retrying (issue #333).** The uniqueness key is released only on success or DLQ, but ActiveJob's `retry_on` re-enqueues from *inside* `perform_now` (after incrementing `executions`), while the executor still holds the key. That retry re-enqueue hit the job's own still-held key, was rejected as a duplicate (`JobNotUnique` under `on_conflict: :reject`), and the original message dead-lettered — so a job with both `ensures_uniqueness :until_executed` and `retry_on` lost its retry and DLQ'd on the first transient failure. A retry re-enqueue (`executions > 0`) is now recognized as the same logical job re-acquiring its own key and is allowed through; the existing key row correctly stays held until the job finally succeeds or dead-letters. Cross-job uniqueness (a genuine fresh duplicate, `executions == 0`) is still rejected. Proven end-to-end with a DB-gated integration test (fail-once-then-succeed runs to success exactly once, no `JobNotUnique`, no DLQ, key cleaned up). Refs #333.
+- **A wildcard (`queues: ['*']`) worker no longer adopts event-bus subscriber queues and dead-letters the events (issue #333).** Event-subscriber queues share the job namespace (`#{queue_prefix}_<handler>`) but carry event payloads, not ActiveJob jobs. `resolve_wildcard_queues` excluded only `_dlq` and stream queues, so a wildcard worker claimed event queues too, handed each event to the ActiveJob executor, failed to deserialize it, and DLQ-moved it out of the consumer's reach — forcing apps that run the event bus to hand-maintain an explicit queue list. Wildcard resolution now also excludes every registered event-subscriber queue (new `EventBus::Registry#event_queue_names`), mirroring the existing stream-queue exclusion. Refs #333.
 - **A pooler-deaf NOTIFY listener no longer raises the worker poll floor to 15s — worse latency than a plain no-NOTIFY deployment (issue #332).** pgbus already detects a transaction-mode pooler / replica LISTEN connection with a self-NOTIFY probe (`NotifyProbe`) and logs a loud, actionable error, but the probe's boolean result was **discarded**: a live-but-deaf listener still reported `running? == true`, so `Worker#wake_timeout` treated it as a healthy NOTIFY source and raised the empty-fetch poll floor to `NOTIFY_FALLBACK_POLL_SECONDS` (15s) — behind a pooler the loop would then sleep up to 15s between polls while jobs sat ready. `NotifyListener` now records the probe result and exposes `delivering?`; `wake_timeout` treats a non-delivering listener as absent and keeps polling at the fast `polling_interval` until a direct-port connection is configured. The streamer path needed no change — its listener already waits on the short `streams_listen_health_check_ms` and has no equivalent 15s ceiling. Refs #332.
 - **The dispatcher no longer logs a scary `Concurrency cleanup failed: ... terminating connection due to administrator command` WARN when an idle DB connection is killed between maintenance cycles.** The dispatcher is a long-lived loop that queries the DB on coarse intervals (concurrency cleanup every 300s, most tasks hourly) and, until now, kept its pooled ActiveRecord connection leased across the idle sleep. When the server terminated that idle backend — routine in **local development** (a Postgres restart, `rails db:migrate` calling `pg_terminate_backend` on idle backends, foreman/overmind restarting the DB) — the next cycle reused the dead socket and *every* maintenance task raised `PG::ConnectionBad` with PostgreSQL's `terminating connection due to administrator command` text, surfaced as an alarming WARN even though the process was healthy and self-heals on the next tick. Two changes: (1) `run_maintenance` now returns every leased AR connection to the pool after each cycle (`clear_active_connections!`, mirroring the Streamer's existing `release_ar_connections`), so an idle backend is never reused — the next cycle checks out afresh and AR's `verify!`-on-checkout transparently discards a dead socket and reconnects; (2) every maintenance task's failure log now routes through `log_maintenance_failure`, which recognizes the terminated-idle-connection signal and logs a calm INFO ("reconnecting on the next cycle") instead of a WARN. Non-connection failures still WARN unchanged, and maintenance backoff is unaffected (a self-healing cycle resets the failure streak on the next successful reconnect).
 - **`priority_levels > 1` no longer silently breaks durable streams.** With job priority enabled, `QueueFactory.for` selects `PriorityStrategy`, and `Client#send_message` routes *every* send — including durable stream broadcasts (which pass no `priority:`) — to a `_p<default_priority>` sub-queue. But the streamer LISTENs and replays exclusively on the **bare** `pgmq.q_<stream>` queue (`read_after`, `notify_stream`), so the broadcast never reached the browser; on a fresh DB, `ensure_stream_queue` also raised `PG::UndefinedTable` because `ensure_queue` created only `_p0.._pN`, never the bare table the NOTIFY trigger and archive index attach to. Durable broadcasts now go through a dedicated `Client#send_stream_message` that always targets the bare queue, and `ensure_stream_queue` creates the bare queue directly via `ensure_single_queue` — both independent of the priority strategy, mirroring the bare-name read path. Streams are delivered by a non-consuming peek; priority sub-queues are meaningless for them. Ephemeral broadcasts (the default mode) were never affected. Refs #310.

data/Rakefile

@@ -209,17 +209,62 @@ task :release, %i[version force] do |_t, args|
     success "Updated #{version_file}"
   end
 
+  # 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.
+  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.
+  #
+  # We deliberately do NOT run `bundle lock` here: a full re-resolve trips over
+  # constraints that have nothing to do with pgbus. Concretely, docs/Gemfile.lock
+  # carries a broad PLATFORMS list (…-gnu / …-musl / arm-linux) for which a
+  # platform gem like `thruster` ships no variant, so `bundle lock` fails with
+  # "Could not find gems matching 'thruster' valid for all resolution platforms"
+  # on any machine whose cache doesn't already hold those exact gems — aborting
+  # the release. `bundle lock --local` was even worse (wrong-file write + no
+  # 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]
+  regenerated_lockfiles = []
+  frozen_lockfiles.each do |lockfile|
+    unless File.exist?(lockfile)
+      skip "#{lockfile} not present"
+      next
+    end
+
+    content = File.read(lockfile)
+    # Matches both the PATH-source spec ("    pgbus (X.Y.Z)") and the
+    # DEPENDENCIES pin ("  pgbus (X.Y.Z)"), leaving everything else untouched.
+    bumped = content.gsub(/^(\s+pgbus) \([^)]*\)$/, "\\1 (#{new_version})")
+
+    if bumped == content
+      skip "#{lockfile} — no pgbus pin to bump"
+      next
+    end
+
+    File.write(lockfile, bumped)
+    regenerated_lockfiles << lockfile
+    success "Bumped pgbus pin in #{lockfile}"
+  end
+
   # Step 2: Verify gem builds cleanly
   header "Build verification"
   sh("gem build pgbus.gemspec --strict")
   sh("rm -f pgbus-*.gem")
   success "Gem builds cleanly"
 
-  # Step 3: Commit version bump
+  # Step 3: Commit version bump (+ any re-synced lockfiles)
   header "Git commit"
-  version_changed = !`git diff #{version_file}`.strip.empty? || !`git diff --cached #{version_file}`.strip.empty?
-  if version_changed
-    sh("git add #{version_file}")
+  paths_to_stage = [version_file, *regenerated_lockfiles]
+  staged_changes = paths_to_stage.any? do |path|
+    !`git diff #{path}`.strip.empty? || !`git diff --cached #{path}`.strip.empty?
+  end
+  if staged_changes
+    paths_to_stage.each { |path| sh("git add #{path}") }
     sh("git commit -m 'chore: bump version to #{new_version}'")
     success "Committed version bump"
   else

data/lib/pgbus/active_job/adapter.rb

@@ -112,6 +112,17 @@ module Pgbus
         uniqueness_key = Uniqueness.extract_key(payload_hash)
         return false unless uniqueness_key
 
+        # A retry re-enqueue is the SAME logical job re-acquiring its OWN key.
+        # ActiveJob increments `executions` at the start of perform_now (before
+        # the body), then retry_on re-enqueues from inside perform_now — while
+        # the executor still holds the key (it releases only on success/DLQ). So
+        # a re-enqueue with executions > 0 would otherwise hit its own held key,
+        # be rejected as a duplicate (JobNotUnique), and dead-letter the original
+        # while losing the retry. Let the retry through; the existing key row
+        # correctly stays held until the job finally succeeds or dead-letters.
+        # See issue #333.
+        return false if active_job.executions.to_i.positive?
+
         result = Uniqueness.acquire_enqueue_lock(uniqueness_key, active_job)
 
         # :no_lock means no enqueue-time lock needed (e.g. :while_executing strategy)

data/lib/pgbus/configuration.rb

@@ -145,7 +145,7 @@ module Pgbus
     attr_accessor :health_port, :health_bind
 
     # Streams (turbo-rails replacement, SSE-based)
-    attr_accessor :streams_enabled, :streams_path, :streams_queue_prefix, :streams_signed_name_secret,
+    attr_accessor :streams_enabled, :streams_path, :streams_signed_name_secret,
                   :streams_default_retention, :streams_retention, :streams_heartbeat_interval,
                   :streams_max_connections, :streams_idle_timeout, :streams_listen_health_check_ms,
                   :streams_write_deadline_ms, :streams_falcon_streaming_body,
@@ -291,12 +291,11 @@ module Pgbus
 
       @streams_enabled = true
       @streams_path = nil
-      # Retained for backward compatibility only — NO LONGER USED for queue
-      # naming or stream detection. Stream queues are named like job queues
-      # (`#{queue_prefix}_<name>`, see #queue_name) and are identified via the
-      # `pgbus_stream_queues` registry (Pgbus::StreamQueue), not by this prefix.
-      # Setting it has no effect. See issue #308.
-      @streams_queue_prefix = "pgbus_stream"
+      # streams_queue_prefix was removed in 1.0 (issue #335): it had been an
+      # inert no-op since #308 (stream queues are named like job queues,
+      # `#{queue_prefix}_<name>`, and identified via the pgbus_stream_queues
+      # registry). Setting it now raises NoMethodError — remove it from your
+      # initializer.
       # Streamer-only connection overrides. The Streamer's Listener owns a
       # dedicated long-lived `wait_for_notify` PG connection that can't go
       # through a PgBouncer in transaction mode (LISTEN/NOTIFY don't survive
@@ -495,12 +494,23 @@ module Pgbus
       # pgbus-installed formatter. A user who set a custom logger with a custom
       # formatter keeps it — log_format only records the intended format for
       # pgbus's own defaults, it must not silently clobber their formatting.
-      return unless pgbus_installable_formatter?(@logger&.formatter)
-
-      @logger.formatter = case format
-                          when :json then LogFormatter::JSON.new
-                          when :text then LogFormatter::Text.new
-                          end
+      old_formatter = @logger&.formatter
+      return unless pgbus_installable_formatter?(old_formatter)
+
+      new_formatter = case format
+                      when :json then LogFormatter::JSON.new
+                      when :text then LogFormatter::Text.new
+                      end
+
+      # ActiveSupport::TaggedLogging works by extending the logger's formatter
+      # instance with a module that prepends the current tags (and adds a
+      # #tagged method the logger delegates to). Installing a fresh pgbus
+      # formatter would strip that, so `logger.tagged { ... }` would drop tags —
+      # and, worse, raise NoMethodError: undefined method `tagged` on our
+      # formatter. Re-extend the new formatter with the same module when the old
+      # one carried it, so tagging keeps working (issue #334).
+      preserve_tagged_logging(old_formatter, new_formatter)
+      @logger.formatter = new_formatter
     end
 
     VALID_BROADCAST_MODES = %i[ephemeral durable].freeze
@@ -631,12 +641,63 @@ module Pgbus
 
       raise Pgbus::ConfigurationError, "require_primary must be true or false" unless [true, false].include?(require_primary)
 
+      validate_job_path_gaps!
       validate_streams!
       validate_metrics_backend!
 
       self
     end
 
+    # Pre-1.0 surface-freeze: reject malformed values for core job-path keys at
+    # boot rather than failing deep in a worker/dispatcher/poller/scheduler
+    # thread, per-enqueue, or by silently corrupting queue names / leaving the
+    # dashboard open. Mirrors the idioms already used above (issue #335).
+    def validate_job_path_gaps!
+      # Worker recycling trio: nil disables the limit; a set value must be a
+      # positive Numeric (mirror stall_threshold).
+      { max_jobs_per_worker: max_jobs_per_worker, max_memory_mb: max_memory_mb,
+        max_worker_lifetime: max_worker_lifetime }.each do |name, value|
+        next if value.nil? || (value.is_a?(Numeric) && value.positive?)
+
+        raise Pgbus::ConfigurationError, "#{name} must be a positive number or nil to disable"
+      end
+
+      # Interval knobs: positive Numeric, never nil (mirror polling_interval).
+      { dispatch_interval: dispatch_interval, outbox_poll_interval: outbox_poll_interval,
+        recurring_schedule_interval: recurring_schedule_interval }.each do |name, value|
+        raise Pgbus::ConfigurationError, "#{name} must be > 0" unless value.is_a?(Numeric) && value.positive?
+      end
+
+      unless outbox_batch_size.is_a?(Integer) && outbox_batch_size.positive?
+        raise Pgbus::ConfigurationError, "outbox_batch_size must be a positive integer"
+      end
+
+      # 0 is a valid priority level (queue_factory clamps to 0..priority_levels-1).
+      unless default_priority.is_a?(Integer) && default_priority >= 0
+        raise Pgbus::ConfigurationError, "default_priority must be a non-negative integer"
+      end
+
+      # Queue-name components: a nil/empty/non-String prefix silently corrupts
+      # every derived queue name (mirror health_bind).
+      { queue_prefix: queue_prefix, default_queue: default_queue }.each do |name, value|
+        raise Pgbus::ConfigurationError, "#{name} must be a non-empty String" unless value.is_a?(String) && !value.empty?
+      end
+
+      # web_auth gates the dashboard; a non-callable value silently leaves it
+      # open (mirror streams_presence_member).
+      unless web_auth.nil? || web_auth.respond_to?(:call)
+        raise Pgbus::ConfigurationError, "web_auth must respond to #call (a Proc/lambda) or be nil"
+      end
+
+      raise Pgbus::ConfigurationError, "error_reporters must be an Array" unless error_reporters.is_a?(Array)
+
+      # connects_to is splatted into ActiveRecord's connects_to at engine boot;
+      # a non-Hash raises a raw TypeError there — surface a clean message here.
+      return if connects_to.nil? || connects_to.is_a?(Hash)
+
+      raise Pgbus::ConfigurationError, "connects_to must be a Hash or nil"
+    end
+
     def validate_streams!
       unless streams_default_retention.is_a?(Numeric) && streams_default_retention >= 0
         raise Pgbus::ConfigurationError, "streams_default_retention must be a non-negative number"
@@ -1114,28 +1175,7 @@ module Pgbus
     #
     # Precedence: streams_database_url > streams_host/port override > base.
     def streams_connection_options
-      return streams_database_url if streams_database_url
-
-      base = connection_options
-      return base unless streams_host || streams_port
-
-      case base
-      when Hash
-        result = base.dup
-        result[:host] = streams_host if streams_host
-        result[:port] = streams_port if streams_port
-        result
-      when String
-        # libpq's conninfo parser takes later key=value pairs as overrides
-        # for earlier ones, so we just append. Handles both URI form
-        # (postgres://...) and key=value form.
-        parts = [base]
-        parts << "host=#{streams_host}" if streams_host
-        parts << "port=#{streams_port}" if streams_port
-        parts.join(" ")
-      else
-        base
-      end
+      override_connection_options(url: streams_database_url, host: streams_host, port: streams_port)
     end
 
     # Connection options for the Worker's dedicated NotifyListener connection.
@@ -1143,38 +1183,64 @@ module Pgbus
     # overridable via worker_notify_database_url / worker_notify_host /
     # worker_notify_port so the LISTEN connection can bypass PgBouncer.
     def worker_notify_connection_options
-      return worker_notify_database_url if worker_notify_database_url
+      override_connection_options(url: worker_notify_database_url, host: worker_notify_host, port: worker_notify_port)
+    end
+
+    # Resolved notify wakeup flag: defaults to listen_notify when nil.
+    def worker_notify_wakeup?
+      if @worker_notify_wakeup.nil?
+        listen_notify
+      else
+        @worker_notify_wakeup
+      end
+    end
+
+    private
+
+    # Shared resolver for a dedicated connection (streamer LISTEN / worker
+    # NotifyListener) that can override the base `connection_options` to bypass a
+    # pooler. Precedence: a full `url` wins outright; otherwise `host`/`port`
+    # surgically override the base (a Hash gets dup+merge, a String URL/conninfo
+    # gets appended key=value pairs libpq treats as later-wins overrides); with
+    # no override, or a base that is neither Hash nor String, the base passes
+    # through unchanged. Extracted from the byte-identical
+    # streams_connection_options / worker_notify_connection_options (issue #335).
+    def override_connection_options(url:, host:, port:)
+      return url if url
 
       base = connection_options
-      return base unless worker_notify_host || worker_notify_port
+      return base unless host || port
 
       case base
       when Hash
         result = base.dup
-        result[:host] = worker_notify_host if worker_notify_host
-        result[:port] = worker_notify_port if worker_notify_port
+        result[:host] = host if host
+        result[:port] = port if port
         result
       when String
         parts = [base]
-        parts << "host=#{worker_notify_host}" if worker_notify_host
-        parts << "port=#{worker_notify_port}" if worker_notify_port
+        parts << "host=#{host}" if host
+        parts << "port=#{port}" if port
         parts.join(" ")
       else
         base
       end
     end
 
-    # Resolved notify wakeup flag: defaults to listen_notify when nil.
-    def worker_notify_wakeup?
-      if @worker_notify_wakeup.nil?
-        listen_notify
-      else
-        @worker_notify_wakeup
-      end
+    # When the logger's previous formatter was extended with
+    # ActiveSupport::TaggedLogging::Formatter (the case for a Rails
+    # Rails.logger), extend the replacement pgbus formatter with the same module
+    # so `logger.tagged`/`push_tags` keep prepending tags instead of dropping
+    # them (and calling #tagged on our formatter stops raising NoMethodError).
+    # No-op when TaggedLogging isn't loaded or the old formatter wasn't tagged.
+    def preserve_tagged_logging(old_formatter, new_formatter)
+      return unless new_formatter
+      return unless defined?(::ActiveSupport::TaggedLogging::Formatter)
+      return unless old_formatter.is_a?(::ActiveSupport::TaggedLogging::Formatter)
+
+      new_formatter.extend(::ActiveSupport::TaggedLogging::Formatter)
     end
 
-    private
-
     # True when log_format= may install its own formatter: no formatter set yet
     # (nil), a pgbus formatter we installed, or a framework DEFAULT formatter
     # (Ruby's Logger::Formatter, Rails' SimpleFormatter) that the app didn't

data/lib/pgbus/event_bus/registry.rb

@@ -28,20 +28,79 @@ module Pgbus
         subscriber
       end
 
-      def setup_all!
-        @subscribers.each(&:setup!)
+      # Set up every registered subscriber (creates its queue + binds its topic
+      # via Pgbus.client, which opens a PGMQ connection).
+      #
+      # safe: false (default) — set up unconditionally; a connection error
+      #   propagates. Use when you know the database is up.
+      # safe: true — boot/rake-safe: skip entirely in a schema/db: rake context
+      #   (opening a PGMQ connection there would block DROP DATABASE and isn't
+      #   wanted during schema load / asset precompile), and swallow a connection
+      #   error with a warning instead of crashing boot when the DB isn't ready.
+      #   This is the path host apps should call from an initializer so they stop
+      #   hand-wrapping setup_all! in a multi-class rescue (issue #334).
+      def setup_all!(safe: false)
+        return if safe && schema_task_context?
+
+        # Snapshot under the mutex — subscribe/clear! mutate @subscribers under
+        # @mutex, and setup! does DB I/O we must NOT hold the lock across, so
+        # iterate a copy taken atomically.
+        subscribers = @mutex.synchronize { @subscribers.dup }
+
+        subscribers.each do |subscriber|
+          subscriber.setup!
+        rescue PGMQ::Errors::ConnectionError, PG::ConnectionBad => e
+          # Only a genuine CONNECTION failure ("database isn't up yet") is
+          # tolerable under safe:; a PG::Error subclass like a syntax/permission/
+          # missing-table error is a real setup bug and must still surface.
+          raise unless safe
+
+          Pgbus.logger.warn do
+            "[Pgbus] EventBus subscriber setup skipped (#{e.class}: #{e.message}) — " \
+              "the database isn't reachable yet; subscribers set up on the next attempt."
+          end
+        end
       end
 
       def handlers_for(routing_key)
         @subscribers.select { |s| matches?(s.pattern, routing_key) }
       end
 
+      # Physical PGMQ queue names for every registered event subscriber, so a
+      # wildcard (`queues: ['*']`) worker can exclude them — an event queue
+      # carries event payloads, not ActiveJob jobs, and a job worker that adopts
+      # one fails to deserialize and DLQ-moves the event (issue #333). Returns a
+      # Set of prefixed names (`#{queue_prefix}_<subscriber>`), matching the
+      # pgmq.meta rows the wildcard resolver diffs against.
+      def event_queue_names
+        @subscribers.to_set { |s| Pgbus.configuration.queue_name(s.queue_name) }
+      end
+
       def clear!
         @mutex.synchronize { @subscribers.clear }
       end
 
       private
 
+      # Rake task-name prefixes during which pgbus must NOT open a PGMQ
+      # connection: creating/dropping/migrating/loading the schema (a live
+      # connection blocks DROP DATABASE) and asset precompile (no DB expected).
+      SCHEMA_TASK_PREFIXES = %w[db: db_test: assets: webpacker: yarn:].freeze
+      private_constant :SCHEMA_TASK_PREFIXES
+
+      # True when running inside a rake schema/asset task, where setup_all!(safe:)
+      # should skip rather than open a connection. Detected from the invoked rake
+      # task names; false outside a Rake run.
+      def schema_task_context?
+        return false unless defined?(::Rake) && ::Rake.respond_to?(:application)
+
+        tasks = ::Rake.application.top_level_tasks
+        tasks.any? { |t| SCHEMA_TASK_PREFIXES.any? { |prefix| t.to_s.start_with?(prefix) } }
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus] schema_task_context? detection failed, assuming non-schema: #{e.class}: #{e.message}" }
+        false
+      end
+
       def matches?(pattern, routing_key)
         regex = pattern
                 .gsub(".", "\\.")

data/lib/pgbus/process/worker.rb

@@ -415,11 +415,20 @@ module Pgbus
         Pgbus::StreamQueue.reset_cache!
         stream_names = Pgbus::StreamQueue.all_names
 
+        # Event-bus subscriber queues also share the job namespace (pgbus_<handler>)
+        # but carry event payloads, not ActiveJob jobs. A wildcard worker that
+        # adopts one hands the event to the executor, which fails to deserialize
+        # it and DLQ-moves it out of the consumer's reach — so an app running the
+        # event bus had to hand-maintain an explicit queue list. Exclude them,
+        # like stream queues (issue #333).
+        event_names = Pgbus::EventBus::Registry.instance.event_queue_names
+
         conn = Pgbus.configuration.connects_to ? Pgbus::BusRecord.connection : ActiveRecord::Base.connection
         all_queues = conn.select_values("SELECT queue_name FROM pgmq.meta ORDER BY queue_name")
         resolved = all_queues
                    .reject { |q| q.end_with?(dlq_suffix) }
                    .reject { |q| stream_names.include?(q) }
+                   .reject { |q| event_names.include?(q) }
                    .map { |q| q.delete_prefix(prefix) }
 
         if resolved.empty?

data/lib/pgbus/streams/phlex_helpers.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Streams
+    # Phlex-includable version of the +pgbus_stream_from+ Rails view helper, so
+    # a Phlex component can subscribe a page to a pgbus stream the same way it
+    # would with turbo-rails' +turbo_stream_from+:
+    #
+    #   class ChatRoom < Phlex::HTML
+    #     include Pgbus::Streams::PhlexHelpers
+    #
+    #     def view_template
+    #       pgbus_stream_from(@room)
+    #     end
+    #   end
+    #
+    # phlex-rails doesn't ship a +Phlex::Rails::Helpers::PgbusStreamFrom+, so
+    # apps used to hand-register this module locally. It is defined exactly like
+    # phlex-rails' own +Phlex::Rails::Helpers::TurboStreamFrom+ (register the
+    # method as an output helper resolved against the Rails view context).
+    #
+    # This file is NOT autoloaded — phlex-rails is an OPTIONAL dependency, so the
+    # module references +Phlex::Rails::HelperMacros+, which only exists when the
+    # app has phlex-rails. Require it explicitly from a Phlex component or an
+    # initializer:  require "pgbus/streams/phlex_helpers".
+    module PhlexHelpers
+      extend Phlex::Rails::HelperMacros
+
+      register_output_helper def pgbus_stream_from(...) = nil
+    end
+  end
+end

data/lib/pgbus/uniqueness.rb

@@ -62,9 +62,18 @@ module Pgbus
         raise ArgumentError, "on_conflict must be one of: #{VALID_CONFLICTS.join(", ")}" unless VALID_CONFLICTS.include?(on_conflict)
         raise ArgumentError, "key must be callable (Proc or lambda)" if key && !key.respond_to?(:call)
 
+        # Record whether an explicit key was given. With NO explicit key the key
+        # defaults to the class name; that is safe for a no-argument job (one
+        # logical instance — e.g. a recurring CleanupJob that must not overlap
+        # itself) but a silent-correctness footgun for a job that takes per-record
+        # arguments: `ImportOrderJob.perform_later(order_id)` would collapse every
+        # order into ONE per-class singleton. resolve_key raises at resolve time
+        # when the class-name default meets non-empty arguments (see #333); the
+        # no-arg case keeps working. explicit_key marks which is which.
         @pgbus_uniqueness = {
           strategy: strategy,
           key: key || ->(*) { name },
+          explicit_key: !key.nil?,
           on_conflict: on_conflict
         }.freeze
       end
@@ -80,6 +89,7 @@ module Pgbus
         return nil unless config
 
         args = active_job.arguments
+        guard_class_name_default!(active_job, config, args)
         last = args.last
         key = if last.is_a?(Hash) && last.each_key.all?(Symbol)
                 config[:key].call(*args[...-1], **last)
@@ -93,6 +103,27 @@ module Pgbus
         key
       end
 
+      # Guards the class-name default key against the per-record collapse
+      # footgun (#333). When an :until_executed job was declared with NO explicit
+      # key (so the key is the class name) AND is enqueued WITH arguments, every
+      # distinct argument set would resolve to the same class-name key and
+      # collapse into one per-class singleton — almost never what the caller
+      # wants. Raise with an actionable message. A no-argument job keeps the
+      # class-name default (one logical instance, e.g. a recurring task that must
+      # not overlap itself), and :while_executing is unaffected (it acquires
+      # per-invocation at execution start, not by class-name identity at enqueue).
+      def guard_class_name_default!(active_job, config, args)
+        return if config[:explicit_key]
+        return unless config[:strategy] == :until_executed
+        return if args.nil? || args.empty?
+
+        raise ArgumentError,
+              "#{active_job.class.name} uses ensures_uniqueness strategy: :until_executed with no key: " \
+              "but is enqueued with arguments — the default key is the class name, which would collapse " \
+              "every distinct argument set into one per-class singleton. Pass an explicit " \
+              "key: ->(*args) { ... } that includes the arguments. See https://pgbus.dev/docs/upgrading-pgbus"
+      end
+
       def inject_metadata(active_job, payload_hash)
         config = uniqueness_config(active_job)
         return payload_hash unless config

data/lib/pgbus/version.rb

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

data/lib/pgbus/web/authentication.rb

@@ -13,6 +13,12 @@ module Pgbus
         attr_accessor :auth_warned
       end
 
+      # Default base controller — anything else means the app deliberately
+      # chose a controller (e.g. an AdminController) that already gates access,
+      # so the dashboard isn't actually open and the warning is a false positive.
+      DEFAULT_BASE_CONTROLLER = "::ActionController::Base"
+      private_constant :DEFAULT_BASE_CONTROLLER
+
       private
 
       def authenticate_pgbus!
@@ -30,6 +36,10 @@ module Pgbus
 
       def warn_unauthenticated_dashboard
         return if Pgbus::Web::Authentication.auth_warned
+        # A non-default base_controller_class signals host-level auth is in
+        # place; don't nag apps that gate the dashboard via a custom controller
+        # (they had to set a redundant web_auth lambda just to silence us — #334).
+        return unless default_base_controller?
 
         Pgbus.logger.warn do
           "[Pgbus] Dashboard is accessible without authentication. " \
@@ -38,6 +48,19 @@ module Pgbus
         end
         Pgbus::Web::Authentication.auth_warned = true
       end
+
+      # True when base_controller_class is (still) the default ActionController::Base.
+      # Normalizes both sides so a Class value, the "::"-prefixed string, and the
+      # bare "ActionController::Base" string all compare equal — otherwise the
+      # warning would wrongly fire for an app that set the default in another form.
+      def default_base_controller?
+        normalize_controller_name(Pgbus.configuration.base_controller_class) ==
+          normalize_controller_name(DEFAULT_BASE_CONTROLLER)
+      end
+
+      def normalize_controller_name(value)
+        value.to_s.delete_prefix("::")
+      end
     end
   end
 end

data/lib/pgbus.rb

@@ -103,6 +103,11 @@ module Pgbus
         # the gem and loads the subsystem explicitly.
         loader.ignore("#{__dir__}/pgbus/mcp")
         loader.ignore("#{__dir__}/pgbus/mcp.rb")
+        # The Phlex stream helper references Phlex::Rails::HelperMacros from the
+        # optional `phlex-rails` gem. Keep it out of Zeitwerk so eager_load never
+        # touches those constants; a Phlex app requires it explicitly via
+        # `require "pgbus/streams/phlex_helpers"`.
+        loader.ignore("#{__dir__}/pgbus/streams/phlex_helpers.rb")
         # Vendor integrations are loaded conditionally (when the vendor gem
         # is present) by lib/pgbus/engine.rb. Keeping them out of Zeitwerk
         # means we don't reference vendor constants at autoload time.
@@ -209,6 +214,19 @@ module Pgbus
       Streams::Key.stream_key!(key)
     end
 
+    # The maximum length (in characters) a stream name may be before it
+    # overflows the pgbus queue-name budget. A stream name becomes the physical
+    # queue `#{queue_prefix}_<name>`, and PGMQ caps queue names, so the usable
+    # budget is `QueueNameValidator::MAX_QUEUE_NAME_LENGTH - queue_prefix.length
+    # - 1`. Depends on `config.queue_prefix`. Use it to size or truncate stream
+    # identifiers up front instead of hand-computing the budget at every call
+    # site.
+    #
+    #   name = candidate.length > Pgbus.stream_name_budget ? Pgbus.stream_key(record) : candidate
+    def stream_name_budget
+      Streams::Key.queue_name_budget
+    end
+
     # Publish an event to the bus — the top-level shortcut for
     # `Pgbus::EventBus::Publisher.publish`, symmetric with `Pgbus.stream`.
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -352,6 +352,7 @@ files:
 - lib/pgbus/streams/envelope.rb
 - lib/pgbus/streams/filters.rb
 - lib/pgbus/streams/key.rb
+- lib/pgbus/streams/phlex_helpers.rb
 - lib/pgbus/streams/pool_autoscaler.rb
 - lib/pgbus/streams/pool_trigger.rb
 - lib/pgbus/streams/presence.rb