{"id":17697217,"url":"https://github.com/jokester/socket.io-serverless","last_synced_at":"2025-04-23T12:31:25.226Z","repository":{"id":257885465,"uuid":"802911830","full_name":"jokester/socket.io-serverless","owner":"jokester","description":"socket.io port for Cloudflare worker","archived":false,"fork":false,"pushed_at":"2024-12-20T16:57:03.000Z","size":286,"stargazers_count":17,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-18T18:51:49.395Z","etag":null,"topics":["cloudflare","serverless","socket-io"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/socket.io-serverless","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jokester.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-19T15:41:28.000Z","updated_at":"2025-03-15T17:27:50.000Z","dependencies_parsed_at":"2024-10-16T22:13:03.066Z","dependency_job_id":"03f11251-464b-4f5f-8ebe-062fd25f6f49","html_url":"https://github.com/jokester/socket.io-serverless","commit_stats":null,"previous_names":["jokester/socket.io-serverless"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jokester%2Fsocket.io-serverless","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jokester%2Fsocket.io-serverless/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jokester%2Fsocket.io-serverless/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jokester%2Fsocket.io-serverless/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jokester","download_url":"https://codeload.github.com/jokester/socket.io-serverless/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250393959,"owners_count":21423358,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudflare","serverless","socket-io"],"created_at":"2024-10-24T14:46:48.330Z","updated_at":"2025-04-23T12:31:25.209Z","avatar_url":"https://github.com/jokester.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# socket.io-serverless\n\nA custom [socket.io](https://socket.io/) build for serverless environments. Currently [Cloudflare Worker + Durable Objects](https://developers.cloudflare.com/durable-objects/).\n\nDemo client app: [sio-serverless-demo-client](https://sio-serverless-demo-client.ihate.work) running `demo-client/` `demo-server/` code in [source code repo](https://github.com/jokester/socket.io-serverless)\n\n## Getting started\n\nThe following example assumes you already know the related Cloudflare products and `wrangler` CLI.\n\n### 1. Install the package\n\n```\nnpm install --save socket.io-serverless\nnpm install --save-dev socket.io # this provides type declarations of socket.io\n```\n\n### 2. Create Durable Object classes and worker entrypoint\n\nA typical worker app built with this library will have the following exports:\n\n1. a `EngineActor` Durable Object class, to run engine.io code\n2. a `SocketActor` Durable Object class, to run socket.io code\n3. a entrypoint default export, to handle HTTP request\n\n[demo-server/](https://github.com/jokester/socket.io-serverless/tree/main/demo-server) provides a minimal implementation.\n\n### 3. Run\n\nWrite a [wrangler.toml](https://developers.cloudflare.com/workers/wrangler/configuration/), and run `wrangler dev` or `wrangler deploy`.\n\nAgain [demo-server/](https://github.com/jokester/socket.io-serverless/tree/main/demo-server) contains a wrangler.toml you can start with.\n\n[demo-client/](https://github.com/jokester/socket.io-serverless/tree/main/demo-client) contains a frontend socket.io client app using `demo-server` to send event across browsers.\n\n## Features\n\nThis lib heavily rewires things to run in and take advantage of Durable Objects.\n\n- *Simpler* socket.io server applications should be compatible.\n\n- Support [Hibernation](https://developers.cloudflare.com/durable-objects/examples/websocket-hibernation-server/) to save costs.\n    - Across Durable Object lifecycles, internal states are persisted with [storage API](https://developers.cloudflare.com/durable-objects/api/storage-api/). Read on to find the details.\n\n- Drive server-inititiated periodic ping by [Alarm](https://developers.cloudflare.com/durable-objects/api/alarms/) rather than `setInterval` timer.\n\n## Limitations\n\n- Parent namespaces need to be defined in `onServerCreated` callback\n    - defining parent namespace with a function is not supported\n\n- Only a certain subset of socket.io server internal state get restored after hibernation\n    - Your application logic need to be consistent with this\n    - concrete namespaces, connected client ids, and namespaces they joined (but not the [rooms](https://socket.io/docs/v4/rooms/))\n\n\u003c!-- otherwise they won't be recovered after hibernation --\u003e\n\n- Only WebSocket transport is supported\n\n- Only engine.io protocol v4 (where a server starts ping-pong checks) is supported\n\n- [message acknowledgement](https://socket.io/docs/v4/emitting-events/#acknowledgements) is not supported.\n\n\u003c!--\n- due to possible hibernation it's hard to do right\n- it's better to not expect a transport to provide application-level ACK anyway\n--\u003e\n\n- [socket.io connection state recovery](https://socket.io/docs/v4/tutorial/step-6) is not supported\n    - Each underlying WebSocket connection will occur as independent to engine.io and socket.io\n\n- socket.io server middleware and namespace middleware is *not tested*\n\n \u003c!-- Allowing so would make it impossible to hydrate in new DO lifetime // TODO: really? --\u003e\n\n- 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.\n\n\u003c!-- Unlike other harder limitations the last 2 should be doable. I just don't have a plan yet --\u003e\n\n\u003c!-- less important ?\n\n- engine.io server middleware\n- engine.io Server and socket.io Server support much fewer options\n\n--\u003e\n\n### License\n\nBSD\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjokester%2Fsocket.io-serverless","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjokester%2Fsocket.io-serverless","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjokester%2Fsocket.io-serverless/lists"}