Loading documentation...
Preparing Ring Platform content
Concepts, value, and typical clone scenarios — less code.
Concepts, value, and typical clone scenarios — less code.
Preparing Ring Platform content
Preparing Ring Platform content
Preparing Ring Platform content
TunnelProvider (in app-client-shell.tsx) owns the shared WSS/SSE connection and channel-subscription-registry. Tunnel consumers — including CreditBalanceProvider and GlobalTunnelListeners — must mount inside TunnelProvider. Feature hooks such as useSync and useUnreadCount should run once inside NotificationProvider — nav widgets consume useNotificationContext(), not duplicate useUnreadCount() calls.
Ring Platform delivers realtime updates through Tunnel Protocol:
lib/tunnel/hub/) — server-side broker; SSE, native WSS, poll queues, channel subscriptions, offline per-user queueserver.ts) — Next.js handler + attachTunnelWss when RING_DEPLOY_TARGET is k8s or self-hostedlib/tunnel/tunnel-timing.ts priority/deferred routes (Tunnel protocol — timing)lib/discovery/sync-discovery.ts publishes opportunity:* and entity:* on topic channels after CRUD (Discovery mutation sync)When publishToUserTunnel runs with no live socket, InMemoryTunnelHub queues the message (publisher logs at console.debug, not an error). On connect:
app/api/tunnel/sse/route.ts drains via hub.drainUserQueueForSse(userId)lib/tunnel/native-ws/attach.ts drains via hub.drainUserQueue(userId) immediately after { op: 'auth_ok' } (parity with SSE)Boot-race messages (e.g. device telemetry during auth-grace) are delivered on the first transport handshake, not the next page load.
Routes, auth frames, priority timing, HTTP dedup hooks, and alpha limitations.
In-app alerts, preferences, and FCM push when the tab is closed.
Provider matrix and subscription dedup backlog.
TunnelProvider defers connect briefly after auth so HTTP ingest (analytics device registration, initial REST) can complete first. Priority routes — including /admin and nested /admin/* — get faster auto-connect via matchesRoutePrefix() in lib/tunnel/tunnel-timing.ts (prefix match, not exact pathname string).
Full route tables, env overrides, and boot-race SSOT: Tunnel protocol.
| Feature | Server publish | Client subscribe |
|---|---|---|
| Notifications | publishToUserTunnel → notifications:unread / notifications:inbox | NotificationProvider → useNotificationContext() |
| Credit balance | publishToUserTunnel → credit:balance (via creditBalanceService.publishBalanceUpdate) | CreditBalanceProvider → useCreditBalanceContext() (bootstrap REST dedup + tunnel push; 60s poll only if tunnel down) |
| Wallet list / native balances | publishWalletListUpdate → wallet:list | WalletListProvider (wallet-wrapper) → useTunnelChannel('wallet:list') |
| Account status | publishToUserTunnel → account:status | GlobalTunnelListeners → AccountStatusTunnelListener |
| Vendor sidebar gate | — (HTTP only) |
See Tunnel protocol for API routes, RING_DEPLOY_TARGET, channel patterns, and alpha limitations.
TunnelProvider (in app-client-shell.tsx) owns the shared WSS/SSE connection and channel-subscription-registry. Tunnel consumers — including CreditBalanceProvider and GlobalTunnelListeners — must mount inside TunnelProvider. Feature hooks such as useSync and useUnreadCount should run once inside NotificationProvider — nav widgets consume useNotificationContext(), not duplicate useUnreadCount() calls.
Ring Platform delivers realtime updates through Tunnel Protocol:
lib/tunnel/hub/) — server-side broker; SSE, native WSS, poll queues, channel subscriptions, offline per-user queueserver.ts) — Next.js handler + attachTunnelWss when RING_DEPLOY_TARGET is k8s or self-hostedlib/tunnel/tunnel-timing.ts priority/deferred routes (Tunnel protocol — timing)lib/discovery/sync-discovery.ts publishes opportunity:* and entity:* on topic channels after CRUD (Discovery mutation sync)When publishToUserTunnel runs with no live socket, InMemoryTunnelHub queues the message (publisher logs at console.debug, not an error). On connect:
app/api/tunnel/sse/route.ts drains via hub.drainUserQueueForSse(userId)lib/tunnel/native-ws/attach.ts drains via hub.drainUserQueue(userId) immediately after { op: 'auth_ok' } (parity with SSE)Boot-race messages (e.g. device telemetry during auth-grace) are delivered on the first transport handshake, not the next page load.
Routes, auth frames, priority timing, HTTP dedup hooks, and alpha limitations.
In-app alerts, preferences, and FCM push when the tab is closed.
Provider matrix and subscription dedup backlog.
TunnelProvider defers connect briefly after auth so HTTP ingest (analytics device registration, initial REST) can complete first. Priority routes — including /admin and nested /admin/* — get faster auto-connect via matchesRoutePrefix() in lib/tunnel/tunnel-timing.ts (prefix match, not exact pathname string).
Full route tables, env overrides, and boot-race SSOT: Tunnel protocol.
| Feature | Server publish | Client subscribe |
|---|---|---|
| Notifications | publishToUserTunnel → notifications:unread / notifications:inbox | NotificationProvider → useNotificationContext() |
| Credit balance | publishToUserTunnel → credit:balance (via creditBalanceService.publishBalanceUpdate) | CreditBalanceProvider → useCreditBalanceContext() (bootstrap REST dedup + tunnel push; 60s poll only if tunnel down) |
| Wallet list / native balances | publishWalletListUpdate → wallet:list | WalletListProvider (wallet-wrapper) → useTunnelChannel('wallet:list') |
| Account status | publishToUserTunnel → account:status | GlobalTunnelListeners → AccountStatusTunnelListener |
| Vendor sidebar gate | — (HTTP only) |
See Tunnel protocol for API routes, RING_DEPLOY_TARGET, channel patterns, and alpha limitations.
TunnelProvider (in app-client-shell.tsx) owns the shared WSS/SSE connection and channel-subscription-registry. Tunnel consumers — including CreditBalanceProvider and GlobalTunnelListeners — must mount inside TunnelProvider. Feature hooks such as useSync and useUnreadCount should run once inside NotificationProvider — nav widgets consume useNotificationContext(), not duplicate useUnreadCount() calls.
Ring Platform delivers realtime updates through Tunnel Protocol:
lib/tunnel/hub/) — server-side broker; SSE, native WSS, poll queues, channel subscriptions, offline per-user queueserver.ts) — Next.js handler + attachTunnelWss when RING_DEPLOY_TARGET is k8s or self-hostedlib/tunnel/tunnel-timing.ts priority/deferred routes (Tunnel protocol — timing)lib/discovery/sync-discovery.ts publishes opportunity:* and entity:* on topic channels after CRUD (Discovery mutation sync)When publishToUserTunnel runs with no live socket, InMemoryTunnelHub queues the message (publisher logs at console.debug, not an error). On connect:
app/api/tunnel/sse/route.ts drains via hub.drainUserQueueForSse(userId)lib/tunnel/native-ws/attach.ts drains via hub.drainUserQueue(userId) immediately after { op: 'auth_ok' } (parity with SSE)Boot-race messages (e.g. device telemetry during auth-grace) are delivered on the first transport handshake, not the next page load.
Routes, auth frames, priority timing, HTTP dedup hooks, and alpha limitations.
In-app alerts, preferences, and FCM push when the tab is closed.
Provider matrix and subscription dedup backlog.
TunnelProvider defers connect briefly after auth so HTTP ingest (analytics device registration, initial REST) can complete first. Priority routes — including /admin and nested /admin/* — get faster auto-connect via matchesRoutePrefix() in lib/tunnel/tunnel-timing.ts (prefix match, not exact pathname string).
Full route tables, env overrides, and boot-race SSOT: Tunnel protocol.
| Feature | Server publish | Client subscribe |
|---|---|---|
| Notifications | publishToUserTunnel → notifications:unread / notifications:inbox | NotificationProvider → useNotificationContext() |
| Credit balance | publishToUserTunnel → credit:balance (via creditBalanceService.publishBalanceUpdate) | CreditBalanceProvider → useCreditBalanceContext() (bootstrap REST dedup + tunnel push; 60s poll only if tunnel down) |
| Wallet list / native balances | publishWalletListUpdate → wallet:list | WalletListProvider (wallet-wrapper) → useTunnelChannel('wallet:list') |
| Account status | publishToUserTunnel → account:status | GlobalTunnelListeners → AccountStatusTunnelListener |
| Vendor sidebar gate | — (HTTP only) |
See Tunnel protocol for API routes, RING_DEPLOY_TARGET, channel patterns, and alpha limitations.
useVendorStatus() → GET /api/vendor/status (30s TTL, single-flight) |
| Chat | publishToChannel → conversation:${id} | hooks/use-messaging.ts → useTunnelChannel |
| Discovery | syncDiscovery → opportunities / entities | use-realtime-opportunities.ts / use-realtime-entities.ts |
| Matcher | publishToChannel → matcher | Admin/matcher UI |
| Collaboration (flagged) | collab:${id} binary CRDT frames | useCollaboration (requires WSS) |
useVendorStatus() → GET /api/vendor/status (30s TTL, single-flight) |
| Chat | publishToChannel → conversation:${id} | hooks/use-messaging.ts → useTunnelChannel |
| Discovery | syncDiscovery → opportunities / entities | use-realtime-opportunities.ts / use-realtime-entities.ts |
| Matcher | publishToChannel → matcher | Admin/matcher UI |
| Collaboration (flagged) | collab:${id} binary CRDT frames | useCollaboration (requires WSS) |
useVendorStatus() → GET /api/vendor/status (30s TTL, single-flight) |
| Chat | publishToChannel → conversation:${id} | hooks/use-messaging.ts → useTunnelChannel |
| Discovery | syncDiscovery → opportunities / entities | use-realtime-opportunities.ts / use-realtime-entities.ts |
| Matcher | publishToChannel → matcher | Admin/matcher UI |
| Collaboration (flagged) | collab:${id} binary CRDT frames | useCollaboration (requires WSS) |