runbeam_sdk/
lib.rs

1//! Runbeam SDK
2//!
3//! A Rust library for integrating with the Runbeam Cloud API.
4//!
5//! This SDK provides:
6//! - JWT token validation with RS256 and JWKS caching
7//! - Laravel Sanctum API token support
8//! - Runbeam Cloud API client for gateway authorization
9//! - Secure token storage via encrypted filesystem storage (age encryption)
10//! - Type definitions for API requests/responses and error handling
11//!
12//! # Authentication Methods
13//!
14//! The SDK supports two authentication methods:
15//!
16//! ## JWT Tokens (Legacy)
17//!
18//! JWT tokens with RS256 signature validation. The SDK performs local validation
19//! using public keys fetched from JWKS endpoints. Use this method when you need
20//! local token validation and claim extraction.
21//!
22//! ## Laravel Sanctum API Tokens
23//!
24//! Laravel Sanctum API tokens (format: `{id}|{token}`) are passed directly to the
25//! server for validation. Use this method for simpler authentication flows where
26//! local token validation is not required.
27//!
28//! # Example (JWT Authentication)
29//!
30//! ```no_run
31//! use runbeam_sdk::{
32//!     RunbeamClient,
33//!     validate_jwt_token,
34//!     save_machine_token,
35//!     MachineToken,
36//! };
37//!
38//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
39//! // Validate a user JWT token
40//! let claims = validate_jwt_token("eyJhbGci...", 24).await?;
41//!
42//! // Create API client from JWT issuer
43//! let client = RunbeamClient::new(claims.api_base_url());
44//!
45//! // Authorize a gateway and get machine token
46//! let response = client.authorize_gateway(
47//!     "eyJhbGci...",
48//!     "gateway-123",
49//!     None,
50//!     None
51//! ).await?;
52//!
53//! // Save machine token securely (encrypted filesystem storage)
54//! let machine_token = MachineToken::new(
55//!     response.machine_token,
56//!     response.expires_at,
57//!     response.gateway.id,
58//!     response.gateway.code,
59//!     response.abilities,
60//! );
61//! save_machine_token("harmony", &machine_token).await?;
62//! # Ok(())
63//! # }
64//! ```
65//!
66//! # Example (Sanctum Authentication)
67//!
68//! ```no_run
69//! use runbeam_sdk::{
70//!     RunbeamClient,
71//!     save_machine_token,
72//!     MachineToken,
73//! };
74//!
75//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
76//! // Create API client with base URL
77//! let client = RunbeamClient::new("https://api.runbeam.io");
78//!
79//! // Authorize a gateway with Sanctum token (no validation needed)
80//! let response = client.authorize_gateway(
81//!     "1|abc123def456...",  // Sanctum API token
82//!     "gateway-123",
83//!     None,
84//!     None
85//! ).await?;
86//!
87//! // Save machine token securely (encrypted filesystem storage)
88//! let machine_token = MachineToken::new(
89//!     response.machine_token,
90//!     response.expires_at,
91//!     response.gateway.id,
92//!     response.gateway.code,
93//!     response.abilities,
94//! );
95//! save_machine_token("harmony", &machine_token).await?;
96//! # Ok(())
97//! # }
98//! ```
99
100pub mod runbeam_api;
101pub mod storage;
102pub mod validation;
103
104// Re-export commonly used types and functions
105pub use validation::{
106    validate_config_toml, validate_pipeline_toml, validate_toml, ValidationError,
107};
108
109pub use runbeam_api::{
110    client::RunbeamClient,
111    jwt::{extract_bearer_token, validate_jwt_token, JwtClaims},
112    resources::{
113        AcknowledgeChangesRequest, AcknowledgeChangesResponse, Authentication, Backend,
114        BaseUrlResponse, Change, ChangeAppliedResponse, ChangeFailedRequest, ChangeFailedResponse,
115        ChangeStatusResponse, Endpoint, Gateway, GatewayConfiguration, Middleware, Network,
116        PaginatedResponse, PaginationLinks, PaginationMeta, Pipeline, Policy, PolicyRules, ResourceResponse,
117        Service, Transform,
118    },
119    token_storage::{
120        // Backwards-compatible machine token functions
121        clear_machine_token,
122        // Generic token storage functions
123        clear_token,
124        load_machine_token,
125        load_token,
126        save_machine_token,
127        save_token,
128        save_token_with_key,
129        MachineToken,
130    },
131    types::{
132        ApiError, AuthorizeResponse, GatewayInfo, RunbeamError, StoreConfigRequest,
133        StoreConfigResponse, TeamInfo, UserInfo, UserToken,
134    },
135};
runbeam_sdk/lib.rs

runbeam_sdk/
lib.rs
