pgbus 0.14.2 → 0.15.0

data/lib/pgbus/client/fair_read.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Client
+    # Fair share reads (issue #426): a weighted, work-conserving interleave
+    # across fair-share keys within one queue. Replaces `read_batch` on the
+    # worker when `config.fair_share` is set.
+    #
+    # Scheduling rule per read of `qty`: for every key that has visible
+    # messages, rank that key's visible messages 1..qty oldest-visible first
+    # (`vt, msg_id`); a message's virtual time is `rank / weight`; take the
+    # `qty` messages with the lowest `(virtual_time, msg_id)`. Weight 3 vs 1
+    # yields a 3:1 split under contention; a lone key fills the whole batch.
+    # This is batch-level weighted fair queuing — proportional within each
+    # batch, memoryless across batches (no deficit carry-over).
+    #
+    # Cost model: key enumeration is a loose index scan over
+    # (key, vt, msg_id) — one probe per key with visible work; keys whose
+    # messages are all invisible (in flight / delayed / in retry backoff) are
+    # skipped at the index level because `vt` is in the index. Per-key
+    # candidates are a bounded `LIMIT qty` index range. Roughly
+    # O(K · log n + K · qty), K = keys with visible work, independent of
+    # backlog depth. Within a key the order is `(vt, msg_id)` — FIFO for
+    # immediate enqueues; retried/delayed messages sort by when they became
+    # visible — a deliberate deviation from pgmq.read's pure msg_id order so
+    # the per-key lookup never sorts a tenant's whole visible backlog.
+    #
+    # Candidates are selected before locking (same shape as
+    # pgmq.read_grouped_rr), so under concurrent readers a batch can come back
+    # short; the worker loop re-reads immediately while it has capacity.
+    module FairRead
+      # The read expressions are written against the alias `m`; the index
+      # expression is the same shape minus the alias so the planner matches it.
+      FAIR_INDEX_KEY_EXPR = "COALESCE(message->>'#{FairShare::METADATA_KEY}', '')".freeze
+      FAIR_KEY_EXPR = "COALESCE(m.message->>'#{FairShare::METADATA_KEY}', '')".freeze
+      FAIR_WEIGHT_EXPR = "COALESCE((m.message->>'#{FairShare::WEIGHT_KEY}')::numeric, 1)".freeze
+      FAIR_INDEX_SUFFIX = "_fair_idx"
+
+      def read_batch_fair(queue_name, qty:, vt: nil)
+        full_name = fair_queue_name(queue_name)
+        guarded_read { fair_read_step(full_name, qty, vt || config.visibility_timeout) }
+      end
+
+      # Idempotent, memoized per process. Uses CREATE INDEX CONCURRENTLY so
+      # enabling fair share on an existing, populated queue never blocks
+      # enqueues. A queue table that does not exist yet is left alone (its
+      # creation path builds the index non-concurrently); any other failure is
+      # logged with the remediation and NOT memoized so the next ensure retries.
+      def ensure_fair_index(queue_name)
+        full_name = fair_queue_name(queue_name)
+        return if fair_indexes_ensured[full_name]
+
+        with_stale_connection_retry do
+          synchronized { exec_ddl(fair_index_sql(full_name, concurrently: true)) }
+        end
+        fair_indexes_ensured[full_name] = true
+      rescue StandardError => e
+        if duplicate_relation_error?(e)
+          fair_indexes_ensured[full_name] = true
+        elsif undefined_table_error?(e)
+          Pgbus.logger.debug { "[Pgbus] Fair index deferred — queue table #{full_name} not created yet" }
+        else
+          Pgbus.logger.error do
+            "[Pgbus] Could not create fair index #{fair_index_name(full_name)} on pgmq.q_#{full_name}: " \
+              "#{e.class}: #{e.message}. A failed CONCURRENTLY build leaves an INVALID index behind — " \
+              "run `DROP INDEX IF EXISTS pgmq.#{fair_index_name(full_name)}` and restart the worker to retry."
+          end
+        end
+      end
+
+      private
+
+      # One instrumented, retried, serialized, timeout-bounded fair read of a
+      # physical (already prefixed + sanitized) queue table. Not breaker-guarded
+      # itself so callers that loop over sub-queues can wrap the loop once.
+      def fair_read_step(full_name, qty, vt_seconds)
+        Instrumentation.instrument("pgbus.client.read_batch_fair", queue: full_name, qty: qty) do
+          with_stale_connection_retry do
+            synchronized { with_read_timeout { exec_fair_read(full_name, qty, vt_seconds) } }
+          end
+        end
+      end
+
+      def fair_queue_name(queue_name)
+        QueueNameValidator.sanitize!(config.queue_name(queue_name))
+      end
+
+      def fair_indexes_ensured
+        @fair_indexes_ensured ||= Concurrent::Map.new
+      end
+
+      # Runs inside create_queue_physically (caller owns the mutex) on a
+      # freshly created, empty table — plain CREATE INDEX is instant there.
+      def create_fair_index_if_needed(full_name)
+        return unless FairShare.enabled?(config)
+
+        exec_ddl(fair_index_sql(full_name, concurrently: false))
+        fair_indexes_ensured[full_name] = true
+      rescue StandardError => e
+        raise unless duplicate_relation_error?(e)
+
+        fair_indexes_ensured[full_name] = true
+      end
+
+      def exec_ddl(sql)
+        @pgmq.with_connection { |conn| conn.exec(sql) }
+      end
+
+      def exec_fair_read(full_name, qty, vt_seconds)
+        rows = @pgmq.with_connection do |conn|
+          conn.exec_params(fair_read_sql(full_name), [qty.to_i, vt_seconds.to_i]).to_a
+        end
+        rows.map { |row| PGMQ::Message.new(row) }
+      end
+
+      def fair_index_name(full_name)
+        "q_#{full_name}#{FAIR_INDEX_SUFFIX}"
+      end
+
+      def fair_index_sql(full_name, concurrently:)
+        "CREATE INDEX #{"CONCURRENTLY " if concurrently}IF NOT EXISTS #{fair_index_name(full_name)} " \
+          "ON pgmq.q_#{full_name} ((#{FAIR_INDEX_KEY_EXPR}), vt, msg_id)"
+      end
+
+      def fair_read_sql(full_name)
+        table = "pgmq.q_#{full_name}"
+        <<~SQL
+          WITH RECURSIVE fair_keys AS (
+            (SELECT #{FAIR_KEY_EXPR} AS k
+               FROM #{table} m
+              WHERE m.vt <= now()
+              ORDER BY 1 LIMIT 1)
+            UNION ALL
+            SELECT (SELECT #{FAIR_KEY_EXPR}
+                      FROM #{table} m
+                     WHERE #{FAIR_KEY_EXPR} > fk.k
+                       AND m.vt <= now()
+                     ORDER BY 1 LIMIT 1)
+              FROM fair_keys fk
+             WHERE fk.k IS NOT NULL
+          ),
+          candidates AS (
+            SELECT c.msg_id, c.rn, c.w
+              FROM fair_keys fk
+              CROSS JOIN LATERAL (
+                SELECT m.msg_id,
+                       ROW_NUMBER() OVER (ORDER BY m.vt, m.msg_id) AS rn,
+                       #{FAIR_WEIGHT_EXPR} AS w
+                  FROM #{table} m
+                 WHERE #{FAIR_KEY_EXPR} = fk.k
+                   AND m.vt <= now()
+                 ORDER BY m.vt, m.msg_id
+                 LIMIT $1
+              ) c
+             WHERE fk.k IS NOT NULL
+          ),
+          picked AS (
+            SELECT msg_id, ROW_NUMBER() OVER (ORDER BY rn / w, msg_id) AS selection_order
+              FROM candidates
+             ORDER BY rn / w, msg_id
+             LIMIT $1
+          ),
+          locked AS (
+            SELECT m.msg_id, p.selection_order
+              FROM #{table} m
+              JOIN picked p ON p.msg_id = m.msg_id
+             WHERE m.vt <= now()
+             FOR UPDATE OF m SKIP LOCKED
+          ),
+          updated AS (
+            UPDATE #{table} m
+               SET vt = clock_timestamp() + make_interval(secs => $2),
+                   read_ct = read_ct + 1,
+                   last_read_at = clock_timestamp()
+              FROM locked l
+             WHERE m.msg_id = l.msg_id
+            RETURNING m.msg_id, m.read_ct, m.enqueued_at, m.last_read_at, m.vt, m.message, m.headers,
+                      l.selection_order
+          )
+          SELECT msg_id, read_ct, enqueued_at, last_read_at, vt, message, headers
+            FROM updated
+           ORDER BY selection_order
+        SQL
+      end
+    end
+  end
+end

data/lib/pgbus/client.rb

@@ -12,6 +12,7 @@ require_relative "client/resizable_pool"
 module Pgbus
   class Client
     include ReadAfter
+    include FairRead
     include EnsureStreamQueue
     include NotifyStream
 
@@ -428,11 +429,17 @@ module Pgbus
       # Non-priority fast path delegates to read_batch, which is already gated
       # by the connection-health breaker — no extra guard needed here.
       unless @queue_strategy.priority?
-        return (read_batch(queue_name, qty: qty, vt: vt) || []).map do |m|
-          [config.queue_name(queue_name), m]
-        end
+        msgs = if FairShare.enabled?(config)
+                 read_batch_fair(queue_name, qty: qty, vt: vt)
+               else
+                 read_batch(queue_name, qty: qty, vt: vt)
+               end
+        return (msgs || []).map { |m| [config.queue_name(queue_name), m] }
       end
 
+      # Fair share (issue #426): strict between levels, fair within a level.
+      return read_batch_prioritized_fair(queue_name, qty: qty, vt: vt) if FairShare.enabled?(config)
+
       # The priority loop issues its own reads, so gate the whole loop: an open
       # breaker fails fast before any sub-queue is touched, and the loop as a
       # unit records one success/failure with the latch.
@@ -457,6 +464,25 @@ module Pgbus
       end
     end
 
+    # Priority sub-queues drained p0 → pN, each level read with the fair
+    # interleave. guarded_read wraps the loop as one unit (see above).
+    def read_batch_prioritized_fair(queue_name, qty:, vt: nil)
+      guarded_read do
+        remaining = qty
+        results = []
+
+        config.priority_queue_names(queue_name).each do |pq_name|
+          break if remaining <= 0
+
+          msgs = fair_read_step(QueueNameValidator.sanitize!(pq_name), remaining, vt || config.visibility_timeout)
+          msgs.each { |m| results << [pq_name, m] }
+          remaining -= msgs.size
+        end
+
+        results
+      end
+    end
+
     def read_with_poll(queue_name, qty:, vt: nil, max_poll_seconds: 5, poll_interval_ms: 100)
       full_name = config.queue_name(queue_name)
       guarded_read do
@@ -1351,6 +1377,7 @@ module Pgbus
         create_queue_table(full_name)
         enable_notify_if_needed(full_name, NOTIFY_THROTTLE_MS)
         create_fifo_index_if_needed(full_name)
+        create_fair_index_if_needed(full_name)
       end
     end
 

data/lib/pgbus/configuration.rb

@@ -70,6 +70,29 @@ module Pgbus
     # :round_robin = use read_grouped_rr (fair round-robin across groups).
     attr_reader :group_mode
 
+    # Fair share scheduling across tenants (issue #426). nil = disabled.
+    # Any #call-able receiving the ActiveJob instance at enqueue time and
+    # returning nil (unkeyed), a key (String/Symbol/Integer), or [key, weight]
+    # (weight: positive Numeric, default 1). Keyed jobs are read with
+    # Client#read_batch_fair — a weighted, work-conserving interleave across
+    # keys within each queue. Mutually exclusive with group_mode.
+    attr_reader :fair_share
+
+    # Fair share for event-bus consumers (issue #427). nil = disabled. Any
+    # #call-able receiving the Pgbus::Event at publish time (routing_key,
+    # payload as passed to publish, headers) and returning nil, a key, or
+    # [key, weight] exactly like fair_share. The key rides in the event
+    # envelope and consumers read subscriber queues with
+    # Client#read_batch_fair. Independent of fair_share (jobs).
+    attr_reader :event_fair_share
+
+    # Persist ActiveSupport::CurrentAttributes across enqueue → perform
+    # (issue #430). nil = off (default). :auto = every CurrentAttributes
+    # subclass; an Array of classes/names; or a Hash of class/name =>
+    # { only: [...] } / { except: [...] }. Normalized to :auto or an Array of
+    # { name:, only:, except: } specs (classes are resolved lazily by name).
+    attr_reader :current_attributes
+
     # Archive compaction. Only the user-facing retention window is configurable;
     # the loop interval and batch size are tuned via constants on
     # Pgbus::Process::Dispatcher.
@@ -268,6 +291,9 @@ module Pgbus
       @priority_levels = nil
       @default_priority = 1
       @group_mode = nil
+      @fair_share = nil
+      @event_fair_share = nil
+      @current_attributes = nil
 
       @archive_retention = 7 * 24 * 3600 # 7 days
       @batch_retention = 7 * 24 * 3600 # 7 days
@@ -608,6 +634,28 @@ module Pgbus
       @group_mode = coerced
     end
 
+    def current_attributes=(value)
+      @current_attributes = Pgbus::CurrentAttributes.normalize(value)
+    end
+
+    def fair_share=(callable)
+      unless callable.nil? || callable.respond_to?(:call)
+        raise Pgbus::ConfigurationError,
+              "fair_share must be nil or respond to #call (got #{callable.class})"
+      end
+
+      @fair_share = callable
+    end
+
+    def event_fair_share=(callable)
+      unless callable.nil? || callable.respond_to?(:call)
+        raise Pgbus::ConfigurationError,
+              "event_fair_share must be nil or respond to #call (got #{callable.class})"
+      end
+
+      @event_fair_share = callable
+    end
+
     VALID_CONNECTION_GUC_MODES = %i[options session].freeze
 
     def connection_guc_mode=(mode)
@@ -783,6 +831,7 @@ module Pgbus
       validate_job_path_gaps!
       validate_streams!
       validate_metrics_backend!
+      validate_fair_share!
 
       self
     end
@@ -863,6 +912,14 @@ module Pgbus
       raise Pgbus::ConfigurationError, "connects_to must be a Hash or nil"
     end
 
+    def validate_fair_share!
+      return unless fair_share && group_mode
+
+      raise Pgbus::ConfigurationError,
+            "fair_share and group_mode are mutually exclusive — fair_share interleaves across keys " \
+            "within a queue, group_mode serializes PGMQ FIFO groups; pick one"
+    end
+
     def validate_streams!
       unless streams_default_retention.is_a?(Numeric) && streams_default_retention >= 0
         raise Pgbus::ConfigurationError, "streams_default_retention must be a non-negative number"

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

@@ -75,6 +75,7 @@ module Pgbus
         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