riverqueue 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db28757576fce6283b32ae3509deb6eb3a66c2e20691e30a67f107fff5b553aa
-  data.tar.gz: d5e6b8447b5e5e9defcd2ab72f95cc1266d9bb488b0f9bf20a6ede96f47ce71f
+  metadata.gz: 8aa1b2a14e085df2b2a7e79fa6c6cd5b19aeb2c893a4fd369b99e469dd5916b9
+  data.tar.gz: 3cebd975dcadb223ecc163918b2e8bb0ce67bb671be99c6f706d3d9ec2da6507
 SHA512:
-  metadata.gz: 9fe6c2f467f9d79d5819a267f3b620481a179b6024339d3bafc20b2811599364daf4a7d85928d873a2a06b250b6a3ebc1783009b08b7e1251920d6d2d1b672c3
-  data.tar.gz: d06cfdf233641f120e2170f3ac694bb98ca04fa2556e9de8bbeaed117d98b56384de9b552e71c9526d6bda2ee15eea79c2475beec625bfb663329e77edfb30c0
+  metadata.gz: 868459a39a19fe9aacec7552b03148d97228ff58bdfb6b79a6e724c800cc97ef10017097a46f5132684d5d4e97ea9c788b83c813dcb6dc812835e9c0c9ec9645
+  data.tar.gz: '05538541ee6466adc722af9d6ab4cbf4c1a081a59c9eb887089b8abea8474415d61dfa9fdf827e4863ee393874258f09e6c54b06ffac87ddc90931f346f12f0b'

data/lib/client.rb

@@ -0,0 +1,330 @@
+require "digest"
+require "fnv"
+require "time"
+
+module River
+  # Default number of maximum attempts for a job.
+  MAX_ATTEMPTS_DEFAULT = 25
+
+  # Default priority for a job.
+  PRIORITY_DEFAULT = 1
+
+  # Default queue for a job.
+  QUEUE_DEFAULT = "default"
+
+  # Provides a client for River that inserts jobs. Unlike the Go version of the
+  # River client, this one can insert jobs only. Jobs can only be worked from Go
+  # code, so job arg kinds and JSON encoding details must be shared between Ruby
+  # and Go code.
+  #
+  # Used in conjunction with a River driver like:
+  #
+  #   DB = Sequel.connect(...)
+  #   client = River::Client.new(River::Driver::Sequel.new(DB))
+  #
+  # River drivers are found in separate gems like `riverqueue-sequel` to help
+  # minimize transient dependencies.
+  class Client
+    def initialize(driver, advisory_lock_prefix: nil)
+      @driver = driver
+      @advisory_lock_prefix = check_advisory_lock_prefix_bounds(advisory_lock_prefix)
+      @time_now_utc = -> { Time.now.utc } # for test time stubbing
+    end
+
+    # Inserts a new job for work given a job args implementation and insertion
+    # options (which may be omitted).
+    #
+    # With job args only:
+    #
+    #   insert_res = client.insert(SimpleArgs.new(job_num: 1))
+    #   insert_res.job # inserted job row
+    #
+    # With insert opts:
+    #
+    #   insert_res = client.insert(SimpleArgs.new(job_num: 1), insert_opts: InsertOpts.new(queue: "high_priority"))
+    #   insert_res.job # inserted job row
+    #
+    # Job arg implementations are expected to respond to:
+    #
+    #   * `#kind`: A string that uniquely identifies the job in the database.
+    #   * `#to_json`: Encodes the args to JSON for persistence in the database.
+    #     Must match encoding an args struct on the Go side to be workable.
+    #
+    # They may also respond to `#insert_opts` which is expected to return an
+    # `InsertOpts` that contains options that will apply to all jobs of this
+    # kind. Insertion options provided as an argument to `#insert` override
+    # those returned by job args.
+    #
+    # For example:
+    #
+    #   class SimpleArgs
+    #     attr_accessor :job_num
+    #
+    #     def initialize(job_num:)
+    #       self.job_num = job_num
+    #     end
+    #
+    #     def kind = "simple"
+    #
+    #     def to_json = JSON.dump({job_num: job_num})
+    #   end
+    #
+    # See also JobArgsHash for an easy way to insert a job from a hash.
+    #
+    # Returns an instance of InsertResult.
+    def insert(args, insert_opts: EMPTY_INSERT_OPTS)
+      insert_params, unique_opts = make_insert_params(args, insert_opts)
+      check_unique_job(insert_params, unique_opts) do
+        job = @driver.job_insert(insert_params)
+        InsertResult.new(job)
+      end
+    end
+
+    # Inserts many new jobs as part of a single batch operation for improved
+    # efficiency.
+    #
+    # Takes an array of job args or InsertManyParams which encapsulate job args
+    # and a paired InsertOpts.
+    #
+    # With job args:
+    #
+    #   num_inserted = client.insert_many([
+    #     SimpleArgs.new(job_num: 1),
+    #     SimpleArgs.new(job_num: 2)
+    #   ])
+    #
+    # With InsertManyParams:
+    #
+    #   num_inserted = client.insert_many([
+    #     River::InsertManyParams.new(SimpleArgs.new(job_num: 1), insert_opts: InsertOpts.new(max_attempts: 5)),
+    #     River::InsertManyParams.new(SimpleArgs.new(job_num: 2), insert_opts: InsertOpts.new(queue: "high_priority"))
+    #   ])
+    #
+    # Job arg implementations are expected to respond to:
+    #
+    #   * `#kind`: A string that uniquely identifies the job in the database.
+    #   * `#to_json`: Encodes the args to JSON for persistence in the database.
+    #     Must match encoding an args struct on the Go side to be workable.
+    #
+    # For example:
+    #
+    #   class SimpleArgs
+    #     attr_accessor :job_num
+    #
+    #     def initialize(job_num:)
+    #       self.job_num = job_num
+    #     end
+    #
+    #     def kind = "simple"
+    #
+    #     def to_json = JSON.dump({job_num: job_num})
+    #   end
+    #
+    # See also JobArgsHash for an easy way to insert a job from a hash.
+    #
+    # Unique job insertion isn't supported with bulk insertion because it'd run
+    # the risk of major lock contention.
+    #
+    # Returns the number of jobs inserted.
+    def insert_many(args)
+      all_params = args.map do |arg|
+        if arg.is_a?(InsertManyParams)
+          make_insert_params(arg.args, arg.insert_opts || EMPTY_INSERT_OPTS, is_insert_many: true).first # unique opts ignored on batch insert
+        else # jobArgs
+          make_insert_params(arg, EMPTY_INSERT_OPTS, is_insert_many: true).first # unique opts ignored on batch insert
+        end
+      end
+
+      @driver.job_insert_many(all_params)
+    end
+
+    private def check_advisory_lock_prefix_bounds(advisory_lock_prefix)
+      return nil if advisory_lock_prefix.nil?
+
+      # 2**32-1 is 0xffffffff (the largest number that's four bytes)
+      if advisory_lock_prefix < 0 || advisory_lock_prefix > 2**32 - 1
+        raise ArgumentError, "advisory lock prefix must fit inside four bytes"
+      end
+      advisory_lock_prefix
+    end
+
+    # Default states that are used during a unique insert. Can be overridden by
+    # setting UniqueOpts#by_state.
+    DEFAULT_UNIQUE_STATES = [
+      JOB_STATE_AVAILABLE,
+      JOB_STATE_COMPLETED,
+      JOB_STATE_RETRYABLE,
+      JOB_STATE_RUNNING,
+      JOB_STATE_SCHEDULED
+    ].freeze
+    private_constant :DEFAULT_UNIQUE_STATES
+
+    EMPTY_INSERT_OPTS = InsertOpts.new.freeze
+    private_constant :EMPTY_INSERT_OPTS
+
+    private def check_unique_job(insert_params, unique_opts, &block)
+      return block.call if unique_opts.nil?
+
+      any_unique_opts = false
+      get_params = Driver::JobGetByKindAndUniquePropertiesParam.new(kind: insert_params.kind)
+      unique_key = ""
+
+      # It's extremely important here that this lock string format and algorithm
+      # match the one in the main River library _exactly_. Don't change them
+      # unless they're updated everywhere.
+      if unique_opts.by_args
+        any_unique_opts = true
+        get_params.encoded_args = insert_params.encoded_args
+        unique_key += "&args=#{insert_params.encoded_args}"
+      end
+
+      if unique_opts.by_period
+        lower_period_bound = truncate_time(@time_now_utc.call, unique_opts.by_period).utc
+
+        any_unique_opts = true
+        get_params.created_at = [lower_period_bound, lower_period_bound + unique_opts.by_period]
+        unique_key += "&period=#{lower_period_bound.strftime("%FT%TZ")}"
+      end
+
+      if unique_opts.by_queue
+        any_unique_opts = true
+        get_params.queue = insert_params.queue
+        unique_key += "&queue=#{insert_params.queue}"
+      end
+
+      if unique_opts.by_state
+        any_unique_opts = true
+        get_params.state = unique_opts.by_state
+        unique_key += "&state=#{unique_opts.by_state.join(",")}"
+      else
+        get_params.state = DEFAULT_UNIQUE_STATES
+        unique_key += "&state=#{DEFAULT_UNIQUE_STATES.join(",")}"
+      end
+
+      return block.call unless any_unique_opts
+
+      # fast path
+      if !unique_opts.by_state || unique_opts.by_state.sort == DEFAULT_UNIQUE_STATES
+        unique_key_hash = Digest::SHA256.digest(unique_key)
+        job, unique_skipped_as_duplicate = @driver.job_insert_unique(insert_params, unique_key_hash)
+        return InsertResult.new(job, unique_skipped_as_duplicated: unique_skipped_as_duplicate)
+      end
+
+      @driver.transaction do
+        lock_str = "unique_key"
+        lock_str += "kind=#{insert_params.kind}"
+        lock_str += unique_key
+
+        lock_key = if @advisory_lock_prefix.nil?
+          FNV.fnv1_hash(lock_str, size: 64)
+        else
+          # Steep should be able to tell that this is not nil, but it can't.
+          prefix = @advisory_lock_prefix #: Integer # rubocop:disable Layout/LeadingCommentSpace
+          prefix << 32 | FNV.fnv1_hash(lock_str, size: 32)
+        end
+
+        # Packs a uint64 then unpacks to int64, which we need to do to keep the
+        # value within the bounds of Postgres' bigint. Overflow is okay because
+        # we can use the full bigint space (including negative numbers) for the
+        # advisory lock.
+        lock_key = uint64_to_int64(lock_key)
+
+        @driver.advisory_lock(lock_key)
+
+        existing_job = @driver.job_get_by_kind_and_unique_properties(get_params)
+        return InsertResult.new(existing_job, unique_skipped_as_duplicated: true) if existing_job
+
+        block.call
+      end
+    end
+
+    private def make_insert_params(args, insert_opts, is_insert_many: false)
+      raise "args should respond to `#kind`" if !args.respond_to?(:kind)
+
+      # ~all objects in Ruby respond to `#to_json`, so check non-nil instead.
+      args_json = args.to_json
+      raise "args should return non-nil from `#to_json`" if !args_json
+
+      args_insert_opts = if args.respond_to?(:insert_opts)
+        args_with_insert_opts = args #: _JobArgsWithInsertOpts # rubocop:disable Layout/LeadingCommentSpace
+        args_with_insert_opts.insert_opts || EMPTY_INSERT_OPTS
+      else
+        EMPTY_INSERT_OPTS
+      end
+
+      scheduled_at = insert_opts.scheduled_at || args_insert_opts.scheduled_at
+      unique_opts = insert_opts.unique_opts || args_insert_opts.unique_opts
+
+      raise ArgumentError, "unique opts can't be used with `#insert_many`" if is_insert_many && unique_opts
+
+      [
+        Driver::JobInsertParams.new(
+          encoded_args: args_json,
+          kind: args.kind,
+          max_attempts: insert_opts.max_attempts || args_insert_opts.max_attempts || MAX_ATTEMPTS_DEFAULT,
+          priority: insert_opts.priority || args_insert_opts.priority || PRIORITY_DEFAULT,
+          queue: insert_opts.queue || args_insert_opts.queue || QUEUE_DEFAULT,
+          scheduled_at: scheduled_at&.utc, # database defaults to now
+          state: scheduled_at ? JOB_STATE_SCHEDULED : JOB_STATE_AVAILABLE,
+          tags: validate_tags(insert_opts.tags || args_insert_opts.tags)
+        ),
+        unique_opts
+      ]
+    end
+
+    # Truncates the given time down to the interval. For example:
+    #
+    #   Thu Jan 15 21:26:36 UTC 2024 @ 15 minutes ->
+    #   Thu Jan 15 21:15:00 UTC 2024
+    private def truncate_time(time, interval_seconds)
+      Time.at((time.to_f / interval_seconds).floor * interval_seconds)
+    end
+
+    # Moves an integer that may occupy the entire uint64 space to one that's
+    # bounded within int64. Allows overflow.
+    private def uint64_to_int64(int)
+      [int].pack("Q").unpack1("q") #: Integer # rubocop:disable Layout/LeadingCommentSpace
+    end
+
+    TAG_RE = /\A[\w][\w\-]+[\w]\z/
+    private_constant :TAG_RE
+
+    private def validate_tags(tags)
+      tags&.each do |tag|
+        raise ArgumentError, "tags should be 255 characters or less" if tag.length > 255
+        raise ArgumentError, "tag should match regex #{TAG_RE.inspect}" unless TAG_RE.match(tag)
+      end
+    end
+  end
+
+  # A single job to insert that's part of an #insert_many batch insert. Unlike
+  # sending raw job args, supports an InsertOpts to pair with the job.
+  class InsertManyParams
+    # Job args to insert.
+    attr_reader :args
+
+    # Insertion options to use with the insert.
+    attr_reader :insert_opts
+
+    def initialize(args, insert_opts: nil)
+      @args = args
+      @insert_opts = insert_opts
+    end
+  end
+
+  # Result of a single insertion.
+  class InsertResult
+    # Inserted job row, or an existing job row if insert was skipped due to a
+    # previously existing unique job.
+    attr_reader :job
+
+    # True if for a unique job, the insertion was skipped due to an equivalent
+    # job matching unique property already being present.
+    attr_reader :unique_skipped_as_duplicated
+
+    def initialize(job, unique_skipped_as_duplicated: false)
+      @job = job
+      @unique_skipped_as_duplicated = unique_skipped_as_duplicated
+    end
+  end
+end

data/lib/driver.rb

@@ -0,0 +1,63 @@
+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
+  # considered to be for internal use only and subject to change. API stability
+  # is not guaranteed.
+  module Driver
+    # Parameters for looking up a job by kind and unique properties.
+    class JobGetByKindAndUniquePropertiesParam
+      attr_accessor :created_at
+      attr_accessor :encoded_args
+      attr_accessor :kind
+      attr_accessor :queue
+      attr_accessor :state
+
+      def initialize(
+        kind:,
+        created_at: nil,
+        encoded_args: nil,
+        queue: nil,
+        state: nil
+      )
+        self.kind = kind
+        self.created_at = created_at
+        self.encoded_args = encoded_args
+        self.queue = queue
+        self.state = state
+      end
+    end
+
+    # 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 :encoded_args
+      attr_accessor :kind
+      attr_accessor :max_attempts
+      attr_accessor :priority
+      attr_accessor :queue
+      attr_accessor :scheduled_at
+      attr_accessor :state
+      attr_accessor :tags
+
+      def initialize(
+        encoded_args:,
+        kind:,
+        max_attempts:,
+        priority:,
+        queue:,
+        scheduled_at:,
+        state:,
+        tags:
+      )
+        self.encoded_args = encoded_args
+        self.kind = kind
+        self.max_attempts = max_attempts
+        self.priority = priority
+        self.queue = queue
+        self.scheduled_at = scheduled_at
+        self.state = state
+        self.tags = tags
+      end
+    end
+  end
+end

data/lib/fnv.rb

@@ -0,0 +1,35 @@
+module River
+  # FNV is the Fowler–Noll–Vo hash function, a simple hash that's very easy to
+  # implement, and hash the perfect characteristics for use with the 64 bits of
+  # available space in a PG advisory lock.
+  #
+  # I'm implemented it myself so that the River gem can stay dependency free
+  # (and because it's quite easy to do).
+  module FNV
+    def self.fnv1_hash(str, size:)
+      hash = OFFSET_BASIS.fetch(size)
+      mask = (2**size - 1).to_int # creates a mask of 1s of `size` bits long like 0xffffffff
+      prime = PRIME.fetch(size)
+
+      str.each_byte do |byte|
+        hash *= prime
+        hash &= mask
+        hash ^= byte
+      end
+
+      hash
+    end
+
+    OFFSET_BASIS = {
+      32 => 0x811c9dc5,
+      64 => 0xcbf29ce484222325
+    }.freeze
+    private_constant :OFFSET_BASIS
+
+    PRIME = {
+      32 => 0x01000193,
+      64 => 0x00000100000001B3
+    }.freeze
+    private_constant :PRIME
+  end
+end

data/lib/insert_opts.rb

@@ -0,0 +1,136 @@
+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
+  # #insert_many.
+  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.
+    attr_accessor :max_attempts
+
+    # 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
+    # that if your workers are swamped with more high-priority jobs then they
+    # can handle, lower priority jobs may not be fetched.
+    #
+    # Defaults to PRIORITY_DEFAULT.
+    attr_accessor :priority
+
+    # The name of the job queue in which to insert the job.
+    #
+    # Defaults to QUEUE_DEFAULT.
+    attr_accessor :queue
+
+    # A time in future at which to schedule the job (i.e. in cases where it
+    # shouldn't be run immediately). The job is guaranteed not to run before
+    # this time, but may run slightly after depending on the number of other
+    # scheduled jobs and how busy the queue is.
+    #
+    # Use of this option generally only makes sense when passing options into
+    # Insert rather than when a job args is returning `#insert_opts`, however,
+    # it will work in both cases.
+    attr_accessor :scheduled_at
+
+    # 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.
+    #
+    # If tags are specified from both a job args override and from options on
+    # Insert, the latter takes precedence. Tags are not merged.
+    attr_accessor :tags
+
+    # Options relating to job uniqueness. No unique options means that the job
+    # is never treated as unique.
+    attr_accessor :unique_opts
+
+    def initialize(
+      max_attempts: nil,
+      priority: nil,
+      queue: nil,
+      scheduled_at: nil,
+      tags: nil,
+      unique_opts: nil
+    )
+      self.max_attempts = max_attempts
+      self.priority = priority
+      self.queue = queue
+      self.scheduled_at = scheduled_at
+      self.tags = tags
+      self.unique_opts = unique_opts
+    end
+  end
+
+  # Parameters for uniqueness for a job.
+  #
+  # If all properties are nil, no uniqueness at 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.
+  #
+  # 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
+  # properties on the job. If both #by_args and #by_queue are on, then for the
+  # given job kind, a single instance is allowed for each combination of args
+  # and queues. If either args or queue is changed on a new job, it's allowed to
+  # be inserted as a new job.
+  #
+  # Uniquenes is checked at insert time by taking a Postgres advisory lock,
+  # doing a look up for an equivalent row, and inserting only if none was found.
+  # There's no database-level mechanism that guarantees jobs stay unique, so if
+  # an equivalent row is inserted out of band (or batch inserted, where a unique
+  # check doesn't occur), it's conceivable that duplicates could coexist.
+  class UniqueOpts
+    # Indicates that uniqueness should be enforced for any specific instance of
+    # encoded args for a job.
+    #
+    # 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.
+    #
+    # The period should be specified in seconds. So a job that's unique every 15
+    # minute period would have a value of 900.
+    #
+    # 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
+    # kind in the database, regardless of when they were scheduled.
+    attr_accessor :by_period
+
+    # Indicates that uniqueness should be enforced within each queue.
+    #
+    # Default is false, meaning that as long as any other unique property is
+    # enabled, uniqueness will be enforced for a kind across all queues.
+    attr_accessor :by_queue
+
+    # Indicates that uniqueness should be enforced across any of the states in
+    # the given set. For example, if the given states were `(scheduled,
+    # running)` then a new job could be inserted even if one of the same kind
+    # was already being worked by the queue (new jobs are inserted as
+    # `available`).
+    #
+    # 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_RUNNING, River::JOB_STATE_RETRYABLE, River::JOB_STATE_SCHEDULED]
+    #
+    # With this setting, any jobs of the same kind that have been completed or
+    # discarded, but not yet cleaned out by the system, won't count towards the
+    # uniqueness of a new insert.
+    attr_accessor :by_state
+
+    def initialize(
+      by_args: nil,
+      by_period: nil,
+      by_queue: nil,
+      by_state: nil
+    )
+      self.by_args = by_args
+      self.by_period = by_period
+      self.by_queue = by_queue
+      self.by_state = by_state
+    end
+  end
+end

data/lib/job.rb

@@ -0,0 +1,187 @@
+module River
+  JOB_STATE_AVAILABLE = "available"
+  JOB_STATE_CANCELLED = "cancelled"
+  JOB_STATE_COMPLETED = "completed"
+  JOB_STATE_DISCARDED = "discarded"
+  JOB_STATE_RETRYABLE = "retryable"
+  JOB_STATE_RUNNING = "running"
+  JOB_STATE_SCHEDULED = "scheduled"
+
+  # 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
+  # hash that will be encoded to JSON.
+  #
+  # For example:
+  #
+  #   insert_res = client.insert(River::JobArgsHash.new("job_kind", {
+  #     job_num: 1
+  #   }))
+  class JobArgsHash
+    def initialize(kind, hash)
+      raise "kind should be non-nil" if !kind
+      raise "hash should be non-nil" if !hash
+
+      @kind = kind
+      @hash = hash
+    end
+
+    attr_reader :kind
+
+    def to_json
+      JSON.dump(@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
+
+    # The job's args as a hash decoded from JSON.
+    attr_accessor :args
+
+    # The attempt number of the job. Jobs are inserted at 0, the number is
+    # incremented to 1 the first time work its worked, and may increment further
+    # if it's either snoozed or errors.
+    attr_accessor :attempt
+
+    # The time that the job was last worked. Starts out as `nil` on a new
+    # insert.
+    attr_accessor :attempted_at
+
+    # The set of worker IDs that have worked this job. A worker ID differs
+    # between different programs, but is shared by all executors within any
+    # given one.  (i.e. Different Go processes have different IDs, but IDs are
+    # shared within any given process.) A process generates a new ID based on
+    # host and current time when it starts up.
+    attr_accessor :attempted_by
+
+    # When the job record was created.
+    attr_accessor :created_at
+
+    # A set of errors that occurred when the job was worked, one for each
+    # attempt. Ordered from earliest error to the latest error.
+    attr_accessor :errors
+
+    # The time at which the job was "finalized", meaning it was either completed
+    # successfully or errored for the last time such that it'll no longer be
+    # retried.
+    attr_accessor :finalized_at
+
+    # 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
+
+    # The maximum number of attempts that the job will be tried before it errors
+    # for the last time and will no longer be worked.
+    attr_accessor :max_attempts
+
+    # Arbitrary metadata associated with the job.
+    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
+    # that if your workers are swamped with more high-priority jobs then they
+    # can handle, lower priority jobs may not be fetched.
+    attr_accessor :priority
+
+    # The name of the queue where the job will be worked. Queues can be
+    # configured independently and be used to isolate jobs.
+    attr_accessor :queue
+
+    # When the job is scheduled to become available to be worked. Jobs default
+    # to running immediately, but may be scheduled for the future when they're
+    # inserted. They may also be scheduled for later because they were snoozed
+    # or because they errored and have additional retry attempts remaining.
+    attr_accessor :scheduled_at
+
+    # The state of job like `available` or `completed`. Jobs are `available`
+    # when they're first inserted.
+    attr_accessor :state
+
+    # Tags are 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.
+    attr_accessor :tags
+
+    # A unique key for the job within its kind that's used for unique job
+    # insertions. It's generated by hashing an inserted job's unique opts
+    # configuration.
+    attr_accessor :unique_key
+
+    def initialize(
+      id:,
+      args:,
+      attempt:,
+      created_at:,
+      kind:,
+      max_attempts:,
+      metadata:,
+      priority:,
+      queue:,
+      scheduled_at:,
+      state:,
+
+      # nullable/optional
+      attempted_at: nil,
+      attempted_by: nil,
+      errors: nil,
+      finalized_at: nil,
+      tags: nil,
+      unique_key: nil
+    )
+      self.id = id
+      self.args = args
+      self.attempt = attempt
+      self.attempted_at = attempted_at
+      self.attempted_by = attempted_by
+      self.created_at = created_at
+      self.errors = errors
+      self.finalized_at = finalized_at
+      self.kind = kind
+      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_key = unique_key
+    end
+  end
+
+  # A failed job work attempt containing information about the error or panic
+  # that occurred.
+  class AttemptError
+    # The time at which the error occurred.
+    attr_accessor :at
+
+    # The attempt number on which the error occurred (maps to #attempt on a job
+    # row).
+    attr_accessor :attempt
+
+    # Contains the stringified error of an error returned from a job or a panic
+    # value in case of a panic.
+    attr_accessor :error
+
+    # Contains a stack trace from a job that panicked. The trace is produced by
+    # invoking `debug.Trace()` in Go.
+    attr_accessor :trace
+
+    def initialize(
+      at:,
+      attempt:,
+      error:,
+      trace:
+    )
+      self.at = at
+      self.attempt = attempt
+      self.error = error
+      self.trace = trace
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riverqueue
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Blake Gentry
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-21 00:00:00.000000000 Z
+date: 2024-08-31 00:00:00.000000000 Z
 dependencies: []
 description: River is a fast job queue for Go. Use this gem in conjunction with gems
   riverqueue-activerecord or riverqueue-sequel to insert jobs in Ruby which will be
@@ -19,6 +19,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/client.rb
+- lib/driver.rb
+- lib/fnv.rb
+- lib/insert_opts.rb
+- lib/job.rb
 - lib/riverqueue.rb
 homepage: https://riverqueue.com
 licenses: