pgbus 0.1.4 → 0.1.6

data/lib/pgbus/outbox/poller.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Outbox
+    class Poller
+      include Process::SignalHandler
+
+      attr_reader :config
+
+      def initialize(config: Pgbus.configuration)
+        @config = config
+        @shutting_down = false
+      end
+
+      def run
+        setup_signals
+        start_heartbeat
+        Pgbus.logger.info { "[Pgbus] Outbox poller started: interval=#{config.outbox_poll_interval}s" }
+
+        loop do
+          break if @shutting_down
+
+          process_signals
+          break if @shutting_down
+
+          poll_and_publish
+          break if @shutting_down
+
+          interruptible_sleep(config.outbox_poll_interval)
+        end
+
+        shutdown
+      end
+
+      def graceful_shutdown
+        @shutting_down = true
+      end
+
+      def immediate_shutdown
+        @shutting_down = true
+      end
+
+      def poll_and_publish
+        published = 0
+
+        loop do
+          succeeded = 0
+
+          OutboxEntry.transaction do
+            entries = OutboxEntry.unpublished
+                                 .order(:id)
+                                 .limit(config.outbox_batch_size)
+                                 .lock("FOR UPDATE SKIP LOCKED")
+                                 .to_a
+            break if entries.empty?
+
+            entries.each do |entry|
+              succeeded += 1 if publish_entry(entry)
+            end
+
+            published += succeeded
+            break if succeeded.zero? || entries.size < config.outbox_batch_size
+          end
+
+          break if succeeded.zero?
+        end
+
+        Pgbus.logger.debug { "[Pgbus] Outbox published #{published} entries" } if published.positive?
+        published
+      rescue StandardError => e
+        Pgbus.logger.error { "[Pgbus] Outbox poll error: #{e.message}" }
+        0
+      end
+
+      private
+
+      def publish_entry(entry)
+        if entry.routing_key.present?
+          Pgbus.client.publish_to_topic(
+            entry.routing_key,
+            entry.payload,
+            headers: entry.headers,
+            delay: entry.delay || 0
+          )
+        else
+          Pgbus.client.send_message(
+            entry.queue_name,
+            entry.payload,
+            headers: entry.headers,
+            delay: entry.delay || 0,
+            priority: entry.priority
+          )
+        end
+
+        entry.update!(published_at: Time.current)
+        true
+      rescue StandardError => e
+        Pgbus.logger.error { "[Pgbus] Failed to publish outbox entry #{entry.id}: #{e.message}" }
+        false
+      end
+
+      def start_heartbeat
+        @heartbeat = Process::Heartbeat.new(
+          kind: "outbox_poller",
+          metadata: { pid: ::Process.pid }
+        )
+        @heartbeat.start
+      end
+
+      def shutdown
+        @heartbeat&.stop
+        restore_signals
+        Pgbus.logger.info { "[Pgbus] Outbox poller stopped" }
+      end
+    end
+  end
+end

data/lib/pgbus/outbox.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Outbox
+    module_function
+
+    def publish(queue_name, payload, headers: nil, priority: nil, delay: 0)
+      OutboxEntry.create!(
+        queue_name: queue_name,
+        payload: payload,
+        headers: headers,
+        priority: priority || Pgbus.configuration.default_priority,
+        delay: delay
+      )
+    end
+
+    def publish_event(routing_key, payload, headers: nil)
+      event_data = EventBus::Publisher.build_event_data(payload)
+      OutboxEntry.create!(
+        routing_key: routing_key,
+        payload: event_data,
+        headers: headers
+      )
+    end
+
+    def flush!
+      Poller.new.poll_and_publish
+    end
+  end
+end

data/lib/pgbus/process/consumer_priority.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Process
+    # Implements consumer priority by checking whether higher-priority
+    # workers are active for the same queues. When a higher-priority
+    # worker is healthy and not at its prefetch limit, lower-priority
+    # workers yield by using a longer polling interval.
+    #
+    # Inspired by LavinMQ's consumer priority where higher-priority
+    # consumers are served first and lower-priority consumers wait
+    # until all higher-priority consumers are at their prefetch limit.
+    module ConsumerPriority
+      # Check if this worker should yield to a higher-priority worker.
+      # Returns true if a higher-priority healthy worker exists for
+      # any of the given queues.
+      def self.should_yield?(queues:, my_priority:, my_pid:)
+        return false if my_priority >= max_active_priority(queues, my_pid)
+
+        true
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus] Consumer priority check failed: #{e.message}" }
+        false
+      end
+
+      # Returns the highest consumer_priority among healthy workers
+      # that share at least one queue with the given queue list,
+      # excluding the current worker (by PID).
+      def self.max_active_priority(queues, my_pid)
+        conn = Pgbus.configuration.connects_to ? Pgbus::ApplicationRecord.connection : ActiveRecord::Base.connection
+        rows = conn.select_all(
+          "SELECT metadata FROM pgbus_processes WHERE kind = 'worker' AND pid != $1 AND last_heartbeat_at > $2",
+          "Pgbus ConsumerPriority",
+          [my_pid, Time.now.utc - Heartbeat::ALIVE_THRESHOLD]
+        )
+
+        max_priority = 0
+        rows.each do |row|
+          metadata = row["metadata"]
+          metadata = JSON.parse(metadata) if metadata.is_a?(String)
+          next unless metadata
+
+          other_queues = metadata["queues"] || []
+          next unless queues.intersect?(other_queues)
+
+          other_priority = metadata["consumer_priority"] || 0
+          max_priority = other_priority if other_priority > max_priority
+        end
+
+        max_priority
+      end
+
+      # Calculate the effective polling interval for this worker.
+      # Higher-priority workers use the base interval.
+      # Lower-priority workers multiply by a backoff factor.
+      def self.effective_polling_interval(base_interval:, my_priority:, max_priority:)
+        return base_interval if my_priority >= max_priority
+
+        # Lower-priority workers back off: 3x the base interval
+        base_interval * 3
+      end
+    end
+  end
+end

data/lib/pgbus/process/dispatcher.rb

@@ -11,6 +11,10 @@ module Pgbus
       CONCURRENCY_INTERVAL = 300            # Run concurrency cleanup every 5 minutes
       BATCH_CLEANUP_INTERVAL = 3600         # Run batch cleanup every hour
       RECURRING_CLEANUP_INTERVAL = 3600     # Run recurring execution cleanup every hour
+      ARCHIVE_COMPACTION_INTERVAL = 3600    # Run archive compaction every hour
+      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
 
       attr_reader :config
 
@@ -22,6 +26,10 @@ module Pgbus
         @last_concurrency_at = Time.now
         @last_batch_cleanup_at = Time.now
         @last_recurring_cleanup_at = Time.now
+        @last_archive_compaction_at = Time.now
+        @last_outbox_cleanup_at = Time.now
+        @last_job_lock_cleanup_at = Time.now
+        @last_stats_cleanup_at = Time.now
       end
 
       def run
@@ -64,6 +72,10 @@ module Pgbus
         run_if_due(now, :@last_concurrency_at, CONCURRENCY_INTERVAL) { cleanup_concurrency }
         run_if_due(now, :@last_batch_cleanup_at, BATCH_CLEANUP_INTERVAL) { cleanup_batches }
         run_if_due(now, :@last_recurring_cleanup_at, RECURRING_CLEANUP_INTERVAL) { cleanup_recurring_executions }
+        run_if_due(now, :@last_archive_compaction_at, archive_compaction_interval) { compact_archives }
+        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 }
       end
 
       # Only update the timestamp when the block succeeds.
@@ -121,6 +133,69 @@ module Pgbus
         Pgbus.logger.warn { "[Pgbus] Batch cleanup failed: #{e.message}" }
       end
 
+      def cleanup_stats
+        return unless config.stats_enabled
+
+        retention = config.stats_retention
+        return unless retention&.positive?
+
+        deleted = JobStat.cleanup!(older_than: Time.now.utc - retention)
+        Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} old job stats" } if deleted.positive?
+      end
+
+      def cleanup_job_locks
+        # Primary: reap orphaned locks whose owner worker is no longer alive.
+        # Cross-references (owner_pid, owner_hostname) against pgbus_processes heartbeats.
+        reaped = JobLock.reap_orphaned!
+        Pgbus.logger.info { "[Pgbus] Reaped #{reaped} orphaned job locks" } if reaped.positive?
+
+        # Last resort: clean up locks with expired TTL (handles case where
+        # even the reaper/supervisor is dead and locks are truly abandoned).
+        expired = JobLock.cleanup_expired!
+        Pgbus.logger.debug { "[Pgbus] Cleaned up #{expired} expired job locks" } if expired.positive?
+        # No rescue here — let run_if_due handle the error and retry next tick
+      end
+
+      def cleanup_outbox
+        return unless config.outbox_enabled
+
+        retention = config.outbox_retention
+        return unless retention&.positive?
+
+        deleted = OutboxEntry.published_before(Time.now.utc - retention).delete_all
+        Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} published outbox entries" } if deleted.positive?
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Outbox cleanup failed: #{e.message}" }
+      end
+
+      def archive_compaction_interval
+        config.archive_compaction_interval || ARCHIVE_COMPACTION_INTERVAL
+      end
+
+      def compact_archives
+        retention = config.archive_retention
+        return unless retention&.positive?
+
+        cutoff = Time.now.utc - retention
+        batch_size = config.archive_compaction_batch_size || 1000
+        prefix = config.queue_prefix
+
+        conn = config.connects_to ? Pgbus::ApplicationRecord.connection : ActiveRecord::Base.connection
+        queue_names = conn.select_values("SELECT queue_name FROM pgmq.meta ORDER BY queue_name")
+
+        queue_names.each do |full_name|
+          next unless full_name.start_with?("#{prefix}_")
+
+          stripped = full_name.delete_prefix("#{prefix}_")
+          deleted = Pgbus.client.purge_archive(stripped, older_than: cutoff, batch_size: batch_size)
+          Pgbus.logger.debug { "[Pgbus] Compacted #{deleted} archive entries from #{full_name}" } if deleted.positive?
+        rescue StandardError => e
+          Pgbus.logger.warn { "[Pgbus] Archive compaction failed for #{full_name}: #{e.message}" }
+        end
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Archive compaction failed: #{e.message}" }
+      end
+
       def cleanup_recurring_executions
         retention = config.recurring_execution_retention
         return unless retention&.positive?

data/lib/pgbus/process/heartbeat.rb

@@ -11,9 +11,10 @@ module Pgbus
 
       attr_reader :process_entry
 
-      def initialize(kind:, metadata: {})
+      def initialize(kind:, metadata: {}, on_beat: nil)
         @kind = kind
         @metadata = metadata
+        @on_beat = on_beat
         @timer = nil
       end
 
@@ -31,6 +32,7 @@ module Pgbus
       def beat
         return unless @process_id
 
+        @on_beat&.call
         ProcessEntry.where(id: @process_id).update_all(last_heartbeat_at: Time.current)
       rescue StandardError => e
         Pgbus.logger.warn { "[Pgbus] Heartbeat failed: #{e.message}" }

data/lib/pgbus/process/lifecycle.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Pgbus
+  module Process
+    # Thread-safe worker lifecycle state machine inspired by LavinMQ's QueueState.
+    #
+    # States:
+    #   :starting  → initial state, setting up
+    #   :running   → actively processing messages
+    #   :paused    → temporarily stopped (manual or circuit breaker)
+    #   :draining  → finishing in-flight work before stopping
+    #   :stopped   → terminal state
+    #
+    # Transitions:
+    #   starting → running
+    #   running  → paused | draining | stopped
+    #   paused   → running | draining | stopped
+    #   draining → stopped
+    class Lifecycle
+      STATES = %i[starting running paused draining stopped].freeze
+
+      TRANSITIONS = {
+        starting: %i[running stopped],
+        running: %i[paused draining stopped],
+        paused: %i[running draining stopped],
+        draining: %i[stopped],
+        stopped: []
+      }.freeze
+
+      attr_reader :state
+
+      def initialize
+        @state = :starting
+        @mutex = Mutex.new
+        @callbacks = Hash.new { |h, k| h[k] = [] }
+      end
+
+      def transition_to!(new_state)
+        @mutex.synchronize do
+          validate_transition!(new_state)
+          old_state = @state
+          @state = new_state
+          fire_callbacks(old_state, new_state)
+          new_state
+        end
+      end
+
+      def transition_to(new_state)
+        transition_to!(new_state)
+      rescue InvalidTransition
+        false
+      end
+
+      def on(event, &block)
+        @callbacks[event] << block
+      end
+
+      def starting?
+        @state == :starting
+      end
+
+      def running?
+        @state == :running
+      end
+
+      def paused?
+        @state == :paused
+      end
+
+      def draining?
+        @state == :draining
+      end
+
+      def stopped?
+        @state == :stopped
+      end
+
+      def active?
+        running? || paused?
+      end
+
+      def can_process?
+        running?
+      end
+
+      def terminal?
+        stopped?
+      end
+
+      private
+
+      def validate_transition!(new_state)
+        raise ArgumentError, "Unknown state: #{new_state}. Valid states: #{STATES.join(", ")}" unless STATES.include?(new_state)
+
+        return if TRANSITIONS[@state].include?(new_state)
+
+        raise InvalidTransition, "Cannot transition from #{@state} to #{new_state}. " \
+                                 "Valid transitions: #{TRANSITIONS[@state].join(", ")}"
+      end
+
+      def fire_callbacks(old_state, new_state)
+        @callbacks[:"#{old_state}_to_#{new_state}"].each(&:call)
+        @callbacks[:any].each { |cb| cb.call(old_state, new_state) }
+      end
+    end
+
+    class InvalidTransition < Pgbus::Error; end
+  end
+end

data/lib/pgbus/process/queue_lock.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Pgbus
+  module Process
+    # Manages PostgreSQL advisory locks for single-active-consumer mode.
+    # Only one worker process can hold the lock for a given queue at a time.
+    # Other workers skip the queue and process other queues instead.
+    #
+    # Uses pg_try_advisory_lock (non-blocking) so workers never wait —
+    # they simply skip queues they can't lock and try again next cycle.
+    #
+    # Locks are session-level and automatically released when the connection
+    # closes (including on crash), so no manual cleanup is needed.
+    class QueueLock
+      # Use a fixed namespace to avoid collision with application advisory locks.
+      # CRC32 of "pgbus_queue_lock" = 0x5067_6275
+      LOCK_NAMESPACE = 0x5067_6275
+
+      def initialize
+        @held_locks = Concurrent::Map.new
+      end
+
+      # Try to acquire an advisory lock for the given queue name.
+      # Returns true if acquired (or already held), false if another process holds it.
+      def try_lock(queue_name)
+        return true if @held_locks[queue_name]
+
+        lock_id = lock_id_for(queue_name)
+        acquired = connection.select_value(
+          "SELECT pg_try_advisory_lock(#{LOCK_NAMESPACE}, #{lock_id})"
+        )
+
+        if acquired
+          @held_locks[queue_name] = lock_id
+          true
+        else
+          false
+        end
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Advisory lock failed for #{queue_name}: #{e.message}" }
+        false
+      end
+
+      # Release the advisory lock for a queue. Called during shutdown.
+      def unlock(queue_name)
+        lock_id = @held_locks.delete(queue_name)
+        return unless lock_id
+
+        connection.select_value(
+          "SELECT pg_advisory_unlock(#{LOCK_NAMESPACE}, #{lock_id})"
+        )
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Advisory unlock failed for #{queue_name}: #{e.message}" }
+      end
+
+      # Release all held locks.
+      def unlock_all
+        @held_locks.each_key { |q| unlock(q) }
+      end
+
+      def locked?(queue_name)
+        @held_locks.key?(queue_name)
+      end
+
+      def held_queues
+        @held_locks.keys
+      end
+
+      private
+
+      def lock_id_for(queue_name)
+        # Use a stable hash to convert queue name to a 32-bit integer
+        Zlib.crc32(queue_name.to_s) & 0x7FFFFFFF
+      end
+
+      def connection
+        if Pgbus.configuration.connects_to
+          Pgbus::ApplicationRecord.connection
+        else
+          ActiveRecord::Base.connection
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/process/supervisor.rb

@@ -55,17 +55,25 @@ module Pgbus
 
         # Boot event consumers if configured
         boot_consumers
+
+        # Boot outbox poller if configured
+        boot_outbox_poller
       end
 
       def fork_worker(worker_config)
         queues = worker_config[:queues] || worker_config["queues"] || [config.default_queue]
         threads = worker_config[:threads] || worker_config["threads"] || 5
+        single_active = worker_config[:single_active_consumer] || worker_config["single_active_consumer"] || false
+        priority = worker_config[:consumer_priority] || worker_config["consumer_priority"] || 0
 
         pid = fork do
           restore_signals
-          setup_child_signals
+          setup_child_process
           load_rails_app
-          worker = Worker.new(queues: queues, threads: threads, config: config)
+          worker = Worker.new(
+            queues: queues, threads: threads, config: config,
+            single_active_consumer: single_active, consumer_priority: priority
+          )
           worker.run
         end
 
@@ -83,7 +91,7 @@ module Pgbus
       def fork_dispatcher
         pid = fork do
           restore_signals
-          setup_child_signals
+          setup_child_process
           load_rails_app
           dispatcher = Dispatcher.new(config: config)
           dispatcher.run
@@ -110,7 +118,7 @@ module Pgbus
       def fork_scheduler
         pid = fork do
           restore_signals
-          setup_child_signals
+          setup_child_process
           load_rails_app
           load_recurring_config
           scheduler = Recurring::Scheduler.new(config: config)
@@ -165,7 +173,7 @@ module Pgbus
 
         pid = fork do
           restore_signals
-          setup_child_signals
+          setup_child_process
           load_rails_app
           consumer = Consumer.new(topics: topics, threads: threads, config: config)
           consumer.run
@@ -182,6 +190,32 @@ module Pgbus
         Pgbus.logger.error { "[Pgbus] Fork failed for consumer: #{e.message}" }
       end
 
+      def boot_outbox_poller
+        return unless config.outbox_enabled
+
+        fork_outbox_poller
+      end
+
+      def fork_outbox_poller
+        pid = fork do
+          restore_signals
+          setup_child_process
+          load_rails_app
+          poller = Outbox::Poller.new(config: config)
+          poller.run
+        end
+
+        unless pid
+          Pgbus.logger.error { "[Pgbus] Failed to fork outbox poller" }
+          return
+        end
+
+        @forks[pid] = { type: :outbox_poller }
+        Pgbus.logger.info { "[Pgbus] Forked outbox poller pid=#{pid}" }
+      rescue Errno::EAGAIN, Errno::ENOMEM => e
+        Pgbus.logger.error { "[Pgbus] Fork failed for outbox poller: #{e.message}" }
+      end
+
       def monitor_loop
         loop do
           break if @shutting_down && @forks.empty?
@@ -223,6 +257,8 @@ module Pgbus
           fork_scheduler
         when :consumer
           fork_consumer(info[:config])
+        when :outbox_poller
+          fork_outbox_poller
         end
       end
 
@@ -234,7 +270,11 @@ module Pgbus
         end
       end
 
-      def setup_child_signals
+      def setup_child_process
+        # Reset the PGMQ client so this forked process gets a fresh
+        # PG::Connection instead of inheriting the parent's (which is
+        # in undefined state post-fork and not thread-safe to share).
+        Pgbus.reset_client!
         %w[INT TERM QUIT].each do |sig|
           trap(sig) { @shutting_down = true }
         end

data/lib/pgbus/process/wake_signal.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Pgbus
+  module Process
+    # Wake signal inspired by LavinMQ's BoolChannel pattern.
+    # Replaces polling-based coordination with instant state-change signaling.
+    #
+    # IMPORTANT: Single-waiter only. The +wait+ method calls @event.reset
+    # immediately after waking, which means concurrent waiters may miss
+    # notifications. Callers must ensure only one thread calls +wait+ at
+    # a time. In pgbus this is guaranteed because each Worker has exactly
+    # one main loop thread that calls +wait+, while +notify!+ can be
+    # called from any thread (signal handlers, lifecycle transitions).
+    #
+    # Usage:
+    #   signal = WakeSignal.new
+    #   # In worker thread (single waiter):
+    #   signal.wait(timeout: 5)  # blocks until signaled or timeout
+    #   # In another thread (e.g. signal handler, lifecycle transition):
+    #   signal.notify!           # wakes the waiting thread
+    class WakeSignal
+      def initialize
+        @event = Concurrent::Event.new
+      end
+
+      # Block until +notify!+ is called or timeout expires.
+      # Returns true if signaled, false if timed out.
+      # Resets the event after waking — only safe with a single waiter.
+      def wait(timeout: nil)
+        result = @event.wait(timeout)
+        @event.reset
+        result
+      end
+
+      # Wake all waiting threads immediately.
+      def notify!
+        @event.set
+      end
+
+      # Check if a notification is pending without blocking.
+      def pending?
+        @event.set?
+      end
+
+      # Clear the pending notification.
+      def reset!
+        @event.reset
+      end
+    end
+  end
+end