runledger_postgres/
jobs.rs

1//! Durable job, schedule, workflow, and admin persistence APIs.
2//!
3//! Choose the highest-level API that matches the work. Use `enqueue_job` for
4//! one independent retried unit. Use workflow DAG APIs such as
5//! `enqueue_workflow_run`, `WorkflowRunEnqueueBuilder`, and
6//! `WorkflowStepEnqueueBuilder` when work has dependencies, fan-out/fan-in,
7//! external gates, or workflow-level idempotency.
8//!
9//! Avoid manually orchestrating ordinary workflows by polling job state,
10//! enqueueing child jobs from handlers, or storing dependency state in payloads.
11
12mod admin;
13mod errors;
14mod logs;
15mod queue;
16mod row_decode;
17mod rows;
18mod runtime_configs;
19mod schedule_definition_guard;
20mod schedules;
21mod transaction_isolation;
22mod types;
23mod workflow_types;
24mod workflows;
25
26pub use admin::{
27    JobPayloadUuidArrayFieldUpdate, JobPayloadUuidArrayFieldUpdateRejection, cancel_job,
28    get_job_by_id, get_job_metrics, get_job_payload_by_idempotency_key,
29    get_latest_job_payload_for_run, list_job_events, list_jobs, requeue_job,
30    update_job_payload_uuid_array_field,
31};
32pub use logs::{insert_job_log, list_job_logs};
33pub use queue::{
34    JobDefinitionCatalogSyncError, JobDefinitionCatalogSyncMode, JobDefinitionCatalogSyncReport,
35    claim_jobs, claim_jobs_for_types, claim_prestart_jobs, claim_prestart_jobs_for_types,
36    complete_job_failure, complete_job_failure_with_outcome, complete_job_success,
37    complete_job_success_with_outcome, enqueue_job, enqueue_job_tx, get_job_definition_by_type,
38    heartbeat_job, insert_job_definition_if_missing_tx, list_job_definitions, reap_expired_leases,
39    reap_expired_leases_with_diagnostics, reap_expired_leases_with_terminal_records,
40    release_unstarted_job_claim, sync_catalog_job_definitions_exact_tx,
41    sync_catalog_job_definitions_tx, update_job_definition, update_job_progress,
42    upsert_job_definition_tx,
43};
44pub use runtime_configs::{
45    get_job_runtime_config_by_type, get_required_job_runtime_config_by_type,
46    insert_job_runtime_config_if_missing, insert_job_runtime_config_if_missing_tx,
47    list_job_runtime_configs, upsert_job_runtime_config, upsert_job_runtime_config_tx,
48};
49pub use schedules::{
50    claim_due_schedules_tx, deactivate_schedules_absent_from_names_tx, get_job_schedule_by_name,
51    mark_schedule_fired_tx, prepare_schedule_exact_sync_critical_section_tx,
52    set_job_schedule_active, set_job_schedule_active_tx, set_job_schedule_next_fire_at,
53    set_job_schedule_next_fire_at_tx, sync_catalog_job_schedules_tx, upsert_job_schedule,
54    upsert_job_schedule_tx,
55};
56pub use types::{
57    JOB_LIST_PAGE_LIMIT_MAX, JOB_SCHEDULE_MAX_JITTER_SECONDS, JobCompletionUpdate,
58    JobDefinitionListFilter, JobDefinitionRecord, JobDefinitionUpdate, JobDefinitionUpsert,
59    JobEnqueue, JobEventRecord, JobFailureCompletionDisposition, JobFailureCompletionOutcome,
60    JobFailureUpdate, JobListFilter, JobLogRecord, JobLogRecordInput, JobMetricsRecord,
61    JobProgressUpdate, JobQueueRecord, JobRuntimeConfigListFilter, JobRuntimeConfigRecord,
62    JobRuntimeConfigUpsert, JobScheduleCatalogSyncEntry, JobScheduleCatalogSyncReport,
63    JobScheduleJobTypeReference, JobScheduleRecord, JobScheduleUpsert, JobSuccessCompletionOutcome,
64    ReapExpiredLeaseDeferredError, ReapExpiredLeasesDetailedResult, ReapExpiredLeasesResult,
65    ReapedLeaseDisposition, ReapedLeaseRecord, ReapedTerminalLeaseRecord,
66};
67pub use workflow_types::{
68    AppendWorkflowStepsInput, AppendWorkflowStepsOutcome, AppendWorkflowStepsResult,
69    CompleteExternalWorkflowStepInput, DEFAULT_WORKFLOW_RUN_WAIT_TIMEOUT, WorkflowRunCountFilter,
70    WorkflowRunDbRecord, WorkflowRunHandle, WorkflowRunHandleError, WorkflowRunHandleScope,
71    WorkflowRunListFilter, WorkflowRunResultRecord, WorkflowRunWaitOptions, WorkflowStepDbRecord,
72    WorkflowStepDependencyDbRecord,
73};
74pub use workflows::{
75    append_workflow_steps, append_workflow_steps_tx, cancel_workflow_run_tx,
76    complete_external_workflow_step, complete_external_workflow_step_tx, count_workflow_runs,
77    count_workflow_step_dependencies, count_workflow_steps, enqueue_workflow_run,
78    enqueue_workflow_run_handle, enqueue_workflow_run_tx, get_latest_workflow_run_by_type,
79    get_workflow_run_by_id, get_workflow_run_by_type_and_idempotency_key,
80    get_workflow_run_by_type_and_idempotency_key_tx, get_workflow_run_id_for_job,
81    list_workflow_runs, list_workflow_step_dependencies, list_workflow_step_dependencies_page,
82    list_workflow_step_keys_for_update_tx, list_workflow_steps, list_workflow_steps_page,
83    retrieve_workflow_run_handle, update_workflow_step_and_pending_job_payload_tx,
84    workflow_run_handle,
85};
86#[cfg(feature = "test-support")]
87pub mod test_support {
88    use runledger_core::jobs::{JobFailure, JobTypeName};
89    use serde_json::Value;
90    use sqlx::types::Uuid;
91
92    use super::types::{ReapedLeaseDisposition, ReapedLeaseRecord, ReapedTerminalLeaseRecord};
93
94    pub use super::workflows::test_support::workflow_run_release_lock_key;
95
96    #[allow(clippy::too_many_arguments)]
97    pub fn reaped_lease_record(
98        job_id: Uuid,
99        job_type: JobTypeName,
100        organization_id: Option<Uuid>,
101        run_number: i32,
102        attempt: i32,
103        max_attempts: i32,
104        worker_id: Option<String>,
105        started_without_renewal_heartbeat: bool,
106        disposition: ReapedLeaseDisposition,
107    ) -> ReapedLeaseRecord {
108        ReapedLeaseRecord {
109            job_id,
110            job_type,
111            organization_id,
112            run_number,
113            attempt,
114            max_attempts,
115            worker_id,
116            started_without_renewal_heartbeat,
117            failure: lease_expired_failure(),
118            disposition,
119        }
120    }
121
122    pub fn reaped_terminal_lease_record(
123        job_id: Uuid,
124        job_type: JobTypeName,
125        organization_id: Option<Uuid>,
126        run_number: i32,
127        attempt: i32,
128        payload: Value,
129    ) -> ReapedTerminalLeaseRecord {
130        ReapedTerminalLeaseRecord {
131            job_id,
132            job_type,
133            organization_id,
134            run_number,
135            attempt,
136            payload,
137        }
138    }
139
140    fn lease_expired_failure() -> JobFailure {
141        JobFailure::lease_expired("job.lease_expired", "Job lease expired before completion.")
142    }
143}
144
145#[deprecated(note = "Use WorkflowRunDbRecord instead.")]
146pub type WorkflowRunRecord = WorkflowRunDbRecord;
147
148#[deprecated(note = "Use WorkflowStepDbRecord instead.")]
149pub type WorkflowStepRecord = WorkflowStepDbRecord;
runledger_postgres/jobs.rs

runledger_postgres/
jobs.rs
