feat: cross-ws (bun, deno, cloudflare, node uwebsocket) (#1056)

* wip

* wip

* wip

* feat: replace listeners by crossws-way

* chore: adds bun types

* bun fix

* type fix in bun.ts

* pnpm lock

* fix: cleanup

* provider: handle unknown messages gracefully (log instead of throw)

* replace ping/pong by timeout based on message received. awareness is sent every 30 seconds, so we can use that instead of ping/pong. ping/pong can't be added to the protocol because old provider would throw.

* fix: make sure that all dist files keep node: prefixes. Deno didnt work because "url" was required without node: prefix ; this is actually coming from the "ws" package, not from our code base... The fix works by checking all require/imports, then checking if they are present in node and then prefixes them

Author: janthurau

package.json

@@ -4,7 +4,11 @@
 	"browserslist": ["defaults", "not IE 11", "maintained node versions"],
 	"type": "module",
 	"ava": {
-		"files": ["tests/**/*", "!tests/utils/**/*", "!database/**/*"],
+		"files": [
+			"tests/**/*",
+			"!tests/utils/**/*",
+			"!database/**/*"
+		],
 		"extensions": {
 			"ts": "module"
 		},
@@ -49,6 +53,7 @@
 	"devDependencies": {
 		"@ava/typescript": "^3.0.1",
 		"@biomejs/biome": "1.9.4",
+		"@types/bun": "^1.3.9",
 		"ava": "^4.3.3",
 		"concurrently": "^6.4.0",
 		"lerna": "^9.0.3",

packages/extension-redis/src/Redis.ts

@@ -142,6 +142,7 @@ export class Redis implements Extension {
 			this.pub = new RedisClient(port, host, options ?? {});
 			this.sub = new RedisClient(port, host, options ?? {});
 		}
+
 		this.sub.on("messageBuffer", this.handleIncomingMessage);
 
 		this.redlock = new Redlock([this.pub], {

packages/extension-throttle/src/index.ts

@@ -114,11 +114,10 @@ export class Throttle implements Extension {
 	onConnect(data: onConnectPayload): Promise<any> {
 		const { request } = data;
 
-		// get the remote ip address
+		// get the remote ip address from headers (web standard Request doesn't have socket)
 		const ip =
-			request.headers["x-real-ip"] ||
-			request.headers["x-forwarded-for"] ||
-			request.socket.remoteAddress ||
+			request.headers.get("x-real-ip") ||
+			request.headers.get("x-forwarded-for") ||
 			"";
 
 		// throttle the connection

packages/provider/src/HocuspocusProvider.ts

@@ -1,5 +1,4 @@
 import { awarenessStatesToArray } from "@hocuspocus/common";
-import type { Event, MessageEvent } from "ws";
 import { Awareness, removeAwarenessStates } from "y-protocols/awareness";
 import * as Y from "yjs";
 import EventEmitter from "./EventEmitter.ts";
@@ -13,22 +12,22 @@ import { AwarenessMessage } from "./OutgoingMessages/AwarenessMessage.ts";
 import { StatelessMessage } from "./OutgoingMessages/StatelessMessage.ts";
 import { SyncStepOneMessage } from "./OutgoingMessages/SyncStepOneMessage.ts";
 import { UpdateMessage } from "./OutgoingMessages/UpdateMessage.ts";
-import type {
-	AuthorizedScope,
-	ConstructableOutgoingMessage,
-	onAuthenticatedParameters,
-	onAuthenticationFailedParameters,
-	onAwarenessChangeParameters,
-	onAwarenessUpdateParameters,
-	onCloseParameters,
-	onDisconnectParameters,
-	onMessageParameters,
-	onOpenParameters,
-	onOutgoingMessageParameters,
-	onStatelessParameters,
-	onStatusParameters,
-	onSyncedParameters,
-	onUnsyncedChangesParameters,
+import {
+	type AuthorizedScope,
+	type ConstructableOutgoingMessage,
+	type onAuthenticatedParameters,
+	type onAuthenticationFailedParameters,
+	type onAwarenessChangeParameters,
+	type onAwarenessUpdateParameters,
+	type onCloseParameters,
+	type onDisconnectParameters,
+	type onMessageParameters,
+	type onOpenParameters,
+	type onOutgoingMessageParameters,
+	type onStatelessParameters,
+	type onStatusParameters,
+	type onSyncedParameters,
+	type onUnsyncedChangesParameters,
 } from "./types.ts";
 
 export type HocuspocusProviderConfiguration = Required<

packages/provider/src/HocuspocusProviderWebsocket.ts

@@ -1,12 +1,13 @@
 import { WsReadyStates } from "@hocuspocus/common";
 import { retry } from "@lifeomic/attempt";
+import * as encoding from "lib0/encoding";
 import * as time from "lib0/time";
-import type { Event, MessageEvent } from "ws";
 import EventEmitter from "./EventEmitter.ts";
 import type { HocuspocusProvider } from "./HocuspocusProvider.ts";
 import { IncomingMessage } from "./IncomingMessage.ts";
 import { CloseMessage } from "./OutgoingMessages/CloseMessage.ts";
 import {
+	MessageType,
 	WebSocketStatus,
 	type onAwarenessChangeParameters,
 	type onAwarenessUpdateParameters,
@@ -373,12 +374,32 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
 
 		this.lastMessageReceived = time.getUnixTime();
 
-		const message = new IncomingMessage(event.data);
+		const data = new Uint8Array(event.data as ArrayBuffer);
+
+		// Check for connection-level Ping message (no document name prefix)
+		// Ping messages are sent as just the message type byte (length 1)
+		// We check length to avoid confusing with regular messages that happen to have
+		// a document name length of 9 as the first byte
+		if (data.length === 1 && data[0] === MessageType.Ping) {
+			this.sendPong();
+			return;
+		}
+
+		const message = new IncomingMessage(data);
 		const documentName = message.peekVarString();
 
 		this.configuration.providerMap.get(documentName)?.onMessage(event);
 	}
 
+	/**
+	 * Send application-level Pong response to server Ping
+	 */
+	private sendPong() {
+		const encoder = encoding.createEncoder();
+		encoding.writeVarUint(encoder, MessageType.Pong);
+		this.send(encoding.toUint8Array(encoder));
+	}
+
 	resolveConnectionAttempt() {
 		if (this.connectionAttempt) {
 			this.connectionAttempt.resolve();

packages/provider/src/MessageReceiver.ts

@@ -1,6 +1,5 @@
-import { readAuthMessage } from "@hocuspocus/common";
+import { type CloseEvent, readAuthMessage } from "@hocuspocus/common";
 import { readVarInt, readVarString } from "lib0/decoding";
-import type { CloseEvent } from "ws";
 import * as awarenessProtocol from "y-protocols/awareness";
 import { messageYjsSyncStep2, readSyncMessage } from "y-protocols/sync";
 import type { HocuspocusProvider } from "./HocuspocusProvider.ts";
@@ -54,17 +53,14 @@ export class MessageReceiver {
 				const event: CloseEvent = {
 					code: 1000,
 					reason: readVarString(message.decoder),
-					// @ts-ignore
-					target: provider.configuration.websocketProvider.webSocket!,
-					type: "close",
 				};
 				provider.onClose();
 				provider.configuration.onClose({ event });
 				provider.forwardClose({ event });
 				break;
 
 			default:
-				throw new Error(`Can’t apply message of unknown type: ${type}`);
+				console.error(`Can’t apply message of unknown type: ${type}`);
 		}
 
 		// Reply

packages/provider/src/types.ts

@@ -1,5 +1,4 @@
 import type { Encoder } from "lib0/encoding";
-import type { Event, MessageEvent } from "ws";
 import type { Awareness } from "y-protocols/awareness";
 import type * as Y from "yjs";
 import type { CloseEvent } from "@hocuspocus/common";
@@ -20,6 +19,8 @@ export enum MessageType {
 	Stateless = 5,
 	CLOSE = 7,
 	SyncStatus = 8,
+	Ping = 9,
+	Pong = 10,
 }
 
 export enum WebSocketStatus {

packages/server/package.json

@@ -3,12 +3,7 @@
 	"description": "plug & play collaboration backend",
 	"version": "3.4.6-rc.2",
 	"homepage": "https://hocuspocus.dev",
-	"keywords": [
-		"hocuspocus",
-		"yjs",
-		"yjs-websocket",
-		"prosemirror"
-	],
+	"keywords": ["hocuspocus", "yjs", "yjs-websocket", "prosemirror"],
 	"license": "MIT",
 	"type": "module",
 	"main": "dist/hocuspocus-server.cjs",
@@ -24,21 +19,17 @@
 			"types": "./dist/index.d.ts"
 		}
 	},
-	"files": [
-		"src",
-		"dist"
-	],
+	"files": ["src", "dist"],
 	"dependencies": {
 		"@hocuspocus/common": "workspace:^",
 		"async-lock": "^1.3.1",
 		"async-mutex": "^0.5.0",
+		"crossws": "^0.3.4",
 		"kleur": "^4.1.4",
-		"lib0": "^0.2.47",
-		"ws": "^8.5.0"
+		"lib0": "^0.2.47"
 	},
 	"devDependencies": {
-		"@types/async-lock": "^1.1.3",
-		"@types/ws": "^8.5.3"
+		"@types/async-lock": "^1.1.3"
 	},
 	"peerDependencies": {
 		"y-protocols": "^1.0.6",
@@ -47,5 +38,8 @@
 	"gitHead": "b3454a4ca289a84ddfb7fa5607a2d4b8d5c37e9d",
 	"repository": {
 		"url": "https://github.com/ueberdosis/hocuspocus"
+	},
+	"engines": {
+		"node": ">=22"
 	}
 }