talos_api_rs/
lib.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! # talos-api-rs
4//!
5//! A typed, async, idiomatic Rust client for the [Talos Linux](https://www.talos.dev/) gRPC API.
6//!
7//! ## Features
8//!
9//! - **40+ APIs** — Machine, etcd, system, files, diagnostics
10//! - **Async-first** — Built on `tokio` and `tonic`
11//! - **Strongly typed** — No stringly-typed API calls
12//! - **Production-ready** — Retries, circuit breakers, connection pooling
13//! - **Observable** — Prometheus metrics, OpenTelemetry tracing
14//! - **mTLS support** — ED25519 certificates (Talos default)
15//!
16//! ## Quick Start
17//!
18//! ```rust,ignore
19//! use talos_api_rs::{TalosClient, TalosClientConfig};
20//!
21//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
22//! // Connect with mTLS
23//! let config = TalosClientConfig::builder("https://10.0.0.1:50000")
24//!     .ca_cert("/path/to/ca.crt")
25//!     .client_cert("/path/to/client.crt")
26//!     .client_key("/path/to/client.key")
27//!     .build();
28//!
29//! let client = TalosClient::new(config).await?;
30//!
31//! // Get kubeconfig from cluster
32//! let kubeconfig = client.kubeconfig().await?;
33//! println!("Got kubeconfig for cluster");
34//! # Ok(())
35//! # }
36//! ```
37//!
38//! ## Module Overview
39//!
40//! - [`client`] — Core client and connection management
41//! - [`resources`] — Typed API request/response wrappers
42//! - [`runtime`] — Resilience (retry, circuit breaker) and observability
43//! - [`error`] — Error types
44//! - [`api`] — Generated protobuf types (low-level)
45//! - [`testkit`] — Testing utilities
46//!
47//! ## Production Features
48//!
49//! ### Retry Policies
50//!
51//! ```rust
52//! use talos_api_rs::runtime::{RetryConfig, ExponentialBackoff};
53//! use std::time::Duration;
54//!
55//! let retry = RetryConfig::builder()
56//!     .max_retries(3)
57//!     .backoff(ExponentialBackoff::new(Duration::from_millis(100)))
58//!     .build();
59//! ```
60//!
61//! ### Circuit Breaker
62//!
63//! ```rust
64//! use talos_api_rs::runtime::{CircuitBreaker, CircuitBreakerConfig};
65//! use std::time::Duration;
66//!
67//! let cb = CircuitBreaker::new(
68//!     CircuitBreakerConfig::new()
69//!         .with_failure_threshold(5)
70//!         .with_reset_timeout(Duration::from_secs(30))
71//! );
72//! ```
73//!
74//! ### Prometheus Metrics
75//!
76//! ```rust
77//! use talos_api_rs::runtime::{MetricsCollector, MetricsConfig};
78//!
79//! let metrics = MetricsCollector::new(
80//!     MetricsConfig::builder()
81//!         .namespace("talos")
82//!         .build()
83//! );
84//!
85//! // Export Prometheus format
86//! let output = metrics.to_prometheus_text();
87//! ```
88//!
89//! ## Disclaimer
90//!
91//! This project is **NOT** affiliated with Sidero Labs or Talos Linux.
92//! Provided AS-IS, without warranty of any kind.
93
94#![cfg_attr(docsrs, feature(doc_cfg))]
95
96pub mod api;
97pub mod client;
98pub mod error;
99pub mod resources;
100pub mod runtime;
101pub mod testkit;
102
103pub use client::{
104    ConnectionPool, ConnectionPoolConfig, EndpointHealth, HealthStatus, LoadBalancer, TalosClient,
105    TalosClientConfig, TalosClientConfigBuilder,
106};
107pub use error::TalosError;
108pub use resources::{
109    ApplyConfigurationRequest, ApplyConfigurationResponse, ApplyConfigurationResult, ApplyMode,
110    BootstrapRequest, BootstrapResponse, BootstrapResult, ConnectionRecord, ConnectionState,
111    ContainerDriver, CopyRequest, CopyResponse, CpuInfo, CpuInfoResponse, CpuInfoResult, DiskStat,
112    DiskStatsResponse, DiskStatsResult, DiskUsageInfo, DiskUsageRequest, DiskUsageResponse,
113    DmesgRequest, DmesgResponse, EtcdAlarmDisarmResponse, EtcdAlarmListResponse, EtcdAlarmType,
114    EtcdDefragmentResponse, EtcdForfeitLeadershipRequest, EtcdForfeitLeadershipResponse,
115    EtcdLeaveClusterRequest, EtcdLeaveClusterResponse, EtcdMember, EtcdMemberAlarm,
116    EtcdMemberListRequest, EtcdMemberListResponse, EtcdMemberStatus, EtcdRemoveMemberByIdRequest,
117    EtcdRemoveMemberByIdResponse, EtcdStatusResponse, FileInfo, FileType,
118    GenerateClientConfigurationRequest, GenerateClientConfigurationResponse,
119    GenerateClientConfigurationResult, KubeconfigResponse, L4ProtoFilter, ListRequest,
120    ListResponse, LoadAvgResponse, LoadAvgResult, LogsRequest, LogsResponse, MemoryResponse,
121    MemoryResult, MountStat, MountsResponse, MountsResult, NetDevStat, NetstatFilter,
122    NetstatRequest, NetstatResponse, NetstatResult, NetworkDeviceStatsResponse,
123    NetworkDeviceStatsResult, PacketCaptureRequest, PacketCaptureResponse, ProcessInfo,
124    ProcessesResponse, ProcessesResult, ReadRequest, ReadResponse, ResetPartitionSpec,
125    ResetRequest, ResetResponse, ResetResult, RollbackResponse, RollbackResult,
126    ServiceRestartRequest, ServiceRestartResponse, ServiceStartRequest, ServiceStartResponse,
127    ServiceStopRequest, ServiceStopResponse, UpgradeRebootMode, UpgradeRequest, UpgradeResponse,
128    UpgradeResult, WipeMode,
129};
130pub use runtime::{
131    BackoffStrategy, CircuitBreaker, CircuitBreakerConfig, CircuitState, CustomRetryPolicy,
132    DefaultRetryPolicy, ExponentialBackoff, FixedBackoff, InterceptorMetrics, LinearBackoff,
133    LogLevel, LoggingConfig, LoggingInterceptor, NoBackoff, NoRetryPolicy, RequestLogger,
134    RequestSpan, RetryConfig, RetryConfigBuilder, RetryPolicy,
135};
talos_api_rs/lib.rs

talos_api_rs/
lib.rs
