Principal targeting

Principal targeting selects a verified subject's active connections. It is useful for notifying one user's browser and mobile connections. The application evaluates permission to reach the user and tenant separation before making this selection.

Configure the identity lifecycle#

When WebSocketIdentityMiddleware publishes verified identity to a connection, it establishes the principal index and expiry lifecycle. Without middleware, principal(...) does not enable this feature on its own; it produces a typed unavailable result. Configure authentication first.

Select an identity#

use lilyrs::websocket::PrincipalId;
let recipient = PrincipalId::try_new("user-42")?;
context.clients().principal(recipient)
    .send("chat:notification", "Yeni mesajınız var.").await?;

This snippet belongs in an async function in the chat namespace that can carry these errors; in an action, handle them with an appropriate conversion such as WebSocketActionError::internal. If the real recipient ID comes from a DTO, verify permission to send to that target first.

PrincipalId is an exact, nonempty value of at most 256 UTF-8 bytes, with no surrounding whitespace or control characters. It uses a different grammar from namespace or room tokens. The application decides whether to normalize identity or add a tenant prefix.

Refresh and expiry#

A successful reauthenticate publishes a new revision and updates the index. The Principal snapshot of a message in progress remains unchanged. If expiry applies to the relevant revision, index membership is removed and new admission ends.

Connection locals are not updated by refresh, so do not base authorization on a stale local copy. If tenants sharing a subject are not separated, principal targets in the same namespace can use a shared key; design the tenant model explicitly.

Distributed sending and delivery#

Principal targets also use the local/backplane dispatch path. Each node's connection manager owns its index memberships. Redis is not a globally authoritative presence store and provides no inbox or replay for offline devices.

send_with_receipt reports queue and publish acceptance. Having no current connection at the target differs from confirmation that a device processed the message. Delivery/read status requires explicit message IDs, persistent storage, and an application-ACK flow.