Steward.Spec (Steward v0.1.0)

Copy Markdown View Source

The jobs a resource's workers desire, built by their Steward.Worker.spec/3 callbacks.

Steward reconciles a resource's jobs in Oban's queues against its spec, inserting, updating and deleting jobs as needed. Add jobs to the spec with schedule/4.

Summary

Functions

Schedules a desired job into the resource's execution plan.

Types

args()

(since 0.1.0)
@type args() :: Oban.Job.args()

job()

(since 0.1.0)
@type job() :: {worker(), args(), keyword()}

t()

(since 0.1.0)
@type t() :: %Steward.Spec{jobs: [job()]}

worker()

(since 0.1.0)
@type worker() :: module()

Functions

schedule(spec, worker, args, opts \\ [])

(since 0.1.0)
@spec schedule(t(), worker(), args(), keyword()) :: t()

Schedules a desired job into the resource's execution plan.

Usually no need to call this directly, call your worker's private schedule/3 helper instead.

Options

  • :steward_unique_key - distinguishes multiple jobs of the same worker for a resource. Any term, hashed when scheduled. Uniqueness holds across all job states, forever. The hash has 32 bits, so collisions only become plausible with many thousands of keys for the same worker and resource.
  • :scheduled_at - when to run the job. Defaults to immediately.
  • :queue, :priority, :max_attempts, :tags - as in Oban.Job.new/2.

Changes to these options are applied to existing jobs that are still scheduled, and omitting an option resets it to its default, e.g. a job no longer given :scheduled_at is rescheduled to run immediately. Steward keeps changes made to a job outside of Steward (e.g. through Oban Web) until the spec's desired value for that option changes.

Steward controls uniqueness itself, so :unique and :replace raise an ArgumentError. So does :schedule_in, as it would push the job back on every reconciliation, and any other option not listed above.