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//!     JwtValidationOptions,
35//!     save_machine_token,
36//!     MachineToken,
37//! };
38//!
39//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
40//! // Validate a user JWT token with trusted issuers
41//! let options = JwtValidationOptions::new()
42//!     .with_trusted_issuers(vec!["https://api.runbeam.io".to_string()]);
43//! let claims = validate_jwt_token("eyJhbGci...", &options).await?;
44//!
45//! // Create API client from JWT issuer
46//! let client = RunbeamClient::new(claims.api_base_url());
47//!
48//! // Authorize a gateway and get machine token
49//! let response = client.authorize_gateway(
50//!     "eyJhbGci...",
51//!     "gateway-123",
52//!     None,
53//!     None
54//! ).await?;
55//!
56//! // Save machine token securely (encrypted filesystem storage)
57//! let machine_token = MachineToken::new(
58//!     response.machine_token,
59//!     response.expires_at,
60//!     response.gateway.id,
61//!     response.gateway.code,
62//!     response.abilities,
63//! );
64//! save_machine_token("harmony", &machine_token).await?;
65//! # Ok(())
66//! # }
67//! ```
68//!
69//! # Example (Sanctum Authentication)
70//!
71//! ```no_run
72//! use runbeam_sdk::{
73//!     RunbeamClient,
74//!     save_machine_token,
75//!     MachineToken,
76//! };
77//!
78//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
79//! // Create API client with base URL
80//! let client = RunbeamClient::new("https://api.runbeam.io");
81//!
82//! // Authorize a gateway with Sanctum token (no validation needed)
83//! let response = client.authorize_gateway(
84//!     "1|abc123def456...",  // Sanctum API token
85//!     "gateway-123",
86//!     None,
87//!     None
88//! ).await?;
89//!
90//! // Save machine token securely (encrypted filesystem storage)
91//! let machine_token = MachineToken::new(
92//!     response.machine_token,
93//!     response.expires_at,
94//!     response.gateway.id,
95//!     response.gateway.code,
96//!     response.abilities,
97//! );
98//! save_machine_token("harmony", &machine_token).await?;
99//! # Ok(())
100//! # }
101//! ```
102
103pub mod runbeam_api;
104pub mod storage;
105pub mod validation;
106
107// Re-export commonly used types and functions
108pub use validation::{
109    validate_config_toml, validate_pipeline_toml, validate_toml, ValidationError,
110};
111
112pub use runbeam_api::{
113    client::RunbeamClient,
114    jwt::{extract_bearer_token, validate_jwt_token, JwtClaims, JwtValidationOptions},
115    resources::{
116        AcknowledgeChangesRequest, AcknowledgeChangesResponse, Authentication, Backend,
117        BaseUrlResponse, Change, ChangeAppliedResponse, ChangeFailedRequest, ChangeFailedResponse,
118        ChangeStatusResponse, Endpoint, Gateway, GatewayConfiguration, Middleware, Network,
119        PaginatedResponse, PaginationLinks, PaginationMeta, Pipeline, Policy, PolicyRules,
120        ResourceResponse, Service, Transform,
121    },
122    token_storage::{
123        // Backwards-compatible machine token functions
124        clear_machine_token,
125        // Generic token storage functions
126        clear_token,
127        load_machine_token,
128        load_token,
129        save_machine_token,
130        save_token,
131        save_token_with_key,
132        MachineToken,
133    },
134    types::{
135        ApiError, AuthorizeResponse, GatewayInfo, RunbeamError, StoreConfigRequest,
136        StoreConfigResponse, TeamInfo, UserInfo, UserToken,
137    },
138};
runbeam_sdk/lib.rs

runbeam_sdk/
lib.rs
