Struct RunbeamClient

Source

pub struct RunbeamClient { /* private fields */ }

Expand description

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§

Source §

impl RunbeamClient

Source

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");

Source

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);

Source

pub fn base_url(&self) -> &str

Get the base URL for this client

Source

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

Source

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

Source

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

Source

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

Source

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

Source

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

Source

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

Source

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);

Source

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

List pending configuration changes for the authenticated gateway

Retrieve queued configuration changes that are ready to be applied. Gateways typically poll this endpoint every 30 seconds to check for updates.

§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("machine_token_abc123").await?;
println!("Found {} pending changes", changes.data.len());

Source

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

Get details of a specific configuration change

Retrieve detailed information about a specific change by its ID.

§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?;
println!("Change status: {}", change.data.status);

Source

pub async fn acknowledge_changes( &self, token: impl Into<String>, change_ids: Vec<String>, ) -> Result<Value, 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?;

Source

pub async fn mark_change_applied( &self, token: impl Into<String>, change_id: impl Into<String>, ) -> Result<Value, 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?;

Source

pub async fn mark_change_failed( &self, token: impl Into<String>, change_id: impl Into<String>, error: String, details: Option<Vec<String>>, ) -> Result<Value, 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?;