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):
| Environment | Value | Notes |
|---|---|---|
| Production | https://chat.ppoppo.com/grpc | TLS; /grpc is a real path prefix on the ingress |
| Development | http://localhost:3200 | Bare origin, no path suffix — the h2c listener serves native gRPC at the root |
Do not use
localhost:3202for 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 set | subscribe_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_triggers | sender_profile / list_contacts / list_labels / list_contacts_by_label | advance_read_watermark | send_message / send_to_multiple / delete_message / create_transaction / pause_trigger / cancel_trigger | create_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_member | set_my_profile | add_contact / remove_contact / update_contact / block_user / unblock_user / create_label / delete_label / add_contact_to_label / remove_contact_from_label | list_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_trigger | discover_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
PcsSessionClientBuildertakes, and the vocabulary its sources speak. - feed
- The feed projection: a delivered
Messageplus the party already resolved for it, as one render-readyFeedItem. - scopes
- Sealed scope-set type family for
crate::PcsSessionClient<S>. - types
- Domain types for the session-face SDK.
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. - Endpoint
Error - What
PcsSessionClientBuilder::newreturns for a malformedapi_url, and a grant credential’snewfor 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. - Message
Subscription - A live message subscription. Obtain via
PcsSessionClient::subscribe_allorPcsSessionClient::subscribe_channel. - PcsSession
Client - Phantom-typed client for the PCS session face (
pcs.session.v1). - PcsSession
Client Builder - 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 ofError::Refused, never a return type of its own. - 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§
- ActFamily
- How much an
Operationcan change, and the family of a privileged one. Vocabulary (ppoppo-chat). The family aSensitivity::Privilegedact belongs to — and so the grant a non-human caller must hold to take it. - Discovery
Error - 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’sfor_issuerconstructor returns. - Endpoint
- Which configured URL an
EndpointErrorrefused — the face’s address (Api), the token endpoint (Token) or, inside aDiscoveryError, the issuer (Issuer). Which configured URL a refusal is about — the half of anEndpointErrorthat says which one was wrong. - EnvError
- What
PcsSessionClientBuilder::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.
- Operation
- One session-face RPC, with the
SensitivityPCS 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 everySensitivity::Privilegedact itself. Vocabulary (ppoppo-chat). One session-face (pcs.session.v1) RPC. Variant name = method name. - 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): - Sensitivity
- How much an
Operationcan 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: PostgreSQLlength()ontextcounts 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.