WebSocket Connection States & Buffer Management

Technical Deep Dive & Specifications

The Four readyState Constants

The W3C/WHATWG WebSocket standard defines four static numerical constants on the WebSocket constructor and its instances:

interface WebSocket {
  readonly CONNECTING: 0;
  readonly OPEN: 1;
  readonly CLOSING: 2;
  readonly CLOSED: 3;

  readonly readyState: 0 | 1 | 2 | 3;
}

+-------------------------------------------------------------------------------+
|                        WEBSOCKET STATE TRANSITION GRAPH                       |
+-------------------------------------------------------------------------------+

                       new WebSocket('wss://...')
                                    |
                                    v
                     +----------------------------+
                     |  0: WebSocket.CONNECTING   |
                     +----------------------------+
                               /        \
                    (Success) /          \ (Failure / Cancel)
                             v            v
             +--------------------+   +-------------------------+
             | 1: WebSocket.OPEN  |   |                         |
             +--------------------+   |                         |
                       |              |                         |
         (socket.close() / Server)    |                         |
                       |              |                         |
                       v              |                         |
             +--------------------+   |                         |
             | 2: WebSocket.CLOSING|  |                         |
             +--------------------+   |                         |
                       \              /                         |
                        \            /                          |
                         v          v                           |
                     +----------------------------+             |
                     |   3: WebSocket.CLOSED      |<------------+
                     +----------------------------+

State Definitions Matrix

The bufferedAmount Property

socket.bufferedAmount is a read-only property returning the number of bytes of data that have been queued using send() calls but not yet transmitted to the operating system's network layer.

const socket = new WebSocket('wss://example.com/feed');

socket.addEventListener('open', () => {
  console.log('Initial bufferedAmount:', socket.bufferedAmount); // 0 bytes
  
  const heavyPayload = new Uint8Array(1024 * 1024); // 1 MB
  socket.send(heavyPayload);
  
  console.log('After send():', socket.bufferedAmount); // 1048576 (1 MB queued)
});

Key Characteristics of bufferedAmount:

1. Immediate Increment: Increases synchronously the moment socket.send() is executed.
2. Asynchronous Drainage: Decreases asynchronously as the browser's background networking thread successfully flushes bytes into the OS TCP write buffer.
3. No Native drain Event: Unlike Node.js writable streams, the browser WebSocket API does not provide a drain or bufferempty event. Developers must poll bufferedAmount or schedule checks using requestAnimationFrame or setInterval.

Designing Backpressure & Flow Control

When transmitting high-frequency real-time data (such as live mouse pointer coordinates, 60 FPS canvas video frames, or audio samples), sending without rate checks can consume gigabytes of browser RAM on slow 3G/4G connections.

Backpressure Strategies:

+-----------------------------------------------------------------------------------+
|                        FLOW CONTROL & DROPPING STRATEGIES                         |
+-----------------------------------------------------------------------------------+

1. LATEST-VALUE ONLY (Lossy - e.g. Mouse Pointers, Sensor Readings):
   [ Update 1 ] -> Overwrites -> [ Update 2 ] -> Overwrites -> [ Update 3 ]
   Only [ Update 3 ] is sent when bufferedAmount < HIGH_WATER_MARK.

2. ADAPTIVE THROTTLING (Lossless - e.g. Chat Messages, Financial Trades):
   Pause dispatching and delay outbound queue processing via setTimeout/RAF.

The Safe Sender Pattern:

class SafeWebSocket {
  constructor(url) {
    this.url = url;
    this.socket = new WebSocket(url);
    this.outboundQueue = [];
    this.HIGH_WATER_MARK = 64 * 1024; // 64 KB threshold

    this.socket.addEventListener('open', () => this.flushQueue());
  }

  send(data) {
    // 1. Guard against unestablished connection
    if (this.socket.readyState === WebSocket.CONNECTING) {
      this.outboundQueue.push(data);
      return false;
    }

    // 2. Guard against closed connection
    if (this.socket.readyState !== WebSocket.OPEN) {
      console.warn('Cannot send: socket is CLOSING or CLOSED');
      return false;
    }

    // 3. Guard against backpressure saturation
    if (this.socket.bufferedAmount > this.HIGH_WATER_MARK) {
      console.warn(`Backpressure limit exceeded (${this.socket.bufferedAmount} bytes). Throttling...`);
      this.outboundQueue.push(data);
      this.scheduleDrainCheck();
      return false;
    }

    // 4. Safe to transmit
    this.socket.send(data);
    return true;
  }

  flushQueue() {
    while (this.outboundQueue.length > 0 && this.socket.readyState === WebSocket.OPEN) {
      if (this.socket.bufferedAmount > this.HIGH_WATER_MARK) {
        this.scheduleDrainCheck();
        break;
      }
      const data = this.outboundQueue.shift();
      this.socket.send(data);
    }
  }

  scheduleDrainCheck() {
    if (this.drainTimer) return;
    this.drainTimer = setInterval(() => {
      if (this.socket.bufferedAmount < (this.HIGH_WATER_MARK / 2)) {
        clearInterval(this.drainTimer);
        this.drainTimer = null;
        this.flushQueue();
      }
    }, 50);
  }
}

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Lines 73–87 (updateBufferUI): Calculates capacity percentages against MAX_BUFFER (64KB) and shifts UI colors dynamically from green (safe) to orange (warning) to red (backpressure drop threshold).
• Lines 89–102 (startDrainWorker): Simulates the asynchronous kernel TCP buffer drainage, decrementing simulatedBufferedAmount in chunks to mirror real network behavior.
• Lines 104–113 (dispatchFrame): Evaluates capacity before queuing. If the high-water mark is exceeded, it prevents memory blowout by rejecting the frame and raising a backpressure event.

Expected Browser Render Output

WebSocket Buffer Meter & Backpressure Controller
Client Buffered Amount (Queue): 32,768 / 65,536 Bytes
[████████████████████░░░░░░░░░░░░░░░░░░░░] 50% Capacity (32768 B)

[Send 4 KB Frame] [Flood 32 KB Stream] [Clear / Drain Buffer]

Transmission Telemetry Log
[21.100] Dispatched 4096B payload. Current buffer: 4096B
[21.115] Dispatched 4096B payload. Current buffer: 8192B
[21.130] Dispatched 4096B payload. Current buffer: 12288B
[21.145] Dispatched 4096B payload. Current buffer: 16384B
[21.850] Buffer completely drained to network.