pgbus 0.3.5 → 0.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a25921e6a7a0ac72023501978b6dec0b38645a18b45cece73bf15ddbc655dae8
-  data.tar.gz: 810980a58f382aad948b660a9102cdb6ea3a3af57c3768f1205c3582b0705003
+  metadata.gz: 031cb29b5105d5731e862ab92fa1c8872279b3ff0e5dbbbdf595d4733874780a
+  data.tar.gz: ab7912d72556e382056a3f8f9cc0edd9f0498706b1958fce1f6546e4f8619eb2
 SHA512:
-  metadata.gz: 597fbc986e88b2c37339156de5f21a576d50f45bab5f72343dc3eaed02b730d35dce777285f65b63f3264f4a91d76fa0b7a001635a6c103b08ef95454c6dc71f
-  data.tar.gz: 2a305826eb3b9b0618e64c99e0724c2daf020047933e83d231a35866d8e8b1e334a45c45c03a7fbef577b8dd2243686dc4e351595a671a8d8cd1a63f940602ed
+  metadata.gz: f2892d6f44649afe256393e7abfc67369fa8d87ecb159b6e9d5a9e5816ab14a2a328bfd48c6c400866f1a81cb48b91446162d500d71faf06a587fc05e8d3bab6
+  data.tar.gz: 3577ea2487cd452e455a43be6dc310511681f003a942960116e41cd79722291a8cdb2a00d103e13950c8a6f996e3054029093e90d9587767e93ef11943969209

data/lib/generators/pgbus/add_failed_events_index_generator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Pgbus
+  module Generators
+    class AddFailedEventsIndexGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Add unique index on pgbus_failed_events (queue_name, msg_id) for failure tracking upserts"
+
+      class_option :database,
+                   type: :string,
+                   default: nil,
+                   desc: "Use a separate database for pgbus tables (e.g. --database=pgbus)"
+
+      def create_migration_file
+        if separate_database?
+          migration_template "add_failed_events_unique_index.rb.erb",
+                             "db/pgbus_migrate/add_pgbus_failed_events_unique_index.rb"
+        else
+          migration_template "add_failed_events_unique_index.rb.erb",
+                             "db/migrate/add_pgbus_failed_events_unique_index.rb"
+        end
+      end
+
+      def display_post_install
+        say ""
+        say "Pgbus failed events unique index added!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  2. Failed jobs will now be tracked in the dashboard"
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+
+      def separate_database?
+        options[:database].present?
+      end
+    end
+  end
+end

data/lib/generators/pgbus/templates/add_failed_events_unique_index.rb.erb

@@ -0,0 +1,7 @@
+class AddPgbusFailedEventsUniqueIndex < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_index :pgbus_failed_events, [:queue_name, :msg_id],
+      unique: true, name: "idx_pgbus_failed_events_queue_msg",
+      if_not_exists: true
+  end
+end

data/lib/generators/pgbus/templates/migration.rb.erb

@@ -65,6 +65,8 @@ class CreatePgbusTables < ActiveRecord::Migration<%= migration_version %>
 
     add_index :pgbus_failed_events, :queue_name, name: "idx_pgbus_failed_events_queue"
     add_index :pgbus_failed_events, :failed_at, name: "idx_pgbus_failed_events_time"
+    add_index :pgbus_failed_events, [:queue_name, :msg_id],
+      unique: true, name: "idx_pgbus_failed_events_queue_msg"
 
     # Concurrency semaphores (counting locks for job concurrency limits)
     create_table :pgbus_semaphores do |t|

data/lib/pgbus/active_job/executor.rb

@@ -20,6 +20,7 @@ module Pgbus
 
         if read_count > config.max_retries
           handle_dead_letter(message, queue_name, payload, source_queue: source_queue)
+          FailedEventRecorder.clear!(queue_name: queue_name, msg_id: message.msg_id.to_i)
           signal_concurrency(payload)
           signal_batch_discarded(payload)
           Uniqueness.release_lock(Uniqueness.extract_key(payload))
@@ -54,6 +55,7 @@ module Pgbus
           job = ::ActiveJob::Base.deserialize(payload)
           execute_job(job)
           archive_from(queue_name, message.msg_id.to_i, source_queue: source_queue)
+          FailedEventRecorder.clear!(queue_name: queue_name, msg_id: message.msg_id.to_i)
           job_succeeded = true
         end
 
@@ -61,7 +63,7 @@ module Pgbus
         record_stat(payload, queue_name, "success", execution_start, message: message)
         :success
       rescue StandardError => e
-        handle_failure(message, queue_name, e)
+        handle_failure(message, queue_name, e, payload: payload)
         instrument("pgbus.job_failed", queue: queue_name, job_class: payload&.dig("job_class"), error: e.class.name)
         record_stat(payload, queue_name, "failed", execution_start, message: message)
         # Don't signal concurrency on transient failure — the job will be retried.
@@ -143,13 +145,22 @@ module Pgbus
         [((Time.now.utc - enqueued_at) * 1000).round, 0].max
       end
 
-      def handle_failure(_message, _queue_name, error)
+      def handle_failure(message, queue_name, error, payload: nil)
         Pgbus.logger.error { "[Pgbus] Job failed: #{error.class}: #{error.message}" }
         Pgbus.logger.debug { error.backtrace&.join("\n") }
 
+        # Record failure for dashboard visibility.
         # Message visibility timeout will expire and it becomes available again.
         # read_ct tracks delivery attempts — when it exceeds max_retries,
         # the next read will route to DLQ.
+        FailedEventRecorder.record!(
+          queue_name: queue_name,
+          msg_id: message.msg_id.to_i,
+          payload: payload || message.message,
+          headers: message.respond_to?(:headers) ? message.headers : nil,
+          error: error,
+          retry_count: [message.read_ct.to_i - 1, 0].max
+        )
       end
 
       def instrument(event_name, payload = {})

data/lib/pgbus/failed_event_recorder.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # Records job failures to pgbus_failed_events for dashboard visibility.
+  # Uses upsert (INSERT ON CONFLICT UPDATE) keyed on (queue_name, msg_id)
+  # so each message has at most one failed_event row tracking its latest error.
+  class FailedEventRecorder
+    class << self
+      def record!(queue_name:, msg_id:, payload:, headers:, error:, retry_count:)
+        connection.exec_query(
+          <<~SQL.squish,
+            INSERT INTO pgbus_failed_events
+              (queue_name, msg_id, payload, headers, error_class, error_message, backtrace, retry_count, failed_at)
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, CURRENT_TIMESTAMP)
+            ON CONFLICT (queue_name, msg_id) DO UPDATE SET
+              error_class = EXCLUDED.error_class,
+              error_message = EXCLUDED.error_message,
+              backtrace = EXCLUDED.backtrace,
+              retry_count = EXCLUDED.retry_count,
+              failed_at = EXCLUDED.failed_at
+          SQL
+          "FailedEvent Record",
+          [
+            queue_name,
+            msg_id.to_i,
+            payload.is_a?(String) ? payload : JSON.generate(payload),
+            headers.is_a?(String) ? headers : headers&.then { |h| JSON.generate(h) },
+            error.class.name,
+            error.message.to_s.truncate(10_000),
+            error.backtrace&.first(30)&.join("\n"),
+            retry_count
+          ]
+        )
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus] Failed to record failed event: #{e.message}" }
+      end
+
+      def clear!(queue_name:, msg_id:)
+        connection.exec_delete(
+          "DELETE FROM pgbus_failed_events WHERE queue_name = $1 AND msg_id = $2",
+          "FailedEvent Clear",
+          [queue_name, msg_id.to_i]
+        )
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus] Failed to clear failed event: #{e.message}" }
+      end
+
+      private
+
+      def connection
+        if defined?(BusRecord) && BusRecord.connected?
+          BusRecord.connection
+        else
+          ActiveRecord::Base.connection
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/recurring/schedule.rb

@@ -11,7 +11,10 @@ module Pgbus
       end
 
       def due_tasks(time = Time.current)
-        tasks.select { |task| task_due?(task, time) }
+        tasks.filter_map do |task|
+          run_at = canonical_run_at(task, time)
+          [task, run_at] if run_at
+        end
       end
 
       def enqueue_task(task, run_at:)
@@ -34,6 +37,12 @@ module Pgbus
           end
         end
       rescue AlreadyRecorded
+        # AlreadyRecorded means this (task_key, run_at) was already enqueued.
+        # If we acquired a NEW lock (prior lock was already released because the
+        # job completed), release it — no message will use it. If we didn't
+        # acquire a lock (nil or :already_locked), there's nothing to release.
+        # In either case, we are NOT opening a race window because the job for
+        # this run_at already ran or is running.
         release_uniqueness_lock(acquired_key)
         Pgbus.logger.debug { "[Pgbus] Recurring task #{task.key} already enqueued for #{run_at.iso8601}" }
       rescue StandardError
@@ -75,23 +84,31 @@ module Pgbus
         end
       end
 
-      def task_due?(task, time)
-        # A task is due when its most recent cron occurrence (previous_time)
-        # falls within the current tick window. We also check match? to
-        # handle the exact-boundary case where time == cron time.
+      # Returns the canonical run_at time if the task is due, or nil if not.
+      # This ensures a consistent run_at regardless of which tick detects
+      # the cron occurrence — fixing a bug where match?(t) at the exact
+      # boundary returns previous_time=T-1, while a tick 1s later gets
+      # previous_time=T, producing different run_at values for the same
+      # cron occurrence and bypassing RecurringExecution deduplication.
+      def canonical_run_at(task, time)
         cron = task.parsed_schedule
-        return false unless cron
-
-        # Check if `time` itself matches the cron (exact boundary hit)
-        return true if cron.match?(time)
+        return nil unless cron
+
+        # Exact boundary hit: cron.match?(time) is true.
+        # previous_time returns the PRIOR occurrence here, but the cron
+        # time that fired is `time` itself (truncated to the minute).
+        if cron.match?(time)
+          # Fugit next_time from 1 second before gives us the current cron time
+          return cron.next_time(time - 1).to_t
+        end
 
-        # Check if the previous occurrence was recent enough that we should
-        # still fire it (handles the case where we tick slightly after the
-        # cron time). The window is the scheduler interval.
+        # Within the scheduler interval window after the cron time.
         prev = task.previous_time(time)
-        return false unless prev
+        return nil unless prev
 
-        (time - prev) <= @config.recurring_schedule_interval
+        return prev if (time - prev) <= @config.recurring_schedule_interval
+
+        nil
       end
 
       def resolve_queue(task)

data/lib/pgbus/recurring/scheduler.rb

@@ -40,10 +40,7 @@ module Pgbus
       end
 
       def tick(now)
-        schedule.due_tasks(now).each do |task|
-          run_at = task.previous_time(now)
-          next unless run_at
-
+        schedule.due_tasks(now).each do |task, run_at|
           schedule.enqueue_task(task, run_at: run_at)
           @last_runs[task.key] = now
         rescue StandardError => e

data/lib/pgbus/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.3.7
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -198,6 +198,7 @@ files:
 - config/routes.rb
 - exe/pgbus
 - lib/active_job/queue_adapters/pgbus_adapter.rb
+- lib/generators/pgbus/add_failed_events_index_generator.rb
 - lib/generators/pgbus/add_job_locks_generator.rb
 - lib/generators/pgbus/add_job_stats_generator.rb
 - lib/generators/pgbus/add_job_stats_latency_generator.rb
@@ -206,6 +207,7 @@ files:
 - lib/generators/pgbus/add_recurring_generator.rb
 - lib/generators/pgbus/install_generator.rb
 - lib/generators/pgbus/migrate_job_locks_generator.rb
+- lib/generators/pgbus/templates/add_failed_events_unique_index.rb.erb
 - lib/generators/pgbus/templates/add_job_locks.rb.erb
 - lib/generators/pgbus/templates/add_job_stats.rb.erb
 - lib/generators/pgbus/templates/add_job_stats_latency.rb.erb
@@ -240,6 +242,7 @@ files:
 - lib/pgbus/event_bus/publisher.rb
 - lib/pgbus/event_bus/registry.rb
 - lib/pgbus/event_bus/subscriber.rb
+- lib/pgbus/failed_event_recorder.rb
 - lib/pgbus/instrumentation.rb
 - lib/pgbus/outbox.rb
 - lib/pgbus/outbox/poller.rb