riverqueue 0.12.0 → 0.14.0

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/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
@@ -90,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
@@ -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

@@ -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(
@@ -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/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

@@ -4,21 +4,57 @@ 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 @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"
 
       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. 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 must fit in signed 64-bit nanoseconds" 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,8 +73,13 @@ 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)} }
+      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|
@@ -97,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]] } }
@@ -107,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?
@@ -117,6 +127,15 @@ 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? }
+    end
+
     # Removes the job associated with +handle+, returning the PeriodicJob or
     # nil when no such handle exists.
     def remove(handle)

data/lib/resumable.rb

@@ -11,6 +11,7 @@ module River
     attr_accessor :completed_step
     attr_reader :cursors
     attr_accessor :cursors_dirty
+    attr_reader :pending_cursor_steps
     attr_accessor :resume_matched
     attr_reader :resume_step
     attr_accessor :step_name
@@ -24,6 +25,8 @@ module River
       @step_name = nil
 
       @resume_matched = @resume_step.to_s.empty?
+      # Step markers may accompany stale cursors from older clients.
+      @pending_cursor_steps = @resume_matched ? @cursors.keys.sort : []
     end
 
     def register(name)
@@ -37,6 +40,9 @@ module River
     # Internal runtime boundary: attach progress only to attempts that did not
     # complete, matching River Go's persisted metadata format.
     def __capture_resumable_metadata!
+      # Keep missing cursor steps reachable when the worker restores them.
+      return unless @resumable_state.pending_cursor_steps.empty?
+
       if @resumable_state.cursors_dirty
         @metadata_updates[RESUMABLE_CURSOR_METADATA_KEY] = @resumable_state.cursors.empty? ? nil : @resumable_state.cursors.dup
       end
@@ -49,6 +55,9 @@ module River
     # Internal runtime boundary: validate that the recorded resume point still
     # exists in the worker after it has returned.
     def __finish_resumable_work!
+      if (pending = @resumable_state.pending_cursor_steps.first)
+        raise Error, "resumable cursor step #{pending.inspect} not found in worker"
+      end
       if @resumable_state.resume_step && !@resumable_state.resume_matched
         raise Error, "resumable step #{@resumable_state.resume_step.inspect} not found in worker"
       end
@@ -56,12 +65,22 @@ module River
 
     # Immediately checkpoints the current step and cursor progress. Wrap the
     # call in Driver#transaction alongside application writes when an atomic
-    # checkpoint is needed.
+    # checkpoint is needed. When resuming cursor-only progress, reach its saved
+    # cursor step before checkpointing another step.
+    #
+    # Commit the transaction before the step block returns
+    # successfully, and let transaction and commit errors propagate out of it.
+    # A successful block marks the step complete even if an enclosing transaction
+    # later rolls back.
     def resumable_checkpoint(cursor: RESUMABLE_CURSOR_UNSET)
       step_name = @resumable_state.step_name
       raise Error, "resumable step can only be persisted inside a resumable step" unless step_name
       raise Error, "job must be running" unless row.state == JOB_STATE_RUNNING
 
+      if (pending = @resumable_state.pending_cursor_steps.first)
+        raise Error, "resumable checkpoint cannot precede saved cursor step #{pending.inspect}"
+      end
+
       cursors = @resumable_state.cursors.dup
       cursors[step_name] = JSON.parse(JSON.generate(cursor)) unless cursor.equal?(RESUMABLE_CURSOR_UNSET)
       updates = {
@@ -117,6 +136,9 @@ module River
     private def run_resumable_step(name, cursor:, default:)
       raise Error, "resumable steps cannot be nested" if @resumable_state.step_name
       raise ArgumentError, "resumable step name must be non-empty" if name.empty?
+      if !cursor && @resumable_state.pending_cursor_steps.include?(name)
+        raise Error, "resumable cursor step #{name.inspect} requires a cursor step"
+      end
       @resumable_state.register(name)
 
       unless @resumable_state.resume_matched
@@ -132,6 +154,7 @@ module River
       @resumable_state.step_name = name
       begin
         value = (cursor && @resumable_state.cursors.key?(name)) ? @resumable_state.cursors[name] : default
+        @resumable_state.pending_cursor_steps.delete(name) if cursor
         result = cursor ? yield(value) : yield
         @resumable_state.completed_step = name
         if cursor && @resumable_state.cursors.key?(name)

data/lib/worker.rb

@@ -12,8 +12,18 @@ module River
     #
     # 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: [])
+    # Alternatively, pass a kind and a block that receives a River::Job on each
+    # attempt. Block workers use the client's retry and timeout policies.
+    # Supply a worker or a block, not both. Kinds and aliases accept symbols or
+    # strings.
+    def add(kind_or_worker, worker = nil, aliases: [], &block)
+      if block
+        raise ArgumentError, "use a worker or a block, not both" unless worker.nil?
+        raise ArgumentError, "block workers require a string or symbol kind" unless kind_or_worker.is_a?(String) || kind_or_worker.is_a?(Symbol)
+
+        worker = BlockWorker.new(block)
+      end
+
       if worker
         kind = kind_or_worker.to_s
       else
@@ -54,11 +64,29 @@ module River
     def kinds
       @workers.keys.freeze
     end
+
+    # Adapts a registered block to the runtime's worker interface.
+    class BlockWorker
+      def initialize(work_func)
+        @work_func = work_func
+      end
+
+      def work(job)
+        @work_func.call(job)
+      end
+    end
+    private_constant :BlockWorker
   end
 
   # A job being worked, with access to its persisted row and attempt-local
   # metadata changes.
   class Job
+    # Internal runtime hint; persisted state determines whether completion committed.
+    attr_accessor :__completion_attempted
+
+    # Internal snapshot retained only after transactional completion commits.
+    attr_accessor :__completion_snapshot
+
     # Client working this job.
     attr_reader :client
 
@@ -67,6 +95,8 @@ module River
 
     def initialize(client, row)
       @client = client
+      @__completion_attempted = false
+      @__completion_snapshot = nil
       @logger = nil
       @metadata_updates = {}
       @row = row

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

@@ -12,10 +12,10 @@
     "postgresql/main/005_migration_unique_client.up.sql": "b760f487152c7d92102869d46b8a64dc1e2094d5675e690ffbe52a747eee8431",
     "postgresql/main/006_bulk_unique.down.sql": "726483f6e5aa7dd02cdd974cd7bf716973a8d0a97ba6dbc5dc5304aaf54c7ad7",
     "postgresql/main/006_bulk_unique.up.sql": "3b133f7ce4662d3dc8bd4a57628e0e116a300b2635a79315557aa1369849f0fb",
-    "postgresql/main/007_notification_outbox_sqlite_jsonb_and_sql_cleanup.down.sql": "9131aae235187dbdaaa822dab2a475a884e917d9af05e3c98fb95c152eaa769a",
-    "postgresql/main/007_notification_outbox_sqlite_jsonb_and_sql_cleanup.up.sql": "47ec8031b88e69004de2def5bc3109d969f71ee4c33a1e7dac2fb8c9dd19182d",
-    "postgresql/main/008_job_id_autoincrement.down.sql": "0c3750a947d6494db07d56f5d3735a5e49a2cbfa1f7a09771227c31c8147bf70",
-    "postgresql/main/008_job_id_autoincrement.up.sql": "0c3750a947d6494db07d56f5d3735a5e49a2cbfa1f7a09771227c31c8147bf70",
+    "postgresql/main/007_notification_outbox_sqlite_jsonb_and_sql_cleanup.down.sql": "2771765becc5baa0a8af4406cb4d58ea6d3fb0ebdbf72a0c23ccc72da623caeb",
+    "postgresql/main/007_notification_outbox_sqlite_jsonb_and_sql_cleanup.up.sql": "af01339fcb1687de1f768a570b6ad1e51d23300082aed60440f6a662a0e39d85",
+    "postgresql/main/008_job_id_autoincrement.down.sql": "678b3b02deb2f798c3fda3a73c974fc1fe48c6b88688b94f0f7700132b30626f",
+    "postgresql/main/008_job_id_autoincrement.up.sql": "678b3b02deb2f798c3fda3a73c974fc1fe48c6b88688b94f0f7700132b30626f",
     "sqlite/main/001_create_river_migration.down.sql": "34c87dc594bf7520bc3ae69f6f0da8d2d9a472616ab38b37e63d4e3838da06d2",
     "sqlite/main/001_create_river_migration.up.sql": "d15597cb0bb884fb0727d2a29ad8313842708b55fd561a5fe62e37aad5f34298",
     "sqlite/main/002_initial_schema.down.sql": "900508ba08d0ca3c8451eb2854cd9ab837166ef55736393524253b6228438470",
@@ -31,8 +31,7 @@
     "sqlite/main/007_notification_outbox_sqlite_jsonb_and_sql_cleanup.down.sql": "55bffeb528b40dffc0cbec2f22d1463aef37a8b3d7977f83729cc505bb77c745",
     "sqlite/main/007_notification_outbox_sqlite_jsonb_and_sql_cleanup.up.sql": "441a05e1d9aa4f151877ccf725b0b0a86f27013442297d4b621c05676270d0b0",
     "sqlite/main/008_job_id_autoincrement.down.sql": "04871283fe5d4cab4ac70da28d8509aa7ba765994d528c2dcc7ebe0ee596710c",
-    "sqlite/main/008_job_id_autoincrement.up.sql": "049c9bf615f24a326bcc31ddc87b46f76e3de11e3eea3b2b9e1358131b3f3bed"
+    "sqlite/main/008_job_id_autoincrement.up.sql": "3ce6d941f4c434adbd87e69089fa5e99b6047e5b51e611c9845e1d0d3c080e0f"
   },
-  "repository": "river",
-  "revision": "c2c380490d14df8efc28b86fbe7be1cf93930405"
+  "source": "riverdriver/"
 }

data/migration/postgresql/main/007_notification_outbox_sqlite_jsonb_and_sql_cleanup.down.sql

@@ -47,7 +47,7 @@ ALTER TABLE /* TEMPLATE: schema */river_queue
 --
 -- SQLite JSONB conversion rollback.
 --
--- No-op. PostgreSQL already stores River JSON columns as jsonb.
+-- No-op. Postgres already stores River JSON columns as jsonb.
 
 --
 -- Notification outbox rollback.

data/migration/postgresql/main/007_notification_outbox_sqlite_jsonb_and_sql_cleanup.up.sql

@@ -16,7 +16,7 @@ CREATE INDEX river_notification_topic_id_idx ON /* TEMPLATE: schema */river_noti
 --
 -- SQLite JSONB conversion.
 --
--- No-op. PostgreSQL already stores River JSON columns as jsonb.
+-- No-op. Postgres already stores River JSON columns as jsonb.
 
 --
 -- SQL cleanup.

data/migration/postgresql/main/008_job_id_autoincrement.down.sql

@@ -1,3 +1,3 @@
--- No-op. PostgreSQL sequences already prevent automatically generated job IDs
+-- No-op. Postgres sequences already prevent automatically generated job IDs
 -- from being reused.
 SELECT 1;

data/migration/postgresql/main/008_job_id_autoincrement.up.sql

@@ -1,3 +1,3 @@
--- No-op. PostgreSQL sequences already prevent automatically generated job IDs
+-- No-op. Postgres sequences already prevent automatically generated job IDs
 -- from being reused.
 SELECT 1;

data/migration/sqlite/main/008_job_id_autoincrement.up.sql

@@ -1,5 +1,5 @@
 -- Rebuild river_job so automatically generated IDs are never reused after the
--- job holding the largest ID is deleted. Unlike PostgreSQL sequences, SQLite's
+-- job holding the largest ID is deleted. Unlike Postgres sequences, SQLite's
 -- default ROWID allocator may otherwise reuse that deleted ID.
 
 -- Rebuilding river_job would discard schema installed by River Pro. Check

data/sig/client.rbs

@@ -1,5 +1,6 @@
 module River
   MAX_ATTEMPTS_DEFAULT: Integer
+  MAX_ATTEMPTS_LIMIT: Integer
   PRIORITY_DEFAULT: Integer
   QUEUE_DEFAULT: String
 
@@ -14,15 +15,17 @@ module River
 
     def initialize: (_Driver driver, ?config: Config?) -> void
     def __finish_claimed_job: (JobRow, ?Exception?) -> untyped
+    def __insert_with_default_scheduled_at: (jobArgs, InsertOpts, Time?) -> JobInsertResult
     def __perform_job: (Integer, ?allow_scheduled: bool) -> untyped
     def __interrupt_workers: () -> untyped
     def __runtime_healthy?: () -> bool
     def id: () -> String
     def insert: (jobArgs, ?insert_opts: InsertOpts?, ?max_attempts: Integer?,
       ?metadata: Hash[String | Symbol, untyped]?, ?priority: Integer?, ?queue: (String | Symbol)?,
-      ?scheduled_at: Time?, ?state: jobStateInput?, ?tags: Array[String]?, ?unique_opts: UniqueOpts?) -> JobInsertResult
+      ?scheduled_at: Time?, ?state: jobStateInitialInput?, ?tags: Array[String]?, ?unique_opts: UniqueOpts?) -> JobInsertResult
     def insert_many: (Array[jobArgs | InsertManyParams]) -> Array[JobInsertResult]
     def job_cancel: (Integer) -> JobRow
+    def job_complete_tx: (Job) -> JobRow
     def job_delete: (Integer) -> JobRow
     def job_delete_many: (?JobListParams?, ?after: untyped, ?after_id: untyped,
       ?ids: untyped, ?kinds: untyped, ?limit: untyped, ?metadata: untyped, ?priorities: untyped,
@@ -45,6 +48,7 @@ module River
     def queue_remove: (String | Symbol) -> self
     def queue_resume: (String | Symbol) -> bool
     def queue_update: (String | Symbol, metadata: Hash[untyped, untyped]) -> Queue
+    def request_resign: () -> nil
     def start: () -> self
     def started?: () -> bool
     def stop: (?wait: bool) -> self
@@ -54,15 +58,17 @@ module River
 
     DEFAULT_UNIQUE_STATES: Array[jobStateAll]
     EMPTY_INSERT_OPTS: InsertOpts
+    INITIAL_STATES: Array[jobStateInitial]
     REQUIRED_UNIQUE_STATES: Array[jobStateAll]
     TAG_RE: Regexp
 
     private def insert_and_check_unique_job: (Driver::JobInsertParams) -> JobInsertResult
-    private def make_insert_params: (jobArgs, InsertOpts) -> Driver::JobInsertParams
+    private def make_insert_params: (jobArgs, InsertOpts, ?Time?) -> Driver::JobInsertParams
     private def make_unique_key_and_bitmask: (Driver::JobInsertParams, UniqueOpts) -> [String, String]
     private def run_insert_plugins: (Array[Driver::JobInsertParams]) { () -> Array[JobInsertResult] } -> Array[JobInsertResult]
     private def truncate_time: (Time, Integer | Rational) -> Time
     private def uint64_to_int64: (Integer) -> Integer
+    private def validate_insert_state: (String | Symbol) -> jobStateInitial
     private def validate_tags: (Array[String]) -> Array[String]
     private def validate_unique_states: (Array[jobStateInput]) -> Array[jobStateAll]
   end
@@ -76,7 +82,7 @@ module River
 
     def initialize: (jobArgs job, ?insert_opts: InsertOpts?, ?max_attempts: Integer?,
       ?metadata: Hash[String | Symbol, untyped]?, ?priority: Integer?, ?queue: (String | Symbol)?,
-      ?scheduled_at: Time?, ?state: jobStateInput?, ?tags: Array[String]?, ?unique_opts: UniqueOpts?) -> void
+      ?scheduled_at: Time?, ?state: jobStateInitialInput?, ?tags: Array[String]?, ?unique_opts: UniqueOpts?) -> void
     def is_a?: (Class) -> bool
   end