@styris-ame/y-engineio 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Kevin Jahns <kevin.jahns@protonmail.com>.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# @styris-ame/y-engineio :tophat:
+> Engine.IO Provider for Yjs
+
+A port of [`y-websocket`](https://github.com/yjs/y-websocket) that syncs a
+`Y.Doc` over [Engine.IO](https://github.com/socketio/engine.io) (the transport
+layer underneath Socket.IO) instead of a raw WebSocket. It keeps the same sync +
+awareness protocol and the same cross-tab BroadcastChannel sync.
+
+Why Engine.IO? It negotiates a transport (HTTP long-polling → WebSocket →
+WebTransport) and transparently falls back when WebSockets are blocked by a
+proxy, which a raw `WebSocket` cannot do.
+
+This is the **Yjs v13 line** (`1.x`, dist-tag `yjs13`): it targets **Yjs v13**
+(`yjs`, `y-protocols`, `lib0@^0.2`).
+
+## Yjs v13 vs v14
+
+This `1.x` line (dist-tag `yjs13`) targets **Yjs v13** (`yjs`, `y-protocols`,
+`lib0@^0.2`). For **Yjs v14** (`@y/y`, `@y/protocols`) install the `2.x` line
+(dist-tag `yjs14`): `npm i @styris-ame/y-engineio@yjs14 @y/y`.
+
+## Quick Start
+
+```sh
+npm i @styris-ame/y-engineio@yjs13 engine.io-client yjs
+```
+
+```js
+import * as Y from 'yjs'
+import { EngineIOProvider } from '@styris-ame/y-engineio'
+
+const doc = new Y.Doc()
+// note: serverUrl is just the origin — the room name is NOT part of the URL
+const provider = new EngineIOProvider('http://localhost:1234', 'my-roomname', doc)
+
+provider.on('status', event => {
+  console.log(event.status) // "connecting" | "connected" | "disconnected"
+})
+```
+
+## How it differs from y-websocket
+
+| | y-websocket | @styris-ame/y-engineio |
+|---|---|---|
+| transport | raw `WebSocket` | engine.io-client `Socket` (polling/ws/webtransport) |
+| URL | `serverUrl/roomname?params` | `serverUrl` only; params become engine.io `query` |
+| room selection | encoded in the URL path | sent as the `room` handshake query param (see below) |
+| socket field | `provider.ws` | `provider.engine` |
+
+Everything else — the `messageSync` / `messageAwareness` / `messageAuth` /
+`messageQueryAwareness` protocol, exponential-backoff reconnect, the
+`socketTimeout` watchdog, `sync` events, and cross-tab BroadcastChannel sync —
+is unchanged from y-websocket.
+
+## Wire protocol (for server authors)
+
+Every frame is binary (engine.io binary message) and starts with a
+[lib0](https://github.com/dmonad/lib0)-encoded `varUint` message type:
+
+| type | const | direction | payload |
+|---|---|---|---|
+| `0` | `messageSync` | both | `y-protocols/sync` message |
+| `1` | `messageAwareness` | both | `varUint8Array` awareness update |
+| `2` | `messageAuth` | server→client | `y-protocols/auth` message |
+| `3` | `messageQueryAwareness` | both | (empty) |
+
+### Room handshake
+
+Because engine.io has a single connection endpoint (no per-room URL), the client
+declares its room as the `room` **handshake query parameter**, alongside any
+user-supplied `params`. engine.io-client URL-encodes query values, so the room
+name needs no manual escaping.
+
+The server reads `room` from the handshake query (e.g. engine.io's
+`allowRequest` middleware or `socket.request`) and binds the connection to that
+room before any frames are exchanged. Because it is available at handshake time,
+the server can **reject an unknown or unauthorized room immediately** instead of
+accepting the socket and waiting for a first frame. After the connection opens
+the client proceeds exactly like y-websocket: it sends sync step 1 and its local
+awareness state.
+
+## API
+
+```js
+import { EngineIOProvider } from '@styris-ame/y-engineio'
+```
+
+**`new EngineIOProvider(serverUrl: string, room: string, ydoc: Y.Doc, opts?)`**
+
+`serverUrl` is the engine.io server origin (e.g. `http://localhost:1234`). The
+following `opts` are supported:
+
+```js
+{
+  // connect immediately; set false to call provider.connect() yourself
+  connect: true,
+  // query-string params -> engine.io `query`
+  params: {}, // Object<string,string>
+  // forwarded verbatim to the engine.io-client Socket
+  // (e.g. path, transports, withCredentials, extraHeaders, ...)
+  engineOptions: {},
+  // override the engine.io-client Socket constructor (e.g. for tests)
+  EngineClass: Socket,
+  // existing awareness instance
+  awareness: new awarenessProtocol.Awareness(ydoc),
+  // resend sync step 1 every N ms (-1 disables)
+  resyncInterval: -1,
+  // max backoff between reconnects (exponential)
+  maxBackoffTime: 2500,
+  // disable cross-tab BroadcastChannel sync
+  disableBc: false,
+  // close + reconnect if no message received for this long
+  socketTimeout: /* ~1.5 * awareness outdatedTimeout */
+}
+```
+
+Instance fields & events match y-websocket, except the `ws`-prefixed fields are
+renamed: `connected`, `connecting`, `shouldConnect`, `bcconnected`, `synced`,
+`params`, `connect()`, `disconnect()`, `destroy()`, and the `status`, `sync`,
+`connection-close`, `connection-error` events. The live socket is exposed as
+`provider.engine` (an engine.io-client `Socket`) rather than `provider.ws`.
+
+## License
+
+[The MIT License](./LICENSE) — port of y-websocket © Kevin Jahns