Skip to main content

Crate ppoppo_pcs_session

Crate ppoppo_pcs_session 

Source
Expand description

§ppoppo-pcs-session

Ppoppo Chat System (PCS) session-face client for Rust.

The SDK for receive-and-respond apps — a desktop notifier, a message logger, an auto-responder. It runs as the user, on a session JWT, and turns “listen to my messages and react” into a one-dependency program.

  • Server-streaming subscribe with reconnect, exponential backoff, and cursor-resume (no missed messages across a drop)
  • Phantom-typed scope sets — method availability enforced at compile time, and independently by the server (double lock)
  • Token re-mint on a server-rejected credential, handled inside the stream

§Usage

[dependencies]
ppoppo-pcs-session = "0.16"
use ppoppo_pcs_session::PcsSessionClientBuilder;
use ppoppo_pcs_session::types::{SenderKey, SubscribeOptions};
use ppoppo_pcs_session::scopes::Notify;
use ppoppo_pcs_session::credential::{AccessToken, StaticTokenSource};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PcsSessionClientBuilder::new(
        "https://chat.ppoppo.com/grpc",
        StaticTokenSource::new(AccessToken::new(std::env::var("PPOPPO_SESSION_TOKEN")?)),
    )?
    .build_as::<Notify>()?; // a bare token cannot vouch for its tier

    let mut sub = client.subscribe_all(SubscribeOptions::default());
    while let Some(msg) = sub.next().await? {
        // A sender-less message (system-composed) has no one to resolve.
        let from = match &msg.sender_ppnum_id {
            Some(id) => client
                .sender_profile(SenderKey::PpnumId(*id))
                .await?
                .profile
                .display()
                // Neither a name nor a number this session may see.
                .unwrap_or("someone")
                .to_owned(),
            None => "system".to_owned(),
        };
        println!("[{}] {}: {}", msg.channel_id, from, msg.content);
    }
    Ok(())
}

That loop is the whole program — reconnects, exponential backoff, cursor-resume and token re-mint on a server-rejected credential all live inside MessageSubscription. An app that wants to render the connection state (“reconnecting…”) reads MessageSubscription::event instead, which yields every transition as a types::ResumeEvent.

§Endpoints

The value you pass as the builder’s first argument (commonly wired from PCS_SESSION_API_URL):

EnvironmentValueNotes
Productionhttps://chat.ppoppo.com/grpcTLS; /grpc is a real path prefix on the ingress
Developmenthttp://localhost:3200Bare origin, no path suffix — the h2c listener serves native gRPC at the root

Do not use localhost:3202 for local development. It looks like the “native gRPC” port, but it terminates TLS with a self-signed certificate and nests the service under /grpc. This client validates against the system root store and exposes no insecure-TLS knob, so it cannot connect there at all — the failure is a TLS handshake error, not an obvious “wrong port” message. Verified live 2026-07-19.

§Scope sets

Construct the client with the scope set matching your OAuth2 grant:

Scope setsubscribe_all / subscribe_channel / get_message / get_messages / search_messages / list_channels / get_channel / list_roster / list_channel_invitations / get_channel_add_policy / get_read_receipts / get_reactions / get_bulk_reactions / get_transaction / list_transactions / get_trigger / list_triggerssender_profile / list_contacts / list_labels / list_contacts_by_labeladvance_read_watermarksend_message / send_to_multiple / delete_message / create_transaction / pause_trigger / cancel_triggercreate_channel / add_member / get_or_create_direct_channel / get_or_create_channel_by_members / respond_to_channel_invitation / leave_channel / update_channel_add_policy / update_read_receipts / create_from_template / remove_memberset_my_profileadd_contact / remove_contact / update_contact / block_user / unblock_user / create_label / delete_label / add_contact_to_label / remove_contact_from_labellist_info_items / get_info_item / add_info_item / update_info_item / delete_info_item / share_info_items / add_reaction / remove_reaction / respond_to_transaction / create_trigger / preview_trigger / update_trigger / resume_triggerdiscover_agents / get_capabilities / get_relations / get_delegation / get_delegation_chain / create_delegation / respond_to_delegation
ReadOnly✓————————
Notify✓✓✓——————
ReadAndSend✓✓✓✓—————
Converse✓✓✓✓✓✓———
Unrestricted✓✓✓✓✓✓✓✓✓

get_me is not in the table: every scope set, Agent included, reaches it, because it reads only the caller.

Calling a method your scope set does not carry is a compile error, not a runtime PermissionDenied. advance_read_watermark (read-ack, chat.ack) joins the Notify tier — a notifier marks a message read so it stops re-alerting; the write reaches only the caller’s own read position.

Unrestricted sits above Converse and requests every atom a method of this crate needs — today it adds contact.write (the session’s own address book), infoitem.read / infoitem.write (its info items), reaction.write, chat.respond (answering a transaction addressed to the session), chat.schedule (temporal triggers — a writer that sends as the session later, with no live token; the Agent grant carries it too), and agent.read / agent.write (the agent directory and delegations). It is a separate tier rather than a larger Converse so that no app already registered for Converse is re-prompted or refused; request it only for what it adds.

§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 PcsSessionClientBuilder takes, and the vocabulary its sources speak.
feed
The feed projection: a delivered Message plus the party already resolved for it, as one render-ready FeedItem.
scopes
Sealed scope-set type family for crate::PcsSessionClient<S>.
types
Domain types for the session-face SDK.

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.
EndpointError
What PcsSessionClientBuilder::new returns for a malformed api_url, and a grant credential’s 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.
MessageSubscription
A live message subscription. Obtain via PcsSessionClient::subscribe_all or PcsSessionClient::subscribe_channel.
PcsSessionClient
Phantom-typed client for the PCS session face (pcs.session.v1).
PcsSessionClientBuilder
Builder for PcsSessionClient<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.
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§

ActFamily
How much an Operation can change, and the family of a privileged one. Vocabulary (ppoppo-chat). The family a Sensitivity::Privileged act belongs to — and so the grant a non-human caller must hold to take it.
DiscoveryError
Why a grant credential could not read PAS’s discovery document — the payload of credential::TokenSourceError::Discovery, which a token fetch returns. Transient when the fetch failed, terminal when the document cannot be used; never a verdict on the credential. Vocabulary (ppoppo-call), shared with every face that takes an issuer. Why an issuer could not be used to find an endpoint — what every face’s for_issuer constructor returns.
Endpoint
Which configured URL an EndpointError refused — the face’s address (Api), the token endpoint (Token) or, inside a DiscoveryError, the issuer (Issuer). Which configured URL a refusal is about — the half of an EndpointError that says which one was wrong.
EnvError
What PcsSessionClientBuilder::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.
Operation
One session-face RPC, with the Sensitivity PCS rates it — Operation::sensitivity. It is the value PCS’s own gates read: rate an operation stricter for your own confirmation prompt if you like, never looser, and never treat your prompt as the only gate — PCS judges every Sensitivity::Privileged act itself. Vocabulary (ppoppo-chat). One session-face (pcs.session.v1) RPC. Variant name = method name.
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):
Sensitivity
How much an Operation can change, and the family of a privileged one. Vocabulary (ppoppo-chat). How much an operation can change.

Constants§

INFO_ITEM_TITLE_MAX_CHARS
The most characters an InfoItem’s title holds; a longer one is refused. Derive a title by cutting to it. Vocabulary (ppoppo-chat). The most characters an info item’s title holds. Characters, not octets: PostgreSQL length() on text counts characters, and the table’s length CHECK is written with it. A title is also required — empty or whitespace-only is refused like an overlong one. Titles are stored in plaintext, unlike an item’s fields: a client that writes a title for the owner never derives it from the fields’ content.