pgbus 0.9.7 → 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).
@@ -86,10 +90,10 @@ module Pgbus
     attr_reader :pgmq_schema_mode
 
     # Event consumers
-    attr_accessor :event_consumers
+    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
 
@@ -103,14 +107,21 @@ module Pgbus
     attr_accessor :zombie_detection
 
     # Job stats
-    attr_accessor :stats_enabled
+    attr_accessor :stats_enabled, :stats_flush_size, :stats_flush_interval
     attr_reader :stats_retention # rubocop:disable Style/AccessorGrouping
 
     # Web dashboard
     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
+    # the supervisor disabled — mount Pgbus::Web::HealthApp in the host Rails
+    # app instead. When set, Supervisor#run serves /livez and /readyz over a
+    # plain TCPServer bound to `health_bind` (default localhost).
+    attr_accessor :health_port, :health_bind
 
     # Streams (turbo-rails replacement, SSE-based)
     attr_accessor :streams_enabled, :streams_path, :streams_queue_prefix, :streams_signed_name_secret,
@@ -136,6 +147,21 @@ module Pgbus
     # Set to false to opt out without uninstalling the appsignal gem.
     attr_accessor :appsignal_enabled, :appsignal_probe_enabled
 
+    # Generic metrics adapter (Pgbus::Metrics). Consumes the same pgbus.*
+    # instrumentation events as AppSignal and forwards them to a backend:
+    #   nil (default) — install nothing, zero overhead
+    #   :prometheus   — in-process registry, scraped via PrometheusExporter
+    #   :statsd       — UDP datagrams to statsd_host:statsd_port
+    #   a Pgbus::Metrics::Backend instance — a custom backend
+    attr_accessor :metrics_backend, :statsd_host, :statsd_port
+
+    # When true (default), Pgbus.configure and ConfigLoader.apply run
+    # validate! after applying settings, so an invalid value fails loud at
+    # boot instead of dormant until a worker path consumes it. Set false to
+    # opt out (exotic setups that intentionally hold a transiently-invalid
+    # config); explicit validate! still works.
+    attr_accessor :eager_validation
+
     def initialize
       @database_url = nil
       @connection_params = nil
@@ -159,6 +185,7 @@ module Pgbus
 
       @stall_threshold = 90
       @read_timeout = 30
+      @drain_timeout = 30
 
       @dispatch_interval = 1.0
 
@@ -202,13 +229,18 @@ 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
 
       @stats_enabled = true
       @stats_retention = 30 * 24 * 3600 # 30 days
+      # StatBuffer flush thresholds. Buffered stats are lost on SIGKILL, so a
+      # smaller size/interval shrinks the residual loss window at the cost of
+      # more frequent bulk inserts. Defaults mirror StatBuffer's own constants.
+      @stats_flush_size = StatBuffer::DEFAULT_FLUSH_SIZE
+      @stats_flush_interval = StatBuffer::DEFAULT_FLUSH_INTERVAL
 
       @connects_to = nil
 
@@ -221,8 +253,13 @@ 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
+      @health_bind = "127.0.0.1"
 
       @streams_enabled = true
       @streams_path = nil
@@ -259,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
@@ -273,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 = []
@@ -287,6 +326,13 @@ module Pgbus
       # the same process, so the operator can disable it independently.
       @appsignal_enabled = true
       @appsignal_probe_enabled = true
+
+      # Generic metrics adapter: off by default (no subscription installed).
+      @metrics_backend = nil
+      @statsd_host = "127.0.0.1"
+      @statsd_port = 8125
+
+      @eager_validation = true
     end
 
     def queue_name(name)
@@ -311,7 +357,7 @@ module Pgbus
     # Returns the execution mode for a specific worker config hash,
     # falling back to the global execution_mode setting.
     def execution_mode_for(worker_config)
-      mode = worker_config[:execution_mode] || worker_config["execution_mode"] || execution_mode
+      mode = worker_config[:execution_mode] || execution_mode
       ExecutionPools.normalize_mode(mode)
     end
 
@@ -320,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
@@ -335,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
 
@@ -350,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
@@ -365,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
@@ -373,96 +426,143 @@ 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 Pgbus::ConfigurationError, "stats_flush_size must be a positive integer"
+      end
+      unless stats_flush_interval.is_a?(Numeric) && stats_flush_interval.positive?
+        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 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] || w["threads"] || 5
-        raise ArgumentError, "worker threads must be > 0" unless threads.is_a?(Integer) && threads.positive?
+        threads = w[:threads] || 5
+        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] || w["execution_mode"]
-        ExecutionPools.normalize_mode(mode) if mode
+        mode = w[:execution_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!
+      validate_metrics_backend!
 
       self
     end
 
     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!
+      value = metrics_backend
+      return if value.nil?
+      return if %i[prometheus statsd].include?(value)
+      return if defined?(Pgbus::Metrics::Backend) && value.is_a?(Pgbus::Metrics::Backend)
+
+      raise Pgbus::ConfigurationError,
+            "metrics_backend must be nil, :prometheus, :statsd, or a " \
+            "Pgbus::Metrics::Backend instance (got #{value.inspect})"
     end
 
     # Returns true if the given stream name should be durable based on
@@ -513,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 }]
     #
@@ -535,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
@@ -552,13 +654,29 @@ module Pgbus
                    parsed = CapsuleDSL.parse(value)
                    assign_auto_names(parsed)
                  when Array
-                   value
+                   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
 
+    # Event consumer configs arrive with symbol keys (Ruby DSL) or string keys
+    # (YAML via ConfigLoader). Normalize once here so every read site uses
+    # symbol access only. nil passes through (no consumers configured).
+    def event_consumers=(value)
+      @event_consumers =
+        case value
+        when nil
+          nil
+        when Array
+          value.map { |entry| normalize_entry(entry, group: "event_consumer") }
+        else
+          raise Pgbus::ConfigurationError,
+                "event_consumers must be an Array or nil — got #{value.class}"
+        end
+    end
+
     # Define a named capsule and append it to the workers list.
     #
     #   c.capsule :critical, queues: %w[critical], threads: 5
@@ -569,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)
 
@@ -611,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
@@ -623,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
 
@@ -662,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
+
+    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
 
-      recurring_tasks_file ? [recurring_tasks_file] : nil
+    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.
@@ -801,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.
@@ -840,21 +1036,40 @@ 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
 
-    # Read a capsule's name from either symbol or string key, normalized
-    # to a string for comparison. Returns nil for unnamed (legacy) entries.
+    # 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 Pgbus::ConfigurationError, "#{group} entry must be a Hash, got #{entry.class}: #{entry.inspect}" unless entry.is_a?(Hash)
+
+      entry.transform_keys(&:to_sym)
+    end
+
+    # Read a capsule's name (symbol key after normalization), as a string for
+    # comparison. Returns nil for unnamed (legacy) entries.
     def capsule_name(entry)
-      raw = entry[:name] || entry["name"]
-      raw&.to_s
+      entry[:name]&.to_s
     end
 
     # Auto-assign :name to parsed capsules where the first queue token would
@@ -887,17 +1102,17 @@ module Pgbus
       existing_named = (@workers || []).select { |c| capsule_name(c) }
       return if existing_named.empty?
 
-      existing_queues = existing_named.flat_map { |c| c[:queues] || c["queues"] || [] }
+      existing_queues = existing_named.flat_map { |c| c[:queues] || [] }
       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"
@@ -906,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
@@ -915,9 +1130,9 @@ module Pgbus
       return 0 unless entries
 
       entries.sum do |entry|
-        threads = entry[:threads] || entry["threads"] || default_threads
+        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