pgbus 0.3.3 → 0.3.4

data/lib/pgbus/recurring/schedule.rb

@@ -16,23 +16,13 @@ module Pgbus
 
       def enqueue_task(task, run_at:)
         queue = resolve_queue(task)
+        acquired_key = acquire_uniqueness_lock(task)
 
-        # Check uniqueness lock before enqueuing. If the job class declares
-        # ensures_uniqueness, we acquire the lock here so duplicate recurring
-        # enqueues are rejected while a previous instance is still queued or running.
-        if uniqueness_locked?(task)
-          Pgbus.logger.debug do
-            "[Pgbus] Recurring task #{task.key} skipped: uniqueness lock held"
-          end
-          return
-        end
+        return if acquired_key == :already_locked
 
         RecurringExecution.record(task.key, run_at) do
           payload = build_payload(task)
           headers = build_headers(task, run_at)
-
-          # Inject uniqueness metadata into the payload so the worker knows
-          # to release the lock after execution.
           payload = inject_uniqueness_metadata(task, payload)
 
           Pgbus.client.ensure_queue(queue)
@@ -44,7 +34,11 @@ module Pgbus
           end
         end
       rescue AlreadyRecorded
+        release_uniqueness_lock(acquired_key)
         Pgbus.logger.debug { "[Pgbus] Recurring task #{task.key} already enqueued for #{run_at.iso8601}" }
+      rescue StandardError
+        release_uniqueness_lock(acquired_key)
+        raise
       end
 
       def build_payload(task)
@@ -112,36 +106,45 @@ module Pgbus
         }
       end
 
-      # Check if the job class has ensures_uniqueness and if its lock is currently held.
-      # Returns true if the lock is held (skip enqueue), false otherwise.
-      def uniqueness_locked?(task)
-        return false unless task.class_name
+      # Acquire the uniqueness lock for a recurring task.
+      # Returns:
+      #   nil              — no uniqueness configured, proceed without lock
+      #   :already_locked  — lock held by a previous instance, caller should skip enqueue
+      #   String           — the lock key (lock was acquired, caller must release on failure)
+      def acquire_uniqueness_lock(task)
+        return nil unless task.class_name
 
         job_class = task.class_name.safe_constantize
-        return false unless job_class
-        return false unless job_class.respond_to?(:pgbus_uniqueness)
+        return nil unless job_class
+        return nil unless job_class.respond_to?(:pgbus_uniqueness)
 
         config = job_class.pgbus_uniqueness
-        return false unless config
-        return false unless config[:strategy] == :until_executed
+        return nil unless config
+        return nil unless config[:strategy] == :until_executed
 
         key = resolve_uniqueness_key(config, task)
-        return false unless key
-
-        # Try to acquire the lock. If it fails, the lock is already held.
-        acquired = JobLock.acquire!(
-          key,
-          job_class: task.class_name,
-          job_id: "recurring-#{task.key}",
-          state: "queued",
-          ttl: config[:lock_ttl]
-        )
-        # If we acquired it, great — the message will be enqueued with the lock held.
-        # If not, a previous instance is still queued/running.
-        !acquired
+        return nil unless key
+
+        acquired = UniquenessKey.acquire!(key, queue_name: resolve_queue(task), msg_id: 0)
+
+        if acquired
+          key
+        else
+          Pgbus.logger.debug { "[Pgbus] Recurring task #{task.key} skipped: uniqueness lock held" }
+          :already_locked
+        end
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Uniqueness lock failed for #{task.key}: #{e.message}" }
+        nil # Fail open — allow enqueue if lock check errors
+      end
+
+      # Release a uniqueness lock. Safe to call with nil or :already_locked.
+      def release_uniqueness_lock(key)
+        return if key.nil? || key == :already_locked
+
+        UniquenessKey.release!(key)
       rescue StandardError => e
-        Pgbus.logger.warn { "[Pgbus] Uniqueness check failed for #{task.key}: #{e.message}" }
-        false # Fail open — allow enqueue if uniqueness check errors
+        Pgbus.logger.warn { "[Pgbus] Lock rollback failed: #{e.message}" }
       end
 
       # Resolve the uniqueness key for a recurring task.

data/lib/pgbus/stat_buffer.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # Thread-safe buffer that accumulates job stats in memory and flushes
+  # them to the database in batches. This avoids one INSERT per job
+  # execution, replacing it with periodic bulk inserts.
+  class StatBuffer
+    DEFAULT_FLUSH_SIZE = 100
+    DEFAULT_FLUSH_INTERVAL = 5 # seconds
+
+    attr_reader :flush_size, :flush_interval
+
+    def initialize(flush_size: DEFAULT_FLUSH_SIZE, flush_interval: DEFAULT_FLUSH_INTERVAL)
+      @flush_size = flush_size
+      @flush_interval = flush_interval
+      @buffer = []
+      @mutex = Mutex.new
+      @last_flush_at = monotonic_now
+      @stopped = false
+    end
+
+    # Append a stat entry to the buffer. Flushes automatically when
+    # the buffer reaches flush_size.
+    def push(attrs)
+      should_flush = false
+
+      @mutex.synchronize do
+        @buffer << attrs
+        should_flush = @buffer.size >= @flush_size
+      end
+
+      flush if should_flush
+    end
+
+    # Flush buffered stats to the database. Safe to call from any thread.
+    def flush
+      entries = nil
+
+      @mutex.synchronize do
+        return if @buffer.empty?
+
+        entries = @buffer.dup
+        @buffer.clear
+        @last_flush_at = monotonic_now
+      end
+
+      write_to_database(entries) if entries&.any?
+    end
+
+    # Flush if the interval has elapsed since the last flush.
+    # Called by the dispatcher on its maintenance tick.
+    def flush_if_due
+      due = @mutex.synchronize { monotonic_now - @last_flush_at >= @flush_interval }
+      flush if due
+    end
+
+    def stop
+      @stopped = true
+      flush
+    end
+
+    def size
+      @mutex.synchronize { @buffer.size }
+    end
+
+    private
+
+    def write_to_database(entries)
+      return unless JobStat.table_exists?
+
+      columns = %i[job_class queue_name status duration_ms]
+      columns.push(:enqueue_latency_ms, :retry_count) if JobStat.latency_columns?
+
+      rows = entries.map do |e|
+        row = [e[:job_class], e[:queue_name], e[:status], e[:duration_ms]]
+        row.push(e[:enqueue_latency_ms], e[:retry_count]) if JobStat.latency_columns?
+        row
+      end
+
+      JobStat.insert_all(
+        rows.map { |row| columns.zip(row).to_h },
+        record_timestamps: true
+      )
+    rescue StandardError => e
+      Pgbus.logger.debug { "[Pgbus] Stat buffer flush failed: #{e.message}" }
+    end
+
+    def monotonic_now
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/pgbus/uniqueness.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "active_support/concern"
-require "socket"
 
 module Pgbus
   # Job uniqueness guarantees: prevent duplicate jobs from running concurrently.
@@ -10,14 +9,16 @@ module Pgbus
   # uniqueness ensures AT MOST ONE job with a given key exists in the system
   # at any time — from enqueue through completion.
   #
-  # Lock lifecycle:
-  #   1. Enqueue: lock acquired (state: queued), no owner yet
-  #   2. Execution start: lock transitions to (state: executing, owner_pid: PID)
-  #   3. Completion/DLQ: lock released (row deleted)
-  #   4. Crash recovery: reaper detects orphaned locks by cross-referencing
-  #      owner_pid against pgbus_processes heartbeats
-  #   5. Last resort: expires_at TTL (default 24h) handles the case where
-  #      even the reaper can't run (entire supervisor dead)
+  # Lock lifecycle (advisory lock + thin lookup table):
+  #   1. Enqueue: pg_advisory_xact_lock serializes concurrent attempts,
+  #      then INSERT INTO pgbus_uniqueness_keys ON CONFLICT DO NOTHING.
+  #      The lock row lives as long as the job is in the queue or executing.
+  #   2. Execution: PGMQ's visibility timeout is the execution lock —
+  #      no separate claim_for_execution step needed.
+  #   3. Completion/DLQ: DELETE FROM pgbus_uniqueness_keys WHERE lock_key = ?.
+  #   4. Crash recovery: if a worker dies, VT expires, the message becomes
+  #      readable again. The uniqueness key row stays (correctly — the job
+  #      hasn't finished). The next worker picks it up and executes.
   #
   # Strategies:
   #   :until_executed  — Lock acquired at enqueue, held through execution, released on
@@ -44,7 +45,8 @@ module Pgbus
     STRATEGY_KEY = "pgbus_uniqueness_strategy"
     TTL_KEY = "pgbus_uniqueness_lock_ttl"
 
-    # 24 hours — last-resort fallback only. The reaper handles normal crash recovery.
+    # TTL is kept for metadata compatibility but no longer drives lock expiry.
+    # The lock exists until the job completes or is dead-lettered.
     DEFAULT_LOCK_TTL = 24 * 60 * 60
 
     VALID_STRATEGIES = %i[until_executed while_executing].freeze
@@ -115,54 +117,37 @@ module Pgbus
       end
 
       # Acquire the uniqueness lock at enqueue time (:until_executed only).
-      # Lock state: queued, no owner_pid yet.
-      # Returns :acquired or :locked.
-      def acquire_enqueue_lock(key, active_job)
+      # Uses pg_advisory_xact_lock to serialize concurrent attempts.
+      # Returns :acquired, :locked, or :no_lock.
+      def acquire_enqueue_lock(key, active_job, queue_name: nil, msg_id: nil)
         config = uniqueness_config(active_job)
         return :no_lock unless config
         return :no_lock unless config[:strategy] == :until_executed
 
-        acquired = JobLock.acquire!(
-          key,
-          job_class: active_job.class.name,
-          job_id: active_job.job_id,
-          state: "queued",
-          ttl: config[:lock_ttl]
-        )
+        acquired = if msg_id && queue_name
+                     UniquenessKey.acquire!(key, queue_name: queue_name, msg_id: msg_id)
+                   else
+                     # Pre-produce check: use advisory lock + ON CONFLICT
+                     UniquenessKey.acquire!(key, queue_name: queue_name || "pending", msg_id: msg_id || 0)
+                   end
         acquired ? :acquired : :locked
       end
 
-      # Transition a queued lock to executing state when the worker picks it up.
-      # Called for :until_executed jobs at execution start.
-      def claim_for_execution!(key, ttl:)
-        JobLock.claim_for_execution!(key, owner_pid: ::Process.pid, owner_hostname: Socket.gethostname, ttl: ttl)
-      end
-
       # Acquire the uniqueness lock at execution time (:while_executing only).
-      # Lock state: executing with owner_pid.
       # Returns true if acquired, false if another instance is running.
       def acquire_execution_lock(key, payload)
         strategy = extract_strategy(payload)
         return true unless strategy == :while_executing
 
-        ttl = payload[TTL_KEY] || DEFAULT_LOCK_TTL
-
-        JobLock.acquire!(
-          key,
-          job_class: payload["job_class"],
-          job_id: payload["job_id"],
-          state: "executing",
-          owner_pid: ::Process.pid,
-          owner_hostname: Socket.gethostname,
-          ttl: ttl
-        )
+        queue_name = payload["queue_name"] || "unknown"
+        UniquenessKey.acquire!(key, queue_name: queue_name, msg_id: 0)
       end
 
       # Release the uniqueness lock after execution completes.
       def release_lock(key)
         return unless key
 
-        JobLock.release!(key)
+        UniquenessKey.release!(key)
       end
     end
   end

data/lib/pgbus/version.rb

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

data/lib/pgbus/web/data_source.rb

@@ -57,10 +57,12 @@ module Pgbus
       end
 
       def purge_queue(name)
+        release_uniqueness_keys_for_queue(name)
         @client.purge_queue(name, prefixed: false)
       end
 
       def drop_queue(name)
+        release_uniqueness_keys_for_queue(name)
         @client.drop_queue(name, prefixed: false)
       end
 
@@ -533,23 +535,43 @@ module Pgbus
         []
       end
 
-      # Job locks
+      # Lock management
+      def discard_lock(lock_key)
+        UniquenessKey.where(lock_key: lock_key).delete_all
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error discarding lock #{lock_key}: #{e.message}" }
+        0
+      end
+
+      def discard_locks(lock_keys)
+        return 0 if lock_keys.empty?
+
+        UniquenessKey.where(lock_key: lock_keys).delete_all
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error discarding locks: #{e.message}" }
+        0
+      end
+
+      def discard_all_locks
+        UniquenessKey.delete_all
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error discarding all locks: #{e.message}" }
+        0
+      end
+
+      # Job uniqueness keys
       def job_locks
-        JobLock.order(locked_at: :desc).limit(100).map do |lock|
+        UniquenessKey.order(created_at: :desc).limit(100).map do |key|
           {
-            lock_key: lock.lock_key,
-            job_class: lock.job_class,
-            job_id: lock.job_id,
-            state: lock.state,
-            owner_pid: lock.owner_pid,
-            owner_hostname: lock.owner_hostname,
-            locked_at: lock.locked_at,
-            expires_at: lock.expires_at,
-            age_seconds: lock.locked_at ? (Time.current - lock.locked_at).to_i : nil
+            lock_key: key.lock_key,
+            queue_name: key.queue_name,
+            msg_id: key.msg_id,
+            created_at: key.created_at,
+            age_seconds: key.created_at ? (Time.current - key.created_at).to_i : nil
           }
         end
       rescue StandardError => e
-        Pgbus.logger.debug { "[Pgbus::Web] Error fetching job locks: #{e.message}" }
+        Pgbus.logger.debug { "[Pgbus::Web] Error fetching uniqueness keys: #{e.message}" }
         []
       end
 
@@ -786,7 +808,7 @@ module Pgbus
 
         payload = payload_str.is_a?(String) ? JSON.parse(payload_str) : payload_str
         key = payload[Uniqueness::METADATA_KEY]
-        JobLock.release!(key) if key
+        UniquenessKey.release!(key) if key
       rescue JSON::ParserError => e
         Pgbus.logger.debug { "[Pgbus::Web] Error parsing payload for lock release: #{e.message}" }
       end
@@ -804,7 +826,7 @@ module Pgbus
           nil
         end
 
-        JobLock.where(lock_key: keys).delete_all if keys.any?
+        UniquenessKey.where(lock_key: keys).delete_all if keys.any?
       rescue StandardError => e
         Pgbus.logger.debug { "[Pgbus::Web] Error releasing locks for messages: #{e.message}" }
       end
@@ -822,10 +844,19 @@ module Pgbus
           nil
         end
 
-        JobLock.where(lock_key: keys).delete_all if keys.any?
+        UniquenessKey.where(lock_key: keys).delete_all if keys.any?
       rescue StandardError => e
         Pgbus.logger.debug { "[Pgbus::Web] Error releasing locks for failed events: #{e.message}" }
       end
+
+      # Release all uniqueness keys associated with a queue before purge/drop.
+      # Scans queue messages for uniqueness metadata and deletes matching rows.
+      def release_uniqueness_keys_for_queue(queue_name)
+        messages = query_queue_messages_raw(queue_name, 10_000, 0)
+        release_locks_for_messages(messages)
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error releasing uniqueness keys for queue #{queue_name}: #{e.message}" }
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.4
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -155,6 +155,7 @@ files:
 - app/models/pgbus/recurring_execution.rb
 - app/models/pgbus/recurring_task.rb
 - app/models/pgbus/semaphore.rb
+- app/models/pgbus/uniqueness_key.rb
 - app/views/layouts/pgbus/application.html.erb
 - app/views/pgbus/dashboard/_processes_table.html.erb
 - app/views/pgbus/dashboard/_queues_table.html.erb
@@ -204,12 +205,15 @@ files:
 - lib/generators/pgbus/add_queue_states_generator.rb
 - 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_job_locks.rb.erb
 - lib/generators/pgbus/templates/add_job_stats.rb.erb
 - lib/generators/pgbus/templates/add_job_stats_latency.rb.erb
 - lib/generators/pgbus/templates/add_outbox.rb.erb
 - lib/generators/pgbus/templates/add_queue_states.rb.erb
 - lib/generators/pgbus/templates/add_recurring_tables.rb.erb
+- lib/generators/pgbus/templates/add_uniqueness_keys.rb.erb
+- lib/generators/pgbus/templates/migrate_job_locks_to_uniqueness_keys.rb.erb
 - lib/generators/pgbus/templates/migration.rb.erb
 - lib/generators/pgbus/templates/pgbus.yml.erb
 - lib/generators/pgbus/templates/pgbus_binstub.erb
@@ -261,6 +265,7 @@ files:
 - lib/pgbus/recurring/scheduler.rb
 - lib/pgbus/recurring/task.rb
 - lib/pgbus/serializer.rb
+- lib/pgbus/stat_buffer.rb
 - lib/pgbus/uniqueness.rb
 - lib/pgbus/version.rb
 - lib/pgbus/web/authentication.rb