Skip to main content

ppoppo_pcs_session/
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;
9pub mod feed;
10// Under `cfg(test)` too, so this crate's own unit tests build the types the
11// way a consumer's do, and the fixture roster test runs under a bare
12// `cargo test` rather than only under `--all-features`.
13#[cfg(any(test, feature = "test-support"))]
14mod fixtures;
15pub mod scopes;
16mod subscribe;
17mod time_defaults;
18pub mod types;
19
20pub use builder::PcsSessionClientBuilder;
21pub use client::PcsSessionClient;
22pub use subscribe::MessageSubscription;
23
24/// The clock port, doored whole: `ppoppo-clock` is vocabulary, and it is the
25/// one sanctioned door to `jiff` — the `Timestamp` this face's response types
26/// carry (`Message.sent_at`, [`credential::AccessToken::expiry_unverified`]) is
27/// `clock::jiff::Timestamp`.
28pub use ppoppo_clock as clock;
29
30/// One session-face RPC, with the [`Sensitivity`] PCS rates it —
31/// [`Operation::sensitivity`]. It is the value PCS's own gates read: rate an
32/// operation stricter for your own confirmation prompt if you like, never
33/// looser, and never treat your prompt as the only gate — PCS judges every
34/// [`Sensitivity::Privileged`] act itself. Vocabulary (`ppoppo-chat`).
35pub use ppoppo_chat::session::Operation;
36
37/// How much an [`Operation`] can change, and the family of a privileged
38/// one. Vocabulary (`ppoppo-chat`).
39pub use ppoppo_chat::{ActFamily, Sensitivity};
40
41/// The most characters an [`InfoItem`](types::InfoItem)'s title holds; a longer one is
42/// refused. Derive a title by cutting to it. Vocabulary (`ppoppo-chat`).
43pub use ppoppo_chat::INFO_ITEM_TITLE_MAX_CHARS;
44
45// The gRPC-client error type is vocabulary (`ppoppo-call`), doored as this
46// SDK's public error: the whole SDK family shares one outcome type and one
47// classifier, so a consumer of two faces reads one `Error`.
48pub use ppoppo_call::Error;
49
50/// The payload of an [`Error::Refused`]: what the refusal means, the status
51/// it came back as, and what the server said.
52pub use ppoppo_call::Refusal;
53
54/// A foreign cause an [`Error`] carries whole — its `detail` is the context,
55/// its `source()` the error underneath.
56pub use ppoppo_call::Cause;
57
58/// What [`PcsSessionClientBuilder::new`] returns for a malformed `api_url`,
59/// and a grant credential's `new` for a malformed issuer — refused at
60/// construction, before anything dials; never an [`Error`], so no retry
61/// policy ever reads a configuration mistake as a transient failure.
62/// [`EndpointError::endpoint`] says which URL was wrong. Vocabulary
63/// (`ppoppo-call`): every gRPC face refuses a dialed URL with this one type.
64pub use ppoppo_call::EndpointError;
65
66/// Which configured URL an [`EndpointError`] refused — the face's address
67/// (`Api`), the token endpoint (`Token`) or, inside a
68/// [`DiscoveryError`], the issuer (`Issuer`).
69pub use ppoppo_call::Endpoint;
70
71/// Why a grant credential could not read PAS's discovery document — the
72/// payload of [`credential::TokenSourceError::Discovery`], which a token
73/// fetch returns. Transient when the fetch failed, terminal when the document
74/// cannot be used; never a verdict on the credential. Vocabulary
75/// (`ppoppo-call`), shared with every face that takes an issuer.
76pub use ppoppo_call::DiscoveryError;
77
78/// What [`PcsSessionClientBuilder::from_env`] returns when its variables are
79/// half-set, not Unicode, or name a malformed URL — a configuration mistake,
80/// refused before anything dials. Vocabulary (`ppoppo-call`): every face reads
81/// its environment set by the same rule.
82pub use ppoppo_call::EnvError;
83
84/// What an [`Error::Refused`] *means* — the return type of
85/// [`Error::rejection`], doored beside `Error` so that reading a refusal never
86/// names a transport status or another crate. Branch on this, or on the
87/// predicates (`is_out_of_sight`, `is_caller_input`, and `Fault`'s
88/// `is_credential` / `is_retryable`):
89///
90/// ```
91/// use ppoppo_pcs_session::types::Fault as _;
92/// use ppoppo_pcs_session::{Error, Refusal, Rejection, WireStatus};
93///
94/// fn remedy(e: &Error) -> &'static str {
95///     match e.rejection() {
96///         Some(Rejection::Credential) => "sign in again",
97///         Some(Rejection::NotFound | Rejection::Forbidden) => "it is gone, or not yours",
98///         Some(Rejection::CallerInput) => "fix the request",
99///         Some(_) => "refused",
100///         None if e.is_retryable() => "try again",
101///         None => "give up",
102///     }
103/// }
104///
105/// let gone = Error::Refused(Refusal {
106///     rejection: Rejection::NotFound,
107///     wire: WireStatus::new("NOT_FOUND"),
108///     message: "no such channel".to_owned(),
109/// });
110/// assert_eq!(remedy(&gone), "it is gone, or not yours");
111/// assert!(gone.is_out_of_sight() && !gone.is_credential());
112/// ```
113///
114/// A consumer pins its own reading of a failure by building the [`Error`]
115/// values it branches on — every variant is constructible from this crate's
116/// names alone — and never by feeding the family's classifier a transport
117/// status: which wire status lands on which [`Rejection`] is the family's
118/// table, pinned by its own tests (`tests/status_oracle_door.rs`).
119pub use ppoppo_call::Rejection;
120
121/// The status name an [`Error`] carries when the call reached the server
122/// ([`Error::wire`]) — opaque, for logs and messages; branch on
123/// [`Rejection`] or the predicates instead.
124pub use ppoppo_call::WireStatus;