runledger_core/lib.rs
1//! Core durable-execution contracts shared by Runledger storage, runtime, and
2//! application crates.
3//!
4//! Use this crate for the storage-agnostic pieces of the job system:
5//! - [`jobs::JobHandler`] and [`jobs::JobHandlerRegistry`] for handler contracts
6//! - [`jobs::JobContext`], [`jobs::JobProgress`], and [`jobs::JobFailure`] for
7//! execution-time state
8//! - workflow enqueue builders and validation helpers such as
9//! [`jobs::WorkflowDagBuilder`], [`jobs::WorkflowRunEnqueueBuilder`], and
10//! [`jobs::validate_workflow_run_enqueue`]
11//!
12//! Use workflow builders when work has dependencies, fan-out/fan-in, external
13//! gates, or workflow-level idempotency. A single direct job is appropriate only
14//! for one independent unit of retried work.
15//!
16//! This crate does not provide persistence or worker loops. Pair it with
17//! `runledger-postgres` for PostgreSQL-backed storage and `runledger-runtime`
18//! for worker, scheduler, and reaper execution.
19//!
20//! # Copy-Paste Examples
21//!
22//! - [Enqueue one job](https://github.com/featherenvy/runledger/blob/master/runledger-postgres/examples/enqueue_job.rs)
23//! - [Enqueue a workflow DAG](https://github.com/featherenvy/runledger/blob/master/runledger-postgres/examples/workflow_dag.rs)
24//! - [Use an external workflow gate](https://github.com/featherenvy/runledger/blob/master/runledger-postgres/examples/external_gate.rs)
25//! - [Run a worker binary](https://github.com/featherenvy/runledger/blob/master/runledger-runtime/examples/worker_binary.rs)
26//! - [Create a scheduled job entrypoint](https://github.com/featherenvy/runledger/blob/master/runledger-postgres/examples/schedule_job.rs)
27//!
28//! # Prelude
29//!
30//! Import the common contracts with:
31//!
32//! ```rust
33//! use runledger_core::prelude::*;
34//! ```
35//!
36//! The prelude intentionally exports contract types and builders, not storage or
37//! runtime APIs. Pair it with `runledger_postgres::prelude::*` and
38//! `runledger_runtime::prelude::*` in integration crates.
39//!
40//! # Build A Job Handler
41//!
42//! ```rust
43//! use runledger_core::prelude::*;
44//! use serde_json::Value;
45//!
46//! struct SendEmail;
47//!
48//! #[async_trait]
49//! impl JobHandler for SendEmail {
50//! fn job_type(&self) -> JobType<'static> {
51//! JobType::new("jobs.email.send")
52//! }
53//!
54//! async fn execute(&self, _context: JobContext, _payload: Value) -> Result<(), JobFailure> {
55//! Ok(())
56//! }
57//! }
58//! ```
59//!
60//! # Build A Workflow DAG
61//!
62//! ```rust
63//! use runledger_core::prelude::*;
64//!
65//! let crawl_payload = serde_json::json!({"profile_id": "p_123"});
66//! let classify_payload = serde_json::json!({"profile_id": "p_123"});
67//! let metadata = serde_json::json!({"source": "api"});
68//!
69//! let run = WorkflowDagBuilder::new("profiles.research", &metadata)
70//! .job("crawl", "profiles.crawl", &crawl_payload)?
71//! .job("classify", "profiles.classify", &classify_payload)?
72//! .after_success("classify", ["crawl"])?
73//! .build()?;
74//! # Ok::<_, WorkflowBuildError>(())
75//! ```
76
77pub mod jobs;
78
79/// Common `runledger-core` imports for consumers.
80///
81/// This prelude contains storage-agnostic job and workflow contracts. It avoids
82/// generic `Result` or `Error` aliases so it can be glob-imported alongside
83/// `runledger_postgres::prelude::*` and `runledger_runtime::prelude::*`.
84pub mod prelude {
85 pub use async_trait::async_trait;
86
87 pub use crate::jobs::{
88 IdentifierValidationError, JobContext, JobDeadLetterInfo, JobDeadLetterReason,
89 JobEventType, JobFailure, JobFailureKind, JobHandler, JobHandlerRegistry, JobProgress,
90 JobStage, JobStatus, JobType, JobTypeName, StepKey, StepKeyName, WorkflowBuildError,
91 WorkflowDagBuilder, WorkflowDagDependencyValidationInput, WorkflowDagStepValidationInput,
92 WorkflowDagValidationError, WorkflowDependencyReleaseMode, WorkflowRunEnqueue,
93 WorkflowRunEnqueueBuilder, WorkflowRunStatus, WorkflowStepDependencySpec,
94 WorkflowStepEnqueue, WorkflowStepEnqueueBuilder, WorkflowStepExecutionKind,
95 WorkflowStepStatus, WorkflowType, WorkflowTypeName, validate_workflow_dag,
96 validate_workflow_run_enqueue, validate_workflow_step_append,
97 };
98}