ws 8.21.0

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/ws@8.21.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/ws@8.21.0
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:56d0c609e9f7ae341ae3e14da6c7296cafdbb59ea354f7dda59af3dea4d655ca","constraints":{"executionContext":"node"},"contract":["WebSocketServer starts on an ephemeral port and accepts incoming WebSocket client connections","WebSocket clients and server exchange UTF-8 text and binary buffer messages bidirectionally","WebSocketServer broadcasts messages across all currently connected and open clients","WebSocket client ping emits corresponding pong heartbeat response from the server","WebSocket client and server close gracefully with specified status code and reason"],"goal":"verify pkg:npm/ws@8.21.0","kind":"HOW","packages":["pkg:npm/ws@8.21.0"],"schemaVersion":1},"contractCommand":["node","test/contract.js"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/ws@8.21.0"],"schemaVersion":1,"verifierAdapter":"node-typescript@1"}

{
  "name": "ws-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "ws-sample",
      "version": "1.0.0",
      "dependencies": {
        "ws": "8.21.0"
      }
    },
    "node_modules/ws": {
      "version": "8.21.0",
      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz",
      "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==",
      "license": "MIT",
      "engines": {
        "node": ">=10.0.0"
      },
      "peerDependencies": {
        "bufferutil": "^4.0.1",
        "utf-8-validate": ">=5.0.2"
      },
      "peerDependenciesMeta": {
        "bufferutil": {
          "optional": true
        },
        "utf-8-validate": {
          "optional": true
        }
      }
    }
  }
}

{
  "name": "ws-sample",
  "version": "1.0.0",
  "dependencies": {
    "ws": "8.21.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/ws@8.21.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/ws@8.21.0"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

const { WebSocket, WebSocketServer } = require('ws');

/**
 * Creates and starts a WebSocket server listening on an ephemeral port.
 *
 * @param {import('ws').ServerOptions} [options={}]
 * @returns {Promise<WebSocketServer>}
 */
function createWebSocketServer(options = {}) {
  return new Promise((resolve, reject) => {
    const server = new WebSocketServer({ port: 0, ...options }, () => {
      resolve(server);
    });
    server.once('error', reject);
  });
}

/**
 * Creates a WebSocket client and waits for it to open.
 *
 * @param {string} address
 * @param {import('ws').ClientOptions} [options]
 * @returns {Promise<WebSocket>}
 */
function createWebSocketClient(address, options) {
  return new Promise((resolve, reject) => {
    const ws = new WebSocket(address, options);
    ws.once('open', () => resolve(ws));
    ws.once('error', reject);
  });
}

/**
 * Broadcasts a message to all connected clients that are in OPEN state.
 *
 * @param {WebSocketServer} server
 * @param {any} data
 * @returns {number} number of clients messaged
 */
function broadcast(server, data) {
  let count = 0;
  for (const client of server.clients) {
    if (client.readyState === WebSocket.OPEN) {
      client.send(data);
      count++;
    }
  }
  return count;
}

/**
 * Closes a WebSocket connection gracefully.
 *
 * @param {WebSocket} ws
 * @param {number} [code]
 * @param {string} [reason]
 * @returns {Promise<{ code: number, reason: string }>}
 */
function closeWebSocket(ws, code, reason) {
  return new Promise((resolve) => {
    if (ws.readyState === WebSocket.CLOSED) {
      resolve({ code: 1000, reason: '' });
      return;
    }
    ws.once('close', (closeCode, closeReason) => {
      resolve({
        code: closeCode,
        reason: closeReason ? closeReason.toString() : '',
      });
    });
    ws.close(code, reason);
  });
}

/**
 * Closes a WebSocket server gracefully.
 *
 * @param {WebSocketServer} server
 * @returns {Promise<void>}
 */
function closeServer(server) {
  return new Promise((resolve, reject) => {
    server.close((err) => {
      if (err) reject(err);
      else resolve();
    });
  });
}

module.exports = {
  WebSocket,
  WebSocketServer,
  createWebSocketServer,
  createWebSocketClient,
  broadcast,
  closeWebSocket,
  closeServer,
};

const assert = require('node:assert/strict');
const {
  WebSocket,
  createWebSocketServer,
  createWebSocketClient,
  broadcast,
  closeWebSocket,
  closeServer,
} = require('../src/index.js');

async function main() {
  // Contract 1: WebSocketServer starts on an ephemeral port and accepts incoming WebSocket client connections
  {
    const server = await createWebSocketServer();
    const port = server.address().port;
    assert.ok(typeof port === 'number' && port > 0, 'Server should listen on a valid positive port');

    const connectedPromise = new Promise(resolve => {
      server.once('connection', (socket, req) => {
        resolve({ socket, url: req.url });
      });
    });

    const client = await createWebSocketClient(`ws://127.0.0.1:${port}/test-path`);
    assert.strictEqual(client.readyState, WebSocket.OPEN, 'Client readyState should be OPEN');

    const { socket: serverSocket, url } = await connectedPromise;
    assert.strictEqual(serverSocket.readyState, WebSocket.OPEN, 'Server socket readyState should be OPEN');
    assert.strictEqual(url, '/test-path', 'Request URL path should match');

    await closeWebSocket(client);
    await closeWebSocket(serverSocket);
    await closeServer(server);
  }

  // Contract 2: WebSocket clients and server exchange UTF-8 text and binary buffer messages bidirectionally
  {
    const server = await createWebSocketServer();
    const port = server.address().port;

    let serverSocket;
    const connected = new Promise(resolve => {
      server.once('connection', ws => {
        serverSocket = ws;
        resolve();
      });
    });

    const client = await createWebSocketClient(`ws://127.0.0.1:${port}`);
    await connected;

    // Test text message from client to server
    const serverReceivedText = new Promise((resolve) => {
      serverSocket.once('message', (data, isBinary) => {
        resolve({ data: data.toString(), isBinary });
      });
    });

    client.send('ping-message');
    const textResult = await serverReceivedText;
    assert.strictEqual(textResult.data, 'ping-message');
    assert.strictEqual(textResult.isBinary, false);

    // Test binary message from server to client
    const clientReceivedBinary = new Promise((resolve) => {
      client.once('message', (data, isBinary) => {
        resolve({ data: Buffer.from(data), isBinary });
      });
    });

    const binaryPayload = Buffer.from([0x01, 0x02, 0x03, 0x04, 0xff]);
    serverSocket.send(binaryPayload);
    const binaryResult = await clientReceivedBinary;
    assert.deepStrictEqual(binaryResult.data, binaryPayload);
    assert.strictEqual(binaryResult.isBinary, true);

    await closeWebSocket(client);
    await closeWebSocket(serverSocket);
    await closeServer(server);
  }

  // Contract 3: WebSocketServer broadcasts messages across all currently connected and open clients
  {
    const server = await createWebSocketServer();
    const port = server.address().port;

    const client1 = await createWebSocketClient(`ws://127.0.0.1:${port}`);
    const client2 = await createWebSocketClient(`ws://127.0.0.1:${port}`);
    const client3 = await createWebSocketClient(`ws://127.0.0.1:${port}`);

    while (server.clients.size < 3) {
      await new Promise(r => setTimeout(r, 5));
    }
    assert.strictEqual(server.clients.size, 3);

    const msg1Promise = new Promise(resolve => client1.once('message', data => resolve(data.toString())));
    const msg2Promise = new Promise(resolve => client2.once('message', data => resolve(data.toString())));
    const msg3Promise = new Promise(resolve => client3.once('message', data => resolve(data.toString())));

    const count = broadcast(server, 'broadcast-notification');
    assert.strictEqual(count, 3, 'Should broadcast to all 3 clients');

    const [msg1, msg2, msg3] = await Promise.all([msg1Promise, msg2Promise, msg3Promise]);
    assert.strictEqual(msg1, 'broadcast-notification');
    assert.strictEqual(msg2, 'broadcast-notification');
    assert.strictEqual(msg3, 'broadcast-notification');

    await closeWebSocket(client1);
    await closeWebSocket(client2);
    await closeWebSocket(client3);
    await closeServer(server);
  }

  // Contract 4: WebSocket client ping emits corresponding pong heartbeat response from the server
  {
    const server = await createWebSocketServer();
    const port = server.address().port;

    const client = await createWebSocketClient(`ws://127.0.0.1:${port}`);

    const pongReceived = new Promise((resolve) => {
      client.once('pong', (data) => {
        resolve(data.toString());
      });
    });

    client.ping('heartbeat-payload');
    const pongData = await pongReceived;
    assert.strictEqual(pongData, 'heartbeat-payload');

    await closeWebSocket(client);
    await closeServer(server);
  }

  // Contract 5: WebSocket client and server close gracefully with specified status code and reason
  {
    const server = await createWebSocketServer();
    const port = server.address().port;

    let serverSocket;
    const connected = new Promise(resolve => {
      server.once('connection', ws => {
        serverSocket = ws;
        resolve();
      });
    });

    const client = await createWebSocketClient(`ws://127.0.0.1:${port}`);
    await connected;

    const serverClosePromise = new Promise((resolve) => {
      serverSocket.once('close', (code, reason) => {
        resolve({ code, reason: reason.toString() });
      });
    });

    const clientCloseResult = await closeWebSocket(client, 4001, 'custom-closure-reason');
    assert.strictEqual(clientCloseResult.code, 4001);
    assert.strictEqual(clientCloseResult.reason, 'custom-closure-reason');

    const serverCloseResult = await serverClosePromise;
    assert.strictEqual(serverCloseResult.code, 4001);
    assert.strictEqual(serverCloseResult.reason, 'custom-closure-reason');

    assert.strictEqual(client.readyState, WebSocket.CLOSED);
    assert.strictEqual(serverSocket.readyState, WebSocket.CLOSED);

    await closeServer(server);
  }

  console.log('All pkg:npm/ws@8.21.0 contracts passed successfully.');
}

main().catch(err => {
  console.error(err);
  process.exit(1);
});