runtara_core/lib.rs
1// Copyright (C) 2025 SyncMyOrders Sp. z o.o.
2// SPDX-License-Identifier: AGPL-3.0-or-later
3//! Runtara Core - Durable Execution Engine
4//!
5//! This crate provides the execution engine for durable workflows. It manages checkpoints,
6//! signals, and instance events, persisting all state to the database for crash resilience.
7//!
8//! # Architecture
9//!
10//! ```text
11//! ┌─────────────────────────────────────────────────────────────────────────┐
12//! │ External Clients │
13//! │ (runtara-management-sdk, CLI) │
14//! └─────────────────────────────────────────────────────────────────────────┘
15//! │
16//! ▼
17//! ┌─────────────────────────────────────────────────────────────────────────┐
18//! │ runtara-environment │
19//! │ (Image Registry, Instance Lifecycle, Wake Queue) │
20//! │ Port 8002 │
21//! └─────────────────────────────────────────────────────────────────────────┘
22//! │ │
23//! │ Shared Persistence │ Spawns
24//! ▼ ▼
25//! ┌───────────────────────┐ ┌─────────────────────────────┐
26//! │ runtara-core │◄───────────────────│ Workflow Instances │
27//! │ (This Crate) │ Instance Protocol │ (using runtara-sdk) │
28//! │ Checkpoints/Signals │ │ │
29//! │ Port 8001 │ └─────────────────────────────┘
30//! └───────────────────────┘
31//! │
32//! ▼
33//! ┌───────────────────────┐
34//! │ PostgreSQL / SQLite │
35//! │ (Durable Storage) │
36//! └───────────────────────┘
37//! ```
38//!
39//! # QUIC Server
40//!
41//! Core exposes one QUIC server:
42//!
43//! | Server | Port | Purpose |
44//! |--------|------|---------|
45//! | Instance Server | 8001 | Workflow instances connect here via runtara-sdk |
46//!
47//! Environment uses the shared `Persistence` trait directly instead of QUIC.
48//!
49//! # Instance Protocol (Port 8001)
50//!
51//! The instance protocol handles all communication between workflow instances and Core.
52//! Instances use [`runtara-sdk`] which wraps this protocol.
53//!
54//! ## Operations
55//!
56//! | Operation | Description |
57//! |-----------|-------------|
58//! | `RegisterInstance` | Self-register on startup, optionally resume from checkpoint |
59//! | `Checkpoint` | Save state (or return existing if checkpoint_id exists) + signal delivery |
60//! | `GetCheckpoint` | Read-only checkpoint lookup |
61//! | `Sleep` | Durable sleep - stores wake time in database |
62//! | `InstanceEvent` | Fire-and-forget events (heartbeat, completed, failed, suspended) |
63//! | `GetInstanceStatus` | Query instance status |
64//! | `PollSignals` | Poll for pending cancel/pause/resume signals |
65//! | `SignalAck` | Acknowledge receipt of a signal |
66//!
67//! ## Checkpoint Semantics
68//!
69//! The `Checkpoint` operation is the primary durability mechanism:
70//!
71//! 1. **First call with checkpoint_id**: Saves state, returns empty `existing_state`
72//! 2. **Subsequent calls with same checkpoint_id**: Returns existing state (for resume)
73//! 3. **Signal delivery**: Returns pending signals in response for efficient poll-free detection
74//!
75//! ## Durable Sleep
76//!
77//! The `Sleep` operation stores a `sleep_until` timestamp in the instances table.
78//! Environment's wake scheduler polls for sleeping instances and relaunches them
79//! when their wake time arrives. On resume, the SDK calculates remaining sleep time.
80//!
81//! # Instance Status State Machine
82//!
83//! ```text
84//! ┌─────────┐
85//! │ PENDING │
86//! └────┬────┘
87//! │ register
88//! ▼
89//! ┌─────────┐
90//! ┌──────────│ RUNNING │──────────┐
91//! │ └────┬────┘ │
92//! │ │ │
93//! pause│ sleep│ cancel
94//! │ │ │
95//! ▼ ▼ ▼
96//! ┌──────────┐ ┌──────────┐ ┌───────────┐
97//! │SUSPENDED │ │SUSPENDED │ │ CANCELLED │
98//! └────┬─────┘ └────┬─────┘ └───────────┘
99//! │ │
100//! resume│ wake│
101//! │ │
102//! └───────┬───────┘
103//! │
104//! ▼
105//! ┌─────────┐
106//! │ RUNNING │──────────┬──────────┐
107//! └─────────┘ │ │
108//! complete fail
109//! │ │
110//! ▼ ▼
111//! ┌───────────┐ ┌────────┐
112//! │ COMPLETED │ │ FAILED │
113//! └───────────┘ └────────┘
114//! ```
115//!
116//! ## Status Descriptions
117//!
118//! | Status | Description |
119//! |--------|-------------|
120//! | `PENDING` | Instance created but not yet registered |
121//! | `RUNNING` | Instance is actively executing |
122//! | `SUSPENDED` | Instance paused (by signal) or sleeping (durable sleep) |
123//! | `COMPLETED` | Instance finished successfully |
124//! | `FAILED` | Instance failed with error |
125//! | `CANCELLED` | Instance was cancelled via signal |
126//!
127//! # Configuration
128//!
129//! Configuration is loaded from environment variables:
130//!
131//! | Variable | Required | Default | Description |
132//! |----------|----------|---------|-------------|
133//! | `RUNTARA_DATABASE_URL` | Yes | - | PostgreSQL or SQLite connection string |
134//! | `RUNTARA_QUIC_PORT` | No | `8001` | Instance QUIC server port |
135//! | `RUNTARA_MAX_CONCURRENT_INSTANCES` | No | `32` | Maximum concurrent instances |
136//!
137//! # Modules
138//!
139//! - [`config`]: Server configuration from environment variables
140//! - [`persistence`]: Database persistence layer for instances, checkpoints, events, signals
141//! - [`error`]: Error types with RPC error code mapping
142//! - [`instance_handlers`]: Instance protocol request handlers
143//! - [`server`]: QUIC server implementation
144
145#![deny(missing_docs)]
146
147/// Database migrations for runtara-core.
148///
149/// Products embedding runtara-core can use this module to run migrations:
150///
151/// ```ignore
152/// use runtara_core::migrations;
153///
154/// let pool = PgPool::connect(&database_url).await?;
155/// migrations::run_postgres(&pool).await?;
156/// ```
157pub mod migrations;
158
159/// Persistence layer for instances, checkpoints, events, and signals.
160pub mod persistence;
161
162/// Error types for Core operations with RPC error code mapping.
163pub mod error;
164
165// Server-mode modules (require QUIC transport)
166#[cfg(feature = "server")]
167/// Server configuration loaded from environment variables.
168pub mod config;
169
170#[cfg(feature = "server")]
171/// Instance protocol handlers (registration, checkpoints, events, signals).
172pub mod instance_handlers;
173
174#[cfg(feature = "server")]
175/// QUIC server implementation for the instance protocol.
176pub mod server;
177
178#[cfg(feature = "server")]
179/// Embeddable runtime for runtara-core.
180pub mod runtime;