Socket Service

The Socket Service provides raw WebSocket messaging capabilities built on Socket.IO. It supports channel-based subscriptions, message broadcasting, direct messaging between clients, and presence tracking.

Core Concepts

Channels

Channels are named groups that clients can join and leave. Messages published to a channel are delivered to all members.

chat:room1
notifications:user123
game:match5

Channel names are arbitrary strings — you define the naming convention for your application.

Connection Lifecycle

Client connects → Authentication → Join channels → Send/Receive → Disconnect

All WebSocket connections are authenticated via JWT tokens passed during the initial handshake.

Usage

Join a Channel

realtime.socketClient.joinChannel('chat:room1');

{
  "event": "subscribe",
  "data": { "topic": "chat:room1" }
}

Publish to a Channel

Send a message to all members of a channel:

realtime.socketClient.publish('chat:room1', 'message', {
  text: 'Hello everyone!',
  sender: 'user123',
});

curl -X POST http://localhost:3000/api/socket/broadcast \
  -H 'Content-Type: application/json' \
  -d '{
    "channel": "chat:room1",
    "event": "message",
    "data": { "text": "Hello everyone!", "sender": "user123" }
  }'

Direct Messaging

Send a message to a specific connected client by their socket ID:

realtime.socketClient.directMessage(targetSocketId, 'notification', {
  text: 'You have a new message',
});

Leave a Channel

realtime.socketClient.leaveChannel('chat:room1');

Connection Events

Listen for connection lifecycle events:

realtime.on('connection', ({ state }) => {
  console.log('Connection state:', state);
  // 'connecting' | 'connected' | 'disconnected' | 'reconnecting'
});

realtime.on('error', (err) => {
  console.error('Connection error:', err);
});

Socket.IO handles automatic reconnection with exponential backoff.

Presence

The Socket Service tracks which clients are connected to each channel:

• Join — presence event broadcast when a client joins a channel
• Leave — presence event broadcast when a client leaves or disconnects
• Members — query current members of a channel

Query Channel Members

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

List Active Channels

curl http://localhost:3000/api/socket/channels

Connection Count

curl http://localhost:3000/api/socket/connections

REST API Reference

WebSocket Events

Admin UI

The Socket Channels page (/socket) in the Admin UI provides:

• List of all active channels with member counts
• View members in each channel
• Broadcast events to channels from the UI
• Real-time connection metrics

Architecture

The Socket Gateway is integrated into the backend Express server via Socket.IO:

Client WebSocket
  → Socket.IO Server (backend)
  → Authentication middleware
  → Channel subscription manager
  → Redis Pub/Sub (cross-instance fanout)
  → Event delivery to connected clients

When running multiple backend instances, Redis Pub/Sub ensures that messages published on one instance are delivered to subscribers connected to other instances.