Skip to main content

Crate ppoppo_pcs_external

Crate ppoppo_pcs_external 

Source
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

VariableProductionDevelopment
PCS_EXTERNAL_API_URLhttps://chat.ppoppo.com/exthttp://localhost:3203
PAS_ISSUERhttps://accounts.ppoppo.comhttp://localhost:3100
PCS_EXTERNAL_CLIENT_ID / PCS_EXTERNAL_CLIENT_SECRETthe 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 setcreate_send_request / send_message / send_directget_send_request_status / subscribe_send_request_events / get_channel / list_channels / list_members / get_messages / subscribe_channel_eventscreate_channel / get_or_create_direct_channel / add_membertransfer_publishercancel_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 PcsExternalClientBuilder takes, 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 Error carries whole — its detail is the context, its source() 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.
ChannelEventSubscription
A resumable subscription to the messages accepted into this app’s channels, from crate::PcsExternalClient::subscribe_channel_events.
EndpointError
What PcsExternalClientBuilder::new returns for a malformed api_url, and AppCredential::new for a malformed issuer — refused at construction, before anything dials; never an Error, so no retry policy ever reads a configuration mistake as a transient failure. EndpointError::endpoint says 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 n requests a minute, one interval apart, across every client built with a clone of it.
PacingError
A pace Pacing::per_minute refused.
PcsExternalClient
Phantom-typed gRPC client for the PCS External Developer Platform.
PcsExternalClientBuilder
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 of Error::Refused, never a return type of its own.
SendRequestEventSubscription
A resumable subscription to this app’s delivery events, from crate::PcsExternalClient::subscribe_send_request_events.
WireStatus
The status name an Error carries when the call reached the server (Error::wire) — opaque, for logs and messages; branch on Rejection or 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 EndpointError refused — the face’s address (Api) or PAS’s issuer (Issuer). Which configured URL a refusal is about — the half of an EndpointError that says which one was wrong.
EnvError
What PcsExternalClientBuilder::from_env returns 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::Refused means — the return type of Error::rejection, doored beside Error so 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, and Fault’s is_credential / is_retryable):