riverqueue 0.6.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db28757576fce6283b32ae3509deb6eb3a66c2e20691e30a67f107fff5b553aa
-  data.tar.gz: d5e6b8447b5e5e9defcd2ab72f95cc1266d9bb488b0f9bf20a6ede96f47ce71f
+  metadata.gz: 46f45a18aa1b8884c93295ba1b023751c826d8feeac212949e18f388f3a6b6cc
+  data.tar.gz: 679dde3151af410e5e8f8949d80750d68f247e300af1e6f93b43270d81dc5d40
 SHA512:
-  metadata.gz: 9fe6c2f467f9d79d5819a267f3b620481a179b6024339d3bafc20b2811599364daf4a7d85928d873a2a06b250b6a3ebc1783009b08b7e1251920d6d2d1b672c3
-  data.tar.gz: d06cfdf233641f120e2170f3ac694bb98ca04fa2556e9de8bbeaed117d98b56384de9b552e71c9526d6bda2ee15eea79c2475beec625bfb663329e77edfb30c0
+  metadata.gz: a7507d5e78f99ef0bb6cda3a91479da386bb5e66c18c40a26c98ed5aec42bb3b5425b3753e797759e4ca4117f9a01636d9784fd1b27d160af215e5e5216ac998
+  data.tar.gz: a65b3a772b4d85b823256fe2bebb656a816cff1ba87777c77d9393670dbdfe3be383095bb49f3446d8110a143cb1ba68b9c7530d64da44a9e9093265be9aa8ba

data/lib/client.rb

@@ -0,0 +1,300 @@
+require "digest"
+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)
+      @driver = driver
+      @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 = make_insert_params(args, insert_opts)
+      insert_and_check_unique_job(insert_params)
+    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.
+    #
+    # 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)
+        else # jobArgs
+          make_insert_params(arg, EMPTY_INSERT_OPTS)
+        end
+      end
+
+      @driver.job_insert_many(all_params)
+        .map do |job, unique_skipped_as_duplicate|
+        InsertResult.new(job, unique_skipped_as_duplicated: unique_skipped_as_duplicate)
+      end
+    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_PENDING,
+      JOB_STATE_RETRYABLE,
+      JOB_STATE_RUNNING,
+      JOB_STATE_SCHEDULED
+    ].freeze
+    private_constant :DEFAULT_UNIQUE_STATES
+
+    REQUIRED_UNIQUE_STATES = [
+      JOB_STATE_AVAILABLE,
+      JOB_STATE_PENDING,
+      JOB_STATE_RUNNING,
+      JOB_STATE_SCHEDULED
+    ].freeze
+    private_constant :REQUIRED_UNIQUE_STATES
+
+    EMPTY_INSERT_OPTS = InsertOpts.new.freeze
+    private_constant :EMPTY_INSERT_OPTS
+
+    private def insert_and_check_unique_job(insert_params)
+      job, unique_skipped_as_duplicate = @driver.job_insert(insert_params)
+      InsertResult.new(job, unique_skipped_as_duplicated: unique_skipped_as_duplicate)
+    end
+
+    private def make_insert_params(args, insert_opts)
+      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
+
+      insert_params = 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 || Time.now,
+        state: scheduled_at ? JOB_STATE_SCHEDULED : JOB_STATE_AVAILABLE,
+        tags: validate_tags(insert_opts.tags || args_insert_opts.tags || [])
+      )
+
+      unique_opts = insert_opts.unique_opts || args_insert_opts.unique_opts
+      if unique_opts
+        unique_key, unique_states = make_unique_key_and_bitmask(insert_params, unique_opts)
+        insert_params.unique_key = unique_key
+        insert_params.unique_states = unique_states
+      end
+      insert_params
+    end
+
+    private def make_unique_key_and_bitmask(insert_params, unique_opts)
+      unique_key = ""
+
+      # It's extremely important here that this unique key format and algorithm
+      # match the one in the main River library _exactly_. Don't change them
+      # unless they're updated everywhere.
+      unless unique_opts.exclude_kind
+        unique_key += "&kind=#{insert_params.kind}"
+      end
+
+      if unique_opts.by_args
+        parsed_args = JSON.parse(insert_params.encoded_args)
+        filtered_args = if unique_opts.by_args.is_a?(Array)
+          parsed_args.select { |k, _| unique_opts.by_args.include?(k) }
+        else
+          parsed_args
+        end
+
+        encoded_args = JSON.generate(filtered_args.sort.to_h)
+        unique_key += "&args=#{encoded_args}"
+      end
+
+      if unique_opts.by_period
+        lower_period_bound = truncate_time(@time_now_utc.call, unique_opts.by_period).utc
+
+        unique_key += "&period=#{lower_period_bound.strftime("%FT%TZ")}"
+      end
+
+      if unique_opts.by_queue
+        unique_key += "&queue=#{insert_params.queue}"
+      end
+
+      unique_key_hash = Digest::SHA256.digest(unique_key)
+      unique_states = validate_unique_states(unique_opts.by_state || DEFAULT_UNIQUE_STATES)
+
+      [unique_key_hash, UniqueBitmask.from_states(unique_states)]
+    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
+
+    private def validate_unique_states(states)
+      REQUIRED_UNIQUE_STATES.each do |required_state|
+        raise ArgumentError, "by_state should include required state #{required_state}" unless states.include?(required_state)
+      end
+      states
+    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:)
+      @job = job
+      @unique_skipped_as_duplicated = unique_skipped_as_duplicated
+    end
+  end
+end

data/lib/driver.rb

@@ -0,0 +1,46 @@
+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
+    # 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
+      attr_accessor :unique_key
+      attr_accessor :unique_states
+
+      def initialize(
+        encoded_args:,
+        kind:,
+        max_attempts:,
+        priority:,
+        queue:,
+        scheduled_at:,
+        state:,
+        tags:,
+        unique_key: nil,
+        unique_states: nil
+      )
+        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
+        self.unique_key = unique_key
+        self.unique_states = unique_states
+      end
+    end
+  end
+end

data/lib/insert_opts.rb

@@ -0,0 +1,146 @@
+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_PENDING, 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.
+    #
+    # The pending, scheduled, available, and running states are required when
+    # customizing this list.
+    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.
+    attr_accessor :exclude_kind
+
+    def initialize(
+      by_args: nil,
+      by_period: nil,
+      by_queue: nil,
+      by_state: nil,
+      exclude_kind: nil
+    )
+      self.by_args = by_args
+      self.by_period = by_period
+      self.by_queue = by_queue
+      self.by_state = by_state
+      self.exclude_kind = exclude_kind
+    end
+  end
+end

data/lib/job.rb

@@ -0,0 +1,193 @@
+module River
+  JOB_STATE_AVAILABLE = "available"
+  JOB_STATE_CANCELLED = "cancelled"
+  JOB_STATE_COMPLETED = "completed"
+  JOB_STATE_DISCARDED = "discarded"
+  JOB_STATE_PENDING = "pending"
+  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
+
+    # A list of states that the job must be in to be considered for uniqueness.
+    attr_accessor :unique_states
+
+    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,
+      unique_states: 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
+      self.unique_states = unique_states
+    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

data/lib/riverqueue.rb

@@ -1,11 +1,11 @@
 require "json"
 
-require_relative "fnv"
 require_relative "insert_opts"
 require_relative "job"
 
 require_relative "client"
 require_relative "driver"
+require_relative "unique_bitmask"
 
 module River
 end

data/lib/unique_bitmask.rb

@@ -0,0 +1,41 @@
+module River
+  class UniqueBitmask
+    JOB_STATE_BIT_POSITIONS = {
+      ::River::JOB_STATE_AVAILABLE => 7,
+      ::River::JOB_STATE_CANCELLED => 6,
+      ::River::JOB_STATE_COMPLETED => 5,
+      ::River::JOB_STATE_DISCARDED => 4,
+      ::River::JOB_STATE_PENDING => 3,
+      ::River::JOB_STATE_RETRYABLE => 2,
+      ::River::JOB_STATE_RUNNING => 1,
+      ::River::JOB_STATE_SCHEDULED => 0
+    }.freeze
+    private_constant :JOB_STATE_BIT_POSITIONS
+
+    def self.from_states(states)
+      val = 0
+
+      states.each do |state|
+        bit_index = JOB_STATE_BIT_POSITIONS[state]
+
+        bit_position = 7 - (bit_index % 8)
+        val |= 1 << bit_position
+      end
+
+      format("%08b", val)
+    end
+
+    def self.to_states(mask)
+      states = [] #: Array[jobStateAll] # rubocop:disable Layout/LeadingCommentSpace
+
+      JOB_STATE_BIT_POSITIONS.each do |state, bit_index|
+        bit_position = 7 - (bit_index % 8)
+        if (mask & (1 << bit_position)) != 0
+          states << state
+        end
+      end
+
+      states.sort
+    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.8.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-12-20 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,7 +19,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/client.rb
+- lib/driver.rb
+- lib/insert_opts.rb
+- lib/job.rb
 - lib/riverqueue.rb
+- lib/unique_bitmask.rb
 homepage: https://riverqueue.com
 licenses:
 - LGPL-3.0-or-later
@@ -43,7 +48,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.20
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: River is a fast job queue for Go.