riverqueue 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b197b9ab6ebd0ca0b94b8fdde5bf071b61060c83509080fd553cf1f96f69a558
-  data.tar.gz: 1f9b3dcf3526a1c931c6fb6bf40f32da98084836c8841a6c5447840074401b8f
+  metadata.gz: c22dfdcd40a71eaf7e3f9f74351b795957b2a23c7a51d5e302c7dd6d046ce3e8
+  data.tar.gz: 495748ff5de7b982d2d18c8ed6670865e5452c5e8198a457428e53c2af5ecf76
 SHA512:
-  metadata.gz: '0782b30ebb1ba9f06886ada1518968bf988736a285164242ec5f03e0dae282b0f8e4ceb0a5cee5e2c21eb92a2ef05765ef3ae2d11451f414398b99fc5907a095'
-  data.tar.gz: 8d1ea3397d795c6b17dd9cb55dcfa3312044240891abe3ed37f4bfd86ec8cba44a4f9b6e750754cb8824fbdc2f6c5162fad613f78b71055ae13ab34651a293e9
+  metadata.gz: 1707b4db9e48540d168af6cdd89dc98e78db8101e4cfaa1a95ede93a1e4d1bd5ab28b13e94f6ab3c106f5673dc30f4092b83d299b98a257c23384ffeb2ba170d
+  data.tar.gz: cffa8f11fda5a7b003413ed3dab643ce44168987dc2afe2fb0b6d5dccafcfbfe0e6a88264262502018e53a38f6f3c2b1a460fef8ccdfb7ce0c9c37999bfe3514

data/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-10-08
+
+### Added
+
+- Expanded checks against Go-generated conformance fixtures to cover cron schedules, snooze counters, all shared metadata keys, and queue-control and leadership notification emission through both SQL drivers. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- Added `CRON_TZ=` / `TZ=` prefixes, `?` wildcards, and Go-style `@every` durations to `PeriodicCron`. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+
+### 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).
+
+### Fixed
+
+- Externally claimed jobs honor worker retry hooks, including Active Job's retry policy, and use their claim timestamps for queue-wait statistics and attempt errors. Worker initialization failures are logged without losing the reported work error. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- Externally reported cancellation, snooze, and interruption signals follow normal worker finalization instead of being recorded as ordinary failures. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- Graceful shutdown and queue removal continue observing remote cancellation until active jobs finish, including when worker timeouts are disabled or cancellation polling temporarily fails. Draining waits respect polling intervals and wake when the last attempt finishes. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- Blocking lifecycle calls from the client's own runtime threads fail immediately instead of waiting for themselves. Workers can still request nonblocking stop. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- Inserts reject states other than `available`, `pending`, and `scheduled`, preventing stranded `running` jobs without attempt timestamps. Insertion hooks are checked after all callbacks run, and invalid batches roll back hook writes. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- The Sequel driver preserves application `ArgumentError` exceptions raised inside SQLite transactions after rolling back, including validation errors from insertion hooks. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- Job inserts and updates reject attempt limits above 32,767 consistently across databases. Attempt updates and manual retries enforce the portable counter range, and claims tolerate counters already at the limit. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- Wildcard queue pause and resume publish events for every affected queue, including beyond 100 queues. Events use the update's snapshots so concurrent changes cannot replace their contents or introduce unrelated queues. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- Manually retrying a cancelled job clears the old cancellation request so its next attempt can complete. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- 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).
+- 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).
+- Periodic jobs now carry `periodic: true` and, when named, `river:periodic_job_id`, while preserving constructor options and application metadata. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- Queue pause, resume, metadata changes, and leader resignation now broadcast notifications for clients in other languages. Notifications commit and roll back with the corresponding database change. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- Cron schedules include both occurrences of repeated daylight-saving times when given a local reference time. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- Job insertion rejects invalid queue names, nonpositive attempt limits, and nonzero uniqueness periods shorter than one second before writing any jobs. [PR #1463](https://github.com/riverqueue/river/pull/1463).
+- 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 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).
+- 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

data/README.md

@@ -0,0 +1,22 @@
+# 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.
+
+- [Usage and configuration](docs/README.md)
+- [Development and releases](docs/development.md)
+- [Conformance coverage](docs/conformance.md)
+- [Migrations](docs/migrations.md)
+
+From the repository root:
+
+```sh
+make -C ruby install
+createdb river_test
+RIVER_REQUIRE_DATABASES=1 make test/ruby
+make lint/ruby typecheck/ruby
+```
+
+Ruby 3.2 or later is required. `make test/ruby/conformance` runs only the
+Go-generated fixture checks and needs no PostgreSQL server.

data/docs/README.md

@@ -1,4 +1,4 @@
-# River client for Ruby [![Build Status](https://github.com/riverqueue/riverqueue-ruby/workflows/CI/badge.svg)](https://github.com/riverqueue/riverqueue-ruby/actions) [![Gem Version](https://badge.fury.io/rb/riverqueue.svg)](https://badge.fury.io/rb/riverqueue)
+# 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.
 
@@ -133,6 +133,12 @@ end
 
 Insertion keywords control the queue, priority, maximum attempts, schedule,
 tags, metadata, and uniqueness of a job. Priority `1` is highest.
+`max_attempts` must be between 1 and 32,767 on every database.
+An explicit `state` must be `:available`, `:pending`, or `:scheduled` (strings
+are also accepted). Other states raise `ArgumentError` before any jobs are
+inserted, including when an invalid state appears in a batch. Without an
+explicit state, jobs are available immediately or scheduled when `scheduled_at`
+is in the future.
 
 ```ruby
 result = client.insert(args,
@@ -224,7 +230,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 rescues stale running jobs after an hour, retrying or discarding them according to their attempt count. `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 Ruby, Go, or River UI.
 
 ### [Job retries](https://riverqueue.com/docs/job-retries)
 
@@ -243,12 +249,18 @@ config = River::Config.new(
 ```
 
 Use `client.job_retry(job_id)` to make a non-running job available immediately.
+This clears its previous cancellation request. Once a job has reached 32,767
+attempts, requesting another retry raises `ArgumentError` without changing it.
 
 A worker may implement `retry?(job, error)` and return false to discard a
 reported error immediately, without reducing the attempt budget used for crash
 recovery. The Rails integration uses this to let Active Job own application retries.
+Jobs claimed and finished by batch extensions honor the registered worker's
+`retry?` and `next_retry` hooks too, including workers registered as classes.
 If a retry hook or policy raises, River logs the callback error and falls back to
 retrying with the default backoff. The original work error is still recorded.
+Stuck-job rescue also falls back per job when a retry policy raises or returns
+an invalid time, allowing other rescues and cleanup to continue.
 
 ### [Error handling and timeouts](https://riverqueue.com/docs/error-handling)
 
@@ -310,6 +322,9 @@ config = River::Config.new(queues: {
 ```
 
 Queues may also be added and removed at runtime with `client.queue_add(name, config)` and `client.queue_remove(name)`.
+Queue removal stops fetching and keeps observing cancellation requests until its
+active jobs finish. Removing a queue from one of its own workers raises
+`ThreadError`, because that worker cannot wait for itself to finish.
 
 ### [Pausing queues](https://riverqueue.com/docs/pausing-queues)
 
@@ -324,6 +339,9 @@ client.queue_resume "*"
 ```
 
 Use `queue_get`, `queue_list`, and `queue_update` to inspect queues and attach metadata.
+Pause and resume events contain a snapshot of each affected queue. Wildcard
+operations publish events for every affected queue; size subscription buffers
+to accommodate the number of events you expect to receive.
 
 ### Rails and Active Job
 
@@ -340,6 +358,11 @@ the job is due, not during registration. A reusable callable can be passed as
 `constructor:` instead; don't supply both. Core periodic schedules live in the
 client process; River Pro adds durable schedules.
 
+A started client can produce periodic jobs with `queues: {}` while other clients
+consume them. Jobs added through `client.periodic_jobs` also start maintenance
+when needed. Periodic registration requires leader election to be enabled,
+including jobs registered after startup.
+
 ```ruby
 cleanup = River::PeriodicJob.new(
   id: :cleanup,
@@ -360,6 +383,10 @@ registrations and returns the bundle.
 `add_many` registers a batch atomically: duplicate IDs or invalid schedules leave
 the registry unchanged.
 
+Inserted jobs carry `periodic: true` in metadata and, when the registration has
+an ID, `river:periodic_job_id`. Constructor options and application metadata are
+preserved.
+
 Schedules can be callbacks (`schedule: ->(now) { now + 300 }`) or objects
 implementing `next(time)`. They must return a `Time` strictly after the supplied
 time; they do not execute the job themselves. A schedule that raises at runtime
@@ -376,12 +403,15 @@ cleanup = River::PeriodicJob.new(
 
 `PeriodicCron` parses once and loads Fugit only when constructed. Fugit is not
 a runtime dependency of the River gem. The timezone defaults explicitly to UTC;
-provide it through `timezone:`, not inside the expression. Five-field cron,
-optional seconds, and aliases such as `@daily` use Fugit's syntax. Results are
-UTC `Time` objects. Local calendar times follow Fugit's daylight-saving rules;
-nonexistent spring-forward times are skipped. Test ambiguous fall-back times
-for your schedules. Cron does not change core scheduling durability or replay
-missed occurrences after downtime.
+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.
+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
+languages. Cron does not replay missed occurrences after downtime.
 
 For a one-time date, insert a job with
 `client.insert(args, scheduled_at: Time.utc(2026, 9, 20, 9))` instead of registering
@@ -534,6 +564,9 @@ A plugin may implement any combination of these methods:
 
 A single plugin can provide both styles. For example, it might use
 `insert_begin` to add metadata and `work` to time the complete work operation.
+After insertion hooks run, each job must still have an initial state of
+`available`, `pending`, or `scheduled`. Invalid states roll back the batch
+and any database writes made by its hooks.
 
 ```ruby
 class TimingPlugin
@@ -604,7 +637,11 @@ client.job_delete_many states: [:cancelled]
 
 Reusable `JobListParams` and `JobUpdateParams` objects are also accepted as
 positional arguments, instead of keywords. For updates, omitted fields remain
-unchanged; an explicit `nil` clears a nullable field.
+unchanged; an explicit `nil` clears a nullable field. Metadata must be a Hash;
+use `metadata: {}` to clear it. Values inside the Hash may be `nil`.
+Updated `max_attempts` must be between 1 and 32,767; `attempt` must be between
+0 and 32,767. Claims cap the attempt counter at 32,767 so an administratively
+requeued job cannot prevent other jobs from being claimed.
 
 Bulk deletion requires at least one filter and never deletes running jobs.
 Metadata filters compare complete JSON values at each supplied top-level key,
@@ -647,6 +684,8 @@ config = River::Config.new(
 ```
 
 A custom service implements `run(client, driver, now)` and runs only while this client holds leadership.
+Service errors are logged without interrupting other services, stuck-job rescue,
+or cleanup. A failed service is retried on the next scheduled maintenance pass.
 
 On SQLite, the leader also removes notification outbox entries older than five
 minutes in bounded batches. Cancellation requests write Go-compatible control
@@ -682,6 +721,13 @@ 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
+other clients, including for workers with no timeout. Transient polling errors
+are retried until the active attempts finish.
+
+Blocking stop calls from the client's own workers or other runtime threads
+raise `ThreadError`. A worker can request shutdown with `client.stop(wait: false)`
+and then finish its work.
 
 Use `client.stop(wait: false)` to request stop and return immediately without
 interrupting active workers. Call `client.stop` later to wait for draining and
@@ -714,7 +760,7 @@ limitations are resolved.
 
 ## RBS and type checking
 
-The gem bundles [RBS files](https://github.com/riverqueue/riverqueue-ruby/tree/master/sig) for tools such as [Steep](https://github.com/soutaro/steep) and other RBS-compatible type checkers.
+The gem bundles [RBS files](https://github.com/riverqueue/river/tree/master/ruby/sig) for tools such as [Steep](https://github.com/soutaro/steep) and other RBS-compatible type checkers.
 
 ## Drivers
 
@@ -750,9 +796,10 @@ River Pro is kept in the separate, privately distributed `riverqueue-pro` gem, s
 
 ## Current differences from the Go client
 
-The shared PostgreSQL insert-only conformance profile is exercised through both
-SQL drivers. Full runtime, SQLite, and multi-engine conformance remain in
-progress; see the [conformance status and differences](../conformance/README.md).
+Ruby checks Go-generated fixtures for unique keys, cron, snooze counters, and
+shared 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

data/docs/conformance.md

@@ -0,0 +1,72 @@
+# Ruby conformance
+
+Ruby reads fixtures generated from this checkout's Go implementation, alongside
+Rust and JavaScript. From the repository root:
+
+```sh
+make -C ruby install
+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
+maintained golden files are needed. Missing fixtures fail with instructions to
+regenerate them. The regular Ruby suite includes these checks too.
+
+The fixture checks cover:
+
+- All unique-key cases, including typed-only cases, raw JSON tokens, selected
+  fields, periods, queues, and state masks.
+- Job state names and unique bits, attempt-error encoding/decoding, retry bounds,
+  and all six shared metadata keys, including actual output, rescue, periodic,
+  unique insertion, and resumable-step persistence.
+- 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
+  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 /
+SQLite insertion, transaction, uniqueness, and worker tests.
+
+This replaces the old `insert-only-v1` adapter and its pinned external harness.
+It checks shared data formats, not live mixed-language worker execution. Adapter
+handshake and request-schema tests were specific to that removed harness; their
+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.
+
+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.
+
+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
+Ruby and rejected in Go; the fixture suite explicitly asserts the difference.
+Fugit rejects impossible calendar dates at construction instead of returning
+Go's zero time. Ruby's default calendar zone remains UTC; tests explicitly pass
+the reference time's fixed offset to model Go's time-location API. `CRON_TZ=` /
+`TZ=` prefixes, `?`, and `@every` duration rounding now follow Go for the shared
+fixtures. No new dependencies were added.
+
+Selected unique fields use `by_args: [:field, [:nested, :field]]`, rather than Go
+struct tags. Dotted string keys are literal. Cross-language unique keys require
+the same encoded argument values, including escaping, numeric tokens, and
+nested ordering; Ruby does not override the application's JSON serialization.
+
+Transactions are connection-scoped blocks. Workers use exceptions and thread
+interruption. List cursors encode the selected field explicitly. Historical
+error timestamps accept Ruby's `Time.parse` formats, and metadata must decode
+to an object. Live interoperability across these boundaries is not covered by
+the fixture target.

data/docs/migrations.md

@@ -98,19 +98,16 @@ history changes. These are not shared locks with Go's migration runner.
 
 ## Updating the bundled SQL
 
-`migration/manifest.json` records the upstream commit and each file's SHA-256.
-Synchronize or verify the public migrations against a local Go checkout:
+`migration/manifest.json` records each canonical file's SHA-256. From `ruby/`,
+synchronize or verify against the Go migrations in this same checkout:
 
 ```sh
-ruby scripts/sync_migrations.rb ../river
+ruby scripts/sync_migrations.rb
 make verify
-make verify RIVER_PATH=/path/to/river
 ```
 
-`make verify` defaults to `../river` and checks SQL contents, filenames, the
-license, and the manifest's checksums and source revision. CI fetches the public
-River repository at that recorded revision and runs the same check; it does not
-require a sibling checkout or access to the private Pro repository.
+Verification checks SQL contents, filenames, license, and manifest checksums.
+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

data/lib/client.rb

@@ -7,6 +7,9 @@ module River
   # Default number of maximum attempts for a job.
   MAX_ATTEMPTS_DEFAULT = 25
 
+  # Largest attempt limit supported by all River databases.
+  MAX_ATTEMPTS_LIMIT = 32_767
+
   # Default priority for a job.
   PRIORITY_DEFAULT = 1
 
@@ -40,6 +43,8 @@ module River
 
     # Internal extension point used by separately packaged batch workers after
     # they atomically claim additional jobs alongside the batch leader.
+    # Errors honor the registered worker's retry hooks and River's cancellation,
+    # snooze, and interruption signals. Timings use the row's claim timestamp.
     def __finish_claimed_job(row, error = nil)
       @runtime.finish_claimed(row, error)
     end
@@ -223,13 +228,18 @@ module River
 
     # Makes a non-running job immediately available for another attempt and
     # returns its updated JobRow. Raises NotFoundError if it does not exist.
+    # Clears any cancellation request from its previous attempt. Raises
+    # ArgumentError if another attempt would exceed MAX_ATTEMPTS_LIMIT.
     def job_retry(id)
       @driver.job_retry(id) || raise(NotFoundError, "job not found: #{id}")
     end
 
     # Applies keyword attributes or a JobUpdateParams to a job and returns its
     # updated JobRow. Explicit nil clears nullable fields; omitted fields are
-    # unchanged. Raises NotFoundError if the job does not exist.
+    # unchanged. Metadata must be a Hash; use an empty Hash to clear it.
+    # attempt must be between 0 and MAX_ATTEMPTS_LIMIT (32,767);
+    # max_attempts must be between 1 and MAX_ATTEMPTS_LIMIT.
+    # Raises NotFoundError if the job does not exist.
     # @type method job_update: (Integer, ?JobUpdateParams?, **untyped) -> JobRow
     def job_update(id, params = nil, **attributes)
       raise ArgumentError, "use params or keyword attributes, not both" if params && !attributes.empty?
@@ -266,9 +276,8 @@ module River
     # Pauses a named queue, or all queues when +name+ is +"*"+.
     def queue_pause(name)
       name = name.to_s
-      @driver.queue_pause(name)
+      queues = @driver.queue_pause(name)
       @runtime.wake
-      queues = (name == "*") ? @driver.queue_list : [@driver.queue_get(name)].compact
       queues.each do |queue|
         @runtime.publish_queue(EVENT_QUEUE_PAUSED, queue)
       end
@@ -278,6 +287,7 @@ module River
 
     # Removes a configured queue, waits for active jobs in it to finish, and
     # returns self.
+    # Raises ThreadError if called from that queue's own worker or producer.
     def queue_remove(name)
       @runtime.queue_remove(name.to_s)
       self
@@ -286,9 +296,8 @@ module River
     # Resumes a named queue, or all queues when +name+ is +"*"+.
     def queue_resume(name)
       name = name.to_s
-      @driver.queue_resume(name)
+      queues = @driver.queue_resume(name)
       @runtime.wake
-      queues = (name == "*") ? @driver.queue_list : [@driver.queue_get(name)].compact
       queues.each do |queue|
         @runtime.publish_queue(EVENT_QUEUE_RESUMED, queue)
       end
@@ -316,12 +325,14 @@ module River
     # waiting; call stop again to finish draining and release resources.
     # In-flight fetches or maintenance operations may finish. Until a waiting
     # stop completes, started? remains true and stopped? remains false.
+    # Raises ThreadError for a waiting call from this client's runtime threads.
     def stop(wait: true)
       @runtime.stop(wait: wait)
       self
     end
 
     # Stops fetching new jobs, interrupts active work, and returns self.
+    # Raises ThreadError if called from this client's own runtime threads.
     def stop_and_cancel
       @runtime.stop(cancel: true)
       self
@@ -350,6 +361,8 @@ module River
 
     EMPTY_INSERT_OPTS = InsertOpts.new.freeze
 
+    INITIAL_STATES = [JOB_STATE_AVAILABLE, JOB_STATE_PENDING, JOB_STATE_SCHEDULED].freeze
+
     REQUIRED_UNIQUE_STATES = [
       JOB_STATE_AVAILABLE,
       JOB_STATE_PENDING,
@@ -359,7 +372,7 @@ module River
 
     TAG_RE = /\A\w[\w-]+\w\z/
 
-    private_constant :DEFAULT_UNIQUE_STATES, :EMPTY_INSERT_OPTS, :REQUIRED_UNIQUE_STATES, :TAG_RE
+    private_constant :DEFAULT_UNIQUE_STATES, :EMPTY_INSERT_OPTS, :INITIAL_STATES, :REQUIRED_UNIQUE_STATES, :TAG_RE
 
     private def insert_and_check_unique_job(insert_params)
       job, unique_skipped_as_duplicate = @driver.job_insert(insert_params)
@@ -380,18 +393,25 @@ module River
         EMPTY_INSERT_OPTS
       end
 
+      max_attempts = insert_opts.max_attempts || args_insert_opts.max_attempts || MAX_ATTEMPTS_DEFAULT
+      raise ArgumentError, "max_attempts must be greater than zero" unless max_attempts > 0
+      raise ArgumentError, "max_attempts must not exceed #{MAX_ATTEMPTS_LIMIT}" if max_attempts > MAX_ATTEMPTS_LIMIT
+
+      queue = (insert_opts.queue || args_insert_opts.queue || QUEUE_DEFAULT).to_s
+      raise ArgumentError, "invalid queue name: #{queue.inspect}" unless queue.match?(QUEUE_NAME_REGEX) && queue.length < 128
+
       scheduled_at = insert_opts.scheduled_at || args_insert_opts.scheduled_at
       now = @time_now_utc.call
-      state = (insert_opts.state || args_insert_opts.state || ((scheduled_at && scheduled_at > now) ? JOB_STATE_SCHEDULED : JOB_STATE_AVAILABLE)).to_s #: jobStateAll # rubocop:disable Layout/LeadingCommentSpace
+      state = validate_insert_state(insert_opts.state || args_insert_opts.state || ((scheduled_at && scheduled_at > now) ? JOB_STATE_SCHEDULED : JOB_STATE_AVAILABLE))
 
       insert_params = Driver::JobInsertParams.new(
         args: args,
         encoded_args: args_json,
         kind: args.kind.to_s,
-        max_attempts: insert_opts.max_attempts || args_insert_opts.max_attempts || MAX_ATTEMPTS_DEFAULT,
+        max_attempts: max_attempts,
         metadata: (args_insert_opts.metadata || {}).merge(insert_opts.metadata || {}),
         priority: insert_opts.priority || args_insert_opts.priority || PRIORITY_DEFAULT,
-        queue: (insert_opts.queue || args_insert_opts.queue || QUEUE_DEFAULT).to_s,
+        queue: queue,
         scheduled_at: scheduled_at&.getutc || now,
         state: state,
         tags: validate_tags(insert_opts.tags || args_insert_opts.tags || [])
@@ -423,6 +443,8 @@ module River
       end
 
       if unique_opts.by_period && unique_opts.by_period != 0
+        raise ArgumentError, "by_period should not be less than 1 second" if unique_opts.by_period < 1
+
         lower_period_bound = truncate_time(insert_params.scheduled_at || @time_now_utc.call, unique_opts.by_period).utc
 
         unique_key += "&period=#{lower_period_bound.strftime("%FT%TZ")}"
@@ -456,6 +478,10 @@ module River
           end
         end
 
+        # Hooks may change any job in the batch, including an earlier entry.
+        # Validate the final states only after all insertion hooks have run.
+        all_params.each { |params| params.state = validate_insert_state(params.state) }
+
         results = insert_operation.call
         results.each do |result|
           config.plugins.reverse_each do |plugin|
@@ -496,6 +522,13 @@ module River
       [int].pack("Q").unpack1("q") #: Integer # rubocop:disable Layout/LeadingCommentSpace
     end
 
+    private def validate_insert_state(state)
+      state = state.to_s #: jobStateInitial # rubocop:disable Layout/LeadingCommentSpace
+      raise ArgumentError, "invalid insertion state: #{state.inspect}; must be available, pending, or scheduled" unless INITIAL_STATES.include?(state)
+
+      state
+    end
+
     private def validate_tags(tags)
       tags.each do |tag|
         raise ArgumentError, "tags should be 255 characters or less" if tag.length > 255