Struct RunbeamClient 

pub struct RunbeamClient { /* private fields */ }

HTTP client for Runbeam Cloud API

This client handles all communication with the Runbeam Cloud control plane, including gateway authorization and future component loading.

Implementations

impl RunbeamClient

pub fn new(base_url: impl Into<String>) -> Self

Create a new Runbeam Cloud API client

Arguments

• base_url - The Runbeam Cloud API base URL (extracted from JWT iss claim)

Example

use runbeam_sdk::RunbeamClient;

let client = RunbeamClient::new("http://runbeam.lndo.site");

pub async fn authorize_gateway( &self, user_token: impl Into<String>, gateway_code: impl Into<String>, machine_public_key: Option<String>, metadata: Option<Vec<String>>, ) -> Result<AuthorizeResponse, RunbeamError>

Authorize a gateway and obtain a machine-scoped token

This method exchanges a user authentication token (either JWT or Laravel Sanctum) for a machine-scoped token that the gateway can use for autonomous API access. The machine token has a 30-day expiry (configured server-side).

Authentication

This method accepts both JWT tokens and Laravel Sanctum API tokens:

• JWT tokens: Validated locally with RS256 signature verification (legacy behavior)
• Sanctum tokens: Passed directly to server for validation (format: {id}|{token})

The token is passed to the Runbeam Cloud API in both the Authorization header and request body, where final validation and authorization occurs.

Arguments

• user_token - The user’s JWT or Sanctum API token from CLI authentication
• gateway_code - The gateway instance ID
• machine_public_key - Optional public key for secure communication
• metadata - Optional metadata about the gateway (array of strings)

Returns

Returns Ok(AuthorizeResponse) with machine token and gateway details, or Err(RunbeamError) if authorization fails.

Example

use runbeam_sdk::RunbeamClient;

let client = RunbeamClient::new("http://runbeam.lndo.site");

// Using JWT token
let response = client.authorize_gateway(
    "eyJhbGci...",
    "gateway-123",
    None,
    None
).await?;

// Using Sanctum token
let response = client.authorize_gateway(
    "1|abc123def456...",
    "gateway-123",
    None,
    None
).await?;

println!("Machine token: {}", response.machine_token);
println!("Expires at: {}", response.expires_at);

pub fn base_url(&self) -> &str

Get the base URL for this client

pub async fn list_changes( &self, token: impl Into<String>, ) -> Result<PaginatedResponse<Change>, RunbeamError>

List all pending configuration changes (admin/user view)

This endpoint lists ALL changes across the system and is intended for administrative and user interfaces. Gateway instances should use list_changes_for_gateway instead.

Authentication

Accepts JWT tokens, Sanctum API tokens, or machine tokens.

Arguments

• token - Authentication token (JWT, Sanctum, or machine token)

Example

use runbeam_sdk::RunbeamClient;

let client = RunbeamClient::new("http://runbeam.lndo.site");
let changes = client.list_changes("user_jwt_or_sanctum_token").await?;
println!("Found {} changes across all gateways", changes.data.len());

pub async fn list_changes_for_gateway( &self, token: impl Into<String>, gateway_id: impl Into<String>, ) -> Result<PaginatedResponse<Change>, RunbeamError>

List pending configuration changes for a specific gateway

This endpoint returns changes specific to a gateway and is what Harmony Proxy instances should call when polling for configuration updates (typically every 30 seconds).

Authentication

Accepts JWT tokens, Sanctum API tokens, or machine tokens.

Arguments

• token - Authentication token (JWT, Sanctum, or machine token)
• gateway_id - The gateway ID to list changes for

Example

use runbeam_sdk::RunbeamClient;

let client = RunbeamClient::new("http://runbeam.lndo.site");
let changes = client.list_changes_for_gateway(
    "machine_token_abc123",
    "01JBXXXXXXXXXXXXXXXXXXXXXXXXXX"
).await?;
println!("Found {} pending changes for this gateway", changes.data.len());

pub async fn get_change( &self, token: impl Into<String>, change_id: impl Into<String>, ) -> Result<ResourceResponse<Change>, RunbeamError>

Get detailed information about a specific configuration change

Retrieve full details of a change including TOML configuration content, metadata, and status information.

Authentication

Accepts JWT tokens, Sanctum API tokens, or machine tokens.

Arguments

• token - Authentication token (JWT, Sanctum, or machine token)
• change_id - The change ID to retrieve

Example

use runbeam_sdk::RunbeamClient;

let client = RunbeamClient::new("http://runbeam.lndo.site");
let change = client.get_change("machine_token_abc123", "change-123").await?;

if let Some(toml_config) = &change.data.toml_config {
    println!("TOML config:\n{}", toml_config);
}

pub async fn list_gateways( &self, token: impl Into<String>, ) -> Result<PaginatedResponse<Gateway>, RunbeamError>

List all gateways for the authenticated team

Returns a paginated list of gateways.

Authentication

Accepts either JWT tokens or Laravel Sanctum API tokens. The token is passed to the server for validation without local verification.

Arguments

• token - JWT or Sanctum API token for authentication

pub async fn get_gateway( &self, token: impl Into<String>, gateway_id: impl Into<String>, ) -> Result<ResourceResponse<Gateway>, RunbeamError>

Get a specific gateway by ID or code

Authentication

Accepts JWT tokens, Sanctum API tokens, or machine tokens. The token is passed to the server for validation without local verification.

Arguments

• token - JWT, Sanctum API token, or machine token for authentication
• gateway_id - The gateway ID or code

pub async fn list_services( &self, token: impl Into<String>, ) -> Result<PaginatedResponse<Service>, RunbeamError>

List all services for the authenticated team

Returns a paginated list of services across all gateways.

Authentication

Accepts either JWT tokens or Laravel Sanctum API tokens. The token is passed to the server for validation without local verification.

Arguments

• token - JWT or Sanctum API token for authentication

pub async fn get_service( &self, token: impl Into<String>, service_id: impl Into<String>, ) -> Result<ResourceResponse<Service>, RunbeamError>

Get a specific service by ID

Authentication

Accepts JWT tokens, Sanctum API tokens, or machine tokens. The token is passed to the server for validation without local verification.

Arguments

• token - JWT, Sanctum API token, or machine token for authentication
• service_id - The service ID

pub async fn list_endpoints( &self, token: impl Into<String>, ) -> Result<PaginatedResponse<Endpoint>, RunbeamError>

List all endpoints for the authenticated team

Authentication

Accepts either JWT tokens or Laravel Sanctum API tokens. The token is passed to the server for validation without local verification.

Arguments

• token - JWT or Sanctum API token for authentication

pub async fn list_backends( &self, token: impl Into<String>, ) -> Result<PaginatedResponse<Backend>, RunbeamError>

List all backends for the authenticated team

Authentication

Accepts either JWT tokens or Laravel Sanctum API tokens. The token is passed to the server for validation without local verification.

Arguments

• token - JWT or Sanctum API token for authentication

pub async fn list_pipelines( &self, token: impl Into<String>, ) -> Result<PaginatedResponse<Pipeline>, RunbeamError>

List all pipelines for the authenticated team

Authentication

Accepts either JWT tokens or Laravel Sanctum API tokens. The token is passed to the server for validation without local verification.

Arguments

• token - JWT or Sanctum API token for authentication

pub async fn get_transform( &self, token: impl Into<String>, transform_id: impl Into<String>, ) -> Result<ResourceResponse<Transform>, RunbeamError>

Get a specific transform by ID

Retrieve transform details including the JOLT specification stored in the options.instructions field. Used by Harmony Proxy to download transform specifications when applying cloud-sourced pipeline configurations.

Authentication

Accepts JWT tokens, Sanctum API tokens, or machine tokens. The token is passed to the server for validation without local verification.

Arguments

• token - JWT, Sanctum API token, or machine token for authentication
• transform_id - The transform ID (ULID format)

Example

use runbeam_sdk::RunbeamClient;

let client = RunbeamClient::new("http://runbeam.lndo.site");
let transform = client.get_transform("machine_token", "01k81xczrw551e1qj9rgrf0319").await?;

// Extract JOLT specification
if let Some(options) = &transform.data.options {
    if let Some(instructions) = &options.instructions {
        println!("JOLT spec: {}", instructions);
    }
}

pub async fn get_base_url( &self, token: impl Into<String>, ) -> Result<BaseUrlResponse, RunbeamError>

Get the base URL for the changes API

Service discovery endpoint that returns the base URL for the changes API. Harmony Proxy instances can call this to discover the API location dynamically.

Authentication

Accepts JWT tokens, Sanctum API tokens, or machine tokens.

Arguments

• token - Authentication token (JWT, Sanctum, or machine token)

Example

use runbeam_sdk::RunbeamClient;

let client = RunbeamClient::new("http://runbeam.lndo.site");
let response = client.get_base_url("machine_token_abc123").await?;
println!("Changes API base URL: {}", response.base_url);

pub async fn discover_base_url( &self, token: impl Into<String>, ) -> Result<Self, RunbeamError>

Discover and return a new client with the resolved base URL

pub async fn acknowledge_changes( &self, token: impl Into<String>, change_ids: Vec<String>, ) -> Result<AcknowledgeChangesResponse, RunbeamError>

Acknowledge receipt of multiple configuration changes

Bulk acknowledge that changes have been received. Gateways should call this immediately after retrieving changes to update their status from “pending” to “acknowledged”.

Authentication

Accepts JWT tokens, Sanctum API tokens, or machine tokens.

Arguments

• token - Authentication token (JWT, Sanctum, or machine token)
• change_ids - Vector of change IDs to acknowledge

Example

use runbeam_sdk::RunbeamClient;

let client = RunbeamClient::new("http://runbeam.lndo.site");
let change_ids = vec!["change-1".to_string(), "change-2".to_string()];
client.acknowledge_changes("machine_token_abc123", change_ids).await?;

pub async fn mark_change_applied( &self, token: impl Into<String>, change_id: impl Into<String>, ) -> Result<ChangeAppliedResponse, RunbeamError>

Mark a configuration change as successfully applied

Report that a change has been successfully applied to the gateway configuration. This updates the change status to “applied”.

Authentication

Accepts JWT tokens, Sanctum API tokens, or machine tokens.

Arguments

• token - Authentication token (JWT, Sanctum, or machine token)
• change_id - The change ID that was applied

Example

use runbeam_sdk::RunbeamClient;

let client = RunbeamClient::new("http://runbeam.lndo.site");
client.mark_change_applied("machine_token_abc123", "change-123").await?;

pub async fn mark_change_failed( &self, token: impl Into<String>, change_id: impl Into<String>, error: String, details: Option<Vec<String>>, ) -> Result<ChangeFailedResponse, RunbeamError>

Mark a configuration change as failed with error details

Report that a change failed to apply, including error details for troubleshooting. This updates the change status to “failed” and stores the error information.

Authentication

Accepts JWT tokens, Sanctum API tokens, or machine tokens.

Arguments

• token - Authentication token (JWT, Sanctum, or machine token)
• change_id - The change ID that failed
• error - Error message describing what went wrong
• details - Optional additional error details

Example

use runbeam_sdk::RunbeamClient;

let client = RunbeamClient::new("http://runbeam.lndo.site");
client.mark_change_failed(
    "machine_token_abc123",
    "change-123",
    "Failed to parse configuration".to_string(),
    Some(vec!["Invalid JSON syntax at line 42".to_string()])
).await?;

pub async fn store_config( &self, token: impl Into<String>, config_type: impl Into<String>, id: Option<String>, config: impl Into<String>, ) -> Result<StoreConfigResponse, RunbeamError>

Store or update Harmony configuration in Runbeam Cloud

This method sends TOML configuration from Harmony instances back to Runbeam Cloud where it is parsed and stored as database models. This is the inverse of the TOML generation/download API - it enables Harmony to push configuration updates to the cloud.

Authentication

Accepts JWT tokens, Sanctum API tokens, or machine tokens. The token is passed to the server for validation without local verification.

Arguments

• token - Authentication token (JWT, Sanctum, or machine token)
• config_type - Type of configuration (“gateway”, “pipeline”, or “transform”)
• id - Optional resource ID for updates (omit for new resources)
• config - TOML configuration content as a string

Returns

Returns Ok(StoreConfigResponse) with status 200 on success, or Err(RunbeamError) if the operation fails (404 for not found, 422 for validation errors).

Examples

Creating a new gateway configuration

use runbeam_sdk::RunbeamClient;

let client = RunbeamClient::new("http://runbeam.lndo.site");
let toml_config = r#"
[proxy]
id = "gateway-123"
name = "Production Gateway"
"#;

let response = client.store_config(
    "machine_token_abc123",
    "gateway",
    None,  // No ID = create new
    toml_config
).await?;

println!("Configuration stored: success={}, message={}", response.success, response.message);

Updating an existing pipeline configuration

use runbeam_sdk::RunbeamClient;

let client = RunbeamClient::new("http://runbeam.lndo.site");
let toml_config = r#"
[pipeline]
name = "Updated Pipeline"
description = "Modified configuration"
"#;

let response = client.store_config(
    "machine_token_abc123",
    "pipeline",
    Some("01k8pipeline123".to_string()),  // With ID = update existing
    toml_config
).await?;

println!("Configuration updated: model_id={}", response.data.id);

pub async fn request_mesh_token( &self, token: impl Into<String>, mesh_id: impl Into<String>, destination_url: impl Into<String>, ) -> Result<MeshTokenResponse, RunbeamError>

Request a mesh authentication token

Request a JWT for authenticating to another mesh member. The requesting gateway must have an enabled egress in the specified mesh, and the destination URL must match an ingress URL pattern in the mesh.

Authentication

Requires a gateway machine token.

Arguments

• token - Gateway machine token for authentication
• mesh_id - The mesh ID to authenticate against
• destination_url - The destination URL the token is being requested for

Returns

Returns Ok(MeshTokenResponse) with the signed JWT and expiry, or Err(RunbeamError) if the request fails.

Example

use runbeam_sdk::RunbeamClient;

let client = RunbeamClient::new("http://runbeam.lndo.site");
let response = client.request_mesh_token(
    "machine_token_abc123",
    "01HXYZ123456789ABCDEF",
    "https://partner.example.com/fhir/r4/Patient"
).await?;

println!("Token: {}", response.token);
println!("Expires at: {}", response.expires_at);

pub async fn resolve_reference( &self, token: impl Into<String>, reference: impl Into<String>, ) -> Result<ResolveResourceResponse, RunbeamError>

Resolve a resource reference

Resolve a provider-based resource reference to its full definition. This is used to look up resources like mesh ingress/egress by their reference string (e.g., runbeam.acme.ingress.name.patient_api).

Authentication

Requires a gateway machine token.

Arguments

• token - Gateway machine token for authentication
• reference - The resource reference string to resolve

Returns

Returns Ok(ResolveResourceResponse) with the resolved resource, or Err(RunbeamError) if resolution fails.

Example

use runbeam_sdk::RunbeamClient;

let client = RunbeamClient::new("http://runbeam.lndo.site");
let response = client.resolve_reference(
    "machine_token_abc123",
    "runbeam.acme.ingress.name.patient_api"
).await?;

println!("Resolved: {} ({})", response.data.name, response.data.resource_type);
println!("URLs: {:?}", response.data.urls);

Trait Implementations

impl Clone for RunbeamClient

fn clone(&self) -> RunbeamClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RunbeamClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.