recflare/apps/notify/README.md

notify

Notifications Worker served on the notify subdomain. Hosts a SignalR hub at /hub/v1.

The hub is implemented as a Durable Object (NotificationsHub) speaking the SignalR JSON Hub Protocol over a hibernatable WebSocket. A single global DO instance holds the shared hub state (one process across all connections).

Endpoints

• POST /hub/v1/negotiate — SignalR negotiation. Returns a connectionId / connectionToken and advertises the WebSocket transport. The token is passed back as ?id= on the WebSocket connect.
• GET /hub/v1 (WebSocket upgrade) — the hub. Forwarded to the Durable Object. Non-upgrade requests get 426.
• POST /internal/notify — { playerId, notificationType, data? }. Send to a player's connections, queueing if they're offline. Admin-gated: requires a Bearer token carrying an admin role (developer/moderator) in its role claim.
• POST /internal/broadcast — { notificationType, data? }. Send to every connected client. Same admin-role gate as /internal/notify.
• POST /internal/coach-message-all — { messageContent }. Broadcast a coach/system MessageReceived to every connected client (online-only; not persisted). Same admin-role gate.

Hub protocol

1. Client POST /hub/v1/negotiate, then opens a WebSocket to /hub/v1?id=<token>.
2. Handshake: client sends {"protocol":"json","version":1}␞, server replies {}␞ (␞ = record separator 0x1e).
3. Server immediately sends the OnConnect invocation on connect.
4. Client→server invocations:
   • SubscribeToPlayers({ playerIds }) — replaces this connection's subscriptions and flushes any queued notifications for those players.
   • GetSubscriptions() → completion with the subscribed player id array.
5. Server→client: Notification invocations carrying a JSON string { Id: <PushNotificationId>, Msg: { ... } }.
6. Pings (type 6) are echoed.

State

Held in the DO's SQLite so it survives hibernation:

• subscriptions(connectionId, playerId) — serves both the connection→players and player→connections lookups.
• pending(id, playerId, payload) — per-player queue delivered once the player subscribes.

A connection's rows are removed on webSocketClose.

TODO before production

• Authenticate the /internal/* endpoints (or move them to a service binding / RPC reachable only by other workers).
• Wire the real callers (relationships, gifts, storefront, events, chat, …) to push through notifyPlayer / broadcast.
• Consider server-initiated keepalive pings if clients rely on them.