pgbus 0.9.8 → 0.9.9

data/lib/pgbus/configuration.rb

@@ -30,7 +30,10 @@ module Pgbus
     # advanced for longer than stall_threshold seconds (default 90).
     # read_timeout caps how long a single PGMQ read can block (default 30s),
     # so a dead socket raises instead of parking the loop forever.
-    attr_accessor :stall_threshold, :read_timeout
+    # drain_timeout bounds the graceful-shutdown drain phase (default 30s): a
+    # job still running after this is abandoned to shutdown's own termination
+    # wait, so recycling/deploy never wedges on a permanently-stuck job.
+    attr_accessor :stall_threshold, :read_timeout, :drain_timeout
 
     # Dispatcher settings
     attr_accessor :dispatch_interval
@@ -50,7 +53,8 @@ module Pgbus
     # Priority queues
     attr_accessor :priority_levels, :default_priority
 
-    # Grouped reads (PGMQ v1.11.0+ FIFO grouping).
+    # Grouped reads (PGMQ v1.11.0+ FIFO grouping). EXPERIMENTAL — exempt from
+    # the 1.0 stability promise; the shape may change in a minor release.
     # nil = disabled (default read_batch behavior).
     # :fifo = use read_grouped (drains oldest group first, throughput-optimized).
     # :round_robin = use read_grouped_rr (fair round-robin across groups).
@@ -89,7 +93,7 @@ module Pgbus
     attr_reader :event_consumers
 
     # Recurring jobs
-    attr_accessor :recurring_tasks, :recurring_schedule_interval, :recurring_tasks_file, :skip_recurring
+    attr_accessor :recurring_tasks, :recurring_schedule_interval, :recurring_enabled, :recurring_tasks_file
     attr_writer :recurring_tasks_files
     attr_reader :recurring_execution_retention # rubocop:disable Style/AccessorGrouping
 
@@ -110,7 +114,7 @@ module Pgbus
     attr_accessor :web_auth, :web_refresh_interval, :web_per_page, :web_live_updates, :web_data_source,
                   :insights_default_minutes, :base_controller_class, :return_to_app_url,
                   :metrics_enabled,
-                  :dashboard_filter_parameters, :dashboard_filter_sensitive
+                  :web_filter_parameters, :web_filter_sensitive
 
     # HTTP health endpoints (liveness/readiness for orchestrators like
     # Kubernetes). `health_port` nil (default) leaves the standalone server in
@@ -181,6 +185,7 @@ module Pgbus
 
       @stall_threshold = 90
       @read_timeout = 30
+      @drain_timeout = 30
 
       @dispatch_interval = 1.0
 
@@ -224,7 +229,7 @@ module Pgbus
       @recurring_schedule_interval = 1.0
       @recurring_tasks_file = nil
       @recurring_tasks_files = nil
-      @skip_recurring = false
+      @recurring_enabled = true
       @recurring_execution_retention = 7 * 24 * 3600 # 7 days
 
       @zombie_detection = true
@@ -248,8 +253,9 @@ module Pgbus
       @base_controller_class = "::ActionController::Base"
       @return_to_app_url = nil
       @metrics_enabled = true
-      @dashboard_filter_parameters = nil # nil = auto-detect from Rails, then fall back to defaults
-      @dashboard_filter_sensitive = true
+      @web_filter_parameters = nil # nil = auto-detect from Rails, then fall back to defaults
+      @web_filter_sensitive = true
+      @deprecation_warned = Set.new
 
       # HTTP health endpoints — nil port disables the standalone server.
       @health_port = nil
@@ -290,6 +296,7 @@ module Pgbus
       # PG keepalive interval.
       @streams_listen_health_check_ms = 250
       @streams_write_deadline_ms = 5_000
+      # EXPERIMENTAL — exempt from the 1.0 stability promise.
       @streams_falcon_streaming_body = false
       # Opt-in: when true, the Dispatcher writes one row to
       # pgbus_stream_stats per broadcast/connect/disconnect. Default
@@ -304,7 +311,8 @@ module Pgbus
       @streams_orphan_sweep_interval = 3600    # 1 hour
       @streams_orphan_threshold = 86_400       # 24 hours
       @streams_durable_patterns = []
-      # Streams matching these patterns get connection-driven presence:
+      # EXPERIMENTAL (both presence settings) — exempt from the 1.0 stability
+      # promise. Streams matching these patterns get connection-driven presence:
       # auto-join on SSE connect, auto-leave on disconnect, touch on the
       # keepalive heartbeat (issue #169). Empty by default (opt-in).
       @streams_presence_patterns = []
@@ -358,10 +366,17 @@ module Pgbus
     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(", ")}"
+        raise Pgbus::ConfigurationError, "Invalid log_format: #{format}. Must be one of: #{VALID_LOG_FORMATS.join(", ")}"
       end
 
       @log_format = format
+
+      # Only install pgbus's formatter when the logger still carries a nil or
+      # 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
@@ -373,7 +388,7 @@ module Pgbus
     def streams_default_broadcast_mode=(mode)
       mode = mode.to_sym
       unless VALID_BROADCAST_MODES.include?(mode)
-        raise ArgumentError,
+        raise Pgbus::ConfigurationError,
               "Invalid streams_default_broadcast_mode: #{mode}. Must be one of: #{VALID_BROADCAST_MODES.join(", ")}"
       end
 
@@ -388,11 +403,11 @@ module Pgbus
                 when Symbol then mode
                 when String then mode.to_sym
                 else
-                  raise ArgumentError,
+                  raise Pgbus::ConfigurationError,
                         "Invalid group_mode type: #{mode.class}. Must be nil, String, or Symbol"
                 end
       unless VALID_GROUP_MODES.include?(coerced)
-        raise ArgumentError, "Invalid group_mode: #{coerced.inspect}. Must be nil, :fifo, or :round_robin"
+        raise Pgbus::ConfigurationError, "Invalid group_mode: #{coerced.inspect}. Must be nil, :fifo, or :round_robin"
       end
 
       @group_mode = coerced
@@ -403,7 +418,7 @@ module Pgbus
     def pgmq_schema_mode=(mode)
       mode = mode.to_sym
       unless VALID_PGMQ_SCHEMA_MODES.include?(mode)
-        raise ArgumentError, "Invalid pgmq_schema_mode: #{mode}. Must be one of: #{VALID_PGMQ_SCHEMA_MODES.join(", ")}"
+        raise Pgbus::ConfigurationError, "Invalid pgmq_schema_mode: #{mode}. Must be one of: #{VALID_PGMQ_SCHEMA_MODES.join(", ")}"
       end
 
       @pgmq_schema_mode = mode
@@ -411,57 +426,75 @@ module Pgbus
 
     def validate!
       if pool_size && !(pool_size.is_a?(Numeric) && pool_size.positive?)
-        raise ArgumentError, "pool_size must be a positive number or nil (auto-tune)"
+        raise Pgbus::ConfigurationError, "pool_size must be a positive number or nil (auto-tune)"
       end
 
-      raise ArgumentError, "pool_timeout must be > 0" unless pool_timeout.is_a?(Numeric) && pool_timeout.positive?
-      raise ArgumentError, "polling_interval must be > 0" unless polling_interval.is_a?(Numeric) && polling_interval.positive?
-      raise ArgumentError, "visibility_timeout must be > 0" unless visibility_timeout.is_a?(Numeric) && visibility_timeout.positive?
-      raise ArgumentError, "max_retries must be >= 0" unless max_retries.is_a?(Integer) && max_retries >= 0
-      raise ArgumentError, "retry_backoff must be > 0" unless retry_backoff.is_a?(Numeric) && retry_backoff.positive?
-      raise ArgumentError, "retry_backoff_max must be > 0" unless retry_backoff_max.is_a?(Numeric) && retry_backoff_max.positive?
+      raise Pgbus::ConfigurationError, "pool_timeout must be > 0" unless pool_timeout.is_a?(Numeric) && pool_timeout.positive?
+      raise Pgbus::ConfigurationError, "polling_interval must be > 0" unless polling_interval.is_a?(Numeric) && polling_interval.positive?
+      unless visibility_timeout.is_a?(Numeric) && visibility_timeout.positive?
+        raise Pgbus::ConfigurationError,
+              "visibility_timeout must be > 0"
+      end
+      raise Pgbus::ConfigurationError, "max_retries must be >= 0" unless max_retries.is_a?(Integer) && max_retries >= 0
+      raise Pgbus::ConfigurationError, "retry_backoff must be > 0" unless retry_backoff.is_a?(Numeric) && retry_backoff.positive?
+      unless retry_backoff_max.is_a?(Numeric) && retry_backoff_max.positive?
+        raise Pgbus::ConfigurationError,
+              "retry_backoff_max must be > 0"
+      end
       unless retry_backoff_jitter.is_a?(Numeric) && retry_backoff_jitter >= 0 && retry_backoff_jitter <= 1
-        raise ArgumentError, "retry_backoff_jitter must be between 0 and 1"
+        raise Pgbus::ConfigurationError, "retry_backoff_jitter must be between 0 and 1"
       end
 
       unless stall_threshold.nil? || (stall_threshold.is_a?(Numeric) && stall_threshold.positive?)
-        raise ArgumentError, "stall_threshold must be a positive number or nil to disable"
+        raise Pgbus::ConfigurationError, "stall_threshold must be a positive number or nil to disable"
       end
       unless read_timeout.nil? || (read_timeout.is_a?(Numeric) && read_timeout.positive?)
-        raise ArgumentError, "read_timeout must be a positive number or nil to disable"
+        raise Pgbus::ConfigurationError, "read_timeout must be a positive number or nil to disable"
       end
+      raise Pgbus::ConfigurationError, "drain_timeout must be > 0" unless drain_timeout.is_a?(Numeric) && drain_timeout.positive?
 
       unless stats_flush_size.is_a?(Integer) && stats_flush_size.positive?
-        raise ArgumentError, "stats_flush_size must be a positive integer"
+        raise Pgbus::ConfigurationError, "stats_flush_size must be a positive integer"
       end
       unless stats_flush_interval.is_a?(Numeric) && stats_flush_interval.positive?
-        raise ArgumentError, "stats_flush_interval must be a positive number"
+        raise Pgbus::ConfigurationError, "stats_flush_interval must be a positive number"
       end
 
       unless health_port.nil? || (health_port.is_a?(Integer) && health_port.between?(1, 65_535))
-        raise ArgumentError, "health_port must be an integer between 1 and 65535 or nil to disable"
+        raise Pgbus::ConfigurationError, "health_port must be an integer between 1 and 65535 or nil to disable"
+      end
+
+      raise Pgbus::ConfigurationError, "health_bind must be a non-empty String" unless health_bind.is_a?(String) && !health_bind.empty?
+
+      raise Pgbus::ConfigurationError, "statsd_host must be a non-empty String" unless statsd_host.is_a?(String) && !statsd_host.empty?
+
+      unless statsd_port.is_a?(Integer) && statsd_port.between?(1, 65_535)
+        raise Pgbus::ConfigurationError, "statsd_port must be an integer between 1 and 65535"
       end
 
       # Validate global execution_mode
-      ExecutionPools.normalize_mode(execution_mode)
+      validate_execution_mode!(execution_mode)
 
       Array(workers).each do |w|
         threads = w[:threads] || 5
-        raise ArgumentError, "worker threads must be > 0" unless threads.is_a?(Integer) && threads.positive?
+        raise Pgbus::ConfigurationError, "worker threads must be > 0" unless threads.is_a?(Integer) && threads.positive?
 
         # Validate per-worker execution_mode override if present
         mode = w[:execution_mode]
-        ExecutionPools.normalize_mode(mode) if mode
+        validate_execution_mode!(mode) if mode
       end
 
-      raise ArgumentError, "prefetch_limit must be > 0" if prefetch_limit && !(prefetch_limit.is_a?(Integer) && prefetch_limit.positive?)
+      if prefetch_limit && !(prefetch_limit.is_a?(Integer) && prefetch_limit.positive?)
+        raise Pgbus::ConfigurationError,
+              "prefetch_limit must be > 0"
+      end
 
       if priority_levels && !(priority_levels.is_a?(Integer) && priority_levels >= 1 && priority_levels <= 10)
-        raise ArgumentError, "priority_levels must be an integer between 1 and 10"
+        raise Pgbus::ConfigurationError, "priority_levels must be an integer between 1 and 10"
       end
 
       unless insights_default_minutes.is_a?(Integer) && insights_default_minutes.positive?
-        raise ArgumentError, "insights_default_minutes must be a positive integer"
+        raise Pgbus::ConfigurationError, "insights_default_minutes must be a positive integer"
       end
 
       validate_streams!
@@ -472,47 +505,53 @@ module Pgbus
 
     def validate_streams!
       unless streams_default_retention.is_a?(Numeric) && streams_default_retention >= 0
-        raise ArgumentError, "streams_default_retention must be a non-negative number"
+        raise Pgbus::ConfigurationError, "streams_default_retention must be a non-negative number"
       end
 
       unless streams_max_connections.is_a?(Integer) && streams_max_connections.positive?
-        raise ArgumentError, "streams_max_connections must be a positive integer"
+        raise Pgbus::ConfigurationError, "streams_max_connections must be a positive integer"
       end
 
       unless streams_heartbeat_interval.is_a?(Numeric) && streams_heartbeat_interval.positive?
-        raise ArgumentError, "streams_heartbeat_interval must be a positive number"
+        raise Pgbus::ConfigurationError, "streams_heartbeat_interval must be a positive number"
       end
 
       unless streams_idle_timeout.is_a?(Numeric) && streams_idle_timeout.positive?
-        raise ArgumentError, "streams_idle_timeout must be a positive number"
+        raise Pgbus::ConfigurationError, "streams_idle_timeout must be a positive number"
       end
 
       unless streams_listen_health_check_ms.is_a?(Integer) && streams_listen_health_check_ms.positive?
-        raise ArgumentError, "streams_listen_health_check_ms must be a positive integer"
+        raise Pgbus::ConfigurationError, "streams_listen_health_check_ms must be a positive integer"
       end
 
       unless streams_write_deadline_ms.is_a?(Integer) && streams_write_deadline_ms.positive?
-        raise ArgumentError, "streams_write_deadline_ms must be a positive integer"
+        raise Pgbus::ConfigurationError, "streams_write_deadline_ms must be a positive integer"
       end
 
-      raise ArgumentError, "streams_retention must be a Hash" unless streams_retention.is_a?(Hash)
+      raise Pgbus::ConfigurationError, "streams_retention must be a Hash" unless streams_retention.is_a?(Hash)
 
       if streams_orphan_sweep_interval && !(streams_orphan_sweep_interval.is_a?(Numeric) && streams_orphan_sweep_interval.positive?)
-        raise ArgumentError, "streams_orphan_sweep_interval must be a positive number or nil to disable"
+        raise Pgbus::ConfigurationError, "streams_orphan_sweep_interval must be a positive number or nil to disable"
       end
 
-      raise ArgumentError, "streams_durable_patterns must be an Array of strings/regex" unless streams_durable_patterns.is_a?(Array)
+      unless streams_durable_patterns.is_a?(Array)
+        raise Pgbus::ConfigurationError,
+              "streams_durable_patterns must be an Array of strings/regex"
+      end
 
-      raise ArgumentError, "streams_presence_patterns must be an Array of strings/regex" unless streams_presence_patterns.is_a?(Array)
+      unless streams_presence_patterns.is_a?(Array)
+        raise Pgbus::ConfigurationError,
+              "streams_presence_patterns must be an Array of strings/regex"
+      end
 
       if !streams_presence_member.nil? && !streams_presence_member.respond_to?(:call)
-        raise ArgumentError, "streams_presence_member must respond to #call (a Proc/lambda) or be nil"
+        raise Pgbus::ConfigurationError, "streams_presence_member must respond to #call (a Proc/lambda) or be nil"
       end
 
       return if streams_orphan_threshold.nil?
       return if streams_orphan_threshold.is_a?(Numeric) && streams_orphan_threshold.positive?
 
-      raise ArgumentError, "streams_orphan_threshold must be a positive number or nil to disable"
+      raise Pgbus::ConfigurationError, "streams_orphan_threshold must be a positive number or nil to disable"
     end
 
     def validate_metrics_backend!
@@ -521,7 +560,7 @@ module Pgbus
       return if %i[prometheus statsd].include?(value)
       return if defined?(Pgbus::Metrics::Backend) && value.is_a?(Pgbus::Metrics::Backend)
 
-      raise ArgumentError,
+      raise Pgbus::ConfigurationError,
             "metrics_backend must be nil, :prometheus, :statsd, or a " \
             "Pgbus::Metrics::Backend instance (got #{value.inspect})"
     end
@@ -574,9 +613,11 @@ module Pgbus
     #     c.workers "*: 5"
     #     c.workers "critical: 5; default, mailers: 10"
     #
-    #   Array  — legacy explicit form. Each entry is a Hash with :queues
+    #   Array  — explicit form. Each entry is a Hash with :queues
     #            and :threads (and optionally :name, :single_active_consumer,
-    #            :consumer_priority, :prefetch_limit).
+    #            :consumer_priority, :prefetch_limit). This is the only way to
+    #            express N identical anonymous capsules, so it is supported
+    #            permanently alongside the String DSL.
     #
     #     c.workers [{ queues: %w[default], threads: 5 }]
     #
@@ -596,15 +637,15 @@ module Pgbus
     #   "*: 5"                       -> one anonymous capsule (wildcard never names)
     #   "*: 3; *: 3; *: 3"           -> three anonymous capsules — legal,
     #                                   represents "3 forks all reading every
-    #                                   queue", restoring the legacy YAML
-    #                                   `5 × {queues: ["*"], threads: 3}` shape
+    #                                   queue", the same shape as the Array form
+    #                                   `3 × {queues: ["*"], threads: 3}`
     #   "default: 5; default: 3"     -> two anonymous capsules — same logic
     #
-    # The point of the carve-out is the legacy "I want N forks of the same
-    # worker pool" pattern: it must keep working since PGMQ tolerates it
-    # natively (multiple processes reading the same queue with FOR UPDATE
-    # SKIP LOCKED). The CLI's --capsule selector only matches NAMED
-    # capsules, so anonymous duplicates can't be ambiguously addressed.
+    # The point of the carve-out is the "I want N forks of the same worker
+    # pool" pattern: it must keep working since PGMQ tolerates it natively
+    # (multiple processes reading the same queue with FOR UPDATE SKIP LOCKED).
+    # The CLI's --capsule selector only matches NAMED capsules, so anonymous
+    # duplicates can't be ambiguously addressed.
     def workers=(value)
       @workers = case value
                  when nil
@@ -615,8 +656,8 @@ module Pgbus
                  when Array
                    value.map { |entry| normalize_entry(entry, group: "worker") }
                  else
-                   raise ArgumentError,
-                         "workers must be a String (DSL), Array (legacy form), or nil — got #{value.class}"
+                   raise Pgbus::ConfigurationError,
+                         "workers must be a String (DSL), Array (explicit form), or nil — got #{value.class}"
                  end
     end
 
@@ -631,7 +672,7 @@ module Pgbus
         when Array
           value.map { |entry| normalize_entry(entry, group: "event_consumer") }
         else
-          raise ArgumentError,
+          raise Pgbus::ConfigurationError,
                 "event_consumers must be an Array or nil — got #{value.class}"
         end
     end
@@ -646,13 +687,15 @@ module Pgbus
     # +c.workers "..."+ followed by +c.capsule :name, ...+ appends the
     # named capsule to the list parsed from the string.
     def capsule(name, queues:, threads:, **)
-      raise ArgumentError, "capsule queues must be a non-empty Array" unless queues.is_a?(Array) && queues.any?
-      raise ArgumentError, "capsule threads must be a positive Integer" unless threads.is_a?(Integer) && threads.positive?
+      raise Pgbus::ConfigurationError, "capsule queues must be a non-empty Array" unless queues.is_a?(Array) && queues.any?
+      raise Pgbus::ConfigurationError, "capsule threads must be a positive Integer" unless threads.is_a?(Integer) && threads.positive?
 
       normalized_name = name.to_s
       @workers ||= []
 
-      raise ArgumentError, "capsule #{name.inspect} is already defined" if @workers.any? { |c| capsule_name(c) == normalized_name }
+      if @workers.any? { |c| capsule_name(c) == normalized_name }
+        raise Pgbus::ConfigurationError, "capsule #{name.inspect} is already defined"
+      end
 
       validate_no_queue_overlap!(queues)
 
@@ -688,9 +731,9 @@ module Pgbus
     #   Array         — list of roles to boot
     #
     # Each role is normalized to a downcased symbol and validated against
-    # VALID_ROLES. Unknown role names raise ArgumentError immediately so
-    # typos like `[:workres]` fail loud at boot rather than leaving the
-    # supervisor idling with no children.
+    # VALID_ROLES. Unknown role names raise Pgbus::ConfigurationError
+    # immediately so typos like `[:workres]` fail loud at boot rather than
+    # leaving the supervisor idling with no children.
     def roles=(value)
       if value.nil?
         @roles = nil
@@ -700,7 +743,7 @@ module Pgbus
       normalized = Array(value).map { |r| r.to_s.downcase.to_sym }.uniq
       invalid = normalized - VALID_ROLES
       if invalid.any?
-        raise ArgumentError,
+        raise Pgbus::ConfigurationError,
               "invalid role(s) #{invalid.inspect} — valid roles are: #{VALID_ROLES.join(", ")}"
       end
 
@@ -739,10 +782,56 @@ module Pgbus
       @recurring_execution_retention = coerce_duration!(value, :recurring_execution_retention)
     end
 
+    # recurring_tasks_file (singular) is deprecated in favor of the plural
+    # recurring_tasks_files. The engine still writes the singular internally to
+    # record which default file was loaded, so it stays a plain accessor; the
+    # deprecation warning fires only when a user has set BOTH — the case where
+    # the singular is silently ignored — pointing them at the plural.
     def recurring_tasks_files
-      return @recurring_tasks_files if @recurring_tasks_files
+      if @recurring_tasks_files
+        if @recurring_tasks_file
+          warn_deprecated_config(
+            :recurring_tasks_file,
+            "recurring_tasks_files is set, so recurring_tasks_file is ignored — " \
+            "consolidate onto recurring_tasks_files (plural)"
+          )
+        end
+        return @recurring_tasks_files
+      end
+
+      @recurring_tasks_file ? [@recurring_tasks_file] : nil
+    end
+
+    # --- Deprecated config aliases (renamed at 1.0.0, removed at 2.0.0) ---
+
+    # skip_recurring was the only negative-polarity toggle among the *_enabled
+    # switches. It now aliases recurring_enabled with inverted polarity.
+    def skip_recurring # rubocop:disable Naming/PredicateMethod
+      !recurring_enabled
+    end
 
-      recurring_tasks_file ? [recurring_tasks_file] : nil
+    def skip_recurring=(value)
+      warn_deprecated_config(:skip_recurring, "use recurring_enabled (positive polarity) instead")
+      self.recurring_enabled = !value
+    end
+
+    # dashboard_filter_* unify onto the incumbent web_ prefix.
+    def dashboard_filter_parameters
+      web_filter_parameters
+    end
+
+    def dashboard_filter_parameters=(value)
+      warn_deprecated_config(:dashboard_filter_parameters, "use web_filter_parameters instead")
+      self.web_filter_parameters = value
+    end
+
+    def dashboard_filter_sensitive
+      web_filter_sensitive
+    end
+
+    def dashboard_filter_sensitive=(value)
+      warn_deprecated_config(:dashboard_filter_sensitive, "use web_filter_sensitive instead")
+      self.web_filter_sensitive = value
     end
 
     # Returns the connection pool size to use for the PGMQ client.
@@ -878,6 +967,36 @@ module Pgbus
 
     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
+    # deliberately choose. A genuinely custom formatter — a Proc, or any other
+    # class — is a deliberate choice and is left untouched.
+    def pgbus_installable_formatter?(formatter)
+      return true if formatter.nil?
+      return true if formatter.is_a?(LogFormatter::Text) || formatter.is_a?(LogFormatter::JSON)
+
+      # instance_of? (not is_a?) so a user subclass of these still counts as custom.
+      return true if formatter.instance_of?(::Logger::Formatter)
+      return true if defined?(::ActiveSupport::Logger::SimpleFormatter) &&
+                     formatter.instance_of?(::ActiveSupport::Logger::SimpleFormatter)
+
+      false
+    end
+
+    # Log a one-time deprecation warning for a renamed config key. Deduped per
+    # key on this Configuration instance so a setter called on every request
+    # (or a reader hit in a hot loop) warns once, not on every access.
+    def warn_deprecated_config(key, guidance)
+      @deprecation_warned ||= Set.new
+      return unless @deprecation_warned.add?(key)
+
+      Pgbus.logger.warn do
+        "[Pgbus] Configuration `#{key}` is deprecated and will be removed in 2.0 — #{guidance}. " \
+          "See https://pgbus.dev/docs/upgrading-pgbus"
+      end
+    end
+
     # Built-in presence-member extractor used when no custom
     # `streams_presence_member` is configured. Returns a { id:, metadata: }
     # Hash or nil; #presence_member_for normalizes the id/metadata.
@@ -917,22 +1036,32 @@ module Pgbus
         return validate_positive_duration!(value, name)
       end
 
-      raise ArgumentError,
+      raise Pgbus::ConfigurationError,
             "#{name} must be a Numeric (seconds), ActiveSupport::Duration, or nil to disable, got #{value.inspect}"
     end
 
     def validate_positive_duration!(numeric, name)
-      raise ArgumentError, "#{name} must be a positive number, got #{numeric}" unless numeric.positive?
+      raise Pgbus::ConfigurationError, "#{name} must be a positive number, got #{numeric}" unless numeric.positive?
 
       numeric
     end
 
+    # ExecutionPools.normalize_mode raises ArgumentError for an unknown mode —
+    # that's the right shape for the factory's own callers, but a bad
+    # execution_mode reaching here is a configuration failure, so re-raise it
+    # as ConfigurationError to match the rest of validate! (issue #282).
+    def validate_execution_mode!(mode)
+      ExecutionPools.normalize_mode(mode)
+    rescue ArgumentError => e
+      raise Pgbus::ConfigurationError, e.message
+    end
+
     # Symbolize the top-level keys of a worker/consumer config entry so every
     # downstream read site can use symbol access only. YAML (via ConfigLoader)
     # yields string keys; the Ruby DSL and +capsule+ builder yield symbols.
     # Entries are flat hashes with array/scalar values — no deep recursion.
     def normalize_entry(entry, group:)
-      raise ArgumentError, "#{group} entry must be a Hash, got #{entry.class}: #{entry.inspect}" unless entry.is_a?(Hash)
+      raise Pgbus::ConfigurationError, "#{group} entry must be a Hash, got #{entry.class}: #{entry.inspect}" unless entry.is_a?(Hash)
 
       entry.transform_keys(&:to_sym)
     end
@@ -977,13 +1106,13 @@ module Pgbus
       return if existing_queues.empty?
 
       if existing_queues.include?(CapsuleDSL::WILDCARD)
-        raise ArgumentError,
+        raise Pgbus::ConfigurationError,
               "an existing named capsule already uses '*' (matches every queue) — " \
               "the new capsule's queues #{new_queues.inspect} would overlap with it"
       end
 
       if new_queues.include?(CapsuleDSL::WILDCARD)
-        raise ArgumentError,
+        raise Pgbus::ConfigurationError,
               "the new capsule uses '*' (matches every queue) but other named capsules " \
               "are already defined with queues #{existing_queues.inspect} — " \
               "the wildcard would overlap with all of them"
@@ -992,7 +1121,7 @@ module Pgbus
       conflict = new_queues.find { |q| existing_queues.include?(q) }
       return unless conflict
 
-      raise ArgumentError,
+      raise Pgbus::ConfigurationError,
             "queue #{conflict.inspect} is already assigned to another named capsule — " \
             "named capsules cannot share queues"
     end
@@ -1003,7 +1132,7 @@ module Pgbus
       entries.sum do |entry|
         threads = entry[:threads] || default_threads
         unless threads.is_a?(Integer) && threads.positive?
-          raise ArgumentError,
+          raise Pgbus::ConfigurationError,
                 "#{group} threads must be a positive integer, got #{threads.inspect}"
         end
 

data/lib/pgbus/doctor.rb

@@ -5,7 +5,7 @@ require "pgbus/mcp/health_analyzer"
 
 module Pgbus
   # Preflight diagnostics for a pgbus deployment — the single command that
-  # answers "is this environment healthy enough to run?". Runs six checks and
+  # answers "is this environment healthy enough to run?". Runs seven checks and
   # returns a machine-readable result plus a human report, so `pgbus doctor`
   # and `rake pgbus:doctor` can gate a deploy or CI run (exit 0 on success,
   # 1 on any failure).
@@ -40,7 +40,8 @@ module Pgbus
         check_pgmq_schema,
         check_queues,
         check_notify,
-        check_processes
+        check_processes,
+        check_allowed_global_id_models
       ].map(&:to_h)
     end
 
@@ -83,11 +84,17 @@ module Pgbus
 
     private
 
+    # True in a Rails production environment. Guarded so the doctor still runs
+    # outside Rails (plain Ruby, tests) without assuming Rails is loaded.
+    def production?
+      defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+    end
+
     # 1. Configuration validity.
     def check_configuration
       @config.validate!
       Check.new(name: "Configuration", status: :ok, detail: "valid")
-    rescue ArgumentError => e
+    rescue Pgbus::ConfigurationError, ArgumentError => e
       Check.new(name: "Configuration", status: :fail, detail: e.message)
     rescue StandardError => e
       Check.new(name: "Configuration", status: :fail, detail: "#{e.class}: #{e.message}")
@@ -185,6 +192,24 @@ module Pgbus
       Check.new(name: "Process liveness", status: :fail, detail: "#{e.class}: #{e.message}")
     end
 
+    # 7. GlobalID allowlist — security. allowed_global_id_models = nil means
+    # "allow ANY model as a GlobalID event/job argument", which lets a crafted
+    # payload deserialize arbitrary AR models. It's the default for upgrade
+    # continuity, so this is a warning (never a failure), and only in production
+    # where the blast radius is real.
+    def check_allowed_global_id_models
+      if @config.allowed_global_id_models.nil? && production?
+        return Check.new(name: "GlobalID allowlist", status: :warn,
+                         detail: "allowed_global_id_models is nil (allow-all) in production — " \
+                                 "set an explicit allowlist of models permitted as GlobalID arguments")
+      end
+
+      Check.new(name: "GlobalID allowlist", status: :ok,
+                detail: @config.allowed_global_id_models.nil? ? "allow-all (non-production)" : "allowlist configured")
+    rescue StandardError => e
+      Check.new(name: "GlobalID allowlist", status: :fail, detail: "#{e.class}: #{e.message}")
+    end
+
     # Physical queue names known to PGMQ. list_queues rows may be Hashes (with a
     # :queue_name key) or value objects responding to #queue_name.
     def existing_queue_names

data/lib/pgbus/execution_pools/async_pool.rb

@@ -25,7 +25,7 @@ module Pgbus
 
       def post(&block)
         raise_if_fatal!
-        raise "Execution pool is shutting down" if shutdown?
+        raise Pgbus::ExecutionPoolError, "Execution pool is shutting down" if shutdown?
 
         reserved = false
         reserve_capacity!
@@ -193,7 +193,7 @@ module Pgbus
 
       def reserve_capacity!
         @mutex.synchronize do
-          raise "Execution pool is at capacity" if @available_capacity <= 0
+          raise Pgbus::ExecutionPoolError, "Execution pool is at capacity" if @available_capacity <= 0
 
           @available_capacity -= 1
         end