Realtime

CairnCMS can push change notifications to connected clients over a WebSocket, so an interface can update as data changes instead of polling. A client opens a persistent connection, subscribes to one or more collections, and receives a message whenever a matching item is created, updated, or deleted.

Realtime is off by default. It is enabled per deployment through the WEBSOCKETS_* configuration, documented in Manage configuration. This section is the usage and protocol reference for what that surface exposes.

Delivery model

Realtime lets applications respond quickly to changes without polling continuously. The database remains authoritative, and each notification tells the client when to reread current state.

• Responsive updates. Subscribe to the collections that matter and use each message to refresh the relevant data.
• Deployment-sized throughput. Notification timing reflects result-set size, query cost, subscriber count, and available capacity. Operators size the deployment for the expected workload.
• Application-owned freshness. Notifications are not stored or replayed and can be missed during a disconnect, overload, or messenger outage. Clients reconnect, resubscribe, and reread after an interruption. Applications that need tighter freshness can also reconcile on their own schedule.

See Reliability for deployment and recovery guidance.

Choose a transport

Use the item protocol for the CairnCMS SDK, initial snapshots, item operations over the socket, or change notifications from dashboards, notifications, operations, panels, and shares.

Use GraphQL subscriptions when your client already uses graphql-transport-ws and you want selection-set-shaped notifications for item collections.

Both transports use the same authentication modes and permission-checked delivery. See Subscription authorization for their shared permission, delete-feed, and ordering rules.

Authentication at a glance

Each transport is configured with one of three authentication modes. Credentials are always an access token. There is no email and password or query-string token over the socket.

• public — anonymous. The connection has the permissions of the public role until a token is supplied.
• handshake — authenticate with the first message. The default.
• strict — a Bearer token is required at the upgrade, before the socket opens.

The Authentication page covers the exact credential location and flow for each mode and transport, token renewal, and the rejection rules.

A minimal client

Using @cairncms/sdk:

import { createCairnCMS, staticToken, realtime } from '@cairncms/sdk';

const client = createCairnCMS('https://example.com')
  .with(staticToken('<token>'))
  .with(realtime({ authMode: 'handshake' }));

await client.connect();

const { subscription } = await client.subscribe('articles');

for await (const message of subscription) {
  console.log(message);
}

The SDK realtime client uses the item protocol and supports the public and handshake modes. The strict mode is a server-side upgrade contract, exercised by a raw client rather than the SDK.

Where to go next

• Authentication — the three modes across both transports, credential location, renewal, and rejection rules.
• Subscription authorization — permission-checked delivery, row-level filters, delete-feed eligibility, and ordering.
• Item protocol — the /websocket JSON frame reference.
• GraphQL subscriptions — the /graphql graphql-transport-ws reference.
• SDK — the realtime() composable and the JavaScript client.
• Extensions — the WebSocketService and the connection lifecycle hooks.
• Reliability — enabling transports, multiple instances, limits, reverse proxies, and recovery.
• Manage configuration — the canonical transport settings, defaults, and limits.