riverqueue 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c22dfdcd40a71eaf7e3f9f74351b795957b2a23c7a51d5e302c7dd6d046ce3e8
-  data.tar.gz: 495748ff5de7b982d2d18c8ed6670865e5452c5e8198a457428e53c2af5ecf76
+  metadata.gz: 1ce8622d0f151131d632d673e694e8ea90ded0502ba912274c7d044076063ee9
+  data.tar.gz: 1df7e4f2f10a3cfe36d3d08793a38b5400bf12dd32c3db3d3fd248184523d961
 SHA512:
-  metadata.gz: 1707b4db9e48540d168af6cdd89dc98e78db8101e4cfaa1a95ede93a1e4d1bd5ab28b13e94f6ab3c106f5673dc30f4092b83d299b98a257c23384ffeb2ba170d
-  data.tar.gz: cffa8f11fda5a7b003413ed3dab643ce44168987dc2afe2fb0b6d5dccafcfbfe0e6a88264262502018e53a38f6f3c2b1a460fef8ccdfb7ce0c9c37999bfe3514
+  metadata.gz: c09ee3fefb3b0d9bdb4bd969761117470a84b7bcfa1278819446471c53348356ddffea3fa424d0cf086f57b1134ec49c1d470d03314286d21d50c9d1670568a4
+  data.tar.gz: a79a913f6f455f8a6a14e989ae72c415adb39248d97c1457b2cfd077b74ce41676e1f3bc79239d4a33d2653485074de7a8a6fd414699fec2e30b97c1fedb3d11

data/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-10-26
+
+### Added
+
+- Receive Postgres and SQLite notifications for insertions, queue controls, cancellation, and leadership handoffs, with reconnect recovery and a `poll_only` option. [PR #1496](https://github.com/riverqueue/river/pull/1496).
+- Add `Client#request_resign` to request that the maintenance leader relinquish leadership after the caller's transaction commits. [PR #1496](https://github.com/riverqueue/river/pull/1496).
+- Allow `River::Workers#add` to register a kind and a work block, using the client's default retry and timeout policies. [PR #1486](https://github.com/riverqueue/river/pull/1486).
+- Added `Client#job_complete_tx(job)` to complete a running job in the caller's Active Record or Sequel transaction, including pending metadata and output. An active transaction on the driver's connection is required. Completion rolls back with the transaction; once committed, it takes precedence over subsequent worker errors and emits a completion event when the worker finishes. [PR #1490](https://github.com/riverqueue/river/pull/1490).
+
+### Changed
+
+- River operations called inside an open Active Record or Sequel transaction now run in that transaction and open no savepoint of their own. If an operation raises, roll back the transaction, or wrap the call in your own savepoint to recover and continue. A `driver.rollback_exception` raised inside `Driver#transaction` now reaches the enclosing transaction block, as a rollback raised in your own code would. Before, it rolled back only River's savepoint. Set `RIVER_USE_LEGACY_SUBTRANSACTIONS=1` (or `true`) to restore the savepoints. This temporary fallback will be removed in a future release. [PR #1544](https://github.com/riverqueue/river/pull/1544).
+- `work_end(job, error)` hooks now return the attempt's error, matching Go. Return the incoming error to preserve it, a replacement exception to change it, or `nil` to clear a failure. The return value feeds the next hook in registration order. Existing observing hooks must explicitly return `error`. End hooks are skipped if `work_begin` raises or the worker raises an exception outside `StandardError`. [PR #1520](https://github.com/riverqueue/river/pull/1520).
+
+### Fixed
+
+- The scheduler no longer opens a savepoint for each due job to catch unique key conflicts. A pass that made more than 64 jobs available overflowed the Postgres subtransaction cache, which can slow queries across the server. The scheduler now finds conflicts with one statement on Postgres and checks before each write on SQLite. Conflicting jobs are still discarded with `unique_key_conflict: scheduler_discarded` metadata. On Postgres, the scheduler now waits for a due job that another transaction has locked, instead of skipping it. [PR #1544](https://github.com/riverqueue/river/pull/1544).
+- Default periodic jobs to their occurrence time, preserving constructor and argument-level schedules. [PR #1537](https://github.com/riverqueue/river/pull/1537).
+- Fail retries that omit a saved cursor-only step, while preserving their checkpoints for recovery. Jobs with an existing step marker retain their behavior, including legacy stale cursor entries. [PR #1534](https://github.com/riverqueue/river/pull/1534).
+- Support large SQLite metadata updates without reaching the expression-depth limit, preserving top-level replacement and JSON null values. [PR #1533](https://github.com/riverqueue/river/pull/1533).
+- A `River::Config` without an explicit `id:` generates its default client ID on first use in each process, so clients built before a fork (as with preloading Puma, Unicorn, or Pitchfork servers) no longer share one ID across forked workers. Explicit IDs are unchanged, and `Config#with` copies share the original's ID. [PR #1498](https://github.com/riverqueue/river/pull/1498).
+- Inserting a job stores its encoded args as given instead of decoding and re-encoding them in Ruby, which rewrote numbers like `1.10` as `1.1` and `1e3` as `1000.0` and rounded digits beyond `Float` precision. Postgres applies its usual `jsonb` normalization, and SQLite keeps the encoded bytes, matching River's Go drivers. Affects Active Record on Postgres and SQLite, and Sequel on SQLite. [PR #1503](https://github.com/riverqueue/river/pull/1503).
+- Wake workers when scheduled jobs become available or jobs are manually retried, including workers in other clients. [PR #1496](https://github.com/riverqueue/river/pull/1496).
+- Honor cancellations that arrive between claiming a job and starting its worker. [PR #1496](https://github.com/riverqueue/river/pull/1496).
+- Preserve worker wakeups that arrive between a fetch and the producer going to sleep. [PR #1496](https://github.com/riverqueue/river/pull/1496).
+
 ## [0.13.0] - 2026-10-08
 
 ### Added
@@ -17,10 +43,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Ruby is now developed in the main [River repository](https://github.com/riverqueue/river/tree/master/ruby). Gem names and require paths are unchanged. The four public gems (`riverqueue`, `riverqueue-activerecord`, `riverqueue-sequel`, and `riverqueue-rails`) are released together. [PR #1463](https://github.com/riverqueue/river/pull/1463).
-- **Breaking:** Job insertion accepts only `available`, `pending`, and `scheduled` states. `running`, `retryable`, and terminal states are rejected, including when set by insertion hooks. [PR #1463](https://github.com/riverqueue/river/pull/1463).
-- **Breaking:** Insertion rejects queue names containing characters other than ASCII letters, digits, underscores, hyphens, colons, or periods. Nonzero `UniqueOpts#by_period` values must be at least one second. [PR #1463](https://github.com/riverqueue/river/pull/1463).
-- **Breaking:** Attempt counts must be between 0 and 32,767, and `max_attempts` must be between 1 and 32,767. These bounds also apply on SQLite. `job_retry` raises `ArgumentError` when another attempt would exceed the limit. [PR #1463](https://github.com/riverqueue/river/pull/1463).
-- **Breaking:** Job and queue metadata updates require a Hash; JSON-encoded strings are no longer accepted. Pass an empty Hash to clear metadata. Updates to `attempted_by` require string entries. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- Job insertion accepts only `available`, `pending`, and `scheduled` states. `running`, `retryable`, and terminal states are rejected, including when set by insertion hooks. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- Insertion rejects queue names containing characters other than ASCII letters, digits, underscores, hyphens, colons, or periods. Nonzero `UniqueOpts#by_period` values must be at least one second. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- Attempt counts must be between 0 and 32,767, and `max_attempts` must be between 1 and 32,767. These bounds also apply on SQLite. `job_retry` raises `ArgumentError` when another attempt would exceed the limit. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- Job and queue metadata updates require a Hash; JSON-encoded strings are no longer accepted. Pass an empty Hash to clear metadata. Updates to `attempted_by` require string entries. [PR #1463](https://github.com/riverqueue/river/pull/1463).
 
 ### Fixed
 
@@ -36,7 +62,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Cancellation wins atomically over discarded attempts and other state transitions, including the last attempt or a worker that disables retries. [PR #1463](https://github.com/riverqueue/river/pull/1463).
 - Stuck-job rescue falls back to the default retry policy per job when an application policy fails or returns an invalid time, allowing recovery and cleanup to continue. [PR #1463](https://github.com/riverqueue/river/pull/1463).
 - Clients without consumer queues run configured periodic jobs and maintenance services. Adding periodic jobs starts maintenance when needed; registration is rejected when leader election is disabled. [PR #1463](https://github.com/riverqueue/river/pull/1463).
-- Bulk deletion excludes running jobs before applying its limit and locks eligible PostgreSQL rows so concurrent retries cannot cause deletion of jobs that no longer match the filters. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- Bulk deletion excludes running jobs before applying its limit and locks eligible Postgres rows so concurrent retries cannot cause deletion of jobs that no longer match the filters. [PR #1463](https://github.com/riverqueue/river/pull/1463).
 - Stuck-job rescue respects longer or disabled client and worker timeouts and scans past protected attempts without consuming the rescue limit. [PR #1463](https://github.com/riverqueue/river/pull/1463).
 - Snoozing and rescue tolerate JSON counters that overflow SQLite's floating-point representation. [PR #1463](https://github.com/riverqueue/river/pull/1463).
 - Snoozing tolerates nonnumeric metadata counters instead of failing on booleans or collections. Ruby-specific recovery cases are tested independently of the shared Go fixtures. [PR #1463](https://github.com/riverqueue/river/pull/1463).
@@ -47,21 +73,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Custom maintenance service failures are logged without blocking other services, stuck-job rescue, or cleanup. [PR #1463](https://github.com/riverqueue/river/pull/1463).
 - Job updates reject non-object metadata before writing to the database, preserving the existing job when invalid metadata is supplied. [PR #1463](https://github.com/riverqueue/river/pull/1463).
 - Job completion atomically checks for cancellation so a concurrent cancellation cannot be overwritten by completion, including when finalization hooks are configured. [PR #1463](https://github.com/riverqueue/river/pull/1463).
-- Job updates reject nonpositive attempt limits consistently on PostgreSQL and SQLite. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- Job updates reject nonpositive attempt limits consistently on Postgres and SQLite. [PR #1463](https://github.com/riverqueue/river/pull/1463).
 - Job lifecycle events report worker execution and completion durations separately using a monotonic clock. [PR #1463](https://github.com/riverqueue/river/pull/1463).
 - Finalization hooks that delete jobs honor concurrent cancellation and record the cancelled attempt instead of deleting it. [PR #1463](https://github.com/riverqueue/river/pull/1463).
 - Queue metadata writes and job metadata merges reject non-object values before changing persisted data. Job updates also reject non-string worker IDs in attempt histories. [PR #1463](https://github.com/riverqueue/river/pull/1463).
 - Unique inserts with `exclude_kind` preserve the existing job's kind when a different kind conflicts, on both databases and through both drivers. [PR #1463](https://github.com/riverqueue/river/pull/1463).
 - Retrying, snoozing, and interrupting jobs preserve the original queue-wait duration in lifecycle events. [PR #1463](https://github.com/riverqueue/river/pull/1463).
 - Invalid rescue counters no longer prevent other stuck jobs in the batch from being rescued. [PR #1463](https://github.com/riverqueue/river/pull/1463).
-- SQLite retains only the newest 100 worker IDs when claiming a job, matching PostgreSQL. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- SQLite retains only the newest 100 worker IDs when claiming a job, matching Postgres. [PR #1463](https://github.com/riverqueue/river/pull/1463).
 - Attempt-error serialization supports frozen timestamps and preserves the caller's timezone. [PR #1463](https://github.com/riverqueue/river/pull/1463).
 
 ## [0.12.0] - 2026-10-01
 
 ### Added
 
-- Add a full Ruby client for River with Go-compatible job insertion and execution on PostgreSQL, SQLite, and YugabyteDB through ActiveRecord or Sequel. Includes workers, retries, cancellation, periodic and resumable jobs, job-persisted logging, job administration, migration and worker CLIs, and testing helpers. Rails and Active Job integration is available through `riverqueue-rails`, with workflows, batches, sequences, concurrency controls, and other advanced features in the separately distributed `riverqueue-pro` gem. [PR #70](https://github.com/riverqueue/riverqueue-ruby/pull/70).
+- Add a full Ruby client for River with Go-compatible job insertion and execution on Postgres, SQLite, and YugabyteDB through ActiveRecord or Sequel. Includes workers, retries, cancellation, periodic and resumable jobs, job-persisted logging, job administration, migration and worker CLIs, and testing helpers. Rails and Active Job integration is available through `riverqueue-rails`, with workflows, batches, sequences, concurrency controls, and other advanced features in the separately distributed `riverqueue-pro` gem. [PR #70](https://github.com/riverqueue/riverqueue-ruby/pull/70).
 
 ## [0.11.0] - 2026-09-02
 
@@ -71,7 +97,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- Stop pulling in `pg` as a hard dependency of either driver. Applications now select their database adapter by including `pg` for PostgreSQL or `sqlite3` for SQLite. [PR #67](https://github.com/riverqueue/riverqueue-ruby/pull/67).
+- Stop pulling in `pg` as a hard dependency of either driver. Applications now select their database adapter by including `pg` for Postgres or `sqlite3` for SQLite. [PR #67](https://github.com/riverqueue/riverqueue-ruby/pull/67).
 
 ## [0.10.1] - 2026-04-09
 
@@ -130,7 +156,7 @@ Users should upgrade backends to River v0.12.0 before upgrading this library in
 
   This updated implementation is significantly faster due to the removal of advisory locks in favor of an index-backed uniqueness system, while allowing some flexibility in which job states are considered. However, not all states may be removed from consideration when using the `by_state` option; pending, scheduled, available, and running states are required whenever customizing this list. [PR #32](https://github.com/riverqueue/riverqueue-ruby/pull/32).
 
-- Update REXML dependency. [PR #28](https://github.com/riverqueue/riverqueue-ruby/pull/36).
+- Update REXML dependency. [PR #36](https://github.com/riverqueue/riverqueue-ruby/pull/36).
 
 ## [0.7.0] - 2024-08-30
 
@@ -155,7 +181,7 @@ Users should upgrade backends to River v0.12.0 before upgrading this library in
 ### Changed
 
 - Tag format is now checked on insert. Tags should be no more than 255 characters and match the regex `/\A[\w][\w\-]+[\w]\z/`. [PR #22](https://github.com/riverqueue/riverqueue-ruby/pull/22).
-- Returned jobs now have a `metadata` property. [PR #21](https://github.com/riverqueue/riverqueue-ruby/pull/22).
+- Returned jobs now have a `metadata` property. [PR #22](https://github.com/riverqueue/riverqueue-ruby/pull/22).
 
 ## [0.4.0] - 2024-04-28
 

data/README.md

@@ -1,22 +1,91 @@
 # River for Ruby
 
-A PostgreSQL and SQLite job queue that shares River's schema with the Go, Rust,
-and JavaScript clients. Includes Active Record and Sequel drivers, plus Rails
-and Active Job integration.
+River is a fast, reliable background job system backed by Postgres or SQLite. The Ruby client inserts and works jobs using the same database schema and job protocol as River's other languages. It includes Active Record and Sequel drivers, plus Rails and Active Job integration.
 
-- [Usage and configuration](docs/README.md)
-- [Development and releases](docs/development.md)
-- [Conformance coverage](docs/conformance.md)
-- [Migrations](docs/migrations.md)
+## Installation
 
-From the repository root:
+Ruby 3.2 or newer is required. Add a River driver and its database adapter to your application's `Gemfile`; the driver brings in the core `riverqueue` gem:
+
+```ruby
+gem "riverqueue-sequel"
+gem "pg"
+```
+
+Use `riverqueue-activerecord` for Active Record, or `sqlite3` instead of `pg` for SQLite. Install the gems with `bundle install`. Rails applications can use [`riverqueue-rails`](rails/riverqueue-rails/README.md) to configure River as their Active Job backend.
+
+## Quick start
+
+Set `DATABASE_URL` to an existing application database and apply River's migrations before inserting or working jobs:
 
 ```sh
-make -C ruby install
-createdb river_test
-RIVER_REQUIRE_DATABASES=1 make test/ruby
-make lint/ruby typecheck/ruby
+export DATABASE_URL=postgres://localhost/my_app
+bundle exec river migrate-up
+```
+
+Define job arguments and a worker with the same stable kind, register the worker, and insert a job. Save this as `worker.rb`:
+
+```ruby
+require "riverqueue-sequel"
+
+class SendEmailArgs
+  def initialize(address:)
+    @address = address
+  end
+
+  def kind = "send_email"
+  def to_json = JSON.generate(address: @address)
+end
+
+class SendEmailWorker
+  def self.kind = "send_email"
+
+  def work(job)
+    puts "Sending email to #{job.args.fetch("address")}"
+    job.output = {delivered: true}
+  end
+end
+
+db = Sequel.connect(ENV.fetch("DATABASE_URL"), max_connections: 12)
+client = River::Client.new(
+  River::Driver::Sequel.new(db),
+  config: River::Config.new(
+    queues: {default: 10},
+    workers: River::Workers.new.add(SendEmailWorker)
+  )
+)
+
+begin
+  client.start
+  result = client.insert(SendEmailArgs.new(address: "person@example.com"))
+  puts "Inserted job #{result.job.id}; press Ctrl-C to stop"
+  sleep
+rescue Interrupt
+  # Stop fetching and wait for active jobs before closing the database pool.
+ensure
+  client.stop
+  db.disconnect
+end
 ```
 
-Ruby 3.2 or later is required. `make test/ruby/conformance` runs only the
-Go-generated fixture checks and needs no PostgreSQL server.
+Run `bundle exec ruby worker.rb`. Replace the worker body with your mail service. Job arguments implement `kind` and `to_json`; workers read decoded JSON keys as strings. Services sharing a job must agree on its kind and JSON fields. For SQLite and alternate Postgres schemas, see [migrations](docs/migrations.md).
+
+A client without configured queues can insert jobs without starting worker threads. Applications own their database pools and should close them only after stopping River.
+
+## Transactions and other features
+
+Inserts join a transaction opened on the same Sequel database or Active Record connection, so jobs commit or roll back with the application writes that caused them. See [transactional enqueueing](docs/README.md#transactional-enqueueing) for examples.
+
+- [Bulk insertion](docs/README.md#bulk-insertion), [scheduled jobs](docs/README.md#scheduled-jobs), and [unique jobs](docs/README.md#unique-jobs).
+- [Retries](docs/README.md#job-retries), [cancellation](docs/README.md#cancelling-jobs), and [snoozing](docs/README.md#snoozing-jobs).
+- [Multiple queues](docs/README.md#multiple-queues), [periodic jobs](docs/README.md#periodic-jobs), and [resumable jobs](docs/README.md#resumable-jobs).
+- [Event subscriptions](docs/README.md#subscriptions) and [job administration](docs/README.md#job-administration).
+- [Graceful stopping](docs/README.md#stopping-gracefully) and a foreground [worker command](docs/workers.md).
+- [Testing helpers](docs/testing.md) for application jobs and workers.
+
+## Documentation
+
+See the [usage and configuration guide](docs/README.md), [migration guide](docs/migrations.md), and [Rails and Active Job integration](rails/riverqueue-rails/README.md). The [Sidekiq migration guide](docs/migrating_from_sidekiq.md) covers moving an existing application.
+
+## Development
+
+See [developing River for Ruby](docs/development.md).

data/docs/README.md

@@ -1,6 +1,6 @@
 # River client for Ruby [![Build Status](https://github.com/riverqueue/river/actions/workflows/ruby.yaml/badge.svg)](https://github.com/riverqueue/river/actions/workflows/ruby.yaml) [![Gem Version](https://badge.fury.io/rb/riverqueue.svg)](https://badge.fury.io/rb/riverqueue)
 
-A Ruby client for [River](https://github.com/riverqueue/river), packaged in the [`riverqueue` gem](https://rubygems.org/gems/riverqueue). It inserts and works jobs using River's canonical database schema and state machine, so Ruby and Go clients can safely share a River database. Separate queues are recommended when each language recognizes different job kinds.
+A Ruby client for [River](https://github.com/riverqueue/river), packaged in the [`riverqueue` gem](https://rubygems.org/gems/riverqueue). It inserts and works jobs using River's canonical database schema and state machine, so Ruby and River clients in other languages can safely share a River database. Separate queues are recommended when each language recognizes different job kinds.
 
 ## Installation
 
@@ -26,9 +26,9 @@ its uniqueness and notification capabilities.
 ## Schema and migrations
 
 Run migrations before inserting jobs or starting workers. The bundled `river`
-command uses Go's canonical PostgreSQL and SQLite migrations; no Go installation
-is needed. After installing a River driver and its database adapter, create your
-application's PostgreSQL database and run:
+command uses River's canonical Postgres and SQLite migrations, bundled with the
+gem. After installing a River driver and its database adapter, create your
+application's Postgres database and run:
 
 ```sh
 export DATABASE_URL=postgres://localhost/my_app
@@ -39,8 +39,8 @@ bundle exec river migrate-up
 ```
 
 `migrate-up` applies all pending migrations and is safe to rerun: already-applied
-versions are skipped, including migrations applied by Go. `--dry-run` previews
-the plan without changing the database. Pass `--database-url URL` to override
+versions are skipped, including migrations applied by other River clients.
+`--dry-run` previews the plan without changing the database. Pass `--database-url URL` to override
 `DATABASE_URL`.
 
 For SQLite, ensure the parent directory exists, then use a SQLite URL:
@@ -57,7 +57,7 @@ both are in your bundle.
 For River Pro, install `riverqueue-pro`, apply the main migrations above, then
 run `bundle exec river migrate-up --line pro` against the same database.
 
-See the [migration guide](migrations.md) for the Ruby API, PostgreSQL schemas,
+See the [migration guide](migrations.md) for the Ruby API, Postgres schemas,
 target versions, downgrade precautions, and existing SQLite Pro installations.
 Test schema snapshots under `spec/support` are test-only and must not be used
 to provision production databases.
@@ -110,12 +110,37 @@ Job arguments must respond to `#kind` and `#to_json`. They may also return defau
 Use strings for `#kind` definitions, and symbols for identifiers such as queues,
 states, periodic job IDs, and resumable step names. Both forms are accepted.
 Persisted job attributes and JSON object keys remain strings, preserving
-compatibility with Go clients.
+compatibility with River clients in other languages.
 Examples omit parentheses on simple calls and `do...end` blocks, retaining them
 for nested expressions and `{ ... }` blocks where they make binding clear.
 
 ## Core features
 
+### Block workers
+
+Pass a kind and a block to `Workers#add` to define a worker inline:
+
+```ruby
+workers = River::Workers.new
+workers.add(:message) do |job|
+  puts "Message: #{job.args.fetch("message")}"
+end
+
+# With client configured to use this registry and the ruby queue:
+client.insert River::JobArgsHash.new(:message, message: "Hello!"), queue: :ruby
+```
+
+Pass this registry as `workers:` in `River::Config`. The kind accepts a string
+or symbol and must match the inserted job's kind. The block receives a
+`River::Job` and uses the client's retry and timeout policies. Returning normally
+completes the job; the block's return value is ignored. Raise exceptions to fail,
+cancel, or snooze work as with a worker class. Optionally use `job.output =` to
+persist a result. Aliases are supported through `aliases:` as for other workers.
+Supply a worker or a block, not both. Existing procs or methods can be passed as
+the block with `&`.
+The same block may run concurrently for multiple jobs, so any captured mutable
+state must be safe to share across threads.
+
 ### [Accessing the client from workers](https://riverqueue.com/docs/context-client)
 
 Every running `River::Job` exposes the client that claimed it. Workers can use
@@ -159,8 +184,8 @@ For simple jobs, `River::JobArgsHash.new(:kind, hash)` avoids defining an argume
 
 ### [Transactional enqueueing](https://riverqueue.com/docs/transactional-enqueueing)
 
-Insertion hooks and middleware execute inside the insertion transaction. If
-they raise, their database writes and the enqueue roll back together. PostgreSQL
+Insertion hooks and middleware execute inside the insertion transaction, so
+their database writes and the enqueue commit or roll back together. Postgres
 insert notifications are delivered only when the surrounding transaction commits.
 
 Inserts automatically join a transaction opened through the same Active Record connection or Sequel database object. A rollback also rolls back the job:
@@ -181,6 +206,62 @@ end
 
 The equivalent works inside `ActiveRecord::Base.transaction` with the Active Record driver.
 
+River calls inside an open transaction run in that transaction and open no
+savepoint of their own. If a River call raises, it may leave partial changes,
+so roll back the transaction. To recover from the error and continue the
+transaction, wrap the call in your own savepoint, such as
+`DB.transaction(savepoint: true)` or
+`ApplicationRecord.transaction(requires_new: true)`.
+
+### Transactional completion
+
+Call `job.client.job_complete_tx(job)` inside a transaction to commit application
+writes and job completion together (the equivalent of Go's `JobCompleteTx`):
+
+```ruby
+class FulfillOrderWorker
+  def work(job)
+    DB.transaction do
+      DB[:orders].where(id: job.args.fetch("order_id")).update(fulfilled: true)
+      job.output = {fulfilled: true}
+      job.client.job_complete_tx(job)
+    end
+  end
+end
+```
+
+With Active Record 7.2 or later, use it inside an `ApplicationRecord.transaction` block. As
+with insertion, the transaction must use the driver's connection on the same
+thread. No explicit transaction argument is needed. Calling `job_complete_tx`
+without an active transaction on that connection raises `River::Error` without
+changing the job.
+
+Sequel 5.20 or later is required so transaction callbacks respect savepoints.
+
+`job_complete_tx` accepts the running `River::Job` passed to the worker and returns
+an updated `River::JobRow`, leaving the original job unchanged. Set output and
+metadata before calling it so they're included in the transaction. A missing
+job raises `River::NotFoundError`; a pending cancellation raises
+`River::JobCancelError`, allowing the transaction to roll back.
+The supplied job must still belong to the current attempt; a stale worker cannot
+complete a replacement attempt.
+Metadata added afterward, including persisted logs, is saved separately when
+the worker finishes, provided the completed attempt has not been retried.
+
+Make completion the last operation in the transaction and let the transaction
+commit before returning from `work`. Propagate errors that roll back the
+transaction so River retries the job. If you swallow a rollback and return
+successfully, River completes the job normally. Once completion commits, later
+worker errors cannot retry or cancel the job. River emits `:job_completed` when
+the worker finishes, and skips its usual finalization hooks for the already
+completed job.
+If the completed row is deleted before the worker finishes, River emits the
+completion event using the snapshot retained when the transaction committed.
+
+If the job is manually retried before the original worker finishes, that worker
+leaves the replacement attempt untouched and does not emit a completion event
+for it.
+
 ### [Bulk insertion](https://riverqueue.com/docs/inserting-many-jobs)
 
 `#insert_many` inserts a batch atomically and returns one `River::JobInsertResult` per input. Use `River::InsertManyParams` when jobs need different options:
@@ -230,7 +311,7 @@ order affect the hash even when the decoded JSON is equivalent.
 
 ### [Reliable execution and stuck jobs](https://riverqueue.com/docs/reliable-workers)
 
-Claims and state transitions are atomic in the database. If a process disappears while working, the elected maintenance client checks for stale running jobs after an hour, retrying or discarding them according to their attempt count. Rescue respects longer client and worker timeouts; disabling a job's timeout also disables automatic timeout-based rescue for it. Cancellation requests still take precedence. Keep worker registrations and timeout configuration consistent across maintenance clients. `attempted_by`, attempt errors, and final state remain in the canonical River row for inspection by Ruby, Go, or River UI.
+Claims and state transitions are atomic in the database. If a process disappears while working, the elected maintenance client checks for stale running jobs after an hour, retrying or discarding them according to their attempt count. Rescue respects longer client and worker timeouts; disabling a job's timeout also disables automatic timeout-based rescue for it. Cancellation requests still take precedence. Keep worker registrations and timeout configuration consistent across maintenance clients. `attempted_by`, attempt errors, and final state remain in the canonical River row for inspection by any River client or River UI.
 
 ### [Job retries](https://riverqueue.com/docs/job-retries)
 
@@ -405,9 +486,9 @@ cleanup = River::PeriodicJob.new(
 a runtime dependency of the River gem. The timezone defaults explicitly to UTC;
 set `timezone:` or use a `CRON_TZ=` / `TZ=` prefix, which takes precedence.
 Five-field cron, optional seconds, and aliases such as `@daily` use Fugit's
-syntax; `?` is also accepted as a wildcard. `@every 1h30m` uses Go duration
-syntax, rounded down to whole seconds with a one-second minimum. Unlike
-`PeriodicInterval`, these intervals align to whole-second boundaries.
+syntax; `?` is also accepted as a wildcard. `@every` accepts durations such
+as `1h30m`, built from `ns`, `us`, `ms`, `s`, `m`, and `h` units, rounded down
+to whole seconds with a one-second minimum. Unlike `PeriodicInterval`, these intervals align to whole-second boundaries.
 Results are UTC `Time` objects. Nonexistent spring-forward times are skipped;
 both occurrences of a repeated fall-back time are scheduled. See
 [conformance differences](conformance.md) before sharing schedules across
@@ -419,7 +500,7 @@ a periodic job. This stores the scheduled job immediately in the database.
 
 ### [Resumable jobs](https://riverqueue.com/docs/resumable-jobs)
 
-Long jobs can checkpoint idempotent steps and cursor progress. On retry, River skips completed steps and resumes a cursor step from its last recorded value using the same metadata format as Go.
+Long jobs can checkpoint idempotent steps and cursor progress. On retry, River skips completed steps and resumes a cursor step from its last recorded value using River's shared metadata format.
 
 ```ruby
 def work(job)
@@ -481,7 +562,7 @@ end
 ### Job-persisted logging
 
 Add `River::JobPersistedLogging::Plugin` to save worker logs with each job attempt,
-using the same `metadata["river:log"]` format as Go's `riverlog` and River UI. This
+using the shared `metadata["river:log"]` format that River UI displays. This
 is a core feature; it does not require Pro or additional migrations.
 
 ```ruby
@@ -557,7 +638,7 @@ A plugin may implement any combination of these methods:
 | Hook       | `insert_begin(params)`           | Before each job is inserted; `params` may be modified.                                       |
 | Hook       | `insert_end(result)`             | After each job is inserted.                                                                  |
 | Hook       | `work_begin(job)`                | After a job is claimed, immediately before its worker runs.                                  |
-| Hook       | `work_end(job, error)`           | After the worker returns or raises; `error` is `nil` on success.                             |
+| Hook       | `work_end(job, error)`           | After the worker returns or raises a `StandardError`; returns the attempt's error or `nil`. |
 | Hook       | `job_finalize(job, state)`       | Before successful finalization; returning `:delete` deletes the job instead of retaining it. |
 | Middleware | `insert_many(params, operation)` | Around one insertion call; `params` is an array even for `Client#insert`.                    |
 | Middleware | `work(job, operation)`           | Around the work hooks and worker for one claimed job.                                        |
@@ -584,10 +665,33 @@ end
 config = River::Config.new(plugins: [AuditPlugin.new, TimingPlugin.new])
 ```
 
-Plugins earlier in the list are the outermost wrappers. Begin callbacks run in
-configuration order, while `insert_end` callbacks run in reverse order. In
-effect, work execution is nested as: middleware before, `work_begin`, worker,
-`work_end`, middleware after.
+Plugins earlier in the list are the outermost wrappers. Begin callbacks and
+`work_end` callbacks run in configuration order, while `insert_end` callbacks
+run in reverse order. In effect, work execution is nested as: middleware before,
+`work_begin`, worker, `work_end`, middleware after.
+
+Each `work_end(job, error)` receives `nil` on success or the worker's exception
+on failure. Return `error` to preserve that outcome, a different exception to
+replace it, or `nil` to clear a failure. Each subsequent end hook receives the
+previous hook's return value. After all end hooks run, River raises the final
+error through the middleware, or completes the operation if it is `nil`.
+Returning `River.job_cancel(...)` or `River.job_snooze(...)` selects the
+corresponding cancellation or snooze behavior.
+
+An observing hook must explicitly return its incoming error:
+
+```ruby
+def work_end(job, error)
+  Metrics.record_attempt(job.kind, error: error)
+  error
+end
+```
+
+If a `work_begin` hook raises, River skips the worker and all end hooks. If an
+end hook raises instead of returning an error, it stops the end-hook chain and
+propagates that exception through the middleware. Fatal exceptions outside
+`StandardError` also bypass end hooks. Use middleware with `ensure` for cleanup
+that must run when hooks or work raise.
 
 ### [Subscriptions](https://riverqueue.com/docs/subscriptions)
 
@@ -687,10 +791,32 @@ A custom service implements `run(client, driver, now)` and runs only while this
 Service errors are logged without interrupting other services, stuck-job rescue,
 or cleanup. A failed service is retried on the next scheduled maintenance pass.
 
+Call `client.request_resign` to ask the current maintenance leader to resign.
+The leader releases its lease and briefly delays reelection so another client
+can take over. The request joins the caller's transaction and is delivered only
+on commit.
+
 On SQLite, the leader also removes notification outbox entries older than five
-minutes in bounded batches. Cancellation requests write Go-compatible control
-notifications in the same transaction as the job update; Ruby workers continue
-to observe cancellation through polling.
+minutes in bounded batches.
+
+### Notifications
+
+Started clients receive job insertion, queue control, cancellation, and
+leadership notifications. Postgres uses one dedicated LISTEN connection per
+started client, separate from the application's connection pool. SQLite polls
+the notification outbox with an independent cursor for each client. Inserts,
+scheduled jobs becoming available, and manual retries wake workers promptly.
+
+The receiver starts before workers and stays active during graceful shutdown.
+Startup fails if the initial subscription fails; an established receiver retries
+after connection errors and refreshes persisted state on reconnect. Normal job
+and queue polling also remains active.
+
+Set `poll_only: true` in `River::Config` to disable receiving notifications, for
+example when connecting through a proxy that cannot support LISTEN. Job, queue,
+and cancellation changes are then observed at the polling interval, and
+`request_resign` is not received. Backends without native notification support,
+such as Yugabyte with LISTEN/NOTIFY disabled, use polling automatically.
 
 ### [Renaming job kinds](https://riverqueue.com/docs/renaming-jobs)
 
@@ -721,7 +847,7 @@ The Ruby configuration file must return an unstarted client. The following clien
 methods are for applications managing their own runtime lifecycle:
 
 `client.stop` stops fetching and waits for active jobs to finish. `client.stop_and_cancel` interrupts active worker threads and returns their jobs to `available` without consuming the interrupted attempt.
-While draining, the client continues polling for cancellation requests from
+While draining, the client continues receiving and polling for cancellation requests from
 other clients, including for workers with no timeout. Transient polling errors
 are retried until the active attempts finish.
 
@@ -751,6 +877,11 @@ Load River and worker definitions in the main Ractor before spawning others. Eac
 
 Database drivers, Active Record, Sequel, and optional dependencies such as Fugit still need their own Ractor compatibility. Job timeouts also depend on Ruby and the `timeout` gem: the test suite exercises them on Ruby 4 with `timeout` 0.6.1; tests on older Rubies disable job timeouts. `WorkerRunner` handles process-wide signals and must run on the main thread of the main Ractor.
 
+Ruby 3.3 and 3.4 can deadlock while scheduling threads inside Ractors, even
+without River ([Ruby bug #20905](https://bugs.ruby-lang.org/issues/20905), fixed
+in Ruby 4). The test suite skips the producer/maintenance lifecycle test on
+those versions; insertion and synchronous worker checks still run.
+
 Ruby 4.0.2 with `timeout` 0.6.1 can intermittently deadlock during VM shutdown
 while terminating Ractors and their timeout helper threads, even after work
 finishes successfully. This reproduces without River. Tests bypass that shutdown
@@ -794,18 +925,17 @@ Minitest integrations are optional and explicitly loaded.
 
 River Pro is kept in the separate, privately distributed `riverqueue-pro` gem, so possession of that package is the access boundary. It is not included in the MPL-2.0 core gem. Its implementation and documentation live in the private `riverqueue-ruby-pro` repository; see that repository's README for configuration and feature examples.
 
-## Current differences from the Go client
+## Current limitations
 
-Ruby checks Go-generated fixtures for unique keys, cron, snooze counters, and
-shared protocol values.
+Ruby checks shared fixtures for unique keys, cron, snooze counters, and
+protocol values.
 See [conformance coverage and differences](conformance.md); this is not yet a
 full mixed-language runtime suite.
 
 The Ruby client does not currently provide dedicated OpenTelemetry/metrics
 integrations or
 transactional job completion alongside application writes. Plugins and
-subscriptions provide integration points for telemetry. Job execution uses Ruby
-worker objects rather than Go's work-function API.
+subscriptions provide integration points for telemetry.
 
 ## Development
 

data/docs/conformance.md

@@ -9,7 +9,7 @@ make test/ruby/conformance
 ```
 
 This generates `conformance/testdata/` and runs `ruby/spec/conformance_spec.rb`.
-No PostgreSQL server, pinned upstream checkout, protocol adapter, or separately
+No Postgres server, pinned upstream checkout, protocol adapter, or separately
 maintained golden files are needed. Missing fixtures fail with instructions to
 regenerate them. The regular Ruby suite includes these checks too.
 
@@ -23,13 +23,13 @@ The fixture checks cover:
 - All snooze-counter fixtures through real worker attempts and both SQL drivers.
 - Cron occurrences, named zones, daylight-saving transitions, interval schedules,
   and invalid expressions, with the Ruby API differences below checked explicitly.
-- Insertion, cancellation, queue pause/resume/metadata, and leadership resignation
+- Insertion, cancellation, queue pause/resume/metadata, and leadership resignation/request
   notification encoding through both SQL drivers, using in-memory SQLite and
   the bundled canonical migrations.
 
 The Ruby workflow runs on Ruby changes. The shared Conformance workflow also
 runs these tests when Go code changes. The ordinary driver suites retain
-PostgreSQL notification delivery/commit-ordering tests and shared PostgreSQL /
+Postgres notification delivery/commit-ordering tests and shared Postgres /
 SQLite insertion, transaction, uniqueness, and worker tests.
 
 This replaces the old `insert-only-v1` adapter and its pinned external harness.
@@ -39,17 +39,17 @@ protocol is not part of the Ruby API.
 
 ## Coverage gaps and API differences
 
-Ruby's runtime still polls job and queue state rather than consuming PostgreSQL
-LISTEN events or the SQLite outbox. The fixture target checks notification
-emission, not dispatch. Ruby does not emit or handle `request_resign`; other
-clients' requests therefore cannot force a Ruby leader to resign. Completing
-that coverage would require a notification listener and runtime dispatch path.
-The ordinary driver suites verify PostgreSQL delivery, commit ordering, and
-rollback for queue controls and resignations as well as insertion/cancellation.
+Ruby consumes Postgres LISTEN events and the SQLite notification outbox. The
+ordinary driver suites exercise insert wakeups, cancellation while draining,
+queue pause/resume, and leadership handoff on `request_resign` through both
+backends and both SQL drivers. They also check commit ordering, rollback,
+independent listeners, startup failures, and recovery after listener failures.
+The fixture target checks wire formats; live mixed-language worker execution
+remains outside its scope.
 
 Shared snooze-counter fixtures cover non-negative integers and absent counters.
 Recovery from other JSON values is implementation-specific. Ruby's shared driver
-tests cover its lenient conversion rules separately on PostgreSQL and SQLite.
+tests cover its lenient conversion rules separately on Postgres and SQLite.
 
 Cron retains Ruby's existing Fugit extensions: six fields with seconds, Sunday
 as 7, hour 24, and descending ranges. These four expressions are accepted in