Adds or verifies Oban configuration.

This function ensures that Oban is properly configured for PhoenixKit's background job processing, including:

1. Repo configuration (auto-detected from PhoenixKit config)
2. Required queues for file processing
3. Pruner plugin for automatic job cleanup

Parameters

• igniter - The igniter context

Returns

Updated igniter with Oban configuration and notices.

Adds Oban to the parent application's supervision tree.

This function ensures that Oban starts automatically when the application starts, with correct positioning in the supervisor tree:

• AFTER PhoenixKit.Supervisor (PhoenixKit services available)
• BEFORE Endpoint (Oban ready before HTTP requests)

Important

Oban MUST start AFTER PhoenixKit.Supervisor because PhoenixKit.Supervisor depends on Repo, and Oban also depends on Repo. The correct order is:

1. Repo (database connection)
2. PhoenixKit.Supervisor (uses Repo for Settings)
3. Oban (uses Repo for job persistence)

Parameters

• igniter - The igniter context

Returns

Updated igniter with Oban added to application supervisor.

@spec ensure_cron_plugin(String.t(), atom() | String.t()) :: String.t()

Ensures the crontab schedules ProcessScheduledJobsWorker.

Public for the same reason as ensure_worker_cron_entries/2: so it can be unit-tested directly against content strings.

@spec ensure_digest_cron_entries(String.t(), atom() | String.t()) :: String.t()

Ensures every notification digest cadence has a crontab entry.

Runs AFTER ensure_cron_plugin/2 (which guarantees a crontab: block exists) and is needed because that function short-circuits as soon as ProcessScheduledJobsWorker is present — so a host installed before the digest workers existed would keep a crontab without them forever, and mix phoenix_kit.update would never notice. Each cadence is checked independently, so a partially-updated crontab converges.

Public (not defp, unlike the sibling ensure_*_queue/2 helpers) specifically so this can be unit-tested directly against plain content strings, the same way ensure_lifeline_plugin/2 is.

@spec ensure_lifeline_plugin(String.t(), atom() | String.t()) :: String.t()

Ensure the Lifeline plugin exists in an existing config :app, Oban block's plugins: list, adding it if missing.

Rescues a job orphaned in :executing by a hard crash (BEAM kill -9, OOM, node failure) back to :available so it runs again — without it, an orphaned job sits stuck in :executing forever. That's more than a stalled retry: for a unique worker whose unique states: includes :executing (a self-scheduling chain deduping against its own in-flight run is a common pattern — see phoenix_kit_emails' pollers), an orphan permanently blocks every future insert for that worker too, not just the one crashed job.

rescue_after is Oban's default of 60 minutes rather than anything more aggressive, and it must stay above the host's longest-running job. Lifeline rescues purely by elapsed time — it never checks whether the node is still alive — so a job that legitimately runs past rescue_after is flipped back to :available (or :discarded, if its attempts are exhausted) while the original process is still working, and re-executes concurrently. PhoenixKit's longest declared worker timeout is 30 minutes (Storage.Workers.SyncFilesJob); workers with no timeout/1 callback have no bound at all, which is the case the margin is really protecting.

Public (not defp, unlike the sibling ensure_*_queue/2 helpers) specifically so this can be unit-tested directly against plain content strings, the same way oban_block_missing_prefix?/1 is — no live Igniter/Mix context needed.

@spec ensure_queue(String.t(), atom() | String.t(), String.t(), pos_integer()) ::
  String.t()

Ensures queue: limit exists in a host's existing Oban queues: list.

The shared implementation behind every ensure_*_queue/2. It was written for scheduled_jobs and generalised afterwards, because the six sibling helpers that predated it had each hand-rolled the same string surgery and reproduced the same six defects — and theirs are worse than the missing queue this repairs: a bad insert corrupts the host's config.exs.

Public so it can be unit-tested directly against content strings.

@spec ensure_scheduled_jobs_queue(String.t(), atom() | String.t()) :: String.t()

Ensures the scheduled_jobs queue exists in a host's existing Oban config.

Public for the same reason as ensure_worker_cron_entries/2: so it can be unit-tested directly against content strings.

@spec ensure_worker_cron_entries(String.t(), atom() | String.t()) :: String.t()

Ensures the plain worker cron entries shipped since a host's install exist.

Public for the same reason as ensure_digest_cron_entries/2: so it can be unit-tested directly against content strings.

@spec oban_block_missing_prefix?(String.t()) :: boolean()

Whether the given config content has a config :app, Oban block that lacks a prefix: key.

Scoped to the Oban block on purpose: a whole-file scan is defeated by the config :phoenix_kit, prefix: "..." entry (which matches a naive prefix: grep) and false-positives on unrelated config. Any prefix: inside the block counts — including computed values like System.get_env(...). Returns false when the content has no Oban block at all (nothing to judge).

Checks if Oban configuration exists in config.exs.

Parameters

• igniter - The igniter context for detecting parent app name

Returns

Boolean indicating if configuration exists.

Checks if Oban supervisor is configured in application.ex.

Parameters

• igniter - The igniter context for detecting parent app name

Returns

Boolean indicating if Oban supervisor exists in application.ex.