# `Steward.Spec`
[🔗](https://github.com/marko-ding/steward/blob/v0.1.0/lib/steward/spec.ex#L3)

The jobs a resource's workers desire, built by their `c: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`.

# `args`
*since 0.1.0* 

```elixir
@type args() :: Oban.Job.args()
```

# `job`
*since 0.1.0* 

```elixir
@type job() :: {worker(), args(), keyword()}
```

# `t`
*since 0.1.0* 

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

# `worker`
*since 0.1.0* 

```elixir
@type worker() :: module()
```

# `schedule`
*since 0.1.0* 

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
