@callback cancel_all_jobs(conf(), queryable()) ::
  {:ok, {non_neg_integer(), [Oban.Job.t()]}}

Mark many executing, available, scheduled or retryable job as cancelled to prevent them from running.

@callback cancel_job(conf(), Oban.Job.t()) :: :ok

Mark an executing, available, scheduled or retryable job as cancelled to prevent it from running.

@callback check_meta(conf(), meta(), running()) :: map()

Format engine meta in a digestible format for queue inspection.

@callback complete_job(conf(), Oban.Job.t()) :: :ok

Record that a job completed successfully.

@callback discard_job(conf(), Oban.Job.t()) :: :ok

Transition a job to discarded and record an optional reason that it shouldn't be ran again.

@callback error_job(conf(), Oban.Job.t(), seconds()) :: :ok

Record an executing job's errors and either retry or discard it, depending on whether it has exhausted its available attempts.

@callback fetch_jobs(conf(), meta(), running()) ::
  {:ok, {meta(), [Oban.Job.t()]}} | {:error, term()}

Fetch available jobs for the given queue, up to configured limits.

@callback init(conf(), opts()) :: {:ok, meta()} | {:error, term()}

Initialize metadata for a queue engine.

Queue metadata is used to identify and track subsequent actions such as fetching or staging jobs.

@callback insert_all_jobs(conf(), Oban.changesets_or_wrapper(), opts()) :: [Oban.Job.t()]

Insert multiple jobs into the database.

@callback insert_all_jobs(
  conf(),
  Ecto.Multi.t(),
  Ecto.Multi.name(),
  Oban.changesets_or_wrapper_or_fun(),
  opts()
) :: Ecto.Multi.t()

Insert multiple jobs within an Ecto.Multi

@callback insert_job(conf(), Oban.Job.changeset(), opts()) ::
  {:ok, Oban.Job.t()} | {:error, term()}

Insert a job into the database.

@callback insert_job(
  conf(),
  Ecto.Multi.t(),
  Ecto.Multi.name(),
  Oban.changeset_or_fun(),
  opts()
) ::
  Ecto.Multi.t()

Insert a job within an Ecto.Multi.

@callback put_meta(conf(), meta(), atom(), term()) :: meta()

Store the given key/value pair in the engine meta.

@callback refresh(conf(), meta()) :: meta()

Refresh a queue to indicate that it is still alive.

@callback retry_all_jobs(conf(), queryable()) :: {:ok, non_neg_integer()}

Mark many jobs as available, adding attempts if already maxed out. Any jobs currently available, executing or scheduled should be ignored.

@callback retry_job(conf(), Oban.Job.t()) :: :ok

Mark a job as available, adding attempts if already maxed out. If the job is currently available, executing or scheduled it should be ignored.

@callback shutdown(conf(), meta()) :: meta()

Prepare a queue engine for shutdown.

The queue process is expected to stop processing new jobs after shutdown starts, though it may continue executing jobs that are already running.

@callback snooze_job(conf(), Oban.Job.t(), seconds()) :: :ok

Reschedule an executing job to run some number of seconds in the future.