WebSocket Messages

WebSocket handlers are implemented in server/src/routes/ws.ts.

Endpoint: same host/port as HTTP, commonly ws://<host>:<port>/ws.

Authentication: the server requires a valid JWT on the WebSocket handshake, passed as the query parameter token (for example ws://localhost:3000/ws?token=<jwt>). The browser WebSocket API cannot set Authorization headers; the web client appends this query parameter automatically from the stored login token. Unauthenticated upgrade attempts receive HTTP 403.

Authorization: after authentication, subscription handlers enforce access (for example track requires an allowed beacon for non-admin users; overview, debug, gatify, gateway_config, test_beacon, and debug_device require an admin JWT).

Client message types

Type	Purpose	Topic behavior
track	Subscribe to position updates for one beacon MAC	subscribes track-{mac}
debug	Subscribe to debug tracking stream for one beacon MAC	subscribes track-debug-{mac}
overview	Subscribe to map-level overview updates	subscribes overview-{map_id}
events	Subscribe to global event stream	subscribes events
test_beacon	Send a test beacon message for processing	subscribes test-beacon and forwards message
gatify	Subscribe to gatify stream	subscribes gatify
debug_device	Device debug channel control	action-based subscribe/unsubscribe/keepalive

debug_device actions

debug_device messages include:

• action: "subscribe" -> subscribes debug-device-{search}
• action: "unsubscribe" -> unsubscribes debug-device-{search}
• action: "keepalive" -> refreshes keepalive for the tracked search key

Validation

Incoming messages are validated by schema before subscription logic:

• HttpWsMessageTrackSchema
• HttpWsMessageOverviewSchema
• HttpWsMessageDebugDeviceSchema