Postconditions: what we check

• WebSocket · missing-error-handler

  error
  WhenWebSocket instance created without error event handler
  ThrowsEmits 'error' event that crashes process if not handled
  Required handlingCaller MUST attach error event handler immediately after creating WebSocket. Without error handler, unhandled 'error' events crash the entire Node.js process. CRITICAL: This is the #1 production bug (60% of codebases). Always add: ws.on('error', (error) => { handle_error(error); })
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• WebSocket · connection-error

  error
  WhenConnection fails (network error, DNS failure, timeout, handshake failure)
  ThrowsEmits 'error' event with Error object
  Required handlingCaller MUST handle connection errors via error event handler. Common errors: ECONNREFUSED, ENOTFOUND, ETIMEDOUT, ECONNRESET. Error event is emitted before close event. Implement reconnection logic with exponential backoff.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• WebSocket · protocol-violation

  error
  WhenWebSocket protocol violation (invalid frames, reserved bits set)
  ThrowsEmits 'error' event and closes connection with code 1002
  Required handlingCaller MUST handle protocol errors. Usually indicates server or client implementation bug. Close code 1002 means protocol error. DO NOT RETRY - fix implementation.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• WebSocket · missing-close-handler

  warning
  WhenConnection closes but no close event handler attached
  ThrowsEmits 'close' event with code and reason
  Required handlingCaller SHOULD handle close events for cleanup and reconnection. Close codes: 1000 (normal), 1006 (abnormal), 1009 (too big), etc. Code 1006 indicates abnormal close (connection lost) - SHOULD reconnect. Code 1000 indicates normal close - DO NOT reconnect. Remove event listeners in close handler to prevent memory leaks.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• send · send-before-open

  error
  Whensend() called before connection is open (readyState !== OPEN)
  ThrowsError: WebSocket is not open: readyState X (CONNECTING|CLOSING|CLOSED)
  Required handlingCaller MUST check readyState before sending OR send only in open event. VERY COMMON BUG (50% of codebases): Sending immediately after new WebSocket(). CORRECT: ws.on('open', () => { ws.send(data); }) CORRECT: if (ws.readyState === WebSocket.OPEN) { ws.send(data); } WRONG: ws.send(data); // Immediately after new WebSocket() - crashes!
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• send · backpressure-exceeded

  warning
  WhenSend buffer full (bufferedAmount exceeds threshold)
  ThrowsDoes NOT throw, but causes memory exhaustion and OOM crashes
  Required handlingCaller MUST check bufferedAmount before sending in high-throughput scenarios. If bufferedAmount > threshold (e.g., 1 MB), pause sending. Wait for drain event before resuming. WITHOUT backpressure handling: memory leak, OOM crash. Example: if (ws.bufferedAmount > 1024*1024) { pause_sending(); }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• send · message-too-large

  error
  WhenMessage size exceeds maxPayload
  ThrowsRangeError: Invalid WebSocket frame: payload length > maxPayload
  Required handlingCaller MUST validate message size before sending. Configure maxPayload appropriately (default 100 MiB may be too high). Connection closes with code 1009 (message too big). Split large messages into chunks or use chunking protocol.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• WebSocketServer · server-error

  error
  WhenServer error (port in use, permission denied, etc.)
  ThrowsEmits 'error' event on server
  Required handlingCaller MUST attach error event handler to server. Common errors: EADDRINUSE (port in use), EACCES (permission denied). Without handler, errors crash the process.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8]
• WebSocketServer · client-error-before-connection

  warning
  WhenClient error before connection established (handshake failure)
  ThrowsEmits 'wsClientError' event on server
  Required handlingCaller SHOULD handle wsClientError for errors during handshake. Prevents crashes from malformed upgrade requests. This event is emitted BEFORE connection event.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9]
• WebSocketServer · no-origin-validation

  warning
  WhenServer accepts connections without origin validation
  ThrowsDoes NOT throw, but allows cross-origin attacks
  Required handlingCaller MUST validate origin in production via verifyClient callback. WITHOUT validation: any website can connect to your WebSocket server. SECURITY RISK: Cross-Site WebSocket Hijacking (CSWSH). Example: new WebSocketServer({ verifyClient: (info) => { return allowedOrigins.includes(info.origin); } });
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[10]
• close · close-emits-event

  warning
  WhenConnection closes (gracefully or abnormally)
  ThrowsEmits 'close' event with code and reason
  Required handlingCaller SHOULD handle close event for cleanup. Close codes indicate reason: 1000 (normal), 1006 (abnormal), etc. Code 1006 means connection lost without close frame (network issue). Code 1000 means clean shutdown. Code 1009 means message too big. Remove event listeners to prevent memory leaks.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• ping · ping-before-open

  error
  Whenping() is called while the WebSocket is still in CONNECTING state (readyState === WebSocket.CONNECTING, i.e., before the 'open' event fires).
  ThrowsError: WebSocket is not open: readyState 0 (CONNECTING)
  Required handlingCaller MUST check readyState before calling ping(), or only send pings after the 'open' event. Heartbeat intervals MUST start in the 'open' event handler, NOT immediately after new WebSocket(). CORRECT heartbeat pattern: ws.on('open', () => { const heartbeat = setInterval(() => { if (ws.readyState === WebSocket.OPEN) ws.ping(); }, 30000); ws.on('close', () => clearInterval(heartbeat)); }); WRONG (crashes if called before connection is established): ws.ping(); // Throws immediately
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[11][12]
• ping · ping-callback-receives-error

  warning
  Whenping() is called when connection is CLOSING or CLOSED and a callback is provided. The callback receives an error but no exception is thrown synchronously.
  ThrowsNo synchronous throw. If a callback is provided, it receives: Error: WebSocket is not open: readyState X (CLOSING|CLOSED)
  Required handlingIf using ping() with a callback for error detection, the callback MUST check for error. Heartbeat implementations that check for errors in the ping callback should handle this gracefully rather than logging/crashing. The more reliable pattern is to check readyState === WebSocket.OPEN before pinging.
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[11]
• handleUpgrade · handleupgrade-missing-wsclienterror-handler

  warning
  WhenhandleUpgrade() receives an invalid upgrade request (missing or invalid Sec-WebSocket-Key, Sec-WebSocket-Version, Upgrade header, or non-GET method). Server has no 'wsClientError' event listener attached.
  ThrowsNo throw. Without a wsClientError listener, ws calls abortHandshake() directly and closes the socket with an HTTP error response (400/405). The upgrade request fails silently from the server application's perspective — no event is emitted, no log is produced.
  Required handlingWhen using noServer mode, ALWAYS attach a wsClientError handler: wss.on('wsClientError', (error, socket, request) => { socket.write('HTTP/1.1 400 Bad Request\r\n\r\n'); socket.destroy(); }); The wsClientError listener is responsible for closing the socket. Without it, malformed upgrade requests are silently dropped with no observability — making debugging impossible in production. Critical: The socket MUST be explicitly closed in the wsClientError handler. ws does NOT close it automatically when the event is emitted.
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[12][13]
• handleUpgrade · handleupgrade-called-in-non-noserver-mode

  error
  WhenhandleUpgrade() is called manually when the server was NOT created with noServer: true — i.e., ws is already handling upgrades automatically via its internal server event listeners.
  ThrowsThe socket may be handled twice, leading to the completeUpgrade() call throwing Error: "websocket already set on socket" or connection state corruption. Behavior is undefined and may cause hard-to-debug connection failures.
  Required handlinghandleUpgrade() MUST only be called when using noServer: true mode. When passing a server option or a port option, ws handles upgrades automatically. Do NOT call handleUpgrade() in that case. noServer mode example (Next.js API route pattern): const wss = new WebSocketServer({ noServer: true }); server.on('upgrade', (req, socket, head) => { wss.handleUpgrade(req, socket, head, (ws) => { wss.emit('connection', ws, req); }); });
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12][14]
• WebSocketServer.close · server-close-already-stopped

  warning
  WhenWebSocketServer.close() is called on a server that is already closed (either never started, or close() already called and completed).
  ThrowsNo synchronous throw. The callback (if provided) receives: Error: The server is not running
  Required handlingAlways check server state before calling close(), or handle the error in the callback: wss.close((err) => { if (err) { // Server was already stopped — safe to ignore in cleanup code if (err.message !== 'The server is not running') throw err; } }); This error is benign in shutdown/cleanup flows where close() may be called defensively. Do NOT ignore all errors in the callback — only the 'not running' case.
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[13][12]
• WebSocketServer.close · server-close-existing-connections-not-terminated

  warning
  WhenWebSocketServer.close() is called while clients are still connected. Existing WebSocket connections continue to work — only new connections are rejected. The server's close event fires before all connections drain.
  ThrowsDoes NOT throw. Existing connections continue unaffected.
  Required handlingIf graceful shutdown is required, terminate all active connections before or after calling close(): wss.clients.forEach((client) => { if (client.readyState === WebSocket.OPEN) { client.close(1001, 'Server shutting down'); } }); wss.close(() => { process.exit(0); }); Without explicit termination, long-lived connections keep the server process alive indefinitely after close() returns.
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[12]
• pong · pong-before-open

  error
  Whenpong() is called while the WebSocket is still in CONNECTING state (readyState === WebSocket.CONNECTING, i.e., before the 'open' event fires).
  ThrowsError: WebSocket is not open: readyState 0 (CONNECTING)
  Required handlingCaller MUST check readyState before calling pong(), or only send pongs after the 'open' event. Unsolicited-pong keepalive intervals MUST start in the 'open' event handler, NOT immediately after new WebSocket(). CORRECT pattern: ws.on('open', () => { const keepalive = setInterval(() => { if (ws.readyState === WebSocket.OPEN) ws.pong(); }, 30000); ws.on('close', () => clearInterval(keepalive)); }); WRONG (crashes if called before connection is established): ws.pong(); // Throws synchronously when readyState === CONNECTING
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[11][12]
• pong · pong-callback-receives-error

  warning
  Whenpong() is called when connection is CLOSING or CLOSED and a callback is provided. The callback receives an error but no exception is thrown synchronously.
  ThrowsNo synchronous throw. If a callback is provided, it receives: Error: WebSocket is not open: readyState X (CLOSING|CLOSED)
  Required handlingIf using pong() with a callback for error detection, the callback MUST check for error. The more reliable pattern is to check readyState === WebSocket.OPEN before pong()-ing. Silent callback errors in keepalive logic cause zombie-connection symptoms.
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[11]
• terminate · terminate-during-connecting-silent

  warning
  Whenterminate() is called while the WebSocket is in CONNECTING state. The handshake is aborted; no 'open' event is emitted; only a 'close' event fires with code 1006 (abnormal closure).
  ThrowsDoes NOT throw. The connection is silently aborted — promise-wrapped connect helpers that only resolve on 'open' will hang indefinitely if they do not also reject on 'close' or 'error' events.
  Required handlingConnect helpers that wrap new WebSocket() in a Promise MUST register handlers for BOTH 'open' (resolve) AND 'close'/'error' (reject) so a mid-connect terminate() is observable to the caller. CORRECT promise-wrapped connect: const ws = new WebSocket(url); await new Promise((resolve, reject) => { ws.once('open', resolve); ws.once('error', reject); ws.once('close', () => reject(new Error('closed before open'))); }); WRONG (hangs forever if terminate() called during CONNECTING): await new Promise(resolve => ws.once('open', resolve));
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[11][12]
• terminate · terminate-on-closed-no-op

  info
  Whenterminate() is called when the WebSocket is already in CLOSED state. The call is a silent no-op — no 'close' event is re-emitted, no callback is invoked, no error surfaces.
  ThrowsDoes NOT throw and produces no observable side effect.
  Required handlingCleanup logic MUST NOT rely on terminate() to trigger a 'close' event if the connection may already be CLOSED. Always perform cleanup (clearing intervals, removing entries from connection registries) at the 'close' event itself or in finally blocks, not after terminate(). CORRECT cleanup pattern: ws.on('close', () => { connections.delete(ws); }); ws.terminate(); // may be no-op; cleanup runs from 'close' handler if any WRONG (cleanup never runs if already closed): ws.terminate(); connections.delete(ws); // OK actually but if cleanup runs in close handler, redundant // worse: relying on a side effect of terminate() to fire 'close'
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[11]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.

[CONNECTING (0)] - Initial state after new WebSocket()
        ↓
    'open' event
        ↓
    [OPEN (1)] - Can send/receive messages
        ↓
    .close() called
        ↓
  [CLOSING (2)] - Close frame sent, waiting for response
        ↓
    Close frame received
        ↓
    [CLOSED (3)] - Connection terminated
        ↓
    'close' event (with code & reason)