pgbus 0.7.3 → 0.7.5

data/lib/pgbus/generators/migration_detector.rb

@@ -74,7 +74,8 @@ module Pgbus
         add_outbox: "pgbus:add_outbox",
         add_recurring: "pgbus:add_recurring",
         add_failed_events_index: "pgbus:add_failed_events_index",
-        tune_autovacuum: "pgbus:tune_autovacuum"
+        tune_autovacuum: "pgbus:tune_autovacuum",
+        tune_fillfactor: "pgbus:tune_fillfactor"
       }.freeze
 
       # Human-friendly description of each migration for the generator
@@ -90,7 +91,8 @@ module Pgbus
         add_outbox: "outbox entries table (transactional outbox)",
         add_recurring: "recurring tasks + executions tables",
         add_failed_events_index: "unique index on pgbus_failed_events (queue_name, msg_id)",
-        tune_autovacuum: "autovacuum tuning for PGMQ queue and archive tables"
+        tune_autovacuum: "autovacuum tuning for PGMQ queue and archive tables",
+        tune_fillfactor: "fillfactor=70 on PGMQ queue tables (reduces page density during update churn)"
       }.freeze
 
       def initialize(connection)
@@ -113,7 +115,8 @@ module Pgbus
           *outbox_migrations,
           *recurring_migrations,
           *failed_events_index_migrations,
-          *autovacuum_migrations
+          *autovacuum_migrations,
+          *fillfactor_migrations
         ]
       end
 
@@ -205,6 +208,15 @@ module Pgbus
         [:tune_autovacuum]
       end
 
+      # Fillfactor tuning: check if any PGMQ queue table already has
+      # fillfactor applied. If not, queue the migration.
+      def fillfactor_migrations
+        return [] unless pgmq_schema_exists?
+        return [] if fillfactor_already_tuned?
+
+        [:tune_fillfactor]
+      end
+
       # --- schema probes -------------------------------------------------
 
       def table_exists?(name)
@@ -247,6 +259,22 @@ module Pgbus
       rescue StandardError
         true # if we can't tell, assume already tuned (safe default)
       end
+
+      def fillfactor_already_tuned?
+        queue_name = connection.select_value("SELECT queue_name FROM pgmq.meta ORDER BY queue_name LIMIT 1")
+        return true unless queue_name # no queues = nothing to tune, skip
+
+        result = connection.select_value(<<~SQL)
+          SELECT reloptions::text LIKE '%fillfactor%'
+          FROM pg_class
+          WHERE relname = 'q_#{queue_name}'
+            AND relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'pgmq')
+        SQL
+
+        [true, "t"].include?(result)
+      rescue StandardError
+        true # if we can't tell, assume already tuned (safe default)
+      end
     end
   end
 end

data/lib/pgbus/process/dispatcher.rb

@@ -15,6 +15,7 @@ module Pgbus
       OUTBOX_CLEANUP_INTERVAL = 3600 # Run outbox cleanup every hour
       JOB_LOCK_CLEANUP_INTERVAL = 300 # Run job lock cleanup every 5 minutes
       STATS_CLEANUP_INTERVAL = 3600 # Run stats cleanup every hour
+      TABLE_MAINTENANCE_INTERVAL = Pgbus::TableMaintenance::MAINTENANCE_INTERVAL
 
       # Page size for archive compaction. Each cycle deletes up to this
       # many archived rows per queue. Tuned via constant rather than
@@ -37,6 +38,7 @@ module Pgbus
         @last_outbox_cleanup_at = monotonic_now
         @last_job_lock_cleanup_at = monotonic_now
         @last_stats_cleanup_at = monotonic_now
+        @last_table_maintenance_at = monotonic_now
       end
 
       def run
@@ -84,6 +86,7 @@ module Pgbus
         run_if_due(now, :@last_outbox_cleanup_at, OUTBOX_CLEANUP_INTERVAL) { cleanup_outbox }
         run_if_due(now, :@last_job_lock_cleanup_at, JOB_LOCK_CLEANUP_INTERVAL) { cleanup_job_locks }
         run_if_due(now, :@last_stats_cleanup_at, STATS_CLEANUP_INTERVAL) { cleanup_stats }
+        run_if_due(now, :@last_table_maintenance_at, TABLE_MAINTENANCE_INTERVAL) { run_table_maintenance }
       end
 
       # Only update the timestamp when the block succeeds.
@@ -158,6 +161,19 @@ module Pgbus
         Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} old stream stats" } if deleted.positive?
       end
 
+      def run_table_maintenance
+        conn = config.connects_to ? Pgbus::BusRecord.connection : ActiveRecord::Base.connection
+        raw_conn = conn.raw_connection
+        maintained = TableMaintenance.run_maintenance(
+          raw_conn,
+          threshold: TableMaintenance::BLOAT_THRESHOLD,
+          reindex: true
+        )
+        Pgbus.logger.info { "[Pgbus] Table maintenance completed: #{maintained} table(s) vacuumed" } if maintained.positive?
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Table maintenance failed: #{e.message}" }
+      end
+
       def cleanup_job_locks
         # Clean up truly orphaned uniqueness keys: rows whose referenced
         # message no longer exists in the PGMQ queue. This handles crashes

data/lib/pgbus/process/supervisor.rb

@@ -145,9 +145,12 @@ module Pgbus
 
       def recurring_tasks_configured?
         return true if config.recurring_tasks&.any?
+
+        files = config.recurring_tasks_files
+        return true if files&.any? { |f| File.exist?(f.to_s) }
+
         return true if config.recurring_tasks_file && File.exist?(config.recurring_tasks_file.to_s)
 
-        # Check default location
         if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
           default_path = Rails.root.join("config", "recurring.yml")
           return File.exist?(default_path.to_s)
@@ -159,6 +162,13 @@ module Pgbus
       def load_recurring_config
         return if config.recurring_tasks&.any?
 
+        files = config.recurring_tasks_files
+        if files
+          tasks = Recurring::ConfigLoader.load_all(files)
+          config.recurring_tasks = tasks unless tasks.empty?
+          return if tasks.any?
+        end
+
         path = config.recurring_tasks_file
         path ||= defined?(Rails) && Rails.respond_to?(:root) && Rails.root ? Rails.root.join("config", "recurring.yml") : nil
         return unless path && File.exist?(path.to_s)

data/lib/pgbus/recurring/config_loader.rb

@@ -23,6 +23,30 @@ module Pgbus
         {}
       end
 
+      def load_all(paths, env: nil)
+        normalized = Array(paths).compact.map { |p| p.respond_to?(:to_path) ? p.to_path : p.to_s }.reject(&:empty?)
+        return {} if normalized.empty?
+
+        env ||= detect_env
+
+        normalized.each_with_object({}) do |path, acc|
+          unless File.exist?(path.to_s)
+            Pgbus.logger.warn { "[Pgbus] Recurring file not found, skipping: #{path}" }
+            next
+          end
+
+          parsed = load(path, env: env)
+          unless parsed.is_a?(Hash)
+            Pgbus.logger.error { "[Pgbus] Invalid recurring config in #{path}: expected Hash, got #{parsed.class}" }
+            next
+          end
+          parsed.each_key do |key|
+            Pgbus.logger.debug { "[Pgbus] Recurring task '#{key}' overridden by #{path}" } if acc.key?(key)
+          end
+          acc.merge!(parsed)
+        end
+      end
+
       def detect_env
         if defined?(Rails) && Rails.respond_to?(:env) && Rails.env
           Rails.env.to_s

data/lib/pgbus/table_maintenance.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # Proactive table maintenance to reduce bloat on PGMQ queue tables.
+  #
+  # PGMQ's read operation UPDATEs three columns (vt, read_ct, last_read_at)
+  # on every message read. With the default fillfactor of 100, every UPDATE
+  # creates a new heap tuple AND a new index entry — the dead tuple and its
+  # old index pointer remain until VACUUM. Under sustained load, autovacuum
+  # can't keep up and B-tree indexes bloat.
+  #
+  # Setting fillfactor=70 on queue tables reserves 30% of each page for
+  # update churn. Because `vt` is indexed and changes on every read, these
+  # writes are not HOT updates, but leaving headroom on heap pages still
+  # reduces page density for a table that is updated heavily between vacuum
+  # passes.
+  #
+  # More importantly, this module provides targeted VACUUM: instead of
+  # relying solely on autovacuum's global heuristics, the dispatcher
+  # periodically checks pg_stat_user_tables for tables with high dead tuple
+  # ratios and vacuums them explicitly. This is inspired by pgque's
+  # philosophy of measuring bloat before acting.
+  module TableMaintenance
+    FILLFACTOR = 70
+    BLOAT_THRESHOLD = 0.1
+    MAINTENANCE_INTERVAL = 6 * 3600 # 6 hours
+
+    class << self
+      def fillfactor_sql_for_queue(queue_name)
+        "ALTER TABLE pgmq.q_#{queue_name} SET (fillfactor = #{FILLFACTOR});"
+      end
+
+      def fillfactor_sql_for_all_queues
+        <<~SQL
+          DO $$
+          DECLARE
+            q RECORD;
+          BEGIN
+            FOR q IN SELECT queue_name FROM pgmq.meta LOOP
+              EXECUTE format('ALTER TABLE pgmq.q_%I SET (fillfactor = #{FILLFACTOR})', q.queue_name);
+            END LOOP;
+          END $$;
+        SQL
+      end
+
+      def vacuum_candidates(conn, threshold: BLOAT_THRESHOLD)
+        rows = conn.exec(<<~SQL)
+          SELECT schemaname, relname, n_dead_tup, n_live_tup
+          FROM pg_stat_user_tables
+          WHERE schemaname = 'pgmq'
+            AND relname LIKE 'q_%'
+          ORDER BY n_dead_tup DESC
+        SQL
+
+        rows.each_with_object([]) do |row, candidates|
+          dead = row["n_dead_tup"].to_i
+          live = row["n_live_tup"].to_i
+          total = dead + live
+          next if total.zero?
+
+          ratio = dead.to_f / total
+          next unless ratio > threshold
+
+          candidates << {
+            table: "#{row["schemaname"]}.#{row["relname"]}",
+            dead_tuples: dead,
+            live_tuples: live,
+            dead_ratio: ratio.round(4)
+          }
+        end
+      end
+
+      def vacuum_sql(table)
+        schema, relname = table.split(".", 2)
+        "VACUUM \"#{schema}\".\"#{relname}\""
+      end
+
+      def reindex_sql(table)
+        schema, relname = table.split(".", 2)
+        "REINDEX TABLE CONCURRENTLY \"#{schema}\".\"#{relname}\""
+      end
+
+      def run_maintenance(conn, threshold: BLOAT_THRESHOLD, reindex: true)
+        candidates = vacuum_candidates(conn, threshold: threshold)
+        return 0 if candidates.empty?
+
+        maintained = 0
+        candidates.each do |candidate|
+          table = candidate[:table]
+          Pgbus.logger.info do
+            "[Pgbus::TableMaintenance] Vacuuming #{table} " \
+              "(dead_ratio=#{candidate[:dead_ratio]}, dead=#{candidate[:dead_tuples]})"
+          end
+          conn.exec(vacuum_sql(table))
+
+          if reindex
+            Pgbus.logger.info { "[Pgbus::TableMaintenance] Reindexing #{table}" }
+            conn.exec(reindex_sql(table))
+          end
+
+          maintained += 1
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::TableMaintenance] Failed to maintain #{table}: #{e.message}" }
+        end
+
+        maintained
+      end
+    end
+  end
+end

data/lib/pgbus/version.rb

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

data/lib/pgbus/web/data_source.rb

@@ -707,10 +707,155 @@ module Pgbus
         []
       end
 
-      # Subscriber registry
+      # Pending events — messages sitting in handler queues that haven't been processed.
+      # Identifies handler queues via the subscriber registry and queries them
+      # for unprocessed messages. Subscriber queue names are logical
+      # (e.g. "task_completion_handler"), while `pgmq.meta.queue_name` stores
+      # physical names (e.g. "pgbus_task_completion_handler"), so we normalize
+      # through `config.queue_name` before intersecting.
+      def pending_events(page: 1, per_page: 25)
+        handler_queues = handler_queue_physical_names
+        return [] if handler_queues.empty?
+
+        existing = connection.select_values(
+          "SELECT queue_name FROM pgmq.meta ORDER BY queue_name", "Pgbus Queue Names"
+        )
+        target_queues = handler_queues & existing
+        return [] if target_queues.empty?
+
+        offset = (page - 1) * per_page
+        paginated_queue_messages(target_queues, per_page, offset)
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error fetching pending events: #{e.message}" }
+        []
+      end
+
+      # Physical queue names for all registered subscribers. Used for both
+      # pending_events lookup and server-side validation of target queues
+      # in reroute_event.
+      def handler_queue_physical_names
+        registered_subscribers.map { |s| s[:physical_queue_name] }.uniq
+      end
+
+      # Find the handler class registered for a given physical queue name.
+      # Returns nil if no subscriber matches — used to reject forged handler
+      # values in mark_event_handled / reroute_event.
+      def handler_class_for_queue(physical_queue_name)
+        sub = registered_subscribers.find { |s| s[:physical_queue_name] == physical_queue_name }
+        sub && sub[:handler_class]
+      end
+
+      # Discard (archive) an event message from a handler queue.
+      def discard_event(queue_name, msg_id)
+        release_lock_for_message(queue_name, msg_id)
+        @client.archive_message(queue_name, msg_id.to_i, prefixed: false)
+        true
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error discarding event #{msg_id}: #{e.message}" }
+        false
+      end
+
+      # Mark an event as handled: archive the queue message and insert a
+      # ProcessedEvent record so it won't be reprocessed on replay.
+      #
+      # The insert is performed BEFORE archive. If the archive step fails
+      # afterwards the operator can retry — replay protection is already in
+      # place and the idempotency dedup will cause the handler to skip the
+      # event even if it is eventually re-read from the queue. Doing it the
+      # other way around would risk losing the message without recording the
+      # marker.
+      def mark_event_handled(queue_name, msg_id, handler_class)
+        detail = job_detail(queue_name, msg_id)
+        return false unless detail
+
+        raw = JSON.parse(detail[:message])
+        event_id = raw["event_id"]
+        return false unless event_id
+
+        ProcessedEvent.insert(
+          { event_id: event_id, handler_class: handler_class, processed_at: Time.now.utc },
+          unique_by: %i[event_id handler_class]
+        )
+        # Release the uniqueness lock while we still hold the payload in
+        # memory — otherwise the message is archived but the lock row stays
+        # behind, blocking later publishes with the same key. Mirrors
+        # discard_event.
+        release_lock_for_payload(detail[:message])
+        @client.archive_message(queue_name, msg_id.to_i, prefixed: false)
+        true
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error marking event #{msg_id} handled: #{e.message}" }
+        false
+      end
+
+      # Edit the payload of a stuck event: delete old message and re-enqueue
+      # with the corrected payload in the same queue. The produce + delete
+      # are wrapped in a PGMQ transaction so the message can't be lost if
+      # either half fails (same pattern as retry_dlq_message).
+      def edit_event_payload(queue_name, msg_id, new_payload_json)
+        begin
+          parsed = JSON.parse(new_payload_json)
+        rescue JSON::ParserError
+          return false
+        end
+
+        detail = job_detail(queue_name, msg_id)
+        return false unless detail
+
+        @client.transaction do |txn|
+          txn.produce(queue_name, parsed.to_json, headers: detail[:headers])
+          txn.delete(queue_name, msg_id.to_i)
+        end
+        true
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error editing event #{msg_id}: #{e.message}" }
+        false
+      end
+
+      # Reroute an event from one handler queue to another. Wrapped in a
+      # PGMQ transaction so produce on the target and delete on the source
+      # are atomic.
+      def reroute_event(source_queue, msg_id, target_queue)
+        detail = job_detail(source_queue, msg_id)
+        return false unless detail
+
+        @client.transaction do |txn|
+          txn.produce(target_queue, detail[:message], headers: detail[:headers])
+          txn.delete(source_queue, msg_id.to_i)
+        end
+        true
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error rerouting event #{msg_id}: #{e.message}" }
+        false
+      end
+
+      # Bulk discard selected events from handler queues.
+      def discard_selected_events(selections)
+        return 0 if selections.empty?
+
+        count = 0
+        selections.each do |sel|
+          discard_event(sel[:queue_name], sel[:msg_id]) && count += 1
+        rescue StandardError => e
+          Pgbus.logger.debug { "[Pgbus::Web] Error in bulk discard for #{sel[:msg_id]}: #{e.message}" }
+          next
+        end
+        count
+      end
+
+      # Subscriber registry. `queue_name` is the logical name the subscriber
+      # registered with; `physical_queue_name` is what the queue is actually
+      # called in `pgmq.meta` (e.g. logical "task_completion_handler" ->
+      # physical "pgbus_task_completion_handler"). The dashboard needs the
+      # physical name to match against pending messages / target queues.
       def registered_subscribers
         EventBus::Registry.instance.subscribers.map do |s|
-          { pattern: s.pattern, handler_class: s.handler_class.name, queue_name: s.queue_name }
+          {
+            pattern: s.pattern,
+            handler_class: s.handler_class.name,
+            queue_name: s.queue_name,
+            physical_queue_name: @client.config.queue_name(s.queue_name)
+          }
         end
       rescue StandardError => e
         Pgbus.logger.debug { "[Pgbus::Web] Error fetching subscribers: #{e.message}" }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.7.5
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -170,6 +170,7 @@ files:
 - app/views/pgbus/dead_letter/_messages_table.html.erb
 - app/views/pgbus/dead_letter/index.html.erb
 - app/views/pgbus/dead_letter/show.html.erb
+- app/views/pgbus/events/_pending_table.html.erb
 - app/views/pgbus/events/index.html.erb
 - app/views/pgbus/events/show.html.erb
 - app/views/pgbus/insights/show.html.erb
@@ -233,8 +234,10 @@ files:
 - lib/generators/pgbus/templates/pgbus_binstub.erb
 - lib/generators/pgbus/templates/recurring.yml.erb
 - lib/generators/pgbus/templates/tune_autovacuum.rb.erb
+- lib/generators/pgbus/templates/tune_fillfactor.rb.erb
 - lib/generators/pgbus/templates/upgrade_pgmq.rb.erb
 - lib/generators/pgbus/tune_autovacuum_generator.rb
+- lib/generators/pgbus/tune_fillfactor_generator.rb
 - lib/generators/pgbus/update_generator.rb
 - lib/generators/pgbus/upgrade_pgmq_generator.rb
 - lib/pgbus.rb
@@ -308,6 +311,7 @@ files:
 - lib/pgbus/streams/turbo_broadcastable.rb
 - lib/pgbus/streams/turbo_stream_override.rb
 - lib/pgbus/streams/watermark_cache_middleware.rb
+- lib/pgbus/table_maintenance.rb
 - lib/pgbus/testing.rb
 - lib/pgbus/testing/assertions.rb
 - lib/pgbus/testing/minitest.rb