Runbeam SDK

A Rust library for integrating with the Runbeam Cloud API.

Features

• JWT Token Validation - RS256 signature verification with automatic JWKS caching
• API Client - Comprehensive HTTP client for Runbeam Cloud API
  • Gateway management (list, get, create, update, delete)
  • Service management (list, get, create, update, delete)
  • Endpoint, Backend, and Pipeline management
  • Gateway authorization and token management
• Secure Storage - OS-native credential storage (Keychain/Secret Service/Credential Manager)
• Machine Tokens - Autonomous gateway authentication with 30-day expiry
• Cross-Platform - Works on macOS, Linux, and Windows

Installation

Add to your Cargo.toml:

[dependencies]
runbeam-sdk = "0.1.0"

Quick Start

use runbeam_sdk::{
    RunbeamClient,
    validate_jwt_token,
    save_token,
    load_token,
    MachineToken,
    storage::KeyringStorage,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Validate user JWT token
    let user_token = "eyJhbGci...";
    let claims = validate_jwt_token(user_token, 24).await?;
    
    // Create API client
    let client = RunbeamClient::new(claims.api_base_url());
    
    // Authorize gateway and get machine token
    let response = client.authorize_gateway(
        user_token,
        "gateway-123",
        None,
        None
    ).await?;
    
    // Save machine token securely
    let storage = KeyringStorage::new("runbeam");
    let machine_token = MachineToken::new(
        response.machine_token,
        response.expires_at,
        response.gateway.id,
        response.gateway.code,
        response.abilities,
    );
    save_token(&storage, &machine_token).await?;
    
    Ok(())
}

Authorization Flow

1. CLI sends user JWT token to Harmony Management API
2. Harmony validates JWT locally (signature verification via JWKS)
3. Harmony exchanges user JWT for machine token from Runbeam Cloud
4. Runbeam Cloud issues machine-scoped token (30-day expiry)
5. Machine token is stored securely for autonomous API access

Storage Options

KeyringStorage (Recommended)

Uses OS-native secure credential storage:

• macOS: Keychain
• Linux: Secret Service API
• Windows: Credential Manager

use runbeam_sdk::storage::KeyringStorage;

let storage = KeyringStorage::new("runbeam");

FilesystemStorage (Development/Testing)

Stores tokens in the filesystem:

use runbeam_sdk::storage::FilesystemStorage;

let storage = FilesystemStorage::new("/path/to/storage")?;

Development

Build

cargo build
cargo build --release

Test

cargo test           # Run all tests
cargo test --lib     # Run only library tests

Lint

cargo clippy
cargo clippy -- -D warnings

Documentation

cargo doc --open

API Usage

List Gateways

use runbeam_sdk::RunbeamClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = RunbeamClient::new("https://runbeam.example.com");
    let machine_token = "your_machine_token";
    
    // List all gateways
    let gateways = client.list_gateways(machine_token).await?;
    for gateway in gateways.data {
        println!("Gateway: {} ({})", gateway.name, gateway.code);
    }
    
    // Get specific gateway
    let gateway = client.get_gateway(machine_token, "gateway-123").await?;
    println!("Gateway enabled: {}", gateway.data.enabled);
    
    Ok(())
}

Manage Services

use runbeam_sdk::RunbeamClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = RunbeamClient::new("https://runbeam.example.com");
    let machine_token = "your_machine_token";
    
    // List all services
    let services = client.list_services(machine_token).await?;
    for service in services.data {
        println!("Service: {} on gateway {}", service.name, service.gateway_id);
    }
    
    // Get specific service
    let service = client.get_service(machine_token, "service-456").await?;
    println!("Service type: {}", service.data.service_type);
    
    Ok(())
}

Download Full Configuration

use runbeam_sdk::RunbeamClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = RunbeamClient::new("https://runbeam.example.com");
    let machine_token = "your_machine_token";
    
    // Fetch all configuration resources
    let endpoints = client.list_endpoints(machine_token).await?;
    let backends = client.list_backends(machine_token).await?;
    let pipelines = client.list_pipelines(machine_token).await?;
    
    // Use the data to configure harmony-proxy
    println!("Endpoints: {}", endpoints.data.len());
    println!("Backends: {}", backends.data.len());
    println!("Pipelines: {}", pipelines.data.len());
    
    Ok(())
}

Architecture

• runbeam_api/client.rs - HTTP client for Runbeam Cloud API
• runbeam_api/jwt.rs - JWT validation with JWKS caching
• runbeam_api/resources.rs - API resource types (Gateway, Service, etc.)
• runbeam_api/token_storage.rs - Token persistence operations
• runbeam_api/types.rs - Error types and API structures
• storage/mod.rs - Storage backend trait and implementations

License

Part of the Runbeam project.