Engine.IO Protocol

This document describes the 4th version of the Engine.IO protocol.

Table of content

• Introduction
• Transports
  • HTTP long-polling
    • Request path
    • Query parameters
    • Headers
    • Sending and receiving data
      • Sending data
      • Receiving data
  • WebSocket
• Protocol
  • Handshake
  • Heartbeat
  • Upgrade
  • Message
• Packet encoding
  • HTTP long-polling
  • WebSocket
• History
  • From v2 to v3
  • From v3 to v4
• Test suite

Introduction

The Engine.IO protocol enables full-duplex and low-overhead communication between a client and a server.

It is based on the WebSocket protocol and uses HTTP long-polling as fallback if the WebSocket connection can't be established.

The reference implementation is written in TypeScript:

• server: https://github.com/socketio/engine.io
• client: https://github.com/socketio/engine.io-client

The Socket.IO protocol is built on top of these foundations, bringing additional features over the communication channel provided by the Engine.IO protocol.

Transports

The connection between an Engine.IO client and an Engine.IO server can be established with:

• HTTP long-polling
• WebSocket

HTTP long-polling

The HTTP long-polling transport (also simply referred as "polling") consists of successive HTTP requests:

• long-running GET requests, for receiving data from the server
• short-running POST requests, for sending data to the server

Request path

The path of the HTTP requests is /engine.io/ by default.

It might be updated by libraries built on top of the protocol (for example, the Socket.IO protocol uses /socket.io/).

Query parameters

The following query parameters are used:

Name	Value	Description
EIO	4	Mandatory, the version of the protocol.
transport	polling	Mandatory, the name of the transport.
sid	<sid>	Mandatory once the session is established, the session identifier.

If a mandatory query parameter is missing, then the server MUST respond with an HTTP 400 error status.

Headers

When sending binary data, the sender (client or server) MUST include a Content-Type: application/octet-stream header.

Without an explicit Content-Type header, the receiver SHOULD infer that the data is plaintext.

Reference: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type

Sending and receiving data