riverqueue 0.11.0 → 0.12.0

data/lib/riverqueue/testing/rspec.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+require "riverqueue/testing"
+
+module River
+  module Testing
+    # Include through RSpec.configure { |c| c.include River::Testing::RSpec }.
+    module RSpec
+      # Matches a client with at least one persisted job matching the attributes.
+      # Includes all job states unless state: is specified.
+      def have_job(**attributes)
+        JobMatcher.new(1, attributes).at_least(1)
+      end
+
+      # Matches a block inserting exactly one matching persisted job.
+      def insert_job(client, **attributes)
+        insert_jobs(client, **attributes)
+      end
+
+      # Matches a block inserting count matching rows (one by default).
+      # Attributes accept composable RSpec matchers. Negation always requires zero
+      # matching rows, regardless of the configured positive count.
+      def insert_jobs(client, count: 1, **attributes)
+        InsertionMatcher.new(client, count, attributes)
+      end
+
+      class JobMatcher
+        include ::RSpec::Matchers::Composable
+
+        def initialize(count, attributes)
+          @attributes = Testing.normalize_attributes(attributes)
+          exactly(count)
+        end
+
+        # Requires at least count matching jobs.
+        def at_least(count)
+          set_count(count, :>=, "at least")
+        end
+
+        # Requires at most count matching jobs.
+        def at_most(count)
+          set_count(count, :<=, "at most")
+        end
+
+        def description = "#{verb} #{@count_description} #{@count} River jobs matching #{surface_descriptions_in(@attributes).inspect}"
+
+        def does_not_match?(actual)
+          matching_rows(actual).empty?
+        end
+
+        # Requires exactly count matching jobs.
+        def exactly(count)
+          set_count(count, :==, "exactly")
+        end
+
+        def failure_message = "Expected to #{description}, got #{@rows.length}: #{@rows.map(&:id).inspect}"
+
+        def failure_message_when_negated = "Expected no matching River jobs for #{surface_descriptions_in(@attributes).inspect}, got #{@rows.length}: #{@rows.map(&:id).inspect}"
+
+        def matches?(actual)
+          matching_rows(actual).length.public_send(@comparison, @count)
+        end
+
+        def supports_block_expectations? = false
+
+        def supports_value_expectations? = true
+
+        private def candidates(actual)
+          Testing.jobs(actual)
+        end
+
+        private def matching_rows(actual)
+          @rows = candidates(actual).select do |row|
+            @attributes.all? { |key, expected| values_match?(expected, row.public_send(key)) }
+          end
+        end
+
+        private def set_count(count, comparison, description)
+          raise ArgumentError, "count must be a nonnegative integer" unless count.is_a?(Integer) && count >= 0
+
+          @comparison = comparison
+          @count = count
+          @count_description = description
+          self
+        end
+
+        private def verb = "have"
+      end
+
+      class InsertionMatcher < JobMatcher
+        def initialize(client, count, attributes)
+          @client = client
+          super(count, attributes)
+        end
+
+        def supports_block_expectations? = true
+
+        def supports_value_expectations? = false
+
+        private def candidates(operation)
+          Testing.inserted_jobs(@client, &operation)
+        end
+
+        private def verb = "insert"
+      end
+    end
+  end
+end

data/lib/riverqueue/testing.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "riverqueue"
+
+module River
+  # Database-backed test helpers. Require explicitly; no test framework is loaded.
+  module Testing
+    class AssertionError < StandardError; end
+    class DrainLimitError < StandardError; end
+
+    JOB_ATTRIBUTES = %i[id args attempt attempted_at attempted_by created_at errors finalized_at kind max_attempts metadata priority queue scheduled_at state tags unique_key unique_states].freeze
+
+    ExecutionResult = Data.define(:id, :error, :job, :outcome)
+
+    # Framework-neutral assertions, also used by the optional integrations.
+    module Assertions
+      # Asserts that a synchronous attempt was cancelled and returns its result.
+      def assert_job_cancelled(result)
+        river_assert(result.outcome == :cancelled, "Expected cancelled River job, got #{result.outcome}: #{result.error.inspect}")
+        result
+      end
+
+      # Asserts that a synchronous attempt completed and returns its result.
+      def assert_job_completed(result)
+        river_assert(result.outcome == :completed, "Expected completed River job, got #{result.outcome}: #{result.error.inspect}")
+        result
+      end
+
+      # Asserts that a synchronous attempt exhausted retries and returns its result.
+      def assert_job_discarded(result)
+        river_assert(result.outcome == :discarded, "Expected discarded River job, got #{result.outcome}: #{result.error.inspect}")
+        result
+      end
+
+      # Asserts that exactly one matching new row was inserted by the block and
+      # returns it. Attributes (including args) use exact equality.
+      def assert_job_inserted(client, **attributes, &block)
+        assert_jobs_inserted(client, count: 1, **attributes, &block).fetch(0)
+      end
+
+      # Asserts the number of matching new rows, returning those rows. Existing
+      # rows returned by uniqueness checks do not count as insertions.
+      def assert_jobs_inserted(client, count:, **attributes, &block)
+        raise ArgumentError, "count must be a nonnegative integer" unless count.is_a?(Integer) && count >= 0
+
+        rows = Testing.inserted_jobs(client, **attributes, &block)
+        message = "Expected #{count} new River jobs matching #{attributes.inspect}, got #{rows.length}: #{rows.map(&:id).inspect}"
+        river_assert(rows.length == count, message)
+        rows
+      end
+
+      # Asserts that the block inserted no matching rows.
+      def assert_no_jobs_inserted(client, **attributes, &block)
+        assert_jobs_inserted(client, count: 0, **attributes, &block)
+      end
+
+      private def river_assert(condition, message)
+        raise AssertionError, message unless condition
+      end
+    end
+
+    class << self
+      # Runs eligible jobs in priority order, including jobs inserted by workers.
+      # Never sleeps or starts maintenance. Raises if runnable work remains after
+      # max_jobs attempts. Use an isolated database with no background consumers.
+      def drain(client, queue:, max_jobs: 100)
+        raise ArgumentError, "max_jobs must be a positive integer" unless max_jobs.is_a?(Integer) && max_jobs.positive?
+        queue = queue.to_s
+        # @type var results: Array[ExecutionResult]
+        results = []
+        loop do
+          now = Time.now.utc
+          row = jobs(client).select { |job| job.queue == queue && %w[available retryable scheduled].include?(job.state) && job.scheduled_at <= now }
+            .min_by { |job| [job.priority, job.scheduled_at, job.id] }
+
+          return results unless row
+          raise DrainLimitError, "River drain reached #{max_jobs} attempts with runnable jobs remaining in #{queue.inspect}" if results.length == max_jobs
+
+          results << perform_job(client, row.id)
+        end
+      end
+
+      # Returns matching rows newly persisted by a block, using an ID snapshot
+      # rather than a count or sequence high-water mark. Rolls back no data.
+      def inserted_jobs(client, **attributes)
+        raise ArgumentError, "a block is required" unless block_given?
+
+        attributes = normalize_attributes(attributes)
+
+        before = jobs(client).to_h { |job| [job.id, true] }
+        yield
+        jobs(client).select do |job|
+          !before.key?(job.id) && attributes.all? { |key, value| job.public_send(key) == value }
+        end
+      end
+
+      # Returns all persisted jobs, in every state, using paginated reads.
+      # Requires an isolated test database without concurrent consumers.
+      def jobs(client)
+        # @type var result: Array[JobRow]
+        result = []
+        # @type var cursor: Integer?
+        cursor = nil
+        loop do
+          page = client.job_list(JobListParams.new(after_id: cursor, limit: 100)).jobs
+          result.concat(page)
+          return result if page.length < 100
+
+          cursor = page.fetch(-1).id
+        end
+      end
+
+      # Internal shared normalization for assertions and RSpec matchers. Only
+      # symbolic identifiers are coerced; JSON values and matchers stay intact.
+      def normalize_attributes(attributes)
+        unknown = attributes.keys - JOB_ATTRIBUTES
+        raise ArgumentError, "unknown job attributes: #{unknown.join(", ")}" unless unknown.empty?
+
+        attributes.to_h do |key, value|
+          [key, (value.is_a?(Symbol) && %i[kind queue state].include?(key)) ? value.to_s : value]
+        end
+      end
+
+      # Performs one attempt on the calling thread using the actual runtime,
+      # returning the persisted row, original exception, and symbolic outcome.
+      # Future jobs require allow_scheduled: true; terminal/running/pending jobs
+      # cannot be claimed. This intentionally bypasses queue pause and capacity.
+      def perform_job(client, id, allow_scheduled: false)
+        job, error, outcome = client.__perform_job(id, allow_scheduled: allow_scheduled)
+        ExecutionResult.new(id: id, error: error, job: job, outcome: outcome)
+      end
+    end
+  end
+end

data/lib/riverqueue.rb

@@ -1,11 +1,27 @@
+# frozen_string_literal: true
+
 require "json"
+require "securerandom"
 
+require_relative "errors"
 require_relative "insert_opts"
 require_relative "job"
+require_relative "worker"
+require_relative "job_persisted_logging/plugin"
+require_relative "resumable"
+require_relative "config"
+require_relative "event"
+require_relative "params"
+require_relative "periodic_cron"
+require_relative "periodic_job"
+require_relative "client_runtime"
 
 require_relative "client"
+require_relative "worker_runner"
 require_relative "driver"
 require_relative "unique_bitmask"
+require_relative "unique_args"
+require_relative "migrator"
 
 module River
 end

data/lib/unique_args.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module River
+  # Internal codec for the argument portion of Go-compatible unique keys.
+  # Only top-level keys are sorted. Decoding and re-encoding values would lose
+  # number lexemes, escaping, duplicate keys, and nested object ordering.
+  module UniqueArgs
+    def self.encode(json, fields)
+      value = JSON.parse(json)
+      if !fields.is_a?(Array) || fields.empty?
+        return "{}" if value.is_a?(Array) && value.empty?
+        raise ArgumentError, "unique args must encode a JSON object" unless value.is_a?(Hash)
+
+        return encode_object(members(json).sort.to_h)
+      end
+
+      paths = fields.map do |field|
+        path = Array(field).map(&:to_s)
+        raise ArgumentError, "unique argument paths must not be empty" if path.empty?
+
+        path
+      end
+      selected = {} #: Hash[String, untyped]
+      paths.sort_by { |path| [path.join("."), path.map { |part| part.gsub(/([\\.])/) { |char| "\\" + char } }.join(".")] }.each do |path|
+        raw = json
+        path.each do |part|
+          raw = members(raw)[part]
+          break unless raw
+        end
+        next unless raw
+
+        target = selected
+        covered = false
+        path.take(path.length - 1).each do |part|
+          if target[part].is_a?(String)
+            covered = true
+            break # Selecting a whole object already includes its children.
+          end
+          target = (target[part] ||= {})
+        end
+        target[path.last] = raw unless covered
+      end
+      # Go's selected-field builder starts with nil bytes, not an empty object.
+      selected.empty? ? "" : encode_object(selected)
+    end
+
+    # The caller validates JSON first. Values remain slices of the original
+    # string; this is a token walk, not a second JSON decoder. Go takes the first
+    # occurrence of a duplicate top-level key.
+    def self.members(json)
+      return {} unless json.lstrip.start_with?("{")
+
+      result = {} #: Hash[String, String]
+      depth = 0
+      key = ""
+      start = nil #: Integer?
+      expecting_value = false
+      # Anchoring prevents repeated searches through an unterminated string.
+      # \K keeps leading whitespace out of the offsets used to slice raw values.
+      json.scan(/\G\s*\K(?:"(?:[^"\\]|\\.)*"|[{}\[\],:]|[^\s{}\[\],:"]+)/) do |scanned|
+        token = scanned #: String
+        match = Regexp.last_match #: MatchData
+        if depth == 1
+          if start && [",", "}"].include?(token)
+            raw = json[start...match.begin(0)] #: String
+            result[key] ||= raw.rstrip
+            start = nil
+          elsif expecting_value
+            start = match.begin(0)
+            expecting_value = false
+          elsif token == ":"
+            expecting_value = true
+          elsif token.start_with?('"') && !start
+            key = JSON.parse(token)
+          end
+        end
+        depth += 1 if token == "{" || token == "["
+        depth -= 1 if token == "}" || token == "]"
+      end
+      result
+    end
+
+    def self.encode_object(object)
+      "{" + object.map { |key, value| "#{encode_key(key)}:#{value.is_a?(Hash) ? encode_object(value) : value}" }.join(",") + "}"
+    end
+
+    # Match sjson's fast path for printable ASCII keys and encoding/json's
+    # HTML escaping for all other keys. Values are never passed through here.
+    def self.encode_key(key)
+      return '"' + key + '"' unless key.match?(/[\x00-\x1f\u0080-\u{10ffff}"\\]/)
+
+      JSON.generate(key).gsub(/[<>&\u2028\u2029]/) { |char| "\\u%04x" % char.ord }
+    end
+
+    private_class_method :encode_object, :encode_key
+  end
+end

data/lib/unique_bitmask.rb

@@ -1,17 +1,7 @@
+# frozen_string_literal: true
+
 module River
   class UniqueBitmask
-    JOB_STATE_BIT_POSITIONS = {
-      ::River::JOB_STATE_AVAILABLE => 7,
-      ::River::JOB_STATE_CANCELLED => 6,
-      ::River::JOB_STATE_COMPLETED => 5,
-      ::River::JOB_STATE_DISCARDED => 4,
-      ::River::JOB_STATE_PENDING => 3,
-      ::River::JOB_STATE_RETRYABLE => 2,
-      ::River::JOB_STATE_RUNNING => 1,
-      ::River::JOB_STATE_SCHEDULED => 0
-    }.freeze
-    private_constant :JOB_STATE_BIT_POSITIONS
-
     def self.from_states(states)
       val = 0
 
@@ -37,5 +27,17 @@ module River
 
       states.sort
     end
+
+    JOB_STATE_BIT_POSITIONS = {
+      ::River::JOB_STATE_AVAILABLE => 7,
+      ::River::JOB_STATE_CANCELLED => 6,
+      ::River::JOB_STATE_COMPLETED => 5,
+      ::River::JOB_STATE_DISCARDED => 4,
+      ::River::JOB_STATE_PENDING => 3,
+      ::River::JOB_STATE_RETRYABLE => 2,
+      ::River::JOB_STATE_RUNNING => 1,
+      ::River::JOB_STATE_SCHEDULED => 0
+    }.freeze
+    private_constant :JOB_STATE_BIT_POSITIONS
   end
 end

data/lib/worker.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module River
+  # Registry that maps job kinds to worker objects.
+  class Workers
+    # Creates an empty worker registry.
+    def initialize
+      @workers = {}
+    end
+
+    # Registers a worker for a job kind and optional aliases, returning self.
+    #
+    # With one argument, the kind is read from +worker.kind+ or
+    # +worker.class.kind+. Pass a kind and worker separately to override it.
+    # Kinds and aliases accept symbols or strings.
+    def add(kind_or_worker, worker = nil, aliases: [])
+      if worker
+        kind = kind_or_worker.to_s
+      else
+        worker = kind_or_worker
+        kind = worker.respond_to?(:kind) ? worker.kind.to_s : worker.class.kind.to_s
+      end
+
+      candidates = [kind] + aliases.map(&:to_s)
+      candidates.each do |candidate|
+        raise ArgumentError, "worker for kind #{candidate.inspect} is already registered" if @workers.key?(candidate)
+      end
+
+      candidates.each do |candidate|
+        @workers[candidate] = worker
+      end
+
+      self
+    end
+
+    # Returns the worker registered for +kind+, or nil when none is registered.
+    def [](kind)
+      @workers[kind.to_s]
+    end
+
+    # Returns a registered worker. Like Hash#fetch, raises KeyError when missing
+    # unless a default argument or fallback block is supplied.
+    def fetch(kind, ...)
+      workers = @workers #: untyped
+      workers.fetch(kind.to_s, ...)
+    end
+
+    # Returns true if a worker is registered for +kind+.
+    def include?(kind)
+      @workers.key?(kind.to_s)
+    end
+
+    # Returns the registered job kinds, including aliases.
+    def kinds
+      @workers.keys.freeze
+    end
+  end
+
+  # A job being worked, with access to its persisted row and attempt-local
+  # metadata changes.
+  class Job
+    # Client working this job.
+    attr_reader :client
+
+    # Persisted JobRow claimed for this attempt.
+    attr_reader :row
+
+    def initialize(client, row)
+      @client = client
+      @logger = nil
+      @metadata_updates = {}
+      @row = row
+      initialize_resumable_state
+    end
+
+    # Returns the job arguments decoded from their persisted JSON.
+    def args = row.args
+
+    # Returns the attempt-local logger supplied by JobPersistedLogging::Plugin.
+    # Output is saved to job metadata when the attempt finishes, not streamed to the DB.
+    def logger
+      @logger || raise(Error, "job.logger requires River::JobPersistedLogging::Plugin in Config#plugins")
+    end
+
+    # Internal middleware boundary; never replaces the client's process logger.
+    def __with_logger(logger)
+      previous = @logger
+      @logger = logger
+      begin
+        yield
+      ensure
+        @logger = previous
+      end
+    end
+
+    # Returns a snapshot of persisted metadata merged with this attempt's changes.
+    def metadata = JSON.parse(JSON.generate(row.metadata.merge(@metadata_updates)))
+
+    # Returns a copy of metadata changes waiting to be persisted when work
+    # finishes.
+    def metadata_updates
+      JSON.parse(JSON.generate(@metadata_updates))
+    end
+
+    def method_missing(name, ...)
+      return row.public_send(name, ...) if row.respond_to?(name)
+
+      super
+    end
+
+    # Stores a worker result under the conventional +"output"+ metadata key.
+    def output=(value)
+      update_metadata("output" => value)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      row.respond_to?(name, include_private) || super
+    end
+
+    # Merges JSON-compatible values into the job metadata to be persisted when
+    # work finishes. Values are validated and copied immediately, so invalid JSON
+    # fails the work without also preventing its failure from being recorded.
+    # Keys are converted to strings. Returns self.
+    def update_metadata(values)
+      @metadata_updates.merge!(JSON.parse(JSON.generate(values.transform_keys(&:to_s))))
+      self
+    end
+  end
+
+  # Default retry schedule used when a worker does not provide its own policy.
+  class DefaultClientRetryPolicy
+    # Match Go's maximum signed 64-bit nanosecond duration exactly.
+    MAX_DELAY = Rational((1 << 63) - 1, 1_000_000_000)
+    private_constant :MAX_DELAY
+
+    # Creates River's default quartic-backoff retry policy. A Random source may
+    # be injected to make jitter deterministic.
+    def initialize(random: Random)
+      @random = random
+    end
+
+    # Returns the Time at which +job+ should next be attempted.
+    def next_retry(job, _error = nil, now: Time.now.utc)
+      error_count = Array(job.errors).length + 1
+      seconds = Integer(error_count**4)
+      return now + MAX_DELAY if seconds >= MAX_DELAY
+
+      delay = seconds + (seconds * (@random.rand * 0.2 - 0.1))
+      now + [delay, MAX_DELAY].min
+    end
+  end
+end

data/lib/worker_runner.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "io/wait"
+
+module River
+  # Owns a dedicated worker process. Call run on its main thread, after boot.
+  # A supervisor should restart failed processes. An unresponsive stop ends
+  # the process with exit!(1), bypassing application at_exit handlers.
+  class WorkerRunner
+    # Grace and finalization deadlines are finite, nonnegative seconds.
+    def initialize(client, finalization_timeout: 5, out: $stdout, stop_timeout: 30)
+      @client = client
+      @finalization_timeout = Float(finalization_timeout, exception: true) #: Float
+      @out = out
+      @stop_timeout = Float(stop_timeout, exception: true) #: Float
+      [@finalization_timeout, @stop_timeout].each do |value|
+        raise ArgumentError, "stop deadlines must be finite and nonnegative" unless value.finite? && value >= 0
+      end
+    end
+
+    # Starts the client and blocks until stopped. Returns 0 for a clean drain,
+    # 1 for a runtime failure or interrupted stop. Restores signal handlers.
+    def run
+      raise ArgumentError, "worker runner must run on the main thread of the main Ractor" unless Thread.current == Thread.main && Ractor.current == Ractor.main
+      raise ArgumentError, "worker runner requires a stopped client" if @client.started?
+      raise ArgumentError, "configure at least one worker queue" if @client.config.queues.empty?
+
+      reader, writer = IO.pipe
+      handlers = {} #: Hash[String, untyped]
+      %w[INT TERM TSTP].each do |signal|
+        handlers[signal] = Signal.trap(signal) { writer.write_nonblock((signal == "TSTP") ? "Q" : "S", exception: false) }
+      end
+
+      begin
+        log("starting")
+        @client.job_list(JobListParams.new(limit: 1))
+        @client.start
+        log("ready pid=#{Process.pid}")
+
+        supervise(reader)
+      ensure
+        handlers.each { |signal, handler| Signal.trap(signal, handler) }
+        reader.close
+        writer.close
+      end
+    end
+
+    private def log(message)
+      @out.puts("River worker: #{message}")
+      @out.flush
+    end
+
+    private def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    private def supervise(reader)
+      deadline = 0.0
+      failed = false
+      interrupted = false
+      stopper = nil #: Thread?
+      loop do
+        signals = reader.wait_readable(0.1) ? reader.read_nonblock(4_096) : ""
+        if signals.include?("Q")
+          @client.stop(wait: false)
+          log("stop requested; no new work will be fetched")
+        end
+
+        unless @client.__runtime_healthy?
+          log("runtime thread exited unexpectedly")
+          failed = true
+        end
+
+        if !stopper && (signals.include?("S") || failed)
+          @client.stop(wait: false)
+          log("draining active attempts")
+          deadline = monotonic_now + @stop_timeout
+          stopper = Thread.new { @client.stop }
+          stopper.report_on_exception = false
+          # Consume only the first stop request; a second escalates immediately.
+          signals = signals.sub("S", "")
+        end
+
+        next unless stopper
+
+        if stopper.join(0)
+          stopper.value
+          log("stopped")
+          return (failed || interrupted) ? 1 : 0
+        end
+
+        next unless signals.include?("S") || monotonic_now >= deadline
+
+        if interrupted
+          log("finalization deadline exceeded; forcing process exit")
+          Process.exit!(1)
+        end
+
+        interrupted = true
+        log("interrupting active attempts")
+        @client.__interrupt_workers
+        deadline = monotonic_now + @finalization_timeout
+      end
+    end
+  end
+end