pgbus 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b8f740d2e7c3b561a9591c94d08aef98b22566a3f56517c3055e4fab2c76f98
-  data.tar.gz: a6ee24b79ade13317966dee815a49c1d03b2b290dd7635751fa070216fee7d0b
+  metadata.gz: f7594e67d8f35115e8a8498a64c766a37bd2705f62ee0414471ac08370596d51
+  data.tar.gz: 31048f0243cf7eddf24e49a79fee753390051637b1173534891d7155c42fc734
 SHA512:
-  metadata.gz: 4df75c29bc7aa63b4a37b6425f9adf333d0986225ee99d65b33a125fd12c23f03a4000b5a38a610c39c46608622cb4dce5998864dff16942aa223d0671f006bf
-  data.tar.gz: a8da2aafd4259b0a73502201aad5542ca31a8d7299e9b84e6e62f3413d62582febd947e1b748024fd09975d1e9b8d2efd16601b278367d6a69feb6e8456ad6d0
+  metadata.gz: 2351357593c783a226b0dccda08f278c2ddf7ab40f2d727bf7c3d5366e3a24aa3ae79670f0a09d867f1f774350e6677e17960d9fd90b46d4be94f7bf4085ba96
+  data.tar.gz: 2e427fc91be9934d37ec6bc21a0e1ffec5be034fdc31ead152c3c86006805778ee3ed9e5490df112c659e2f9f7363333b35889f1dc9374cf1bb0f3069ade65c4

data/app/controllers/pgbus/outbox_controller.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class OutboxController < ApplicationController
+    def index
+      @stats = data_source.outbox_stats
+      @entries = data_source.outbox_entries(page: page_param, per_page: per_page)
+    end
+  end
+end

data/app/controllers/pgbus/queues_controller.rb

@@ -17,5 +17,15 @@ module Pgbus
       data_source.purge_queue(params[:name])
       redirect_to queue_path(name: params[:name]), notice: "Queue purged."
     end
+
+    def pause
+      data_source.pause_queue(params[:name], reason: params[:reason])
+      redirect_to queue_path(name: params[:name]), notice: "Queue paused."
+    end
+
+    def resume
+      data_source.resume_queue(params[:name])
+      redirect_to queue_path(name: params[:name]), notice: "Queue resumed."
+    end
   end
 end

data/app/helpers/pgbus/application_helper.rb

@@ -45,6 +45,12 @@ module Pgbus
       end
     end
 
+    def pgbus_paused_badge(paused)
+      return unless paused
+
+      tag.span("Paused", class: "inline-flex items-center rounded-full bg-yellow-100 px-2 py-0.5 text-xs font-medium text-yellow-800")
+    end
+
     def pgbus_parse_message(message)
       return {} unless message
 

data/app/models/pgbus/outbox_entry.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class OutboxEntry < Pgbus::ApplicationRecord
+    self.table_name = "pgbus_outbox_entries"
+
+    scope :unpublished, -> { where(published_at: nil) }
+    scope :published_before, ->(time) { where(published_at: ...time) }
+  end
+end

data/app/models/pgbus/queue_state.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class QueueState < Pgbus::ApplicationRecord
+    self.table_name = "pgbus_queue_states"
+
+    scope :paused, -> { where(paused: true) }
+
+    def self.paused?(queue_name)
+      where(queue_name: queue_name, paused: true).exists?
+    end
+
+    def self.pause!(queue_name, reason: nil)
+      record = find_or_initialize_by(queue_name: queue_name)
+      record.update!(paused: true, paused_reason: reason, paused_at: Time.current, circuit_breaker_resume_at: nil)
+      record
+    end
+
+    def self.resume!(queue_name)
+      record = find_by(queue_name: queue_name)
+      return unless record
+
+      record.update!(
+        paused: false,
+        paused_reason: nil,
+        paused_at: nil,
+        circuit_breaker_trip_count: 0,
+        circuit_breaker_resume_at: nil
+      )
+      record
+    end
+  end
+end

data/app/views/layouts/pgbus/application.html.erb

@@ -46,6 +46,7 @@
               <%= pgbus_nav_link "Processes", pgbus.processes_path %>
               <%= pgbus_nav_link "Events", pgbus.events_path %>
               <%= pgbus_nav_link "DLQ", pgbus.dead_letter_index_path %>
+              <%= pgbus_nav_link "Outbox", pgbus.outbox_index_path %>
             </div>
           </div>
         </div>

data/app/views/pgbus/dashboard/_stats_cards.html.erb

@@ -1,5 +1,5 @@
 <turbo-frame id="dashboard-stats" data-auto-refresh src="<%= pgbus.root_path(frame: 'stats') %>">
-  <div class="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-5 mb-8">
+  <div class="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-6 mb-8">
     <div class="rounded-lg bg-white p-5 shadow ring-1 ring-gray-200">
       <p class="text-sm font-medium text-gray-500">Queues</p>
       <p class="mt-1 text-3xl font-semibold text-gray-900"><%= @stats[:total_queues] %></p>
@@ -32,5 +32,11 @@
         <%= @stats[:failed_count] %> / <%= @stats[:dlq_depth] %>
       </p>
     </div>
+
+    <div class="rounded-lg bg-white p-5 shadow ring-1 ring-gray-200">
+      <p class="text-sm font-medium text-gray-500">Throughput</p>
+      <p class="mt-1 text-3xl font-semibold text-gray-900"><%= @stats[:throughput_rate] %></p>
+      <p class="text-xs text-gray-400">msgs/s</p>
+    </div>
   </div>
 </turbo-frame>

data/app/views/pgbus/outbox/index.html.erb

@@ -0,0 +1,55 @@
+<div class="mb-6">
+  <h1 class="text-2xl font-bold text-gray-900">Outbox</h1>
+  <p class="mt-1 text-sm text-gray-500">Transactional outbox entries pending publication to PGMQ</p>
+</div>
+
+<div class="mb-6 grid grid-cols-3 gap-4">
+  <div class="rounded-lg bg-white p-4 shadow ring-1 ring-gray-200">
+    <dt class="text-xs font-medium uppercase text-gray-500">Unpublished</dt>
+    <dd class="mt-1 text-2xl font-semibold text-gray-900"><%= pgbus_number(@stats[:unpublished]) %></dd>
+  </div>
+  <div class="rounded-lg bg-white p-4 shadow ring-1 ring-gray-200">
+    <dt class="text-xs font-medium uppercase text-gray-500">Total</dt>
+    <dd class="mt-1 text-2xl font-semibold text-gray-900"><%= pgbus_number(@stats[:total]) %></dd>
+  </div>
+  <div class="rounded-lg bg-white p-4 shadow ring-1 ring-gray-200">
+    <dt class="text-xs font-medium uppercase text-gray-500">Oldest Unpublished</dt>
+    <dd class="mt-1 text-2xl font-semibold text-gray-900"><%= @stats[:oldest_unpublished_age] ? "#{@stats[:oldest_unpublished_age]}s" : "—" %></dd>
+  </div>
+</div>
+
+<div class="overflow-hidden rounded-lg bg-white shadow ring-1 ring-gray-200">
+  <table class="min-w-full divide-y divide-gray-200">
+    <thead class="bg-gray-50">
+      <tr>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">ID</th>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">Queue / Topic</th>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">Payload</th>
+        <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500">Priority</th>
+        <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500">Status</th>
+        <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500">Created</th>
+      </tr>
+    </thead>
+    <tbody class="divide-y divide-gray-100">
+      <% @entries.each do |entry| %>
+        <tr class="hover:bg-gray-50">
+          <td class="px-4 py-3 text-sm font-mono text-gray-700"><%= entry.id %></td>
+          <td class="px-4 py-3 text-sm text-gray-700"><%= entry.routing_key || entry.queue_name %></td>
+          <td class="px-4 py-3 text-sm text-gray-500 max-w-xs truncate"><%= pgbus_json_preview(entry.payload) %></td>
+          <td class="px-4 py-3 text-sm text-right text-gray-500"><%= entry.priority %></td>
+          <td class="px-4 py-3 text-sm text-right">
+            <% if entry.published_at %>
+              <span class="inline-flex items-center rounded-full bg-green-100 px-2 py-0.5 text-xs font-medium text-green-800">Published</span>
+            <% else %>
+              <span class="inline-flex items-center rounded-full bg-yellow-100 px-2 py-0.5 text-xs font-medium text-yellow-800">Pending</span>
+            <% end %>
+          </td>
+          <td class="px-4 py-3 text-sm text-right text-gray-500"><%= pgbus_time_ago(entry.created_at) %></td>
+        </tr>
+      <% end %>
+      <% if @entries.empty? %>
+        <tr><td colspan="6" class="px-4 py-8 text-center text-sm text-gray-400">No outbox entries</td></tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>

data/app/views/pgbus/queues/_queues_list.html.erb

@@ -18,13 +18,27 @@
             <td class="px-4 py-3 text-sm">
               <%= link_to q[:name], pgbus.queue_path(name: q[:name]), class: "font-medium text-indigo-600 hover:text-indigo-500", data: { turbo_frame: "_top" } %>
               <%= pgbus_queue_badge(q[:name]) %>
+              <% if q[:paused] %>
+                <span class="inline-flex items-center rounded-full bg-yellow-100 px-2 py-0.5 text-xs font-medium text-yellow-800">Paused</span>
+              <% end %>
             </td>
             <td class="px-4 py-3 text-sm text-right font-mono text-gray-700"><%= pgbus_number(q[:queue_length]) %></td>
             <td class="px-4 py-3 text-sm text-right font-mono text-gray-700"><%= pgbus_number(q[:queue_visible_length]) %></td>
             <td class="px-4 py-3 text-sm text-right text-gray-500"><%= q[:oldest_msg_age_sec] || "—" %></td>
             <td class="px-4 py-3 text-sm text-right text-gray-500"><%= q[:newest_msg_age_sec] || "—" %></td>
             <td class="px-4 py-3 text-sm text-right text-gray-500"><%= pgbus_number(q[:total_messages]) %></td>
-            <td class="px-4 py-3 text-sm text-right">
+            <td class="px-4 py-3 text-sm text-right space-x-2">
+              <% if q[:paused] %>
+                <%= button_to "Resume", pgbus.resume_queue_path(name: q[:name]),
+                      method: :post,
+                      class: "text-xs text-green-600 hover:text-green-800 font-medium",
+                      data: { turbo_frame: "_top" } %>
+              <% else %>
+                <%= button_to "Pause", pgbus.pause_queue_path(name: q[:name]),
+                      method: :post,
+                      class: "text-xs text-yellow-600 hover:text-yellow-800 font-medium",
+                      data: { turbo_confirm: "Pause processing for #{q[:name]}?", turbo_frame: "_top" } %>
+              <% end %>
               <%= button_to "Purge", pgbus.purge_queue_path(name: q[:name]),
                     method: :post,
                     class: "text-xs text-red-600 hover:text-red-800 font-medium",

data/config/routes.rb

@@ -6,6 +6,8 @@ Pgbus::Engine.routes.draw do
   resources :queues, only: %i[index show], param: :name do
     member do
       post :purge
+      post :pause
+      post :resume
     end
   end
 
@@ -46,6 +48,8 @@ Pgbus::Engine.routes.draw do
     end
   end
 
+  resources :outbox, only: [:index], controller: "outbox"
+
   namespace :api do
     get :stats, to: "stats#show"
   end

data/lib/generators/pgbus/add_outbox_generator.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Pgbus
+  module Generators
+    class AddOutboxGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Add outbox table for transactional event publishing"
+
+      class_option :database,
+                   type: :string,
+                   default: nil,
+                   desc: "Use a separate database for pgbus tables (e.g. --database=pgbus)"
+
+      def create_migration
+        if separate_database?
+          migration_template "add_outbox.rb.erb",
+                             "db/pgbus_migrate/add_pgbus_outbox.rb"
+        else
+          migration_template "add_outbox.rb.erb",
+                             "db/migrate/add_pgbus_outbox.rb"
+        end
+      end
+
+      def display_post_install
+        say ""
+        say "Pgbus outbox installed!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  2. Enable in config: config.outbox_enabled = true"
+        say "  3. Restart pgbus: bin/pgbus start"
+        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/add_queue_states_generator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Pgbus
+  module Generators
+    class AddQueueStatesGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Add queue states table for pause/resume and circuit breaker support"
+
+      class_option :database,
+                   type: :string,
+                   default: nil,
+                   desc: "Use a separate database for pgbus tables (e.g. --database=pgbus)"
+
+      def create_migration
+        if separate_database?
+          migration_template "add_queue_states.rb.erb",
+                             "db/pgbus_migrate/add_pgbus_queue_states.rb"
+        else
+          migration_template "add_queue_states.rb.erb",
+                             "db/migrate/add_pgbus_queue_states.rb"
+        end
+      end
+
+      def display_post_install
+        say ""
+        say "Pgbus queue states table installed!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  2. Restart pgbus: bin/pgbus start"
+        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_outbox.rb.erb

@@ -0,0 +1,25 @@
+class AddPgbusOutbox < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :pgbus_outbox_entries do |t|
+      t.string :queue_name
+      t.string :routing_key
+      t.jsonb :payload, null: false
+      t.jsonb :headers
+      t.integer :priority, default: 0
+      t.integer :delay, default: 0
+      t.datetime :published_at
+      t.datetime :created_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+    end
+
+    add_check_constraint :pgbus_outbox_entries,
+      "(queue_name IS NOT NULL) <> (routing_key IS NOT NULL)",
+      name: "chk_pgbus_outbox_destination"
+
+    add_index :pgbus_outbox_entries, :published_at,
+      where: "published_at IS NULL",
+      name: "idx_pgbus_outbox_unpublished"
+    add_index :pgbus_outbox_entries, :published_at,
+      where: "published_at IS NOT NULL",
+      name: "idx_pgbus_outbox_cleanup"
+  end
+end

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

@@ -0,0 +1,16 @@
+class AddPgbusQueueStates < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :pgbus_queue_states do |t|
+      t.string :queue_name, null: false
+      t.boolean :paused, null: false, default: false
+      t.string :paused_reason
+      t.datetime :paused_at
+      t.integer :circuit_breaker_trip_count, default: 0
+      t.datetime :circuit_breaker_resume_at
+      t.timestamps
+    end
+
+    add_index :pgbus_queue_states, :queue_name,
+      unique: true, name: "idx_pgbus_queue_states_queue_name"
+  end
+end

data/lib/pgbus/active_job/adapter.rb

@@ -38,18 +38,19 @@ module Pgbus
       def enqueue_with_concurrency(active_job, queue, payload_hash, delay: 0)
         key = Concurrency.extract_key(payload_hash)
         concurrency = concurrency_config(active_job)
+        priority = active_job.try(:priority)
 
         if key && concurrency
           result = Concurrency::Semaphore.acquire(key, concurrency[:limit], concurrency[:duration])
 
           if result == :acquired
-            msg_id = Pgbus.client.send_message(queue, payload_hash, delay: delay)
+            msg_id = Pgbus.client.send_message(queue, payload_hash, delay: delay, priority: priority)
             active_job.provider_job_id = msg_id
           else
-            handle_conflict(concurrency, active_job, key, queue, payload_hash)
+            handle_conflict(concurrency, active_job, key, queue, payload_hash, priority: priority)
           end
         else
-          msg_id = Pgbus.client.send_message(queue, payload_hash, delay: delay)
+          msg_id = Pgbus.client.send_message(queue, payload_hash, delay: delay, priority: priority)
           active_job.provider_job_id = msg_id
         end
 
@@ -63,14 +64,14 @@ module Pgbus
         active_job.class.respond_to?(:pgbus_concurrency) && active_job.class.pgbus_concurrency
       end
 
-      def handle_conflict(concurrency, active_job, key, queue, payload_hash)
+      def handle_conflict(concurrency, active_job, key, queue, payload_hash, priority: nil)
         case concurrency[:on_conflict]
         when :block
           Concurrency::BlockedExecution.insert(
             concurrency_key: key,
             queue_name: queue,
             payload: payload_hash,
-            priority: active_job.try(:priority) || 0,
+            priority: priority || Pgbus.configuration.default_priority,
             duration: concurrency[:duration]
           )
         when :discard

data/lib/pgbus/active_job/executor.rb

@@ -10,12 +10,12 @@ module Pgbus
         @config = config
       end
 
-      def execute(message, queue_name)
+      def execute(message, queue_name, source_queue: nil)
         payload = JSON.parse(message.message)
         read_count = message.read_ct.to_i
 
         if read_count > config.max_retries
-          handle_dead_letter(message, queue_name, payload)
+          handle_dead_letter(message, queue_name, payload, source_queue: source_queue)
           signal_concurrency(payload)
           signal_batch_discarded(payload)
           return :dead_lettered
@@ -28,7 +28,7 @@ module Pgbus
         Instrumentation.instrument("pgbus.executor.execute", queue: queue_name, job_class: job_class) do
           job = ::ActiveJob::Base.deserialize(payload)
           execute_job(job)
-          client.archive_message(queue_name, message.msg_id.to_i)
+          archive_from(queue_name, message.msg_id.to_i, source_queue: source_queue)
           job_succeeded = true
         end
 
@@ -109,12 +109,29 @@ module Pgbus
         Pgbus.logger.warn { "[Pgbus] Batch discard signal failed: #{e.message}" }
       end
 
-      def handle_dead_letter(message, queue_name, payload)
+      def archive_from(queue_name, msg_id, source_queue: nil)
+        if source_queue
+          client.archive_from_queue(source_queue, msg_id)
+        else
+          client.archive_message(queue_name, msg_id)
+        end
+      end
+
+      def handle_dead_letter(message, queue_name, payload, source_queue: nil)
         Pgbus.logger.warn do
           job_class = payload["job_class"] || "unknown"
           "[Pgbus] Moving job #{job_class} to dead letter queue after #{message.read_ct} attempts"
         end
-        client.move_to_dead_letter(queue_name, message)
+        if source_queue
+          client.ensure_dead_letter_queue(queue_name)
+          dlq_name = config.dead_letter_queue_name(queue_name)
+          client.transaction do |txn|
+            txn.produce(dlq_name, message.message, headers: message.headers)
+            txn.delete(source_queue, message.msg_id.to_i)
+          end
+        else
+          client.move_to_dead_letter(queue_name, message)
+        end
       end
     end
   end

data/lib/pgbus/circuit_breaker.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Pgbus
+  class CircuitBreaker
+    attr_reader :config
+
+    def initialize(config: Pgbus.configuration)
+      @config = config
+      @failure_counts = Concurrent::Map.new
+      @pause_cache = Concurrent::Map.new
+      @pause_cache_ttl = 30 # seconds
+    end
+
+    def record_success(queue_name)
+      @failure_counts.delete(queue_name)
+    end
+
+    def record_failure(queue_name)
+      return unless config.circuit_breaker_enabled
+
+      count = @failure_counts.compute(queue_name) { |val| (val || 0) + 1 }
+
+      return unless count >= config.circuit_breaker_threshold
+
+      trip!(queue_name, count)
+    end
+
+    def paused?(queue_name)
+      cached = @pause_cache[queue_name]
+      return cached[:paused] if cached && (Time.now - cached[:checked_at]) < @pause_cache_ttl
+
+      paused = check_paused(queue_name)
+      @pause_cache[queue_name] = { paused: paused, checked_at: Time.now }
+      paused
+    end
+
+    def pause!(queue_name, reason: nil)
+      QueueState.pause!(queue_name, reason: reason)
+      invalidate_cache(queue_name)
+    end
+
+    def resume!(queue_name)
+      QueueState.resume!(queue_name)
+      @failure_counts.delete(queue_name)
+      invalidate_cache(queue_name)
+    end
+
+    def invalidate_cache(queue_name = nil)
+      if queue_name
+        @pause_cache.delete(queue_name)
+      else
+        @pause_cache.clear
+      end
+    end
+
+    private
+
+    def trip!(queue_name, failure_count)
+      trip_count = current_trip_count(queue_name) + 1
+      backoff = calculate_backoff(trip_count)
+      resume_at = Time.current + backoff
+
+      Pgbus.logger.warn do
+        "[Pgbus] Circuit breaker tripped for #{queue_name}: #{failure_count} consecutive failures, " \
+          "backoff #{backoff}s (trip ##{trip_count})"
+      end
+
+      QueueState.find_or_initialize_by(queue_name: queue_name).update!(
+        paused: true,
+        paused_reason: "circuit_breaker: #{failure_count} consecutive failures",
+        paused_at: Time.current,
+        circuit_breaker_trip_count: trip_count,
+        circuit_breaker_resume_at: resume_at
+      )
+
+      @failure_counts.delete(queue_name)
+      invalidate_cache(queue_name)
+    rescue StandardError => e
+      Pgbus.logger.error { "[Pgbus] Circuit breaker trip failed for #{queue_name}: #{e.message}" }
+    end
+
+    def check_paused(queue_name)
+      state = QueueState.find_by(queue_name: queue_name)
+      return false unless state&.paused?
+
+      # Auto-resume if circuit breaker backoff has expired
+      if state.circuit_breaker_resume_at && Time.current >= state.circuit_breaker_resume_at
+        QueueState.resume!(queue_name)
+        Pgbus.logger.info { "[Pgbus] Circuit breaker auto-resumed #{queue_name}" }
+        return false
+      end
+
+      true
+    rescue StandardError => e
+      Pgbus.logger.warn { "[Pgbus] Circuit breaker pause check failed for #{queue_name}: #{e.message}" }
+      false
+    end
+
+    def current_trip_count(queue_name)
+      QueueState.find_by(queue_name: queue_name)&.circuit_breaker_trip_count || 0
+    rescue StandardError
+      0
+    end
+
+    def calculate_backoff(trip_count)
+      backoff = config.circuit_breaker_base_backoff * (2**(trip_count - 1))
+      [backoff, config.circuit_breaker_max_backoff].min
+    end
+  end
+end