riverqueue 0.12.0 → 0.14.0

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
@@ -8,16 +10,16 @@ module River
     def job_cancel: (Integer, ?now: Time) -> JobRow?
     def job_delete: (Integer) -> JobRow?
     def job_delete_finalized: (**untyped) -> Integer
-    def job_delete_if_running: (Integer) -> bool
+    def job_delete_if_running: (Integer) -> (bool | :cancelled)
     def job_delete_many: (JobListParams) -> Array[JobRow]
     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) -> untyped
-    def queue_resume: (String, ?now: Time) -> untyped
+    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,8 +142,8 @@ 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_rescue_stuck: (horizon: untyped, retry_policy: untyped, ?now: untyped, ?max: 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
       def job_set_state_if_running: (id: untyped, state: untyped, ?now: untyped, ?attempt: untyped, ?error: untyped, ?finalized_at: untyped, ?metadata: untyped, ?scheduled_at: 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,13 +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
@@ -157,11 +192,13 @@ module River
       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_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/insert_opts.rbs

@@ -5,11 +5,11 @@ module River
     attr_accessor priority: Integer?
     attr_accessor queue: (String | Symbol)?
     attr_accessor scheduled_at: Time?
-    attr_accessor state: jobStateInput?
+    attr_accessor state: jobStateInitialInput?
     attr_accessor tags: Array[String]?
     attr_accessor unique_opts: UniqueOpts?
 
-    def initialize: (?max_attempts: Integer?, ?metadata: Hash[String | Symbol, untyped]?, ?priority: Integer?, ?queue: (String | Symbol)?, ?scheduled_at: Time?, ?state: jobStateInput?, ?tags: Array[String]?, ?unique_opts: UniqueOpts?) -> void
+    def initialize: (?max_attempts: Integer?, ?metadata: Hash[String | Symbol, untyped]?, ?priority: Integer?, ?queue: (String | Symbol)?, ?scheduled_at: Time?, ?state: jobStateInitialInput?, ?tags: Array[String]?, ?unique_opts: UniqueOpts?) -> void
   end
 
   class UniqueOpts

data/sig/job.rbs

@@ -9,6 +9,8 @@ module River
   JOB_STATE_SCHEDULED: "scheduled"
 
   type jobStateAll = "available" | "cancelled" | "completed" | "discarded" | "pending" | "retryable" | "running" | "scheduled"
+  type jobStateInitial = "available" | "pending" | "scheduled"
+  type jobStateInitialInput = jobStateInitial | :available | :pending | :scheduled
   type jobStateInput = jobStateAll | :available | :cancelled | :completed | :discarded | :pending | :retryable | :running | :scheduled
 
   interface _JobArgs

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]
@@ -288,8 +317,11 @@ module River
 
   class PeriodicCron
     @cron: untyped
+    @interval: Integer?
     def initialize: (String, ?timezone: String) -> void
     def next: (Time) -> Time
+    private
+    def parse_interval: (String) -> Integer
   end
 
   class PeriodicInterval
@@ -299,15 +331,18 @@ module River
   end
 
   class PeriodicJobBundle
+    @enabled: bool
     @jobs: Hash[Integer, untyped]
     @mutex: Mutex
     @next_handle: Integer
     @wake: untyped
-    def initialize: (Array[PeriodicJob], wake: untyped) -> void
+    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
     def due: (Time) ?{ (PeriodicJob, StandardError) -> void } -> Array[PeriodicJob]
+    def empty?: () -> bool
     def remove: (Integer) -> PeriodicJob?
     def remove_by_id: (untyped) -> bool
   end
@@ -316,17 +351,35 @@ module River
     class Interrupted < StandardError
     end
 
+    class JobTiming
+      attr_accessor finished_monotonic: Float
+      attr_reader queue_wait_duration: Float
+      attr_reader started_at: Time
+      attr_reader started_monotonic: Float
+
+      def initialize: (Time, Float, Time) -> void
+    end
+
     @client: Client
     @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
@@ -356,8 +409,10 @@ module River
     def check_remote_cancellations: (String) -> untyped
     def error_handler_cancel?: (Exception, Job) -> bool
     def execute: (JobRow) -> untyped
-    def finish_failed: (JobRow, Job, Exception, Time, ?cancelled: bool, ?worker: untyped) -> untyped
-    def finish_snoozed: (JobRow, Job, JobSnoozeError, Time) -> untyped
+    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
@@ -365,18 +420,31 @@ module River
     def maintenance_loop: () -> untyped
     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, Time) -> 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.12.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
@@ -100,7 +100,9 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
+- README.md
 - docs/README.md
+- docs/conformance.md
 - docs/migrations.md
 - docs/testing.md
 - docs/workers.md
@@ -111,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
@@ -183,10 +186,10 @@ homepage: https://riverqueue.com
 licenses:
 - MPL-2.0
 metadata:
-  bug_tracker_uri: https://github.com/riverqueue/riverqueue-ruby/issues
-  changelog_uri: https://github.com/riverqueue/riverqueue-ruby/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/riverqueue/river/issues
+  changelog_uri: https://github.com/riverqueue/river/blob/master/ruby/CHANGELOG.md
   rubygems_mfa_required: 'true'
-  source_code_uri: https://github.com/riverqueue/riverqueue-ruby
+  source_code_uri: https://github.com/riverqueue/river/tree/master/ruby
 rdoc_options: []
 require_paths:
 - lib
@@ -203,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: []