pgbus 0.16.6 → 0.17.0

data/lib/pgbus/pgmq_schema.rb

@@ -14,6 +14,7 @@ module Pgbus
     class VersionNotFoundError < Pgbus::Error; end
 
     SCHEMA_DIR = File.expand_path("pgmq_schema", __dir__).freeze
+    FIXUPS_DIR = File.join(SCHEMA_DIR, "fixups").freeze
 
     class << self
       # Returns the latest vendored PGMQ version string.
@@ -23,9 +24,37 @@ module Pgbus
 
       # Returns sorted list of all vendored PGMQ versions.
       def available_versions
-        Dir.glob(File.join(SCHEMA_DIR, "pgmq_v*.sql"))
-           .map { |f| File.basename(f).match(/pgmq_v(.+)\.sql/)[1] }
-           .sort_by { |v| Gem::Version.new(v) }
+        versions_in(SCHEMA_DIR)
+      end
+
+      # Versions that ship a table fixup, in version order.
+      #
+      # An upgrade drops every pgmq function and composite type and re-runs the
+      # target version's schema, which recreates both — but never touches an
+      # existing table. An upstream hop that ALTERs one (1.13.0 moves
+      # partitioned queues' msg_id from GENERATED ALWAYS to BY DEFAULT) needs
+      # its own step, and that is what these files are.
+      def fixup_versions
+        versions_in(FIXUPS_DIR)
+      end
+
+      # Concatenated fixups for every version in (after, upto], in version
+      # order. Returns "" when the hop crosses none.
+      #
+      # @param after [String, nil] the installed version; nil (no recorded
+      #   version) applies every fixup up to the target, which is safe because
+      #   each one is idempotent.
+      # @param upto [String] the version being upgraded to
+      def fixups_sql(after:, upto: latest_version)
+        ceiling = Gem::Version.new(upto)
+        floor = after && Gem::Version.new(after)
+
+        applicable = fixup_versions.select do |version|
+          candidate = Gem::Version.new(version)
+          candidate <= ceiling && (floor.nil? || candidate > floor)
+        end
+
+        applicable.map { |version| File.read(File.join(FIXUPS_DIR, "pgmq_v#{version}.sql")) }.join("\n")
       end
 
       # Returns the filesystem path to the vendored SQL file for a given version.
@@ -177,6 +206,15 @@ module Pgbus
 
       private
 
+      # Vendored versions discovered in a directory, in version order. Schema
+      # files and fixups share this so the two can never drift into different
+      # discovery rules.
+      def versions_in(dir)
+        Dir.glob(File.join(dir, "pgmq_v*.sql"))
+           .map { |f| File.basename(f).match(/pgmq_v(.+)\.sql/)[1] }
+           .sort_by { |v| Gem::Version.new(v) }
+      end
+
       # Strips extension-specific blocks (pg_extension_config_dump, pg_depend checks)
       # that only work when pgmq is installed as an extension.
       def strip_extension_only_blocks(sql)

data/lib/pgbus/process/consumer.rb

@@ -78,6 +78,11 @@ module Pgbus
         )
         @registry = EventBus::Registry.instance
         @circuit_breaker = Pgbus::CircuitBreaker.new(config: config)
+        # Queues already warned about for an unroutable message (issue #469).
+        # handle_message runs on the execution pool, so this is touched from
+        # several threads — Concurrent::Set makes add? the atomic
+        # test-and-set the once-per-queue guarantee needs.
+        @unrouted_queues = Concurrent::Set.new
         # stat_buffer: :default means "build one iff config.stats_enabled";
         # passing an explicit value (including nil) overrides that for tests.
         @stat_buffer =
@@ -222,10 +227,12 @@ module Pgbus
         raw = JSON.parse(message.message)
         routing_key = raw.dig("headers", "routing_key") || raw["routing_key"]
 
-        handlers = @registry.handlers_for(routing_key || "")
-        handlers.each do |subscriber|
-          handler = subscriber.handler_class.new
-          handler.process(message)
+        handlers = @registry.handlers_for(routing_key || "", queue_name: queue_name)
+
+        if handlers.empty?
+          report_unrouted(queue_name, routing_key)
+        else
+          dispatch(handlers, message, queue_name)
         end
 
         Pgbus.client.archive_message(queue_name, message.msg_id.to_i)
@@ -247,6 +254,65 @@ module Pgbus
         @jobs_processed.increment
       end
 
+      # Run every handler that owns this message, with the message's visibility
+      # timeout held open for as long as they take (issue #470).
+      #
+      # Without this the consumer had no equivalent of
+      # ActiveJob::Executor#with_visibility_heartbeat: an event handler slower
+      # than config.visibility_timeout (30s by default) was redelivered *while
+      # still running*, a second consumer read the same envelope, and the
+      # holder's pending idempotency claim was indistinguishable from a claim
+      # left by a crash — so the handler ran twice, concurrently.
+      #
+      # The beat also refreshes the claims the handlers register, which is what
+      # lets Handler tell "holder still running" from "holder died": message
+      # visibility and claim liveness go quiet together when this process does.
+      #
+      # Tracking ends before the caller archives — a beat must never re-arm the
+      # VT of a message that is already gone (same rule as the executor's).
+      def dispatch(handlers, message, queue_name)
+        claim_beat = EventBus::ClaimBeat.new
+
+        VisibilityHeartbeat.track(
+          client: Pgbus.client,
+          queue_name: queue_name,
+          msg_id: message.msg_id.to_i,
+          job_class: "EventConsumer",
+          config: config,
+          on_beat: -> { claim_beat.touch! }
+        ) do
+          handlers.each { |subscriber| subscriber.handler_class.new.process(message, claim_beat: claim_beat) }
+        end
+      end
+
+      # No subscriber in this process owns +queue_name+ (a stale
+      # pgmq.topic_bindings row left by a renamed or removed handler, another
+      # app bound to the same bus), or the owner's pattern no longer matches the
+      # routing key. The message is archived by the caller either way — looping
+      # it through VT redelivery would only walk it into the DLQ — but that used
+      # to happen in total silence. The warning is rate-limited to once per
+      # queue per process so a permanently stale binding cannot flood the log;
+      # the instrumentation fires on every message, so the real rate stays
+      # visible in metrics (issue #469).
+      def report_unrouted(queue_name, routing_key)
+        first_for_queue = @unrouted_queues.add?(queue_name)
+
+        if first_for_queue
+          Pgbus.logger.warn do
+            "[Pgbus] Consumer read an unroutable event from queue #{queue_name} " \
+              "(routing_key=#{routing_key.inspect}): no subscriber in this process owns that queue. " \
+              "Archiving. This usually means a stale topic binding — a handler was renamed or removed " \
+              "without unbinding its queue. Further unrouted messages on this queue are not logged."
+          end
+        end
+
+        Pgbus::Instrumentation.instrument(
+          "pgbus.event_unrouted",
+          queue_name: queue_name,
+          routing_key: routing_key
+        )
+      end
+
       # Record a job stat for the handled message, mirroring the shape the
       # executor pushes (Executor#record_stat) so consumer and worker throughput
       # land in the same pgbus_job_stats table. No-op unless stats are enabled.
@@ -521,6 +587,7 @@ module Pgbus
         # wait IS its drain window — bound it by the same knob workers use
         # instead of a hardcoded 30s (issue #386).
         @pool.wait_for_termination(config.drain_timeout)
+        VisibilityHeartbeat.stop
         @stat_buffer&.stop
         @heartbeat&.stop
         restore_signals

data/lib/pgbus/testing.rb

@@ -58,7 +58,7 @@ module Pgbus
           event = @mutex.synchronize { @events.first }
           break unless event
 
-          Pgbus::EventBus::Registry.instance.handlers_for(event.routing_key).each do |subscriber|
+          Pgbus::EventBus::Registry.instance.subscribers_matching(event.routing_key).each do |subscriber|
             # Restore the publisher's Current (issue #431) like the consumer does.
             Pgbus::CurrentAttributes.restore(event.context) { subscriber.handler_class.new.handle(event) }
           end

data/lib/pgbus/version.rb

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

data/lib/pgbus/visibility_heartbeat.rb

@@ -25,9 +25,15 @@ module Pgbus
   # out with `pgbus_visibility_heartbeat false`.
   module VisibilityHeartbeat
     # `concurrency` is `[key, duration]` for a concurrency-limited job, else
-    # nil — one member, so the struct stays inside an 80-byte slot.
+    # nil. `on_beat` is an optional callable run on every extension — the event
+    # consumer uses it to refresh its handlers' idempotency claims (issue #470).
+    #
+    # The ninth member takes the struct out of the 80-byte slot it used to fit
+    # (measured: 80 → 160). That is paid at most once per in-flight message, so
+    # the whole table is bounded by the execution pool's capacity — a handful of
+    # entries per process, not one per enqueued job.
     Entry = Struct.new(:client, :queue_name, :prefixed, :msg_id, :job_class, :extended_at, :extensions,
-                       :concurrency, keyword_init: true)
+                       :concurrency, :on_beat, keyword_init: true)
 
     # Per-job opt-out, included on ActiveJob::Base by the engine:
     #
@@ -59,13 +65,14 @@ module Pgbus
       # @param config [Pgbus::Configuration]
       # @param concurrency [Array(String, Numeric), nil] semaphore key to keep alive alongside
       #   the message and how far to push its expiry on each beat
+      # @param on_beat [#call, nil] run after each extension; its failures are contained
       def track(client:, queue_name:, msg_id:, prefixed: true, job_class: nil, config: Pgbus.configuration,
-                concurrency: nil)
+                concurrency: nil, on_beat: nil)
         return yield unless config.visibility_heartbeat
 
         entry = Entry.new(client: client, queue_name: queue_name, prefixed: prefixed, msg_id: msg_id.to_i,
                           job_class: job_class, extended_at: monotonic_now, extensions: 0,
-                          concurrency: concurrency)
+                          concurrency: concurrency, on_beat: on_beat)
         register(entry, config)
         begin
           yield
@@ -130,6 +137,7 @@ module Pgbus
         entry.extended_at = now
         entry.extensions += 1
         touch_semaphore(entry)
+        run_on_beat(entry)
         Instrumentation.instrument(
           "pgbus.job_visibility_extended",
           queue: entry.queue_name, job_class: entry.job_class, msg_id: entry.msg_id, vt: vt,
@@ -186,6 +194,17 @@ module Pgbus
         end
       end
 
+      # Same containment as touch_semaphore: a lease the beat keeps alive
+      # alongside the message must never cost the message its extension.
+      def run_on_beat(entry)
+        entry.on_beat&.call
+      rescue StandardError => e
+        Pgbus.logger.warn do
+          "[Pgbus::VisibilityHeartbeat] on_beat hook failed for msg_id=#{entry.msg_id} " \
+            "queue=#{entry.queue_name}: #{e.class}: #{e.message}"
+        end
+      end
+
       def forget_parent_entries!
         return if @pid == ::Process.pid
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.16.6
+  version: 0.17.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -291,6 +291,7 @@ files:
 - lib/pgbus/engine.rb
 - lib/pgbus/error_reporter.rb
 - lib/pgbus/event.rb
+- lib/pgbus/event_bus/claim_beat.rb
 - lib/pgbus/event_bus/handler.rb
 - lib/pgbus/event_bus/publisher.rb
 - lib/pgbus/event_bus/registry.rb
@@ -342,9 +343,11 @@ files:
 - lib/pgbus/outbox.rb
 - lib/pgbus/outbox/poller.rb
 - lib/pgbus/pgmq_schema.rb
+- lib/pgbus/pgmq_schema/fixups/pgmq_v1.13.0.sql
 - lib/pgbus/pgmq_schema/pgmq_v1.11.0.sql
 - lib/pgbus/pgmq_schema/pgmq_v1.11.1.sql
 - lib/pgbus/pgmq_schema/pgmq_v1.12.0.sql
+- lib/pgbus/pgmq_schema/pgmq_v1.13.0.sql
 - lib/pgbus/process/consumer.rb
 - lib/pgbus/process/consumer_priority.rb
 - lib/pgbus/process/dispatcher.rb