Scheduled jobs reference

Este conteúdo não está disponível em sua língua ainda.

This reference lists every job the scheduler can register, what triggers it, the configuration key that turns it on and what it changes when it runs. This reference reflects Onetime Secret v0.26.19 (e98a88c9).

Reading the tables

Trigger is the interval or cron pattern the job registers with, plus its first run after the scheduler starts. Enabled by gives the configuration key and the value its own check accepts. Depends on lists what has to be reachable. Effects separates jobs that only report from jobs that change data, send mail or move messages.

Almost every enablement check tests for exactly true, so a key set to "true", 1 or yes leaves the job off. The two exceptions are noted in their rows.

A job decides for itself whether to register: its scheduling method returns early unless its own check passes. A disabled job is therefore absent from the schedule rather than registered and skipped, so ots scheduler status shows the jobs that were actually registered by the running scheduler.

Maintenance jobs need two switches: the master jobs.maintenance.enabled and the job’s own enabled. Most also read an auto_repair flag; with it unset or false the job reports what it found and changes nothing. Every one of those defaults to false.

The scheduler process

Property	Behaviour
Process	`bin/ots scheduler`, which runs rufus-scheduler in the foreground, or detached with `--daemonize`.
Discovery	Every `_job.rb` file under the scheduled-jobs directory is loaded, and each named job class that implements its own scheduling method is registered. Loading a job file schedules nothing by itself.
Overlap	Overlapping runs are not prevented by default. Only the domain refresh job registers with overlap disabled; the maintenance base class states that non-idempotent repair logic would need its own datastore lock.
Coordination	No cross-process lock exists for scheduled jobs. The source states the assumption directly: one scheduler process per datastore.
Run records	Each run is recorded with a status of success, partial, skipped or error. A job that raises is recorded as error and logged, and the scheduler keeps running.
Liveness	The scheduler registers its own heartbeat every 60 seconds, with overlap disabled. Liveness is judged against three heartbeat intervals.
Signals	`INT` and `TERM` shut down after waiting for running jobs. `USR1` logs the current schedule.

Scheduled jobs

Job	Trigger	Enabled by	Depends on	Effects
`CatalogRetryJob`	Every 2 minutes, first run after 30 seconds.	`jobs.catalog_retry.enabled` must be exactly `true`; shipped `true`. The class exists only when billing is enabled.	Datastore, a configured Stripe key, billing enabled.	Reprocesses up to 50 webhook events the Stripe circuit breaker deferred. Skips the run while the breaker is open or no Stripe key is set.
`DlqEmailConsumerJob`	Every 5 minutes, first run after 30 seconds.	`jobs.dlq_consumer.enabled` must be exactly `true`; shipped `true`.	Broker, datastore.	Pops up to 50 messages from the email dead-letter queue within a 240-second budget. Replays authentication email whose token is still valid, and discards non-authentication email as stale. Raw Rodauth email is always replayed.
`DlqMonitorJob`	Every 60 seconds, first run after 15 seconds.	`jobs.dlq_monitor_enabled` must be exactly `true`. The key has no entry in the shipped defaults, so it is unset until an operator adds it.	Broker.	Reads each dead-letter queue depth with a passive declaration and warns for every queue holding messages. Consumes nothing.
`DomainRefreshJob`	Every `jobs.domain_refresh.check_interval` (shipped `30m`), first run after 2 minutes.	`jobs.domain_refresh.enabled` must be exactly `true`; shipped `true`.	Datastore, outbound DNS and TLS lookups or the validation strategy’s provider API.	Walks one page of custom domains per run (`batch_size`, shipped 200) and writes refreshed vhost and resolving state. Recently created unverified domains fill spare capacity inside `dns_propagation_window`. Overlap disabled: a tick during a run is skipped, not queued.
`ExpirationWarningJob`	Every `jobs.expiration_warnings.check_interval` (shipped `1h`), first run after 30 seconds.	`jobs.expiration_warnings.enabled` must be exactly `true`; shipped `false`.	Datastore, the email publisher, and the broker when jobs are enabled.	Enqueues one warning email per receipt for secrets inside `warning_hours`, up to `batch_size` per run, and removes timeline entries that expired over an hour ago. Mail is enqueued at scan time; there is no delayed delivery.
`FaviconBackfillJob`	Cron `jobs.favicon_backfill.cron` (shipped `0 3 * * *`).	Both `jobs.favicon_backfill.enabled` and `jobs.favicon_fetch.enabled` must be exactly `true`. Shipped: backfill `false`, fetch `true`.	Datastore, broker.	Paginates custom domains (`batch_size`, shipped 500) and enqueues a favicon fetch for each domain missing an auto-fetched icon whose backoff window elapsed. Reads the backoff fields; the worker writes them.
`HeartbeatJob`	Every 1 minute, first run after 5 seconds.	`jobs.heartbeat_enabled` must be truthy. This is the one check that accepts any truthy value rather than exactly `true`. The key has no entry in the shipped defaults.	Datastore.	Logs a debug line with current secret and receipt counts. Writes nothing. Distinct from the scheduler’s own heartbeat.
`PlanCacheRefreshJob`	Every 6 hours, first run after 1 minute.	`jobs.plan_cache_refresh.enabled` must be exactly `true`; shipped `true`.	Datastore, a configured Stripe key.	Pulls the plan catalog from Stripe into the plan cache, whose entries expire after 12 hours. Installs with no Stripe key skip the run. A rate limit is retried on the next interval.

Maintenance jobs

Job	Trigger	Enabled by	Depends on	Effects
`DataConsistencyAuditJob`	Every `jobs.maintenance.data_audit.interval` (shipped `6h`), first run after 5 minutes.	`jobs.maintenance.enabled` and `jobs.maintenance.data_audit.enabled`, both exactly `true`; both shipped `false`.	Datastore.	Report only. Compares counts, samples members for backing keys, cross-checks unique indexes and checks participation in both directions, then logs one structured report. It has no `auto_repair` setting.
`EntitlementMaterializeJob`	Cron `jobs.maintenance.entitlement_materialize.cron` (shipped `0 3 * * *`).	`jobs.maintenance.enabled` and `jobs.maintenance.entitlement_materialize.enabled`, both exactly `true`; both shipped `false`.	Datastore, a configured Stripe key.	Refreshes the plan cache from Stripe, then re-materializes organization entitlements and cascades to active memberships. The run aborts unless the catalog pull reports a verified catalog, so it never materializes from a stale cache. Per-organization failures are logged and counted.
`HousekeepingJob`	Cron `jobs.maintenance.housekeeping.cron` (shipped `0 2 * * *`).	`jobs.maintenance.enabled` and `jobs.maintenance.housekeeping.enabled`, both exactly `true`; both shipped `false`.	Datastore.	Runs every registered model chore in batches of `batch_size` (default 100). The chore bodies own what is written. An optional `models` allowlist narrows the set. Record-level failures make the run status partial.
`IndexRebuildJob`	Cron `jobs.maintenance.index_rebuild.cron` (shipped `0 4 * * *`).	`jobs.maintenance.enabled` and `jobs.maintenance.index_rebuild.enabled`, both exactly `true`; both shipped `false`.	Datastore.	Reconciles the customer email, organization contact-email and custom-domain name indexes. Reports only unless `auto_repair` is `true` (shipped `false`), when it removes stale and mismatched entries and re-adds missing ones through ownership-checked writes. Conflicting entries are reported and never repaired.
`InstancesRebuildJob`	Cron `jobs.maintenance.instances_rebuild.cron` (shipped `0 3 * * 0`).	`jobs.maintenance.enabled` and `jobs.maintenance.instances_rebuild.enabled`, both exactly `true`; both shipped `false`.	Datastore.	Scans model keys and merges the class-level instance sets: adds missing members, removes members whose key is gone. Reports only unless `auto_repair` is `true` (shipped `false`). A run aborts when the difference exceeds 20 per cent of the total. The source calls this the most invasive maintenance job.
`ParticipationGCJob`	Cron `jobs.maintenance.participation_gc.cron` (shipped `0 5 * * *`).	`jobs.maintenance.enabled` and `jobs.maintenance.participation_gc.enabled`, both exactly `true`; both shipped `false`.	Datastore.	Reports stale participation members, expired pending invitations and organizations whose owner record is gone. With `auto_repair` `true` (shipped `false`) it removes stale entries, destroys expired invitation memberships with index cleanup and promotes a member with the owner role where one exists. A key scan aborts after five consecutive errors.
`PhantomCleanupJob`	Every `jobs.maintenance.phantom_cleanup.interval` (shipped `1h`), first run after 2 minutes.	`jobs.maintenance.enabled` and `jobs.maintenance.phantom_cleanup.enabled`, both exactly `true`; both shipped `false`.	Datastore.	Scans instance and participation sorted sets for members whose key no longer exists. Reports only unless `auto_repair` is `true` (shipped `false`), when the phantom members are removed, bounded by `batch_size` (default 500).
`SecretCountReconcileJob`	Cron `30 4 * * *`, fixed in source and not configurable.	`jobs.maintenance.enabled` alone, exactly `true`; shipped `false`. The job deliberately has no key of its own.	Datastore.	Recounts live secrets per owner with one bounded cursor scan and sets each customer’s active-secret counter to that count, including zero. The write is an idempotent set to the recomputed value.

Scheduler-owned entries

Entry	Trigger	Enabled by	Depends on	Effects
Liveness heartbeat	Every 60 seconds, first run after 1 second, overlap disabled.	Always, whenever the scheduler process runs. It is registered by the scheduler rather than discovered as a job.	Datastore.	Refreshes the heartbeat record that `ots scheduler status` and the admin console read. It is not a job class, so it never appears in the job list.