Faye-WebSocket

Common errors

• Not able to load the library in ESM context using named import.

  cause Attempting to use ES module `import { WebSocket } from 'faye-websocket';` syntax in an ESM context.
  fix Use CommonJS `require` syntax: `const WebSocket = require('faye-websocket');`. The library does not provide native ESM exports.

• Error during WebSocket handshake: 'Connection' header value is not 'Upgrade'

  cause The HTTP server or an intermediary proxy (like Nginx or Apache) is not correctly forwarding the 'Upgrade' header, or the server itself isn't set up to handle WebSocket upgrade requests.
  fix Ensure your HTTP server is configured to listen for and handle the `upgrade` event (e.g., `http.createServer().on('upgrade', ...)` in Node.js). If using a proxy, verify that it's configured to correctly proxy WebSocket upgrade requests, including the `Connection: Upgrade` and `Upgrade: websocket` headers.

• TypeError: WebSocket.Client is not a constructor (or similar when trying to instantiate client)

  cause Incorrectly importing the `Client` constructor, often trying a named import for a submodule that is actually a property of the main export.
  fix The `Client` class is a static property of the main `WebSocket` object. Import the main `WebSocket` object first, then access `WebSocket.Client`: `const WebSocket = require('faye-websocket'); const client = new WebSocket.Client(...);`.

Warnings

• breaking The license for `faye-websocket` changed from MIT to Apache 2.0 in version 0.11.3. Users should be aware of the different licensing terms, particularly if integrating into projects with specific license requirements.
  Fix: Review Apache 2.0 license terms for compatibility with your project's licensing and obligations.
• gotcha When using `wss://` (secure WebSockets), `faye-websocket` client (since 0.11.0) performs server certificate verification by default. This can cause connection failures if the server certificate is invalid, self-signed, or not trusted by the client's system root certificates.
  Fix: Ensure the WebSocket server presents a valid, trusted SSL/TLS certificate. For development or specific scenarios, you can optionally disable certificate verification via the `tls` option in `WebSocket.Client` constructor, though this is not recommended for production.
• gotcha Detecting client-side dropped WebSocket connections can be unreliable. Browsers might not immediately trigger `onclose` events, leading to a 'half-open' connection state where the server perceives the client as active.
  Fix: Implement application-level heartbeats (ping/pong) to actively monitor connection liveness. The `ws.ping()` method can be used on the server, and the client should respond with a pong. Alternatively, set a `ping` option during server-side WebSocket construction.
• breaking The library is essentially unmaintained since its last release in May 2021. It does not support native ESM imports directly, which may cause compatibility issues in modern Node.js projects that primarily use `import`/`export` syntax.
  Fix: Consider migrating to an actively maintained WebSocket library that provides native ESM support, such as `ws`. If continuing to use `faye-websocket`, explicitly use CommonJS `require()` statements.

Install

• npm install faye-websocket npm
• yarn add faye-websocket yarn
• pnpm add faye-websocket pnpm

Imports

• WebSocket
  wrong:

  import WebSocket from 'faye-websocket';

  correct:

  const WebSocket = require('faye-websocket');

  The library is primarily CommonJS. Direct ESM named imports are not officially supported and may lead to errors (see GitHub issue #82).
• WebSocket.Client
  wrong:

  import { Client } from 'faye-websocket';

  correct:

  const WebSocket = require('faye-websocket');
  const client = new WebSocket.Client('ws://example.com');

  The Client constructor is a static property of the main WebSocket export. ESM imports for this pattern are problematic.
• WebSocket.isWebSocket
  wrong:

  import { isWebSocket } from 'faye-websocket';

  correct:

  const WebSocket = require('faye-websocket');
  if (WebSocket.isWebSocket(request)) { /* ... */ }

  Used on the server side to determine if an incoming HTTP 'upgrade' request is a WebSocket handshake. It's a static method on the main export.

Quickstart

This example demonstrates both a basic Faye-WebSocket server that echoes messages and a client that connects to it, sends a message, and closes.

const WebSocket = require('faye-websocket');
const http = require('http');

// --- WebSocket Server --- 
const server = http.createServer();

server.on('upgrade', function(request, socket, body) {
  if (WebSocket.isWebSocket(request)) {
    const ws = new WebSocket(request, socket, body);

    ws.on('message', function(event) {
      console.log('Server received:', event.data);
      ws.send(`Echo: ${event.data}`);
    });

    ws.on('close', function(event) {
      console.log('Server closed:', event.code, event.reason);
      ws = null;
    });

    ws.on('error', function(event) {
      console.error('Server error:', event.message);
    });
  }
});

server.listen(8000, () => {
  console.log('WebSocket server listening on port 8000');
});

// --- WebSocket Client (connects to the server above) --- 
const clientWs = new WebSocket.Client('ws://localhost:8000/');

clientWs.on('open', function(event) {
  console.log('Client connected');
  clientWs.send('Hello from client!');
});

clientWs.on('message', function(event) {
  console.log('Client received:', event.data);
  if (event.data.includes('Echo')) {
    clientWs.close(1000, 'Finished');
  }
});

clientWs.on('close', function(event) {
  console.log('Client closed:', event.code, event.reason);
});

clientWs.on('error', function(event) {
  console.error('Client error:', event.message);
});