Dashboard WebSocket API

Connect an open dashboard to receive project update events when an audit report is completed. The server sends project_updated with the project name and trigger. Your client reloads the relevant REST resources and updates the screen. This reference explains authentication, event fields, and connection recovery for frontend developers.

Prerequisites

Configure the server and sign in to obtain the JWT for your current session. Enable dashboard.websocket_enabled; this channel is disabled by default. The dashboard needs API access and a function that reloads project data through the REST API.

Endpoint

wss://codegraph.example/api/v1/traceability/ws

Use ws only for a trusted local HTTP environment. Production pages served over HTTPS must use wss.

Authentication

Send the token in the first message. A non-empty token query parameter causes the server to reject the HTTP handshake with status 403 before the WebSocket opens. The handler uses the rejection reason Query token transport is not allowed.

The server accepts the socket first and then waits up to 5 seconds for the first client message. Send a JSON object containing your JWT:

{"token": "<JWT>"}

The runtime also accepts a raw token string, but the JSON object is the documented contract. If authentication fails, the server sends an error event and closes with code 1008. If the first message does not arrive within 5 seconds, it closes with an authentication timeout.

If the connection rate limit is exceeded, the server closes with code 1008 and reason WebSocket rate limit exceeded, without a connected event.

An unauthenticated connection is allowed only when the explicit local-development unauthenticated-surface setting is enabled and both client and requested host are loopback addresses.

Events

Each dashboard message is a JSON object. Its event field identifies the event; the remaining fields carry its data.

The server broadcasts each project_updated event to every connected client. Each event includes the project name, trigger, and timestamp. Use these fields to choose which REST resources to reload.

Use project_name to select the dashboard resources to reload. The trigger field identifies the producer that requested the update, and timestamp records when the event was created as Unix time in seconds.

Browser example

Add this function to an authenticated dashboard. Pass a current JWT and a refreshDashboardResources(projectName) callback that reloads the relevant project REST resources. The example uses location.host, so it assumes that the page and API share a host.

function connectDashboardSocket(accessToken, refreshDashboardResources) {
  const scheme = location.protocol === "https:" ? "wss:" : "ws:";
  const socket = new WebSocket(
    scheme + "//" + location.host + "/api/v1/traceability/ws"
  );

  socket.addEventListener("open", () => {
    socket.send(JSON.stringify({ token: accessToken }));
  });

  socket.addEventListener("message", async (event) => {
    const message = JSON.parse(event.data);

    if (message.event === "project_updated") {
      await refreshDashboardResources(message.project_name);
    }
  });

  return socket;
}

Call connectDashboardSocket with the access token from your authenticated session and your existing resource-refresh function. It returns the WebSocket instance. After successful authentication, the server sends connected with a client identifier and the heartbeat interval. Each project_updated calls your refresh function with the project name. Call socket.close() when the dashboard is unmounted.

Keep the access token in session memory and exclude it from URLs and logs.

Heartbeat and reconnect

The server sends heartbeat after the configured idle interval. A client may send the plain text ping and should receive a pong event.

Reconnect with bounded exponential backoff and jitter. Obtain a fresh token before reconnecting if the authenticated session expired. Do not reconnect continuously after code 1008: first correct authentication, configuration, or rate-limit conditions.

After reconnecting, reload dashboard resources through REST because events emitted while the socket was disconnected are not replayed.

Configuration

dashboard:
  websocket_enabled: true
  websocket_heartbeat_seconds: 30

The effective heartbeat is capped by the runtime WebSocket ping timeout. Configuration changes require the normal deployment/restart process for the installation.

For chat, job progress, and user notifications, use Application WebSocket API.