Realtime Server-Sent Events (SSE)
Realtime Server-Sent Events (SSE)
NodeStack provides real-time event distribution via standard HTTP Server-Sent Events (SSE).
Why SSE Instead of WebSockets?
- Standard HTTP/2 & HTTP/1.1: Operates over standard HTTP without protocol upgrade issues across proxies, corporate firewalls, and CDNs.
- Built-in Browser Reconnection: Browsers automatically attempt reconnection if a connection drops.
- Lightweight: Minimal memory footprint per open connection.
The Handshake Protocol (NS_CONNECT)
- The client opens an
EventSourceconnection to:GET /api/realtime - The server acknowledges the connection by sending an initial handshake event containing a unique client ID:
event: NS_CONNECTdata: {"clientId": "cl_8f910a2b"}
- The client submits subscription requests by
POSTing topics (collections or specific record IDs) to/api/realtime:POST /api/realtimeContent-Type: application/json{"clientId": "cl_8f910a2b","subscriptions": ["posts", "orders/rec_12345"]}
Using via nodestack-client
The TypeScript client SDK handles connection multiplexing, handshakes, authorization, and reconnection automatically:
import NodeStackClient from 'nodestack-client';
const client = new NodeStackClient('http://localhost:8090');
// Subscribe to all changes in the 'posts' collection
const unsubscribe = await client.collection('posts').subscribe('*', (event) => {
console.log('Action:', event.action); // 'create' | 'update' | 'delete'
console.log('Record:', event.record);
});
// Subscribe to a specific single record
await client.collection('posts').subscribe('rec_12345', (event) => {
console.log('Post 12345 updated:', event.record);
});
// Clean up subscription when no longer needed
unsubscribe();
Access Rule Enforcement
Real-time subscriptions strictly respect collection Access Rules:
- When a record is mutated, NodeStack re-evaluates the collection's View Rule against each connected client's auth context.
- If a client does not have permission to view the updated record, the event is silently suppressed for that connection.