riverqueue 0.12.0 → 0.14.0

data/lib/client.rb

@@ -7,6 +7,9 @@ module River
   # Default number of maximum attempts for a job.
   MAX_ATTEMPTS_DEFAULT = 25
 
+  # Largest attempt limit supported by all River databases.
+  MAX_ATTEMPTS_LIMIT = 32_767
+
   # Default priority for a job.
   PRIORITY_DEFAULT = 1
 
@@ -40,10 +43,19 @@ module River
 
     # Internal extension point used by separately packaged batch workers after
     # they atomically claim additional jobs alongside the batch leader.
+    # Errors honor the registered worker's retry hooks and River's cancellation,
+    # snooze, and interruption signals. Timings use the row's claim timestamp.
     def __finish_claimed_job(row, error = nil)
       @runtime.finish_claimed(row, error)
     end
 
+    # Internal scheduler entry point. Prepare ordinary insertion options and
+    # uniqueness before applying an occurrence fallback to the stored schedule.
+    def __insert_with_default_scheduled_at(args, insert_opts, default_scheduled_at)
+      insert_params = make_insert_params(args, insert_opts, default_scheduled_at)
+      run_insert_plugins([insert_params]) { [insert_and_check_unique_job(insert_params)] }.first
+    end
+
     def __perform_job(id, allow_scheduled: false)
       @runtime.perform_job(id, allow_scheduled: allow_scheduled)
     end
@@ -72,7 +84,8 @@ module River
     #
     #   * `#kind`: A symbol or string identifying the job kind in the database.
     #   * `#to_json`: Encodes the args to JSON for persistence in the database.
-    #     Must match encoding an args struct on the Go side to be workable.
+    #     Must match the JSON expected by whichever River client works the
+    #     job.
     #
     # They may also respond to `#insert_opts` which is expected to return an
     # `InsertOpts` that contains options that will apply to all jobs of this
@@ -101,8 +114,7 @@ module River
     def insert(args, insert_opts: nil, **options)
       raise ArgumentError, "use insert_opts or keyword options, not both" if insert_opts && !options.empty?
       insert_opts ||= options.empty? ? EMPTY_INSERT_OPTS : InsertOpts.new(**options)
-      insert_params = make_insert_params(args, insert_opts)
-      run_insert_plugins([insert_params]) { [insert_and_check_unique_job(insert_params)] }.first
+      __insert_with_default_scheduled_at(args, insert_opts, nil)
     end
 
     # Inserts many new jobs as part of a single batch operation for improved
@@ -129,7 +141,8 @@ module River
     #
     #   * `#kind`: A symbol or string identifying the job kind in the database.
     #   * `#to_json`: Encodes the args to JSON for persistence in the database.
-    #     Must match encoding an args struct on the Go side to be workable.
+    #     Must match the JSON expected by whichever River client works the
+    #     job.
     #
     # For example:
     #
@@ -177,6 +190,44 @@ module River
       @driver.job_cancel(id) || raise(NotFoundError, "job not found: #{id}")
     end
 
+    # Completes a running Job and returns its updated JobRow, including pending
+    # metadata and output. The original JobRow is not modified.
+    #
+    # Requires and joins the caller's transaction on the same Active Record
+    # connection or Sequel database. Commit before returning from work;
+    # propagate rollback errors so the runtime can retry the job. A committed
+    # completion takes precedence over any subsequent worker error.
+    #
+    # Raises NotFoundError for a missing job, JobCancelError for a pending
+    # cancellation, and Error if there is no active transaction or the job is
+    # no longer running or completed.
+    def job_complete_tx(job)
+      raise ArgumentError, "job must be a River::Job" unless job.is_a?(Job)
+      raise ArgumentError, "job must belong to this client" unless job.client.equal?(self)
+      raise Error, "job must be running" unless job.row.state == JOB_STATE_RUNNING
+      raise Error, "job_complete_tx requires an active transaction on the driver's connection" unless @driver.in_transaction?
+
+      # Mark the attempt before the write: an interrupt can arrive after the
+      # database commits but before the driver returns. The runtime checks the
+      # persisted state because the caller may still roll back this transaction.
+      job.__completion_attempted = true
+      now = @time_now_utc.call
+      completed = @driver.job_complete(id: job.row.id, finalized_at: now, expected_job: job.row, metadata: job.metadata_updates, now: now)
+      raise JobCancelError if completed == :cancelled
+
+      completed ||= job_get(job.row.id)
+      unless completed.attempt == job.row.attempt && completed.attempted_at == job.row.attempted_at
+        raise Error, "job attempt is no longer current"
+      end
+      raise Error, "job must be running" unless completed.state == JOB_STATE_COMPLETED
+
+      # Retention or application code may delete the row before work returns.
+      # Only retain a snapshot after the caller's outer transaction commits;
+      # rolled-back transactions and savepoints must not report completion.
+      @driver.after_commit { job.__completion_snapshot = completed }
+      completed
+    end
+
     # Deletes a job by ID and returns its former JobRow.
     #
     # Raises NotFoundError if the job does not exist and JobRunningError if it
@@ -223,13 +274,18 @@ module River
 
     # Makes a non-running job immediately available for another attempt and
     # returns its updated JobRow. Raises NotFoundError if it does not exist.
+    # Clears any cancellation request from its previous attempt. Raises
+    # ArgumentError if another attempt would exceed MAX_ATTEMPTS_LIMIT.
     def job_retry(id)
       @driver.job_retry(id) || raise(NotFoundError, "job not found: #{id}")
     end
 
     # Applies keyword attributes or a JobUpdateParams to a job and returns its
     # updated JobRow. Explicit nil clears nullable fields; omitted fields are
-    # unchanged. Raises NotFoundError if the job does not exist.
+    # unchanged. Metadata must be a Hash; use an empty Hash to clear it.
+    # attempt must be between 0 and MAX_ATTEMPTS_LIMIT (32,767);
+    # max_attempts must be between 1 and MAX_ATTEMPTS_LIMIT.
+    # Raises NotFoundError if the job does not exist.
     # @type method job_update: (Integer, ?JobUpdateParams?, **untyped) -> JobRow
     def job_update(id, params = nil, **attributes)
       raise ArgumentError, "use params or keyword attributes, not both" if params && !attributes.empty?
@@ -266,9 +322,8 @@ module River
     # Pauses a named queue, or all queues when +name+ is +"*"+.
     def queue_pause(name)
       name = name.to_s
-      @driver.queue_pause(name)
+      queues = @driver.queue_pause(name)
       @runtime.wake
-      queues = (name == "*") ? @driver.queue_list : [@driver.queue_get(name)].compact
       queues.each do |queue|
         @runtime.publish_queue(EVENT_QUEUE_PAUSED, queue)
       end
@@ -278,6 +333,7 @@ module River
 
     # Removes a configured queue, waits for active jobs in it to finish, and
     # returns self.
+    # Raises ThreadError if called from that queue's own worker or producer.
     def queue_remove(name)
       @runtime.queue_remove(name.to_s)
       self
@@ -286,9 +342,8 @@ module River
     # Resumes a named queue, or all queues when +name+ is +"*"+.
     def queue_resume(name)
       name = name.to_s
-      @driver.queue_resume(name)
+      queues = @driver.queue_resume(name)
       @runtime.wake
-      queues = (name == "*") ? @driver.queue_list : [@driver.queue_get(name)].compact
       queues.each do |queue|
         @runtime.publish_queue(EVENT_QUEUE_RESUMED, queue)
       end
@@ -301,7 +356,13 @@ module River
       @driver.queue_update(name.to_s, metadata: metadata) || raise(NotFoundError, "queue not found: #{name}")
     end
 
-    # Starts polling configured queues and working jobs in background threads.
+    # Requests that the current leader resign. Delivery waits for the caller's
+    # Active Record or Sequel transaction to commit, if one is open.
+    def request_resign
+      @driver.request_resign
+    end
+
+    # Starts notification receiving, polling, and working configured queues.
     # Returns self.
     def start
       @runtime.start
@@ -316,12 +377,14 @@ module River
     # waiting; call stop again to finish draining and release resources.
     # In-flight fetches or maintenance operations may finish. Until a waiting
     # stop completes, started? remains true and stopped? remains false.
+    # Raises ThreadError for a waiting call from this client's runtime threads.
     def stop(wait: true)
       @runtime.stop(wait: wait)
       self
     end
 
     # Stops fetching new jobs, interrupts active work, and returns self.
+    # Raises ThreadError if called from this client's own runtime threads.
     def stop_and_cancel
       @runtime.stop(cancel: true)
       self
@@ -350,6 +413,8 @@ module River
 
     EMPTY_INSERT_OPTS = InsertOpts.new.freeze
 
+    INITIAL_STATES = [JOB_STATE_AVAILABLE, JOB_STATE_PENDING, JOB_STATE_SCHEDULED].freeze
+
     REQUIRED_UNIQUE_STATES = [
       JOB_STATE_AVAILABLE,
       JOB_STATE_PENDING,
@@ -359,14 +424,14 @@ module River
 
     TAG_RE = /\A\w[\w-]+\w\z/
 
-    private_constant :DEFAULT_UNIQUE_STATES, :EMPTY_INSERT_OPTS, :REQUIRED_UNIQUE_STATES, :TAG_RE
+    private_constant :DEFAULT_UNIQUE_STATES, :EMPTY_INSERT_OPTS, :INITIAL_STATES, :REQUIRED_UNIQUE_STATES, :TAG_RE
 
     private def insert_and_check_unique_job(insert_params)
       job, unique_skipped_as_duplicate = @driver.job_insert(insert_params)
       JobInsertResult.new(job, unique_skipped_as_duplicated: unique_skipped_as_duplicate)
     end
 
-    private def make_insert_params(args, insert_opts)
+    private def make_insert_params(args, insert_opts, default_scheduled_at = nil)
       raise ArgumentError, "args should respond to `#kind`" if !args.respond_to?(:kind)
 
       # ~all objects in Ruby respond to `#to_json`, so check non-nil instead.
@@ -380,18 +445,25 @@ module River
         EMPTY_INSERT_OPTS
       end
 
+      max_attempts = insert_opts.max_attempts || args_insert_opts.max_attempts || MAX_ATTEMPTS_DEFAULT
+      raise ArgumentError, "max_attempts must be greater than zero" unless max_attempts > 0
+      raise ArgumentError, "max_attempts must not exceed #{MAX_ATTEMPTS_LIMIT}" if max_attempts > MAX_ATTEMPTS_LIMIT
+
+      queue = (insert_opts.queue || args_insert_opts.queue || QUEUE_DEFAULT).to_s
+      raise ArgumentError, "invalid queue name: #{queue.inspect}" unless queue.match?(QUEUE_NAME_REGEX) && queue.length < 128
+
       scheduled_at = insert_opts.scheduled_at || args_insert_opts.scheduled_at
       now = @time_now_utc.call
-      state = (insert_opts.state || args_insert_opts.state || ((scheduled_at && scheduled_at > now) ? JOB_STATE_SCHEDULED : JOB_STATE_AVAILABLE)).to_s #: jobStateAll # rubocop:disable Layout/LeadingCommentSpace
+      state = validate_insert_state(insert_opts.state || args_insert_opts.state || ((scheduled_at && scheduled_at > now) ? JOB_STATE_SCHEDULED : JOB_STATE_AVAILABLE))
 
       insert_params = Driver::JobInsertParams.new(
         args: args,
         encoded_args: args_json,
         kind: args.kind.to_s,
-        max_attempts: insert_opts.max_attempts || args_insert_opts.max_attempts || MAX_ATTEMPTS_DEFAULT,
+        max_attempts: max_attempts,
         metadata: (args_insert_opts.metadata || {}).merge(insert_opts.metadata || {}),
         priority: insert_opts.priority || args_insert_opts.priority || PRIORITY_DEFAULT,
-        queue: (insert_opts.queue || args_insert_opts.queue || QUEUE_DEFAULT).to_s,
+        queue: queue,
         scheduled_at: scheduled_at&.getutc || now,
         state: state,
         tags: validate_tags(insert_opts.tags || args_insert_opts.tags || [])
@@ -404,6 +476,9 @@ module River
         insert_params.unique_states = unique_states
       end
 
+      if scheduled_at.nil? && default_scheduled_at
+        insert_params.scheduled_at = default_scheduled_at.getutc
+      end
       insert_params
     end
 
@@ -423,6 +498,8 @@ module River
       end
 
       if unique_opts.by_period && unique_opts.by_period != 0
+        raise ArgumentError, "by_period should not be less than 1 second" if unique_opts.by_period < 1
+
         lower_period_bound = truncate_time(insert_params.scheduled_at || @time_now_utc.call, unique_opts.by_period).utc
 
         unique_key += "&period=#{lower_period_bound.strftime("%FT%TZ")}"
@@ -456,6 +533,10 @@ module River
           end
         end
 
+        # Hooks may change any job in the batch, including an earlier entry.
+        # Validate the final states only after all insertion hooks have run.
+        all_params.each { |params| params.state = validate_insert_state(params.state) }
+
         results = insert_operation.call
         results.each do |result|
           config.plugins.reverse_each do |plugin|
@@ -496,6 +577,13 @@ module River
       [int].pack("Q").unpack1("q") #: Integer # rubocop:disable Layout/LeadingCommentSpace
     end
 
+    private def validate_insert_state(state)
+      state = state.to_s #: jobStateInitial # rubocop:disable Layout/LeadingCommentSpace
+      raise ArgumentError, "invalid insertion state: #{state.inspect}; must be available, pending, or scheduled" unless INITIAL_STATES.include?(state)
+
+      state
+    end
+
     private def validate_tags(tags)
       tags.each do |tag|
         raise ArgumentError, "tags should be 255 characters or less" if tag.length > 255