pgbus 0.14.1 → 0.15.0

data/lib/pgbus/current_attributes.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # Persists ActiveSupport::CurrentAttributes across enqueue → perform
+  # (issue #430).
+  #
+  # `capture` snapshots the assigned attributes of every persisted class
+  # (config.current_attributes: :auto, an explicit list, or per-class
+  # only:/except: filters) serialized through ActiveJob::Arguments — so
+  # GlobalID models, Symbols, Times round-trip like job arguments and fall
+  # under the allowed_global_id_models allowlist on the way back. `restore`
+  # nests `klass.set(attrs)` for the duration of a block.
+  #
+  # The ActiveJob side (Pgbus::ActiveJob::CurrentAttributes) calls capture
+  # from `serialize` and restore around `perform_now`, so the hop works under
+  # the pgbus worker and under Rails' :test / :inline adapters alike.
+  module CurrentAttributes
+    METADATA_KEY = "pgbus_current"
+
+    @missing_warned = Concurrent::Map.new
+
+    class << self
+      def enabled?(config = Pgbus.configuration)
+        !config.current_attributes.nil?
+      end
+
+      # { "Current" => serialized_attrs, ... } or nil when there is nothing
+      # to persist. `override` is a per-job-class spec (false disables; an
+      # Array/Hash replaces the config's list for this job).
+      def capture(config = Pgbus.configuration, override: nil)
+        return nil if override == false
+        return nil unless override || enabled?(config)
+
+        captured = {}
+        persisted_specs(config, override: override).each do |spec|
+          klass = resolve_class(spec[:name]) or next
+          attrs = filter_attrs(klass.attributes, spec)
+          next if attrs.empty?
+
+          captured[klass.name] = serialize_attrs(klass, attrs)
+        end
+        captured.empty? ? nil : captured
+      end
+
+      # Set every stored class's attributes for the block; previous values
+      # come back afterwards (ActiveSupport::CurrentAttributes#set semantics).
+      def restore(stored, &block)
+        return yield if stored.nil? || stored.empty?
+
+        stored.reduce(block) do |inner, (name, attrs)|
+          klass = resolve_class(name)
+          next inner unless klass
+
+          values = deserialize_attrs(klass, attrs)
+          -> { klass.set(values) { inner.call } }
+        end.call
+      end
+
+      # Config/override value → nil | :auto | [{ name:, only:, except: }].
+      # Raises Pgbus::ConfigurationError for anything else.
+      def normalize(value)
+        case value
+        when nil then nil
+        when :auto then :auto
+        when Array then value.map { |entry| class_spec(entry, {}) }
+        when Hash then value.map { |entry, filters| class_spec(entry, filters) }
+        else
+          raise Pgbus::ConfigurationError,
+                "current_attributes must be nil, :auto, an Array of CurrentAttributes classes/names, " \
+                "or a Hash of class/name => { only: [...] } | { except: [...] } (got #{value.inspect})"
+        end
+      end
+
+      # Normalized [{ name:, only:, except: }] for the config (or override).
+      def persisted_specs(config = Pgbus.configuration, override: nil)
+        source = override.nil? ? config.current_attributes : normalize(override)
+        return [] if source.nil? || source == false
+        return source unless source == :auto
+
+        ActiveSupport::CurrentAttributes.descendants.filter_map do |klass|
+          { name: klass.name, only: nil, except: nil } if klass.name
+        end
+      end
+
+      private
+
+      def class_spec(entry, filters)
+        name = case entry
+               when Class, String then entry.to_s
+               else
+                 raise Pgbus::ConfigurationError,
+                       "current_attributes entries must be classes or class names (got #{entry.inspect})"
+               end
+        unless filters.is_a?(Hash) && (filters.keys - %i[only except]).empty? && filters.size <= 1
+          raise Pgbus::ConfigurationError,
+                "current_attributes filters for #{name} must be { only: [...] } or { except: [...] } (got #{filters.inspect})"
+        end
+
+        { name: name, only: filter_list(name, filters[:only], :only), except: filter_list(name, filters[:except], :except) }
+      end
+
+      def filter_list(name, list, kind)
+        return nil if list.nil?
+        unless list.is_a?(Array) && list.all? { |a| a.is_a?(Symbol) || a.is_a?(String) }
+          raise Pgbus::ConfigurationError,
+                "current_attributes #{kind}: for #{name} must be an Array of attribute names (got #{list.inspect})"
+        end
+
+        list.map(&:to_sym)
+      end
+
+      def resolve_class(name)
+        name.constantize
+      rescue NameError
+        @missing_warned.compute_if_absent(name) do
+          Pgbus.logger.warn { "[Pgbus] current_attributes: #{name} is not defined — skipping" }
+          true
+        end
+        nil
+      end
+
+      def filter_attrs(attrs, spec)
+        attrs = attrs.compact
+        attrs = attrs.slice(*spec[:only]) if spec[:only]
+        attrs = attrs.except(*spec[:except]) if spec[:except]
+        attrs
+      end
+
+      def serialize_attrs(klass, attrs)
+        ::ActiveJob::Arguments.serialize([attrs]).first
+      rescue ::ActiveJob::SerializationError, URI::Error
+        culprit, value = attrs.find do |_name, v|
+          ::ActiveJob::Arguments.serialize([v])
+          false
+        rescue ::ActiveJob::SerializationError, URI::Error
+          true
+        end
+        raise Pgbus::CurrentAttributesError,
+              "#{klass.name}##{culprit} (#{value.class}) cannot be serialized for job persistence — " \
+              "make it GlobalID/JSON-serializable or exclude it: " \
+              "config.current_attributes = { #{klass.name} => { except: [:#{culprit}] } }"
+      end
+
+      def deserialize_attrs(klass, attrs)
+        instance = klass.instance
+        known, unknown = attrs.partition { |name, _| name.start_with?("_aj_") || instance.respond_to?("#{name}=") }
+        unless unknown.empty?
+          Pgbus.logger.debug do
+            "[Pgbus] current_attributes: #{klass.name} no longer defines #{unknown.map(&:first).join(", ")} — dropped"
+          end
+        end
+        ::ActiveJob::Arguments.deserialize([known.to_h]).first
+      end
+    end
+  end
+end

data/lib/pgbus/engine.rb

@@ -74,6 +74,8 @@ module Pgbus
       ActiveSupport.on_load(:active_job) do
         include Pgbus::Concurrency
         include Pgbus::Uniqueness
+        include Pgbus::ActiveJob::BatchId
+        include Pgbus::ActiveJob::CurrentAttributes
       end
     end
 

data/lib/pgbus/event.rb

@@ -4,14 +4,19 @@ require "time"
 
 module Pgbus
   class Event
-    attr_reader :event_id, :payload, :published_at, :routing_key, :headers
+    # +context+ is the publisher's persisted ActiveSupport::CurrentAttributes
+    # (issue #431) in their stored form — { "Current" => serialized attrs } —
+    # or nil. Handlers normally just read +Current+ (it is restored around
+    # +handle+); the raw form is here for tests and explicit access.
+    attr_reader :event_id, :payload, :published_at, :routing_key, :headers, :context
 
-    def initialize(event_id:, payload:, published_at: nil, routing_key: nil, headers: nil)
+    def initialize(event_id:, payload:, published_at: nil, routing_key: nil, headers: nil, context: nil)
       @event_id = event_id
       @payload = payload
       @published_at = published_at || Time.now.utc
       @routing_key = routing_key
       @headers = headers || {}
+      @context = context
     end
 
     def [](key)

data/lib/pgbus/event_bus/handler.rb

@@ -43,7 +43,10 @@ module Pgbus
           msg_id: message.msg_id.to_i
         }
         Instrumentation.instrument("pgbus.event_processed", instrument_payload) do
-          handle(event)
+          # Publisher's Current attributes (issue #431) are set for the handler
+          # and reverted after (CurrentAttributes#set semantics); the Rails
+          # executor wrap above additionally resets at completion.
+          Pgbus::CurrentAttributes.restore(event.context) { handle(event) }
         end
         complete_claim!(event.event_id) if self.class.idempotent?
         :handled
@@ -88,10 +91,17 @@ module Pgbus
         payload = raw["payload"]
         payload = Serializer.locate_global_id(payload["_global_id"]) if payload.is_a?(Hash) && payload["_global_id"]
 
+        # Same allowlist boundary as Serializer.deserialize_job_data: every
+        # _aj_globalid in the persisted context is checked BEFORE anything is
+        # located, so a crafted envelope cannot load an arbitrary model.
+        context = raw[Pgbus::CurrentAttributes::METADATA_KEY]
+        Serializer.assert_job_global_ids_allowed!(context) if context
+
         Event.new(
           event_id: raw["event_id"],
           payload: payload,
-          published_at: raw["published_at"] ? Time.parse(raw["published_at"]) : nil
+          published_at: raw["published_at"] ? Time.parse(raw["published_at"]) : nil,
+          context: context
         )
       end
 

data/lib/pgbus/event_bus/publisher.rb

@@ -9,6 +9,8 @@ module Pgbus
 
       def publish(routing_key, payload, headers: nil, delay: 0)
         event_data = build_event_data(payload, routing_key: routing_key)
+        event_data = tag_fair_share(event_data, payload, routing_key: routing_key, headers: headers)
+        event_data = tag_current(event_data)
 
         if defined?(Pgbus::Testing) && !Pgbus::Testing.disabled?
           event = Pgbus::Event.new(
@@ -16,14 +18,15 @@ module Pgbus
             payload: event_data["payload"],
             published_at: event_data["published_at"] ? Time.parse(event_data["published_at"]) : nil,
             routing_key: routing_key,
-            headers: headers
+            headers: headers,
+            context: event_data[Pgbus::CurrentAttributes::METADATA_KEY]
           )
 
           Pgbus::Testing.store.push_event(event)
 
           if Pgbus::Testing.inline? && delay.to_i <= 0
             Pgbus::EventBus::Registry.instance.handlers_for(routing_key).each do |subscriber|
-              subscriber.handler_class.new.handle(event)
+              Pgbus::CurrentAttributes.restore(event.context) { subscriber.handler_class.new.handle(event) }
             end
           end
 
@@ -37,6 +40,38 @@ module Pgbus
         publish(routing_key, payload, headers: headers, delay: delay)
       end
 
+      # Fair share for consumers (issue #427): when config.event_fair_share is
+      # set, hand the callable a Pgbus::Event (routing key, the payload object
+      # as passed to publish — not its serialized form — and headers) and merge
+      # the resolved key/weight into the envelope. Shared with Outbox.publish_event
+      # so the key is resolved where the publisher's context (Current.*) exists
+      # and rides the outbox row to the bus. Returns event_data itself when off.
+      def tag_fair_share(event_data, payload, routing_key:, headers:)
+        return event_data unless FairShare.event_enabled?
+
+        event = Pgbus::Event.new(
+          event_id: event_data["event_id"],
+          payload: payload,
+          routing_key: routing_key,
+          headers: headers
+        )
+        FairShare.inject_event_metadata(event, event_data)
+      end
+
+      # Current attributes publish → handler (issue #431): when
+      # config.current_attributes is set, snapshot the publisher's persisted
+      # Current classes (Pgbus::CurrentAttributes.capture — same filters,
+      # serialization and allowlist gating as jobs) into the envelope under
+      # the same +pgbus_current+ key jobs use. Shared with Outbox.publish_event
+      # so the capture happens where Current is set, not at relay time.
+      # Returns event_data itself when off or nothing is assigned.
+      def tag_current(event_data)
+        captured = Pgbus::CurrentAttributes.capture
+        return event_data unless captured
+
+        event_data.merge(Pgbus::CurrentAttributes::METADATA_KEY => captured)
+      end
+
       def build_event_data(payload, routing_key: nil)
         event_id = SecureRandom.uuid
 

data/lib/pgbus/event_bus/subscriber.rb

@@ -13,6 +13,10 @@ module Pgbus
 
       def setup!
         Pgbus.client.ensure_queue(queue_name)
+        # Subscriber queues are created here, not by a worker, so this is their
+        # creation hook for the fair-share index (issue #427). Idempotent and
+        # memoized per process; instant on a fresh table, CONCURRENTLY otherwise.
+        Pgbus.client.ensure_fair_index(queue_name) if FairShare.event_enabled?
         Pgbus.client.bind_topic(pattern, queue_name)
       end
 

data/lib/pgbus/fair_share.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # Fair share scheduling across tenants (issue #426).
+  #
+  # At enqueue time the configured callable (`config.fair_share`) resolves a
+  # key — typically a tenant id — and an optional weight for the job. Both
+  # ride inside the job payload hash (same pattern as Concurrency::METADATA_KEY
+  # and Batch::METADATA_KEY), so they survive every path that re-sends a
+  # payload: blocked-execution promotion, DLQ retry, dashboard retry, bulk
+  # enqueue. On the read side Client#read_batch_fair interleaves across keys
+  # proportionally to weight (see Client::FairRead).
+  #
+  # Events (issue #427) use the same keys and the same read primitive: the
+  # configured `config.event_fair_share` callable receives the Pgbus::Event at
+  # publish time and the key rides in the event *envelope* (a sibling of
+  # event_id / payload / published_at — never inside the user payload), so the
+  # same `message->>'pgbus_fair_key'` expression, index and read SQL serve both
+  # jobs and events, and the outbox (which stores the envelope) carries it.
+  module FairShare
+    METADATA_KEY = "pgbus_fair_key"
+    WEIGHT_KEY = "pgbus_fair_weight"
+    DEFAULT_WEIGHT = 1
+
+    class << self
+      def enabled?(config = Pgbus.configuration)
+        !config.fair_share.nil?
+      end
+
+      def event_enabled?(config = Pgbus.configuration)
+        !config.event_fair_share.nil?
+      end
+
+      # Returns the payload with fair-share metadata merged in, or the payload
+      # itself (same object) when fair share is off or the job is unkeyed.
+      # Exceptions raised by the callable propagate — a key resolver that
+      # cannot run is a programmer error, not something to swallow at enqueue.
+      def inject_metadata(active_job, payload_hash, config = Pgbus.configuration)
+        return payload_hash unless enabled?(config)
+
+        tag(payload_hash, resolve(active_job, config))
+      end
+
+      # Event twin of inject_metadata: returns the event envelope (the hash
+      # Publisher.build_event_data produced) with fair-share metadata merged
+      # in, or the envelope itself (same object) when event fair share is off
+      # or the callable declines to key the event.
+      def inject_event_metadata(event, event_data, config = Pgbus.configuration)
+        return event_data unless event_enabled?(config)
+
+        tag(event_data, resolve_event(event, config))
+      end
+
+      # [key, weight] for the job, or nil when the callable declines to key it.
+      def resolve(active_job, config = Pgbus.configuration)
+        normalize(config.fair_share.call(active_job))
+      end
+
+      # [key, weight] for the event, or nil when the callable declines.
+      def resolve_event(event, config = Pgbus.configuration)
+        normalize(config.event_fair_share.call(event))
+      end
+
+      def extract_key(payload)
+        payload[METADATA_KEY]
+      end
+
+      def extract_weight(payload)
+        payload[WEIGHT_KEY] || DEFAULT_WEIGHT
+      end
+
+      private
+
+      def tag(hash, resolved)
+        return hash unless resolved
+
+        key, weight = resolved
+        tagged = hash.merge(METADATA_KEY => key)
+        tagged[WEIGHT_KEY] = weight unless weight == DEFAULT_WEIGHT
+        tagged
+      end
+
+      def normalize(result)
+        return nil if result.nil?
+
+        raw_key, raw_weight = result.is_a?(Array) ? result : [result, nil]
+        [normalize_key(raw_key), normalize_weight(raw_weight)]
+      end
+
+      def normalize_key(raw)
+        key = case raw
+              when String, Symbol, Integer then raw.to_s
+              else
+                raise ArgumentError,
+                      "fair_share key must be a String, Symbol, or Integer (got #{raw.class})"
+              end
+        raise ArgumentError, "fair_share key must not be empty" if key.empty?
+
+        key
+      end
+
+      def normalize_weight(raw)
+        return DEFAULT_WEIGHT if raw.nil?
+        return raw if raw.is_a?(Numeric) && raw.positive?
+
+        raise ArgumentError, "fair_share weight must be a positive Numeric (got #{raw.inspect})"
+      end
+    end
+  end
+end

data/lib/pgbus/generators/migration_detector.rb

@@ -78,6 +78,8 @@ module Pgbus
         add_recurring: "pgbus:add_recurring",
         add_failed_events_index: "pgbus:add_failed_events_index",
         add_processed_event_completion: "pgbus:add_processed_event_completion",
+        add_batch_executions: "pgbus:add_batch_executions",
+        add_batch_callback_jobs: "pgbus:add_batch_callback_jobs",
         tune_autovacuum: "pgbus:tune_autovacuum",
         tune_fillfactor: "pgbus:tune_fillfactor"
       }.freeze
@@ -97,6 +99,8 @@ module Pgbus
         add_recurring: "recurring tasks + executions tables",
         add_failed_events_index: "unique index on pgbus_failed_events (queue_name, msg_id)",
         add_processed_event_completion: "completed_at on pgbus_processed_events (two-phase idempotency claim)",
+        add_batch_executions: "batch execution-row tracking (self-healing completion, on_failure rename)",
+        add_batch_callback_jobs: "batch callback-job columns (configured ActiveJob instances as batch callbacks)",
         tune_autovacuum: "autovacuum tuning for PGMQ queue and archive tables",
         tune_fillfactor: "fillfactor=70 on PGMQ queue tables (reduces page density during update churn)"
       }.freeze
@@ -123,6 +127,8 @@ module Pgbus
           *recurring_migrations,
           *failed_events_index_migrations,
           *processed_event_completion_migrations,
+          *batch_executions_migrations,
+          *batch_callback_jobs_migrations,
           *autovacuum_migrations,
           *fillfactor_migrations
         ]
@@ -223,6 +229,30 @@ module Pgbus
         [:add_processed_event_completion]
       end
 
+      # Execution-row tracking plus the on_discard → on_failure column rename
+      # ship as one upgrade. Either a missing executions table or leftover
+      # pre-rename columns means this generator still needs to run.
+      def batch_executions_migrations
+        return [] unless table_exists?("pgbus_batches")
+
+        batches_columns = column_names("pgbus_batches")
+        migrated = table_exists?("pgbus_batch_executions") &&
+                   batches_columns.include?("on_failure_class") &&
+                   !batches_columns.include?("discarded_jobs")
+        return [] if migrated
+
+        [:add_batch_executions]
+      end
+
+      # Configured callback instances (on_finish: MyJob.new.set(...)) need
+      # somewhere to store the serialized job — issue #415.
+      def batch_callback_jobs_migrations
+        return [] unless table_exists?("pgbus_batches")
+        return [] if column_names("pgbus_batches").include?("on_finish_job")
+
+        [:add_batch_callback_jobs]
+      end
+
       # Autovacuum tuning: check if any PGMQ queue table already has
       # custom autovacuum settings applied. If not, queue the migration.
       def autovacuum_migrations

data/lib/pgbus/instrumentation.rb

@@ -25,6 +25,11 @@ module Pgbus
   #   pgbus.consumer.recycle       — consumer hit a recycle threshold (same payload shape as pgbus.worker.recycle)
   #   pgbus.serializer.serialize   — job/event serialization
   #   pgbus.serializer.deserialize — job/event deserialization
+  #   pgbus.batch_finished         — batch flipped to finished
+  #                                  payload: batch_id, total_jobs, completed_jobs, failed_jobs
+  #   pgbus.batch_sweep            — dispatcher stalled-batch sweep
+  #                                  payload: stalled_for, stale_executions, orphan_rows,
+  #                                  started_batches, finished_batches
   #
   module Instrumentation
     module_function

data/lib/pgbus/outbox/poller.rb

@@ -102,12 +102,12 @@ module Pgbus
         return 0 if entries.empty?
 
         succeeded = 0
-        entries.group_by { |e| [e.queue_name, e.priority, e.delay || 0] }.each do |(queue, _priority, delay), group|
+        entries.group_by { |e| [e.queue_name, e.priority, e.delay || 0] }.each do |(queue, priority, delay), group|
           payloads = group.map(&:payload)
           headers = group.map(&:headers)
           headers = nil if headers.all?(&:blank?)
 
-          Pgbus.client.send_batch(queue, payloads, headers: headers, delay: delay)
+          Pgbus.client.send_batch(queue, payloads, headers: headers, delay: delay, priority: priority)
           now = Time.current
           group.each { |e| e.update!(published_at: now) }
           succeeded += group.size
@@ -119,16 +119,15 @@ module Pgbus
         succeeded
       end
 
-      # Fallback for individual publishing when a batch fails.
-      # Intentionally omits priority to match send_batch routing behavior
-      # (base queue only), ensuring consistent queue placement regardless
-      # of whether the batch or fallback path is used.
+      # Fallback for individual publishing when a batch fails. Passes the same
+      # priority as the batch path so queue placement is identical either way.
       def publish_single_queue(entry)
         Pgbus.client.send_message(
           entry.queue_name,
           entry.payload,
           headers: entry.headers,
-          delay: entry.delay || 0
+          delay: entry.delay || 0,
+          priority: entry.priority
         )
         entry.update!(published_at: Time.current)
         true

data/lib/pgbus/outbox.rb

@@ -18,7 +18,14 @@ module Pgbus
 
     def publish_event(routing_key, payload, headers: nil)
       Instrumentation.instrument("pgbus.outbox.publish", routing_key: routing_key, kind: :event) do
-        event_data = EventBus::Publisher.build_event_data(payload)
+        # routing_key: in the envelope so the consumer can dispatch the relayed
+        # event to handlers — pgmq.send_topic matches queues at relay time but
+        # stamps nothing on the message, and Consumer#handle_message reads the
+        # routing key from the envelope (fixed alongside issue #431; previously
+        # relayed outbox events matched zero handlers and were archived unrun).
+        event_data = EventBus::Publisher.build_event_data(payload, routing_key: routing_key)
+        event_data = EventBus::Publisher.tag_fair_share(event_data, payload, routing_key: routing_key, headers: headers)
+        event_data = EventBus::Publisher.tag_current(event_data)
         OutboxEntry.create!(
           routing_key: routing_key,
           payload: event_data,

data/lib/pgbus/process/consumer.rb

@@ -116,6 +116,7 @@ module Pgbus
         setup_signals
         start_heartbeat
         setup_subscriptions
+        ensure_fair_indexes
         start_wake_source
         Pgbus.logger.info do
           "[Pgbus] Consumer started: topics=#{topics.join(",")} threads=#{threads} " \
@@ -188,7 +189,9 @@ module Pgbus
         active_queues = @queue_names.reject { |q| @circuit_breaker.paused?(q) }
         return [] if active_queues.empty?
 
-        if active_queues.size == 1
+        if fair_share_enabled?
+          fetch_fair(active_queues, qty)
+        elsif active_queues.size == 1
           queue = active_queues.first
           (Pgbus.client.read_batch(queue, qty: qty) || []).map { |m| [queue, m] }
         else
@@ -282,6 +285,40 @@ module Pgbus
         end
       end
 
+      # Fair share for consumers (issue #427): one weighted-interleave read per
+      # subscriber queue, in list order with the remaining capacity — strict
+      # order across queues, fair across tenants WITHIN each queue. Same loop
+      # shape as Worker#fetch_fair; the consumer has no priority levels or
+      # group mode, so this is the whole fair branch.
+      def fetch_fair(active_queues, qty)
+        remaining = qty
+        results = []
+
+        active_queues.each do |queue|
+          break if remaining <= 0
+
+          messages = Pgbus.client.read_batch_fair(queue, qty: remaining) || []
+          messages.each { |m| results << [queue, m] }
+          remaining -= messages.size
+        end
+
+        results
+      end
+
+      def fair_share_enabled?
+        FairShare.event_enabled?(config)
+      end
+
+      # Build the fair index on every subscriber queue this consumer reads
+      # (idempotent, memoized in the client, CONCURRENTLY so a populated queue
+      # is never write-locked). Subscriber queues created later get theirs from
+      # Subscriber#setup!.
+      def ensure_fair_indexes
+        return unless fair_share_enabled?
+
+        @queue_names.each { |q| Pgbus.client.ensure_fair_index(q) }
+      end
+
       # Signal the loop to exit cleanly once a recycle limit is hit. The clean
       # exit gets an immediate supervisor restart (supervisor.rb:305-307), so a
       # fresh fork replaces this one before its memory grows unbounded — the