Rust Client Guide

This guide walks through connecting the Rust SDK (clients/rust) to a running Shirly deployment. It assumes the scheduler binaries are online as described in ../binaries_setup.md.

1. Install

Add the client crate to your workspace by referencing the shipped path or published package:

# Cargo.toml
[dependencies]
shirly-client = { path = "../../clients/rust" }

Then fetch dependencies:

cargo fetch

2. Configure Environment

The client needs the API gateway URL and (optionally) a bearer token:

export SHIRLY_API_URL="http://localhost:8080/api/v1"
export SHIRLY_API_KEY="optional-token"        # omit if not required

3. Submit & Track Jobs

use shirly_client::{Client, SubmitJobRequest};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let base = std::env::var("SHIRLY_API_URL").unwrap_or_else(|_| "http://localhost:8080/api/v1".into());
    let api_key = std::env::var("SHIRLY_API_KEY").ok();

    let client = Client::new(&base, api_key.as_deref())?;

    let req = SubmitJobRequest {
        priority: Some("critical".into()), // optional: "normal" by default
        payload: json!({ "kind": "email", "to": "ops@example.com" }),
        max_retries: Some(3),
        ..Default::default()
    };

    let job = client.submit_job(req).await?;
    println!("submitted job {}", job.job_id);

    // Poll until completion
    loop {
        let status = client.get_job_status(&job.job_id).await?;
        println!("job state {}", status.state);
        if matches!(status.state.as_str(), "completed" | "failed") {
            break;
        }
        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
    }

    Ok(())
}

If priority is omitted it defaults to "normal". Use "critical" to target the high-priority stream queue.

4. Scheduled Jobs & Workflows

The client exposes helpers for advanced scenarios:

• create_scheduled_job to register cron/interval jobs.
• create_workflow to submit DAG-based workflows.
• submit_job_batch to push many jobs in one request.

Refer to the crate documentation (cargo doc --open -p shirly-client) for payload structures such as CreateScheduledJobRequest and WorkflowConfigRequest.

5. Admin Operations

Administrative endpoints map to hosted methods:

• list_workers, get_system_overview
• pause_queue, resume_queue
• list_dlq, replay_dlq
• pause_scheduler, resume_scheduler

These calls require the API to be started with appropriate access controls (e.g., API key or reverse proxy).

6. Testing

The client ships with integration tests that assume a local stack:

cargo test -p shirly-client --features integration -- --test-threads=1

Use this guide when packaging or documenting the Rust SDK for downstream users.