Struct JobCatalog 

pub struct JobCatalog { /* private fields */ }

Single-source registry of job handlers, definition defaults, schedules, and enqueue helpers.

Implementations

impl JobCatalog

pub fn job_enqueue<'a>( &self, input: &CatalogJobEnqueueInput<'a>, ) -> Result<JobEnqueue<'a>, CatalogError>

Builds a JobEnqueue after validating the job type is registered and enabled.

This checks catalog configuration only. Operator-disabled database rows are still enforced by runledger-postgres when the job is enqueued. Job-specific definition overrides take precedence over the catalog default enabled flag when present.

pub fn job_schedule<'a>( &self, input: &CatalogJobScheduleInput<'a>, ) -> Result<JobScheduleUpsert<'a>, CatalogError>

Builds a one-off JobScheduleUpsert after validating the job type is registered and enabled.

This helper does not make the schedule catalog-owned. It is intended for lower-level setup flows that will call runledger_postgres::jobs::upsert_job_schedule directly.

This checks catalog configuration only. Operator-disabled database rows are still enforced by runledger-postgres when schedule-created jobs are materialized. Job-specific definition overrides take precedence over the catalog default enabled flag when present.

pub fn workflow_step<'a>( &self, step_key: &'a str, job_type_name: &str, payload: &'a Value, ) -> Result<WorkflowStepEnqueueBuilder<'a>, CatalogError>

Builds a workflow step after validating the job type is registered and enabled.

impl JobCatalog

pub fn new() -> Self

Creates an empty catalog with default definition values.

pub fn defaults(self, defaults: JobCatalogDefaults) -> Self

Replaces the definition defaults used by subsequent sync operations.

pub fn try_job<H>( self, job_type: &'static str, handler: H, ) -> Result<Self, CatalogError>

where H: JobHandler + 'static,

Registers a handler after validating declared and handler job types match.

Errors

Returns CatalogError when job types are blank, mismatched, or duplicated.

pub fn job<H>(self, job_type: &'static str, handler: H) -> Self

where H: JobHandler + 'static,

Registers a handler, panicking when validation fails.

pub fn try_job_with_definition_overrides<H>( self, job_type: &'static str, handler: H, overrides: JobCatalogDefinitionOverrides, ) -> Result<Self, CatalogError>

where H: JobHandler + 'static,

Registers a handler with job-specific definition overrides.

Errors

Returns CatalogError when job types are blank, mismatched, or duplicated.

pub fn job_with_definition_overrides<H>( self, job_type: &'static str, handler: H, overrides: JobCatalogDefinitionOverrides, ) -> Self

where H: JobHandler + 'static,

Registers a handler with job-specific definition overrides, panicking when validation fails.

pub fn try_definition_overrides( self, job_type: &str, overrides: JobCatalogDefinitionOverrides, ) -> Result<Self, CatalogError>

Replaces the definition overrides for one registered catalog job.

Errors

Returns CatalogError::UnknownJobType when the job type is not registered.

pub fn definition_overrides( self, job_type: &str, overrides: JobCatalogDefinitionOverrides, ) -> Self

Replaces the definition overrides for one registered catalog job, panicking when validation fails.

pub fn try_retry_delay_override( self, job_type: &str, failure_code: &'static str, retry_delay_ms: i32, ) -> Result<Self, CatalogError>

Registers a retry-delay override for a catalog job type.

Errors

Returns CatalogError when the job type is unknown or override values are invalid.

pub fn retry_delay_override( self, job_type: &str, failure_code: &'static str, retry_delay_ms: i32, ) -> Self

Registers a retry-delay override, panicking when validation fails.

pub fn try_schedule( self, spec: CatalogJobScheduleSpec<'_>, ) -> Result<Self, CatalogError>

Registers a catalog-owned schedule after validating its shape and job type.

Registered schedules are used by Self::sync_schedules and Self::sync_schedules_exact. The referenced job must already be registered on this builder and effectively enabled.

Errors

Returns CatalogError when the schedule spec is invalid, the job type is unknown or disabled, or the schedule name is already registered.

pub fn schedule(self, spec: CatalogJobScheduleSpec<'_>) -> Self

Registers a catalog-owned schedule, panicking when validation fails.

Use Self::try_schedule when registration data is not static or should be reported as a recoverable startup error.

pub fn to_registry(&self) -> JobRegistry

Converts the catalog into a runtime JobRegistry.

Disabled catalog jobs still register handlers so workers can process already-queued work and dead-letter hooks.

pub fn contains(&self, job_type: JobType<'_>) -> bool

Returns whether the catalog has a registered job type.

pub fn require_job_type( &self, job_type: &str, ) -> Result<JobType<'static>, CatalogError>

Returns a catalog job type when it is registered.

Errors

Returns CatalogError::UnknownJobType when the name is not in the catalog.

pub fn require_catalog_enabled_job_type( &self, job_type: &str, ) -> Result<JobType<'static>, CatalogError>

Returns a catalog job type when it is registered and catalog-enabled.

This checks catalog configuration only. It does not read job_definitions; operator-disabled database rows are enforced later by persistence APIs. Job-specific definition overrides take precedence over the catalog default enabled flag when present.

Errors

Returns CatalogError::UnknownJobType or CatalogError::DisabledJobType.

impl JobCatalog

pub async fn sync_definitions( &self, pool: &DbPool, ) -> Result<JobCatalogSyncReport, CatalogError>

Upserts every catalog job into job_definitions.

The catalog owns the synced definition fields: repeated syncs overwrite version, max_attempts, default_timeout_seconds, and default_priority for registered jobs. Effectively enabled catalog jobs preserve an existing disabled row so operator pauses survive worker restarts; effectively disabled catalog jobs explicitly write is_enabled = false. Safe to call repeatedly. Does not delete or disable definitions absent from the catalog. Use Self::sync_definitions_exact with an explicit scope when removed catalog entries should be disabled.

Syncs that disable catalog jobs briefly lock job_schedules and job_definitions so active schedule checks and definition disables are evaluated against a stable write boundary.

Errors

Returns CatalogError when defaults are invalid or persistence fails.

pub async fn sync_definitions_exact( &self, pool: &DbPool, scope: &JobCatalogSyncScope, ) -> Result<JobCatalogExactSyncReport, CatalogError>

Upserts catalog jobs, then disables enabled job_definitions rows in scope whose job type is absent from the catalog.

This is the stricter startup mode for applications that want the catalog to be the active job-definition source of truth. It never deletes rows, never operates outside the supplied owned job-type set, and rejects active schedules that still reference a job type it would disable. Unlike Self::sync_definitions, exact sync restores catalog entries’ effective is_enabled value from catalog defaults and job-specific overrides.

Exact sync briefly locks job_schedules and job_definitions before it checks active schedules or disables definitions, so it is heavier than the additive sync path.

Errors

Returns CatalogError when the scope is invalid, the catalog is empty, a catalog job is outside the scope, active schedules still reference absent scoped jobs, or persistence fails.

impl JobCatalog

pub fn schedule_sync_scope( &self, ) -> Result<JobCatalogScheduleSyncScope, CatalogError>

Builds an exact-sync scope from schedules registered with Self::schedule.

Use this with Self::sync_schedules_exact when the registered schedules are the source of truth for their owned name set. The helper avoids duplicating schedule names in startup code.

Errors

Returns CatalogError::InvalidExactScheduleSyncScope when the catalog has no registered schedules.

pub async fn sync_schedules( &self, pool: &DbPool, ) -> Result<JobCatalogScheduleSyncReport, CatalogError>

Upserts every catalog-registered schedule and applies each spec’s is_active value.

Use this for static schedules registered with Self::schedule next to their handler registration. It does not sync caller-provided startup specs; use Self::sync_schedules_with for those.

Call Self::sync_definitions before this method so referenced job definitions exist. Safe to call repeatedly on worker startup. Existing rows keep their organization_id, keep next_fire_at unless the cron expression changes, and have is_active overwritten from the registered spec on every sync. Use lower-level schedule APIs for schedules whose active state should be owned by an admin pause/resume workflow instead of startup catalog sync.

Sync applies one schedule upsert at a time so persistence errors can be reported with the schedule name that failed. Keep catalog-owned schedule sets on the order of dozens, not thousands; use a custom lower-level setup path for very large schedule inventories.

Errors

Returns CatalogError when schedule validation fails, a schedule references an unknown or disabled catalog job type, or persistence fails.

pub async fn sync_schedules_with<'a>( &self, pool: &DbPool, specs: &[CatalogJobScheduleSpec<'a>], ) -> Result<JobCatalogScheduleSyncReport, CatalogError>

Upserts caller-provided schedule specs and applies each spec’s is_active value.

Use this for schedule specs assembled at startup from config, feature flags, tenants, or another source outside the builder chain. This syncs only specs; it does not include schedules registered with Self::schedule. Existing rows keep their organization_id, and keep next_fire_at unless the cron expression changes. Existing rows have is_active overwritten from the provided spec on every sync.

Use lower-level schedule APIs for schedules whose active state should be owned by an admin pause/resume workflow instead of startup catalog sync. Sync applies one schedule upsert at a time so persistence errors can be reported with the schedule name that failed. Keep catalog-owned schedule sets on the order of dozens, not thousands; use a custom lower-level setup path for very large schedule inventories.

Errors

Returns CatalogError when schedule validation fails, a schedule references an unknown or disabled catalog job type, duplicate names are supplied, or persistence fails.

pub async fn sync_schedules_exact( &self, pool: &DbPool, scope: &JobCatalogScheduleSyncScope, ) -> Result<JobCatalogScheduleSyncReport, CatalogError>

Upserts catalog-registered schedules, then deactivates enabled schedules in scope whose names are absent from the synced spec set.

Use this when registered catalog schedules are the active source of truth for a bounded deployment-owned schedule-name scope.

Every registered schedule name must be included in scope. Exact sync takes a bounded PostgreSQL lock around the upsert/deactivation window so overlapping exact syncs cannot interleave their active schedule sets. Scheduler claims and fire-cursor updates can also wait briefly behind this lock, bounded by the exact-sync transaction settings. Exact sync still applies each present schedule’s is_active value on every sync; absent active schedules inside scope are deactivated. Keep ownership scopes deployment-stable during rolling deploys. For a feature-flagged schedule, prefer registering the schedule with is_active: false over omitting it from the catalog, so exact sync still owns and can deactivate the row.

Errors

Returns CatalogError when any schedule is outside scope, schedule validation fails, a schedule references an unknown or disabled catalog job type, lock acquisition fails, or persistence fails.

pub async fn sync_schedules_exact_with<'a>( &self, pool: &DbPool, scope: &JobCatalogScheduleSyncScope, specs: &[CatalogJobScheduleSpec<'a>], ) -> Result<JobCatalogScheduleSyncReport, CatalogError>

Upserts caller-provided schedule specs, then deactivates enabled schedules in scope whose names are absent from the synced spec set.

Use this when startup-provided specs are the active source of truth for a bounded deployment-owned schedule-name scope.

This exact syncs only specs; it does not include schedules registered with Self::schedule. Every provided schedule name must be included in scope. Passing an empty specs slice deactivates every enabled schedule in the owned scope. Exact sync still applies each present schedule’s is_active value on every sync. Scheduler claims and fire-cursor updates can wait briefly behind the exact-sync table lock, bounded by the exact-sync transaction settings. Keep ownership scopes deployment-stable during rolling deploys; when a dynamic source disables a schedule, keep its name in scope if exact sync should deactivate the stored row.

Errors

Returns CatalogError when any schedule is outside scope, schedule validation fails, a schedule references an unknown or disabled catalog job type, duplicate names are supplied, lock acquisition fails, or persistence fails.

impl JobCatalog

pub fn workflow_dag<'a>( &self, workflow_type: &'a str, metadata: &'a Value, ) -> CatalogWorkflowDagBuilder<'a, '_>

Starts a workflow DAG builder that validates step job types against the catalog.

Trait Implementations

impl Clone for JobCatalog

fn clone(&self) -> JobCatalog

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for JobCatalog

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for JobCatalog

fn default() -> Self

Returns the “default value” for a type.