Skip to main content

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