# `PhoenixKit.Modules.Sitemap.SchedulerWorker`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.165/lib/modules/sitemap/scheduler_worker.ex#L1)

Oban worker for scheduled sitemap regeneration.

This worker is responsible for:
- Periodic sitemap regeneration based on configured interval
- Automatic re-scheduling after each run
- Checking if scheduling is enabled before execution

## Configuration

Scheduling is controlled via Settings:
- `sitemap_schedule_enabled` - Enable/disable automatic regeneration
- `sitemap_schedule_interval_hours` - Interval between regenerations (default: 24)

## Usage

    # Schedule initial job (called when schedule is enabled)
    PhoenixKit.Modules.Sitemap.SchedulerWorker.schedule()

    # Manual trigger
    PhoenixKit.Modules.Sitemap.SchedulerWorker.regenerate_now()

    # Cancel scheduled jobs
    PhoenixKit.Modules.Sitemap.SchedulerWorker.cancel_scheduled()

## Oban Queue

Jobs are placed in the `:sitemap` queue with max 3 attempts.

# `cancel_scheduled`

```elixir
@spec cancel_scheduled() :: {:ok, non_neg_integer()}
```

Cancels all scheduled sitemap jobs.

This is called when scheduling is disabled.

# `ensure_cache_warm`

```elixir
@spec ensure_cache_warm() ::
  {:ok, Oban.Job.t()} | :file_exists | :disabled | {:error, term()}
```

Ensures sitemap file exists on application startup.

With file-only architecture, this is optional - sitemap will be generated
on first request if file doesn't exist. Use this for explicit pre-warming.

## Returns

- `{:ok, job}` - Regeneration job scheduled (file doesn't exist)
- `:file_exists` - Sitemap file already exists
- `:disabled` - Sitemap module is disabled

## Examples

    # In Application.start/2 or supervisor child
    PhoenixKit.Modules.Sitemap.SchedulerWorker.ensure_cache_warm()

# `ensure_scheduled`

```elixir
@spec ensure_scheduled() ::
  {:ok, Oban.Job.t()} | {:error, term()} | :disabled | :already_scheduled
```

Ensures a scheduled job exists when scheduling is enabled.

Called on application startup to recover the scheduling chain if it was
broken by a server restart, Oban pruning, or job failure.

# `perform`

Performs sitemap regeneration.

This callback is invoked by Oban when the scheduled job runs.
It checks if scheduling is still enabled before regenerating.

# `regenerate_module_now`

```elixir
@spec regenerate_module_now(String.t()) :: {:ok, Oban.Job.t()} | {:error, term()}
```

Triggers immediate regeneration for a specific source module.

Regenerates only the specified source's sitemap file and rebuilds the index.

# `regenerate_now`

```elixir
@spec regenerate_now() :: {:ok, Oban.Job.t()} | {:error, term()}
```

Triggers immediate sitemap regeneration.

This creates a job that runs immediately, bypassing the schedule.

# `schedule`

```elixir
@spec schedule(keyword()) :: {:ok, Oban.Job.t()} | {:error, term()} | :disabled
```

Schedules the next sitemap regeneration.

The job is scheduled based on `sitemap_schedule_interval_hours` setting.
If scheduling is disabled, no job is created.

## Options

- `:delay_hours` - Override the configured interval (optional)

## Examples

    # Schedule with configured interval
    PhoenixKit.Modules.Sitemap.SchedulerWorker.schedule()

    # Schedule with custom delay
    PhoenixKit.Modules.Sitemap.SchedulerWorker.schedule(delay_hours: 1)

# `schedule_next`

```elixir
@spec schedule_next() :: {:ok, Oban.Job.t()} | {:error, term()} | :disabled
```

Schedules the next regeneration after current job completes.

# `status`

```elixir
@spec status() :: map()
```

Returns the current scheduling status and next run time.

---

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