What Happens When the CloddsBot WebSocket Server Reaches Capacity

When the CloddsBot WebSocket server reaches the configured maxClients limit, it immediately rejects new connection attempts by closing the socket with WebSocket close code 1013 ("Server at capacity") while leaving existing connections untouched.

CloddsBot is an open-source bot framework maintained in the alsk1992/CloddsBot repository that enforces strict connection limits to prevent resource exhaustion. When simultaneous client connections hit the threshold defined in the gateway configuration, the server implements a clean rejection protocol that protects active sessions. Understanding this behavior is essential for operators scaling their deployments and developers building resilient client applications.

How CloddsBot Enforces the Connection Limit

The capacity management system relies on a simple but effective counter check performed at the edge of the connection lifecycle. The server maintains an internal clients map tracking active sessions and compares its size against the maxClients configuration parameter on every new connection attempt.

The maxClients Configuration

The connection limit is controlled through the GatewayConfig interface, typically defined alongside other gateway settings. This value represents the maximum number of concurrent WebSocket clients the server will accept before entering a rejection state. Operators can configure this threshold when initializing the gateway server to match their infrastructure constraints.

Capacity Check in handleConnection

According to the source code in src/gateway/index.ts, the handleConnection method performs the capacity validation immediately upon receiving a new WebSocket upgrade request. Located at lines 73-76, the implementation checks the current client count before proceeding with session initialization:

// src/gateway/index.ts
private handleConnection(socket: WebSocket, request: http.IncomingMessage): void {
  // Reject if we already have the maximum allowed clients
  if (this.clients.size >= this.config.maxClients!) {
    socket.close(1013, 'Server at capacity');
    return;
  }

  // …normal connection setup follows…
}

If the condition evaluates to true, the server invokes socket.close() with code 1013 and reason "Server at capacity", then returns immediately. This prevents the client from being added to the internal clients map, ensuring the active session pool never exceeds the configured maximum. The event is typically logged via logger.debug or logger.warn for monitoring purposes.

WebSocket Close Code 1013 and Client Rejection

When capacity is reached, CloddsBot utilizes WebSocket close code 1013, which the specification defines as "Service Restart" or "Try again later." This code signals to clients that the server is temporarily unavailable due to load conditions, distinguishing capacity issues from authentication failures or protocol errors.

Existing connections remain completely unaffected by the rejection of new clients. The server does not implement load shedding or forcible disconnection of active sessions when the threshold is reached; only the excess connection attempt is terminated. This isolation ensures stability for currently connected users while the server operates at full capacity.

Configuring the Server-Side Connection Limit

To implement capacity constraints in your CloddsBot deployment, pass the maxClients option when creating the gateway server. The following example establishes a limit of 100 concurrent WebSocket connections:

import { createGatewayServer } from './gateway';

const gateway = createGatewayServer({
  maxClients: 100,               // ← limit of concurrent connections
  // …other config options…
});

await gateway.start();

Setting this value requires balancing infrastructure resources against expected user load. The maxClients parameter is consumed by the WebSocketServer initialization logic in src/web/index.ts and subsequently enforced by the gateway's connection handler.

##Handling Server-at-Capacity Errors on the Client

Client applications connecting to CloddsBot should implement specific error handling for close code 1013 to provide appropriate user feedback or retry logic. The following implementation demonstrates detecting the capacity rejection:

import WebSocket from 'ws';

const ws = new WebSocket('ws://your-host.com/chat');

ws.on('close', (code, reason) => {
  if (code === 1013) {
    console.error('Connection refused: server is at capacity');
    // Optional: implement exponential backoff retry or user notification
  } else {
    console.log(`Closed with code ${code}: ${reason}`);
  }
});

Detecting this specific close code allows client applications to distinguish between temporary capacity issues and permanent connection failures, enabling smarter reconnection strategies such as delayed retries or queueing mechanisms.

Summary

• Connection Limit: CloddsBot caps concurrent WebSocket connections using the maxClients configuration parameter defined in the gateway settings.
• Rejection Mechanism: New connections are rejected with WebSocket close code 1013 and the reason "Server at capacity" when the limit is reached.
• Source Location: The capacity check occurs in src/gateway/index.ts within the handleConnection method at lines 73-76.
• Session Preservation: Existing connections remain active and are never terminated to accommodate new clients; only incoming requests are refused.
• Client Handling: Applications should listen for close code 1013 to implement appropriate backoff strategies when the server is at capacity.

Frequently Asked Questions

What WebSocket close code does CloddsBot use when at capacity?

CloddsBot uses close code 1013 ("Service Restart" or "Try again later") when rejecting connections due to capacity limits. This standardized code indicates that the server is temporarily overloaded and the client should retry the connection later, distinguishing it from permanent errors like authentication failures.

Does CloddsBot drop existing connections when the limit is reached?

No. The server does not drop existing connections when reaching the maxClients threshold. The capacity check in src/gateway/index.ts only affects new incoming connection attempts. Active clients maintained in the internal clients map continue their sessions normally while new requests are rejected until existing connections close and free up slots.

How do I configure the maximum number of clients in CloddsBot?

Set the maxClients property in the gateway configuration object passed to createGatewayServer(). This value is defined in the GatewayConfig interface and enforced by the handleConnection method. The configuration is typically specified alongside other gateway options like port and authentication settings.

Where is the capacity check implemented in the CloddsBot source code?

The capacity check is implemented in src/gateway/index.ts at the beginning of the handleConnection method (lines 73-76). This location contains the conditional logic comparing this.clients.size against this.config.maxClients, along with the immediate socket closure procedure for excess connections.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}