Socket API

The Socket API provides REST endpoints for managing WebSocket channels and broadcasting messages server-side.

List Channels

GET /api/socket/channels

Returns all currently active channels with member counts.

Response:

[
  { "name": "chat:room1", "memberCount": 5 },
  { "name": "notifications:user123", "memberCount": 1 }
]

GET /api/socket/channels/:channel/members

Example:

curl http://localhost:3000/api/socket/channels/chat:room1/members

Response:

[
  { "socketId": "abc123", "joinedAt": 1710000000000 },
  { "socketId": "def456", "joinedAt": 1710000100000 }
]

GET /api/socket/connections

Response:

{
  "count": 42
}

Send a message to all members of a channel via REST (useful for server-side broadcasting):

POST /api/socket/broadcast

Request Body:

{
  "channel": "chat:room1",
  "event": "message",
  "data": {
    "text": "Server announcement",
    "sender": "system"
  }
}

These events are used over the Socket.IO WebSocket connection (not REST):

Event	Direction	Payload	Description
`subscribe`	Client → Server	`{ topic, filter?, returnMode? }`	Subscribe to a domain topic. `returnMode` controls sync event payload shape (`'full'`, `'diff'`, or `'both'`).
`unsubscribe`	Client → Server	`{ subscriptionId }`	Unsubscribe from a topic
`event`	Server → Client	`RealtimeEvent`	Delivered event matching subscription

For plain WebSocket clients connected on /ws, the JSON message protocol is:

Client → Server:

{ "type": "subscribe", "topic": "sync.session.updated", "filter": {}, "returnMode": "diff" }

{ "type": "unsubscribe", "subscriptionId": "sub_abc123" }

{ "type": "ping" }

Server → Client:

{ "type": "subscribed", "subscriptionId": "sub_abc123", "topic": "sync.session.updated" }

{ "type": "event", "topic": "sync.session.updated", "data": { ... } }

{ "type": "pong" }