Crate runtara_sdk 

Runtara SDK - High-level client for instance communication with runtara-core.

This crate provides an ergonomic API for scenarios/instances to communicate with the runtara-core durable execution engine. It provides strongly-typed methods for all instance lifecycle operations.

Features

• Instance Registration: Self-register with runtara-core on startup
• Checkpointing: Save state for durability with automatic resume handling
• Durable Sleep: Request sleep with automatic checkpoint/wake
• Lifecycle Events: Send heartbeat, completed, failed events
• Signal Handling: Poll and handle cancel, pause, resume signals
• Status Queries: Query instance status and server health

Quick Start

use runtara_sdk::RuntaraSdk;

fn main() -> runtara_sdk::Result<()> {
    let mut sdk = RuntaraSdk::from_env()?;

    // Connect and register
    sdk.connect()?;
    sdk.register(None)?;

    // Process items with checkpointing
    for i in 0..items.len() {
        let state = serde_json::to_vec(&my_state)?;
        let result = sdk.checkpoint(&format!("item-{}", i), &state)?;

        // Check for pause/cancel signals
        if result.should_cancel() {
            return Err(SdkError::Cancelled.into());
        }
        if result.should_pause() {
            sdk.suspended()?;
            return Ok(());
        }

        if let Some(existing) = result.existing_state() {
            // Resuming - restore state and skip
            my_state = serde_json::from_slice(existing)?;
            continue;
        }
        // Fresh execution - process item
        process_item(&items[i]);
    }

    sdk.completed(b"result data")?;
    Ok(())
}

Configuration

The SDK can be configured via environment variables or programmatically:

Environment Variables

Variable	Required	Default	Description
RUNTARA_INSTANCE_ID	Yes	-	Unique instance identifier
RUNTARA_TENANT_ID	Yes	-	Tenant identifier
RUNTARA_HTTP_URL	No	http://127.0.0.1:8003	HTTP API URL
RUNTARA_REQUEST_TIMEOUT_MS	No	30000	Request timeout
RUNTARA_SIGNAL_POLL_INTERVAL_MS	No	1000	Signal poll rate limit

Programmatic Configuration

use runtara_sdk::HttpSdkConfig;

let config = HttpSdkConfig {
    instance_id: "my-instance".to_string(),
    tenant_id: "my-tenant".to_string(),
    base_url: "http://192.168.1.100:8003".to_string(),
    request_timeout_ms: 30_000,
    signal_poll_interval_ms: 500,
    heartbeat_interval_ms: 30_000,
};

let sdk = RuntaraSdk::new(config)?;

Structs

CheckpointResult

Checkpoint response with signal information.

CustomSignal

Custom signal targeted to a specific checkpoint/wait key.

HttpSdkConfig

Configuration for the HTTP backend.

RetryConfig

Configuration for retry behavior in durable functions.

RuntaraSdk

High-level SDK client for instance communication with runtara-core.

Signal

A signal received from runtara-core.

StatusResponse

Instance status response with full details.

Enums

InstanceStatus

Instance status as returned by status queries.

RetryStrategy

Retry strategy for durable functions.

SdkError

Errors that can occur in the SDK.

SignalType

Signal types that can be received from runtara-core.

Traits

Persistence

Persistence interface used by core handlers.

Functions

acknowledge_cancellation

Acknowledge cancellation to runtara-core.

acknowledge_pause

Acknowledge a pause signal to runtara-core.

is_cancelled

Check if the instance has been cancelled.

register_sdk

Register an SDK instance globally for use by #[durable] functions.

sdk

Get a reference to the registered SDK.

stop_heartbeat

Stop the background heartbeat task.

trigger_cancellation

Trigger cancellation programmatically.

try_sdk

Try to get a reference to the registered SDK.

with_cancellation

Execute a closure with cancellation support.

with_cancellation_err

Check a result with cancellation support, using a custom error type.

Type Aliases

Result

Type alias for SDK results.

Attribute Macros

durable

Makes a function durable by wrapping it with checkpoint-based caching and retry support.