Client configuration

Overlay, tenant, channel

Three names. Easy to mix up.

Name	Role
Overlay	The FastPubSub network / environment you join (`globaltest`, or the overlay name from Cockpit). `open(overlay)` bootstraps edges for that overlay.
Tenant	Isolation inside an overlay. Messages never cross tenants. No tenant wildcards.
Channel	The stream inside a tenant, usually dot-separated (`public.chat.room1`). Publish uses a concrete name. Subscribe may use a pattern.

Tokens

Master token (MT_...) — stays on your backend. It creates, refreshes, and revokes access tokens. Never ship it to a browser. Cockpit stores a required name with the token, plus optional description, tenant_prefix, and allow_ip_masks (IP of the token API, not of the client socket).
Access token (AT_{id}_{secret}) — given to clients. It carries tenant grants, optional IP/origin/protocol limits, optional KB/s caps, and an expiry.

Maximum access-token TTL is 24 hours. Extend it with refresh from the backend, or mint a new token.

See Tokens and REST API.

Edge selection

The SDK does not hard-code a region.

Bootstrap returns nearby edge candidates for the overlay.
The client calls GET /ping on candidates and keeps the fastest.
WebSocket (or WebTransport) connects to that edge with the access token.

In JavaScript, webSocket(token).build() can resolve the edge for you and cache it. In Rust, call session.resolve_edge().await? before web_socket.

GET /ping is only for picking an edge. After the socket is open, optional application PING/PONG measures RTT on that connection. See JavaScript SDK.

Endpoints

You usually do not set URLs by hand. The SDK derives:

REST base on the selected edge (/ping, /v1/get-token, …)
WebSocket endpoint
WebTransport endpoint when the edge publishes one

For tests you can still pin an explicit WebSocket URL in the SDK builder.

Browser vs backend

Piece	Where it runs
Master token, `createAccessToken`, refresh, revoke	Backend
`open(overlay)`, `webSocket(accessToken)`, publish/subscribe	Browser, Node.js, or a Rust service
Access token	Short-lived credential on the client

If allowed_ws_origin is set on the token, the browser Origin header must match.

Keyboard shortcuts