WebSocket

WebSocket is the main protocol for publishing and subscribing.

Connection

Open a WebSocket to the service URL (e.g. wss://ws.fastpubsub.com/) and pass your token. Use TLS (wss://) in production.

Authentication (how to pass the token)

There are two supported methods. The server checks them in the following priority order:

1. Authorization header (recommended for server-side clients):

   Authorization: Bearer AT_<id>_<secret>
   

2. Sec-WebSocket-Protocol subprotocol (recommended for browsers):

   The browser WebSocket API does not allow setting custom HTTP headers. Instead, pass the token as a subprotocol value with the at. prefix alongside a real protocol name (e.g. llps.v1):

   const ws = new WebSocket("wss://ws.fastpubsub.com/", [
     "llps.v1",
     "at.AT_<id>_<secret>"
   ]);
   

   The server extracts the token from the at.-prefixed value. In the 101 Switching Protocols response the server echoes back only the real protocol (Sec-WebSocket-Protocol: llps.v1); the token is never reflected in the response.

If neither method provides a valid token, the server responds with HTTP 401.

Subscribe

Send a subscribe message with tenant and channel (or a wildcard pattern). After that you receive messages as WebSocket frames (binary or text). Each frame is a message for that channel (tenant + channel name + payload).

Publish

Send a message with tenant, channel, and payload. The service forwards it to all current subscribers that match that tenant and channel (or pattern).

Message format

A common format is JSON: { "tenant": "...", "channel": "...", "payload": "..." }. The payload can be a string or base64-encoded binary. Some deployments use binary frames with the same structure. See Reference for the exact schema.

Error handling

If you send an invalid token, the connection will be closed immediately (often with a 401 or 403 status during handshake, or a Close frame). If you try to publish/subscribe to a forbidden tenant or channel, the service may silently drop the message or close the connection, depending on security settings. Connection loss should be handled by reconnecting (with exponential backoff).

For a practical list of common failures and codes, see Error codes.