pgbus 0.6.9 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84c8f674c6aa6d83d0120f586b93f0fc4126ccb5d72378ec04a9b8cb3d464677
-  data.tar.gz: 2544b1be7c34ccf50493ce0af717c3069e979d95ded26197340d8133d637378f
+  metadata.gz: c45dd364f341b6819b7901f583e058dbe761b375210e4162f19faf75917e3043
+  data.tar.gz: ed5ee189a3ff3d7fe0610deada3b2daba3726a2647d7762c58735e0771c9e0eb
 SHA512:
-  metadata.gz: bb329bb54c6eb7da4341eb8050657007d4fe057e862db7b8ef3c6cb0612abff33eaa383d7ea0ce00844dab1a532bd4b45ad3c52618c9ef45b7f9cf9d693ba199
-  data.tar.gz: 8ed028896561f51cb8a904f8e692125e6e61335501fceae366f5cda3f22daf7379b1b83d472df940c4965e2f0b2e00aed30ab90e3227d185e797ee17fb9654b6
+  metadata.gz: e28c032dc7b4f2cba37bd709c4a45030bcedd90274b86a1499d55dd4f4e255769e580983023602a42267b8728068a7eb11f7fdcbc8d12bd3efd83f35a50f241b
+  data.tar.gz: dc6d8d5d2e4feebbf7d940c173f53700549b5364c0e15df3f6afac1d72ecc6b1222127d85649016e9c6590e3c184eb9365da95c424a21a98be683862f4a24e67

data/README.md

@@ -23,6 +23,7 @@ PostgreSQL-native job processing and event bus for Rails, built on [PGMQ](https:
   - [Circuit breaker and queue pause/resume](#circuit-breaker-and-queue-pauseresume)
   - [Prefetch flow control](#prefetch-flow-control)
   - [Worker recycling](#worker-recycling)
+  - [Retry backoff](#retry-backoff)
 - [Routing and ordering](#routing-and-ordering)
   - [Priority queues](#priority-queues)
   - [Consumer priority](#consumer-priority)
@@ -31,6 +32,10 @@ PostgreSQL-native job processing and event bus for Rails, built on [PGMQ](https:
   - [Batches](#batches)
   - [Transactional outbox](#transactional-outbox)
   - [Archive compaction](#archive-compaction)
+- [Observability](#observability)
+  - [Error reporting](#error-reporting)
+  - [Structured logging](#structured-logging)
+  - [Queue health monitoring](#queue-health-monitoring)
 - [Real-time broadcasts](#real-time-broadcasts-turbo-streams-replacement)
 - [Operations](#operations)
   - [CLI](#cli)
@@ -63,6 +68,10 @@ PostgreSQL-native job processing and event bus for Rails, built on [PGMQ](https:
 - **Single active consumer** -- advisory-lock-based exclusive queue processing for strict ordering
 - **Consumer priority** -- higher-priority workers get first dibs, lower-priority workers back off
 - **Job uniqueness** -- prevent duplicate jobs with reaper-based crash recovery, no TTL-driven expiry
+- **Retry backoff** -- exponential backoff with jitter for VT-based retries, per-job overrides
+- **Error reporting** -- pluggable error reporters for APM integration (Appsignal, Sentry, etc.)
+- **Structured logging** -- JSON log formatter with component extraction and thread-local context
+- **Queue health** -- dead tuple monitoring, autovacuum tuning, Prometheus metrics
 
 ## Requirements
 
@@ -463,6 +472,34 @@ end
 
 When a limit is hit, the worker drains its thread pool, exits, and the supervisor forks a fresh process. RSS memory is sampled from `/proc/self/statm` (Linux) or `ps -o rss` (macOS).
 
+### Retry backoff
+
+When a job fails, Pgbus extends the PGMQ visibility timeout with exponential backoff so retries are spread out instead of bunched at fixed intervals:
+
+```ruby
+Pgbus.configure do |config|
+  config.retry_backoff     = 5       # base delay (seconds)
+  config.retry_backoff_max = 300     # cap at 5 minutes
+  config.retry_backoff_jitter = 0.15 # +-15% randomization
+end
+```
+
+The delay formula is `base * 2^(attempt-1) * (1 + random_jitter)`. For a job that fails 4 times with defaults: ~5s, ~10s, ~20s, ~40s before hitting DLQ on the 5th read.
+
+Jobs can override the global settings per-class:
+
+```ruby
+class FragileApiJob < ApplicationJob
+  include Pgbus::RetryBackoff::JobMixin
+
+  pgbus_retry_backoff base: 10, max: 600, jitter: 0.2
+
+  def perform(...)
+    # ...
+  end
+end
+```
+
 ### Async execution mode (fibers)
 
 Workers can optionally execute jobs as fibers instead of threads. This is ideal for I/O-bound workloads (HTTP calls, email delivery, LLM API calls) where jobs spend most of their time waiting on network I/O.
@@ -662,6 +699,96 @@ as configuration. The dispatcher runs archive compaction as part of its
 maintenance loop, deleting archived messages older than `archive_retention`
 in batches to avoid long-running transactions.
 
+## Observability
+
+Error reporting, structured logging, and queue health monitoring.
+
+### Error reporting
+
+By default, Pgbus logs caught exceptions and continues. To route them to your APM service (Appsignal, Sentry, Honeybadger, etc.), push callable reporters onto `config.error_reporters`:
+
+```ruby
+Pgbus.configure do |c|
+  c.error_reporters << ->(ex, ctx) {
+    Appsignal.set_error(ex) { |t| t.set_tags(ctx) }
+  }
+end
+```
+
+Each reporter receives `(exception, context_hash)`. The context hash includes keys like `action`, `queue`, `job_class`, and `msg_id` depending on the call site. Reporters that accept a third argument also receive the Pgbus configuration object.
+
+Reporters are wired into all critical rescue paths: job execution failures, worker fetch/process errors, dispatcher maintenance, supervisor fork failures, circuit breaker trips, outbox publish errors, and failed event recording. Non-critical paths (dashboard queries, stat recording) remain log-only.
+
+`ErrorReporter.report` is guaranteed to never raise — if a reporter or the logger itself throws, the error is swallowed silently. This preserves fault-tolerance invariants at every rescue site.
+
+### Structured logging
+
+Pgbus ships two log formatters inspired by Sidekiq's `Logger::Formatters`:
+
+```ruby
+Pgbus.configure do |c|
+  c.log_format = :json   # or :text (default)
+end
+```
+
+**Text format** (default):
+
+```text
+INFO 2025-01-15T10:30:00.000Z pid=1234 tid=abc queue=default: Starting job
+```
+
+**JSON format**:
+
+```json
+{"ts":"2025-01-15T10:30:00.000Z","pid":1234,"tid":"abc","lvl":"INFO","component":"Pgbus","msg":"Starting job","ctx":{"queue":"default"}}
+```
+
+The JSON formatter extracts `[Pgbus]` and `[Pgbus::Web]` prefixes from log messages into a separate `component` field so the `msg` field stays clean for log aggregators. Thread-local context can be added via `Pgbus::LogFormatter.with_context(queue: "default") { ... }` and appears under the `ctx` key.
+
+You can also set a formatter directly on the logger:
+
+```ruby
+Pgbus.configure do |c|
+  c.logger.formatter = Pgbus::LogFormatter::JSON.new
+end
+```
+
+### Queue health monitoring
+
+The dashboard includes a **Queue Health** panel showing PostgreSQL vacuum stats per PGMQ table: dead tuple counts, live tuple counts, bloat ratio (dead / total), last vacuum age, and MVCC horizon age. The same stats appear on individual queue detail pages.
+
+#### Autovacuum tuning
+
+PGMQ queue tables have high insert/delete churn that overwhelms PostgreSQL's default autovacuum settings. Pgbus applies aggressive per-table tuning automatically:
+
+- **New queues at runtime**: `Client#ensure_single_queue` applies tuning after `pgmq.create()`
+- **Existing installations**: `rails generate pgbus:update` detects untuned tables
+- **Fresh installs**: The install migration includes tuning for the default queue
+
+To apply tuning manually or after `db:schema:load` (which loses `ALTER TABLE` settings):
+
+```bash
+rails generate pgbus:tune_autovacuum                  # Generate migration
+rails generate pgbus:tune_autovacuum --database=pgbus # For separate database
+```
+
+The `pgbus:tune_autovacuum` rake task also hooks into `db:schema:load` automatically.
+
+#### Prometheus metrics
+
+When `config.metrics_enabled = true` (default), the dashboard exposes Prometheus-compatible gauges:
+
+| Metric | Description |
+|--------|-------------|
+| `pgbus_table_dead_tuples` | Dead tuple count per PGMQ table |
+| `pgbus_table_live_tuples` | Live tuple count per PGMQ table |
+| `pgbus_table_bloat_ratio` | Dead / (dead + live) per table |
+| `pgbus_table_last_vacuum_age_seconds` | Seconds since last vacuum per table |
+| `pgbus_oldest_transaction_age_seconds` | MVCC horizon pin risk |
+| `pgbus_worker_pool_capacity` | Total worker thread slots |
+| `pgbus_worker_pool_busy` | Currently busy worker threads |
+| `pgbus_worker_pool_utilization` | Busy / capacity ratio |
+
 ## Real-time broadcasts (turbo-streams replacement)
 
 Pgbus ships a drop-in replacement for turbo-rails' `turbo_stream_from` helper that fixes several well-known ActionCable correctness bugs by using PGMQ message IDs as a replay cursor. Same API as turbo-rails. No Redis. No ActionCable. No lost messages on reconnect.
@@ -751,6 +878,34 @@ One Puma worker (or Falcon reactor) hosts one `Pgbus::Web::Streamer::Instance` s
 
 Per-stream retention is handled by the main pgbus dispatcher process on the same interval as the dispatcher's `ARCHIVE_COMPACTION_INTERVAL` constant. Streams default to a 5-minute retention because SSE clients reconnect within seconds; chat-style applications override the retention to days via `streams_retention`.
 
+### Stream name helpers
+
+Apps using UUID primary keys with turbo-rails-style dom IDs can hit PGMQ's 47-character queue-name ceiling (`"gid://app/Ai::Chat/9c14e8b2-...:messages"` exceeds the limit before the `pgbus_` prefix is even added). Pgbus provides helpers to generate short, collision-safe stream names:
+
+```ruby
+# In your ApplicationRecord
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+  include Pgbus::Streams::Streamable
+end
+```
+
+This gives every model `short_id` (16-hex SHA-256 prefix of the GlobalID) and `to_stream_key`:
+
+```ruby
+chat = Ai::Chat.find("9c14e8b2-...")
+chat.short_id        # => "ai_chat_a3f8c1e9d2b47610"
+chat.to_stream_key   # => "ai_chat_a3f8c1e9d2b47610"
+
+# Compose multi-part stream names
+Pgbus.stream_key(chat, :messages)  # => "ai_chat_a3f8c1e9d2b47610_messages"
+
+# Use in views
+<%= pgbus_stream_from Pgbus.stream_key(@chat, :messages) %>
+```
+
+The budget is computed from `config.queue_prefix` at call time so prefix overrides adjust automatically. If a stream name exceeds the budget, `Pgbus::Streams::StreamNameTooLong` is raised immediately with the offending name, computed budget, and a pointer to `Pgbus.stream_key` — before PGMQ is ever touched.
+
 ### Transactional broadcasts
 
 **This is the feature no other Rails real-time stack can offer.** A broadcast issued inside an open ActiveRecord transaction is deferred until the transaction commits. If it rolls back, the broadcast silently drops — clients never see the change that the database never persisted.
@@ -1001,6 +1156,8 @@ Pgbus uses these tables (created via PGMQ and migrations):
 | `pgbus_outbox_entries` | Transactional outbox entries pending publication |
 | `pgbus_recurring_tasks` | Recurring job definitions |
 | `pgbus_recurring_executions` | Recurring job execution history |
+| `pgbus_presence_members` | Stream presence tracking (who is subscribed) |
+| `pgbus_stream_stats` | Stream broadcast/connect/disconnect metrics (opt-in) |
 
 ### Switching from another backend
 
@@ -1058,6 +1215,9 @@ PostgreSQL + PGMQ
 | `polling_interval` | `0.1` | Seconds between polls (LISTEN/NOTIFY is primary) |
 | `visibility_timeout` | `30` | Time before unacked message becomes visible again. Accepts seconds or `ActiveSupport::Duration` (e.g. `10.minutes`) |
 | `max_retries` | `5` | Failed reads before routing to dead letter queue |
+| `retry_backoff` | `5` | Base delay in seconds for VT-based retry backoff (exponential: `base * 2^(attempt-1)`) |
+| `retry_backoff_max` | `300` | Maximum retry delay in seconds (caps the exponential curve) |
+| `retry_backoff_jitter` | `0.15` | Jitter factor (0-1) added to retry delays to spread retries |
 | `max_jobs_per_worker` | `nil` | Recycle worker after N jobs (nil = unlimited) |
 | `max_memory_mb` | `nil` | Recycle worker when memory exceeds N MB |
 | `max_worker_lifetime` | `nil` | Recycle worker after N seconds. Accepts seconds or Duration. |
@@ -1080,6 +1240,12 @@ PostgreSQL + PGMQ
 | `web_live_updates` | `true` | Enable Turbo Frames auto-refresh on dashboard |
 | `stats_enabled` | `true` | Record job execution stats for insights dashboard |
 | `stats_retention` | `30.days` | How long to keep job stats. Accepts seconds, Duration, or `nil` to disable cleanup |
+| `streams_stats_enabled` | `false` | Record stream broadcast/connect/disconnect stats (opt-in, can be high volume) |
+| `streams_path` | `nil` | Custom URL path for the SSE endpoint (nil = auto-detected from engine mount) |
+| `execution_mode` | `:threads` | Global execution mode (`:threads` or `:async`). Per-worker override via capsule config. |
+| `error_reporters` | `[]` | Array of callables invoked on caught exceptions. Each receives `(exception, context_hash)`. |
+| `log_format` | `:text` | Log formatter (`:text` or `:json`). Sets `logger.formatter` automatically. |
+| `metrics_enabled` | `true` | Enable Prometheus-compatible metrics on the dashboard |
 
 ## Development
 

data/lib/pgbus/active_job/executor.rb

@@ -13,6 +13,10 @@ module Pgbus
         @stat_buffer = stat_buffer
       end
 
+      # Exceptions we never want to swallow — let the process die/signal propagate.
+      FATAL_EXCEPTIONS = [SystemExit, Interrupt, SignalException, NoMemoryError, SystemStackError].freeze
+      private_constant :FATAL_EXCEPTIONS
+
       def execute(message, queue_name, source_queue: nil)
         execution_start = monotonic_now
         payload = JSON.parse(message.message)
@@ -51,18 +55,36 @@ module Pgbus
 
         job_succeeded = false
 
+        # Debug-level phase markers. Silent at INFO+, but invaluable when a
+        # fiber interrupt or connection issue loses control flow between phases
+        # (issue #126). Each line identifies msg_id + phase so the gap is
+        # visible in logs: "deserialized" without "archived" means the job
+        # ran but its message was never archived.
+        msg_id = message.msg_id.to_i
         Instrumentation.instrument("pgbus.executor.execute", queue: queue_name, job_class: job_class) do
+          Pgbus.logger.debug { "[Pgbus] Executor phase=deserialize msg_id=#{msg_id} job=#{job_class}" }
           job = ::ActiveJob::Base.deserialize(payload)
+          Pgbus.logger.debug { "[Pgbus] Executor phase=perform msg_id=#{msg_id} job=#{job_class}" }
           execute_job(job)
-          archive_from(queue_name, message.msg_id.to_i, source_queue: source_queue)
-          FailedEventRecorder.clear!(queue_name: queue_name, msg_id: message.msg_id.to_i)
+          Pgbus.logger.debug { "[Pgbus] Executor phase=archive msg_id=#{msg_id} job=#{job_class}" }
+          archive_from(queue_name, msg_id, source_queue: source_queue)
+          FailedEventRecorder.clear!(queue_name: queue_name, msg_id: msg_id)
           job_succeeded = true
+          Pgbus.logger.debug { "[Pgbus] Executor phase=succeeded msg_id=#{msg_id} job=#{job_class}" }
         end
 
         instrument("pgbus.job_completed", queue: queue_name, job_class: job_class)
         record_stat(payload, queue_name, "success", execution_start, message: message)
         :success
-      rescue StandardError => e
+      rescue *FATAL_EXCEPTIONS
+        # Process-fatal: propagate so the supervisor/OS can react.
+        raise
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        # Widened from StandardError to catch Async::Stop / Async::Cancel
+        # (both inherit from Exception, not StandardError) under execution_mode: :async.
+        # Before this, a fiber interruption between perform_now and archive_from
+        # silently lost control flow — no failed event row, no job_failed
+        # notification, uniqueness lock held until VT expired. See issue #126.
         handle_failure(message, queue_name, e, payload: payload)
         instrument("pgbus.job_failed", queue: queue_name, job_class: payload&.dig("job_class"), error: e.class.name)
         record_stat(payload, queue_name, "failed", execution_start, message: message)
@@ -146,7 +168,9 @@ module Pgbus
       end
 
       def handle_failure(message, queue_name, error, payload: nil)
-        Pgbus.logger.error { "[Pgbus] Job failed: #{error.class}: #{error.message}" }
+        ctx = { action: "execute_job", queue: queue_name, job_class: payload&.dig("job_class"),
+                msg_id: message.msg_id.to_i, read_ct: message.read_ct.to_i }
+        ErrorReporter.report(error, ctx)
         Pgbus.logger.debug { error.backtrace&.join("\n") }
 
         # Record failure for dashboard visibility.

data/lib/pgbus/circuit_breaker.rb

@@ -92,7 +92,7 @@ module Pgbus
       @failure_counts.delete(queue_name)
       invalidate_cache(queue_name)
     rescue StandardError => e
-      Pgbus.logger.error { "[Pgbus] Circuit breaker trip failed for #{queue_name}: #{e.message}" }
+      ErrorReporter.report(e, { action: "circuit_breaker_trip", queue: queue_name })
     end
 
     def check_paused(queue_name)

data/lib/pgbus/client/ensure_stream_queue.rb

@@ -27,7 +27,9 @@ module Pgbus
         # sensitive and need every broadcast to fire a NOTIFY, even
         # when several are batched within a single millisecond.
         # Override the throttle to 0 specifically for stream queues.
-        synchronized { @pgmq.enable_notify_insert(full_name, throttle_interval_ms: 0) } if config.listen_notify
+        # Use the idempotent path to avoid deadlocks when multiple
+        # processes race to set up the same stream queue.
+        synchronized { enable_notify_if_needed(full_name, 0) }
 
         # CREATE INDEX IF NOT EXISTS is idempotent in Postgres but still
         # requires a roundtrip and a brief ACCESS SHARE lock on the archive

data/lib/pgbus/client.rb

@@ -156,10 +156,17 @@ module Pgbus
     # Read from multiple queues in a single SQL query (UNION ALL).
     # Each returned message includes a queue_name field identifying its source.
     # queue_names should be logical names (prefix is added automatically).
-    def read_multi(queue_names, qty:, vt: nil)
+    #
+    # `qty` is the per-queue cap (pgmq-ruby semantics), so without `limit:` the
+    # caller receives up to `queue_count * qty` messages. Pass `limit:` to cap
+    # the total across all queues — required when feeding a fixed-size pool,
+    # otherwise the pool can overflow on multi-queue reads (issue #123).
+    def read_multi(queue_names, qty:, vt: nil, limit: nil)
       full_names = queue_names.map { |q| config.queue_name(q) }
-      Instrumentation.instrument("pgbus.client.read_multi", queues: full_names, qty: qty) do
-        synchronized { @pgmq.read_multi(full_names, vt: vt || config.visibility_timeout, qty: qty) }
+      Instrumentation.instrument("pgbus.client.read_multi", queues: full_names, qty: qty, limit: limit) do
+        synchronized do
+          @pgmq.read_multi(full_names, vt: vt || config.visibility_timeout, qty: qty, limit: limit)
+        end
       end
     end
 
@@ -450,12 +457,48 @@ module Pgbus
         synchronized do
           @pgmq.create(full_name)
           tune_autovacuum(full_name)
-          @pgmq.enable_notify_insert(full_name, throttle_interval_ms: NOTIFY_THROTTLE_MS) if config.listen_notify
+          enable_notify_if_needed(full_name, NOTIFY_THROTTLE_MS)
         end
         true
       end
     end
 
+    def enable_notify_if_needed(full_name, throttle_ms)
+      return unless config.listen_notify
+      return if notify_trigger_current?(full_name, throttle_ms)
+
+      @pgmq.enable_notify_insert(full_name, throttle_interval_ms: throttle_ms)
+    end
+
+    # Check whether the NOTIFY trigger already exists on this queue with the
+    # expected throttle interval. When it does, we can skip the destructive
+    # DROP TRIGGER + CREATE TRIGGER cycle that causes deadlocks when multiple
+    # forked processes race during bootstrap.
+    def notify_trigger_current?(full_name, throttle_ms)
+      with_raw_connection do |conn|
+        result = conn.exec_params(<<~SQL, [full_name, throttle_ms])
+          SELECT 1
+          FROM pg_trigger t
+          JOIN pg_class c ON t.tgrelid = c.oid
+          JOIN pg_namespace n ON c.relnamespace = n.oid
+          WHERE n.nspname = 'pgmq'
+            AND c.relname = pgmq.format_table_name($1, 'q')
+            AND t.tgname = 'trigger_notify_queue_insert_listeners'
+            AND EXISTS (
+              SELECT 1 FROM pgmq.notify_insert_throttle
+              WHERE queue_name = $1
+                AND throttle_interval_ms = $2
+            )
+          LIMIT 1
+        SQL
+        result.ntuples.positive?
+      end
+    rescue StandardError
+      # If we can't check (e.g. pgmq schema not fully ready), fall back to
+      # the unconditional path — same behavior as before this fix.
+      false
+    end
+
     def tune_autovacuum(queue_name)
       with_raw_connection do |conn|
         conn.exec(AutovacuumTuning.sql_for_queue(queue_name))

data/lib/pgbus/configuration.rb

@@ -59,6 +59,11 @@ module Pgbus
 
     # Logging
     attr_accessor :logger
+    attr_reader :log_format # rubocop:disable Style/AccessorGrouping
+
+    # Error reporting — array of callable objects invoked on caught exceptions.
+    # Each receives (exception, context_hash) or (exception, context_hash, config).
+    attr_accessor :error_reporters
 
     # LISTEN/NOTIFY. Only the on/off switch is user-facing — the throttle
     # interval is a Postgres-side tuning knob that lives as a constant on
@@ -140,6 +145,8 @@ module Pgbus
       @allowed_global_id_models = nil # nil = allow all (for backwards compat)
 
       @logger = (defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger) || Logger.new($stdout)
+      @log_format = :text
+      @error_reporters = []
 
       @listen_notify = true
 
@@ -224,6 +231,21 @@ module Pgbus
       ExecutionPools.normalize_mode(mode)
     end
 
+    VALID_LOG_FORMATS = %i[text json].freeze
+
+    def log_format=(format)
+      format = format.to_sym
+      unless VALID_LOG_FORMATS.include?(format)
+        raise ArgumentError, "Invalid log_format: #{format}. Must be one of: #{VALID_LOG_FORMATS.join(", ")}"
+      end
+
+      @log_format = format
+      @logger.formatter = case format
+                          when :json then LogFormatter::JSON.new
+                          when :text then LogFormatter::Text.new
+                          end
+    end
+
     VALID_PGMQ_SCHEMA_MODES = %i[auto extension embedded].freeze
 
     def pgmq_schema_mode=(mode)

data/lib/pgbus/error_reporter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # Central error reporting module. Iterates all configured error reporters
+  # and logs the error. Inspired by Sidekiq's error_handlers pattern.
+  #
+  # Usage:
+  #   Pgbus::ErrorReporter.report(exception, { queue: "default" })
+  #
+  # Configuration:
+  #   Pgbus.configure do |c|
+  #     c.error_reporters << ->(ex, ctx) { Appsignal.set_error(ex) { |t| t.set_tags(ctx) } }
+  #   end
+  module ErrorReporter
+    module_function
+
+    def report(exception, context = {}, config: Pgbus.configuration)
+      log_error(exception, context, config: config)
+
+      config.error_reporters.each do |handler|
+        call_handler(handler, exception, context, config)
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        config.logger.error { "[Pgbus] Error reporter raised: #{e.class}: #{e.message}" }
+      end
+    rescue Exception # rubocop:disable Lint/RescueException
+      # ErrorReporter must never raise — callers sit inside rescue blocks
+      # where an unexpected raise would break fault-tolerance invariants.
+      nil
+    end
+
+    def call_handler(handler, exception, context, config)
+      target = handler.is_a?(Proc) ? handler : handler.method(:call)
+      if target.arity == 3 || (target.arity.negative? && target.parameters.size >= 3)
+        handler.call(exception, context, config)
+      else
+        handler.call(exception, context)
+      end
+    end
+
+    def log_error(exception, context, config:)
+      config.logger.error do
+        msg = "[Pgbus] #{exception.class}: #{exception.message}"
+        msg += " (#{context.inspect})" unless context.empty?
+        msg
+      end
+    end
+  end
+end

data/lib/pgbus/execution_pools/async_pool.rb

@@ -128,9 +128,20 @@ module Pgbus
         nil
       end
 
+      # Supervisor-level rescue: catch any Exception raised from the user
+      # block so capacity is always restored and the failure is logged.
+      # The `async` gem uses Async::Stop / Async::Cancel (Exception subclasses,
+      # NOT StandardError) to cancel tasks, and prior to issue #126 those
+      # would leak past `rescue StandardError` and silently vanish.
+      # Process-fatal signals still propagate so the supervisor can react.
+      FATAL_EXCEPTIONS = [SystemExit, Interrupt, SignalException, NoMemoryError, SystemStackError].freeze
+      private_constant :FATAL_EXCEPTIONS
+
       def perform(block)
         block.call
-      rescue StandardError => e
+      rescue *FATAL_EXCEPTIONS
+        raise
+      rescue Exception => e # rubocop:disable Lint/RescueException
         Pgbus.logger.error { "[Pgbus] Async pool fiber error: #{e.class}: #{e.message}" }
       ensure
         restore_capacity

data/lib/pgbus/failed_event_recorder.rb

@@ -32,14 +32,7 @@ module Pgbus
           ]
         )
       rescue StandardError => e
-        # ERROR-level: silent loss of failure-tracking data defeats the
-        # purpose of the dashboard's "Failed Jobs" section. If recording
-        # fails, surface it loudly so the broken state can be diagnosed
-        # rather than silently masked.
-        Pgbus.logger.error do
-          "[Pgbus] Failed to record failed event for queue=#{queue_name} msg_id=#{msg_id}: " \
-            "#{e.class}: #{e.message}"
-        end
+        ErrorReporter.report(e, { action: "record_failed_event", queue: queue_name, msg_id: msg_id })
       end
 
       def clear!(queue_name:, msg_id:)

data/lib/pgbus/log_formatter.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "json"
+require "logger"
+require "time"
+
+module Pgbus
+  # Log formatters for Pgbus, inspired by Sidekiq::Logger::Formatters.
+  #
+  # Usage:
+  #   Pgbus.configure do |c|
+  #     c.logger.formatter = Pgbus::LogFormatter::JSON.new
+  #   end
+  #
+  # Or via the convenience config option:
+  #   Pgbus.configure do |c|
+  #     c.log_format = :json
+  #   end
+  module LogFormatter
+    module_function
+
+    def tid
+      Thread.current[:pgbus_tid] ||= (Thread.current.object_id ^ ::Process.pid).to_s(36)
+    end
+
+    # Thread-local context for structured logging. Works like
+    # Sidekiq::Context — any key/value pairs set via with_context
+    # appear in the JSON output under the "ctx" key.
+    def with_context(hash)
+      orig = current_context.dup
+      current_context.merge!(hash)
+      yield
+    ensure
+      Thread.current[:pgbus_log_context] = orig
+    end
+
+    def current_context
+      Thread.current[:pgbus_log_context] ||= {}
+    end
+
+    # Human-readable text formatter with Pgbus context.
+    # Output: "INFO 2024-01-15T10:30:00.000Z pid=1234 tid=abc queue=default: message\n"
+    class Text < ::Logger::Formatter
+      def call(severity, time, _progname, message)
+        "#{severity} #{time.utc.iso8601(3)} pid=#{::Process.pid} tid=#{LogFormatter.tid}#{format_context}: #{message}\n"
+      end
+
+      private
+
+      def format_context
+        ctx = LogFormatter.current_context
+        return "" if ctx.empty?
+
+        " #{ctx.map { |k, v| "#{k}=#{v}" }.join(" ")}"
+      end
+    end
+
+    # JSON formatter for structured logging. Each log line is a single
+    # JSON object followed by a newline. Extracts the [Pgbus::Component]
+    # prefix from messages into a separate "component" field.
+    #
+    # Output fields:
+    #   ts  — ISO 8601 timestamp with milliseconds
+    #   pid — process ID
+    #   tid — thread ID (short hex)
+    #   lvl — severity (DEBUG/INFO/WARN/ERROR/FATAL)
+    #   msg — the log message (with component prefix stripped)
+    #   component — extracted from [Pgbus] or [Pgbus::Foo] prefix (optional)
+    #   ctx — thread-local context hash (optional, only when non-empty)
+    class JSON < ::Logger::Formatter
+      COMPONENT_PREFIX = /\A\[([^\]]+)\]\s*/
+
+      def call(severity, time, _progname, message)
+        msg = message.to_s
+        hash = {
+          ts: time.utc.iso8601(3),
+          pid: ::Process.pid,
+          tid: LogFormatter.tid,
+          lvl: severity
+        }
+
+        if (match = msg.match(COMPONENT_PREFIX))
+          hash[:component] = match[1]
+          msg = msg.sub(COMPONENT_PREFIX, "")
+        end
+
+        hash[:msg] = msg
+
+        ctx = LogFormatter.current_context
+        hash[:ctx] = ctx unless ctx.empty?
+
+        "#{::JSON.generate(hash)}\n"
+      end
+    end
+  end
+end

data/lib/pgbus/outbox/poller.rb

@@ -65,7 +65,7 @@ module Pgbus
         Pgbus.logger.debug { "[Pgbus] Outbox published #{published} entries" } if published.positive?
         published
       rescue StandardError => e
-        Pgbus.logger.error { "[Pgbus] Outbox poll error: #{e.message}" }
+        ErrorReporter.report(e, { action: "outbox_poll" })
         0
       end
 
@@ -92,7 +92,7 @@ module Pgbus
         entry.update!(published_at: Time.current)
         true
       rescue StandardError => e
-        Pgbus.logger.error { "[Pgbus] Failed to publish outbox entry #{entry.id}: #{e.message}" }
+        ErrorReporter.report(e, { action: "outbox_publish_topic", entry_id: entry.id })
         false
       end
 
@@ -112,7 +112,7 @@ module Pgbus
           group.each { |e| e.update!(published_at: now) }
           succeeded += group.size
         rescue StandardError => e
-          Pgbus.logger.error { "[Pgbus] Failed to batch-publish #{group.size} outbox entries: #{e.message}" }
+          ErrorReporter.report(e, { action: "outbox_batch_publish", queue: queue, batch_size: group.size })
           # Fall back to individual publishing for this group
           group.each { |entry| succeeded += 1 if publish_single_queue(entry) }
         end
@@ -133,7 +133,7 @@ module Pgbus
         entry.update!(published_at: Time.current)
         true
       rescue StandardError => e
-        Pgbus.logger.error { "[Pgbus] Failed to publish outbox entry #{entry.id}: #{e.message}" }
+        ErrorReporter.report(e, { action: "outbox_publish_queue", entry_id: entry.id })
         false
       end
 

data/lib/pgbus/process/consumer.rb

@@ -98,8 +98,12 @@ module Pgbus
         # the next read will route to DLQ above.
       end
 
+      # `qty` is the total pool capacity. pgmq-ruby treats `qty:` as per-queue,
+      # so we also pass `limit: qty` to cap the total across all queues —
+      # otherwise we get `queue_count * qty` messages and overflow the
+      # execution pool, crashing the consumer fork (issue #123).
       def fetch_multi_consumer(qty)
-        messages = Pgbus.client.read_multi(@queue_names, qty: qty) || []
+        messages = Pgbus.client.read_multi(@queue_names, qty: qty, limit: qty) || []
         prefix = "#{config.queue_prefix}_"
 
         messages.map do |m|

data/lib/pgbus/process/dispatcher.rb

@@ -94,7 +94,7 @@ module Pgbus
         yield
         instance_variable_set(ivar, now)
       rescue StandardError => e
-        Pgbus.logger.error { "[Pgbus] Dispatcher maintenance error: #{e.message}" }
+        ErrorReporter.report(e, { action: "dispatcher_maintenance", task: ivar.to_s.delete_prefix("@last_").delete_suffix("_at") })
       end
 
       def cleanup_processed_events

data/lib/pgbus/process/supervisor.rb

@@ -21,6 +21,14 @@ module Pgbus
 
         Pgbus.logger.info { "[Pgbus] Supervisor starting pid=#{::Process.pid}" }
 
+        # Bootstrap queues once in the parent process before forking children.
+        # This avoids the deadlock that occurs when multiple forked children
+        # race to call enable_notify_insert (DROP TRIGGER + CREATE TRIGGER)
+        # concurrently on the same queue tables. Children still call
+        # bootstrap_queues post-fork but the idempotent check in
+        # notify_trigger_current? makes those calls cheap no-ops.
+        bootstrap_queues
+
         boot_processes
         monitor_loop
       ensure
@@ -83,7 +91,7 @@ module Pgbus
         @forks[pid] = { type: :worker, config: worker_config }
         Pgbus.logger.info { "[Pgbus] Forked worker pid=#{pid} queues=#{queues.join(",")} mode=#{exec_mode}" }
       rescue Errno::EAGAIN, Errno::ENOMEM => e
-        Pgbus.logger.error { "[Pgbus] Fork failed for worker: #{e.message}" }
+        ErrorReporter.report(e, { action: "fork_worker", queues: queues })
       end
 
       def fork_dispatcher
@@ -103,7 +111,7 @@ module Pgbus
         @forks[pid] = { type: :dispatcher }
         Pgbus.logger.info { "[Pgbus] Forked dispatcher pid=#{pid}" }
       rescue Errno::EAGAIN, Errno::ENOMEM => e
-        Pgbus.logger.error { "[Pgbus] Fork failed for dispatcher: #{e.message}" }
+        ErrorReporter.report(e, { action: "fork_dispatcher" })
       end
 
       def boot_scheduler
@@ -132,7 +140,7 @@ module Pgbus
         @forks[pid] = { type: :scheduler }
         Pgbus.logger.info { "[Pgbus] Forked scheduler pid=#{pid}" }
       rescue Errno::EAGAIN, Errno::ENOMEM => e
-        Pgbus.logger.error { "[Pgbus] Fork failed for scheduler: #{e.message}" }
+        ErrorReporter.report(e, { action: "fork_scheduler" })
       end
 
       def recurring_tasks_configured?
@@ -186,7 +194,7 @@ module Pgbus
         @forks[pid] = { type: :consumer, config: consumer_config }
         Pgbus.logger.info { "[Pgbus] Forked consumer pid=#{pid} topics=#{topics.join(",")}" }
       rescue Errno::EAGAIN, Errno::ENOMEM => e
-        Pgbus.logger.error { "[Pgbus] Fork failed for consumer: #{e.message}" }
+        ErrorReporter.report(e, { action: "fork_consumer", topics: topics })
       end
 
       def boot_outbox_poller
@@ -212,7 +220,7 @@ module Pgbus
         @forks[pid] = { type: :outbox_poller }
         Pgbus.logger.info { "[Pgbus] Forked outbox poller pid=#{pid}" }
       rescue Errno::EAGAIN, Errno::ENOMEM => e
-        Pgbus.logger.error { "[Pgbus] Fork failed for outbox poller: #{e.message}" }
+        ErrorReporter.report(e, { action: "fork_outbox_poller" })
       end
 
       def monitor_loop
@@ -282,7 +290,7 @@ module Pgbus
       def bootstrap_queues
         Pgbus.client.ensure_all_queues
       rescue StandardError => e
-        Pgbus.logger.error { "[Pgbus] Failed to bootstrap queues: #{e.message}" }
+        ErrorReporter.report(e, { action: "bootstrap_queues" })
       end
 
       def load_rails_app

data/lib/pgbus/process/worker.rb

@@ -151,7 +151,7 @@ module Pgbus
         if undefined_queue_table_error?(e)
           evict_missing_queues(e)
         else
-          Pgbus.logger.error { "[Pgbus] Error fetching messages: #{e.message}" }
+          ErrorReporter.report(e, { action: "fetch_messages", queues: active_queues })
         end
         []
       end
@@ -194,8 +194,13 @@ module Pgbus
       # Use pgmq-ruby's read_multi to read from all queues in a single
       # SQL query (UNION ALL). Each returned message carries a queue_name
       # field so we can map it back to the logical queue.
+      #
+      # `qty` is the total pool capacity. pgmq-ruby treats `qty:` as per-queue,
+      # so we also pass `limit: qty` to cap the total across all queues —
+      # otherwise we get `queue_count * qty` messages and overflow the
+      # execution pool, crashing the worker fork (issue #123).
       def fetch_multi(active_queues, qty)
-        messages = Pgbus.client.read_multi(active_queues, qty: qty) || []
+        messages = Pgbus.client.read_multi(active_queues, qty: qty, limit: qty) || []
         prefix = "#{config.queue_prefix}_"
 
         messages.map do |m|
@@ -223,7 +228,7 @@ module Pgbus
         @jobs_failed.increment
         @rate_counter.increment(:failed)
         @circuit_breaker.record_failure(queue_name)
-        Pgbus.logger.error { "[Pgbus] Unhandled error processing message: #{e.message}" }
+        ErrorReporter.report(e, { action: "process_message", queue: queue_name })
       ensure
         @in_flight.decrement
       end

data/lib/pgbus/queue_name_validator.rb

@@ -7,9 +7,21 @@ module Pgbus
   # (e.g., pgmq.q_<name>, pgmq.a_<name>). This module enforces strict
   # validation to prevent SQL injection via crafted queue names.
   module QueueNameValidator
-    # PostgreSQL identifier limit is 63 bytes (NAMEDATALEN - 1).
-    # PGMQ prefixes with "q_" or "a_" (2 chars), so limit the name itself.
-    MAX_QUEUE_NAME_LENGTH = 61
+    # PostgreSQL's NAMEDATALEN caps identifiers at 63 bytes, but the
+    # effective limit is tighter: pgmq-ruby (our transport gem) rejects
+    # any queue name with `length >= 48` in `PGMQ::Client#validate_queue_name!`.
+    # That leaves an actual usable ceiling of 47 characters for the
+    # fully-prefixed name (`<queue_prefix>_<logical_name>`), which is what
+    # this constant expresses. pgmq-ruby picked 48 to leave headroom for
+    # PGMQ's internal tables (`pgmq.q_`, `pgmq.a_`, sequences, indexes)
+    # which all get suffixed beyond the base name.
+    #
+    # Historically this was 61 (the raw PostgreSQL ceiling minus PGMQ's
+    # `q_`/`a_` prefix). That was wrong in practice: names in the 48-61
+    # range passed pgbus's validator but blew up deep inside pgmq-ruby
+    # with an InvalidQueueNameError — exactly the kind of opaque failure
+    # the validator was meant to catch up front.
+    MAX_QUEUE_NAME_LENGTH = 47
 
     # Only alphanumeric characters and underscores are allowed.
     VALID_QUEUE_NAME_PATTERN = /\A[a-zA-Z0-9_]+\z/
@@ -34,16 +46,23 @@ module Pgbus
       name
     end
 
-    # Normalizes a queue name by replacing common separators (hyphens, dots)
-    # with underscores, stripping remaining invalid characters, and collapsing
-    # consecutive underscores. Use this for names from external sources
-    # (e.g., Turbo stream names like "hotwire-livereload") where the intent
-    # is to derive a valid PGMQ queue name that preserves readability.
+    # Normalizes a queue name by replacing common separators (hyphens,
+    # dots, colons) with underscores, stripping remaining invalid
+    # characters, and collapsing consecutive underscores. Use this for
+    # names from external sources (e.g., Turbo stream names like
+    # "hotwire-livereload" or "gid://app/Foo/1") where the intent is
+    # to derive a valid PGMQ queue name that preserves as much of the
+    # original identifier as possible.
+    #
+    # Colons in particular are the turbo-rails stream-name separator
+    # (`Pgbus.stream([user, :notifications])` → `"user_gid:notifications"`),
+    # so they must map to a safe character rather than be stripped —
+    # otherwise `"a:b"` and `"ab"` would collide on the same queue.
     def normalize(name)
       name = name.to_s
       return validate!(name) if VALID_QUEUE_NAME_PATTERN.match?(name)
 
-      normalized = name.gsub(/[-.]/, "_")           # hyphens/dots → underscores
+      normalized = name.gsub(/[-.:]/, "_")          # hyphens/dots/colons → underscores
                        .gsub(/[^a-zA-Z0-9_]/, "")   # strip remaining invalid chars
                        .gsub(/_+/, "_")              # collapse consecutive underscores
                        .gsub(/\A_|_\z/, "")          # strip leading/trailing underscores

data/lib/pgbus/streams/key.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Pgbus
+  module Streams
+    # Short, pgbus-safe stream identifiers.
+    #
+    # PGMQ queue names are bounded by two ceilings: PostgreSQL's
+    # NAMEDATALEN (63 chars for `pgmq.q_<name>`) and pgmq-ruby's own
+    # stricter runtime check (`length >= 48` in
+    # `PGMQ::Client#validate_queue_name!`). The effective budget is the
+    # lower of the two, exposed as `QueueNameValidator::MAX_QUEUE_NAME_LENGTH`
+    # (currently 47). Any stream name composed from UUID primary keys
+    # and turbo-rails-style dom ids blows past that budget almost
+    # immediately:
+    #
+    #     "gid://app/Ai::Chat/9c14e8b2-94c3-4c6f-8ca1-f50d2f5e22ca:messages"
+    #     # => 63 chars, already too long before the "pgbus_" prefix is added.
+    #
+    # `stream_key` produces a deterministic short form suitable as a
+    # pgbus stream identifier. It normalizes each part, joins with ":",
+    # and enforces the queue-name budget (derived from the configured
+    # `queue_prefix`) at the call site — raising ArgumentError rather
+    # than letting the failure surface as an opaque QueueNameValidator
+    # error deep inside `Pgbus.stream(...).broadcast(...)`.
+    #
+    # Silent truncation is intentionally NOT supported: trimming a
+    # too-long key to fit would reintroduce the collision risk that the
+    # 64-bit digest is chosen to eliminate. Callers who overflow should
+    # shorten their own identifiers or adopt `Pgbus::Streams::Streamable`
+    # on their ActiveRecord models.
+    #
+    # Usage:
+    #
+    #     Pgbus.stream_key(chat, :messages)
+    #       # => "ai_chat_3a4f9c21b7d20e18:messages"
+    #
+    #     Pgbus.stream_key([user, :notifications])
+    #       # => "user_5fa83c91d44a2701:notifications"
+    #
+    #     Pgbus.stream(Pgbus.stream_key(chat, :messages)).broadcast("<turbo-stream/>")
+    #
+    # Collision horizon: the 64-bit SHA-256 prefix gives a birthday bound
+    # of roughly 5 billion records per model class before a 50% chance of
+    # collision. For multi-tenant apps where a collision would mean two
+    # records share a stream (and receive each other's broadcasts), this
+    # is wide enough in practice. Callers with higher sensitivity can
+    # pass `digest_bits: 128`.
+    module Key
+      DEFAULT_DIGEST_BITS = 64
+
+      module_function
+
+      # Compose a short pgbus-safe stream name from any mix of records,
+      # strings, symbols, and arrays. Returns the joined key when it fits
+      # the pgbus queue-name budget; raises ArgumentError otherwise.
+      #
+      # Fragments must not contain `:` — it's the join separator, so
+      # `stream_key("a:b", :c)` and `stream_key("a", "b:c")` would both
+      # produce `"a:b:c"` and collapse two logically distinct streams
+      # onto one queue. Colons inside fragments (typically from a
+      # `to_stream_key`/`to_gid_param` implementation that forgot to
+      # sanitize) raise an ArgumentError at the call site.
+      def stream_key(*parts, digest_bits: DEFAULT_DIGEST_BITS)
+        fragments = Array(parts).flatten.map { |part| normalize(part, digest_bits: digest_bits) }
+        fragments.each { |fragment| reject_colons!(fragment) }
+        key = fragments.join(":")
+        budget = queue_name_budget
+        return key if key.length <= budget
+
+        raise ArgumentError,
+              "stream_key #{key.inspect} is #{key.length} chars, " \
+              "exceeds pgbus budget of #{budget} " \
+              "(queue_prefix=#{Pgbus.configuration.queue_prefix.inspect}, " \
+              "pgbus_max_queue_name_length=#{QueueNameValidator::MAX_QUEUE_NAME_LENGTH}). " \
+              "Shorten the streamables or use Pgbus::Streams::Streamable on the model."
+      end
+
+      # 64-bit (default) SHA-256 prefix of the record's primary key. Stdlib
+      # only, deterministic, and fixed-length. CRC32's 32-bit output is
+      # intentionally not used here: its ~77k-row birthday bound is too
+      # tight for a multi-tenant stream identifier where a collision would
+      # route two records' broadcasts to the same queue.
+      # Full output size of the backing digest, in bits. Capping
+      # digest_bits here matters because `SHA256.hexdigest` only
+      # produces 64 hex chars (256 bits) no matter what — slicing
+      # `[0, 128]` just returns all 64 chars — so a caller asking for
+      # `digest_bits: 512` would silently get the same output as
+      # `digest_bits: 256` and walk away believing they'd widened the
+      # collision horizon. Raise instead.
+      MAX_DIGEST_BITS = ::Digest::SHA256.new.digest_length * 8 # => 256
+
+      def short_id(record, digest_bits: DEFAULT_DIGEST_BITS)
+        unless digest_bits.is_a?(Integer) && digest_bits.positive? &&
+               (digest_bits % 4).zero? && digest_bits <= MAX_DIGEST_BITS
+          raise ArgumentError,
+                "digest_bits must be a positive multiple of 4 and <= #{MAX_DIGEST_BITS} " \
+                "(SHA-256 produces #{MAX_DIGEST_BITS} bits; asking for more would silently truncate)"
+        end
+
+        # Unpersisted records all share id=nil, which hashes to a single
+        # constant digest and would collapse every new instance of the
+        # same class into one stream. Fail loud at the first unsaved
+        # call site — the whole point of the 64-bit digest is to
+        # eliminate collisions, so silently producing a shared key here
+        # would reintroduce exactly what it was chosen to prevent.
+        if record.id.nil?
+          raise ArgumentError,
+                "#{record.class.name} must be persisted before generating a stream key " \
+                "(record.id is nil — all unsaved records would collide on one stream)"
+        end
+
+        hex_chars = digest_bits / 4
+        ::Digest::SHA256.hexdigest(record.id.to_s)[0, hex_chars]
+      end
+
+      # Normalize a single streamable fragment to a pgbus-safe string.
+      # Mirrors the shape accepted by Turbo::Streams::StreamName and
+      # Pgbus::Streams::Stream.name_from so the two code paths agree
+      # on the wire format.
+      #
+      # - Strings and symbols pass through verbatim.
+      # - ActiveRecord models become "<param_key>_<short_id>".
+      # - Anything else responding to `to_gid_param` / `to_param` falls
+      #   back to that; a UUID primary key would still overflow, which
+      #   is why AR models are hashed above.
+      def normalize(part, digest_bits: DEFAULT_DIGEST_BITS)
+        case part
+        when String, Symbol
+          part.to_s
+        else
+          if defined?(::ActiveRecord::Base) && part.is_a?(::ActiveRecord::Base)
+            "#{part.class.model_name.param_key}_#{short_id(part, digest_bits: digest_bits)}"
+          elsif part.respond_to?(:to_stream_key)
+            part.to_stream_key
+          elsif part.respond_to?(:to_gid_param)
+            part.to_gid_param
+          elsif part.respond_to?(:to_param)
+            part.to_param
+          else
+            part.to_s
+          end
+        end
+      end
+
+      # Budget = effective pgbus queue-name limit - "<queue_prefix>_"
+      # length. Computed at call time (not a constant) so apps that
+      # override `config.queue_prefix` get the correct budget
+      # automatically.
+      def queue_name_budget
+        QueueNameValidator::MAX_QUEUE_NAME_LENGTH -
+          Pgbus.configuration.queue_prefix.length - 1
+      end
+
+      # Raises if a normalized fragment contains the `:` separator.
+      # Kept private-ish via module_function so the guard is shared
+      # between stream_key and any future composer without becoming
+      # part of the public surface.
+      def reject_colons!(fragment)
+        return unless fragment.include?(":")
+
+        raise ArgumentError,
+              "stream_key fragment #{fragment.inspect} contains ':' which is the " \
+              "join separator — two calls with different colon placements would " \
+              "collapse to the same key (e.g. stream_key('a:b', :c) vs " \
+              "stream_key('a', 'b:c') both produce 'a:b:c'). Strip or replace " \
+              "colons in the offending streamable before calling stream_key."
+      end
+      private_class_method :reject_colons!
+    end
+  end
+end

data/lib/pgbus/streams/streamable.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Streams
+    # ActiveRecord concern that adds `short_id` and `to_stream_key`
+    # instance methods for producing pgbus-safe stream identifiers from
+    # records whose primary key is a UUID (or any other long string).
+    #
+    # Intended for inclusion in `ApplicationRecord`:
+    #
+    #     class ApplicationRecord < ActiveRecord::Base
+    #       primary_abstract_class
+    #       include Pgbus::Streams::Streamable
+    #     end
+    #
+    # Every subclass then gets:
+    #
+    #     chat.short_id
+    #     # => "3a4f9c21b7d20e18"
+    #
+    #     chat.to_stream_key
+    #     # => "ai_chat_3a4f9c21b7d20e18"
+    #
+    #     Pgbus.stream_key(chat, :messages)
+    #     # => "ai_chat_3a4f9c21b7d20e18:messages"
+    #
+    # The mixin is intentionally thin: it delegates to `Pgbus::Streams::Key`
+    # so the digest policy lives in one place.
+    #
+    # `#to_stream_key` calls `Key.short_id(self)` directly rather than
+    # dispatching through `#short_id`. Ruby does NOT warn when a class
+    # defines an instance method and a later `include` adds a module
+    # with the same name — the class method silently wins. A host app
+    # that already defines its own `#short_id` (returning, say, a
+    # display-friendly abbreviation) would therefore hijack
+    # `to_stream_key` without any indication, producing stream keys
+    # the wire format never promised. Calling `Key.short_id(self)`
+    # explicitly bypasses instance-method lookup and guarantees the
+    # advertised digest regardless of what the host class does with
+    # the unqualified name.
+    module Streamable
+      # Returns a short SHA-256 prefix (64 bits / 16 hex chars by default)
+      # of this record's primary key. See `Pgbus::Streams::Key.short_id`
+      # for the digest policy and collision horizon.
+      def short_id(digest_bits: Key::DEFAULT_DIGEST_BITS)
+        Key.short_id(self, digest_bits: digest_bits)
+      end
+
+      # Returns a stable, pgbus-safe identifier of the form
+      # `<model_key>_<short_id>` suitable for passing directly to
+      # `Pgbus.stream(...)` or composing with `Pgbus.stream_key`.
+      def to_stream_key
+        "#{self.class.model_name.param_key}_#{Key.short_id(self)}"
+      end
+    end
+  end
+end

data/lib/pgbus/streams.rb

@@ -6,6 +6,15 @@ module Pgbus
   # which returns a `Pgbus::Streams::Stream` providing `#broadcast`,
   # `#current_msg_id`, and `#read_after`.
   module Streams
+    # Raised when a composed stream name would overflow PGMQ's queue-name
+    # budget (derived from PostgreSQL's NAMEDATALEN=64, minus PGMQ's `q_`
+    # table prefix, minus the configured queue_prefix + separator).
+    #
+    # Inherits from ArgumentError so existing rescues of the underlying
+    # QueueNameValidator error keep working; callers that want to handle
+    # this specifically can rescue Pgbus::Streams::StreamNameTooLong.
+    class StreamNameTooLong < ArgumentError; end
+
     # Process-wide registry of server-side audience filter predicates.
     # Register filters at boot time via:
     #   Pgbus::Streams.filters.register(:admin_only) { |user| user.admin? }
@@ -30,6 +39,7 @@ module Pgbus
 
       def initialize(streamables, client: Pgbus.client)
         @name = self.class.name_from(streamables)
+        self.class.validate_name_length!(@name, streamables)
         @client = client
         @ensured = false
         @ensure_mutex = Mutex.new
@@ -108,6 +118,33 @@ module Pgbus
         end
       end
 
+      # Enforces the pgbus queue-name budget at the Stream-construction
+      # boundary so a forgotten call site fails with an actionable error
+      # (pointing at the offending streamables and suggesting
+      # `Pgbus.stream_key`) instead of an opaque QueueNameValidator
+      # failure three frames deep in Client#ensure_stream_queue.
+      #
+      # The budget is computed from `config.queue_prefix` at call time
+      # so apps that override the prefix get the correct limit. Does not
+      # mutate the name — silent truncation is a footgun for
+      # multi-tenant apps where collisions would mix broadcasts across
+      # records. Callers who need a short, safe identifier should use
+      # `Pgbus.stream_key(...)` or include `Pgbus::Streams::Streamable`
+      # on their ActiveRecord models.
+      def self.validate_name_length!(name, streamables)
+        budget = Key.queue_name_budget
+        return if name.length <= budget
+
+        raise StreamNameTooLong,
+              "Stream name #{name.inspect} is #{name.length} chars, " \
+              "exceeds pgbus budget of #{budget} " \
+              "(queue_prefix=#{Pgbus.configuration.queue_prefix.inspect}, " \
+              "pgbus_max_queue_name_length=#{QueueNameValidator::MAX_QUEUE_NAME_LENGTH}). " \
+              "Streamables: #{streamables.inspect}. " \
+              "Use Pgbus.stream_key(*streamables) to produce a safe short name, " \
+              "or include Pgbus::Streams::Streamable on the model."
+      end
+
       private
 
       def ensure_queue!

data/lib/pgbus/version.rb

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

data/lib/pgbus.rb

@@ -105,6 +105,20 @@ module Pgbus
       @stream_cache.compute_if_absent(name) { Streams::Stream.new(streamables) }
     end
 
+    # Compose a short, pgbus-safe stream identifier from any mix of
+    # records, strings, symbols, and arrays. Delegates to
+    # `Pgbus::Streams::Key.stream_key`; raises `ArgumentError` if the
+    # resulting key would overflow the pgbus queue-name budget. See
+    # `lib/pgbus/streams/key.rb` for the digest policy and rationale.
+    #
+    #   Pgbus.stream_key(chat, :messages)
+    #   # => "ai_chat_3a4f9c21b7d20e18:messages"
+    #
+    #   Pgbus.stream(Pgbus.stream_key(chat, :messages)).broadcast(html)
+    def stream_key(*parts, **)
+      Streams::Key.stream_key(*parts, **)
+    end
+
     def reset!
       @client&.close
       @client = nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.6.9
+  version: 0.7.1
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -256,6 +256,7 @@ files:
 - lib/pgbus/configuration/capsule_dsl.rb
 - lib/pgbus/dedup_cache.rb
 - lib/pgbus/engine.rb
+- lib/pgbus/error_reporter.rb
 - lib/pgbus/event.rb
 - lib/pgbus/event_bus/handler.rb
 - lib/pgbus/event_bus/publisher.rb
@@ -269,6 +270,7 @@ files:
 - lib/pgbus/generators/database_target_detector.rb
 - lib/pgbus/generators/migration_detector.rb
 - lib/pgbus/instrumentation.rb
+- lib/pgbus/log_formatter.rb
 - lib/pgbus/outbox.rb
 - lib/pgbus/outbox/poller.rb
 - lib/pgbus/pgmq_schema.rb
@@ -299,8 +301,10 @@ files:
 - lib/pgbus/streams/cursor.rb
 - lib/pgbus/streams/envelope.rb
 - lib/pgbus/streams/filters.rb
+- lib/pgbus/streams/key.rb
 - lib/pgbus/streams/presence.rb
 - lib/pgbus/streams/signed_name.rb
+- lib/pgbus/streams/streamable.rb
 - lib/pgbus/streams/turbo_broadcastable.rb
 - lib/pgbus/streams/turbo_stream_override.rb
 - lib/pgbus/streams/watermark_cache_middleware.rb