pgbus 0.6.8 → 0.7.0

data/lib/generators/pgbus/install_generator.rb

@@ -2,11 +2,13 @@
 
 require "rails/generators"
 require "rails/generators/active_record"
+require_relative "migration_path"
 
 module Pgbus
   module Generators
     class InstallGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
+      include MigrationPath
 
       source_root File.expand_path("templates", __dir__)
 
@@ -25,13 +27,8 @@ module Pgbus
                          "Migrations go to db/pgbus_migrate/ and schema to db/pgbus_schema.rb"
 
       def create_migration_file
-        if separate_database?
-          migration_template "migration.rb.erb",
-                             "db/pgbus_migrate/create_pgbus_tables.rb"
-        else
-          migration_template "migration.rb.erb",
-                             "db/migrate/create_pgbus_tables.rb"
-        end
+        migration_template "migration.rb.erb",
+                           File.join(pgbus_migrate_path, "create_pgbus_tables.rb")
       end
 
       def create_config_file
@@ -121,10 +118,6 @@ module Pgbus
       def database_name
         options[:database]
       end
-
-      def separate_database?
-        database_name.present?
-      end
     end
   end
 end

data/lib/generators/pgbus/migrate_job_locks_generator.rb

@@ -2,11 +2,13 @@
 
 require "rails/generators"
 require "rails/generators/active_record"
+require_relative "migration_path"
 
 module Pgbus
   module Generators
     class MigrateJobLocksGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
+      include MigrationPath
 
       source_root File.expand_path("templates", __dir__)
 
@@ -18,13 +20,8 @@ module Pgbus
                    desc: "Use a separate database for pgbus tables (e.g. --database=pgbus)"
 
       def create_migration_file
-        if separate_database?
-          migration_template "migrate_job_locks_to_uniqueness_keys.rb.erb",
-                             "db/pgbus_migrate/migrate_pgbus_job_locks_to_uniqueness_keys.rb"
-        else
-          migration_template "migrate_job_locks_to_uniqueness_keys.rb.erb",
-                             "db/migrate/migrate_pgbus_job_locks_to_uniqueness_keys.rb"
-        end
+        migration_template "migrate_job_locks_to_uniqueness_keys.rb.erb",
+                           File.join(pgbus_migrate_path, "migrate_pgbus_job_locks_to_uniqueness_keys.rb")
       end
 
       def display_post_install
@@ -47,10 +44,6 @@ module Pgbus
       def migration_version
         "[#{ActiveRecord::Migration.current_version}]"
       end
-
-      def separate_database?
-        options[:database].present?
-      end
     end
   end
 end

data/lib/generators/pgbus/migration_path.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Generators
+    # Shared migration path logic for all pgbus generators.
+    #
+    # When --database is passed, uses Rails' built-in db_migrate_path which
+    # reads migrations_paths from database.yml. This is the standard Rails
+    # multi-database mechanism and respects custom paths like db/pgbus_migrate/.
+    #
+    # Falls back to db/migrate/ when no --database is set (single-database mode).
+    module MigrationPath
+      private
+
+      def pgbus_migrate_path
+        if separate_database?
+          db_migrate_path
+        else
+          "db/migrate"
+        end
+      end
+
+      def separate_database?
+        options[:database].present?
+      end
+    end
+  end
+end

data/lib/generators/pgbus/tune_autovacuum_generator.rb

@@ -2,11 +2,13 @@
 
 require "rails/generators"
 require "rails/generators/active_record"
+require_relative "migration_path"
 
 module Pgbus
   module Generators
     class TuneAutovacuumGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
+      include MigrationPath
 
       source_root File.expand_path("templates", __dir__)
 
@@ -18,13 +20,8 @@ module Pgbus
                    desc: "Use a separate database for pgbus tables (e.g. --database=pgbus)"
 
       def create_migration_file
-        if separate_database?
-          migration_template "tune_autovacuum.rb.erb",
-                             "db/pgbus_migrate/tune_pgbus_autovacuum.rb"
-        else
-          migration_template "tune_autovacuum.rb.erb",
-                             "db/migrate/tune_pgbus_autovacuum.rb"
-        end
+        migration_template "tune_autovacuum.rb.erb",
+                           File.join(pgbus_migrate_path, "tune_pgbus_autovacuum.rb")
       end
 
       def display_post_install
@@ -46,10 +43,6 @@ module Pgbus
       def migration_version
         "[#{ActiveRecord::Migration.current_version}]"
       end
-
-      def separate_database?
-        options[:database].present?
-      end
     end
   end
 end

data/lib/generators/pgbus/upgrade_pgmq_generator.rb

@@ -2,11 +2,13 @@
 
 require "rails/generators"
 require "rails/generators/active_record"
+require_relative "migration_path"
 
 module Pgbus
   module Generators
     class UpgradePgmqGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
+      include MigrationPath
 
       source_root File.expand_path("templates", __dir__)
 
@@ -18,13 +20,8 @@ module Pgbus
                    desc: "Use a separate database for pgbus tables (e.g. --database=pgbus)"
 
       def create_migration_file
-        if separate_database?
-          migration_template "upgrade_pgmq.rb.erb",
-                             "db/pgbus_migrate/upgrade_pgmq_to_v#{target_version_slug}.rb"
-        else
-          migration_template "upgrade_pgmq.rb.erb",
-                             "db/migrate/upgrade_pgmq_to_v#{target_version_slug}.rb"
-        end
+        migration_template "upgrade_pgmq.rb.erb",
+                           File.join(pgbus_migrate_path, "upgrade_pgmq_to_v#{target_version_slug}.rb")
       end
 
       def display_post_upgrade
@@ -51,10 +48,6 @@ module Pgbus
       def target_version_slug
         target_version.tr(".", "_")
       end
-
-      def separate_database?
-        options[:database].present?
-      end
     end
   end
 end

data/lib/pgbus/active_job/executor.rb

@@ -146,7 +146,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.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
 

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

@@ -47,6 +47,7 @@ module Pgbus
     rake_tasks do
       load File.expand_path("../tasks/pgbus_pgmq.rake", __dir__)
       load File.expand_path("../tasks/pgbus_streams.rake", __dir__)
+      load File.expand_path("../tasks/pgbus_autovacuum.rake", __dir__)
     end
 
     initializer "pgbus.i18n" do

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/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

@@ -83,7 +83,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 +103,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 +132,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 +186,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 +212,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 +282,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