spire_api/
lib.rs

1#![deny(missing_docs)]
2#![deny(unsafe_code)]
3#![warn(missing_debug_implementations)]
4#![warn(clippy::all)]
5#![warn(clippy::pedantic)]
6#![allow(clippy::module_name_repetitions)]
7#![allow(clippy::must_use_candidate)]
8
9//! Rust client bindings for SPIRE gRPC APIs.
10//!
11//! This crate provides ergonomic wrappers around SPIRE's gRPC APIs (generated from protobuf)
12//! with strongly-typed request helpers.
13//!
14//! ## Endpoints and transport
15//!
16//! SPIRE exposes multiple gRPC APIs (e.g. the Agent API) over a local endpoint. In most
17//! deployments this is a Unix domain socket.
18//!
19//! The high-level clients in this crate typically accept a pre-built `tonic::transport::Channel`.
20//! This keeps transport configuration explicit and composable (timeouts, TLS, interceptors, etc).
21//!
22//! ## Quick start
23//!
24//! ```no_run
25//! use spire_api::{DelegatedIdentityClient, DelegateAttestationRequest};
26//! use spire_api::selectors;
27//!
28//! # async fn demo() -> Result<(), Box<dyn std::error::Error>> {
29//! // Build a tonic Channel (example shown for a standard TCP URI).
30//! // For Unix domain sockets, build the Channel using a custom connector.
31//! let channel = tonic::transport::Channel::from_static("http://127.0.0.1:8081")
32//!     .connect()
33//!     .await?;
34//!
35//! let client = DelegatedIdentityClient::new(channel)?;
36//!
37//! let svid = client
38//!     .fetch_x509_svid(DelegateAttestationRequest::Selectors(vec![
39//!         selectors::Selector::Unix(selectors::Unix::Uid(1000)),
40//!     ]))
41//!     .await?;
42//!
43//! println!("SPIFFE ID: {}", svid.spiffe_id());
44//! # Ok(())
45//! # }
46//! ```
47//!
48//! ## Generated protobuf types
49//!
50//! Protobuf-generated types are available under [`pb`]. Most users should not need to use these
51//! directly, but they are exposed for advanced use-cases.
52
53/// Protobuf-generated types for SPIRE APIs.
54///
55/// These bindings are generated from SPIRE's protobuf definitions and are considered a
56/// lower-level interface than the high-level clients in this crate.
57pub mod pb {
58    #[allow(
59        missing_docs,
60        clippy::all,
61        clippy::pedantic,
62        clippy::module_name_repetitions,
63        dead_code,
64        non_camel_case_types,
65        non_snake_case,
66        non_upper_case_globals,
67        unused_imports,
68        unused_qualifications
69    )]
70
71    pub mod spire {
72        pub mod api {
73            pub mod agent {
74                pub mod delegatedidentity {
75                    pub mod v1 {
76                        include!("pb/spire.api.agent.delegatedidentity.v1.rs");
77                    }
78                }
79            }
80
81            pub mod types {
82                include!("pb/spire.api.types.rs");
83            }
84        }
85    }
86}
87
88/// SPIRE Agent API clients.
89pub mod agent;
90
91/// Selector types used by SPIRE APIs.
92pub mod selectors;
93
94/// Common re-exports for convenience.
95///
96/// This is intentionally small; prefer importing types from their modules for clarity.
97pub mod prelude {
98    /// Common imports for SPIRE client usage.
99    pub use crate::agent::delegated_identity::{
100        DelegateAttestationRequest, DelegatedIdentityClient,
101    };
102    pub use crate::selectors;
103}
104
105// Re-exports (top-level convenience)
106pub use agent::delegated_identity::{DelegateAttestationRequest, DelegatedIdentityClient};
spire_api/lib.rs

spire_api/
lib.rs
