riverqueue 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c862e762c9679461633535e60ce0063ea7cad3fbe42d1f4b35c97350826ee3e0
-  data.tar.gz: 9a80c1852a2d587408fdc8e4c0c0c6b1af20bba5c60c0b777787f87248eb4cc9
+  metadata.gz: 70cd35bf366c6911d61d8adf29777d699b4dd24c8641eeae53d520c2719a573f
+  data.tar.gz: bf715e145cd3a1f6bc089cd5796d3e02313e89a72c52cbd8868c8e6866905b23
 SHA512:
-  metadata.gz: 1b189d118fbb38fbf14f961ce645505c0a47e28421c1b0af11154c2dde5d6d057a4ddf25f88b4fc5a3d8f602c931db792281d89a73c8d0dab230fb9266aab1d4
-  data.tar.gz: ebf174f14f464c6be842647ddfc3a23a5ee3b33ffd84ce8c10b471849192bedcbc1e05db8e15d457ccf6cfbdfe8e3c04090882c636abb9fa2b6111ad2ffd483b
+  metadata.gz: e46f580c619455d5d15fbb9e7e0e1295b2d82f1e72fa395aac9648aa8066031a965a0bf2651630a1efa93b289235296717af90aee9ed5bc7caf54b51cea25376
+  data.tar.gz: 6470ef7fdd259235f4de8c34e8098b629934908202ce2f8f455357fb335504af66980780befe160fd45420afef3a034937cbfb59ffda40adfd639354a217d51c

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.0] - 2026-11-04
+
+### Added
+
+- Add `output:` to `Client#job_update` and `River::JobUpdateParams` to persist job output immediately with an atomic metadata update that preserves other keys. Explicit `output: nil` stores JSON null; when `metadata:` is also supplied, output is applied to that replacement metadata. [PR #1568](https://github.com/riverqueue/river/pull/1568).
+
+### Fixed
+
+- Reduce database overhead in the Active Record and Sequel drivers: use `RETURNING` to avoid redundant row fetches, claim batches and clean up finalized jobs in one statement, and omit unnecessary transactions. Return Active Record connections to the pool after operations and avoid allocating models for job reads. Avoid slow Postgres fetching-index scans for updates and deletes targeting a job by ID when state statistics are stale. [PR #1574](https://github.com/riverqueue/river/pull/1574).
+- Prevent ordinary job wakeups from interrupting maintenance error backoff and causing rapid retries during persistent failures. [PR #1574](https://github.com/riverqueue/river/pull/1574).
+- Enforce the 32 MiB encoded UTF-8 JSON limit for `Job#output=`, preserving previous output when validation fails. [PR #1569](https://github.com/riverqueue/river/pull/1569).
+
 ## [0.15.0] - 2026-10-30
 
 ### Added

data/docs/README.md

@@ -546,7 +546,7 @@ remain idempotent.
 
 ### [Recorded output and metadata](https://riverqueue.com/docs/recorded-output)
 
-Assign `job.output` to store JSON-compatible output under `metadata["output"]`. Use `job.update_metadata` for other metadata that should be committed with the attempt's final transition.
+Assign `job.output` to buffer JSON-compatible output under `metadata["output"]` until the attempt finishes. Use `job.update_metadata` for other metadata that should be committed with the attempt's final transition.
 
 Values are validated and copied when assigned. Invalid JSON fails the attempt
 normally without preventing its error from being recorded. `job.metadata` and
@@ -559,6 +559,22 @@ def work(job)
 end
 ```
 
+To save output immediately, including between resumable steps, use `job_update`:
+
+```ruby
+job.client.job_update(job.id, output: {normalized_text: normalized})
+```
+
+This writes `metadata["output"]` atomically while preserving other metadata keys,
+including resumable progress. It participates in an enclosing transaction, so
+commit that transaction before relying on the saved result. Read saved output
+through `client.job_get(job.id).metadata["output"]`. `job.output =` remains buffered;
+an output assigned there can overwrite an immediate update when the attempt ends.
+
+Omitting `output:` leaves it unchanged; `output: nil` stores JSON null. When
+`metadata:` and `output:` are both supplied, metadata replaces the existing Hash
+and the explicit output value overrides its `"output"` key.
+
 ### Job-persisted logging
 
 Add `River::JobPersistedLogging::Plugin` to save worker logs with each job attempt,

data/lib/client.rb

@@ -283,6 +283,10 @@ module River
     # Applies keyword attributes or a JobUpdateParams to a job and returns its
     # updated JobRow. Explicit nil clears nullable fields; omitted fields are
     # unchanged. Metadata must be a Hash; use an empty Hash to clear it.
+    # Output is written immediately under metadata["output"], preserving other
+    # keys. Explicit output: nil stores JSON null. If metadata is also supplied,
+    # it replaces the existing metadata and output overrides its "output" key.
+    # The write participates in an enclosing transaction, if any.
     # 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.

data/lib/client_runtime.rb

@@ -589,7 +589,7 @@ module River
       end
     rescue => error
       @config.logger.error("River maintenance stopped: #{error.full_message}")
-      wait(5)
+      wait(5, condition: @maintenance_condition)
       retry unless stopping?
     end
 
@@ -906,8 +906,8 @@ module River
       @mutex.synchronize { @stop_requested }
     end
 
-    private def wait(duration)
-      @mutex.synchronize { @condition.wait(@mutex, duration) unless @stop_requested }
+    private def wait(duration, condition: @condition)
+      @mutex.synchronize { condition.wait(@mutex, duration) unless @stop_requested }
     end
 
     private def wait_for_maintenance(duration, generation)

data/lib/driver/runtime.rb

@@ -47,7 +47,7 @@ module River::Driver
     def job_cancel(id, now: Time.now.utc)
       original_id = Integer(id)
       transaction do
-        updated_id = runtime_returning_ids(<<~SQL).first
+        updated = runtime_query_jobs(<<~SQL).first
           UPDATE river_job
           SET state = CASE WHEN state = 'running' THEN state ELSE 'cancelled' END,
               finalized_at = CASE WHEN state = 'running' THEN finalized_at ELSE #{runtime_time(now)} END,
@@ -55,12 +55,12 @@ module River::Driver
           WHERE id = #{original_id}
             AND state NOT IN ('cancelled', 'completed', 'discarded')
             AND finalized_at IS NULL
-          RETURNING id
+          RETURNING #{runtime_job_columns}
         SQL
-        row = job_get_by_id(updated_id || original_id)
+        row = updated || job_get_by_id(original_id)
         # Other engines interrupt running workers through this notification;
         # the durable marker remains Ruby's polling fallback.
-        runtime_notify("river_control", action: "cancel", job_id: row.id, queue: row.queue) if updated_id
+        runtime_notify("river_control", action: "cancel", job_id: row.id, queue: row.queue) if updated
         row
       end
     end
@@ -82,25 +82,19 @@ module River::Driver
       assignments = ["state = 'completed'", "finalized_at = #{runtime_time(finalized_at)}"]
       assignments << "metadata = #{runtime_merge_metadata(metadata)}" unless metadata.nil? || metadata.empty?
 
-      transaction do
-        updated_id = runtime_returning_ids(<<~SQL).first
-          UPDATE river_job SET #{assignments.join(", ")}
-          WHERE #{predicate} AND state = 'running' AND NOT (#{runtime_cancel_attempted})
-          RETURNING id
-        SQL
-        next runtime_read_job(updated_id) if updated_id
+      updated = runtime_query_jobs(<<~SQL, tolerate_decode_errors: true).first
+        UPDATE river_job SET #{assignments.join(", ")}
+        WHERE #{runtime_running_job_predicate(id, expected_job: expected_job, uncancelled: true)}
+        RETURNING #{runtime_job_columns}
+      SQL
+      return updated if updated
 
-        :cancelled if runtime_returning_ids("SELECT id FROM river_job WHERE #{predicate} AND (#{runtime_cancel_attempted})").any?
-      end
+      :cancelled if runtime_returning_ids("SELECT id FROM river_job WHERE #{predicate} AND (#{runtime_cancel_attempted})").any?
     end
 
     def job_delete(id)
-      existing = job_get_by_id(id)
-      return nil unless existing
-      return existing if existing.state == River::JOB_STATE_RUNNING
-
-      deleted_id = runtime_returning_ids("DELETE FROM river_job WHERE id = #{Integer(id)} AND state != 'running' RETURNING id").first
-      deleted_id ? existing : job_get_by_id(id)
+      deleted = runtime_query_jobs("DELETE FROM river_job WHERE id = #{Integer(id)} AND state != 'running' RETURNING #{runtime_job_columns}").first
+      deleted || job_get_by_id(id)
     end
 
     def job_delete_finalized(retention:, now: Time.now.utc, max: 1_000)
@@ -112,14 +106,11 @@ module River::Driver
 
       return 0 if clauses.empty?
 
-      ids = runtime_query_rows(<<~SQL).map { |row| runtime_value(row, :id).to_i }
-        SELECT id FROM river_job WHERE #{clauses.join(" OR ")} ORDER BY id LIMIT #{Integer(max)}
-      SQL
-      return 0 if ids.empty?
-
       runtime_returning_ids(<<~SQL).length
         DELETE FROM river_job
-        WHERE id IN (#{ids.join(",")}) AND (#{clauses.join(" OR ")})
+        WHERE id IN (
+          SELECT id FROM river_job WHERE #{clauses.join(" OR ")} ORDER BY id LIMIT #{Integer(max)}
+        ) AND (#{clauses.join(" OR ")})
         RETURNING id
       SQL
     end
@@ -130,7 +121,7 @@ module River::Driver
       id = Integer(id)
       deleted = runtime_returning_ids(<<~SQL).any?
         DELETE FROM river_job
-        WHERE id = #{id} AND state = 'running' AND NOT (#{runtime_cancel_attempted})
+        WHERE #{runtime_running_job_predicate(id, uncancelled: true)}
         RETURNING id
       SQL
       return true if deleted
@@ -177,23 +168,20 @@ module River::Driver
     end
 
     # When supplied, expected_job prevents metadata from crossing into another
-    # attempt or state. Keep the update and returned snapshot in one transaction.
+    # attempt or state. RETURNING provides the snapshot from the update itself.
     def job_metadata_merge(id, metadata, expected_job = nil)
       predicate = "id = #{Integer(id)}"
       if expected_job
         predicate += " AND #{runtime_job_attempt_predicate(expected_job)}"
-        predicate += " AND state = #{runtime_quote(expected_job.state)}"
+        predicate += " AND #{runtime_job_state_column} = #{runtime_quote(expected_job.state)}"
       end
 
-      transaction do
-        updated_id = runtime_returning_ids(<<~SQL).first
-          UPDATE river_job
-          SET metadata = #{runtime_merge_metadata(metadata)}
-          WHERE #{predicate}
-          RETURNING id
-        SQL
-        updated_id ? job_get_by_id(updated_id) : nil
-      end
+      runtime_query_jobs(<<~SQL).first
+        UPDATE river_job
+        SET metadata = #{runtime_merge_metadata(metadata)}
+        WHERE #{predicate}
+        RETURNING #{runtime_job_columns}
+      SQL
     end
 
     def job_rescue_stuck(horizon:, retry_policy:, now: Time.now.utc, max: 1_000, logger: nil, rescue_if: nil)
@@ -249,10 +237,10 @@ module River::Driver
     end
 
     def job_retry(id, now: Time.now.utc)
-      updated_id, job = transaction do
+      updated, job = transaction do
         # Check the counter in the write itself so a concurrent claim cannot
         # advance it between validation and the update.
-        updated_id = runtime_returning_ids(<<~SQL).first
+        updated = runtime_query_jobs(<<~SQL).first
           UPDATE river_job
           SET state = 'available',
               max_attempts = CASE WHEN attempt = max_attempts THEN max_attempts + 1 ELSE max_attempts END,
@@ -263,13 +251,13 @@ module River::Driver
             AND state != 'running'
             AND (state != 'available' OR scheduled_at > #{runtime_time(now)})
             AND attempt < #{River::MAX_ATTEMPTS_LIMIT}
-          RETURNING id
+          RETURNING #{runtime_job_columns}
         SQL
-        job = job_get_by_id(updated_id || id)
-        runtime_notify("river_insert", queue: job.queue) if updated_id && job
-        [updated_id, job]
+        job = updated || job_get_by_id(id)
+        runtime_notify("river_insert", queue: job.queue) if updated && job
+        [updated, job]
       end
-      if !updated_id && job && job.state != "running" && (job.state != "available" || job.scheduled_at > now) && job.attempt >= River::MAX_ATTEMPTS_LIMIT
+      if !updated && job && job.state != "running" && (job.state != "available" || job.scheduled_at > now) && job.attempt >= River::MAX_ATTEMPTS_LIMIT
         raise ArgumentError, "cannot retry a job with #{River::MAX_ATTEMPTS_LIMIT} or more attempts"
       end
       job
@@ -307,40 +295,59 @@ module River::Driver
 
       assignments << "state = CASE WHEN #{cancel_path} THEN 'cancelled' ELSE #{runtime_state(state)} END"
 
-      id = runtime_returning_ids(<<~SQL).first
+      runtime_query_jobs(<<~SQL, tolerate_decode_errors: true).first
         UPDATE river_job
         SET #{assignments.join(",\n    ")}
-        WHERE id = #{Integer(id)} AND state = 'running'
-        RETURNING id
+        WHERE #{runtime_running_job_predicate(id)}
+        RETURNING #{runtime_job_columns}
       SQL
-      id ? runtime_read_job(id) : nil
     end
 
     def job_update(id, params)
-      assignments = params.each.map do |field, value|
+      values = params.each.to_h
+      assignments = [] #: Array[String]
+      if values.key?(:output)
+        output = values.delete(:output)
+        if values.key?(:metadata)
+          metadata = values[:metadata]
+          raise ArgumentError, "metadata must be a Hash" unless metadata.is_a?(Hash)
+
+          values[:metadata] = metadata.transform_keys(&:to_s).merge("output" => output)
+        else
+          # Merge against the database row in the UPDATE, preserving metadata
+          # written since the caller last read the job.
+          assignments << "metadata = #{runtime_merge_metadata("output" => output)}"
+        end
+      end
+      values.each do |field, value|
         raise ArgumentError, "unknown update field: #{field}" unless River::JobUpdateParams.method_defined?(field)
 
-        "#{field} = #{runtime_update_value(field, value)}"
+        assignments << "#{field} = #{runtime_update_value(field, value)}"
       end
 
       return job_get_by_id(id) if assignments.empty?
 
-      updated_id = runtime_returning_ids(<<~SQL).first
+      runtime_query_jobs(<<~SQL).first
         UPDATE river_job SET #{assignments.join(", ")}
         WHERE id = #{Integer(id)}
-        RETURNING id
+        RETURNING #{runtime_job_columns}
       SQL
-      updated_id ? job_get_by_id(updated_id) : nil
     end
 
     def leader_acquire(id, ttl: 30, now: Time.now.utc)
       transaction do
         runtime_execute("DELETE FROM river_leader WHERE expires_at < #{runtime_time(now)}")
-        runtime_execute(<<~SQL)
+        sql = <<~SQL
           INSERT INTO river_leader (leader_id, elected_at, expires_at)
           VALUES (#{runtime_quote(id)}, #{runtime_time(now)}, #{runtime_time(now + ttl)})
           ON CONFLICT (name) DO NOTHING
         SQL
+        if runtime_postgres?
+          next true if runtime_query_rows("#{sql} RETURNING leader_id").any?
+        else
+          # RETURNING saved a statement but did not improve SQLite timings.
+          runtime_execute(sql)
+        end
         runtime_query_rows("SELECT leader_id FROM river_leader WHERE leader_id = #{runtime_quote(id)}").any?
       end
     end
@@ -431,11 +438,11 @@ module River::Driver
       transaction do
         row = runtime_query_rows(<<~SQL).first
           UPDATE river_queue SET metadata = #{runtime_json(metadata)}, updated_at = #{runtime_time(now)}
-          WHERE name = #{runtime_quote(name)} RETURNING name
+          WHERE name = #{runtime_quote(name)} RETURNING #{runtime_queue_columns}
         SQL
         if row
           runtime_notify("river_control", action: "metadata_changed", queue: name, metadata: metadata)
-          queue_get(name)
+          runtime_queue_from_row(row)
         end
       end
     end
@@ -443,17 +450,18 @@ module River::Driver
     def queue_upsert(name, metadata: {}, now: Time.now.utc)
       raise ArgumentError, "metadata must be a Hash" unless metadata.is_a?(Hash)
 
-      runtime_execute(<<~SQL)
+      row = runtime_query_rows(<<~SQL).first
         INSERT INTO river_queue (name, created_at, metadata, updated_at)
         VALUES (#{runtime_quote(name)}, #{runtime_time(now)}, #{runtime_json(metadata)}, #{runtime_time(now)})
         ON CONFLICT (name) DO UPDATE SET updated_at = excluded.updated_at
+        RETURNING #{runtime_queue_columns}
       SQL
-      queue_get(name)
+      runtime_queue_from_row(row)
     end
 
     # Delivery follows the caller's transaction, just like job insertion.
     def request_resign
-      transaction { runtime_notify("river_leadership", action: "request_resign", leader_id: "") }
+      runtime_notify("river_leadership", action: "request_resign", leader_id: "")
       nil
     end
 
@@ -488,46 +496,43 @@ module River::Driver
     end
 
     private def runtime_claim_jobs(predicate, max, attempted_by, now)
-      transaction do
-        attempted_by_sql = if runtime_postgres?
-          "array_append(CASE WHEN cardinality(attempted_by) >= 100 THEN attempted_by[(cardinality(attempted_by) - 98):] ELSE attempted_by END, #{runtime_quote(attempted_by)})"
-        else
-          # Preserve corrupt history so decoding can fail this attempt instead
-          # of silently repairing it or aborting the entire claim batch. Trim
-          # to the newest 99 entries before appending, preserving JSON types.
-          <<~SQL
-            CASE WHEN NOT json_valid(attempted_by, 10) AND attempted_by IS NOT NULL THEN attempted_by
-                 ELSE jsonb(json_insert(json(
-                   CASE WHEN json_array_length(attempted_by) >= 100 THEN (
-                     SELECT json_group_array(json(value)) FROM (
-                       SELECT attempted_by -> ('$[' || key || ']') AS value FROM json_each(attempted_by)
-                       WHERE key >= json_array_length(attempted_by) - 99 ORDER BY key
-                     )
-                   ) ELSE coalesce(attempted_by, jsonb('[]')) END
-                 ), '$[#]', #{runtime_quote(attempted_by)})) END
-          SQL
-        end
-
-        lock_clause = runtime_postgres? ? "FOR UPDATE SKIP LOCKED" : ""
-        # An administratively requeued job may already be at the counter limit.
-        # Saturate instead of letting that row abort the entire claim batch.
-        ids = runtime_returning_ids(<<~SQL)
-          UPDATE river_job
-          SET attempt = CASE WHEN attempt < #{River::MAX_ATTEMPTS_LIMIT} THEN attempt + 1 ELSE attempt END,
-              attempted_at = #{runtime_time(now)},
-              attempted_by = #{attempted_by_sql},
-              state = 'running'
-          WHERE id IN (
-            SELECT id FROM river_job
-            WHERE #{predicate}
-            ORDER BY priority ASC, scheduled_at ASC, id ASC
-            LIMIT #{Integer(max)}
-            #{lock_clause}
-          )
-          RETURNING id
+      attempted_by_sql = if runtime_postgres?
+        "array_append(CASE WHEN cardinality(attempted_by) >= 100 THEN attempted_by[(cardinality(attempted_by) - 98):] ELSE attempted_by END, #{runtime_quote(attempted_by)})"
+      else
+        # Preserve corrupt history so decoding can fail this attempt instead
+        # of silently repairing it or aborting the entire claim batch. Trim
+        # to the newest 99 entries before appending, preserving JSON types.
+        <<~SQL
+          CASE WHEN NOT json_valid(attempted_by, 10) AND attempted_by IS NOT NULL THEN attempted_by
+               ELSE jsonb(json_insert(json(
+                 CASE WHEN json_array_length(attempted_by) >= 100 THEN (
+                   SELECT json_group_array(json(value)) FROM (
+                     SELECT attempted_by -> ('$[' || key || ']') AS value FROM json_each(attempted_by)
+                     WHERE key >= json_array_length(attempted_by) - 99 ORDER BY key
+                   )
+                 ) ELSE coalesce(attempted_by, jsonb('[]')) END
+               ), '$[#]', #{runtime_quote(attempted_by)})) END
         SQL
-        ids.map { |id| runtime_read_job(id) }
       end
+
+      lock_clause = runtime_postgres? ? "FOR UPDATE SKIP LOCKED" : ""
+      # An administratively requeued job may already be at the counter limit.
+      # Saturate instead of letting that row abort the entire claim batch.
+      runtime_query_jobs(<<~SQL, tolerate_decode_errors: true)
+        UPDATE river_job
+        SET attempt = CASE WHEN attempt < #{River::MAX_ATTEMPTS_LIMIT} THEN attempt + 1 ELSE attempt END,
+            attempted_at = #{runtime_time(now)},
+            attempted_by = #{attempted_by_sql},
+            state = 'running'
+        WHERE id IN (
+          SELECT id FROM river_job
+          WHERE #{predicate}
+          ORDER BY priority ASC, scheduled_at ASC, id ASC
+          LIMIT #{Integer(max)}
+          #{lock_clause}
+        )
+        RETURNING #{runtime_job_columns}
+      SQL
     end
 
     private def runtime_read_job(id)
@@ -615,6 +620,12 @@ module River::Driver
       "(#{column} IS NULL OR #{column} #{comparison} #{value} OR (#{column} = #{value} AND #{id_clause}))"
     end
 
+    private def runtime_insert_transaction(params)
+      notify = params.any? { |param| param.state == River::JOB_STATE_AVAILABLE } &&
+        (!runtime_postgres? || postgres_capabilities.supports_listen_notify)
+      notify ? transaction { yield } : yield
+    end
+
     private def runtime_job_attempt_predicate(job)
       "attempt = #{Integer(job.attempt)} AND attempted_at IS NOT DISTINCT FROM #{runtime_nullable_time(job.attempted_at)}"
     end
@@ -654,6 +665,13 @@ module River::Driver
       SQL
     end
 
+    # Use this only for state checks on mutations already targeted by ID.
+    # Casting the enum prevents a fetching-index scan when state statistics
+    # are stale; Postgres can still use the primary key to find the target.
+    private def runtime_job_state_column
+      runtime_postgres? ? "state::text" : "state"
+    end
+
     private def runtime_json(value)
       encoded = value.is_a?(String) ? value : JSON.generate(value)
       runtime_postgres? ? "#{runtime_quote(encoded)}::jsonb" : "jsonb(#{runtime_quote(encoded)})"
@@ -735,6 +753,18 @@ module River::Driver
       end
     end
 
+    # Runtime transitions must retain corrupt rows so the worker can fail the
+    # affected attempt without losing the rest of a claimed batch.
+    private def runtime_query_jobs(sql, tolerate_decode_errors: false)
+      runtime_query_rows(sql).map do |row|
+        runtime_postgres? ? runtime_decode_postgres_job(row) : runtime_decode_sqlite_job(row)
+      rescue River::JobRowDecodeError => error
+        raise unless tolerate_decode_errors
+
+        error.job
+      end
+    end
+
     private def runtime_queue_columns
       runtime_postgres? ? "name, created_at, metadata, paused_at, updated_at" : "name, CAST(created_at AS text) AS created_at, json(metadata) AS metadata, CAST(paused_at AS text) AS paused_at, CAST(updated_at AS text) AS updated_at"
     end
@@ -766,6 +796,16 @@ module River::Driver
       runtime_query_rows(sql).map { |row| runtime_value(row, :id).to_i }
     end
 
+    # UPDATE/DELETE lock and recheck the attempt and cancellation predicates
+    # after waiting for a concurrent change to the target row.
+    private def runtime_running_job_predicate(id, expected_job: nil, uncancelled: false)
+      predicate = "id = #{Integer(id)}"
+      predicate += " AND #{runtime_job_attempt_predicate(expected_job)}" if expected_job
+      predicate += " AND #{runtime_job_state_column} = 'running'"
+      predicate += " AND NOT (#{runtime_cancel_attempted})" if uncancelled
+      predicate
+    end
+
     # Finds conflicts and changes the whole pass in one statement.
     private def runtime_schedule_postgres(now, max)
       now = runtime_time(now)

data/lib/params.rb

@@ -68,12 +68,14 @@ module River
 
     # Values to apply, with omitted fields represented internally by UNSET.
     attr_reader :attempt, :attempted_at, :attempted_by, :errors, :finalized_at,
-      :max_attempts, :metadata, :state
+      :max_attempts, :metadata, :output, :state
 
-    # Creates a partial set of updates for a persisted job.
+    # Creates a partial set of updates for a persisted job. Output replaces only
+    # metadata["output"] unless metadata is also supplied, in which case output
+    # is applied to that replacement Hash. Explicit nil stores JSON null.
     def initialize(attempt: UNSET, attempted_at: UNSET, attempted_by: UNSET,
       errors: UNSET, finalized_at: UNSET, max_attempts: UNSET, metadata: UNSET,
-      state: UNSET)
+      output: UNSET, state: UNSET)
       @attempt = attempt
       @attempted_at = attempted_at
       @attempted_by = attempted_by
@@ -81,6 +83,7 @@ module River
       @finalized_at = finalized_at
       @max_attempts = max_attempts
       @metadata = metadata
+      @output = output
       @state = state.is_a?(Symbol) ? state.to_s : state
     end
 

data/lib/worker.rb

@@ -139,8 +139,13 @@ module River
     end
 
     # Stores a worker result under the conventional +"output"+ metadata key.
+    # Raises ArgumentError if its encoded UTF-8 JSON exceeds 32 MiB, leaving any
+    # previously recorded output unchanged.
     def output=(value)
-      update_metadata("output" => value)
+      encoded = JSON.generate(value)
+      raise ArgumentError, "output is too large: #{encoded.bytesize} bytes (max 32 MiB)" if encoded.bytesize > 32 * 1024 * 1024
+
+      @metadata_updates["output"] = JSON.parse(encoded)
     end
 
     def respond_to_missing?(name, include_private = false)

data/sig/client.rbs

@@ -39,7 +39,7 @@ module River
     def job_retry: (Integer) -> JobRow
     def job_update: (Integer, ?JobUpdateParams?, ?attempt: untyped, ?attempted_at: untyped,
       ?attempted_by: untyped, ?errors: untyped, ?finalized_at: untyped, ?max_attempts: untyped,
-      ?metadata: untyped, ?state: untyped) -> JobRow
+      ?metadata: untyped, ?output: untyped, ?state: untyped) -> JobRow
     def periodic_jobs: () -> PeriodicJobBundle
     def queue_add: (String | Symbol, QueueConfig | Integer) -> self
     def queue_get: (String | Symbol) -> Queue

data/sig/driver.rbs

@@ -172,10 +172,13 @@ module River
       def runtime_cursor_clause: (untyped) -> String
       def runtime_execute: (String) -> untyped
       def runtime_in_clause: (untyped, untyped) -> untyped
+      def runtime_insert_transaction: (Array[JobInsertParams]) { () -> untyped } -> untyped
       def runtime_job_attempt_predicate: (untyped) -> String
+      def runtime_job_columns: () -> String
       def runtime_job_list_without_params: () -> untyped
       def runtime_job_list: (JobListParams, ?for_delete: bool) -> Array[JobRow]
       def runtime_job_rows: (String) -> untyped
+      def runtime_job_state_column: () -> String
       def runtime_json: (untyped) -> untyped
       def runtime_legacy_subtransactions?: () -> bool
       def runtime_merge_metadata: (untyped) -> untyped
@@ -188,12 +191,14 @@ module River
       def runtime_parse_json: (untyped) -> untyped
       def runtime_parse_time: (untyped) -> untyped
       def runtime_postgres?: () -> bool
+      def runtime_query_jobs: (String, ?tolerate_decode_errors: bool) -> Array[JobRow]
       def runtime_query_rows: (String) -> untyped
       def runtime_queue_columns: () -> untyped
       def runtime_queue_from_row: (untyped) -> untyped
       def runtime_quote: (untyped) -> String
       def runtime_rescue_retry: (untyped, untyped, untyped, untyped, untyped) -> Time
       def runtime_returning_ids: (untyped) -> untyped
+      def runtime_running_job_predicate: (untyped, ?expected_job: untyped, ?uncancelled: bool) -> String
       def runtime_schedule_postgres: (Time, Integer) -> Array[String]
       def runtime_schedule_sqlite: (Time, Integer) -> Array[String]
       def runtime_state: (untyped) -> untyped

data/sig/runtime.rbs

@@ -290,6 +290,7 @@ module River
     @finalized_at: untyped
     @max_attempts: untyped
     @metadata: untyped
+    @output: untyped
     @state: untyped
     attr_reader attempt: untyped
     attr_reader attempted_at: untyped
@@ -298,10 +299,11 @@ module River
     attr_reader finalized_at: untyped
     attr_reader max_attempts: untyped
     attr_reader metadata: untyped
+    attr_reader output: untyped
     attr_reader state: untyped
     def initialize: (?attempt: untyped, ?attempted_at: untyped, ?attempted_by: untyped,
       ?errors: untyped, ?finalized_at: untyped, ?max_attempts: untyped,
-      ?metadata: untyped, ?state: untyped) -> void
+      ?metadata: untyped, ?output: untyped, ?state: untyped) -> void
     def each: () { (Symbol, untyped) -> void } -> untyped
             | () -> Enumerator[[Symbol, untyped], untyped]
   end
@@ -439,7 +441,7 @@ module River
     def start_notifications: () -> untyped
     def start_producer: (String, QueueConfig) -> untyped
     def stopping?: () -> bool
-    def wait: (Float | Integer) -> untyped
+    def wait: (Float | Integer, ?condition: ConditionVariable) -> untyped
     def wait_for_maintenance: (Float | Integer, Integer) -> untyped
     def wait_for_queue: (String, Float | Integer, Integer) -> untyped
     def wait_for_running_jobs: (String, Float | Integer) -> untyped

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riverqueue
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Blake Gentry