Skip to content

Latest commit

 

History

History
90 lines (52 loc) · 3.66 KB

README.md

File metadata and controls

90 lines (52 loc) · 3.66 KB
Raw

socket.io-serverless

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

Demo client app: sio-serverless-demo-client running demo-client/ demo-server/ code in this repo.

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