runtara-core 1.6.4

// Copyright (C) 2025 SyncMyOrders Sp. z o.o.
// SPDX-License-Identifier: AGPL-3.0-or-later
//! Runtara Core - Durable Execution Engine
//!
//! This crate provides the execution engine for durable workflows. It manages checkpoints,
//! signals, and instance events, persisting all state to the database for crash resilience.
//!
//! # Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────────────────┐
//! │                         External Clients                                 │
//! │                    (runtara-management-sdk, CLI)                         │
//! └─────────────────────────────────────────────────────────────────────────┘
//!                                    │
//!                                    ▼
//! ┌─────────────────────────────────────────────────────────────────────────┐
//! │                      runtara-environment                                 │
//! │            (Image Registry, Instance Lifecycle, Wake Queue)              │
//! │                           Port 8002                                      │
//! └─────────────────────────────────────────────────────────────────────────┘
//!           │                                              │
//!           │ Shared Persistence                           │ Spawns
//!           ▼                                              ▼
//! ┌───────────────────────┐                    ┌─────────────────────────────┐
//! │    runtara-core       │◄───────────────────│     Workflow Instances      │
//! │  (This Crate)         │  Instance Protocol │   (using runtara-sdk)       │
//! │  Checkpoints/Signals  │                    │                             │
//! │  Port 8001            │                    └─────────────────────────────┘
//! └───────────────────────┘
//!           │
//!           ▼
//! ┌───────────────────────┐
//! │  PostgreSQL / SQLite  │
//! │  (Durable Storage)    │
//! └───────────────────────┘
//! ```
//!
//! # HTTP Server
//!
//! Core exposes one HTTP server:
//!
//! | Server | Port | Purpose |
//! |--------|------|---------|
//! | Instance Server | 8001 | Workflow instances connect here via runtara-sdk |
//!
//! Environment uses the shared `Persistence` trait directly instead of HTTP.
//!
//! # Instance Protocol (Port 8001)
//!
//! The instance protocol handles all communication between workflow instances and Core.
//! Instances use [`runtara-sdk`] which wraps this protocol.
//!
//! ## Operations
//!
//! | Operation | Description |
//! |-----------|-------------|
//! | `RegisterInstance` | Self-register on startup, optionally resume from checkpoint |
//! | `Checkpoint` | Save state (or return existing if checkpoint_id exists) + signal delivery |
//! | `GetCheckpoint` | Read-only checkpoint lookup |
//! | `Sleep` | Durable sleep - stores wake time in database |
//! | `InstanceEvent` | Fire-and-forget events (heartbeat, completed, failed, suspended) |
//! | `GetInstanceStatus` | Query instance status |
//! | `PollSignals` | Poll for pending cancel/pause/resume signals |
//! | `SignalAck` | Acknowledge receipt of a signal |
//!
//! ## Checkpoint Semantics
//!
//! The `Checkpoint` operation is the primary durability mechanism:
//!
//! 1. **First call with checkpoint_id**: Saves state, returns empty `existing_state`
//! 2. **Subsequent calls with same checkpoint_id**: Returns existing state (for resume)
//! 3. **Signal delivery**: Returns pending signals in response for efficient poll-free detection
//!
//! ## Durable Sleep
//!
//! The `Sleep` operation stores a `sleep_until` timestamp in the instances table.
//! Environment's wake scheduler polls for sleeping instances and relaunches them
//! when their wake time arrives. On resume, the SDK calculates remaining sleep time.
//!
//! # Instance Status State Machine
//!
//! ```text
//!                     ┌─────────┐
//!                     │ PENDING │
//!                     └────┬────┘
//!                          │ register
//!                          ▼
//!                     ┌─────────┐
//!          ┌──────────│ RUNNING │──────────┐
//!          │          └────┬────┘          │
//!          │               │               │
//!     pause│          sleep│          cancel
//!          │               │               │
//!          ▼               ▼               ▼
//!     ┌──────────┐   ┌──────────┐   ┌───────────┐
//!     │SUSPENDED │   │SUSPENDED │   │ CANCELLED │
//!     └────┬─────┘   └────┬─────┘   └───────────┘
//!          │               │
//!     resume│          wake│
//!          │               │
//!          └───────┬───────┘
//!                  │
//!                  ▼
//!             ┌─────────┐
//!             │ RUNNING │──────────┬──────────┐
//!             └─────────┘          │          │
//!                             complete      fail
//!                                  │          │
//!                                  ▼          ▼
//!                            ┌───────────┐ ┌────────┐
//!                            │ COMPLETED │ │ FAILED │
//!                            └───────────┘ └────────┘
//! ```
//!
//! ## Status Descriptions
//!
//! | Status | Description |
//! |--------|-------------|
//! | `PENDING` | Instance created but not yet registered |
//! | `RUNNING` | Instance is actively executing |
//! | `SUSPENDED` | Instance paused (by signal) or sleeping (durable sleep) |
//! | `COMPLETED` | Instance finished successfully |
//! | `FAILED` | Instance failed with error |
//! | `CANCELLED` | Instance was cancelled via signal |
//!
//! # Configuration
//!
//! Configuration is loaded from environment variables:
//!
//! | Variable | Required | Default | Description |
//! |----------|----------|---------|-------------|
//! | `RUNTARA_DATABASE_URL` | Yes | - | PostgreSQL or SQLite connection string |
//! | `RUNTARA_HTTP_PORT` | No | `8001` | Instance HTTP server port |
//! | `RUNTARA_MAX_CONCURRENT_INSTANCES` | No | `32` | Maximum concurrent instances |
//!
//! # Modules
//!
//! - [`config`]: Server configuration from environment variables
//! - [`persistence`]: Database persistence layer for instances, checkpoints, events, signals
//! - [`error`]: Error types with RPC error code mapping
//! - [`instance_handlers`]: Instance protocol request handlers
//! - [`server`]: HTTP server implementation

#![deny(missing_docs)]

/// Database migrations for runtara-core.
///
/// Products embedding runtara-core can use this module to run migrations:
///
/// ```ignore
/// use runtara_core::migrations;
///
/// let pool = PgPool::connect(&database_url).await?;
/// migrations::run_postgres(&pool).await?;
/// ```
pub mod migrations;

/// Persistence layer for instances, checkpoints, events, and signals.
pub mod persistence;

/// Error types for Core operations with RPC error code mapping.
pub mod error;

/// Compensation framework for saga pattern support.
pub mod compensation;

// Server-mode modules (require HTTP transport)
#[cfg(feature = "server")]
/// Server configuration loaded from environment variables.
pub mod config;

#[cfg(feature = "server")]
/// Instance protocol handlers (registration, checkpoints, events, signals).
pub mod instance_handlers;

#[cfg(feature = "server")]
/// HTTP server implementation for the instance protocol.
pub mod server;

#[cfg(feature = "server")]
/// Embeddable runtime for runtara-core.
pub mod runtime;