Expand description
§ppoppo-pcs-external
Ppoppo Chat System (PCS) External face client for Rust.
The SDK for an app that reaches Ppoppo accounts: alerts from a registered
template, and channels — a direct channel with one account, or a channel the
app creates and owns. It runs as the app, on its own client_credentials pair, and turns
“tell this account, then hear what comes back” into a one-dependency program.
- Issuer-only credential — the token endpoint is read from PAS’s discovery document; the token is minted, cached and re-minted inside the client
- Phantom-typed scope sets — method availability enforced at compile time, and independently by the server (double lock)
- Deep reads — listings walk the server’s pages; the inbound and delivery streams reconnect, back off and resume from their cursor
§Usage
[dependencies]
ppoppo-pcs-external = "0.12"use ppoppo_pcs_external::credential::{AppCredential, ClientSecret};
use ppoppo_pcs_external::scopes::Unrestricted;
use ppoppo_pcs_external::types::{ChannelEventItem, NewMessage, Ppnum};
use ppoppo_pcs_external::PcsExternalClientBuilder;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = PcsExternalClientBuilder::new(
"https://chat.ppoppo.com/ext",
AppCredential::<Unrestricted>::new(
"https://accounts.ppoppo.com",
std::env::var("PCS_EXTERNAL_CLIENT_ID")?,
ClientSecret::new(std::env::var("PCS_EXTERNAL_CLIENT_SECRET")?),
)?,
)?
.build()?; // the tier is the credential's
// Open (or reuse) the direct channel — this is what makes the app a party to it.
let reporter = Ppnum::parse("10012345678")?;
let dm = client.get_or_create_direct_channel(&reporter).await?;
client
.send_direct(&dm, &NewMessage::text("We received your report."))
.await?;
// Hear what comes back.
let mut events = client.subscribe_channel_events(std::slice::from_ref(&dm.id), None);
while let Some(item) = events.next().await? {
if let ChannelEventItem::Event(event) = item
&& !event.from_app
{
println!("{}: {}", reporter.display(), event.message.content);
}
}
Ok(())
}That loop is the whole program — discovery, the token, reconnects, backoff and
resume live inside the client. PcsExternalClientBuilder::from_env() reads the
same configuration as one set; examples/quickstart.rs runs it.
Every constructor parses and dials nothing: a malformed URL or issuer is an
EndpointError at construction, never a retryable failure on the first call.
§Endpoints
| Variable | Production | Development |
|---|---|---|
PCS_EXTERNAL_API_URL | https://chat.ppoppo.com/ext | http://localhost:3203 |
PAS_ISSUER | https://accounts.ppoppo.com | http://localhost:3100 |
PCS_EXTERNAL_CLIENT_ID / PCS_EXTERNAL_CLIENT_SECRET | the app’s registered pair |
Pass the face’s address exactly as PAS and PCS spell it: it is the token’s
RFC 8707 resource, matched byte for byte (a trailing slash names a different
one).
§Scope sets
Construct the client with the scope set your app was registered with. No
scope is requested; every grant’s scope echo is checked to cover the set, or
the call is never dialled.
| Scope set | create_send_request / send_message / send_direct | get_send_request_status / subscribe_send_request_events / get_channel / list_channels / list_members / get_messages / subscribe_channel_events | create_channel / get_or_create_direct_channel / add_member | transfer_publisher | cancel_trigger |
|---|---|---|---|---|---|
ReadOnly | — | ✓ | — | — | — |
SendOnly | ✓ | — | — | — | — |
ReadAndSend | ✓ | ✓ | — | — | — |
Unrestricted | ✓ | ✓ | ✓ | ✓ | ✓ |
The columns are the capability traits ChatSendCapable (chat.send),
ChatReadCapable (chat.read), ChatManageCapable (chat.manage), and the
two privileged acts: transfer_publisher needs ChatManageCapable +
ChatPrivilegedChannelCapable (chat.privileged.channel), cancel_trigger
needs ChatSendCapable + ChatPrivilegedTriggerCapable
(chat.privileged.trigger). PCS’s server act gate demands the privileged-act
atom of an app, which holds it only when its registration named it — PAS never
grants one by default. Calling a method your scope set does not carry is a
compile error, not a runtime PermissionDenied. chat.manage and the
privileged-act atoms are Unrestricted’s alone: the tiers published before
them were not widened, so an app that declared one of them still holds exactly
what it was registered with.
§Versioning
This crate keeps its own semver: its version moves only when its own public
surface (or a dependency that reaches it) changed. Read CHANGELOG.md for what
actually moved.
§License
MIT OR Apache-2.0
Re-exports§
pub use ppoppo_clock as clock;
Modules§
- credential
- What a client presents — the credential a
PcsExternalClientBuildertakes, and the vocabulary its sources speak. - scopes
- Sealed scope-set type family for
crate::PcsExternalClient<S>. - types
- Domain types for the PCS External API client hot path.
Structs§
- Cause
- A foreign cause an
Errorcarries whole — itsdetailis the context, itssource()the error underneath. A cause the family did not write — a transport’s, a parser’s, a store’s — carried whole, never formatted into a string. - Channel
Event Subscription - A resumable subscription to the messages accepted into this app’s channels,
from
crate::PcsExternalClient::subscribe_channel_events. - Endpoint
Error - What
PcsExternalClientBuilder::newreturns for a malformedapi_url, andAppCredential::newfor a malformed issuer — refused at construction, before anything dials; never anError, so no retry policy ever reads a configuration mistake as a transient failure.EndpointError::endpointsays which URL was wrong. Vocabulary (ppoppo-call): every gRPC face refuses a dialed URL with this one type. A configured URL, refused where it was handed over — before anything was dialled, fetched or retried. - Pacing
- A shared pace: at most
nrequests a minute, one interval apart, across every client built with a clone of it. - Pacing
Error - A pace
Pacing::per_minuterefused. - PcsExternal
Client - Phantom-typed gRPC client for the PCS External Developer Platform.
- PcsExternal
Client Builder - Builder for
PcsExternalClient<S>: the face’s address and the credential the client presents there. - Refusal
- The payload of an
Error::Refused: what the refusal means, the status it came back as, and what the server said. An application-layer refusal: what it means, the status it came back as, and what the server said — the payload ofError::Refused, never a return type of its own. - Send
Request Event Subscription - A resumable subscription to this app’s delivery events, from
crate::PcsExternalClient::subscribe_send_request_events. - Wire
Status - The status name an
Errorcarries when the call reached the server (Error::wire) — opaque, for logs and messages; branch onRejectionor the predicates instead. The status a server answered with, by its canonical name — for a log line or an error message, never for a branch.
Enums§
- Endpoint
- Which configured URL an
EndpointErrorrefused — the face’s address (Api) or PAS’s issuer (Issuer). Which configured URL a refusal is about — the half of anEndpointErrorthat says which one was wrong. - EnvError
- What
PcsExternalClientBuilder::from_envreturns when its variables are half-set, not Unicode, or name a malformed URL — a configuration mistake, refused before anything dials. Vocabulary (ppoppo-call): every face reads its environment set by the same rule. A face’s environment variable set, refused. - Error
- Every error a ppoppo client returns from a credentialed call.
- Rejection
- What an
Error::Refusedmeans — the return type ofError::rejection, doored besideErrorso that reading a refusal never names a transport status or another crate. Branch on this, or on the predicates (is_out_of_sight,is_caller_input, andFault’sis_credential/is_retryable):