or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdserver.mdsocket.mdtransports.mdtypes.md
tile.json

index.mddocs/

Engine.IO

Engine.IO is a transport-based cross-browser/cross-device bidirectional communication layer that serves as the foundation for Socket.IO. It provides maximum reliability by establishing a long-polling connection first, then upgrading to better transports like WebSocket when available, handling connection management, transport switching, message queuing, and protocol negotiation.

Package Information

  • Package Name: engine.io
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install engine.io

Core Imports

import { Server, Socket, listen, attach, uServer, Transport, parser, protocol } from "engine.io";

For CommonJS:

const { Server, Socket, listen, attach, uServer, Transport, parser, protocol } = require("engine.io");

Basic Usage

Creating a Standalone Server

import { listen } from "engine.io";

// Create server listening on port 3000
const server = listen(3000);

server.on('connection', (socket) => {
  console.log('Client connected:', socket.id);
  
  // Send messages
  socket.send('Hello client!');
  socket.send(Buffer.from([0, 1, 2, 3])); // binary data
  
  // Handle messages
  socket.on('message', (data) => {
    console.log('Received:', data);
  });
  
  socket.on('close', () => {
    console.log('Client disconnected:', socket.id);
  });
});

Attaching to Existing HTTP Server

import { createServer } from "http";
import { attach } from "engine.io";

const httpServer = createServer().listen(3000);
const server = attach(httpServer);

server.on('connection', (socket) => {
  socket.on('message', (data) => {
    socket.send(`Echo: ${data}`);
  });
});

Manual Server Setup

import { Server } from "engine.io";
import { createServer } from "http";

const server = new Server({
  pingTimeout: 20000,
  pingInterval: 25000,
  transports: ['polling', 'websocket']
});

const httpServer = createServer();
server.attach(httpServer, { path: '/engine.io' });

httpServer.listen(3000);

Architecture

Engine.IO is built around several key components:

  • Server Management: Core Server class that manages client connections and handles HTTP/WebSocket upgrades
  • Client Connections: Each client connection is represented by a Socket instance with bidirectional communication
  • Transport Layer: Pluggable transport system supporting polling (XHR/JSONP) and WebSocket protocols
  • Protocol Management: Automatic transport negotiation and upgrade handling for optimal connectivity
  • Message Processing: Binary and text message support with automatic encoding/decoding

Capabilities

Server Management

Core server functionality for creating and managing realtime connections with automatic transport negotiation and client lifecycle management.

function listen(port: number, options?: ServerOptions, callback?: () => void): Server;
function attach(server: HttpServer, options?: AttachOptions & ServerOptions): Server;

class Server extends BaseServer {
  constructor(opts?: ServerOptions);
  attach(server: HttpServer, options?: AttachOptions): void;
  handleRequest(req: IncomingMessage, res: ServerResponse): void;
  handleUpgrade(req: IncomingMessage, socket: Socket, head: Buffer): void;
  close(): void;
}

Server Management

Client Socket Connections

Individual client connection management with bidirectional message passing, transport upgrades, and connection state tracking.

class Socket extends EventEmitter {
  readonly id: string;
  readonly protocol: number;
  readonly readyState: ReadyState;
  readonly transport: Transport;
  readonly request: IncomingMessage;
  readonly remoteAddress: string;
  
  send(data: string | Buffer, options?: SendOptions, callback?: () => void): void;
  close(discard?: boolean): void;
}

Socket Connections

Transport System

Pluggable transport layer with automatic fallback and upgrade capabilities supporting polling, WebSocket, and WebTransport protocols.

abstract class Transport extends EventEmitter {
  readonly name: string;
  readonly sid: string;
  readonly protocol: number;
  writable: boolean;
  
  abstract send(packets: Packet[]): void;
  close(fn?: () => void): void;
}

interface TransportRegistry {
  polling: typeof Polling;
  websocket: typeof WebSocket;
  webtransport: typeof WebTransport;
}

Transport System

Configuration Types

Core Configuration Interfaces

Primary interfaces for configuring server behavior, connection handling, and transport options.

interface ServerOptions {
  pingTimeout?: number;
  pingInterval?: number;
  upgradeTimeout?: number;
  maxHttpBufferSize?: number;
  transports?: ("polling" | "websocket" | "webtransport")[];
  allowUpgrades?: boolean;
  cors?: CorsOptions;
  cookie?: CookieSerializeOptions & { name: string } | boolean;
}

interface AttachOptions {
  path?: string;
  destroyUpgrade?: boolean;
  destroyUpgradeTimeout?: number;
  addTrailingSlash?: boolean;
}

Configuration Types

Protocol & Constants

// Protocol version
const protocol: number;

// Protocol parser
const parser: {
  protocol: number;
  packets: Record<string, number>;
  encodePacket(packet: Packet): string | Buffer;
  decodePacket(data: string | Buffer): Packet;
};

Error Handling

Engine.IO emits various events for error handling:

  • Server errors: connection_error events with error details
  • Socket errors: error events on individual socket instances
  • Transport errors: Automatic fallback to alternative transports
  • Connection timeouts: Configurable via pingTimeout and pingInterval