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::JobCompletion`], 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(
55//! &self,
56//! _context: JobContext,
57//! _payload: Value,
58//! ) -> Result<JobCompletion, JobFailure> {
59//! Ok(JobCompletion::success())
60//! }
61//! }
62//! ```
63//!
64//! # Build A Workflow DAG
65//!
66//! ```rust
67//! use runledger_core::prelude::*;
68//!
69//! let crawl_payload = serde_json::json!({"profile_id": "p_123"});
70//! let classify_payload = serde_json::json!({"profile_id": "p_123"});
71//! let metadata = serde_json::json!({"source": "api"});
72//!
73//! let run = WorkflowDagBuilder::new("profiles.research", &metadata)
74//! .job("crawl", "profiles.crawl", &crawl_payload)?
75//! .job("classify", "profiles.classify", &classify_payload)?
76//! .after_success("classify", ["crawl"])?
77//! .build()?;
78//! # Ok::<_, WorkflowBuildError>(())
79//! ```
80
81pub mod jobs;
82
83/// Common `runledger-core` imports for consumers.
84///
85/// This prelude contains storage-agnostic job and workflow contracts. It avoids
86/// generic `Result` or `Error` aliases so it can be glob-imported alongside
87/// `runledger_postgres::prelude::*` and `runledger_runtime::prelude::*`.
88pub mod prelude {
89 pub use async_trait::async_trait;
90
91 pub use crate::jobs::{
92 IdentifierValidationError, JobCompletion, JobContext, JobDeadLetterInfo,
93 JobDeadLetterReason, JobEventType, JobFailure, JobFailureKind, JobHandler,
94 JobHandlerRegistry, JobStage, JobStatus, JobType, JobTypeName, StepKey, StepKeyName,
95 WorkflowBuildError, WorkflowDagBuilder, WorkflowDagDependencyValidationInput,
96 WorkflowDagStepValidationInput, WorkflowDagValidationError, WorkflowDependencyReleaseMode,
97 WorkflowRunEnqueue, WorkflowRunEnqueueBuilder, WorkflowRunStatus,
98 WorkflowStepDependencySpec, WorkflowStepEnqueue, WorkflowStepEnqueueBuilder,
99 WorkflowStepExecutionKind, WorkflowStepStatus, WorkflowType, WorkflowTypeName,
100 validate_workflow_dag, validate_workflow_run_enqueue, validate_workflow_step_append,
101 };
102}