Realtime
Self-negotiated WebSocket, SSE and NATS. Presence, replay, guaranteed ordering, backpressure. 1M connections by POP, fanout sub-15ms p99 between regions.
Sync, presence, broadcast#
The aura-realtime service broadcasts three types of events: CDC Postgres (INSERT/UPDATE/DELETE filtered by RLS), Presence (which is online) and Broadcast (custom events independent of the database). All go through the same SDK via .channel().
A channel is identified by an arbitrary name (sensors:live, doc:42, room:abc). Messages are ordered by channel, deduplicated by message_id, and guaranteed exactly-once within the same channel.
Subscriptions inherit the RLS policies from the database. A client can only subscribe to changes it can read — the filter is evaluated server-side on the WAL, not client-side.
One connection, N channels#
The SDK maintains a single multiplexed TCP connection between the client and the nearest POP. You can open 100 channels without opening 100 sockets.
┌──────────────────┐
Client (WS) ────▶ │ aura-realtime │
│ ─ CDC listener │
│ ─ Presence CRDT │
│ ─ Broadcast hub │
└────────┬─────────┘
│ NATS JetStream
┌────────────────────┴────────────────────┐
▼ ▼ ▼
aura-db WAL Presence state autres POPs
Events are partitioned by consistent hashing. A channel always lives on the same POP, but its replication to other POPs is guaranteed in less than 15ms p99.
Six native abilities#
- High-throughput transport. Native WebSocket connection powered by inter-service NATS.
- Postgres CDC. WAL changes filtered on the server side, RLS applied to the flow.
- Presence API. Who is online, arbitrary state, join/leave events.
- Multiplexing. Several channels share one WebSocket connection.
- Event delivery. Best-effort live delivery with automatic client reconnection.
- Collaborative cursors. Native primitive, adaptive throttle 60 FPS, client interpolation.
Four essential patterns#
const channel = aura.channel('db:public.devices')
.on('postgres_changes', {
event: '*',
schema: 'public',
table: 'devices',
filter: `tenant_id=eq.${tid}`,
}, ({ new: row }) => render(row))
.subscribe()
Always call channel.unsubscribe() on unmount. In React, do this in the useEffect cleanup — the useChannel hook above does it for you.
What we promise, what we don't promise#
✓ GUARANTEED
- Ordering by channel
- Exactly-once per
message_idin a channel - Fanout p99 < 15ms cross-region
- Auto reconnection with 60s replay
- Explicit backpressure (configurable drop policy)
✗ NOT GUARANTEED
- Cross-channel ordering
- Exactly-once cross-channel (at-least-once)
- Sub-ms latency (< 15ms p99 is our floor)
- Replay beyond 60s (use a Postgres log)