Skip to main content

everruns_durable/
lib.rs

1//! PostgreSQL-backed durable execution for the [Everruns](https://everruns.com)
2//! ecosystem: a claimable task queue, an event log, schedules, a
3//! worker pool, and retries and circuit breakers.
4//!
5//! State lives in PostgreSQL. Workers claim tasks with
6//! `SELECT ... FOR UPDATE SKIP LOCKED`, and anything a dead worker held is
7//! reclaimed and retried, so work survives crashes and restarts with no
8//! infrastructure beyond the database.
9//!
10//! - [`WorkflowEventStore`] is the storage contract, split into focused traits
11//!   such as [`EventLog`], [`TaskQueue`] and [`WorkerRegistry`].
12//!   [`PostgresWorkflowEventStore`] is the production store and
13//!   [`InMemoryWorkflowEventStore`] the test double.
14//! - [`WorkerPool`] claims and runs tasks with bounded concurrency, heartbeats
15//!   and backpressure; [`StaleTaskReaper`] reclaims work from dead workers.
16//! - [`DurableScheduler`] fires cron and interval schedules.
17//! - [`RetryPolicy`], [`ActivityOptions`] and [`DistributedCircuitBreaker`]
18//!   control retries, timeouts and failure isolation.
19//!
20//! The crate knows workflows and tasks as durable records, and nothing about
21//! the domain built on top of it. The Everruns worker's task loop and the
22//! server's cluster jobs drive the task queue directly and own their own
23//! semantics.
24//!
25//! # Example
26//!
27//! The crate ships its own PostgreSQL schema. Apply it with
28//! [`PostgresWorkflowEventStore::migrate`], which is idempotent and safe to call
29//! on every start-up, then enqueue and claim work.
30//!
31//! ```no_run
32//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
33//! use everruns_durable::prelude::*;
34//! use serde_json::json;
35//!
36//! let pool = sqlx::PgPool::connect("postgres://localhost/my_app").await?;
37//! PostgresWorkflowEventStore::migrate(&pool).await?;
38//! let store = PostgresWorkflowEventStore::new(pool);
39//!
40//! let workflow_id = uuid::Uuid::now_v7();
41//! store.create_workflow(workflow_id, "order", json!({}), None).await?;
42//! store
43//!     .enqueue_task(TaskDefinition {
44//!         workflow_id: Some(workflow_id),
45//!         activity_id: "charge".into(),
46//!         activity_type: "charge_card".into(),
47//!         input: json!({ "amount": 42 }),
48//!         options: ActivityOptions::default(),
49//!     })
50//!     .await?;
51//!
52//! let claimed = store.claim_task("worker-1", &["charge_card".into()], 1).await?;
53//! # let _ = claimed;
54//! # Ok(()) }
55//! ```
56
57pub mod activity;
58pub mod maintenance;
59pub mod persistence;
60pub mod reliability;
61pub mod scheduler;
62mod update_field;
63// `/proc` readings for the worker pool's backpressure and the bench reports.
64// Not part of the API.
65pub(crate) mod sysstat;
66// Bounds repeated failure reports per call site (EVE-1328).
67pub(crate) mod report_throttle;
68pub mod task_events;
69pub mod worker;
70pub mod workflow;
71
72// The README's examples are compiled and run as doctests without rendering
73// the README twice in the API docs.
74#[cfg(doctest)]
75#[doc = include_str!("../README.md")]
76struct ReadmeDoctests;
77
78/// PostgreSQL pool passed by an owning host to the durable store API.
79pub type PostgresPool = sqlx::PgPool;
80
81/// Benchmark support utilities
82///
83/// This module provides metrics collection and HTML report generation
84/// for load testing the durable execution engine. Behind the `bench` feature,
85/// which only the crate's own bench binaries enable; not a supported API.
86#[cfg(feature = "bench")]
87#[doc(hidden)]
88pub mod bench;
89
90/// Prelude for common imports
91pub mod prelude {
92    pub use crate::activity::ActivityError;
93    pub use crate::persistence::{
94        CircuitBreakers, ClaimedTask, DeadLetters, DurableAdmin, EventLog,
95        InMemoryWorkflowEventStore, PostgresWorkflowEventStore, Schedules, StoreError,
96        TaskDefinition, TaskQueue, TraceContext, WorkerInfo, WorkerRegistry, WorkflowEventStore,
97        WorkflowStatus,
98    };
99    pub use crate::reliability::{CircuitBreakerConfig, RetryPolicy};
100    pub use crate::scheduler::{DurableScheduler, SchedulerConfig, SchedulerError};
101    pub use crate::worker::{WorkerPool, WorkerPoolConfig, WorkerPoolError};
102    pub use crate::workflow::{ActivityOptions, WorkflowError, WorkflowEvent};
103}
104
105// Root re-exports: the storage contract and its record types, the task event
106// recorders the Everruns worker and server call, and the scheduler, worker
107// pool and reaper entry points. Narrow helpers (env readers, `/proc` readings)
108// stay at their module path or crate-private.
109pub use activity::ActivityError;
110pub use maintenance::{
111    NoopReapHandler, ReapHandler, ReaperConfig, StaleTaskReaper, reap_stale_tasks,
112};
113pub use persistence::{
114    CircuitBreakerState, CircuitBreakers, ClaimedTask, CreateScheduleRow, DeadLetters,
115    DeadTaskInfo, DlqEntry, DlqFilter, DurableAdmin, EventLog, HeartbeatResponse,
116    InMemoryWorkflowEventStore, Pagination, PostgresWorkflowEventStore, ReclaimResult,
117    ScheduleExecutionFilter, ScheduleExecutionRow, ScheduleExecutionStatus, ScheduleFilter,
118    ScheduleRow, ScheduleStats, ScheduleTargetType, SchedulerInstanceInfo, Schedules,
119    SealedTaskInfo, StoreError, SystemHealth, TaskDefinition, TaskFailureOutcome, TaskFilter,
120    TaskInfo, TaskQueue, TaskStatus, TraceContext, UpdateSchedule, WORKER_HEARTBEAT_TIMEOUT_SECS,
121    WorkerFilter, WorkerHeartbeat, WorkerInfo, WorkerRegistry, WorkflowEventInfo,
122    WorkflowEventStore, WorkflowFilter, WorkflowInfo, WorkflowInfoExtended, WorkflowStatus,
123    begin_transaction, commit_in_place, commit_transaction,
124};
125pub use reliability::{
126    CircuitBreakerConfig, CircuitBreakerError, CircuitState, DistributedCircuitBreaker, RetryPolicy,
127};
128pub use scheduler::{
129    Cadence, DurableScheduler, EnsureOutcome, ScheduleSpec, SchedulerConfig, SchedulerError,
130    disable_schedule, ensure_schedule, find_schedule, next_trigger_after,
131};
132// `ScheduleUpdate` fields are `UpdateField`s, so the type stays nameable here.
133pub use update_field::UpdateField;
134pub use worker::{WorkerPool, WorkerPoolConfig, WorkerPoolError};
135pub use workflow::{ActivityOptions, WorkflowError, WorkflowEvent};
136
137// Task event recording, used by the Everruns worker and server sweeps.
138pub use task_events::{
139    append_event, record_activity_completed, record_activity_failed, record_activity_started,
140    record_workflow_cancelled, record_workflow_completed, record_workflow_failed,
141};
142
143pub mod schedule_transaction;