search-engine-for-typesense 30.9.1 → 30.9.3

data/lib/search_engine/indexing_run_store/rails_cache.rb

@@ -7,7 +7,7 @@ module SearchEngine
   module IndexingRunStore
     # Rails.cache-backed implementation for async partition indexing run metadata.
     class RailsCache
-      # @param cache [Object, nil] cache object responding to read/write/delete
+      # @param cache [Object, nil] Rails-compatible cache responding to read/write/delete
       def initialize(cache: nil)
         @cache = cache || resolve_rails_cache!
         validate_cache!
@@ -29,17 +29,17 @@ module SearchEngine
           created_at: SearchEngine::IndexingRun.iso8601_now,
           updated_at: SearchEngine::IndexingRun.iso8601_now
         }
-        write_meta(run, ttl_s: ttl_s)
+        write!(meta_cache_key(run_id), run, ttl_s: ttl_s)
         entries.each do |partition_key, entry|
-          @cache.write(partition_cache_key(run_id, partition_key), entry, expires_in: ttl_s)
+          write!(partition_cache_key(run_id, partition_key), entry, ttl_s: ttl_s)
         end
         snapshot(run_id: run_id)
       end
 
       # Mark a partition as started.
-      # @return [Hash]
-      def mark_started(run_id:, partition_key:, job_id: nil)
-        update_partition(run_id, partition_key) do |entry|
+      # @return [Hash, nil] run snapshot when requested
+      def mark_started(run_id:, partition_key:, job_id: nil, return_snapshot: true)
+        update_partition(run_id, partition_key, return_snapshot:) do |entry|
           ensure_non_terminal!(entry, 'start')
           entry[:status] = 'running'
           entry[:attempts] = entry[:attempts].to_i + 1
@@ -49,9 +49,9 @@ module SearchEngine
 
       # Record one failed import attempt without terminalizing the partition.
       # ActiveJob may safely start the same partition again on retry.
-      # @return [Hash]
-      def record_attempt(run_id:, partition_key:, summary:, error:)
-        update_partition(run_id, partition_key) do |entry|
+      # @return [Hash, nil] run snapshot when requested
+      def record_attempt(run_id:, partition_key:, summary:, error:, return_snapshot: true)
+        update_partition(run_id, partition_key, return_snapshot:) do |entry|
           ensure_non_terminal!(entry, 'record an attempt for')
           assign_summary!(entry, summary)
           entry[:status] = 'running'
@@ -60,9 +60,9 @@ module SearchEngine
       end
 
       # Mark a partition as succeeded with import counters.
-      # @return [Hash]
-      def mark_succeeded(run_id:, partition_key:, summary:)
-        update_partition(run_id, partition_key) do |entry|
+      # @return [Hash, nil] run snapshot when requested
+      def mark_succeeded(run_id:, partition_key:, summary:, return_snapshot: true)
+        update_partition(run_id, partition_key, return_snapshot:) do |entry|
           ensure_non_terminal!(entry, 'succeed')
           assign_summary!(entry, summary)
           entry[:status] = 'succeeded'
@@ -71,9 +71,9 @@ module SearchEngine
       end
 
       # Mark a partition as failed.
-      # @return [Hash]
-      def mark_failed(run_id:, partition_key:, error:)
-        update_partition(run_id, partition_key) do |entry|
+      # @return [Hash, nil] run snapshot when requested
+      def mark_failed(run_id:, partition_key:, error:, return_snapshot: true)
+        update_partition(run_id, partition_key, return_snapshot:) do |entry|
           ensure_not_succeeded!(entry)
           entry[:status] = 'failed'
           entry[:sample_error] = error_message(error) if entry[:sample_error].to_s.strip.empty?
@@ -87,14 +87,13 @@ module SearchEngine
         meta = symbolize_meta(@cache.read(meta_cache_key(run_id)))
         return nil unless meta
 
-        partition_keys = Array(meta[:partition_keys]).map(&:to_s)
-        partitions = partition_keys.each_with_object({}) do |partition_key, hash|
-          entry = @cache.read(partition_cache_key(run_id, partition_key))
-          hash[partition_key] = if entry.is_a?(Hash)
-                                  deep_symbolize(entry)
-                                else
-                                  missing_partition_entry(partition_key)
-                                end
+        cache_keys = Array(meta[:partition_keys]).to_h do |partition_key|
+          [partition_key.to_s, partition_cache_key(run_id, partition_key)]
+        end
+        entries = read_entries(cache_keys.values)
+        partitions = cache_keys.to_h do |partition_key, cache_key|
+          entry = entries[cache_key]
+          [partition_key, entry.is_a?(Hash) ? deep_symbolize(entry) : missing_partition_entry(partition_key)]
         end
         meta[:partitions] = partitions
         meta[:status] = run_status(partitions)
@@ -150,30 +149,42 @@ module SearchEngine
         end
       end
 
-      def write_meta(run, ttl_s:)
-        @cache.write(meta_cache_key(run[:run_id]), run, expires_in: ttl_s)
+      def read_entries(keys)
+        return {} if keys.empty?
+        return @cache.read_multi(*keys) if @cache.respond_to?(:read_multi)
+
+        keys.to_h { |key| [key, @cache.read(key)] }
       end
 
-      def update_partition(run_id, partition_key)
-        meta = symbolize_meta(@cache.read(meta_cache_key(run_id)))
-        raise StaleRun, "indexing run not found: #{run_id}" unless meta
+      def write!(key, value, ttl_s:)
+        return if @cache.write(key, value, expires_in: ttl_s)
+
+        raise IOError, "failed to write indexing run cache entry #{key}"
+      end
 
+      def update_partition(run_id, partition_key, return_snapshot:)
         partition_key = partition_key.to_s
-        unless Array(meta[:partition_keys]).map(&:to_s).include?(partition_key)
+        cache_key = partition_cache_key(run_id, partition_key)
+        meta_key = meta_cache_key(run_id)
+        entries = read_entries([meta_key, cache_key])
+        meta = symbolize_meta(entries[meta_key])
+        raise StaleRun, "indexing run not found: #{run_id}" unless meta
+
+        unless Array(meta[:partition_keys]).any? { |key| key.to_s == partition_key }
           raise StaleRun, "indexing run partition not found: #{partition_key}"
         end
 
-        entry = @cache.read(partition_cache_key(run_id, partition_key))
+        entry = entries[cache_key]
         raise StaleRun, "indexing run partition not found: #{partition_key}" unless entry
 
         entry = deep_symbolize(entry)
         yield entry
         now = SearchEngine::IndexingRun.iso8601_now
         entry[:updated_at] = now
-        @cache.write(partition_cache_key(run_id, partition_key), entry, expires_in: meta[:ttl_s])
+        write!(cache_key, entry, ttl_s: meta[:ttl_s])
         meta[:updated_at] = now
-        write_meta(meta, ttl_s: meta[:ttl_s])
-        snapshot(run_id: run_id)
+        write!(meta_key, meta, ttl_s: meta[:ttl_s])
+        snapshot(run_id: run_id) if return_snapshot
       end
 
       def run_status(partitions)

data/lib/search_engine/indexing_run_store.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'active_support/core_ext/object/with_options'
+
 module SearchEngine
   # Resolver and interface contract for async partition indexing run stores.
   module IndexingRunStore
@@ -20,6 +22,14 @@ module SearchEngine
       default
     end
 
+    # Worker and timeout transitions only need to persist the affected partition.
+    # Custom stores keep their configured transition signatures.
+    def partition_writer(store = resolve)
+      return store unless defined?(RailsCache) && store.instance_of?(RailsCache)
+
+      store.with_options(return_snapshot: false)
+    end
+
     # Build the default run store.
     # @return [SearchEngine::IndexingRunStore::RailsCache]
     def default

data/lib/search_engine/joins/guard.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'search_engine/registry'
+
 module SearchEngine
   module Joins
     # Stateless guard for validating join usage across Relation and Parser.
@@ -85,28 +87,32 @@ module SearchEngine
         )
       end
 
+      # Structured filters use association names; native expressions can also
+      # name a physical collection directly. A missing registration has no
+      # local schema. Errors loading an existing registration must propagate.
+      def target_model(source_klass, name)
+        association = source_klass.joins_config[name.to_sym] if source_klass.respond_to?(:joins_config)
+        SearchEngine.collection_for(association ? association.fetch(:collection) : name) { nil }
+      end
+
       # Validate that a joined field exists on the target collection when the
       # target model is registered and exposes attributes.
       #
-      # Best-effort: when registry or attributes are unavailable, no exception
-      # is raised (prefer low-noise behavior on missing metadata).
+      # Collections without a local model leave validation to Typesense.
       #
       # @param assoc_cfg [Hash] normalized association config
       # @param field [Symbol, String]
       # @param source_klass [Class, nil] optional source model class for error messages
+      # @param target_klass [Class, nil] already resolved target model, if available
       # @raise [SearchEngine::Errors::UnknownJoinField]
       # @return [void]
-      def validate_joined_field!(assoc_cfg, field, source_klass: nil)
+      def validate_joined_field!(assoc_cfg, field, source_klass: nil, target_klass: nil)
         return if assoc_cfg.nil?
 
         collection = assoc_cfg[:collection]
         return if blank?(collection)
 
-        target_klass = begin
-          SearchEngine.collection_for(collection)
-        rescue StandardError
-          nil
-        end
+        target_klass ||= SearchEngine.collection_for(collection) { nil }
         return unless target_klass.respond_to?(:attributes)
 
         known = Array(target_klass.attributes).map { |k, _| k.to_s }

data/lib/search_engine/multi.rb

@@ -5,7 +5,7 @@ require 'set'
 module SearchEngine
   # Builder for assembling labeled Relations into a federated multi-search.
   #
-  # Pure collector: validates labels and relations, preserves insertion order,
+  # Validates labels and relations, preserves insertion order,
   # and produces per-search payload hashes ready for {SearchEngine::Client#multi_search}.
   #
   # Usage (via the module-level convenience):
@@ -21,7 +21,7 @@ module SearchEngine
     URL_ONLY_KEYS = %i[use_cache cache_ttl].freeze
 
     # Keys that must be present/retained for :only mode in multi-search payloads.
-    ESSENTIAL_MULTI_KEYS = %i[collection q page per_page preset].freeze
+    ESSENTIAL_MULTI_KEYS = %i[collection q page per_page offset limit preset].freeze
 
     # Canonicalize a label into a case-insensitive Symbol key.
     # @param label [String, Symbol]
@@ -90,7 +90,7 @@ module SearchEngine
     # Presets:
     # - Preset token lives inside each per-search payload under :preset (never top-level)
     # - mode=:merge — pass through compiler output (includes :preset)
-    # - mode=:only  — retain only ESSENTIAL_MULTI_KEYS (collection,q,page,per_page,preset) after common merge
+    # - mode=:only  — retain only ESSENTIAL_MULTI_KEYS after common merge
     # - mode=:lock  — defensively drop any keys present in Config.presets.locked_domains from the merged payload
     #                 (conflict recording remains in single-search compile)
     #
@@ -107,7 +107,7 @@ module SearchEngine
     def to_payloads(common: {})
       raise ArgumentError, 'common must be a Hash' unless common.is_a?(Hash)
 
-      filtered_common = filter_url_only_keys(common)
+      filtered_common = filter_url_only_keys(common).transform_keys(&:to_sym)
 
       seen = Set.new
       @entries.map do |e|
@@ -129,8 +129,14 @@ module SearchEngine
 
         collection = collection_name_for_relation(e.relation)
 
-        # Shallow-merge with per-search winning
-        merged = filtered_common.merge(per_search)
+        common_params = if per_search.key?(:offset) || per_search.key?(:limit)
+                          filtered_common.except(:page, :per_page)
+                        elsif per_search.key?(:page) || per_search.key?(:per_page)
+                          filtered_common.except(:offset, :limit)
+                        else
+                          filtered_common
+                        end
+        merged = common_params.merge(per_search)
         payload = { collection: collection }.merge(EssentialPruner.prune(merged, relation: e.relation))
         prune_empty_values(payload)
       end
@@ -142,6 +148,28 @@ module SearchEngine
       @entries.map { |e| e.relation.klass }
     end
 
+    # Execute the labeled searches together. Typed results retain each relation's context.
+    # Raw responses expose the complete backend envelope, including per-search errors.
+    def execute(common: {}, client: nil, url_opts: {}, raw: false)
+      keys = labels
+      enforce_multi_limit!(keys.size, SearchEngine.config.multi_search_limit)
+      searches = to_payloads(common: common)
+      client ||= SearchEngine.client
+      url_opts = search_url_options(client, url_opts)
+      payload = build_multi_event_payload(keys.size, keys, url_opts)
+
+      Instrumentation.instrument('search_engine.multi_search', payload) do |ctx|
+        begin
+          response = client.multi_search(searches: searches, url_opts: url_opts)
+        rescue Errors::Api => error
+          ctx[:http_status] = error.status
+          raise augment_multi_api_error(error, keys)
+        end
+        ctx[:http_status] = 200
+        raw ? response : to_result(response, keys)
+      end
+    end
+
     # ResultSet maps labels to {SearchEngine::Result} while preserving order.
     class ResultSet
       # @param pairs [Array<Array(Symbol, SearchEngine::Result)>>] ordered (label, result) pairs
@@ -195,6 +223,64 @@ module SearchEngine
 
     private
 
+    # Hydrate each result with the selection, facets and constraints of its relation.
+    def to_result(response, keys)
+      items = response[:results] || response['results'] if response.is_a?(Hash)
+      MultiResult.new(labels: keys, raw_results: items) do |raw, index|
+        relation = @entries.fetch(index).relation
+        if relation.is_a?(Relation)
+          relation.send(:enforce_hit_validator_if_needed!, raw[:found] || raw['found'])
+          Result.new(raw, **Hydration::Materializers.result_options(relation))
+        else
+          Result.new(raw, klass: relation.klass)
+        end
+      end
+    end
+
+    def enforce_multi_limit!(count, limit)
+      return unless count > limit
+
+      raise ArgumentError,
+            "multi_search: #{count} searches exceed limit (#{limit}). " \
+            'Increase `SearchEngine.config.multi_search_limit` if necessary.'
+    end
+
+    def search_url_options(client, overrides)
+      defaults = if client.respond_to?(:search_url_options)
+                   client.search_url_options
+                 else
+                   ClientOptions.url_options_from_config
+                 end
+      options = defaults.merge(overrides)
+      disabled = @entries.any? do |entry|
+        entry.relation.is_a?(Relation) && entry.relation.send(:build_url_opts)[:use_cache] == false
+      end
+      options[:use_cache] = false if disabled
+      options
+    end
+
+    def build_multi_event_payload(count, labels, url_opts)
+      {
+        searches_count: count,
+        labels: labels.map(&:to_s),
+        http_status: nil,
+        source: :multi,
+        url_opts: Observability.filtered_url_opts(url_opts)
+      }
+    end
+
+    def augment_multi_api_error(error, labels)
+      body = error.body
+      results = body[:results] || body['results'] if body.is_a?(Hash)
+      return error unless results.is_a?(Array)
+
+      labels.each_with_index do |label, index|
+        failure = MultiResult.entry_error(label, results[index])
+        return Errors::Api.new(failure.message, status: error.status, body: body) if failure
+      end
+      error
+    end
+
     def validate_relation!(relation)
       unless relation.respond_to?(:to_typesense_params) && relation.respond_to?(:klass)
         raise ArgumentError, 'relation must respond to :to_typesense_params and :klass'

data/lib/search_engine/multi_result.rb

@@ -28,6 +28,21 @@ module SearchEngine
   #   mr.dig('brands').to_a
   #   mr.labels #=> [:products, :brands]
   class MultiResult
+    attr_reader :result_set
+
+    # Typesense can report individual failures inside a successful HTTP response.
+    def self.entry_error(label, item)
+      return unless item.is_a?(Hash)
+
+      code = item[:code] || item['code'] || item[:status] || item['status']
+      status = Integer(code, exception: false)
+      return unless item[:error] || item['error'] || (status && !(200..299).cover?(status))
+
+      message = "Multi-search failed for label :#{label}"
+      message += " (status #{status})" if status
+      Errors::Api.new("#{message}.", status: status, body: item)
+    end
+
     # Build a new MultiResult.
     #
     # @param labels [Array<String, Symbol>] ordered labels
@@ -36,36 +51,38 @@ module SearchEngine
     # @raise [ArgumentError] when sizes mismatch, labels invalid/duplicate, or inputs malformed
     # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/multi-search-guide`
     def initialize(labels:, raw_results:, klasses: nil)
-      @labels = canonicalize_labels(labels)
-      @map = {}
-
-      # Store the raw array privately to document the one-time network call and hydration
-      @raw_results = Array(raw_results).freeze
-
-      validate_sizes!(@labels, @raw_results, klasses)
-
-      klass_by_index = build_klass_index(@labels, klasses)
-
-      @labels.each_with_index do |label, index|
-        raw = @raw_results[index]
-        kls = klass_by_index[index] || infer_klass_from_raw(raw)
-        @map[label] = SearchEngine::Result.new(raw, klass: kls)
+      keys = canonicalize_labels(labels)
+      validate_sizes!(keys, raw_results, klasses)
+      keys.each_with_index do |label, index|
+        raw = raw_results[index]
+        raise ArgumentError, "Expected a result Hash for label :#{label}" unless raw.is_a?(Hash)
+
+        failure = MultiResult.entry_error(label, raw)
+        raise failure if failure
       end
 
+      klass_by_index = build_klass_index(keys, klasses)
+      pairs = keys.each_with_index.map do |label, index|
+        raw = raw_results[index]
+        result = if block_given?
+                   yield(raw, index)
+                 else
+                   Result.new(raw, klass: klass_by_index[index] || infer_klass_from_raw(raw))
+                 end
+        [label, result]
+      end
+      @result_set = Multi::ResultSet.new(pairs)
       freeze
     end
 
-    # Return a shallow copy of labels to preserve immutability.
-    # @return [Array<Symbol>]
+    # Return a shallow copy of the ordered labels.
     def labels
-      @labels.dup
+      @result_set.labels
     end
 
-    # Fetch a Result by label.
-    # @param label [String, Symbol]
-    # @return [SearchEngine::Result, nil]
+    # Fetch a result by its case-insensitive label.
     def [](label)
-      @map[SearchEngine::Multi.canonicalize_label(label)]
+      @result_set[label]
     rescue ArgumentError
       nil
     end
@@ -87,7 +104,7 @@ module SearchEngine
     # Pure helper: returns a shallow copy and never performs HTTP.
     # @return [Hash{Symbol=>SearchEngine::Result}]
     def to_h
-      @map.dup
+      @result_set.to_h
     end
 
     # Iterate over (label, result) in insertion order.
@@ -98,7 +115,7 @@ module SearchEngine
     def each_label
       return enum_for(:each_label) unless block_given?
 
-      @labels.each { |l| yield([l, @map[l]]) }
+      @result_set.each_pair { |label, result| yield([label, result]) }
     end
 
     # Convenience to map over (label, result) pairs.

data/lib/search_engine/notifications/compact_logger.rb

@@ -335,7 +335,7 @@ module SearchEngine
                         {}
                       end
         parts = []
-        %i[q query_by per_page page infix].each do |key|
+        %i[q query_by per_page page limit offset infix].each do |key|
           next unless params_hash.key?(key)
 
           parts << format_param(key, params_hash[key])
@@ -540,7 +540,7 @@ module SearchEngine
       private_class_method :attach_grouping_fields!
 
       def self.attach_selected_params!(h, params_hash)
-        %i[q query_by per_page page infix].each do |key|
+        %i[q query_by per_page page limit offset infix].each do |key|
           h[key.to_s] = params_hash[key] if params_hash.key?(key)
         end
         h['filter_by'] = '***' if params_hash.key?(:filter_by)

data/lib/search_engine/observability.rb

@@ -12,7 +12,7 @@ module SearchEngine
 
     # Whitelisted search parameter keys to include in payload excerpts.
     PARAM_WHITELIST = %i[
-      q query_by include_fields exclude_fields per_page page infix filter_by sort_by
+      q query_by include_fields exclude_fields per_page page limit offset infix filter_by sort_by
       group_by group_limit group_missing_values
       facet_by max_facet_values facet_query
       num_typos drop_tokens_threshold prioritize_exact_match query_by_weights
@@ -110,7 +110,7 @@ module SearchEngine
       return str unless str.is_a?(String)
 
       # Mask obvious quoted literals first
-      redacted = str.gsub(/"[^"]*"|'[^']*'/, '***')
+      redacted = str.gsub(/`[^`]*`|"[^"]*"|'[^']*'/, '***')
 
       # Mask numeric literals (best-effort)
       redacted.gsub(/\b\d+(?:\.\d+)?\b/, '***')
@@ -124,10 +124,10 @@ module SearchEngine
     def self.redact_filter_by(filter)
       return filter unless filter.is_a?(String)
 
-      # Replace values that follow a comparator or a colon with *** until a
-      # delimiter is reached. Also mask quoted strings and numbers.
-      masked = filter.gsub(/([!:><=]{1,2})\s*([^\s)&|]+)/, '\1***')
-      masked = masked.gsub(/"[^"]*"|'[^']*'/, '***')
+      # Mask whole literals first: their contents may look like expressions.
+      # Once quoted values are gone, a list can safely be masked as a unit.
+      masked = filter.gsub(/`[^`]*`|"[^"]*"|'[^']*'/, '***').gsub(/\[[^\]]*\]/, '***')
+      masked = masked.gsub(/([!:><=]{1,2})\s*([^\s)&|]+)/, '\1***')
       masked.gsub(/\b\d+(?:\.\d+)?\b/, '***')
     end
 

data/lib/search_engine/postgres_outbox/database_queries.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  module PostgresOutbox
+    # Operational reads must observe current delivery state and acquire row locks on each poll.
+    module DatabaseQueries
+      private
+
+      def select_rows(sql)
+        result = connection.respond_to?(:exec_query) ? connection.exec_query(sql) : connection.select_all(sql)
+        return result.to_a if result.respond_to?(:to_a)
+
+        Array(result)
+      end
+    end
+  end
+end

data/lib/search_engine/postgres_outbox/drainer.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'socket'
-require 'securerandom'
 require 'set'
 require 'search_engine/cache'
 
@@ -10,7 +9,6 @@ module SearchEngine
     # Orchestrates one bounded PostgreSQL outbox drain pass.
     class Drainer
       BLOCKED_ERROR = 'Skipped because an earlier outbox collection group failed'
-      LEASE_OWNER_MAX_LENGTH = 255
 
       # @param repository [SearchEngine::PostgresOutbox::Repository]
       # @param processor [#call]
@@ -31,8 +29,8 @@ module SearchEngine
           'search_engine.postgres_outbox.drain',
           drain_payload(limit)
         ) do |payload|
-          lease_owner = next_lease_owner
-          events = repository.claim_pending(limit: limit, worker_id: lease_owner)
+          lease_owner = Event.new_lease_owner(worker_id) unless repository_assigns_lease_owner?
+          events = repository.claim_pending(limit: limit, worker_id: lease_owner || worker_id)
           summary = empty_summary(events)
           next summary if events.empty?
 
@@ -43,7 +41,7 @@ module SearchEngine
           record_acknowledgements(summary, :superseded, superseded_events, superseded_ids)
 
           ordered = SearchEngine::DependencyPlanner.order_events(kept)
-          process_ordered_events(ordered, summary, lease_owner: lease_owner)
+          process_ordered_events(ordered, summary, lease_owner: lease_owner || events.first.event_lease_owner)
           payload.merge!(summary)
           summary
         end
@@ -53,6 +51,10 @@ module SearchEngine
 
       attr_reader :repository, :processor, :worker_id, :target_key
 
+      def repository_assigns_lease_owner?
+        repository.respond_to?(:assigns_event_lease_owner?) && repository.assigns_event_lease_owner?
+      end
+
       def empty_summary(events)
         summary = {
           claimed: events.size,
@@ -250,13 +252,6 @@ module SearchEngine
         "#{Socket.gethostname}:#{$PROCESS_ID}:#{Thread.current.object_id}"
       end
 
-      def next_lease_owner
-        suffix = SecureRandom.uuid
-        prefix_limit = LEASE_OWNER_MAX_LENGTH - suffix.length - 1
-        prefix = worker_id.to_s.gsub(/[^a-zA-Z0-9_.:-]/, '_')[0, prefix_limit]
-        "#{prefix}:#{suffix}"
-      end
-
       def processor_context(lease_owner)
         context = { worker_id: worker_id, lease_owner: lease_owner }
         context[:target_key] = target_key if target_key

data/lib/search_engine/postgres_outbox/event.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
+require 'securerandom'
+
 module SearchEngine
   module PostgresOutbox
     # Immutable value object for one PostgreSQL outbox row.
     class Event
+      LEASE_OWNER_MAX_LENGTH = 255
       VALID_OPERATIONS = %i[upsert delete].freeze
 
       attr_reader :id,
@@ -16,10 +19,18 @@ module SearchEngine
                   :attempts,
                   :payload,
                   :created_at,
+                  :event_lease_owner,
                   :delivery_id,
                   :target_key,
                   :delivery_lease_owner
 
+      def self.new_lease_owner(worker_id)
+        suffix = SecureRandom.uuid
+        prefix_limit = LEASE_OWNER_MAX_LENGTH - suffix.length - 1
+        prefix = worker_id.to_s.gsub(/[^a-zA-Z0-9_.:-]/, '_')[0, prefix_limit]
+        "#{prefix}:#{suffix}"
+      end
+
       # @param row [Hash] outbox row with string or symbol keys
       # @raise [ArgumentError] when operation is not upsert/delete
       def initialize(row)
@@ -33,6 +44,7 @@ module SearchEngine
         @attempts = (value(row, :delivery_attempts) || value(row, :attempts)).to_i
         @payload = value(row, :payload) || {}
         @created_at = value(row, :created_at)
+        @event_lease_owner = string_value(row, :event_lease_owner)
         @delivery_id = value(row, :delivery_id)
         @target_key = string_value(row, :target_key)
         @delivery_lease_owner = string_value(row, :delivery_lease_owner)