riverqueue 0.13.0 → 0.14.0

data/docs/migrations.md

@@ -1,8 +1,8 @@
 # Schema migrations
 
-River Ruby includes a migration API and the `river` command. Neither needs
-Go installed. The gems bundle byte-for-byte copies of the PostgreSQL and SQLite
-SQL from Go's River drivers, pinned to release v0.48.0 through migration 008;
+River Ruby includes a migration API and the `river` command. The gems bundle
+byte-for-byte copies of River's canonical Postgres and SQLite migration SQL,
+pinned to release v0.48.0 through migration 008;
 only the upstream schema template placeholders are substituted when executing
 them.
 
@@ -24,7 +24,7 @@ bundle exec river migrate-up --database-url sqlite://storage/river.sqlite3
 
 `DATABASE_URL` supplies the URL when `--database-url` is omitted. ActiveRecord
 uses `sqlite3:` URLs instead of Sequel's `sqlite:` URLs. To target an existing
-PostgreSQL schema, pass `--schema jobs`; otherwise the connection's current
+Postgres schema, pass `--schema jobs`; otherwise the connection's current
 schema is used. Schema names must be simple SQL identifiers. SQLite always
 uses its main schema.
 
@@ -52,22 +52,22 @@ migrator.migrate(dry_run: true, target: 8)
 migrator.migrate(direction: :down) # One version; no interactive confirmation.
 ```
 
-The API accepts either driver and optionally `schema:` for PostgreSQL. `migrate`
+The API accepts either driver and optionally `schema:` for Postgres. `migrate`
 returns the migration records applied (or planned in dry-run mode), with their
 version, name, and original up/down SQL. Each version's SQL and history update
 commit in their own transaction. A failing version rolls back while earlier
 versions remain committed, so rerunning resumes safely. Do not wrap the migrator
-in an application transaction: some PostgreSQL changes require a real commit
+in an application transaction: some Postgres changes require a real commit
 before the next version can run.
 
 An up migration targeting an already-applied version does nothing, even when
 newer migrations are pending.
 
-## Go compatibility and Pro
+## Compatibility and Pro
 
-The migrator reads and writes Go's `river_migration` history, including the
-legacy pre-version-5 format. Either language can continue from the other's
-applied versions. Unknown newer versions and gaps in history cause an error
+The migrator reads and writes the `river_migration` history shared by all River
+clients, including the legacy pre-version-5 format. Any River client can
+continue from versions applied by another. Unknown newer versions and gaps in history cause an error
 rather than guessing what SQL to run. It does not baseline an existing schema
 that has no River migration history.
 
@@ -75,7 +75,7 @@ Pro SQL is distributed only inside `riverqueue-pro`, not the public core gem.
 SQLite main migration 008 rebuilds `river_job` with `AUTOINCREMENT` so deleted
 job IDs are not reused. Its upgrade and downgrade refuse to run while Pro's
 workflow/sequence schema is installed; coordinate that upgrade with Pro before
-running it on an existing Pro database. PostgreSQL migration 008 is a no-op.
+running it on an existing Pro database. Postgres migration 008 is a no-op.
 
 Migrate main first, then Pro:
 
@@ -92,14 +92,14 @@ River::Pro::Migrator.new(driver).migrate
 ```
 
 Remove other migration lines before downgrading main. Run only one migration
-process at a time across languages. Ruby migrators take a PostgreSQL advisory
+process at a time across languages. Ruby migrators take a Postgres advisory
 lock per schema; SQLite takes a write lock per version and checks for concurrent
-history changes. These are not shared locks with Go's migration runner.
+history changes. These locks are not shared with other River clients' migration runners.
 
 ## Updating the bundled SQL
 
 `migration/manifest.json` records each canonical file's SHA-256. From `ruby/`,
-synchronize or verify against the Go migrations in this same checkout:
+synchronize or verify against the canonical migrations in this same checkout:
 
 ```sh
 ruby scripts/sync_migrations.rb
@@ -111,8 +111,8 @@ CI uses the same working-tree comparison; no separate checkout is needed.
 
 Pro migrations have their own manifest and sync script in the private
 `riverqueue-ruby-pro` repository. Run that repository's `make verify` against
-the Go Pro checkout; the public sync script handles only the main migrations.
+the River Pro checkout; the public sync script handles only the main migrations.
 
 Review the upstream changes and run the complete test matrix before publishing.
 Do not edit the copied SQL independently. Upstream changes are bundled in gem
-releases; users do not need the Go repositories or network access at runtime.
+releases; users do not need the upstream repositories or network access at runtime.

data/docs/testing.md

@@ -1,6 +1,6 @@
 # Testing River jobs
 
-Testing helpers ship in `riverqueue`. They use your real PostgreSQL or SQLite
+Testing helpers ship in `riverqueue`. They use your real Postgres or SQLite
 database through either driver; there is no fake queue, global testing mode,
 implicit migration, or automatic cleanup. Require them explicitly:
 

data/lib/client.rb

@@ -49,6 +49,13 @@ module River
       @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
@@ -77,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
@@ -106,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
@@ -134,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:
     #
@@ -182,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
@@ -310,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
@@ -379,7 +431,7 @@ module River
       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.
@@ -424,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