Realtime guide
Subscribe a live client to record changes.
Authenticate at /live, read the session message,
subscribe to a permitted topic, and handle responses and events as
different message types.
- WebSocket
- Topic permissions
- Base64 payload
Use the wire protocol as documented.
const ws = new WebSocket(
`ws://localhost:6336/live?token=${TOKEN}`
)
ws.send(JSON.stringify({
id: "req-1",
method: "subscribe",
attributes: { topicName: "order" }
}))
Separate type, topic, and
event fields identify a pushed record event. The wire
data is base64-encoded JSON, so decode it before
parsing. Do not invent a combined event name.
Design for a live connection, not a durable queue.
- The initial session message contains the expected user and groups.
- Allowed and denied system-topic subscriptions return distinct responses.
- Create, update, and delete each arrive with the correct topic and event fields.
- Ping receives pong and the client reconnects with backoff after interruption.
- The client refreshes authoritative records after reconnection instead of assuming no events were missed.
- Clients reconnect after a group or permission change because subscription context is captured on connection.
- Row data is tested with the exact access model before exposing sensitive topics.
These are live notifications, not a durable event log with replay or guaranteed delivery. Use database state as the authority after disconnects.
Connection test
Treat notification and state as different things.
- Authenticate, subscribe to one permitted table topic, and decode the base64 JSON event data.
- Confirm a caller without topic access cannot subscribe successfully.
- Change group membership and reconnect before expecting the new authorization context.
- Disconnect during several writes, reconnect, and reload authoritative records through the data API.
- Do not promise replay, durable delivery, or guaranteed receipt; add a durable queue when the product requires those semantics.