socket.io-serverless

A custom socket.io build for serverless environments. Currently Cloudflare Worker + Durable Objects.

Getting started

The following example assumes you already know the Cloudflare products and wrangler CLI.

1. Install the package

npm install --save socket.io-serverless
npm install --save-dev socket.io # this provides type declarations of socket.io

2. Create Durable Object classes and worker entrypoint

A typical worker app built with this library will have the following exports:

1. a EngineActor Durable Object class, to run engine.io code
2. a SocketActor Durable Object class, to run socket.io code
3. a entrypoint default export, to handle HTTP request

demo-server/ provides a minimal implementation.

3. Run

Write a wrangler.toml, and run wrangler dev or wrangler deploy.

Again demo-server/ contains a wrangler.toml you can start with.

demo-client/ contains a frontend socket.io client app.

Features

This lib heavily rewires things to run in and take advantage of Durable Objects.

• Simpler socket.io server applications should be compatible.

• Support Hibernation to save costs.

  • Across Durable Object lifecycles, internal states are persisted with storage API. Read on to find the details.

• Drive server-inititiated ping check by Alarm rather than setInterval timer.

Limitations

• Parent namespaces need to be defined in onServerCreated callback

  • defining parent namespace with a function is not supported

• Only a certain subset of socket.io server internal state get restored after hibernation

  • Your application logic need to be consistent with this
  • concrete namespaces, connected client ids, and namespaces they joined (but not the rooms)

• Only WebSocket transport is supported

• Only engine.io protocol v4 (where a server starts ping-pong checks) is supported

• message acknowledgement is not supported.

• socket.io connection state recovery is not supported

  • Each underlying WebSocket connection will occur as independent to engine.io and socket.io

• socket.io server middleware and namespace middleware is not tested

• Load splitting like cluster-adapter is not supported. Currently this library uses a single DO to run engine.io code, and another to run socket.io code.

License

BSD