riverqueue 0.13.0 → 0.14.0

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

data/lib/driver/runtime.rb

@@ -5,12 +5,19 @@ require "time"
 module River::Driver
   # Database operations used by River's worker runtime. Driver gems implement a
   # small set of raw SQL primitives and include this module so the state machine
-  # stays identical across ActiveRecord and Sequel.
+  # stays identical across ActiveRecord and Sequel. Those private primitives
+  # provide execution, quoting, row access, and connection management inside
+  # driver modules; callers use the driver's public operations and Ruby values.
   module Runtime
     def init_driver
       postgres_capabilities if runtime_postgres?
     end
 
+    # Returns the UTC timestamp that writing and reading +time+ preserves.
+    def normalize_time(time)
+      runtime_postgres? ? time.getutc.floor(6) : time.getutc.round(3)
+    end
+
     def postgres_capabilities
       @postgres_capabilities_cache.fetch(runtime_connection_pool) do
         row = runtime_query_rows(<<~SQL).first
@@ -27,7 +34,7 @@ module River::Driver
     end
 
     # Notifications and rows must commit together. The insertion drivers call
-    # this inside their transaction; PostgreSQL defers delivery until commit.
+    # this inside their transaction; Postgres defers delivery until commit.
     private def postgres_notify_insert(params)
       queues = params.select { |param| param.state == River::JOB_STATE_AVAILABLE }.map(&:queue).uniq
       return if queues.empty?
@@ -68,19 +75,23 @@ module River::Driver
     # 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)
+    def job_complete(id:, finalized_at:, expected_job: nil, metadata: nil, now: Time.now.utc)
       id = Integer(id)
+      predicate = "id = #{id}"
+      predicate += " AND #{runtime_job_attempt_predicate(expected_job)}" if expected_job
       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
+      transaction do
+        updated_id = runtime_returning_ids(<<~SQL).first
+          UPDATE river_job SET #{assignments.join(", ")}
+          WHERE #{predicate} AND state = 'running' AND NOT (#{runtime_cancel_attempted})
+          RETURNING id
+        SQL
+        next runtime_read_job(updated_id) if updated_id
 
-      :cancelled if job_get_cancelled_ids([id]).include?(id)
+        :cancelled if runtime_returning_ids("SELECT id FROM river_job WHERE #{predicate} AND (#{runtime_cancel_attempted})").any?
+      end
     end
 
     def job_delete(id)
@@ -165,14 +176,24 @@ module River::Driver
       runtime_job_list(params)
     end
 
-    def job_metadata_merge(id, metadata)
-      updated_id = runtime_returning_ids(<<~SQL).first
-        UPDATE river_job
-        SET metadata = #{runtime_merge_metadata(metadata)}
-        WHERE id = #{Integer(id)}
-        RETURNING id
-      SQL
-      updated_id ? job_get_by_id(updated_id) : nil
+    # When supplied, expected_job prevents metadata from crossing into another
+    # attempt or state. Keep the update and returned snapshot in one transaction.
+    def job_metadata_merge(id, metadata, expected_job = nil)
+      predicate = "id = #{Integer(id)}"
+      if expected_job
+        predicate += " AND #{runtime_job_attempt_predicate(expected_job)}"
+        predicate += " AND state = #{runtime_quote(expected_job.state)}"
+      end
+
+      transaction do
+        updated_id = runtime_returning_ids(<<~SQL).first
+          UPDATE river_job
+          SET metadata = #{runtime_merge_metadata(metadata)}
+          WHERE #{predicate}
+          RETURNING id
+        SQL
+        updated_id ? job_get_by_id(updated_id) : nil
+      end
     end
 
     def job_rescue_stuck(horizon:, retry_policy:, now: Time.now.utc, max: 1_000, logger: nil, rescue_if: nil)
@@ -244,7 +265,9 @@ module River::Driver
             AND attempt < #{River::MAX_ATTEMPTS_LIMIT}
           RETURNING id
         SQL
-        [updated_id, job_get_by_id(updated_id || id)]
+        job = job_get_by_id(updated_id || id)
+        runtime_notify("river_insert", queue: job.queue) if updated_id && job
+        [updated_id, job]
       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"
@@ -252,31 +275,18 @@ module River::Driver
       job
     end
 
+    # Makes due scheduled and retryable jobs available. A job is discarded
+    # instead if another row already holds its unique key, or if an earlier
+    # job in the same pass shares that key. The queries find these conflicts
+    # before they write, so the pass never needs a savepoint to recover from a
+    # failed write.
     def job_schedule(now: Time.now.utc, max: 1_000)
       transaction do
-        # Hold each selected row until its transition (including uniqueness
-        # conflict handling) finishes. A concurrent retry may change its due time.
-        lock = runtime_postgres? ? "FOR UPDATE SKIP LOCKED" : ""
-        ids = runtime_query_rows(<<~SQL).map { |row| runtime_value(row, :id).to_i }
-          SELECT id FROM river_job
-          WHERE state IN ('retryable', 'scheduled') AND scheduled_at <= #{runtime_time(now)}
-          ORDER BY priority, scheduled_at, id
-          LIMIT #{Integer(max)} #{lock}
-        SQL
-        ids.each do |id|
-          transaction do
-            runtime_execute("UPDATE river_job SET state = 'available' WHERE id = #{id} AND state IN ('retryable', 'scheduled')")
-          end
-        rescue runtime_unique_violation_class
-          runtime_execute(<<~SQL)
-            UPDATE river_job
-            SET state = 'discarded', finalized_at = #{runtime_time(now)},
-                metadata = #{runtime_merge_metadata("unique_key_conflict" => "scheduler_discarded")}
-            WHERE id = #{id}
-          SQL
-        end
-
-        ids.length
+        queues = runtime_postgres? ? runtime_schedule_postgres(now, Integer(max)) : runtime_schedule_sqlite(now, Integer(max))
+        # Notify each changed queue, including queues with only discarded
+        # jobs, as Go does.
+        queues.uniq.each { |queue| runtime_notify("river_insert", queue: queue) }
+        queues.length
       end
     end
 
@@ -365,6 +375,16 @@ module River::Driver
       SQL
     end
 
+    # Opens a receiver independent of application transactions. Postgres uses
+    # one dedicated connection; SQLite keeps a cursor in its shared outbox.
+    def notification_listener
+      return NotificationListener::SQLite.new(method(:notification_query)) unless runtime_postgres?
+      return unless postgres_capabilities.supports_listen_notify
+
+      connection, schema = runtime_notification_connection
+      NotificationListener::Postgres.new(connection, schema)
+    end
+
     def queue_get(name)
       row = runtime_query_rows("SELECT #{runtime_queue_columns} FROM river_queue WHERE name = #{runtime_quote(name)}").first
       runtime_queue_from_row(row)
@@ -431,6 +451,21 @@ module River::Driver
       queue_get(name)
     end
 
+    # Delivery follows the caller's transaction, just like job insertion.
+    def request_resign
+      transaction { runtime_notify("river_leadership", action: "request_resign", leader_id: "") }
+      nil
+    end
+
+    private def notification_query(sql)
+      runtime_query_rows(sql)
+    end
+
+    # Smallest timestamp increment preserved by this driver, in seconds.
+    def time_precision
+      runtime_postgres? ? Rational(1, 1_000_000) : Rational(1, 1_000)
+    end
+
     private def runtime_append_error(error)
       value = error.respond_to?(:to_h) ? error.to_h : error
       if runtime_postgres?
@@ -558,7 +593,7 @@ module River::Driver
       params.map do |param|
         key = param.unique_key
         if key && !key.empty? && River::UniqueBitmask.to_states((param.unique_states || "0").to_i(2)).include?(param.state)
-          # PostgreSQL rejects batches that upsert the same indexed row twice.
+          # Postgres rejects batches that upsert the same indexed row twice.
           raise ArgumentError, "unique key appears more than once in batch" if keys[key]
 
           keys[key] = true
@@ -580,6 +615,10 @@ module River::Driver
       "(#{column} IS NULL OR #{column} #{comparison} #{value} OR (#{column} = #{value} AND #{id_clause}))"
     end
 
+    private def runtime_job_attempt_predicate(job)
+      "attempt = #{Integer(job.attempt)} AND attempted_at IS NOT DISTINCT FROM #{runtime_nullable_time(job.attempted_at)}"
+    end
+
     private def runtime_job_list(params, for_delete: false)
       clauses = [] #: Array[String]
       clauses << "state != 'running'" if for_delete
@@ -594,7 +633,7 @@ module River::Driver
       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.
+      # so Postgres 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.
@@ -620,18 +659,33 @@ module River::Driver
       runtime_postgres? ? "#{runtime_quote(encoded)}::jsonb" : "jsonb(#{runtime_quote(encoded)})"
     end
 
+    # Temporary fallback: when true, transaction helpers open a savepoint
+    # inside an open transaction instead of joining it.
+    private def runtime_legacy_subtransactions?
+      %w[1 true].include?(ENV.fetch("RIVER_USE_LEGACY_SUBTRANSACTIONS", ""))
+    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
-        # PostgreSQL's || replaces top-level values, including JSON null.
-        # JSON Merge Patch would recursively merge objects and delete nulls.
-        merged = metadata.reduce("metadata") do |expression, (key, value)|
-          path = runtime_quote("$.#{JSON.generate(key.to_s)}")
-          "jsonb_set(#{expression}, #{path}, jsonb(#{runtime_quote(JSON.generate(value))}))"
-        end
+        # Keep the SQL shape fixed regardless of the number of updated keys.
+        # -> preserves JSON booleans and large numeric tokens during aggregation.
+        merged = <<~SQL.strip
+          (WITH updates(doc) AS (SELECT #{runtime_json(metadata)})
+              SELECT CASE WHEN json_type(metadata) = 'object' THEN (
+                  SELECT jsonb_group_object(key, jsonb(doc -> fullkey))
+                  FROM (
+                      SELECT key, fullkey, metadata AS doc FROM json_each(metadata)
+                      WHERE key NOT IN (SELECT key FROM updates, json_each(doc))
+                      UNION ALL
+                      SELECT key, fullkey, doc FROM updates, json_each(doc)
+                  )
+              ) WHEN json_type(metadata) = 'array' THEN jsonb_insert(metadata, '$[#]', doc)
+              ELSE jsonb_array(json(metadata), doc) END FROM updates)
+        SQL
         "CASE WHEN json_valid(metadata, 10) THEN #{merged} ELSE metadata END"
       end
     end
@@ -712,6 +766,114 @@ module River::Driver
       runtime_query_rows(sql).map { |row| runtime_value(row, :id).to_i }
     end
 
+    # Finds conflicts and changes the whole pass in one statement.
+    private def runtime_schedule_postgres(now, max)
+      now = runtime_time(now)
+      runtime_query_rows(<<~SQL).map { |row| runtime_value(row, :queue) }
+        WITH jobs_to_schedule AS (
+            SELECT id, unique_key, unique_states, priority, scheduled_at
+            FROM river_job
+            WHERE state IN ('retryable', 'scheduled')
+                AND priority >= 0
+                AND queue IS NOT NULL
+                AND scheduled_at <= #{now}
+            ORDER BY priority, scheduled_at, id
+            LIMIT #{max}
+            FOR UPDATE
+        ),
+        jobs_with_rownum AS (
+            SELECT
+                *,
+                CASE
+                    WHEN unique_key IS NOT NULL AND unique_states IS NOT NULL THEN
+                        ROW_NUMBER() OVER (PARTITION BY unique_key ORDER BY priority, scheduled_at, id)
+                END AS row_num
+            FROM jobs_to_schedule
+        ),
+        unique_conflicts AS (
+            SELECT river_job.unique_key
+            FROM river_job
+            JOIN jobs_with_rownum
+                ON river_job.unique_key = jobs_with_rownum.unique_key
+                AND river_job.id != jobs_with_rownum.id
+            WHERE river_job.unique_key IS NOT NULL
+                AND river_job.unique_states IS NOT NULL
+                AND river_job_state_in_bitmask(river_job.unique_states, river_job.state)
+        ),
+        job_updates AS (
+            SELECT
+                job.id,
+                job.row_num IS NOT NULL AND (uc.unique_key IS NOT NULL OR job.row_num > 1) AS discard
+            FROM jobs_with_rownum job
+            LEFT JOIN unique_conflicts uc ON job.unique_key = uc.unique_key
+        )
+        UPDATE river_job
+        SET state = CASE WHEN job_updates.discard THEN 'discarded'::river_job_state ELSE 'available'::river_job_state END,
+            finalized_at = CASE WHEN job_updates.discard THEN #{now} ELSE river_job.finalized_at END,
+            metadata = CASE WHEN job_updates.discard THEN river_job.metadata || '{"unique_key_conflict": "scheduler_discarded"}'::jsonb
+                            ELSE river_job.metadata END
+        FROM job_updates
+        WHERE river_job.id = job_updates.id
+        RETURNING river_job.queue
+      SQL
+    end
+
+    # Follows Go's SQLite driver: check each unique job in order, and make it
+    # available before checking the next one, so a later job with the same
+    # key sees it as a conflict. SQLite allows one writer at a time. Once this
+    # pass writes, other connections cannot write until it ends. If another
+    # connection writes first, this pass's next write fails instead of using
+    # stale rows.
+    private def runtime_schedule_sqlite(now, max)
+      rows = runtime_query_rows(<<~SQL)
+        SELECT id, queue, unique_key IS NOT NULL AS has_unique_key
+        FROM river_job
+        WHERE state IN ('retryable', 'scheduled') AND scheduled_at <= #{runtime_time(now)}
+        ORDER BY priority, scheduled_at, id
+        LIMIT #{max}
+      SQL
+      available = [] #: Array[Integer]
+      discarded = [] #: Array[Integer]
+      rows.each do |row|
+        id = runtime_value(row, :id).to_i
+        next available << id if runtime_value(row, :has_unique_key).to_i.zero?
+
+        conflict = runtime_query_rows(<<~SQL).any?
+          SELECT 1 FROM river_job
+          WHERE id <> #{id}
+            AND unique_key = (SELECT job.unique_key FROM river_job AS job WHERE job.id = #{id})
+            AND unique_states IS NOT NULL
+            AND CASE state
+                  WHEN 'available' THEN unique_states & (1 << 0)
+                  WHEN 'cancelled' THEN unique_states & (1 << 1)
+                  WHEN 'completed' THEN unique_states & (1 << 2)
+                  WHEN 'discarded' THEN unique_states & (1 << 3)
+                  WHEN 'pending'   THEN unique_states & (1 << 4)
+                  WHEN 'retryable' THEN unique_states & (1 << 5)
+                  WHEN 'running'   THEN unique_states & (1 << 6)
+                  WHEN 'scheduled' THEN unique_states & (1 << 7)
+                  ELSE 0
+                END >= 1
+          LIMIT 1
+        SQL
+        next discarded << id if conflict
+
+        runtime_execute("UPDATE river_job SET state = 'available' WHERE id = #{id}")
+      end
+
+      unless discarded.empty?
+        runtime_execute(<<~SQL)
+          UPDATE river_job
+          SET state = 'discarded', finalized_at = #{runtime_time(now)},
+              metadata = #{runtime_merge_metadata("unique_key_conflict" => "scheduler_discarded")}
+          WHERE id IN (#{discarded.join(",")})
+        SQL
+      end
+      runtime_execute("UPDATE river_job SET state = 'available' WHERE id IN (#{available.join(",")})") unless available.empty?
+
+      rows.map { |row| runtime_value(row, :queue) }
+    end
+
     private def runtime_state(value)
       runtime_postgres? ? "#{runtime_quote(value)}::river_job_state" : runtime_quote(value)
     end
@@ -729,9 +891,9 @@ module River::Driver
 
       cast = runtime_postgres? ? "::timestamptz" : ""
       encoded = if runtime_postgres?
-        value.getutc.iso8601(6)
+        normalize_time(value).iso8601(6)
       else
-        value.getutc.round(3).strftime("%Y-%m-%d %H:%M:%S.%3N")
+        normalize_time(value).strftime("%Y-%m-%d %H:%M:%S.%3N")
       end
       "#{runtime_quote(encoded)}#{cast}"
     end

data/lib/driver.rb

@@ -50,4 +50,5 @@ end
 
 require_relative "driver/postgres_capabilities"
 require_relative "driver/job_row_decoder"
+require_relative "driver/notification_listener"
 require_relative "driver/runtime"

data/lib/insert_opts.rb

@@ -94,7 +94,7 @@ module River
   # be inserted as a new job.
   class UniqueOpts
     # Empty options don't enable uniqueness. Zero periods and empty state lists
-    # have the same meaning as their unset equivalents in the Go client.
+    # have the same meaning as their unset equivalents.
     def empty?
       !by_args && !by_queue && !exclude_kind && (!by_period || by_period == 0) && (!by_state || by_state.empty?)
     end

data/lib/job.rb

@@ -59,7 +59,7 @@ module River
 
     # The set of worker IDs that have worked this job. A worker ID differs
     # between different programs, but is shared by all executors within any
-    # given one.  (i.e. Different Go processes have different IDs, but IDs are
+    # given one.  (i.e. Different processes have different IDs, but IDs are
     # shared within any given process.) A process generates a new ID based on
     # host and current time when it starts up.
     attr_accessor :attempted_by
@@ -173,7 +173,7 @@ module River
   # that occurred.
   class AttemptError
     # The time at which the error occurred. Unreadable historical timestamps
-    # become Time.utc(1), matching Go's zero time.
+    # become Time.utc(1), the zero time 0001-01-01T00:00:00Z.
     attr_accessor :at
 
     # The attempt number on which the error occurred (maps to #attempt on a job
@@ -184,8 +184,8 @@ module River
     # value in case of a panic.
     attr_accessor :error
 
-    # Contains a stack trace from a job that panicked. The trace is produced by
-    # invoking `debug.Trace()` in Go.
+    # Contains a stack trace from a job that raised or panicked. Ruby records
+    # the exception backtrace; other River clients record their own format.
     attr_accessor :trace
 
     def initialize(

data/lib/job_persisted_logging/plugin.rb

@@ -5,7 +5,8 @@ require "logger"
 module River
   module JobPersistedLogging
     # Captures job.logger output and persists it with the attempt's state change,
-    # including failed attempts. Uses Go riverlog's metadata format for River UI.
+    # including failed attempts. Uses the shared `river:log` metadata format
+    # that River UI displays.
     # Register through Config#plugins, preferably before other work middleware.
     class Plugin
       # Limits are positive byte counts. History is capped at 64 MiB, dropping
@@ -84,7 +85,7 @@ module River
           @mutex.synchronize do
             @closed = true
             # Drop invalid/incomplete UTF-8 sequences (including a character cut
-            # at the byte limit) and NULs, which PostgreSQL JSONB cannot represent.
+            # at the byte limit) and NULs, which Postgres JSONB cannot represent.
             [@data.dup.force_encoding(Encoding::UTF_8).scrub("").delete("\0"), @truncated]
           end
         end

data/lib/migrator.rb

@@ -9,7 +9,7 @@ module River
 
     attr_reader :migrations
 
-    # Creates a migrator for an installed River driver. PostgreSQL schemas must
+    # Creates a migrator for an installed River driver. Postgres schemas must
     # already exist and use simple SQL identifiers; SQLite uses its main schema.
     # The optional migrations_path is a root containing backend/line/*.sql.
     def initialize(driver, line: "main", migrations_path: File.expand_path("../migration", __dir__.to_s), schema: nil)

data/lib/periodic_cron.rb

@@ -5,8 +5,9 @@ module River
   class PeriodicCron
     # Parses a cron expression once. +timezone+ defaults to UTC; use an IANA
     # 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.
+    # precedence. Supports @every durations such as `1h30m` or `500ms`, rounded
+    # down to whole seconds with a one-second minimum. Fugit is loaded only on
+    # construction.
     def initialize(expression, timezone: "UTC")
       require "fugit"
 
@@ -31,7 +32,7 @@ module River
     end
 
     # Returns a UTC Time strictly after +time+. Interval schedules align to
-    # whole seconds, as Go does. Calendar and daylight-saving rules use Fugit.
+    # whole seconds. Calendar and daylight-saving rules use Fugit.
     def next(time)
       interval = @interval
       return Time.at(time.to_i + interval).utc if interval
@@ -51,7 +52,7 @@ module River
       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)
+      raise ArgumentError, "@every duration must fit in signed 64-bit nanoseconds" unless (-(1 << 63)...(1 << 63)).cover?(nanos)
 
       [nanos.div(1_000_000_000), 1].max
     end

data/lib/periodic_job.rb

@@ -76,7 +76,10 @@ module River
       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)} }
+      entries = jobs.map do |job|
+        run_on_start = job.run_on_start
+        {job: job, next_at: run_on_start ? now : job.next_at(now), run_on_start: run_on_start}
+      end
       handles = @mutex.synchronize do
         ids = @jobs.values.to_h { |entry| [entry[:job].id, true] }
         jobs.each do |job|
@@ -100,7 +103,9 @@ module River
       self
     end
 
-    def due(now)
+    # Internal scheduler entry point that retains each claimed occurrence's
+    # time even after advancing its registration.
+    def __due_with_times(now)
       # Application schedules may reenter the registry, so evaluate outside its
       # lock and only advance registrations that haven't been removed or claimed.
       entries = @mutex.synchronize { @jobs.map { |handle, entry| [handle, entry, entry[:next_at]] } }
@@ -110,8 +115,10 @@ module River
         following = entry[:job].next_at(now)
         @mutex.synchronize do
           next unless @jobs[handle].equal?(entry) && entry[:next_at] == next_at
+          scheduled_at = entry[:run_on_start] ? now : next_at
+          entry[:run_on_start] = false
           entry[:next_at] = following
-          entry[:job]
+          [entry[:job], scheduled_at]
         end
       rescue => error
         raise unless block_given?
@@ -120,6 +127,10 @@ module River
       end
     end
 
+    def due(now, &block)
+      __due_with_times(now, &block).map(&:first)
+    end
+
     # Returns true when the bundle has no registered periodic jobs.
     def empty?
       @mutex.synchronize { @jobs.empty? }