riverqueue 0.13.0 → 0.14.0

data/lib/resumable.rb

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

data/lib/worker.rb

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

data/migration/manifest.json

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

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

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

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

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

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

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

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

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

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

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

data/sig/client.rbs

@@ -15,6 +15,7 @@ module River
 
     def initialize: (_Driver driver, ?config: Config?) -> void
     def __finish_claimed_job: (JobRow, ?Exception?) -> untyped
+    def __insert_with_default_scheduled_at: (jobArgs, InsertOpts, Time?) -> JobInsertResult
     def __perform_job: (Integer, ?allow_scheduled: bool) -> untyped
     def __interrupt_workers: () -> untyped
     def __runtime_healthy?: () -> bool
@@ -24,6 +25,7 @@ module River
       ?scheduled_at: Time?, ?state: jobStateInitialInput?, ?tags: Array[String]?, ?unique_opts: UniqueOpts?) -> JobInsertResult
     def insert_many: (Array[jobArgs | InsertManyParams]) -> Array[JobInsertResult]
     def job_cancel: (Integer) -> JobRow
+    def job_complete_tx: (Job) -> JobRow
     def job_delete: (Integer) -> JobRow
     def job_delete_many: (?JobListParams?, ?after: untyped, ?after_id: untyped,
       ?ids: untyped, ?kinds: untyped, ?limit: untyped, ?metadata: untyped, ?priorities: untyped,
@@ -46,6 +48,7 @@ module River
     def queue_remove: (String | Symbol) -> self
     def queue_resume: (String | Symbol) -> bool
     def queue_update: (String | Symbol, metadata: Hash[untyped, untyped]) -> Queue
+    def request_resign: () -> nil
     def start: () -> self
     def started?: () -> bool
     def stop: (?wait: bool) -> self
@@ -60,7 +63,7 @@ module River
     TAG_RE: Regexp
 
     private def insert_and_check_unique_job: (Driver::JobInsertParams) -> JobInsertResult
-    private def make_insert_params: (jobArgs, InsertOpts) -> Driver::JobInsertParams
+    private def make_insert_params: (jobArgs, InsertOpts, ?Time?) -> Driver::JobInsertParams
     private def make_unique_key_and_bitmask: (Driver::JobInsertParams, UniqueOpts) -> [String, String]
     private def run_insert_plugins: (Array[Driver::JobInsertParams]) { () -> Array[JobInsertResult] } -> Array[JobInsertResult]
     private def truncate_time: (Time, Integer | Rational) -> Time

data/sig/driver.rbs

@@ -1,6 +1,8 @@
 module River
   interface _Driver
+    def after_commit: () { () -> void } -> void
     def respond_to?: (Symbol, ?bool) -> bool
+    def in_transaction?: () -> bool
     def init_driver: () -> void
     def migration_backend: () -> Symbol
     def migration_connection: [A] () { (untyped) -> A } -> A
@@ -13,11 +15,11 @@ module River
     def job_get_available: (queue: String, max: Integer, attempted_by: String, ?kinds: Array[String]?, ?now: Time) -> Array[JobRow]
     def job_claim: (id: Integer, attempted_by: String, ?allow_scheduled: bool, ?now: Time) -> JobRow?
     def job_get_cancelled_ids: (Array[Integer]) -> Array[Integer]
-    def job_complete: (id: Integer, finalized_at: Time, ?metadata: Hash[untyped, untyped]?, ?now: Time) -> (JobRow | :cancelled)?
+    def job_complete: (id: Integer, finalized_at: Time, ?expected_job: JobRow?, ?metadata: Hash[untyped, untyped]?, ?now: Time) -> (JobRow | :cancelled)?
     def job_get_by_kind_and_unique_properties: (Driver::JobGetByKindAndUniquePropertiesParam) -> JobRow?
     def job_insert: (Driver::JobInsertParams) -> [JobRow, bool]
     def job_insert_many: (Array[Driver::JobInsertParams]) -> Array[[JobRow, bool]]
-    def job_metadata_merge: (Integer, Hash[untyped, untyped]) -> JobRow?
+    def job_metadata_merge: (Integer, Hash[untyped, untyped], ?JobRow?) -> JobRow?
     def job_rescue_stuck: (**untyped) -> Integer
     def job_retry: (Integer, ?now: Time) -> JobRow?
     def job_schedule: (?now: Time, ?max: Integer) -> Integer
@@ -26,13 +28,17 @@ module River
     def leader_acquire: (String, ?ttl: Integer, ?now: Time) -> bool
     def leader_release: (String) -> untyped
     def leader_renew: (String, ?ttl: Integer, ?now: Time) -> bool
+    def normalize_time: (Time) -> Time
     def notification_delete_before: (horizon: Time, ?max: Integer) -> Integer
+    def notification_listener: () -> untyped
+    def request_resign: () -> nil
     def queue_get: (String) -> Queue?
     def queue_list: (?max: Integer) -> Array[Queue]
     def queue_pause: (String, ?now: Time) -> Array[Queue]
     def queue_resume: (String, ?now: Time) -> Array[Queue]
     def queue_update: (String, metadata: Hash[untyped, untyped], ?now: Time) -> Queue?
     def queue_upsert: (String, ?metadata: Hash[untyped, untyped], ?now: Time) -> Queue?
+    def time_precision: () -> Rational
     def transaction: [T] () { () -> T } -> T
 
     # this set of methods is used only in tests
@@ -56,6 +62,25 @@ module River
       def finish: (JobRow) -> JobRow
     end
 
+    module NotificationListener
+      TOPICS: Array[String]
+      class Postgres
+        @connection: untyped
+        @channels: Hash[String, String]
+        def initialize: (untyped, String) -> void
+        def close: () -> untyped
+        def poll: (Float | Integer) -> Array[untyped]
+      end
+
+      class SQLite
+        @query: untyped
+        @last_id: Integer
+        def initialize: (untyped) -> void
+        def close: () -> nil
+        def poll: (Float | Integer) -> Array[untyped]
+      end
+    end
+
     class PostgresCapabilities
       attr_reader supports_listen_notify: bool
       attr_reader unique_insert_mode: :metadata_nonce | :returning_old | :xmax
@@ -103,10 +128,11 @@ module River
       def runtime_decode_postgres_job: (untyped) -> JobRow
       @postgres_capabilities_cache: PostgresCapabilities::Cache
       def init_driver: () -> void
+      def normalize_time: (Time) -> Time
       def postgres_capabilities: () -> PostgresCapabilities
       def postgres_notify_insert: (Array[JobInsertParams]) -> void
       def job_get_cancelled_ids: (Array[Integer]) -> Array[Integer]
-      def job_complete: (id: untyped, finalized_at: untyped, ?metadata: untyped, ?now: untyped) -> untyped
+      def job_complete: (id: untyped, finalized_at: untyped, ?expected_job: untyped, ?metadata: untyped, ?now: untyped) -> untyped
       def job_cancel: (untyped, ?now: untyped) -> untyped
       def job_delete: (untyped) -> untyped
       def job_delete_finalized: (retention: untyped, ?now: untyped, ?max: untyped) -> untyped
@@ -116,7 +142,7 @@ module River
       def job_claim: (id: untyped, attempted_by: untyped, ?allow_scheduled: untyped, ?now: untyped) -> untyped
       private def runtime_claim_jobs: (untyped, untyped, untyped, untyped) -> untyped
       def job_list: (?untyped) -> untyped
-      def job_metadata_merge: (untyped, untyped) -> untyped
+      def job_metadata_merge: (untyped, untyped, ?untyped) -> untyped
       def job_rescue_stuck: (horizon: untyped, retry_policy: untyped, ?now: untyped, ?max: untyped, ?logger: untyped, ?rescue_if: untyped) -> untyped
       def job_retry: (untyped, ?now: untyped) -> untyped
       def job_schedule: (?now: untyped, ?max: untyped) -> untyped
@@ -126,6 +152,8 @@ module River
       def leader_release: (untyped) -> untyped
       def leader_renew: (untyped, ?ttl: untyped, ?now: untyped) -> untyped
       def notification_delete_before: (horizon: untyped, ?max: untyped) -> untyped
+      def notification_listener: () -> untyped
+      def request_resign: () -> nil
       def queue_get: (untyped) -> untyped
       def queue_list: (?max: untyped) -> untyped
       def queue_pause: (untyped, ?now: untyped) -> untyped
@@ -133,6 +161,8 @@ module River
       def queue_update: (untyped, metadata: untyped, ?now: untyped) -> untyped
       def queue_upsert: (untyped, ?metadata: untyped, ?now: untyped) -> untyped
 
+      def time_precision: () -> Rational
+
       private
 
       def job_get_by_id: (untyped) -> untyped
@@ -142,14 +172,18 @@ module River
       def runtime_cursor_clause: (untyped) -> String
       def runtime_execute: (String) -> untyped
       def runtime_in_clause: (untyped, untyped) -> untyped
+      def runtime_job_attempt_predicate: (untyped) -> 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_json: (untyped) -> untyped
+      def runtime_legacy_subtransactions?: () -> bool
       def runtime_merge_metadata: (untyped) -> untyped
       def runtime_metadata_equals: (untyped, untyped) -> untyped
       def runtime_nullable_time: (untyped) -> untyped
       def runtime_notify: (String, untyped) -> untyped
+      def notification_query: (String) -> untyped
+      def runtime_notification_connection: () -> untyped
       def sqlite_insert_nonces: (Array[JobInsertParams]) -> Array[String]
       def runtime_parse_json: (untyped) -> untyped
       def runtime_parse_time: (untyped) -> untyped
@@ -160,10 +194,11 @@ module River
       def runtime_quote: (untyped) -> String
       def runtime_rescue_retry: (untyped, untyped, untyped, untyped, untyped) -> Time
       def runtime_returning_ids: (untyped) -> untyped
+      def runtime_schedule_postgres: (Time, Integer) -> Array[String]
+      def runtime_schedule_sqlite: (Time, Integer) -> Array[String]
       def runtime_state: (untyped) -> untyped
       def runtime_tag_contains: (untyped) -> untyped
       def runtime_time: (untyped) -> untyped
-      def runtime_unique_violation_class: () -> singleton(Exception)
       def runtime_update_value: (untyped, untyped) -> untyped
       def runtime_value: (untyped, untyped) -> untyped
       def transaction: () { () -> untyped } -> untyped

data/sig/runtime.rbs

@@ -77,21 +77,32 @@ module River
     @workers: Hash[String, untyped]
     def initialize: () -> void
     def add: (untyped, ?untyped, ?aliases: Array[untyped]) -> self
+           | (String | Symbol, ?aliases: Array[untyped]) { (Job) -> untyped } -> self
     def []: (String | Symbol) -> untyped
     def fetch: (String | Symbol) -> untyped
              | (String | Symbol, untyped) -> untyped
              | (String | Symbol) { (String) -> untyped } -> untyped
     def include?: (String | Symbol) -> bool
     def kinds: () -> Array[String]
+
+    class BlockWorker
+      @work_func: ^(Job) -> untyped
+      def initialize: (^(Job) -> untyped) -> void
+      def work: (Job) -> untyped
+    end
   end
 
   class Job
     RESUMABLE_CURSOR_UNSET: Object
+    @__completion_attempted: bool
+    @__completion_snapshot: JobRow?
     @client: Client
     @logger: untyped
     @metadata_updates: Hash[String, untyped]
     @resumable_state: ResumableState
     @row: JobRow
+    attr_accessor __completion_attempted: bool
+    attr_accessor __completion_snapshot: JobRow?
     attr_reader client: Client
     attr_reader row: JobRow
     def initialize: (Client, JobRow) -> void
@@ -126,6 +137,7 @@ module River
     attr_accessor completed_step: String?
     attr_reader cursors: Hash[String, untyped]
     attr_accessor cursors_dirty: bool
+    attr_reader pending_cursor_steps: Array[String]
     attr_accessor resume_matched: bool
     attr_reader resume_step: String?
     attr_accessor step_name: String?
@@ -152,15 +164,30 @@ module River
     def resolved_fetch_poll_interval: (Config) -> Float
   end
 
+  class DefaultClientID
+    HOSTNAME_MAX_LENGTH: Integer
+    @mutex: Mutex
+    @state: Hash[Integer, String]?
+    def initialize: () -> void
+    def value: () -> String
+
+    private
+
+    def generate: (Integer) -> String
+  end
+
   class Config
+    @poll_only: bool
+    attr_reader poll_only: bool
     @cancelled_job_retention_period: Float?
     @completed_job_retention_period: Float?
+    @default_id: DefaultClientID
     @discarded_job_retention_period: Float?
     @error_handler: untyped
     @fetch_cooldown: Float
     @fetch_only_known_kinds: bool
     @fetch_poll_interval: Float
-    @id: String
+    @id: String?
     @job_timeout: Float?
     @leader_election_disabled: bool
     @logger: untyped
@@ -178,7 +205,6 @@ module River
     attr_reader fetch_cooldown: Float
     attr_reader fetch_only_known_kinds: bool
     attr_reader fetch_poll_interval: Float
-    attr_reader id: String
     attr_reader job_timeout: Float?
     attr_reader leader_election_disabled: bool
     attr_reader logger: untyped
@@ -191,13 +217,16 @@ module River
 
     def initialize: (?queues: untyped, ?workers: untyped, ?id: untyped,
       ?fetch_cooldown: untyped, ?fetch_only_known_kinds: bool, ?fetch_poll_interval: untyped, ?job_timeout: untyped,
-      ?leader_election_disabled: bool,
+      ?leader_election_disabled: bool, ?poll_only: bool,
       ?retry_policy: untyped, ?error_handler: untyped, ?plugins: untyped,
       ?maintenance_services: untyped, ?periodic_jobs: untyped,
       ?cancelled_job_retention_period: untyped, ?completed_job_retention_period: untyped,
       ?discarded_job_retention_period: untyped, ?logger: untyped) -> void
+    def id: () -> String
     def with: (**untyped) -> Config
 
+    def adopt_default_id: (DefaultClientID) -> void
+
     private
 
     def normalize_queues: (untyped) -> Hash[String, QueueConfig]
@@ -308,6 +337,7 @@ module River
     @next_handle: Integer
     @wake: untyped
     def initialize: (Array[PeriodicJob], wake: untyped, ?enabled: bool) -> void
+    def __due_with_times: (Time) ?{ (PeriodicJob, StandardError) -> void } -> Array[[PeriodicJob, Time]]
     def add: (PeriodicJob) -> Integer
     def add_many: (Array[PeriodicJob]) -> Array[Integer]
     def clear: () -> self
@@ -334,13 +364,22 @@ module River
     @condition: ConditionVariable
     @config: Config
     @driver: _Driver
+    @fetching_queues: Hash[String, Array[Integer]]
+    @leader: bool
+    @maintenance_condition: ConditionVariable
+    @maintenance_generation: Integer
     @maintenance_thread: Thread?
     @mutex: Mutex
-    @periodic_jobs: PeriodicJobBundle
+    @notification_thread: Thread?
+    @notifications_disabled: bool
     @performing: bool?
+    @periodic_jobs: PeriodicJobBundle
     @producer_threads: Hash[String, Thread]
     @queue_configs: Hash[String, QueueConfig]
+    @queue_generations: Hash[String, Integer]
+    @queue_paused: Hash[String, bool]
     @removed_queues: Hash[String, bool]
+    @resign_requested: bool
     @running: Hash[Integer, untyped]
     @started: bool
     @stop_requested: bool
@@ -373,6 +412,7 @@ module River
     def finish_failed: (JobRow, Job, Exception, JobTiming, ?cancelled: bool, ?worker: untyped) -> untyped
     def finish_interrupted: (JobRow, Job, JobTiming) -> untyped
     def finish_snoozed: (JobRow, Job, JobSnoozeError, JobTiming) -> untyped
+    def finish_transactional_completion: (Job, JobTiming) -> bool
     def finish_work: (Integer) -> untyped
     def invoke_plugins: (Symbol, *untyped) -> Array[untyped]
     def invoke_worker: (untyped, Job) -> untyped
@@ -381,22 +421,30 @@ module River
     def monotonic_now: () -> Float
     def next_retry: (JobRow, Exception, Time, ?worker: untyped) -> Time
     def next_snooze_count: (untyped) -> Integer
+    def notification_loop: (untyped) -> untyped
+    def notifications_stopping?: () -> bool
     def retry_allowed?: (untyped, Job, Exception) -> untyped
     def perform_work: (untyped, Job) -> untyped
     def periodic_jobs_changed: () -> untyped
     def producer_loop: (String, QueueConfig) -> untyped
     def publish: (Symbol, JobRow, JobTiming) -> untyped
     def queue_stopping?: (String) -> bool
+    def receive_notification: (untyped, untyped) -> untyped
     def remove_subscription: (Subscription) -> Subscription?
     def rescue_job?: (JobRow, Time) -> bool
     def resolve_worker: (String) -> untyped
     def run_periodic: (Time) -> untyped
     def running_count: (String) -> Integer
     def start_maintenance: () -> untyped
+    def start_notifications: () -> untyped
     def start_producer: (String, QueueConfig) -> untyped
     def stopping?: () -> bool
     def wait: (Float | Integer) -> 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
+    def wake_maintenance: () -> untyped
+    def wake_queue: (String) -> untyped
     def worker_timeout: (untyped, Job) -> Float?
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riverqueue
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Blake Gentry
@@ -91,7 +91,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1000'
 description: Insert and work River jobs in Ruby using the same schema and state machine
-  as River's Go client. Use with riverqueue-activerecord or riverqueue-sequel.
+  as other River clients. Use with riverqueue-activerecord or riverqueue-sequel.
 email: brandur@brandur.org
 executables:
 - river
@@ -113,6 +113,7 @@ files:
 - lib/config.rb
 - lib/driver.rb
 - lib/driver/job_row_decoder.rb
+- lib/driver/notification_listener.rb
 - lib/driver/postgres_capabilities.rb
 - lib/driver/runtime.rb
 - lib/errors.rb
@@ -205,5 +206,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.9
 specification_version: 4
-summary: A fast, reliable job queue for Ruby backed by PostgreSQL or SQLite.
+summary: A fast, reliable job queue for Ruby backed by Postgres or SQLite.
 test_files: []