Crate runtara_environment

Expand description

Runtara Environment - Instance Lifecycle Management

This crate provides the control plane for managing workflow instances. It handles image registration, instance lifecycle, container execution, and wake scheduling for durable sleeps.

§Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                         External Clients                                 │
│                    (runtara-management-sdk, CLI)                         │
└─────────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                   runtara-environment (This Crate)                       │
│                         Port 8002                                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Image     │  │  Instance   │  │    Wake     │  │  Container  │     │
│  │  Registry   │  │  Lifecycle  │  │  Scheduler  │  │   Runner    │     │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘     │
└─────────────────────────────────────────────────────────────────────────┘
          │                 │                              │
          │                 │ Proxy signals                │ Spawn
          │                 ▼                              ▼
          │       ┌───────────────────┐        ┌─────────────────────────┐
          │       │   runtara-core    │◄───────│   Workflow Instances    │
          │       │   Port 8001/8003  │        │   (OCI containers)      │
          │       └───────────────────┘        └─────────────────────────┘
          │                 │
          ▼                 ▼
┌───────────────────────────────────────────────────────────────────────┐
│                           PostgreSQL                                   │
│              (Images, Instances, Wake Queue)                          │
└───────────────────────────────────────────────────────────────────────┘

§HTTP Server (Environment Protocol - Port 8002)

Environment exposes an HTTP server for all management operations. External clients (via runtara-management-sdk) connect here.

§Image Operations

Operation	Description
`RegisterImage`	Register a new image (single-frame upload < 16MB)
`RegisterImageStream`	Register a large image via streaming upload
`ListImages`	List images with optional tenant filter and pagination
`GetImage`	Get image details by ID
`DeleteImage`	Delete an image

§Instance Operations

Operation	Description
`StartInstance`	Start a new instance from an image
`StopInstance`	Stop a running instance with grace period
`ResumeInstance`	Resume a suspended instance
`GetInstanceStatus`	Query instance status
`ListInstances`	List instances with filtering and pagination

§Signal Operations

Operation	Description
`SendSignal`	Send cancel/pause/resume signal to instance

Signals are proxied to runtara-core which stores them for the instance.

§Runner Types

Environment supports multiple runner backends for executing workflow binaries:

Runner	Description
OCI (default)	Execute in OCI containers via runc
Native	Execute as direct processes (development)
Wasm	Execute as WebAssembly modules (planned)

§Instance Status State Machine

                    ┌─────────┐
                    │ PENDING │
                    └────┬────┘
                         │ register
                         ▼
                    ┌─────────┐
         ┌──────────│ RUNNING │──────────┐
         │          └────┬────┘          │
         │               │               │
    pause│          sleep│          cancel
         │               │               │
         ▼               ▼               ▼
    ┌──────────┐   ┌──────────┐   ┌───────────┐
    │SUSPENDED │   │SUSPENDED │   │ CANCELLED │
    └────┬─────┘   └────┬─────┘   └───────────┘
         │               │
    resume│          wake│
         │               │
         └───────┬───────┘
                 │
                 ▼
            ┌─────────┐
            │ RUNNING │──────────┬──────────┐
            └─────────┘          │          │
                            complete      fail
                                 │          │
                                 ▼          ▼
                           ┌───────────┐ ┌────────┐
                           │ COMPLETED │ │ FAILED │
                           └───────────┘ └────────┘

§Configuration

Configuration is loaded from environment variables:

Variable	Required	Default	Description
`RUNTARA_ENVIRONMENT_DATABASE_URL`	Yes*	-	PostgreSQL connection string
`RUNTARA_DATABASE_URL`	Yes*	-	Fallback if above not set
`RUNTARA_ENV_HTTP_PORT`	No	`8002`	HTTP server port
`RUNTARA_CORE_ADDR`	No	`127.0.0.1:8001`	runtara-core address
`DATA_DIR`	No	`.data`	Data directory for images and bundles
`RUNTARA_SKIP_CERT_VERIFICATION`	No	`false`	Skip TLS verification

§Modules

config: Server configuration from environment variables
db: PostgreSQL persistence for images, instances, and wake queue
error: Error types for Environment operations
handlers: Environment protocol request handlers
image_registry: Image storage and retrieval
container_registry: Running container tracking
instance_output: Instance output types (legacy, used by SDK)
runner: Container/process execution backends
http_server: HTTP server implementation
wake_scheduler: Durable sleep wake scheduling

Re-exports§

pub use config::Config;
pub use error::Error;

Modules§

cleanup_worker: Background worker for cleaning up old run directories. Background worker for cleaning up old run directories.
config: Server configuration loaded from environment variables. Configuration for runtara-environment.
container_registry: Running container tracking and management. Container Registry
db: PostgreSQL database operations for images, instances, and wake queue. Database operations for runtara-environment.
db_cleanup_worker: Background worker for cleaning up old database records. Background worker for cleaning up old database records.
error: Error types for Environment operations. Error types for runtara-environment.
handlers: Environment protocol request handlers. Environment protocol handlers.
heartbeat_monitor: Background worker for detecting and failing stale instances. Background worker for detecting and failing stale instances.
http_server: HTTP server for the Environment protocol. HTTP server for the environment protocol.
image_cleanup_worker: Background worker for cleaning up unused images. Background worker for cleaning up unused images.
image_registry: Image storage and retrieval. Image Registry
instance_output: Instance output types (legacy, used by SDK). Instance output handling.
migrations: Database migrations for runtara-environment.
runner: Container/process execution backends (OCI, Native, Wasm). Runner module - instance execution backends.
runtime: Embeddable runtime for runtara-environment. Embeddable runtime for runtara-environment.
wake_scheduler: Durable sleep wake scheduling. Wake scheduler for durable sleep.