Struct RuntaraSdk

Source

pub struct RuntaraSdk { /* private fields */ }

Expand description

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

This client wraps a backend (QUIC or embedded) and provides ergonomic methods for all instance lifecycle operations.

§Example (QUIC mode)

use runtara_sdk::RuntaraSdk;

let mut sdk = RuntaraSdk::localhost("my-instance", "my-tenant")?;
sdk.connect().await?;
sdk.register(None).await?;

// Process items with checkpointing
for i in 0..items.len() {
    let state = serde_json::to_vec(&my_state)?;
    if let Some(existing) = sdk.checkpoint(&format!("item-{}", i), &state).await? {
        // 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").await?;

§Example (Embedded mode)

use runtara_sdk::RuntaraSdk;
use std::sync::Arc;

// Create persistence layer (e.g., SQLite or PostgreSQL)
let persistence: Arc<dyn Persistence> = create_persistence().await?;

let mut sdk = RuntaraSdk::embedded(persistence, "my-instance", "my-tenant");
sdk.connect().await?;  // No-op for embedded
sdk.register(None).await?;

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

sdk.completed(b"result").await?;

Implementations§

Source §

impl RuntaraSdk

Source

pub fn new(config: SdkConfig) -> Result<RuntaraSdk, SdkError>

Create a new SDK instance with the given configuration.

This creates a QUIC-based SDK that connects to runtara-core over the network.

Source

pub fn from_env() -> Result<RuntaraSdk, SdkError>

Create an SDK instance from environment variables.

See SdkConfig::from_env for required and optional environment variables.

Source

pub fn localhost( instance_id: impl Into<String>, tenant_id: impl Into<String>, ) -> Result<RuntaraSdk, SdkError>

Create an SDK instance for local development.

This connects to 127.0.0.1:8001 with TLS verification disabled.

Source

pub async fn init(self, checkpoint_id: Option<&str>) -> Result<(), SdkError>

Initialize SDK: connect, register, and make available globally for #[durable].

This is a convenience method that combines:

connect() - establish connection to runtara-core
register(checkpoint_id) - register this instance
register_sdk() - make SDK available globally for #[durable] functions

§Example

use runtara_sdk::RuntaraSdk;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // One-liner setup for #[durable] functions
    RuntaraSdk::localhost("my-instance", "my-tenant")?
        .init(None)
        .await?;

    // Now #[durable] functions work automatically
    my_durable_function("key".to_string(), args).await?;
    Ok(())
}

Source

pub async fn connect(&self) -> Result<(), SdkError>

Connect to runtara-core.

Source

pub async fn is_connected(&self) -> bool

Check if connected to runtara-core.

Source

pub async fn close(&self)

Close the connection to runtara-core.

Source

pub async fn register( &mut self, checkpoint_id: Option<&str>, ) -> Result<(), SdkError>

Register this instance with runtara-core.

This should be called at instance startup. If checkpoint_id is provided, the instance is resuming from a checkpoint.

Source

pub async fn checkpoint( &self, checkpoint_id: &str, state: &[u8], ) -> Result<CheckpointResult, SdkError>

Checkpoint with the given ID and state.

This is the primary checkpoint method that handles both save and resume:

If a checkpoint with this ID already exists, returns the existing state (for resume)
If no checkpoint exists, saves the provided state and returns None

This also serves as a heartbeat - each checkpoint call reports progress to runtara-core.

The returned CheckpointResult also includes any pending signal (cancel, pause) that the instance should handle after processing the checkpoint.

§Example

// In a loop - checkpoint handles both fresh runs and resumes
for i in 0..items.len() {
    let checkpoint_id = format!("item-{}", i);
    let result = sdk.checkpoint(&checkpoint_id, &state).await?;

    // Check for pending signals
    if result.should_cancel() {
        return Err("Cancelled".into());
    }
    if result.should_pause() {
        // Exit cleanly - will be resumed later
        return Ok(());
    }

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

Source

pub async fn get_checkpoint( &self, checkpoint_id: &str, ) -> Result<Option<Vec<u8>>, SdkError>

Get a checkpoint by ID without saving (read-only lookup).

Returns the checkpoint state if found, or None if not found. Use this when you want to check if a cached result exists before executing.

§Example

// Check if result is already cached
if let Some(cached_state) = sdk.get_checkpoint("my-operation").await? {
    let result: MyResult = serde_json::from_slice(&cached_state)?;
    return Ok(result);
}
// Not cached - execute operation and save result
let result = do_expensive_operation();
let state = serde_json::to_vec(&result)?;
sdk.checkpoint("my-operation", &state).await?;

Source

pub async fn sleep( &self, duration: Duration, checkpoint_id: &str, state: &[u8], ) -> Result<(), SdkError>

Request to sleep for the specified duration.

This is a durable sleep that persists across restarts:

Saves a checkpoint with the provided state
Records the wake time (sleep_until) in the database
On resume, calculates remaining time and only sleeps for the remainder

In QUIC mode, the server tracks the wake time. In embedded mode, the persistence layer tracks it directly.

Source

pub async fn heartbeat(&self) -> Result<(), SdkError>

Send a heartbeat event (simple “I’m alive” signal).

Use this for progress reporting without checkpointing. For durable progress, use checkpoint() instead.

Source

pub async fn completed(&self, output: &[u8]) -> Result<(), SdkError>

Send a completed event with output.

Source

pub async fn failed(&self, error: &str) -> Result<(), SdkError>

Send a failed event with error message.

Source

pub async fn suspended(&self) -> Result<(), SdkError>

Send a suspended event.

Source

pub async fn custom_event( &self, subtype: &str, payload: Vec<u8>, ) -> Result<(), SdkError>

Send a custom event with arbitrary subtype and payload.

This is a fire-and-forget event stored by runtara-core with the given subtype. Core treats the subtype as an opaque string without any semantic interpretation.

§Arguments

subtype - Arbitrary event subtype string
payload - Event payload as raw bytes (typically JSON serialized)

§Example

let payload = serde_json::to_vec(&my_event_data)?;
sdk.custom_event("my_custom_event", payload).await?;

Source

pub async fn poll_signal(&mut self) -> Result<Option<Signal>, SdkError>

Poll for pending signals.

Rate-limited to avoid hammering the server. Returns Some(Signal) if a signal is pending, None otherwise.