Realtime Updates

Realtime Updates

Phoenix offers a managed WebSocket channel for live leaderboard streams. Use it when you need immediate score changes in your game client, spectator dashboard, or broadcast overlays.

1. Endpoint & Authentication

GET /v1/leaderboards/{leaderboard_id}/ws
Authorization: Bearer <JWT>

• Protocol: Secure WebSocket (wss://).
• Auth: Send the same JWT used for Query Gateway REST: Authorization: Bearer <JWT> on the HTTP upgrade request. Tenant is resolved from the token; the path does not include tenant_id.
• Phoenix validates the JWT and ensures the leaderboard exists for the tenant before upgrading the connection.

2. Connection Workflow

1. Resolve leaderboard – ensure the leaderboard is active and you have the valid JWT for the tenant.
2. Open WebSocket – use your preferred WebSocket client. On success, Phoenix immediately sends a snapshot for page 1 (size 100 by default).
3. Send configuration – optionally send a configure message to set custom pagination, filters, or window keys.
4. Stream updates – Phoenix delivers JSON messages as scores change, keeping your UI synchronized.

Connections idle for more than 30 seconds are pinged automatically; respond with pong frames or simply rely on Phoenix's built-in heartbeat messages.

3. Client Messages

To modify what you receive, send JSON messages with the following structure:

{
  "type": "configure",
  "page": 2,
  "page_size": 50,
  "filter": { "type": "top_n", "n": 100 }
}

Filters (filter.type) mirror the options exposed by Phoenix's WebSocket handler:

• none – receive all updates (default).
• page_range – only entries affecting a specific page.
• page_aware – current page plus users who might enter it (supports buffer_size).
• top_n – top N users regardless of pagination.
• user_ids – "watchlist" of specific users.
• rank_range – updates for a rank band (e.g., 1–50).

Phoenix acknowledges configuration changes by returning a config_ack message that echoes the active settings.

4. Server → Client Messages

All outbound messages are JSON with the type field shown below:

All message schemas are documented in the services/query-gateway/src/handlers/websocket.rs file and remain stable for client integrations.

5. Filtering Strategies & Pagination Tips

• Top N overlays – use filter: { "type": "top_n", "n": 50 } to power broadcast tickers without paginated requests.
• Page-aware UIs – page_aware ensures you see anyone who might enter the current page (configurable buffer_size defaults to page_size).
• Watchlists – track specific users or squads by sending user_ids. Phoenix only delivers updates for those IDs, reducing noise.
• Rank range highlights – perfect for spotlighting mid-tier brackets ("ranks 500–550").

To keep clients in sync:

1. Open WebSocket and display the initial snapshot.
2. Listen for score_update messages and patch your UI.
3. Periodically refresh via request_page to handle large jumps (e.g., a user moving multiple pages at once).
4. Handle config_ack to confirm server-side pagination state matches your UI.

6. Handling Windows

By default, Phoenix streams the current window for the leaderboard's timeframe. If you need a completed window:

• Include window_key in your configure message (e.g., "window_key": "2025-11-18T12" for hourly).
• If the requested window is historical, Phoenix sources data from its snapshot store and still emits updates (none for completed windows, but the page data is returned).
• If the window doesn't exist, you receive an error message with details.

7. Error & Disconnect Scenarios

Always treat WebSocket connections as transient. Implement reconnection logic and resume from the latest known page/window.

8. Sample Client (TypeScript)

WebSocket auth uses the same JWT as Query REST: send Authorization: Bearer <JWT> on the HTTP upgrade request. Path does not include tenant_id (tenant from JWT).

import WebSocket from "ws";

const leaderboardId = "xp-weekly-global";
const jwt = "your-jwt-token";

const ws = new WebSocket(
  `${QUERY_WS_URL}/v1/leaderboards/${leaderboardId}/ws`,
  {
    headers: {
      Authorization: `Bearer ${jwt}`,
    },
  }
);

ws.on("open", () => {
  console.log("Connected");
  ws.send(
    JSON.stringify({
      type: "configure",
      page: 1,
      page_size: 50,
      filter: { type: "page_aware", page: 1, page_size: 50, buffer_size: 50 },
    })
  );
});

ws.on("message", (data) => {
  const msg = JSON.parse(data.toString());
  switch (msg.type) {
    case "snapshot":
    case "page_data":
      renderLeaderboard(msg.entries);
      break;
    case "score_update":
      applyScoreUpdate(msg);
      break;
    case "ping":
      ws.pong();
      break;
    case "error":
      console.error("Server error:", msg.message);
      break;
  }
});

9. Checklist

• Use JWT in Authorization: Bearer <JWT> when opening the WebSocket.
• Handle snapshot, page_data, score_update, and ping messages.
• Implement reconnection logic with exponential backoff.
• Use filters to limit bandwidth (top N, page-aware, watchlists).
• Surface errors to operators when Phoenix rejects a connection.

Next guide: Querying Results, covering REST APIs for live pages, user-centric queries, and historical snapshots.