Skip to main content

​
Overview

The SolBid WebSocket server provides real-time updates for game events and bids. The server is built with the ws library and requires JWT authentication for all connections.

​
Connection URL

Connect to the WebSocket server at: 
ws://your-server-url:8080
The default port is 8080, but can be configured via the PORT environment variable.

​
Authentication flow

All WebSocket connections must authenticate immediately after connecting by sending a JWT token.

​
Initial authentication message

After establishing the WebSocket connection, send an authentication message: 
{
  "data": {
    "token": "your-jwt-token-here"
  }
}
​
data.token
string
required
Valid JWT token signed with NEXT_PUBLIC_SECRET
If no token is provided or the token is invalid, the connection will be closed immediately with an error message.

​
Authentication responses

Success: No response is sent on successful authentication. You can proceed to send messages. Failure: An error message is sent before the connection closes: 
{
  "type": "error",
  "data": {
    "message": "Token not found"
  }
}

​
Connection lifecycle

​
1. Establish connection

const ws = new WebSocket('ws://your-server-url:8080');

ws.onopen = () => {
  // Send authentication message
  ws.send(JSON.stringify({
    data: { token: 'your-jwt-token' }
  }));
};

​
2. Handle messages

After authentication, you’ll receive real-time game events: 
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('Received:', message);
};

​
3. Send messages

After successful authentication, you can send game-related messages: 
{
  "type": "create-game",
  "data": {
    "token": "your-jwt-token",
    // game creation data
  }
}
All client messages must include the JWT token in the data.token field for authentication.

​
4. Handle disconnection

ws.onclose = () => {
  console.log('Disconnected from server');
};
When a client disconnects, they are automatically removed from the server’s client list and will no longer receive broadcasts.

​
Error handling

The server sends error messages in the following format:
​
type
string
Always "error" for error messages
​
data
object
​
data.message
string
Human-readable error message

​
Common errors

  • Token not found - No token was provided in the message
  • Unauthorized - JWT token verification failed
  • Unknown message type: {type} - Invalid message type sent to server
  • Failed to process message - JSON parsing or other processing error
For authentication errors (Token not found, Unauthorized), the connection will be closed immediately after the error message is sent.

​
Connection management

The server maintains a singleton GameManager instance that tracks all connected clients. When you connect:
  1. Your WebSocket connection is added to the clients set
  2. You receive all future game broadcasts
  3. On disconnect, you’re automatically removed from the client list
The server logs connection counts to the console: New client connected. Total clients: {count}

Build docs developers (and LLMs) love

Get started for freeTalk to us