riverqueue 0.12.0 → 0.14.0

data/lib/config.rb

@@ -40,22 +40,52 @@ module River
     end
   end
 
+  # Lazily generates a client ID once per process. The process ID check
+  # regenerates it in forked children without needing a fork hook.
+  class DefaultClientID # :nodoc:
+    HOSTNAME_MAX_LENGTH = 80
+
+    def initialize
+      @mutex = Mutex.new
+      @state = nil
+    end
+
+    def value
+      pid = Process.pid
+      @state&.[](pid) || @mutex.synchronize { @state&.[](pid) || generate(pid) }
+    end
+
+    # The PID and ID are swapped in as one frozen hash so a lock-free reader
+    # never pairs one process's PID with another's ID.
+    private def generate(pid)
+      id = "#{Socket.gethostname[0, HOSTNAME_MAX_LENGTH]}-#{pid}-#{SecureRandom.hex(6)}".freeze
+      @state = {pid => id}.freeze
+      id
+    end
+  end
+  private_constant :DefaultClientID
+
   # Complete configuration for a River client and its worker runtime.
   class Config
     # Configured values used by Client and its runtime.
     attr_reader :cancelled_job_retention_period, :completed_job_retention_period,
       :discarded_job_retention_period, :error_handler, :fetch_cooldown,
-      :fetch_only_known_kinds, :fetch_poll_interval, :id, :job_timeout,
+      :fetch_only_known_kinds, :fetch_poll_interval, :job_timeout,
       :leader_election_disabled, :logger, :maintenance_services,
-      :periodic_jobs, :plugins, :queues, :retry_policy, :workers
+      :periodic_jobs, :plugins, :poll_only, :queues, :retry_policy, :workers
 
     # Creates a client configuration.
     #
     # Configure queues and workers here to enable job processing; a client with
     # neither may still be used for insertion and administrative operations.
-    # +fetch_only_known_kinds+ leaves unregistered kinds untouched in shared
-    # queues. +leader_election_disabled+ prevents this client's maintenance;
-    # another eligible client must run scheduling, rescue, and cleanup.
+    # An explicit +id+ is used exactly as given and must be unique among all
+    # running clients. Without one, each process using this config generates
+    # its own ID; see #id. +fetch_only_known_kinds+ leaves unregistered kinds
+    # untouched in shared queues. +leader_election_disabled+ prevents this
+    # client's maintenance; another eligible client must run scheduling,
+    # rescue, and cleanup.
+    # +poll_only+ disables notification receiving, including leadership
+    # resignation requests. Job and queue state are still polled.
     def initialize(
       queues: {},
       workers: Workers.new,
@@ -70,6 +100,7 @@ module River
       plugins: [],
       maintenance_services: [],
       periodic_jobs: [],
+      poll_only: false,
       cancelled_job_retention_period: 86_400,
       completed_job_retention_period: 86_400,
       discarded_job_retention_period: 604_800,
@@ -82,13 +113,15 @@ module River
       @fetch_cooldown = Float(fetch_cooldown)
       @fetch_only_known_kinds = fetch_only_known_kinds
       @fetch_poll_interval = Float(fetch_poll_interval)
-      @id = id || "#{Socket.gethostname}-#{Process.pid}-#{SecureRandom.hex(6)}"
+      @default_id = DefaultClientID.new
+      @id = id
       @job_timeout = job_timeout.nil? ? nil : Float(job_timeout)
       @leader_election_disabled = leader_election_disabled
       @logger = logger || Logger.new($stdout, level: Logger::WARN)
       @maintenance_services = maintenance_services.dup.freeze
       @periodic_jobs = periodic_jobs.dup.freeze
       @plugins = plugins.dup.freeze
+      @poll_only = poll_only
       @queues = normalize_queues(queues).freeze
       @retry_policy = retry_policy
       @workers = workers
@@ -96,10 +129,22 @@ module River
       validate
     end
 
+    # Returns the client ID recorded in +attempted_by+ and used for leadership.
+    #
+    # An explicitly configured ID is returned unchanged. Otherwise, the ID is
+    # generated on first use in each process and stays stable for the life of
+    # that process, so clients built from a config before a fork (for example,
+    # by a preloading Puma, Unicorn, or Pitchfork server) get distinct IDs in
+    # each forked child instead of sharing the parent's.
+    def id
+      @id || @default_id.value
+    end
+
     # Returns a new Config with the supplied values replacing this config's
-    # corresponding settings.
+    # corresponding settings. Without an +id+ override, the copy shares this
+    # config's ID, including its per-process generated default.
     def with(**overrides)
-      Config.new(id: id,
+      copy = Config.new(id: @id,
         cancelled_job_retention_period: cancelled_job_retention_period,
         completed_job_retention_period: completed_job_retention_period,
         discarded_job_retention_period: discarded_job_retention_period,
@@ -113,9 +158,16 @@ module River
         maintenance_services: maintenance_services,
         periodic_jobs: periodic_jobs,
         plugins: plugins,
+        poll_only: poll_only,
         queues: queues,
         retry_policy: retry_policy,
         workers: workers, **overrides)
+      copy.adopt_default_id(@default_id) unless overrides.key?(:id)
+      copy
+    end
+
+    protected def adopt_default_id(default_id)
+      @default_id = default_id
     end
 
     private def normalize_queues(queues)
@@ -136,7 +188,7 @@ module River
 
     private def validate
       raise ArgumentError, "fetch intervals and job_timeout must be finite" unless [fetch_cooldown, fetch_poll_interval, job_timeout].compact.all?(&:finite?)
-      raise ArgumentError, "id must be between 1 and 127 characters" unless (1...128).cover?(id.length)
+      raise ArgumentError, "id must be between 1 and 127 characters" if (explicit_id = @id) && !(1...128).cover?(explicit_id.length)
       raise ArgumentError, "fetch_cooldown must be at least 0.001 seconds" if fetch_cooldown < 0.001
       raise ArgumentError, "fetch_poll_interval cannot be less than fetch_cooldown" if fetch_poll_interval < fetch_cooldown
       raise ArgumentError, "job_timeout must be greater than zero or nil" if job_timeout && job_timeout <= 0

data/lib/driver/job_row_decoder.rb

@@ -23,7 +23,7 @@ module River::Driver
     def self.error_time(value)
       return ZERO_TIME unless value.is_a?(String)
 
-      # Keep Ruby's existing acceptance of PostgreSQL-style timestamps too.
+      # Keep Ruby's existing acceptance of Postgres-style timestamps too.
       Time.parse(value).utc
     rescue ArgumentError
       ZERO_TIME
@@ -63,7 +63,7 @@ module River::Driver
     end
 
     def decoded(field, value, type: nil, strings: false, default: nil)
-      # Sequel's PostgreSQL JSON and array wrappers delegate to Ruby values.
+      # Sequel's Postgres JSON and array wrappers delegate to Ruby values.
       value = value.__getobj__ if value.respond_to?(:__getobj__)
       return default if value.nil?
 

data/lib/driver/notification_listener.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module River::Driver
+  # Internal notification transports. Each client owns its listener; SQLite
+  # cursors never consume or delete another client's notifications.
+  module NotificationListener
+    TOPICS = %w[river_control river_insert river_leadership].freeze
+
+    class Postgres
+      def initialize(connection, schema)
+        @connection = connection
+        @channels = TOPICS.to_h { |topic| ["#{schema}.#{topic}", topic] }
+        @channels.each_key { |channel| @connection.exec("LISTEN #{@connection.escape_identifier(channel)}") }
+      rescue
+        close
+        raise
+      end
+
+      def close
+        @connection.close unless @connection.finished?
+      end
+
+      def poll(timeout)
+        notifications = [] #: Array[untyped]
+        @connection.wait_for_notify(timeout) do |channel, _pid, payload|
+          notifications << [@channels[channel], payload]
+        end
+        # Bound each batch so a busy sender cannot prevent shutdown.
+        while notifications.length < 1_000 && (notification = @connection.notifies)
+          notifications << [@channels[notification[:relname]], notification[:extra]]
+        end
+        notifications
+      end
+    end
+
+    class SQLite
+      def initialize(query)
+        @query = query
+        # Historical requests must not resign a newly started client.
+        @last_id = @query.call("SELECT coalesce(max(id), 0) AS id FROM river_notification").first.transform_keys(&:to_sym).fetch(:id).to_i
+      end
+
+      def close
+      end
+
+      def poll(timeout)
+        rows = @query.call("SELECT id, topic, payload FROM river_notification WHERE id > #{@last_id} ORDER BY id LIMIT 1000")
+        if rows.empty?
+          sleep(timeout)
+          return []
+        end
+
+        rows.map do |row|
+          row = row.transform_keys(&:to_sym)
+          @last_id = row.fetch(:id).to_i
+          [row.fetch(:topic), row.fetch(:payload)]
+        end
+      end
+    end
+  end
+end

data/lib/driver/postgres_capabilities.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module River::Driver
-  # PostgreSQL-compatible servers differ in conflict detection and notification
+  # Postgres-compatible servers differ in conflict detection and notification
   # support. Keep these rules aligned with Go's PostgresCapabilities.
   class PostgresCapabilities
     attr_reader :supports_listen_notify, :unique_insert_mode, :unique_insert_sql