Crate runtara_core 

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

┌─────────────────────────────────────────────────────────────────────────┐
│                         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)    │
└───────────────────────┘

QUIC Server

Core exposes one QUIC server:

Server	Port	Purpose
Instance Server	8001	Workflow instances connect here via runtara-sdk

Environment uses the shared Persistence trait directly instead of QUIC.

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

                    ┌─────────┐
                    │ 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_QUIC_PORT	No	8001	Instance QUIC 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: QUIC server implementation

Modules

config

Server configuration loaded from environment variables. Configuration loading from environment variables.

error

Error types for Core operations with RPC error code mapping. Error types for runtara-core.

instance_handlers

Instance protocol handlers (registration, checkpoints, events, signals). Instance protocol handlers for runtara-core.

migrations

Database migrations for runtara-core.

persistence

Persistence layer for instances, checkpoints, events, and signals. Persistence interfaces and backends for runtara-core.

runtime

Embeddable runtime for runtara-core. Embeddable runtime for runtara-core.

server

QUIC server implementation for the instance protocol. QUIC server for runtara-core.