or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

eventsource.mdindex.mdwebsocket-client.mdwebsocket-server.md
tile.json

tessl/npm-faye-websocket

Standards-compliant WebSocket server and client implementation for Node.js with EventSource support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/faye-websocket@0.11.x

To install, run

npx @tessl/cli install tessl/npm-faye-websocket@0.11.0

index.mddocs/

Faye WebSocket

Faye WebSocket is a standards-compliant WebSocket implementation for Node.js that provides both server and client capabilities. It offers WebSocket server handling, client connections with proxy support, and EventSource (server-sent events) functionality without additional abstractions beyond the standard WebSocket API.

Package Information

  • Package Name: faye-websocket
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install faye-websocket

Core Imports

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

For individual components:

const WebSocket = require('faye-websocket');
const Client = WebSocket.Client;
const EventSource = WebSocket.EventSource;

Basic Usage

WebSocket Server

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

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) {
      ws.send(event.data);
    });
    
    ws.on('close', function(event) {
      console.log('close', event.code, event.reason);
    });
  }
});

server.listen(8000);

WebSocket Client

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

ws.on('open', function(event) {
  ws.send('Hello, world!');
});

ws.on('message', function(event) {
  console.log('message', event.data);
});

Architecture

Faye WebSocket is built around several key components:

  • WebSocket Server: Handles HTTP upgrade requests and creates WebSocket connections
  • WebSocket Client: Establishes outbound WebSocket connections with full protocol support
  • EventSource: Implements server-sent events for unidirectional server-to-client streaming
  • Stream Interface: All WebSocket objects are Node.js duplex streams
  • Event System: DOM-compatible event handling with EventTarget interface

Capabilities

WebSocket Server

Server-side WebSocket implementation that handles HTTP upgrade requests and manages WebSocket connections. Supports protocol negotiation, extensions, and standard WebSocket events.

const WebSocket = require('faye-websocket');
const ws = new WebSocket(request, socket, body, protocols, options);

// Static methods
WebSocket.isWebSocket(request); // boolean
WebSocket.validateOptions(options, validKeys); // void

WebSocket Server

WebSocket Client

Client-side WebSocket implementation with support for secure connections, proxy servers, and all standard WebSocket features. Includes handshake inspection and connection management.

const Client = WebSocket.Client;
const ws = new Client(url, protocols, options);

// Properties available after connection
ws.headers;    // Object - response headers
ws.statusCode; // Number - HTTP status code

WebSocket Client

EventSource (Server-Sent Events)

Server-sent events implementation for unidirectional streaming from server to client. Supports event types, IDs, retry configuration, and automatic reconnection.

const EventSource = WebSocket.EventSource;
const es = new EventSource(request, response, options);

// Static methods
EventSource.isEventSource(request); // boolean

// Properties
es.url;         // String - request URL
es.lastEventId; // String - last event ID

EventSource

Types

Connection States

// WebSocket ready states (also available as constants)
const CONNECTING = 0; // Connection being established
const OPEN = 1;       // Connection open and ready
const CLOSING = 2;    // Connection closing
const CLOSED = 3;     // Connection closed

Event Objects

// Event object structure for WebSocket events
{
  type: 'open' | 'message' | 'error' | 'close',
  data: string | Buffer,     // for message events
  code: number,              // for close events
  reason: string,            // for close events
  message: string            // for error events
}

Configuration Options

// Common options for WebSocket and Client
{
  extensions: Array,    // WebSocket extensions
  headers: Object,      // Custom HTTP headers
  maxLength: number,    // Max frame size (default: 2^26 - 1)
  ping: number         // Ping interval in seconds
}

// Client-specific options
{
  proxy: {
    origin: string,     // Proxy URL
    headers: Object,    // Proxy headers
    tls: Object        // Proxy TLS settings
  },
  net: Object,         // Network connection options
  tls: Object,         // TLS connection options
  ca: string | Buffer  // Certificate authority (legacy)
}

// EventSource options
{
  headers: Object,     // Custom response headers
  retry: number,       // Client reconnect interval (seconds)
  ping: number        // Server ping interval (seconds)
}