Scalable WebSockets (Redis Pub/Sub)

The boilerplate includes a production-ready, horizontally scalable WebSocket implementation using Redis Pub/Sub. This allows you to run multiple instances of your API (app_server) and ensuring that real-time messages reach all connected clients, regardless of which instance they are connected to.

Architecture

• Subscriber-Only: The WebSocket endpoint is designed primarily for receiving real-time updates (server-to-client).
• Redis Bridge: The server acts as a bridge. When a client subscribes to a topic (e.g., chat-room), the server subscribes to the corresponding Redis channel.
• Broadcast: Messages published to Redis are automatically broadcast to all WebSocket clients subscribed to that topic across all replicas.

Press enter or space to select a node. You can then use the arrow keys to move the node around. You can then use the arrow keys to move the node around, press delete to remove it and press escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or press escape to cancel.

Connection Details

• URL: ws://localhost:3000 or ws://localhost:5080 (or configured port)
• Protocol: JSON-based messages.

Message Protocol

1. Connection Established

Upon connection, the server sends:

{ "action": "connect", "message": "connection established" }
{ "action": "session", "message": "waiting for create session", "session": "YOUR_SESSION_ID" }

Save the session ID, it is required for all subsequent requests.

2. Authorization (Required)

You must authenticate using a valid JWT token before subscribing to topics.

Request:

{
  "action": "authorization",
  "session": "YOUR_SESSION_ID",
  "context": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response:

{ "action": "session", "message": "session authenticated" }

3. Subscribe to Topic

Start receiving messages for a specific context.

Request:

{
  "action": "subscribe",
  "session": "YOUR_SESSION_ID",
  "context": "chat-room"
}

Response:

{ "action": "subscribe", "message": "context subscribed" }

4. Unsubscribe

Stop receiving messages.

Request:

{
  "action": "unsubscribe",
  "session": "YOUR_SESSION_ID",
  "context": "chat-room"
}

Response:

{ "action": "unsubscribe", "message": "context unsubscribed" }

🧪 Testing Guide

Follow these steps to verify the implementation using Postman (or any WebSocket client) and Redis CLI.

Step 1: Connect

1. Open Postman.
2. Create a new WebSocket Request.
3. Enter URL: ws://localhost:3000 (or ws://localhost:5080 if testing docker-compose mapping).
4. Click Connect.
5. Copy the session ID from the response log.

Step 2: Authenticate

1. Send the Authorization JSON payload (see above) with a valid JWT.

   Note: If you are in a dev environment with auth disabled, you may skip this or send any string if the bypass is active.

Step 3: Subscribe

1. Send the Subscribe JSON payload for the context test-channel.
2. Verify you receive the context subscribed confirmation.

Step 4: Publish Message (Simulate Event)

Since the WebSocket is subscriber-only, use Redis to simulate a backend event.

1. Open your terminal.

2. Connect to the Redis container:

   podman exec -it redis redis-cli -a <REDIS_PASSWORD>

   (Default password in .env is typically 65QaKz4Hn2KN)

3. Publish a message to the channel:

   PUBLISH test-channel '{"info": "Hello from Redis"}'

Step 5: Verify Receipt

1. Check Postman.
2. You should instantaneously receive:

   {
     "action": "message",
     "topic": "test-channel",
     "snapshot": { "info": "Hello from Redis" }
   }