search-engine-for-typesense 30.1.8.13 → 30.1.8.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 680a9c687c571328d2ed1e521cb93b9a2d1962ec53bbeb7b315042015a150506
-  data.tar.gz: 64250ee42b7643fcdc3979a1e10c05d3d22bfcda11cf282dc1635566ca0f63e4
+  metadata.gz: 68b92138a4716df3c14da84a5f66b26f30bbdcb6afcb8d54f19d953c6652d1ed
+  data.tar.gz: 7f21c4f3ea8216ad390494f9ca813a3829b80b15b8948f3ea5523f566d101368
 SHA512:
-  metadata.gz: 5f6a796bf120e04de8c2a55e4cf662b6e83b5f4a38b2e76315e0f8c79780d383d8f3673b65de5b1218ebfd36388f5dc47a08d385428a824ad26bedaddd09f4b8
-  data.tar.gz: 1837a2de35e82c7f7e7878eb39a6844d7b96d3767509a0c3829cc62fd12a126ff4f53d6284475c464e3db6c8395444065ac308d1ef673361f83ed33f97ead872
+  metadata.gz: 0cec597cc88d5553ac833035e7e974ea3f6683d1efeaf1c2a2f2431f004c78a5ccfdee27e4eb22c513a0e95f8c2275e28b2b2158fb6d8d95b3846328f45633e4
+  data.tar.gz: 0a3d95f6df6dba0f0ea9bbdb93fe6224a3b5b2d7cefa0907504273a004c095750f1a9a9f7d67b3e60180dcbf019a01ab55bd137fc5cde563c76c28634a401e3b

data/README.md

@@ -218,9 +218,13 @@ SearchEngine.configure do |c|
   c.postgres_outbox.listener_enabled = -> { Rails.env.production? }
   c.postgres_outbox.table_name = "search_engine_outbox_events"
   c.postgres_outbox.delivery_table_name = "search_engine_outbox_deliveries"
+  c.postgres_outbox.drain_slot_table_name = "search_engine_outbox_drain_slots"
   c.postgres_outbox.channel = "search_engine_outbox"
   c.postgres_outbox.queue_name = "search_engine"
   c.postgres_outbox.batch_size = 1000
+  c.postgres_outbox.drain_target_parallelism = 1
+  c.postgres_outbox.drain_job_max_batches = 1
+  c.postgres_outbox.drain_job_max_runtime_s = nil
   c.postgres_outbox.poll_interval_s = 5
   c.postgres_outbox.retention_s = 7.days.to_i
 
@@ -230,7 +234,7 @@ SearchEngine.configure do |c|
   # Optional. Leave empty for the default single-target flow.
   c.postgres_outbox.delivery_targets = lambda do
     [
-      { key: :mirror_a, queue_name: :search_engine_mirror_a },
+      { key: :mirror_a, queue_name: :search_engine_mirror_a, parallelism: 2 },
       { key: :mirror_b, queue_name: :search_engine_mirror_b }
     ]
   end
@@ -251,8 +255,9 @@ class CreateSearchEngineOutboxEvents < ActiveRecord::Migration[7.1]
 
   def change
     create_search_engine_outbox_events
-    # Required only when c.postgres_outbox.delivery_targets is configured.
+    # Required only when c.postgres_outbox.delivery_targets is configured:
     create_search_engine_outbox_deliveries
+    create_search_engine_outbox_drain_slots
   end
 end
 ```
@@ -290,11 +295,42 @@ end
 PL/pgSQL `record_data` variable, which is `NEW` for inserts/updates and `OLD` for deletes.
 
 The event table stores logical changes. When `delivery_targets` is empty, drain jobs claim those event rows
-directly and existing single-target setups do not need to create or use delivery rows. When you configure
-delivery targets, `search_engine_outbox_deliveries` stores target-specific status, retry, lock, and queue
-state for each logical event. The listener uses the drain enqueuer to materialize missing delivery rows and
-enqueue one drain job per target queue. Processors still receive event objects and return event IDs; the
-parent event status is refreshed from the aggregate delivery states.
+directly and existing single-target setups do not need to create or use delivery rows, drain slots, or the
+drain slot table. When you configure delivery targets, `search_engine_outbox_deliveries` stores
+target-specific status, retry, lock, and queue state for each logical event. Add
+`create_search_engine_outbox_drain_slots` in that delivery-target migration so the drain enqueuer can cap
+queued and running drain jobs per target.
+
+Drain slots are a generic backpressure mechanism for delivery-target mode. On each listener or polling
+wakeup, the enqueuer materializes missing delivery rows, acquires idle slots from
+`c.postgres_outbox.drain_slot_table_name`, and enqueues one drain job per acquired slot. If all slots for a
+target are already queued or processing, that wakeup does not enqueue another job for the target.
+
+`c.postgres_outbox.drain_target_parallelism` controls the default maximum concurrent drain jobs per delivery
+target. Individual targets can override it with `parallelism:`:
+
+```ruby
+SearchEngine.configure do |c|
+  c.postgres_outbox.drain_target_parallelism = 2
+  c.postgres_outbox.delivery_targets = [
+    { key: :mirror_a, queue_name: :search_engine_mirror_a },
+    { key: :mirror_b, queue_name: :search_engine_mirror_b, parallelism: 4 }
+  ]
+end
+```
+
+Slot-aware drain jobs do finite work. `c.postgres_outbox.drain_job_max_batches` limits how many batches a
+job may drain before yielding, and `c.postgres_outbox.drain_job_max_runtime_s` optionally adds a runtime
+budget. When a slot-aware job reaches either bound while more work remains, it requeues the same slot instead
+of acquiring a new one. When no more work is indicated, it releases the slot back to `idle`.
+
+Already-enqueued target jobs without a `drain_slot` argument remain compatible. If the drain slot table
+exists, those old jobs route through the slot-aware enqueuer for their continuations; if the table does not
+exist, the gem falls back to the previous one-job-per-target behavior. This keeps staged rollouts safe while
+hosts add the optional drain slot table.
+
+Processors still receive event objects and return event IDs; the parent event status is refreshed from the
+aggregate delivery states.
 
 Pair triggered source models with `sync_strategy: :postgres_outbox` so Active Record callbacks do not also
 write to Typesense for the same changes:

data/app/search_engine/search_engine/postgres_outbox/drain_job.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'socket'
+
 module SearchEngine
   module PostgresOutbox
     # ActiveJob entrypoint for one bounded PostgreSQL outbox drain pass.
@@ -11,10 +13,14 @@ module SearchEngine
       # Drain pending outbox events once when PostgreSQL outbox processing is enabled.
       # @param limit [Integer, nil] optional maximum number of events to claim
       # @param target_key [String, Symbol, nil] optional delivery target scope
+      # @param drain_slot [Integer, nil] optional acquired drain slot
       # @return [Hash, nil]
-      def perform(limit: nil, target_key: nil)
+      def perform(limit: nil, target_key: nil, drain_slot: nil)
         return nil unless SearchEngine.config.postgres_outbox.enabled
         return enqueue_target_drains(limit: limit) if target_key.nil? && delivery_targets.any?
+        unless drain_slot.nil?
+          return perform_with_drain_slot(limit: limit, target_key: target_key, drain_slot: drain_slot)
+        end
 
         effective_limit = limit || SearchEngine.config.postgres_outbox.batch_size
         drainer = drainer_for(target_key)
@@ -31,6 +37,57 @@ module SearchEngine
         { claimed: 0, processed: 0, enqueued_targets: delivery_targets.size }
       end
 
+      def perform_with_drain_slot(limit:, target_key:, drain_slot:)
+        target = delivery_target_for!(target_key)
+        slot = drain_slot.to_i
+        effective_limit = limit || SearchEngine.config.postgres_outbox.batch_size
+        repository = repository_for_slot
+        return stale_slot_summary(target.key, slot) unless repository.start_drain_slot!(
+          target_key: target.key,
+          slot: slot,
+          worker_id: worker_id
+        )
+
+        summary = drain_slot_batches(limit: effective_limit, target_key: target.key, drain_slot: slot)
+        if summary.delete(:more_work)
+          requeued = repository.requeue_drain_slot!(
+            target_key: target.key,
+            slot: slot,
+            worker_id: worker_id
+          )
+          enqueue_target_continuation(limit: limit, target_key: target.key, drain_slot: slot) if requeued
+        else
+          repository.release_drain_slot!(target_key: target.key, slot: slot, worker_id: worker_id)
+        end
+        summary
+      rescue StandardError => error
+        if repository && target && slot
+          repository.release_drain_slot!(target_key: target.key, slot: slot, worker_id: worker_id, error: error)
+        end
+        raise
+      end
+
+      def drain_slot_batches(limit:, target_key:, drain_slot:)
+        drainer = drainer_for(target_key)
+        summary = slot_summary(target_key, drain_slot)
+        max_batches = drain_job_max_batches
+        batches = 0
+        more_work = false
+
+        while batches < max_batches
+          batch_summary = drainer.drain_once(limit: limit)
+          batches += 1
+          merge_batch_summary!(summary, batch_summary)
+          more_work = continue_draining?(batch_summary, limit)
+          break unless more_work
+          break if runtime_budget_exhausted?
+        end
+
+        summary[:batches] = batches
+        summary[:more_work] = more_work
+        summary
+      end
+
       def continue_draining?(summary, effective_limit)
         summary[:continue] || summary[:claimed].to_i >= effective_limit.to_i
       end
@@ -42,18 +99,24 @@ module SearchEngine
       end
 
       def enqueue_continuation(limit:, target_key:)
-        return enqueue_target_continuation(limit: limit, target_key: target_key) unless target_key.nil?
+        if target_key
+          return enqueue_target_drains(limit: limit) if drain_slots_table_exists?
+
+          return enqueue_target_continuation(limit: limit, target_key: target_key)
+        end
         return self.class.perform_later if limit.nil?
 
         self.class.perform_later(limit: limit)
       end
 
-      def enqueue_target_continuation(limit:, target_key:)
+      def enqueue_target_continuation(limit:, target_key:, drain_slot: nil)
         target = delivery_target_for!(target_key)
         job = self.class.set(queue: target.queue_name)
-        return job.perform_later(target_key: target.key) if limit.nil?
+        kwargs = { target_key: target.key }
+        kwargs[:drain_slot] = drain_slot unless drain_slot.nil?
+        kwargs[:limit] = limit unless limit.nil?
 
-        job.perform_later(target_key: target.key, limit: limit)
+        job.perform_later(**kwargs)
       end
 
       def delivery_target_for!(target_key)
@@ -69,6 +132,57 @@ module SearchEngine
         raw_targets = configured.respond_to?(:call) ? configured.call : configured
         Array(raw_targets).map { |target| DeliveryTarget.normalize(target) }
       end
+
+      def repository_for_slot
+        SearchEngine::PostgresOutbox::Repository.new
+      end
+
+      def drain_slots_table_exists?
+        repository_for_slot.drain_slots_table_exists?
+      end
+
+      def worker_id
+        @worker_id ||= "#{Socket.gethostname}:#{Process.pid}:#{job_id}"
+      end
+
+      def slot_summary(target_key, drain_slot)
+        {
+          claimed: 0,
+          processed: 0,
+          superseded: 0,
+          retryable: 0,
+          failed: 0,
+          collections: [],
+          target_key: target_key,
+          drain_slot: drain_slot
+        }
+      end
+
+      def stale_slot_summary(target_key, drain_slot)
+        slot_summary(target_key, drain_slot).merge(stale_slot: true, batches: 0)
+      end
+
+      def merge_batch_summary!(summary, batch_summary)
+        %i[claimed processed superseded retryable failed].each do |key|
+          summary[key] += batch_summary[key].to_i
+        end
+        summary[:collections] |= Array(batch_summary[:collections])
+      end
+
+      def drain_job_max_batches
+        [SearchEngine.config.postgres_outbox.drain_job_max_batches.to_i, 1].max
+      end
+
+      def runtime_budget_exhausted?
+        max_runtime_s = SearchEngine.config.postgres_outbox.drain_job_max_runtime_s.to_i
+        return false unless max_runtime_s.positive?
+
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at >= max_runtime_s
+      end
+
+      def started_at
+        @started_at ||= Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
     end
   end
 end

data/lib/generators/search_engine/postgres_outbox/templates/create_outbox_events.rb.tt

@@ -6,5 +6,6 @@ class CreateSearchEngineOutboxEvents < ActiveRecord::Migration[<%= ActiveRecord:
   def change
     create_search_engine_outbox_events
     create_search_engine_outbox_deliveries
+    create_search_engine_outbox_drain_slots
   end
 end

data/lib/search_engine/config.rb

@@ -272,6 +272,8 @@ module SearchEngine
       attr_accessor :table_name
       # @return [String] database table used by host-managed outbox deliveries
       attr_accessor :delivery_table_name
+      # @return [String] database table used by host-managed drain slots
+      attr_accessor :drain_slot_table_name
       # @return [String] PostgreSQL notification channel for wakeups
       attr_accessor :channel
       # @return [String] queue name used by host app job dispatch
@@ -300,11 +302,18 @@ module SearchEngine
       attr_accessor :retry_backoff
       # @return [#call] resolver returning configured delivery targets
       attr_accessor :delivery_targets
+      # @return [Integer] default maximum concurrent drain jobs per delivery target
+      attr_accessor :drain_target_parallelism
+      # @return [Integer] maximum drain batches a slot-aware job may run before yielding
+      attr_accessor :drain_job_max_batches
+      # @return [Integer, nil] optional runtime budget in seconds for slot-aware drain jobs
+      attr_accessor :drain_job_max_runtime_s
 
       def initialize
         @enabled = false
         @table_name = 'search_engine_outbox_events'
         @delivery_table_name = 'search_engine_outbox_deliveries'
+        @drain_slot_table_name = 'search_engine_outbox_drain_slots'
         @channel = 'search_engine_outbox'
         @queue_name = 'search_engine'
         @batch_size = 1000
@@ -319,6 +328,9 @@ module SearchEngine
         @collection_processors = {}
         @retry_backoff = ->(attempt) { [attempt.to_i, 1].max * 5 }
         @delivery_targets = -> { [] }
+        @drain_target_parallelism = 1
+        @drain_job_max_batches = 1
+        @drain_job_max_runtime_s = nil
       end
     end
 
@@ -870,6 +882,7 @@ module SearchEngine
         enabled: postgres_outbox.enabled ? true : false,
         table_name: postgres_outbox.table_name,
         delivery_table_name: postgres_outbox.delivery_table_name,
+        drain_slot_table_name: postgres_outbox.drain_slot_table_name,
         channel: postgres_outbox.channel,
         queue_name: postgres_outbox.queue_name,
         batch_size: postgres_outbox.batch_size,
@@ -883,7 +896,10 @@ module SearchEngine
         listener_enabled: postgres_outbox.listener_enabled,
         collection_processors: postgres_outbox.collection_processors,
         retry_backoff: postgres_outbox.retry_backoff,
-        delivery_targets: postgres_outbox.delivery_targets
+        delivery_targets: postgres_outbox.delivery_targets,
+        drain_target_parallelism: postgres_outbox.drain_target_parallelism,
+        drain_job_max_batches: postgres_outbox.drain_job_max_batches,
+        drain_job_max_runtime_s: postgres_outbox.drain_job_max_runtime_s
       }
     end
 

data/lib/search_engine/postgres_outbox/delivery_target.rb

@@ -8,12 +8,16 @@ module SearchEngine
       attr_reader :key
       # @return [String] ActiveJob queue name used to process this target
       attr_reader :queue_name
+      # @return [Integer] maximum concurrent drain jobs for this target
+      attr_reader :parallelism
 
       # @param key [String, Symbol] stable target identifier
       # @param queue_name [String, Symbol] queue name for target-specific drain jobs
-      def initialize(key:, queue_name:)
+      # @param parallelism [Integer, #to_i, nil] optional target concurrency cap
+      def initialize(key:, queue_name:, parallelism: nil)
         @key = normalize_value(key, 'key')
         @queue_name = normalize_value(queue_name, 'queue_name')
+        @parallelism = normalize_parallelism(parallelism)
       end
 
       # Normalize a configured target into a DeliveryTarget.
@@ -25,11 +29,16 @@ module SearchEngine
 
         if value.respond_to?(:to_hash)
           hash = value.to_hash
-          return new(key: fetch_hash_value(hash, :key), queue_name: fetch_hash_value(hash, :queue_name))
+          return new(
+            key: fetch_hash_value(hash, :key),
+            queue_name: fetch_hash_value(hash, :queue_name),
+            parallelism: fetch_hash_value(hash, :parallelism)
+          )
         end
 
         if value.respond_to?(:key) && value.respond_to?(:queue_name)
-          return new(key: value.key, queue_name: value.queue_name)
+          parallelism = value.parallelism if value.respond_to?(:parallelism)
+          return new(key: value.key, queue_name: value.queue_name, parallelism: parallelism)
         end
 
         raise ArgumentError, 'delivery target must be a DeliveryTarget, Hash, or target-like object'
@@ -53,6 +62,11 @@ module SearchEngine
 
         normalized
       end
+
+      def normalize_parallelism(value)
+        normalized = value.nil? ? SearchEngine.config.postgres_outbox.drain_target_parallelism : value
+        [normalized.to_i, 1].max
+      end
     end
   end
 end

data/lib/search_engine/postgres_outbox/drain_enqueuer.rb

@@ -28,6 +28,8 @@ module SearchEngine
         return enqueue_legacy(limit: limit) if targets.empty?
 
         materialize_deliveries(limit: limit)
+        return enqueue_acquired_slots(targets, limit: limit) if repository.drain_slots_table_exists?
+
         targets.each { |target| enqueue_target(target, limit: limit) }
         nil
       end
@@ -55,6 +57,20 @@ module SearchEngine
         job.perform_later(target_key: target.key, limit: limit)
       end
 
+      def enqueue_acquired_slots(targets, limit:)
+        repository.acquire_drain_slots!(targets: targets).each do |slot|
+          enqueue_drain_slot(slot, limit: limit)
+        end
+        nil
+      end
+
+      def enqueue_drain_slot(slot, limit:)
+        job = drain_job.set(queue: slot.fetch(:queue_name))
+        kwargs = { target_key: slot.fetch(:target_key), drain_slot: slot.fetch(:slot) }
+        kwargs[:limit] = limit unless limit.nil?
+        job.perform_later(**kwargs)
+      end
+
       def delivery_targets
         raw_targets = targets_resolver ? targets_resolver.call : configured_delivery_targets
         Array(raw_targets).map { |target| DeliveryTarget.normalize(target) }

data/lib/search_engine/postgres_outbox/migration_helpers.rb

@@ -99,6 +99,39 @@ module SearchEngine
                         on_delete: :cascade
       end
 
+      # Create the SearchEngine outbox drain slots table.
+      #
+      # @param table_name [String, Symbol] destination drain slots table name
+      # @return [void]
+      def create_search_engine_outbox_drain_slots(
+        table_name: SearchEngine.config.postgres_outbox.drain_slot_table_name
+      )
+        create_table table_name do |t|
+          t.string :target_key, null: false
+          t.integer :slot, null: false
+          t.string :queue_name, null: false
+          t.string :status, null: false, default: 'idle'
+          t.datetime :locked_at
+          t.string :locked_by
+          t.datetime :enqueued_at
+          t.datetime :started_at
+          t.datetime :finished_at
+          t.text :last_error
+          t.timestamps
+        end
+
+        add_index table_name,
+                  %i[target_key slot],
+                  name: 'idx_se_outbox_drain_slots_unique',
+                  unique: true
+        add_index table_name,
+                  %i[target_key status slot],
+                  name: 'idx_se_outbox_drain_slots_target_status'
+        add_index table_name,
+                  %i[status locked_at],
+                  name: 'idx_se_outbox_drain_slots_stale'
+      end
+
       # Create or replace a row-level PostgreSQL trigger that writes outbox events.
       #
       # @param table_name [String, Symbol] source table name

data/lib/search_engine/postgres_outbox/repository.rb

@@ -128,6 +128,100 @@ module SearchEngine
         rows
       end
 
+      # Check whether the optional drain slot table exists.
+      #
+      # @return [Boolean]
+      def drain_slots_table_exists?
+        if connection.respond_to?(:data_source_exists?)
+          connection.data_source_exists?(drain_slot_table_name)
+        else
+          connection.table_exists?(drain_slot_table_name)
+        end
+      end
+
+      # Acquire idle drain slots for configured delivery targets.
+      #
+      # @param targets [Array<SearchEngine::PostgresOutbox::DeliveryTarget, Hash>]
+      # @return [Array<Hash>] acquired slot descriptors
+      def acquire_drain_slots!(targets:)
+        normalized_targets = Array(targets).map { |target| DeliveryTarget.normalize(target) }
+        return [] if normalized_targets.empty?
+
+        connection.transaction do
+          ensure_drain_slots!(normalized_targets)
+          reset_stale_drain_slots!(normalized_targets)
+          rows = select_rows(acquire_drain_slots_sql(normalized_targets))
+          return rows.map { |row| drain_slot_descriptor(row) }
+        end
+      end
+
+      # Mark an acquired drain slot as processing for the current worker.
+      #
+      # @param target_key [String, Symbol]
+      # @param slot [Integer]
+      # @param worker_id [String]
+      # @return [Boolean] whether the queued slot was claimed by this worker
+      def start_drain_slot!(target_key:, slot:, worker_id:)
+        rows = select_rows(<<~SQL)
+          UPDATE #{quoted_drain_slot_table}
+          SET status = 'processing',
+              locked_at = CURRENT_TIMESTAMP,
+              locked_by = #{quote(worker_id)},
+              started_at = CURRENT_TIMESTAMP,
+              updated_at = CURRENT_TIMESTAMP
+          WHERE target_key = #{quote(target_key)}
+            AND slot = #{slot.to_i}
+            AND status = 'queued'
+          RETURNING target_key, slot
+        SQL
+        rows.any?
+      end
+
+      # Requeue a processing drain slot for a follow-up job.
+      #
+      # @param target_key [String, Symbol]
+      # @param slot [Integer]
+      # @param worker_id [String]
+      # @return [Boolean] whether the current worker still owned and requeued the slot
+      def requeue_drain_slot!(target_key:, slot:, worker_id:)
+        rows = select_rows(<<~SQL)
+          UPDATE #{quoted_drain_slot_table}
+          SET status = 'queued',
+              locked_at = CURRENT_TIMESTAMP,
+              locked_by = NULL,
+              enqueued_at = CURRENT_TIMESTAMP,
+              updated_at = CURRENT_TIMESTAMP
+          WHERE target_key = #{quote(target_key)}
+            AND slot = #{slot.to_i}
+            AND status = 'processing'
+            AND locked_by = #{quote(worker_id)}
+          RETURNING target_key, slot
+        SQL
+        rows.any?
+      end
+
+      # Release a drain slot back to idle.
+      #
+      # @param target_key [String, Symbol]
+      # @param slot [Integer]
+      # @param worker_id [String, nil]
+      # @param error [Exception, String, nil]
+      # @return [void]
+      def release_drain_slot!(target_key:, slot:, worker_id: nil, error: nil)
+        execute(<<~SQL)
+          UPDATE #{quoted_drain_slot_table}
+          SET status = 'idle',
+              locked_at = NULL,
+              locked_by = NULL,
+              finished_at = CURRENT_TIMESTAMP,
+              last_error = #{quote(error.nil? ? nil : truncate_error(error))},
+              updated_at = CURRENT_TIMESTAMP
+          WHERE target_key = #{quote(target_key)}
+            AND slot = #{slot.to_i}
+            #{drain_slot_owner_guard_sql(worker_id)}
+        SQL
+      end
+
       private
 
       attr_reader :target_key
@@ -571,6 +665,98 @@ module SearchEngine
         end.join(', ')
       end
 
+      def ensure_drain_slots!(targets)
+        targets.each do |target|
+          execute(<<~SQL)
+            INSERT INTO #{quoted_drain_slot_table} (
+              target_key,
+              slot,
+              queue_name,
+              status,
+              created_at,
+              updated_at
+            )
+            SELECT #{quote(target.key)},
+                   slot,
+                   #{quote(target.queue_name)},
+                   'idle',
+                   CURRENT_TIMESTAMP,
+                   CURRENT_TIMESTAMP
+            FROM generate_series(1, #{target.parallelism}) AS slot
+            ON CONFLICT (target_key, slot) DO UPDATE
+            SET queue_name = EXCLUDED.queue_name,
+                updated_at = #{quoted_drain_slot_table}.updated_at
+          SQL
+        end
+      end
+
+      def reset_stale_drain_slots!(targets)
+        execute(<<~SQL)
+          UPDATE #{quoted_drain_slot_table}
+          SET status = 'idle',
+              locked_at = NULL,
+              locked_by = NULL,
+              last_error = NULL,
+              updated_at = CURRENT_TIMESTAMP
+          WHERE target_key IN (#{ids_sql(targets.map(&:key))})
+            AND status IN ('queued', 'processing')
+            AND locked_at < (CURRENT_TIMESTAMP - interval '#{processing_timeout_s} seconds')
+        SQL
+      end
+
+      def acquire_drain_slots_sql(targets)
+        <<~SQL
+          WITH target(target_key, queue_name, parallelism) AS (
+            VALUES #{drain_slot_target_values_sql(targets)}
+          ),
+          available AS (
+            SELECT slots.id
+            FROM #{quoted_drain_slot_table} slots
+            INNER JOIN target
+              ON target.target_key = slots.target_key
+            WHERE slots.status = 'idle'
+              AND slots.slot <= target.parallelism
+            ORDER BY slots.target_key ASC, slots.slot ASC
+            FOR UPDATE SKIP LOCKED
+          ),
+          updated AS (
+            UPDATE #{quoted_drain_slot_table} slots
+            SET status = 'queued',
+                locked_at = CURRENT_TIMESTAMP,
+                locked_by = NULL,
+                enqueued_at = CURRENT_TIMESTAMP,
+                last_error = NULL,
+                updated_at = CURRENT_TIMESTAMP
+            FROM available
+            WHERE slots.id = available.id
+            RETURNING slots.target_key, slots.slot, slots.queue_name
+          )
+          SELECT target_key, slot, queue_name
+          FROM updated
+          ORDER BY target_key ASC, slot ASC
+        SQL
+      end
+
+      def drain_slot_target_values_sql(targets)
+        targets.map do |target|
+          "(#{quote(target.key)}, #{quote(target.queue_name)}, #{target.parallelism})"
+        end.join(', ')
+      end
+
+      def drain_slot_descriptor(row)
+        {
+          target_key: row_value(row, :target_key).to_s,
+          slot: row_value(row, :slot).to_i,
+          queue_name: row_value(row, :queue_name).to_s
+        }
+      end
+
+      def drain_slot_owner_guard_sql(worker_id)
+        return '' if worker_id.nil?
+
+        "AND locked_by = #{quote(worker_id)}"
+      end
+
       def quoted_table
         connection.quote_table_name(SearchEngine.config.postgres_outbox.table_name)
       end
@@ -579,6 +765,14 @@ module SearchEngine
         connection.quote_table_name(SearchEngine.config.postgres_outbox.delivery_table_name)
       end
 
+      def quoted_drain_slot_table
+        connection.quote_table_name(drain_slot_table_name)
+      end
+
+      def drain_slot_table_name
+        SearchEngine.config.postgres_outbox.drain_slot_table_name
+      end
+
       def quote(value)
         connection.quote(value)
       end

data/lib/search_engine/version.rb

@@ -3,5 +3,5 @@
 module SearchEngine
   # Current gem version.
   # @return [String]
-  VERSION = '30.1.8.13'
+  VERSION = '30.1.8.14'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: search-engine-for-typesense
 version: !ruby/object:Gem::Version
-  version: 30.1.8.13
+  version: 30.1.8.14
 platform: ruby
 authors:
 - Nikita Shkoda