riverqueue 0.12.0 → 0.13.0

data/lib/driver/runtime.rb

@@ -65,13 +65,22 @@ module River::Driver
       runtime_claim_jobs(predicate, 1, attempted_by, now).first
     end
 
-    # Drivers may combine the cancellation probe and completion atomically.
+    # The cancellation predicate must be part of the completion update so it is
+    # checked against the row we lock, including concurrent cancellations.
     # :cancelled asks the runtime to apply its normal cancellation/error hooks.
     def job_complete(id:, finalized_at:, metadata: nil, now: Time.now.utc)
       id = Integer(id)
-      return :cancelled if job_get_cancelled_ids([id]).include?(id)
+      assignments = ["state = 'completed'", "finalized_at = #{runtime_time(finalized_at)}"]
+      assignments << "metadata = #{runtime_merge_metadata(metadata)}" unless metadata.nil? || metadata.empty?
+
+      updated_id = runtime_returning_ids(<<~SQL).first
+        UPDATE river_job SET #{assignments.join(", ")}
+        WHERE id = #{id} AND state = 'running' AND NOT (#{runtime_cancel_attempted})
+        RETURNING id
+      SQL
+      return runtime_read_job(updated_id) if updated_id
 
-      job_set_state_if_running(id: id, finalized_at: finalized_at, metadata: metadata, now: now, state: "completed")
+      :cancelled if job_get_cancelled_ids([id]).include?(id)
     end
 
     def job_delete(id)
@@ -104,13 +113,24 @@ module River::Driver
       SQL
     end
 
+    # A finalization hook's deletion must honor the same cancellation marker as
+    # completion. Return :cancelled so the runtime can record the cancellation.
     def job_delete_if_running(id)
-      runtime_returning_ids("DELETE FROM river_job WHERE id = #{Integer(id)} AND state = 'running' RETURNING id").any?
+      id = Integer(id)
+      deleted = runtime_returning_ids(<<~SQL).any?
+        DELETE FROM river_job
+        WHERE id = #{id} AND state = 'running' AND NOT (#{runtime_cancel_attempted})
+        RETURNING id
+      SQL
+      return true if deleted
+      return :cancelled if job_get_cancelled_ids([id]).include?(id)
+
+      false
     end
 
     def job_delete_many(params)
       transaction do
-        jobs = job_list(params).reject { |job| job.state == River::JOB_STATE_RUNNING }
+        jobs = runtime_job_list(params, for_delete: true)
         next [] if jobs.empty?
 
         ids = jobs.map(&:id)
@@ -142,36 +162,7 @@ module River::Driver
       params ||= River::JobListParams.new
       return runtime_job_list_without_params if params == :all
 
-      clauses = [] #: Array[String]
-      clauses << runtime_cursor_clause(params) if params.after
-      clauses << "id #{(params.sort_order == :asc) ? ">" : "<"} #{Integer(params.after_id)}" if params.after_id
-      clauses << runtime_in_clause("id", params.ids.map { |value| Integer(value) }) if params.ids&.any?
-      clauses << runtime_in_clause("kind", params.kinds) if params.kinds&.any?
-      clauses << runtime_in_clause("priority", params.priorities.map { |value| Integer(value) }) if params.priorities&.any?
-      clauses << runtime_in_clause("queue", params.queues) if params.queues&.any?
-      clauses << runtime_in_clause("state", params.states) if params.states&.any?
-
-      finalized = params.sort_by == :finalized_at && params.states&.length == 1 &&
-        %w[cancelled completed discarded].include?(params.states.first)
-      # Schemas require finalized timestamps for terminal states. Spell this out
-      # so PostgreSQL can use the partial (state, finalized_at) index.
-      clauses << "finalized_at IS NOT NULL" if finalized
-      # Explicit NULLS LAST prevents a backward index scan, even when there are
-      # no nulls. Only request it for timestamps that can actually be null.
-      null_order = (params.sort_by == :finalized_at && !finalized) ? " NULLS LAST" : ""
-
-      params.metadata&.each { |key, value| clauses << runtime_metadata_equals(key, value) }
-      Array(params.tags_all).each { |tag| clauses << runtime_tag_contains(tag) }
-      if params.tags_any&.any?
-        clauses << "(" + params.tags_any.map { |tag| runtime_tag_contains(tag) }.join(" OR ") + ")"
-      end
-
-      where = clauses.empty? ? "" : "WHERE #{clauses.join(" AND ")}"
-      runtime_job_rows(<<~SQL)
-        #{where}
-        ORDER BY #{params.sort_by} #{params.sort_order.to_s.upcase}#{null_order}, id #{params.sort_order.to_s.upcase}
-        LIMIT #{params.limit}
-      SQL
+      runtime_job_list(params)
     end
 
     def job_metadata_merge(id, metadata)
@@ -184,56 +175,81 @@ module River::Driver
       updated_id ? job_get_by_id(updated_id) : nil
     end
 
-    def job_rescue_stuck(horizon:, retry_policy:, now: Time.now.utc, max: 1_000)
+    def job_rescue_stuck(horizon:, retry_policy:, now: Time.now.utc, max: 1_000, logger: nil, rescue_if: nil)
+      max = Integer(max)
       transaction do
-        # Select only stuck jobs before applying the limit, and hold their locks
-        # until rescue finishes so a newer attempt cannot be rescued by mistake.
+        # Lock each candidate until its transition finishes. Continue past jobs
+        # that are still within their timeouts without consuming the rescue limit.
+        after_id = rescued = 0
         lock = runtime_postgres? ? "FOR UPDATE SKIP LOCKED" : ""
-        ids = runtime_returning_ids(<<~SQL)
-          SELECT id FROM river_job
-          WHERE state = 'running' AND attempted_at < #{runtime_time(horizon)}
-          ORDER BY id LIMIT #{Integer(max)} #{lock}
-        SQL
-        jobs = ids.map { |id| runtime_read_job(id) }
-        jobs.each do |job|
-          cancelled = job.metadata.key?("cancel_attempted_at")
-          final = cancelled || job.attempt >= job.max_attempts
-          state = if cancelled
-            River::JOB_STATE_CANCELLED
-          elsif final
-            River::JOB_STATE_DISCARDED
-          else
-            River::JOB_STATE_RETRYABLE
+        while rescued < max
+          ids = runtime_returning_ids(<<~SQL)
+            SELECT id FROM river_job
+            WHERE state = 'running' AND attempted_at < #{runtime_time(horizon)} AND id > #{after_id}
+            ORDER BY id LIMIT #{max - rescued} #{lock}
+          SQL
+          break if ids.empty?
+
+          after_id = ids.last
+          ids.each do |id|
+            job = runtime_read_job(id)
+            cancelled = job.metadata.key?("cancel_attempted_at")
+            next if !cancelled && rescue_if && !rescue_if.call(job, now)
+            final = cancelled || job.attempt >= job.max_attempts
+            state = if cancelled
+              River::JOB_STATE_CANCELLED
+            elsif final
+              River::JOB_STATE_DISCARDED
+            else
+              River::JOB_STATE_RETRYABLE
+            end
+            error = River::AttemptError.new(at: now, attempt: job.attempt, error: "Stuck job rescued by River", trace: "")
+            rescue_count = job.metadata["river:rescue_count"]
+            rescue_count = case rescue_count
+            when Integer then rescue_count
+            when Float then rescue_count.finite? ? rescue_count.to_i : 0
+            else 0
+            end
+            job_set_state_if_running(
+              id: job.id,
+              error: error,
+              finalized_at: final ? now : nil,
+              metadata: {"river:rescue_count" => rescue_count + 1},
+              now: now,
+              scheduled_at: final ? nil : runtime_rescue_retry(job, error, retry_policy, now, logger),
+              state: state
+            )
+            rescued += 1
           end
-          error = River::AttemptError.new(at: now, attempt: job.attempt, error: "Stuck job rescued by River", trace: "")
-          job_set_state_if_running(
-            id: job.id,
-            error: error,
-            finalized_at: final ? now : nil,
-            metadata: {"river:rescue_count" => job.metadata.fetch("river:rescue_count", 0).to_i + 1},
-            now: now,
-            scheduled_at: final ? nil : retry_policy.next_retry(job, error, now: now),
-            state: state
-          )
         end
 
-        jobs.length
+        rescued
       end
     end
 
     def job_retry(id, now: Time.now.utc)
-      updated_id = runtime_returning_ids(<<~SQL).first
-        UPDATE river_job
-        SET state = 'available',
-            max_attempts = CASE WHEN attempt = max_attempts THEN max_attempts + 1 ELSE max_attempts END,
-            finalized_at = NULL,
-            scheduled_at = #{runtime_time(now)}
-        WHERE id = #{Integer(id)}
-          AND state != 'running'
-          AND (state != 'available' OR scheduled_at > #{runtime_time(now)})
-        RETURNING id
-      SQL
-      job_get_by_id(updated_id || id)
+      updated_id, job = transaction do
+        # Check the counter in the write itself so a concurrent claim cannot
+        # advance it between validation and the update.
+        updated_id = runtime_returning_ids(<<~SQL).first
+          UPDATE river_job
+          SET state = 'available',
+              max_attempts = CASE WHEN attempt = max_attempts THEN max_attempts + 1 ELSE max_attempts END,
+              metadata = #{runtime_postgres? ? "metadata - 'cancel_attempted_at'" : "jsonb_remove(metadata, '$.cancel_attempted_at')"},
+              finalized_at = NULL,
+              scheduled_at = #{runtime_time(now)}
+          WHERE id = #{Integer(id)}
+            AND state != 'running'
+            AND (state != 'available' OR scheduled_at > #{runtime_time(now)})
+            AND attempt < #{River::MAX_ATTEMPTS_LIMIT}
+          RETURNING id
+        SQL
+        [updated_id, job_get_by_id(updated_id || id)]
+      end
+      if !updated_id && job && job.state != "running" && (job.state != "available" || job.scheduled_at > now) && job.attempt >= River::MAX_ATTEMPTS_LIMIT
+        raise ArgumentError, "cannot retry a job with #{River::MAX_ATTEMPTS_LIMIT} or more attempts"
+      end
+      job
     end
 
     def job_schedule(now: Time.now.utc, max: 1_000)
@@ -267,8 +283,9 @@ module River::Driver
     def job_set_state_if_running(id:, state:, now: Time.now.utc, attempt: nil,
       error: nil, finalized_at: nil, metadata: nil, scheduled_at: nil)
       state = state.to_s
-      retrying = [River::JOB_STATE_AVAILABLE, River::JOB_STATE_RETRYABLE, River::JOB_STATE_SCHEDULED].include?(state)
-      cancel_path = retrying ? runtime_cancel_attempted : "false"
+      # Cancellation wins over every attempt outcome, including exhausted
+      # retries, direct completion, and transitions requested by extensions.
+      cancel_path = runtime_cancel_attempted
 
       assignments = [] #: Array[String]
       assignments << "attempt = CASE WHEN NOT (#{cancel_path}) THEN #{Integer(attempt)} ELSE attempt END" unless attempt.nil?
@@ -319,7 +336,10 @@ module River::Driver
     end
 
     def leader_release(id)
-      runtime_execute("DELETE FROM river_leader WHERE leader_id = #{runtime_quote(id)}")
+      transaction do
+        deleted = runtime_query_rows("DELETE FROM river_leader WHERE leader_id = #{runtime_quote(id)} RETURNING leader_id")
+        runtime_notify("river_leadership", action: "resigned", leader_id: id) unless deleted.empty?
+      end
     end
 
     def leader_renew(id, ttl: 30, now: Time.now.utc)
@@ -356,34 +376,53 @@ module River::Driver
     end
 
     def queue_pause(name, now: Time.now.utc)
-      filter = (name == "*") ? "true" : "name = #{runtime_quote(name)}"
-      runtime_execute(<<~SQL)
-        UPDATE river_queue
-        SET paused_at = CASE WHEN paused_at IS NULL THEN #{runtime_time(now)} ELSE paused_at END,
-            updated_at = CASE WHEN paused_at IS NULL THEN #{runtime_time(now)} ELSE updated_at END
-        WHERE #{filter}
-      SQL
+      transaction do
+        filter = (name == "*") ? "true" : "name = #{runtime_quote(name)}"
+        changed = runtime_query_rows(<<~SQL)
+          UPDATE river_queue
+          SET paused_at = CASE WHEN paused_at IS NULL THEN #{runtime_time(now)} ELSE paused_at END,
+              updated_at = CASE WHEN paused_at IS NULL THEN #{runtime_time(now)} ELSE updated_at END
+          WHERE #{filter}
+          RETURNING #{runtime_queue_columns}
+        SQL
+        runtime_notify("river_control", action: "pause", queue: name) unless changed.empty?
+        changed.map { |row| runtime_queue_from_row(row) }
+      end
     end
 
     def queue_resume(name, now: Time.now.utc)
-      filter = (name == "*") ? "true" : "name = #{runtime_quote(name)}"
-      runtime_execute(<<~SQL)
-        UPDATE river_queue
-        SET updated_at = CASE WHEN paused_at IS NOT NULL THEN #{runtime_time(now)} ELSE updated_at END,
-            paused_at = NULL
-        WHERE #{filter}
-      SQL
+      transaction do
+        filter = (name == "*") ? "true" : "name = #{runtime_quote(name)}"
+        changed = runtime_query_rows(<<~SQL)
+          UPDATE river_queue
+          SET updated_at = CASE WHEN paused_at IS NOT NULL THEN #{runtime_time(now)} ELSE updated_at END,
+              paused_at = NULL
+          WHERE #{filter}
+          RETURNING #{runtime_queue_columns}
+        SQL
+        runtime_notify("river_control", action: "resume", queue: name) unless changed.empty?
+        changed.map { |row| runtime_queue_from_row(row) }
+      end
     end
 
     def queue_update(name, metadata:, now: Time.now.utc)
-      id = runtime_query_rows(<<~SQL).first
-        UPDATE river_queue SET metadata = #{runtime_json(metadata)}, updated_at = #{runtime_time(now)}
-        WHERE name = #{runtime_quote(name)} RETURNING name
-      SQL
-      id ? queue_get(name) : nil
+      raise ArgumentError, "metadata must be a Hash" unless metadata.is_a?(Hash)
+
+      transaction do
+        row = runtime_query_rows(<<~SQL).first
+          UPDATE river_queue SET metadata = #{runtime_json(metadata)}, updated_at = #{runtime_time(now)}
+          WHERE name = #{runtime_quote(name)} RETURNING name
+        SQL
+        if row
+          runtime_notify("river_control", action: "metadata_changed", queue: name, metadata: metadata)
+          queue_get(name)
+        end
+      end
     end
 
     def queue_upsert(name, metadata: {}, now: Time.now.utc)
+      raise ArgumentError, "metadata must be a Hash" unless metadata.is_a?(Hash)
+
       runtime_execute(<<~SQL)
         INSERT INTO river_queue (name, created_at, metadata, updated_at)
         VALUES (#{runtime_quote(name)}, #{runtime_time(now)}, #{runtime_json(metadata)}, #{runtime_time(now)})
@@ -419,17 +458,27 @@ module River::Driver
           "array_append(CASE WHEN cardinality(attempted_by) >= 100 THEN attempted_by[(cardinality(attempted_by) - 98):] ELSE attempted_by END, #{runtime_quote(attempted_by)})"
         else
           # Preserve corrupt history so decoding can fail this attempt instead
-          # of silently repairing it or aborting the entire claim batch.
+          # of silently repairing it or aborting the entire claim batch. Trim
+          # to the newest 99 entries before appending, preserving JSON types.
           <<~SQL
             CASE WHEN NOT json_valid(attempted_by, 10) AND attempted_by IS NOT NULL THEN attempted_by
-                 ELSE jsonb(json_insert(json(coalesce(attempted_by, jsonb('[]'))), '$[#]', #{runtime_quote(attempted_by)})) END
+                 ELSE jsonb(json_insert(json(
+                   CASE WHEN json_array_length(attempted_by) >= 100 THEN (
+                     SELECT json_group_array(json(value)) FROM (
+                       SELECT attempted_by -> ('$[' || key || ']') AS value FROM json_each(attempted_by)
+                       WHERE key >= json_array_length(attempted_by) - 99 ORDER BY key
+                     )
+                   ) ELSE coalesce(attempted_by, jsonb('[]')) END
+                 ), '$[#]', #{runtime_quote(attempted_by)})) END
           SQL
         end
 
         lock_clause = runtime_postgres? ? "FOR UPDATE SKIP LOCKED" : ""
+        # An administratively requeued job may already be at the counter limit.
+        # Saturate instead of letting that row abort the entire claim batch.
         ids = runtime_returning_ids(<<~SQL)
           UPDATE river_job
-          SET attempt = attempt + 1,
+          SET attempt = CASE WHEN attempt < #{River::MAX_ATTEMPTS_LIMIT} THEN attempt + 1 ELSE attempt END,
               attempted_at = #{runtime_time(now)},
               attempted_by = #{attempted_by_sql},
               state = 'running'
@@ -531,12 +580,49 @@ module River::Driver
       "(#{column} IS NULL OR #{column} #{comparison} #{value} OR (#{column} = #{value} AND #{id_clause}))"
     end
 
+    private def runtime_job_list(params, for_delete: false)
+      clauses = [] #: Array[String]
+      clauses << "state != 'running'" if for_delete
+      clauses << runtime_cursor_clause(params) if params.after
+      clauses << "id #{(params.sort_order == :asc) ? ">" : "<"} #{Integer(params.after_id)}" if params.after_id
+      clauses << runtime_in_clause("id", params.ids.map { |value| Integer(value) }) if params.ids&.any?
+      clauses << runtime_in_clause("kind", params.kinds) if params.kinds&.any?
+      clauses << runtime_in_clause("priority", params.priorities.map { |value| Integer(value) }) if params.priorities&.any?
+      clauses << runtime_in_clause("queue", params.queues) if params.queues&.any?
+      clauses << runtime_in_clause("state", params.states) if params.states&.any?
+
+      finalized = params.sort_by == :finalized_at && params.states&.length == 1 &&
+        %w[cancelled completed discarded].include?(params.states.first)
+      # Schemas require finalized timestamps for terminal states. Spell this out
+      # so PostgreSQL can use the partial (state, finalized_at) index.
+      clauses << "finalized_at IS NOT NULL" if finalized
+      # Explicit NULLS LAST prevents a backward index scan, even when there are
+      # no nulls. Only request it for timestamps that can actually be null.
+      null_order = (params.sort_by == :finalized_at && !finalized) ? " NULLS LAST" : ""
+
+      params.metadata&.each { |key, value| clauses << runtime_metadata_equals(key, value) }
+      Array(params.tags_all).each { |tag| clauses << runtime_tag_contains(tag) }
+      if params.tags_any&.any?
+        clauses << "(" + params.tags_any.map { |tag| runtime_tag_contains(tag) }.join(" OR ") + ")"
+      end
+
+      where = clauses.empty? ? "" : "WHERE #{clauses.join(" AND ")}"
+      runtime_job_rows(<<~SQL)
+        #{where}
+        ORDER BY #{params.sort_by} #{params.sort_order.to_s.upcase}#{null_order}, id #{params.sort_order.to_s.upcase}
+        LIMIT #{params.limit}
+        #{"FOR UPDATE SKIP LOCKED" if for_delete && runtime_postgres?}
+      SQL
+    end
+
     private def runtime_json(value)
       encoded = value.is_a?(String) ? value : JSON.generate(value)
       runtime_postgres? ? "#{runtime_quote(encoded)}::jsonb" : "jsonb(#{runtime_quote(encoded)})"
     end
 
     private def runtime_merge_metadata(metadata)
+      raise ArgumentError, "metadata must be a Hash" unless metadata.is_a?(Hash)
+
       if runtime_postgres?
         "metadata || #{runtime_json(metadata)}"
       else
@@ -611,6 +697,17 @@ module River::Driver
       )
     end
 
+    private def runtime_rescue_retry(job, error, retry_policy, now, logger)
+      retry_at = retry_policy.next_retry(job, error, now: now)
+      raise ArgumentError, "next_retry must return a Time" unless retry_at.is_a?(Time)
+      raise ArgumentError, "next_retry must not return a past Time" if retry_at < now
+
+      retry_at
+    rescue => retry_error
+      logger&.error("River rescue retry scheduling failed; using default backoff: #{retry_error.full_message}")
+      River::DefaultClientRetryPolicy.new.next_retry(job, error, now: now)
+    end
+
     private def runtime_returning_ids(sql)
       runtime_query_rows(sql).map { |row| runtime_value(row, :id).to_i }
     end
@@ -641,17 +738,31 @@ module River::Driver
 
     private def runtime_update_value(field, value)
       case field
-      when :attempt, :max_attempts
-        Integer(value).to_s
+      when :attempt
+        attempt = Integer(value)
+        raise ArgumentError, "attempt must be between 0 and #{River::MAX_ATTEMPTS_LIMIT}" unless (0..River::MAX_ATTEMPTS_LIMIT).cover?(attempt)
+
+        attempt.to_s
       when :attempted_at, :finalized_at
         value ? runtime_time(value) : "NULL"
       when :attempted_by
-        runtime_postgres? ? "ARRAY[#{Array(value).map { |item| runtime_quote(item) }.join(",")}]::text[]" : runtime_json(Array(value))
+        values = Array(value) #: Array[untyped]
+        raise ArgumentError, "attempted_by must contain only Strings" unless values.all? { |item| item.is_a?(String) }
+
+        runtime_postgres? ? "ARRAY[#{values.map { |item| runtime_quote(item) }.join(",")}]::text[]" : runtime_json(values)
       when :errors
         input_values = Array(value) #: Array[untyped]
         values = input_values.map { |error| error.respond_to?(:to_h) ? error.to_h : error }
         runtime_postgres? ? "ARRAY[#{values.map { |item| runtime_json(item) }.join(",")}]::jsonb[]" : runtime_json(values)
+      when :max_attempts
+        max_attempts = Integer(value)
+        raise ArgumentError, "max_attempts must be greater than zero" unless max_attempts > 0
+        raise ArgumentError, "max_attempts must not exceed #{River::MAX_ATTEMPTS_LIMIT}" if max_attempts > River::MAX_ATTEMPTS_LIMIT
+
+        max_attempts.to_s
       when :metadata
+        raise ArgumentError, "metadata must be a Hash" unless value.is_a?(Hash)
+
         runtime_json(value)
       when :state
         runtime_state(value)

data/lib/event.rb

@@ -12,7 +12,14 @@ module River
   # Event emitted by a Client and delivered through a Subscription.
   Event = Data.define(:kind, :job, :queue, :stats)
 
-  # Timing statistics attached to job lifecycle events.
+  # Timing statistics attached to job lifecycle events, in seconds.
+  # run_duration measures worker execution including work hooks;
+  # complete_duration measures finalization after execution finishes.
+  # queue_wait_duration uses the schedule at the start of execution, before
+  # retries or snoozes change it.
+  # Execution and completion durations use a monotonic clock. Externally
+  # executed jobs have zero run_duration because this runtime does not observe
+  # their execution; their queue wait ends at the row's attempted_at timestamp.
   JobStatistics = Data.define(:complete_duration, :queue_wait_duration, :run_duration)
 
   # Bounded stream of selected Client lifecycle events.

data/lib/insert_opts.rb

@@ -7,6 +7,8 @@ module River
   class InsertOpts
     # The maximum number of total attempts (including both the original run and
     # all retries) before a job is abandoned and set as discarded.
+    # Must be between 1 and MAX_ATTEMPTS_LIMIT (32,767).
+    # Defaults to MAX_ATTEMPTS_DEFAULT.
     attr_accessor :max_attempts
 
     # Arbitrary metadata to merge into the persisted job. River and River Pro
@@ -23,6 +25,7 @@ module River
     attr_accessor :priority
 
     # The name of the job queue in which to insert the job, as a symbol or string.
+    # Must contain 1 to 127 ASCII letters, digits, underscores, hyphens, colons, or periods.
     #
     # Defaults to QUEUE_DEFAULT.
     attr_accessor :queue
@@ -38,7 +41,8 @@ module River
     attr_accessor :scheduled_at
 
     # Initial state. Primarily intended for extensions such as workflows and
-    # sequences, which insert blocked jobs as `:pending`. Accepts symbols or strings.
+    # sequences, which insert blocked jobs as `:pending`. Accepts only
+    # `available`, `pending`, or `scheduled`, as symbols or strings.
     attr_accessor :state
 
     # An arbitrary list of keywords to add to the job. They have no functional
@@ -109,7 +113,8 @@ module River
     # in UTC. Equivalent times in different zones produce the same unique key.
     #
     # The period should be specified in seconds. So a job that's unique every 15
-    # minute period would have a value of 900.
+    # minute period would have a value of 900. Nonzero periods must be at least
+    # one second; zero disables period-based uniqueness.
     #
     # Default is no unique period, meaning that as long as any other unique
     # property is enabled, uniqueness will be enforced across all jobs of the

data/lib/job.rb

@@ -202,7 +202,7 @@ module River
 
     # Returns the database-compatible representation of this attempt error.
     def to_h
-      {at: at.utc.iso8601(6), attempt: attempt, error: error, trace: trace}
+      {at: at.getutc.iso8601(6), attempt: attempt, error: error, trace: trace}
     end
   end
 end

data/lib/periodic_cron.rb

@@ -4,21 +4,56 @@ module River
   # A cron schedule for PeriodicJob. Add the optional +fugit+ gem to use it.
   class PeriodicCron
     # Parses a cron expression once. +timezone+ defaults to UTC; use an IANA
-    # name such as America/New_York for local calendar schedules. Specify the
-    # timezone here, not inside +expression+. Fugit is loaded only on construction.
+    # name or a fixed offset for local schedules. A CRON_TZ= or TZ= prefix takes
+    # precedence. Supports Go's @every durations, rounded down to whole seconds
+    # with a one-second minimum. Fugit is loaded only on construction.
     def initialize(expression, timezone: "UTC")
       require "fugit"
 
       raise ArgumentError, "cron expression must be a String" unless expression.is_a?(String)
       raise ArgumentError, "timezone must be a nonempty name without whitespace" unless timezone.is_a?(String) && /\A\S+\z/.match?(timezone)
 
-      @cron = Object.const_get(:Fugit).const_get(:Cron).do_parse("#{expression} #{timezone}")
+      expression = expression.strip
+      if (prefix = /\A(?:CRON_TZ|TZ)=(\S+)\s+(.+)\z/.match(expression))
+        timezone = prefix[1].to_s
+        expression = prefix[2].to_s
+      end
+      # Validate the zone even for interval schedules, which don't use it.
+      cron_class = Object.const_get(:Fugit).const_get(:Cron)
+      cron_class.do_parse("* * * * * #{timezone}")
+      @interval = nil
+      if expression.start_with?("@every ")
+        @interval = parse_interval(expression.delete_prefix("@every "))
+        @cron = nil
+      else
+        @cron = cron_class.do_parse("#{expression.tr("?", "*")} #{timezone}")
+      end
     end
 
-    # Returns a UTC Time strictly after +time+. Calendar and daylight-saving
-    # rules are provided by Fugit; this helper does not enqueue or persist jobs.
+    # Returns a UTC Time strictly after +time+. Interval schedules align to
+    # whole seconds, as Go does. Calendar and daylight-saving rules use Fugit.
     def next(time)
-      @cron.next_time(time).to_t.getutc
+      interval = @interval
+      return Time.at(time.to_i + interval).utc if interval
+
+      # Keep the reference in UTC so Fugit does not skip a repeated local wall
+      # time when daylight saving ends. The schedule owns the calendar zone.
+      @cron.next_time(time.getutc).to_t.getutc
+    end
+
+    private def parse_interval(duration)
+      # Go's time.ParseDuration syntax, deliberately excluding Fugit's extra
+      # units (days/months) and natural-language interval expressions.
+      sign = duration.start_with?("-") ? -1 : 1
+      duration = duration.sub(/\A[+-]/, "")
+      parts = duration.scan(/((?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+))(ns|us|µs|μs|ms|s|m|h)/) #: Array[[String, String]] # rubocop:disable Layout/LeadingCommentSpace
+      valid = duration == "0" || (!parts.empty? && parts.map(&:join).join == duration)
+      raise ArgumentError, "invalid @every duration" unless valid
+      units = {"ns" => 1, "us" => 1_000, "µs" => 1_000, "μs" => 1_000, "ms" => 1_000_000, "s" => 1_000_000_000, "m" => 60_000_000_000, "h" => 3_600_000_000_000}
+      nanos = parts.sum { |number, unit| (number.to_r * units.fetch(unit)).to_i } * sign
+      raise ArgumentError, "@every duration exceeds Go's duration range" unless (-(1 << 63)...(1 << 63)).cover?(nanos)
+
+      [nanos.div(1_000_000_000), 1].max
     end
   end
 end

data/lib/periodic_job.rb

@@ -56,7 +56,8 @@ module River
 
   # Thread-safe collection used to change a client's periodic jobs at runtime.
   class PeriodicJobBundle
-    def initialize(jobs, wake:)
+    def initialize(jobs, wake:, enabled: true)
+      @enabled = enabled
       @jobs = {}
       @mutex = Mutex.new
       @next_handle = 0
@@ -72,6 +73,8 @@ module River
     # Adds periodic jobs atomically and returns their handles in input order.
     # Invalid schedules or duplicate IDs leave the registry unchanged.
     def add_many(jobs)
+      raise ArgumentError, "periodic jobs require leader election" if !@enabled && !jobs.empty?
+
       now = Time.now.utc
       entries = jobs.map { |job| {job: job, next_at: job.run_on_start ? now : job.next_at(now)} }
       handles = @mutex.synchronize do
@@ -117,6 +120,11 @@ module River
       end
     end
 
+    # Returns true when the bundle has no registered periodic jobs.
+    def empty?
+      @mutex.synchronize { @jobs.empty? }
+    end
+
     # Removes the job associated with +handle+, returning the PeriodicJob or
     # nil when no such handle exists.
     def remove(handle)

data/migration/README.md

@@ -5,7 +5,9 @@ https://github.com/riverqueue/river, distributed under the upstream Mozilla
 Public License 2.0 (see LICENSE). The Ruby implementation remains licensed
 under the repository's MPL-2.0 license.
 
-The bundle matches River v0.48.0 through main migration 008.
-manifest.json records the source commit and SHA-256 of every SQL file.
+The bundle includes main migrations through version 008.
+manifest.json records the SHA-256 of every SQL file in the repository's
+riverdriver/ directory.
+Verification compares against this checkout, not a pinned upstream revision.
 Update or verify these files with scripts/sync_migrations.rb; do not edit SQL
 here independently of upstream. Private Pro migrations are not included here.

data/migration/manifest.json

@@ -33,6 +33,5 @@
     "sqlite/main/008_job_id_autoincrement.down.sql": "04871283fe5d4cab4ac70da28d8509aa7ba765994d528c2dcc7ebe0ee596710c",
     "sqlite/main/008_job_id_autoincrement.up.sql": "049c9bf615f24a326bcc31ddc87b46f76e3de11e3eea3b2b9e1358131b3f3bed"
   },
-  "repository": "river",
-  "revision": "c2c380490d14df8efc28b86fbe7be1cf93930405"
+  "source": "riverdriver/"
 }