Skip to main content

ppoppo_pas_plims/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2#![doc = include_str!("../README.md")]
3#![deny(rust_2018_idioms)]
4#![warn(missing_docs, missing_debug_implementations)]
5
6mod builder;
7mod client;
8pub mod credential;
9#[cfg(feature = "test-support")]
10mod fixtures;
11mod proto;
12pub mod scopes;
13pub mod types;
14
15pub use builder::PasPlimsClientBuilder;
16
17pub use client::PasPlimsClient;
18/// Why a credential could not read PAS's discovery document — the payload of
19/// [`credential::TokenSourceError::Discovery`], which a token fetch returns.
20/// Transient when the fetch failed, terminal when the document cannot be
21/// used; never a verdict on the credential. Vocabulary (`ppoppo-call`), shared
22/// with every face that takes an issuer.
23pub use ppoppo_call::DiscoveryError;
24
25/// The clock port, doored whole: `ppoppo-clock` is vocabulary, and it is the
26/// one sanctioned door to `jiff` — the `Timestamp` this face's response types
27/// carry is `clock::jiff::Timestamp`.
28pub use ppoppo_clock as clock;
29
30// The gRPC-client error type is vocabulary (`ppoppo-call`), doored as this
31// SDK's public error: the whole SDK family shares one outcome type and one
32// classifier, so a consumer of two faces reads one `Error`.
33pub use ppoppo_call::Error;
34
35/// The payload of an [`Error::Refused`]: what the refusal means, the status
36/// it came back as, and what the server said.
37pub use ppoppo_call::Refusal;
38
39/// A foreign cause an [`Error`] carries whole — its `detail` is the context,
40/// its `source()` the error underneath.
41pub use ppoppo_call::Cause;
42
43/// What [`PasPlimsClientBuilder::new`] returns for a malformed `api_url`,
44/// and [`AppCredential::new`](credential::AppCredential::new) for a malformed
45/// issuer — refused at construction, before anything dials; never an
46/// [`Error`], so no retry policy ever reads a configuration mistake as a
47/// transient failure. [`EndpointError::endpoint`] says which URL was wrong.
48/// Vocabulary (`ppoppo-call`): every gRPC face refuses a dialed URL with this
49/// one type.
50pub use ppoppo_call::EndpointError;
51
52/// Which configured URL an [`EndpointError`] refused — the face's address
53/// (`Api`) or PAS's issuer (`Issuer`).
54pub use ppoppo_call::Endpoint;
55
56/// What [`PasPlimsClientBuilder::from_env`] returns when its variables are
57/// half-set, not Unicode, or name a malformed URL — a configuration mistake,
58/// refused before anything dials. Vocabulary (`ppoppo-call`): every face reads
59/// its environment set by the same rule.
60pub use ppoppo_call::EnvError;
61
62/// What an [`Error::Refused`] *means* — the return type of
63/// [`Error::rejection`], doored beside `Error` so that reading a refusal never
64/// names a transport status or another crate. Branch on this, or on the
65/// predicates (`is_out_of_sight`, `is_caller_input`, and `Fault`'s
66/// `is_credential` / `is_retryable`):
67///
68/// ```
69/// use ppoppo_pas_plims::types::Fault as _;
70/// use ppoppo_pas_plims::{Error, Refusal, Rejection, WireStatus};
71///
72/// fn remedy(e: &Error) -> &'static str {
73///     match e.rejection() {
74///         Some(Rejection::Credential) => "sign in again",
75///         Some(Rejection::NotFound | Rejection::Forbidden) => "it is gone, or not yours",
76///         Some(Rejection::CallerInput) => "fix the request",
77///         Some(_) => "refused",
78///         None if e.is_retryable() => "try again",
79///         None => "give up",
80///     }
81/// }
82///
83/// let gone = Error::Refused(Refusal {
84///     rejection: Rejection::NotFound,
85///     wire: WireStatus::new("NOT_FOUND"),
86///     message: "no such channel".to_owned(),
87/// });
88/// assert_eq!(remedy(&gone), "it is gone, or not yours");
89/// assert!(gone.is_out_of_sight() && !gone.is_credential());
90/// ```
91pub use ppoppo_call::Rejection;
92
93/// The status name an [`Error`] carries when the call reached the server
94/// ([`Error::wire`]) — opaque, for logs and messages; branch on
95/// [`Rejection`] or the predicates instead.
96pub use ppoppo_call::WireStatus;