# What Happens When the CloddsBot WebSocket Server Reaches Capacity

> Discover what happens when the CloddsBot WebSocket server reaches capacity. Learn how it rejects new connections with close code 1013, ensuring existing clients remain unaffected.

- Repository: [AL/CloddsBot](https://github.com/alsk1992/CloddsBot)
- Tags: internals
- Published: 2026-09-13

---

**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`](https://github.com/alsk1992/CloddsBot/blob/main/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:

```typescript
// 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:

```typescript
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`](https://github.com/alsk1992/CloddsBot/blob/main/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:

```typescript
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`](https://github.com/alsk1992/CloddsBot/blob/main/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`](https://github.com/alsk1992/CloddsBot/blob/main/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`](https://github.com/alsk1992/CloddsBot/blob/main/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.