riverqueue 0.11.0 → 0.13.0

data/lib/driver.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module River
   # Contains an interface used by the top-level River module to interface with
   # its driver implementations. All types and methods in this module should be
@@ -7,9 +9,11 @@ module River
     # Insert parameters for a job. This is sent to underlying drivers and is meant
     # for internal use only. Its interface is subject to change.
     class JobInsertParams
+      attr_accessor :args
       attr_accessor :encoded_args
       attr_accessor :kind
       attr_accessor :max_attempts
+      attr_accessor :metadata
       attr_accessor :priority
       attr_accessor :queue
       attr_accessor :scheduled_at
@@ -22,17 +26,16 @@ module River
         encoded_args:,
         kind:,
         max_attempts:,
-        priority:,
-        queue:,
-        scheduled_at:,
-        state:,
-        tags:,
+        priority:, queue:, scheduled_at:, state:, tags:, metadata: {},
         unique_key: nil,
-        unique_states: nil
+        unique_states: nil,
+        args: nil
       )
+        self.args = args
         self.encoded_args = encoded_args
         self.kind = kind
         self.max_attempts = max_attempts
+        self.metadata = metadata
         self.priority = priority
         self.queue = queue
         self.scheduled_at = scheduled_at
@@ -44,3 +47,7 @@ module River
     end
   end
 end
+
+require_relative "driver/postgres_capabilities"
+require_relative "driver/job_row_decoder"
+require_relative "driver/runtime"

data/lib/errors.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module River
+  class Error < StandardError; end
+
+  class NotFoundError < Error; end
+
+  class JobRunningError < Error; end
+
+  # A stored job contains fields that cannot be decoded. Administrative reads
+  # raise this error; consumers fail this job's attempt without blocking peers.
+  class JobRowDecodeError < Error
+    attr_reader :job
+
+    def initialize(job, detail)
+      @job = job
+      super("job row #{job.id} couldn't be decoded: #{detail}")
+      job.__decode_error = self
+    end
+  end
+
+  class JobCancelError < Error
+    # Original exception that caused cancellation, when supplied.
+    attr_reader :cause
+
+    def initialize(message = "job cancelled", cause: nil)
+      @cause = cause
+      super(message)
+    end
+  end
+
+  class JobSnoozeError < Error
+    # Number of seconds for which the job should be snoozed.
+    attr_reader :duration
+
+    def initialize(duration)
+      @duration = Float(duration, exception: true) #: Float
+      raise ArgumentError, "duration must be finite" unless @duration.finite?
+      raise ArgumentError, "duration must be zero or greater" if @duration.negative?
+
+      super("job snoozed for #{@duration} seconds")
+    end
+  end
+
+  class UnknownJobKindError < Error
+    # Unregistered job kind encountered by the runtime.
+    attr_reader :kind
+
+    def initialize(kind)
+      @kind = kind
+      super("unknown job kind: #{kind}")
+    end
+  end
+
+  class ClientNotStartedError < Error; end
+
+  class ClientAlreadyStartedError < Error; end
+
+  # Returns an exception that tells River to cancel the current job.
+  #
+  # An Exception argument is retained as the cancellation's cause; any other
+  # non-nil argument is used as its message. Raise the result from a worker:
+  #
+  #   raise River.job_cancel("account closed")
+  def self.job_cancel(error = nil)
+    case error
+    when Exception
+      JobCancelError.new(error.message, cause: error)
+    when nil
+      JobCancelError.new
+    else
+      JobCancelError.new(error.to_s)
+    end
+  end
+
+  # Returns an exception that tells River to reschedule the current job after
+  # +duration+ seconds without treating the attempt as an error.
+  #
+  #   raise River.job_snooze(30)
+  def self.job_snooze(duration)
+    JobSnoozeError.new(duration)
+  end
+end

data/lib/event.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module River
+  EVENT_JOB_CANCELLED = :job_cancelled
+  EVENT_JOB_COMPLETED = :job_completed
+  EVENT_JOB_FAILED = :job_failed
+  EVENT_JOB_INTERRUPTED = :job_interrupted
+  EVENT_JOB_SNOOZED = :job_snoozed
+  EVENT_QUEUE_PAUSED = :queue_paused
+  EVENT_QUEUE_RESUMED = :queue_resumed
+
+  # Event emitted by a Client and delivered through a Subscription.
+  Event = Data.define(:kind, :job, :queue, :stats)
+
+  # Timing statistics attached to job lifecycle events, in seconds.
+  # run_duration measures worker execution including work hooks;
+  # complete_duration measures finalization after execution finishes.
+  # queue_wait_duration uses the schedule at the start of execution, before
+  # retries or snoozes change it.
+  # Execution and completion durations use a monotonic clock. Externally
+  # executed jobs have zero run_duration because this runtime does not observe
+  # their execution; their queue wait ends at the row's attempted_at timestamp.
+  JobStatistics = Data.define(:complete_duration, :queue_wait_duration, :run_duration)
+
+  # Bounded stream of selected Client lifecycle events.
+  class Subscription
+    # Creates an event subscription. Applications normally receive instances
+    # from Client#subscribe.
+    def initialize(kinds, buffer_size: 100, on_close: nil)
+      @closed = false
+      @kinds = kinds.map(&:to_sym).freeze
+      @mutex = Mutex.new
+      @on_close = on_close
+      @queue = SizedQueue.new(buffer_size)
+    end
+
+    # Closes the subscription and releases it from its client. Closing more than
+    # once is safe. Buffered events remain readable; blocked readers wake once
+    # the buffer is drained.
+    def close
+      on_close = @mutex.synchronize do
+        return if @closed
+
+        @closed = true
+        @queue.close
+        @on_close.tap { @on_close = nil }
+      end
+
+      on_close&.call(self)
+      nil
+    end
+
+    # Yields events as they arrive until the subscription is closed. Returns an
+    # Enumerator when no block is given.
+    def each
+      return enum_for(:each) unless block_given?
+
+      loop do
+        event = @queue.pop
+        break if event.nil?
+
+        yield event
+      end
+    end
+
+    # Removes and returns the next queued value, blocking unless +non_block+ is
+    # true. A blocking pop returns nil once the subscription is closed and its
+    # buffered events have been drained.
+    #
+    # A non-blocking pop raises ThreadError when no event is available.
+    def pop(non_block = false)
+      @queue.pop(non_block)
+    end
+
+    def publish(event)
+      @mutex.synchronize do
+        return if @closed || !@kinds.include?(event.kind)
+
+        @queue.push(event, true)
+      end
+    rescue ThreadError
+      nil
+    end
+  end
+end

data/lib/insert_opts.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module River
   # Options for job insertion, and which can be provided by implementing
   # #insert_opts on job args, or specified as a parameter on #insert or
@@ -5,8 +7,14 @@ module River
   class InsertOpts
     # The maximum number of total attempts (including both the original run and
     # all retries) before a job is abandoned and set as discarded.
+    # Must be between 1 and MAX_ATTEMPTS_LIMIT (32,767).
+    # Defaults to MAX_ATTEMPTS_DEFAULT.
     attr_accessor :max_attempts
 
+    # Arbitrary metadata to merge into the persisted job. River and River Pro
+    # reserve keys prefixed with `river:` and workflow metadata keys.
+    attr_accessor :metadata
+
     # The priority of the job, with 1 being the highest priority and 4 being the
     # lowest. When fetching available jobs to work, the highest priority jobs
     # will always be fetched before any lower priority jobs are fetched. Note
@@ -16,7 +24,8 @@ module River
     # Defaults to PRIORITY_DEFAULT.
     attr_accessor :priority
 
-    # The name of the job queue in which to insert the job.
+    # The name of the job queue in which to insert the job, as a symbol or string.
+    # Must contain 1 to 127 ASCII letters, digits, underscores, hyphens, colons, or periods.
     #
     # Defaults to QUEUE_DEFAULT.
     attr_accessor :queue
@@ -31,6 +40,11 @@ module River
     # it will work in both cases.
     attr_accessor :scheduled_at
 
+    # Initial state. Primarily intended for extensions such as workflows and
+    # sequences, which insert blocked jobs as `:pending`. Accepts only
+    # `available`, `pending`, or `scheduled`, as symbols or strings.
+    attr_accessor :state
+
     # An arbitrary list of keywords to add to the job. They have no functional
     # behavior and are meant entirely as a user-specified construct to help
     # group and categorize jobs.
@@ -43,18 +57,23 @@ module River
     # is never treated as unique.
     attr_accessor :unique_opts
 
+    # Creates options that override the defaults for a single job insertion.
     def initialize(
       max_attempts: nil,
+      metadata: nil,
       priority: nil,
       queue: nil,
       scheduled_at: nil,
+      state: nil,
       tags: nil,
       unique_opts: nil
     )
       self.max_attempts = max_attempts
+      self.metadata = metadata
       self.priority = priority
       self.queue = queue
       self.scheduled_at = scheduled_at
+      self.state = state
       self.tags = tags
       self.unique_opts = unique_opts
     end
@@ -62,9 +81,10 @@ module River
 
   # Parameters for uniqueness for a job.
   #
-  # If all properties are nil, no uniqueness at is enforced. As each property is
+  # If all properties are nil, no uniqueness is enforced. As each property is
   # initialized, it's added as a dimension on the uniqueness matrix, and with
-  # any property on, the job's kind always counts toward uniqueness.
+  # any property on, the job's kind counts toward uniqueness unless #exclude_kind
+  # is enabled.
   #
   # So for example, if only #by_queue is on, then for the given job kind, only a
   # single instance is allowed in any given queue, regardless of other
@@ -73,20 +93,28 @@ module River
   # and queues. If either args or queue is changed on a new job, it's allowed to
   # be inserted as a new job.
   class UniqueOpts
+    # Empty options don't enable uniqueness. Zero periods and empty state lists
+    # have the same meaning as their unset equivalents in the Go client.
+    def empty?
+      !by_args && !by_queue && !exclude_kind && (!by_period || by_period == 0) && (!by_state || by_state.empty?)
+    end
+
     # Indicates that uniqueness should be enforced for any specific instance of
-    # encoded args for a job.
+    # encoded args for a job. An array of symbol or string keys selects only
+    # those top-level arguments. Nested arrays select paths, for example
+    # +by_args: [[:account, :id], :label]+. Dots in a string key are literal.
     #
     # Default is false, meaning that as long as any other unique property is
     # enabled, uniqueness will be enforced for a kind regardless of input args.
     attr_accessor :by_args
 
-    # Defines uniqueness within a given period. On an insert time is rounded
-    # down to the nearest multiple of the given period, and a job is only
-    # inserted if there isn't an existing job that will run between then and the
-    # next multiple of the period.
+    # Defines uniqueness within a given period. The effective scheduled time
+    # (or current time for unscheduled jobs) is rounded down to a period boundary
+    # in UTC. Equivalent times in different zones produce the same unique key.
     #
     # The period should be specified in seconds. So a job that's unique every 15
-    # minute period would have a value of 900.
+    # minute period would have a value of 900. Nonzero periods must be at least
+    # one second; zero disables period-based uniqueness.
     #
     # Default is no unique period, meaning that as long as any other unique
     # property is enabled, uniqueness will be enforced across all jobs of the
@@ -108,21 +136,27 @@ module River
     # Unlike other unique options, ByState gets a default when it's not set for
     # user convenience. The default is equivalent to:
     #
-    #   by_state: [River::JOB_STATE_AVAILABLE, River::JOB_STATE_COMPLETED, River::JOB_STATE_PENDING, River::JOB_STATE_RUNNING, River::JOB_STATE_RETRYABLE, River::JOB_STATE_SCHEDULED]
+    #   by_state: %i[available completed pending running retryable scheduled]
     #
-    # With this setting, any jobs of the same kind that have been completed or
+    # With this setting, any jobs of the same kind that have been cancelled or
     # discarded, but not yet cleaned out by the system, won't count towards the
     # uniqueness of a new insert.
     #
     # The pending, scheduled, available, and running states are required when
-    # customizing this list.
+    # customizing this list. State names accept symbols or strings.
     attr_accessor :by_state
 
     # Indicates that the job kind should not be considered for uniqueness. This
     # is useful when you want to enforce uniqueness based on other properties
     # across multiple worker types.
+    #
+    # Requires #by_args, #by_queue, or a nonzero #by_period. Otherwise every job
+    # would share the same key, so insertion raises ArgumentError. #by_state
+    # alone does not supply a key dimension.
     attr_accessor :exclude_kind
 
+    # Creates a set of dimensions used to determine whether an inserted job is
+    # unique.
     def initialize(
       by_args: nil,
       by_period: nil,

data/lib/job.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module River
   JOB_STATE_AVAILABLE = "available"
   JOB_STATE_CANCELLED = "cancelled"
@@ -10,36 +12,38 @@ module River
 
   # Provides a way of creating a job args from a simple Ruby hash for a quick
   # way to insert a job without having to define a class. The first argument is
-  # a "kind" string for identifying the job in the database and the second is a
+  # a kind (symbol or string) identifying the job in the database and the second is a
   # hash that will be encoded to JSON.
   #
   # For example:
   #
-  #   insert_res = client.insert(River::JobArgsHash.new("job_kind", {
+  #   insert_res = client.insert(River::JobArgsHash.new(:job_kind, {
   #     job_num: 1
   #   }))
   class JobArgsHash
+    # Job kind persisted to the database.
+    attr_reader :kind
+
+    # Creates job arguments with a database kind and JSON-compatible hash.
     def initialize(kind, hash)
-      raise "kind should be non-nil" if !kind
-      raise "hash should be non-nil" if !hash
+      raise ArgumentError, "kind should be non-nil" if !kind
+      raise ArgumentError, "hash should be non-nil" if !hash
 
-      @kind = kind
       @hash = hash
+      @kind = kind.to_s
     end
 
-    attr_reader :kind
-
+    # Encodes the argument hash for insertion.
     def to_json
-      JSON.dump(@hash)
+      # JSON.dump reads mutable global options that are inaccessible in Ractors.
+      JSON.generate(@hash)
     end
   end
 
   # JobRow contains the properties of a job that are persisted to the database.
   class JobRow
-    # ID of the job. Generated as part of a Postgres sequence and generally
-    # ascending in nature, but there may be gaps in it as transactions roll
-    # back.
-    attr_accessor :id
+    # Internal driver/runtime diagnostic, not a persisted column.
+    attr_accessor :__decode_error
 
     # The job's args as a hash decoded from JSON.
     attr_accessor :args
@@ -72,6 +76,11 @@ module River
     # retried.
     attr_accessor :finalized_at
 
+    # ID of the job. Generated as part of a Postgres sequence and generally
+    # ascending in nature, but there may be gaps in it as transactions roll
+    # back.
+    attr_accessor :id
+
     # Kind uniquely identifies the type of job and instructs which worker
     # should work it. It is set at insertion time via `#kind` on job args.
     attr_accessor :kind
@@ -163,7 +172,8 @@ module River
   # A failed job work attempt containing information about the error or panic
   # that occurred.
   class AttemptError
-    # The time at which the error occurred.
+    # The time at which the error occurred. Unreadable historical timestamps
+    # become Time.utc(1), matching Go's zero time.
     attr_accessor :at
 
     # The attempt number on which the error occurred (maps to #attempt on a job
@@ -189,5 +199,10 @@ module River
       self.error = error
       self.trace = trace
     end
+
+    # Returns the database-compatible representation of this attempt error.
+    def to_h
+      {at: at.getutc.iso8601(6), attempt: attempt, error: error, trace: trace}
+    end
   end
 end

data/lib/job_persisted_logging/plugin.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module River
+  module JobPersistedLogging
+    # Captures job.logger output and persists it with the attempt's state change,
+    # including failed attempts. Uses Go riverlog's metadata format for River UI.
+    # Register through Config#plugins, preferably before other work middleware.
+    class Plugin
+      # Limits are positive byte counts. History is capped at 64 MiB, dropping
+      # oldest entries first, but always retaining the newest attempt. An optional
+      # block receives a bounded writer and must return a fresh logger per attempt.
+      # By default this is a standard Ruby Logger at INFO level.
+      def initialize(max_size_bytes: 2 * 1024 * 1024, max_total_bytes: 8 * 1024 * 1024, &logger_factory)
+        {max_size_bytes: max_size_bytes, max_total_bytes: max_total_bytes}.each do |name, value|
+          raise ArgumentError, "#{name} must be a positive integer" unless value.is_a?(Integer) && value.positive?
+        end
+
+        @logger_factory = logger_factory
+        @max_size_bytes = max_size_bytes
+        @max_total_bytes = [max_total_bytes, 64 * 1024 * 1024].min
+      end
+
+      # Wraps the work hooks and worker without changing their return value or
+      # exception. No extra database round trip is needed to save the log.
+      def work(job, operation)
+        buffer = Buffer.new(@max_size_bytes)
+        factory = @logger_factory
+        logger = factory ? factory.call(buffer) : Logger.new(buffer, level: Logger::INFO)
+        begin
+          job.__with_logger(logger) { operation.call }
+        ensure
+          persist_log(job, buffer)
+        end
+      end
+
+      private def persist_log(job, buffer)
+        log, truncated = buffer.finish
+        return if log.empty?
+
+        history = job.metadata.fetch("river:log", [])
+        raise TypeError, '"river:log" value is not an array' unless history.is_a?(Array)
+
+        entries = [{"attempt" => job.row.attempt, "log" => log}]
+        size = JSON.generate(entries.first).bytesize + 2 # Array brackets.
+        # Walk only the newest suffix that fits; never repeatedly serialize or
+        # shift the entire history. Keep the latest entry even if it exceeds the cap.
+        history.reverse_each do |entry|
+          entry_size = JSON.generate(entry).bytesize + 1 # Separator comma.
+          break if size + entry_size > @max_total_bytes
+
+          entries << entry
+          size += entry_size
+        end
+        job.update_metadata("river:log" => entries.reverse)
+
+        job.client.config.logger.warn("River job log truncated to #{@max_size_bytes} bytes for job #{job.row.id}") if truncated
+        dropped = history.length + 1 - entries.length
+        job.client.config.logger.warn("River job log dropped #{dropped} oldest entries for job #{job.row.id}") if dropped.positive?
+      rescue JSON::JSONError, TypeError => error
+        # Corrupt history must not hide the worker's original error or turn
+        # otherwise successful work into a failure.
+        job.client.config.logger.error("River job log could not be persisted for job #{job.row.id}: #{error.message}")
+      end
+
+      # A per-attempt, thread-safe writer. Bound memory while writing, rather than
+      # accumulating an unbounded StringIO and truncating only when work finishes.
+      class Buffer
+        def initialize(limit)
+          @closed = false
+          @data = String.new(encoding: Encoding::BINARY)
+          @limit = limit
+          @mutex = Mutex.new
+          @truncated = false
+        end
+
+        def close
+          @mutex.synchronize { @closed = true }
+          nil
+        end
+
+        def finish
+          @mutex.synchronize do
+            @closed = true
+            # Drop invalid/incomplete UTF-8 sequences (including a character cut
+            # at the byte limit) and NULs, which PostgreSQL JSONB cannot represent.
+            [@data.dup.force_encoding(Encoding::UTF_8).scrub("").delete("\0"), @truncated]
+          end
+        end
+
+        def write(message)
+          message = message.to_s
+          @mutex.synchronize do
+            unless @closed
+              remaining = @limit - @data.bytesize
+              chunk = message.byteslice(0, remaining) #: String
+              @data << chunk.force_encoding(Encoding::BINARY)
+              @truncated ||= message.bytesize > remaining
+            end
+          end
+          message.bytesize
+        end
+      end
+      private_constant :Buffer
+    end
+  end
+end

data/lib/migration_cli.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "riverqueue"
+
+module River
+  # Minimal command-line interface to the Ruby migration API.
+  module MigrationCLI
+    def self.run(argv, err: $stderr, out: $stdout)
+      # @type var database: untyped
+      # @type var active_record_base: untyped
+      options = {line: "main"} #: Hash[Symbol, untyped]
+      parser = OptionParser.new do |args|
+        args.banner = "Usage: river migrate-up|migrate-down|migrate-status [options]"
+        args.on("--database-url URL", "Defaults to DATABASE_URL") { |value| options[:url] = value }
+        args.on("--line NAME", %w[main pro]) { |value| options[:line] = value }
+        args.on("--schema NAME") { |value| options[:schema] = value }
+        args.on("--steps N", Integer) { |value| options[:steps] = value }
+        args.on("--target VERSION", Integer) { |value| options[:target] = value }
+        args.on("--dry-run") { options[:dry_run] = true }
+        args.on("--yes", "Confirm destructive down migrations") { options[:yes] = true }
+        args.on("-h", "--help") {
+          out.puts(args)
+          return 0
+        }
+      end
+
+      args = argv.dup
+      parser.parse!(args)
+      command = args.shift
+      raise ArgumentError, parser.banner unless %w[migrate-up migrate-down migrate-status].include?(command) && args.empty?
+
+      url = options[:url] || ENV["DATABASE_URL"]
+      raise ArgumentError, "provide --database-url or DATABASE_URL" if url.nil? || url.empty?
+
+      if command == "migrate-down" && !options[:yes] && !options[:dry_run]
+        raise ArgumentError, "down migrations may delete data; pass --yes to confirm"
+      end
+
+      adapter = detect_driver
+
+      if options[:line] == "pro"
+        require "riverqueue-pro"
+      end
+
+      migrator_class = (options[:line] == "pro") ? River.const_get(:Pro).const_get(:Migrator) : River::Migrator
+      if adapter == "activerecord"
+        require "riverqueue-activerecord"
+        active_record_base = Object.const_get("ActiveRecord::Base")
+        active_record_base.establish_connection(url)
+        driver = River::Driver.const_get(:ActiveRecord).new
+      else
+        require "riverqueue-sequel"
+        database = Object.const_get(:Sequel).connect(url)
+        driver = River::Driver.const_get(:Sequel).new(database)
+      end
+
+      migrator = migrator_class.new(driver, schema: options[:schema])
+      if command == "migrate-status"
+        migrator.status.each { |migration| out.puts("#{migration.applied ? "applied" : "pending"} #{migration.version.to_s.rjust(3, "0")} #{migration.name}") }
+      else
+        migrations = migrator.migrate(direction: (command == "migrate-up") ? :up : :down,
+          dry_run: !!options[:dry_run], steps: options[:steps], target: options[:target])
+        migrations.each { |migration| out.puts("#{options[:dry_run] ? "planned" : "applied"} #{migration.version.to_s.rjust(3, "0")} #{migration.name}") }
+      end
+
+      0
+    rescue StandardError, LoadError => error
+      # Do not echo connection exception messages, which may contain credentials.
+      message = (error.is_a?(ArgumentError) || error.is_a?(OptionParser::ParseError) || error.is_a?(River::Error)) ? error.message : error.class.name
+      err.puts("Migration failed: #{message}")
+      1
+    ensure
+      database&.disconnect
+      active_record_base&.connection_pool&.disconnect!
+    end
+
+    def self.detect_driver
+      driver = %w[sequel activerecord].find do |driver|
+        !Gem::Specification.find_all_by_name("riverqueue-#{driver}").empty?
+      end
+
+      unless driver
+        raise ArgumentError, "install riverqueue-activerecord or riverqueue-sequel in your bundle to run migrations"
+      end
+      driver
+    end
+    private_class_method :detect_driver
+  end
+end