pgbus 0.9.8 → 0.9.9

data/lib/pgbus/web/streamer/listener.rb

@@ -19,10 +19,11 @@ module Pgbus
       #
       # Health check: `wait_for_notify(timeout)` returns nil on timeout. When
       # it does, the listener runs `SELECT 1` as a TCP keepalive. If that
-      # raises, the connection is reset (`conn.reset`) and every channel in
-      # `@listening_to` is re-LISTENed. This is the fix for design doc §11 #1
-      # (silently dropped LISTEN connections from NAT / PG restart / network
-      # blips).
+      # raises, the listener rebuilds a FRESH connection via connection_factory
+      # and re-LISTENs every channel in `@listening_to`. This is the fix for
+      # design doc §11 #1 (silently dropped LISTEN connections from NAT / PG
+      # restart / network blips) — a fresh connect also re-resolves DNS and
+      # converges on the promoted primary after a failover.
       #
       # NOTIFY channel naming (from pgmq_v1.11.0.sql:1634):
       #   PG_NOTIFY('pgmq.' || TG_TABLE_NAME || '.' || TG_OP, NULL)
@@ -42,12 +43,15 @@ module Pgbus
 
         attr_reader :listening_to
 
-        # @param connection_factory [#call, nil] builds a FRESH PG connection on
-        #   each reconnect attempt (the Instance passes -> { build_pg_connection }).
-        #   When nil (tests injecting only pg_connection:), reconnect falls back to
-        #   the legacy single-shot @conn.reset.
+        # @param connection_factory [#call] builds a FRESH PG connection on each
+        #   reconnect attempt (the Instance passes -> { build_raw_pg_connection }).
+        #   Required — the reconnect loop always rebuilds rather than resetting a
+        #   possibly-dead socket, so every caller (production and tests) must pass
+        #   one.
         def initialize(pg_connection:, dispatch_queue:, health_check_ms:,
-                       logger: Pgbus.logger, connection_factory: nil)
+                       connection_factory:, logger: Pgbus.logger)
+          raise ArgumentError, "connection_factory is required" unless connection_factory.respond_to?(:call)
+
           @conn = pg_connection
           @dispatch_queue = dispatch_queue
           @health_check_ms = health_check_ms
@@ -210,11 +214,8 @@ module Pgbus
         # NotifyListener#reconnect!: a single failed attempt never returns with
         # a dead connection while running, so ensure_listening acks can't
         # succeed vacuously against a broken LISTEN socket and strand SSE
-        # clients. When no connection_factory was injected (tests passing only
-        # pg_connection:), fall back to the legacy single-shot conn.reset.
+        # clients.
         def reconnect!
-          return reconnect_via_reset unless @connection_factory
-
           # Snapshot the canonical subscription set BEFORE tearing down the old
           # connection. We rebuild @listening_to from this and only publish it
           # once every channel has been re-LISTENed on the new conn, so a
@@ -234,10 +235,13 @@ module Pgbus
               # primary; re-LISTENing on a replica registers channels that never wake.
               Pgbus::Process::PrimaryValidator.validate_primary!(new_conn)
               channels.each { |channel| new_conn.exec(%(LISTEN "#{channel}")) }
-            rescue PG::Error, Pgbus::Process::ReplicaConnectionError => e
-              # The factory may have returned a live conn before a later LISTEN
-              # raised (or validate_primary! rejected a replica). Close the
-              # partial conn so repeated failures don't leak PG connections.
+            rescue PG::Error, Pgbus::Process::ReplicaConnectionError, Pgbus::ConfigurationError => e
+              # The factory may raise a ConfigurationError (a bad
+              # streams_connection_options, e.g. a pooled AR connection) or return
+              # a live conn before a later LISTEN raised (or validate_primary!
+              # rejected a replica). Close any partial conn so repeated failures
+              # don't leak PG connections, then back off and retry rather than
+              # letting the exception kill the listener thread silently.
               close_quietly(new_conn)
               @logger.error { "[Pgbus::Streamer::Listener] reconnect failed: #{e.class}: #{e.message}" }
               sleep RECONNECT_BACKOFF_SECONDS
@@ -250,25 +254,6 @@ module Pgbus
           end
         end
 
-        # Legacy fallback for tests that inject only pg_connection: (no factory).
-        # A single conn.reset attempt; on failure it logs and backs off, leaving
-        # recovery to the next run_loop cycle. Kept for backwards compatibility
-        # with test wiring; production always injects a connection_factory.
-        def reconnect_via_reset
-          @conn.reset
-          Pgbus::Process::PrimaryValidator.validate_primary!(@conn)
-          to_relisten = @listening_to.to_a
-          new_listening = Set.new
-          to_relisten.each do |channel|
-            @conn.exec(%(LISTEN "#{channel}"))
-            new_listening.add(channel)
-          end
-          @listening_to = new_listening
-        rescue PG::Error, Pgbus::Process::ReplicaConnectionError => e
-          @logger.error { "[Pgbus::Streamer::Listener] reconnect failed: #{e.class}: #{e.message}" }
-          sleep RECONNECT_BACKOFF_SECONDS
-        end
-
         # Close a PG connection we're discarding (the old conn at the top of a
         # reconnect cycle, or a half-built one whose LISTEN raised). Best-effort.
         def close_quietly(conn)

data/lib/pgbus.rb

@@ -10,6 +10,24 @@ module Pgbus
   # this to be configurable.
   DEAD_LETTER_SUFFIX = "_dlq"
 
+  # Error-hierarchy policy (the 1.0 contract, issue #282):
+  #
+  #   * OPERATIONAL errors — a pgbus subsystem failed to do its job at runtime
+  #     (bad configuration, a pool that's shutting down, a batch enqueue that
+  #     came back short, a rejected GlobalID, a missing PGMQ version) — descend
+  #     from Pgbus::Error. `rescue Pgbus::Error` is meant to catch every one of
+  #     them; that is the whole point of the hierarchy.
+  #
+  #   * ARGUMENT-SHAPE errors — the caller handed a method a malformed argument
+  #     (a stream name too long for the queue-name budget, an unparseable
+  #     cursor, a capsule DSL line that doesn't parse) — stay ArgumentError
+  #     subclasses. That's what ArgumentError means, and rescuing it is the
+  #     caller's responsibility, not an operational concern. These live in
+  #     their own files: Streams::StreamNameTooLong, Streams::Cursor::InvalidCursor,
+  #     Configuration::CapsuleDSL::ParseError.
+  #
+  # When adding a new error class, decide which half it belongs to and parent
+  # it accordingly — do not default to StandardError.
   class Error < StandardError; end
   class ConfigurationError < Error; end
   class SerializationError < Error; end
@@ -20,6 +38,16 @@ module Pgbus
   class SchemaNotReady < Error; end
   class ReadTimeoutError < Error; end
 
+  # Raised by the ActiveJob adapter when a batch enqueue (perform_all_later)
+  # comes back with a msg_id count that doesn't match the number of jobs sent —
+  # a data-integrity signal that some jobs may not have been persisted.
+  class EnqueueError < Error; end
+
+  # Raised by the execution pools when work can't be accepted: the pool is
+  # shutting down, or it's momentarily at capacity. Consumer-reachable during
+  # job submission, so it descends from Pgbus::Error rather than RuntimeError.
+  class ExecutionPoolError < Error; end
+
   # Raised by Client read paths when the in-memory connection-health circuit
   # breaker (Client::ConnectionHealth) is open: the database has failed enough
   # consecutive connection attempts that reads now fail fast without a pool
@@ -85,12 +113,6 @@ module Pgbus
         # root and tries to autoload Puma::Plugin, which collides with the real
         # Puma::Plugin class defined by the puma gem itself.
         loader.ignore("#{__dir__}/puma")
-        # lib/rubocop holds pgbus's custom RuboCop cops (Pgbus/NoRubyTimeout).
-        # They're loaded by RuboCop via .rubocop.yml's `require:`, not by the
-        # gem at runtime. Without this ignore, Zeitwerk scans lib/rubocop under
-        # the pgbus root and tries to autoload a `Rubocop` constant, colliding
-        # with the rubocop gem's real `RuboCop`.
-        loader.ignore("#{__dir__}/rubocop")
         loader
       end
     end
@@ -187,6 +209,24 @@ module Pgbus
       Streams::Key.stream_key!(key)
     end
 
+    # Publish an event to the bus — the top-level shortcut for
+    # `Pgbus::EventBus::Publisher.publish`, symmetric with `Pgbus.stream`.
+    #
+    #   Pgbus.publish("orders.created", { order_id: 42 })
+    #   Pgbus.publish("orders.created", order, headers: { "x-trace" => id }, delay: 30)
+    def publish(routing_key, payload, headers: nil, delay: 0)
+      EventBus::Publisher.publish(routing_key, payload, headers: headers, delay: delay)
+    end
+
+    # Publish an event with a delay. Mirrors
+    # `Pgbus::EventBus::Publisher.publish_later`; `delay:` is required (a
+    # publish_later with no delay is just publish).
+    #
+    #   Pgbus.publish_later("orders.reminder", { order_id: 42 }, delay: 1.hour)
+    def publish_later(routing_key, payload, delay:, headers: nil)
+      EventBus::Publisher.publish_later(routing_key, payload, delay: delay, headers: headers)
+    end
+
     def reset!
       @client&.close
       @client = nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.9.8
+  version: 0.9.9
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -150,7 +150,6 @@ files:
 - app/models/pgbus/application_record.rb
 - app/models/pgbus/batch_entry.rb
 - app/models/pgbus/blocked_execution.rb
-- app/models/pgbus/job_lock.rb
 - app/models/pgbus/job_stat.rb
 - app/models/pgbus/outbox_entry.rb
 - app/models/pgbus/process_entry.rb
@@ -209,7 +208,6 @@ files:
 - 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
 - lib/generators/pgbus/add_job_stats_queue_index_generator.rb
@@ -218,11 +216,11 @@ files:
 - lib/generators/pgbus/add_queue_states_generator.rb
 - lib/generators/pgbus/add_recurring_generator.rb
 - lib/generators/pgbus/add_stream_stats_generator.rb
+- lib/generators/pgbus/add_uniqueness_keys_generator.rb
 - lib/generators/pgbus/install_generator.rb
 - lib/generators/pgbus/migrate_job_locks_generator.rb
 - lib/generators/pgbus/migration_path.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
 - lib/generators/pgbus/templates/add_job_stats_queue_index.rb.erb
@@ -318,6 +316,7 @@ files:
 - lib/pgbus/outbox/poller.rb
 - lib/pgbus/pgmq_schema.rb
 - lib/pgbus/pgmq_schema/pgmq_v1.11.0.sql
+- lib/pgbus/pgmq_schema/pgmq_v1.11.1.sql
 - lib/pgbus/process/consumer.rb
 - lib/pgbus/process/consumer_priority.rb
 - lib/pgbus/process/dispatcher.rb
@@ -383,8 +382,6 @@ files:
 - lib/pgbus/web/streamer/stream_counter.rb
 - lib/pgbus/web/streamer/stream_event_dispatcher.rb
 - lib/puma/plugin/pgbus_streams.rb
-- lib/rubocop/cop/pgbus/no_ruby_timeout.rb
-- lib/rubocop/pgbus.rb
 - lib/tasks/pgbus_autovacuum.rake
 - lib/tasks/pgbus_doctor.rake
 - lib/tasks/pgbus_pgmq.rake
@@ -397,6 +394,7 @@ metadata:
   homepage_uri: https://github.com/mhenrixon/pgbus
   source_code_uri: https://github.com/mhenrixon/pgbus/tree/main
   changelog_uri: https://github.com/mhenrixon/pgbus/blob/main/CHANGELOG.md
+  documentation_uri: https://pgbus.zoolutions.llc
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:

data/app/models/pgbus/job_lock.rb

@@ -1,98 +0,0 @@
-# frozen_string_literal: true
-
-module Pgbus
-  class JobLock < BusRecord
-    self.table_name = "pgbus_job_locks"
-
-    # States:
-    #   queued    — lock held from enqueue time (:until_executed), no worker yet
-    #   executing — lock held by an active worker process
-    STATES = %w[queued executing].freeze
-
-    scope :executing, -> { where(state: "executing") }
-    scope :queued_locks, -> { where(state: "queued") }
-    scope :expired, ->(now = Time.current) { where("expires_at < ?", now) }
-
-    # Atomically try to acquire a lock.
-    # Cleans up expired locks for this key first (crash recovery at acquire time).
-    # Returns true if acquired, false if already locked.
-    #
-    # Uses raw SQL on the hot path to minimize ActiveRecord allocations
-    # (~29 objects vs ~304 per acquire+release cycle with AR query builder).
-    def self.acquire!(lock_key, job_class:, ttl:, job_id: nil, state: "queued", owner_pid: nil, owner_hostname: nil) # rubocop:disable Naming/PredicateMethod
-      expires_at = Time.current + ttl
-
-      # Remove any expired lock for this key inline (last-resort TTL recovery)
-      connection.exec_delete(
-        "DELETE FROM #{table_name} WHERE lock_key = $1 AND expires_at < $2",
-        "JobLock Expire", [lock_key, Time.current]
-      )
-
-      result = connection.exec_query(
-        "INSERT INTO #{table_name} (lock_key, job_class, job_id, state, owner_pid, owner_hostname, expires_at) " \
-        "VALUES ($1, $2, $3, $4, $5, $6, $7) ON CONFLICT (lock_key) DO NOTHING RETURNING id",
-        "JobLock Acquire", [lock_key, job_class, job_id, state, owner_pid, owner_hostname, expires_at]
-      )
-      result.rows.any?
-    end
-
-    # Transition a queued lock to executing state and claim ownership.
-    # Called when a worker starts executing a job that was locked at enqueue time.
-    def self.claim_for_execution!(lock_key, owner_pid:, owner_hostname:, ttl:)
-      connection.exec_update(
-        "UPDATE #{table_name} SET state = $1, owner_pid = $2, owner_hostname = $3, expires_at = $4 " \
-        "WHERE lock_key = $5",
-        "JobLock Claim", ["executing", owner_pid, owner_hostname, Time.current + ttl, lock_key]
-      )
-    end
-
-    # Release a lock by key.
-    def self.release!(lock_key)
-      connection.exec_delete(
-        "DELETE FROM #{table_name} WHERE lock_key = $1",
-        "JobLock Release", [lock_key]
-      )
-    end
-
-    # Check if a lock is currently held (regardless of expiry — reaper handles orphans).
-    def self.locked?(lock_key)
-      result = connection.select_value(
-        "SELECT 1 FROM #{table_name} WHERE lock_key = $1 LIMIT 1", "JobLock Check", [lock_key]
-      )
-      !result.nil?
-    end
-
-    # Reap orphaned locks whose owner is no longer alive, plus stale queued
-    # locks that were never claimed by a worker.
-    # Returns the total number of orphaned locks released.
-    def self.reap_orphaned!
-      reaped = 0
-
-      # 1. Executing locks whose owner process has no healthy heartbeat
-      alive_workers = ProcessEntry
-                      .where("last_heartbeat_at >= ?", Time.current - Process::Heartbeat::ALIVE_THRESHOLD)
-                      .pluck(:pid, :hostname)
-
-      orphaned_executing = executing.select do |lock|
-        alive_workers.none? { |pid, hostname| pid == lock.owner_pid && hostname == lock.owner_hostname }
-      end
-
-      reaped += where(id: orphaned_executing.map(&:id)).delete_all if orphaned_executing.any?
-
-      # 2. Queued locks older than the visibility timeout that were never
-      #    claimed. These are left behind when enqueue fails after lock
-      #    acquisition (e.g. network error, process crash).
-      threshold = Pgbus.configuration.visibility_timeout
-      stale_queued = queued_locks.where("locked_at < ?", Time.current - threshold)
-      reaped += stale_queued.delete_all if stale_queued.exists?
-
-      reaped
-    end
-
-    # Last-resort cleanup: delete locks whose expires_at has passed.
-    # This only fires when the reaper itself can't run (e.g., entire supervisor dead).
-    def self.cleanup_expired!
-      expired.delete_all
-    end
-  end
-end

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

@@ -1,21 +0,0 @@
-class AddPgbusJobLocks < ActiveRecord::Migration<%= migration_version %>
-  def change
-    create_table :pgbus_job_locks do |t|
-      t.string :lock_key, null: false
-      t.string :job_class, null: false
-      t.string :job_id
-      t.string :state, null: false, default: "queued"
-      t.integer :owner_pid
-      t.string :owner_hostname
-      t.datetime :locked_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
-      t.datetime :expires_at, null: false
-    end
-
-    add_index :pgbus_job_locks, :lock_key,
-      unique: true, name: "idx_pgbus_job_locks_key"
-    add_index :pgbus_job_locks, :expires_at,
-      name: "idx_pgbus_job_locks_expires"
-    add_index :pgbus_job_locks, [:state, :owner_pid],
-      name: "idx_pgbus_job_locks_reaper"
-  end
-end

data/lib/rubocop/cop/pgbus/no_ruby_timeout.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-module RuboCop
-  module Cop
-    module Pgbus
-      # Flags any use of Ruby's `Timeout.timeout`. It interrupts the target
-      # thread with `Thread#raise`, which can fire at an arbitrary point —
-      # including mid-libpq-call — and leave a pooled `PG::Connection` in a
-      # corrupt state that re-hangs or returns wrong results on reuse. Prefer a
-      # server-side/socket-level bound instead (Postgres `statement_timeout`,
-      # libpq `tcp_user_timeout`/`keepalives`, an explicit `IO`/socket timeout).
-      #
-      # There is no autocorrect on purpose: the safe replacement depends on what
-      # is being bounded, so a human must choose it.
-      #
-      # @example
-      #   # bad
-      #   Timeout.timeout(5) { do_work }
-      #
-      #   # good — bound the actual resource (DB query, socket) directly
-      #   conn.exec("SET statement_timeout = 5000")
-      #   do_work
-      class NoRubyTimeout < Base
-        MSG = "Please be careful, Timeout is dangerous. Timeout.timeout uses " \
-              "Thread#raise and can corrupt a pooled connection mid-call. Bound the " \
-              "resource itself instead (statement_timeout / tcp_user_timeout / socket timeout)."
-
-        # Matches `Timeout.timeout(...)` and `::Timeout.timeout(...)`.
-        # @!method ruby_timeout?(node)
-        def_node_matcher :ruby_timeout?, <<~PATTERN
-          (send (const {nil? cbase} :Timeout) :timeout ...)
-        PATTERN
-
-        def on_send(node)
-          return unless ruby_timeout?(node)
-
-          add_offense(node.loc.selector)
-        end
-      end
-    end
-  end
-end

data/lib/rubocop/pgbus.rb

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-
-# Entry point for pgbus's custom RuboCop cops. Required from .rubocop.yml via
-# `require:` so the cops are available when linting this repo.
-require_relative "cop/pgbus/no_ruby_timeout"