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

runbeam_sdk/
lib.rs
