bestool_canopy/lib.rs
1//! bestool's canopy client: the published [`bes_canopy_api`] wire layer plus
2//! bestool's own HTTP transport and registration/backup helpers.
3//!
4//! The typed [`CanopyClient`], the [`CanopyTransport`] trait, the wire types in
5//! [`schema`], and the error types all come from [`bes_canopy_api`] and are
6//! re-exported here. This crate supplies the parts specific to how bestool
7//! reaches canopy:
8//!
9//! - [`ReqwestTransport`], the default [`CanopyTransport`], which picks canopy's
10//! tailscale or mTLS auth path and routes calls accordingly;
11//! - [`connect`] and [`connect_to`], which probe for an auth path and build a
12//! [`CanopyClient`] over one;
13//! - [`registration`], and the backup helpers [`TargetOutcome`] and
14//! [`ContainerCreds`].
15//!
16//! The transport-shaped operations — [`is_tailscale`](ReqwestTransport::is_tailscale),
17//! [`refresh`](ReqwestTransport::refresh), [`renew`](ReqwestTransport::renew) —
18//! live on [`ReqwestTransport`]; reach them through
19//! [`CanopyClient::transport`](bes_canopy_api::CanopyClient::transport).
20//!
21//! # Wire types
22//!
23//! The types in [`schema`] are generated from canopy's OpenAPI document, which
24//! canopy builds and publishes as `bes-canopy-api`. Timestamp fields are
25//! [`jiff::Timestamp`], credential secrets are wrapped in [`Redacted`] so they
26//! stay out of `Debug` output, and each generated struct carries a builder and
27//! is `#[non_exhaustive]`. [`CanopyClient`] has one method per endpoint taking
28//! and returning these types; any non-2xx surfaces as [`CanopyHttpError`].
29
30mod backup;
31mod connect;
32pub mod registration;
33mod reqwest_transport;
34#[cfg(test)]
35mod test_support;
36
37pub use bes_canopy_api::{
38 CanopyHttpError, CanopyRequest, CanopyResponse, CanopyTransport, Error, Redacted, async_trait,
39 bytes, http, schema,
40};
41
42pub use backup::{ContainerCreds, TargetOutcome};
43pub use connect::{connect, connect_to};
44pub use reqwest;
45pub use reqwest_transport::{
46 CERT_RENEW_AFTER, ClientBuilderFactory, DEFAULT_CANOPY_URL, ReqwestTransport, TAILSCALE_URL,
47 device_identity, tailscale_client,
48};
49
50/// The typed canopy client, defaulting to bestool's [`ReqwestTransport`].
51///
52/// [`bes_canopy_api::CanopyClient`] takes its transport as a required type
53/// parameter; this alias restores the default so the common case — a client
54/// built by [`connect`] or [`connect_to`] — never has to name it.
55pub type CanopyClient<T = ReqwestTransport> = bes_canopy_api::CanopyClient<T>;