@hocuspocus/provider 3.4.6-rc.2 → 4.0.0-rc.1

package/dist/index.d.ts

@@ -1,8 +1,7 @@
-import { Event, MessageEvent } from "ws";
 import * as Y from "yjs";
 import { CloseEvent } from "@hocuspocus/common";
 
-//#region node_modules/lib0/observable.d.ts
+//#region node_modules/.pnpm/lib0@0.2.117/node_modules/lib0/observable.d.ts
 /**
  * Handles named events.
  *
@@ -43,7 +42,7 @@ declare class Observable<N> {
   destroy(): void;
 }
 //#endregion
-//#region node_modules/y-protocols/awareness.d.ts
+//#region node_modules/.pnpm/y-protocols@1.0.7_yjs@13.6.29/node_modules/y-protocols/awareness.d.ts
 /**
  * @typedef {Object} MetaClientState
  * @property {number} MetaClientState.clock
@@ -132,34 +131,35 @@ declare class EventEmitter {
   removeAllListeners(): void;
 }
 //#endregion
-//#region node_modules/lib0/encoding.d.ts
+//#region node_modules/.pnpm/lib0@0.2.117/node_modules/lib0/encoding.d.ts
 /**
  * A BinaryEncoder handles the encoding to an Uint8Array.
  */
 declare class Encoder {
   cpos: number;
-  cbuf: Uint8Array;
+  cbuf: Uint8Array<ArrayBuffer>;
   /**
    * @type {Array<Uint8Array>}
    */
   bufs: Array<Uint8Array>;
 }
 //#endregion
-//#region node_modules/lib0/decoding.d.ts
+//#region node_modules/.pnpm/lib0@0.2.117/node_modules/lib0/decoding.d.ts
 /**
  * A Decoder handles the decoding of an Uint8Array.
+ * @template {ArrayBufferLike} [Buf=ArrayBufferLike]
  */
-declare class Decoder {
+declare class Decoder<Buf extends ArrayBufferLike = ArrayBufferLike> {
   /**
-   * @param {Uint8Array} uint8Array Binary data to decode
+   * @param {Uint8Array<Buf>} uint8Array Binary data to decode
    */
-  constructor(uint8Array: Uint8Array);
+  constructor(uint8Array: Uint8Array<Buf>);
   /**
    * Decoding target.
    *
-   * @type {Uint8Array}
+   * @type {Uint8Array<Buf>}
    */
-  arr: Uint8Array;
+  arr: Uint8Array<Buf>;
   /**
    * Current decoding position.
    *
@@ -190,7 +190,7 @@ declare class OutgoingMessage implements OutgoingMessageInterface {
   type?: MessageType;
   constructor();
   get(args: Partial<OutgoingMessageArguments>): Encoder | undefined;
-  toUint8Array(): Uint8Array<ArrayBufferLike>;
+  toUint8Array(): Uint8Array<ArrayBuffer>;
 }
 //#endregion
 //#region packages/provider/src/OutgoingMessages/AuthenticationMessage.d.ts
@@ -243,7 +243,9 @@ declare enum MessageType {
   QueryAwareness = 3,
   Stateless = 5,
   CLOSE = 7,
-  SyncStatus = 8
+  SyncStatus = 8,
+  Ping = 9,
+  Pong = 10
 }
 declare enum WebSocketStatus {
   Connecting = "connecting",
@@ -394,6 +396,7 @@ interface CompleteHocuspocusProviderWebsocketConfiguration {
   providerMap: Map<string, HocuspocusProvider>;
 }
 declare class HocuspocusProviderWebsocket extends EventEmitter {
+  private static readonly DEDUPLICATABLE_TYPES;
   private messageQueue;
   configuration: CompleteHocuspocusProviderWebsocketConfiguration;
   webSocket: HocusPocusWebSocket | null;
@@ -421,6 +424,10 @@ declare class HocuspocusProviderWebsocket extends EventEmitter {
   cleanupWebSocket(): void;
   createWebSocketConnection(): Promise<unknown>;
   onMessage(event: MessageEvent): void;
+  /**
+   * Send application-level Pong response to server Ping
+   */
+  private sendPong;
   resolveConnectionAttempt(): void;
   stopConnectionAttempt(): void;
   rejectConnectionAttempt(): void;
@@ -429,6 +436,8 @@ declare class HocuspocusProviderWebsocket extends EventEmitter {
   get serverUrl(): string;
   get url(): string;
   disconnect(): void;
+  private parseQueuedMessage;
+  private addToQueue;
   send(message: any): void;
   onClose({
     event
@@ -464,6 +473,17 @@ interface CompleteHocuspocusProviderConfiguration {
    * Hocuspocus websocket provider
    */
   websocketProvider: HocuspocusProviderWebsocket;
+  /**
+   * Enable session-aware multiplexing. When true, the provider embeds a unique
+   * sessionId in the documentName field of every message, allowing multiple
+   * providers with the same document name on a single WebSocket connection.
+   *
+   * Only set this to `false` when connecting to a v3 server that does not
+   * support session awareness.
+   *
+   * Default: true
+   */
+  sessionAwareness: boolean;
   /**
    * Force syncing the document in the defined interval.
    */
@@ -495,6 +515,17 @@ declare class HocuspocusProvider extends EventEmitter {
   authorizedScope: AuthorizedScope | undefined;
   manageSocket: boolean;
   private _isAttached;
+  /**
+   * Unique session identifier for this provider instance.
+   * Used for multiplexing multiple providers with the same document name on a single WebSocket.
+   */
+  sessionId: string;
+  /**
+   * The effective name used as the first VarString in messages.
+   * When `sessionAwareness` is enabled, returns a composite key (documentName\0sessionId).
+   * Otherwise, returns the plain document name.
+   */
+  get effectiveName(): string;
   intervals: any;
   constructor(configuration: HocuspocusProviderConfiguration);
   boundDocumentUpdateHandler: (update: Uint8Array, origin: any) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hocuspocus/provider",
-	"version": "3.4.6-rc.2",
+	"version": "4.0.0-rc.1",
 	"description": "hocuspocus provider",
 	"homepage": "https://hocuspocus.dev",
 	"keywords": [
@@ -29,7 +29,7 @@
 		"dist"
 	],
 	"dependencies": {
-		"@hocuspocus/common": "^3.4.6-rc.2",
+		"@hocuspocus/common": "^4.0.0-rc.1",
 		"@lifeomic/attempt": "^3.0.2",
 		"lib0": "^0.2.87",
 		"ws": "^8.17.1"
@@ -38,8 +38,11 @@
 		"y-protocols": "^1.0.6",
 		"yjs": "^13.6.8"
 	},
-	"gitHead": "cd788b6a315f608ef531524409abdce1e6790726",
+	"gitHead": "730ac02724fcc44bbbfcc5849df4b0cafb996450",
 	"repository": {
 		"url": "https://github.com/ueberdosis/hocuspocus"
+	},
+	"publishConfig": {
+		"access": "public"
 	}
 }

package/src/HocuspocusProvider.ts

@@ -1,5 +1,4 @@
-import { awarenessStatesToArray } from "@hocuspocus/common";
-import type { Event, MessageEvent } from "ws";
+import { awarenessStatesToArray, makeRoutingKey, parseRoutingKey } from "@hocuspocus/common";
 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<
@@ -78,6 +77,18 @@ export interface CompleteHocuspocusProviderConfiguration {
 	 */
 	websocketProvider: HocuspocusProviderWebsocket;
 
+	/**
+	 * Enable session-aware multiplexing. When true, the provider embeds a unique
+	 * sessionId in the documentName field of every message, allowing multiple
+	 * providers with the same document name on a single WebSocket connection.
+	 *
+	 * Only set this to `false` when connecting to a v3 server that does not
+	 * support session awareness.
+	 *
+	 * Default: true
+	 */
+	sessionAwareness: boolean;
+
 	/**
 	 * Force syncing the document in the defined interval.
 	 */
@@ -112,6 +123,7 @@ export class HocuspocusProvider extends EventEmitter {
 		// @ts-ignore
 		awareness: undefined,
 		token: null,
+		sessionAwareness: true,
 		forceSyncInterval: false,
 		onAuthenticated: () => null,
 		onAuthenticationFailed: () => null,
@@ -143,6 +155,23 @@ export class HocuspocusProvider extends EventEmitter {
 
 	private _isAttached = false;
 
+	/**
+	 * Unique session identifier for this provider instance.
+	 * Used for multiplexing multiple providers with the same document name on a single WebSocket.
+	 */
+	sessionId: string = Math.random().toString(36).slice(2);
+
+	/**
+	 * The effective name used as the first VarString in messages.
+	 * When `sessionAwareness` is enabled, returns a composite key (documentName\0sessionId).
+	 * Otherwise, returns the plain document name.
+	 */
+	get effectiveName(): string {
+		return this.configuration.sessionAwareness
+			? makeRoutingKey(this.configuration.name, this.sessionId)
+			: this.configuration.name;
+	}
+
 	intervals: any = {
 		forceSync: null,
 	};
@@ -280,7 +309,7 @@ export class HocuspocusProvider extends EventEmitter {
 
 		this.send(SyncStepOneMessage, {
 			document: this.document,
-			documentName: this.configuration.name,
+			documentName: this.effectiveName,
 		});
 	}
 
@@ -304,7 +333,7 @@ export class HocuspocusProvider extends EventEmitter {
 
 	sendStateless(payload: string) {
 		this.send(StatelessMessage, {
-			documentName: this.configuration.name,
+			documentName: this.effectiveName,
 			payload,
 		});
 	}
@@ -322,7 +351,7 @@ export class HocuspocusProvider extends EventEmitter {
 
 		this.send(AuthenticationMessage, {
 			token: token ?? "",
-			documentName: this.configuration.name,
+			documentName: this.effectiveName,
 		});
 	}
 
@@ -332,7 +361,7 @@ export class HocuspocusProvider extends EventEmitter {
 		}
 
 		this.incrementUnsyncedChanges();
-		this.send(UpdateMessage, { update, documentName: this.configuration.name });
+		this.send(UpdateMessage, { update, documentName: this.effectiveName });
 	}
 
 	awarenessUpdateHandler({ added, updated, removed }: any, origin: any) {
@@ -341,7 +370,7 @@ export class HocuspocusProvider extends EventEmitter {
 		this.send(AwarenessMessage, {
 			awareness: this.awareness,
 			clients: changedClients,
-			documentName: this.configuration.name,
+			documentName: this.effectiveName,
 		});
 	}
 
@@ -414,14 +443,14 @@ export class HocuspocusProvider extends EventEmitter {
 
 		this.send(SyncStepOneMessage, {
 			document: this.document,
-			documentName: this.configuration.name,
+			documentName: this.effectiveName,
 		});
 
 		if (this.awareness && this.awareness.getLocalState() !== null) {
 			this.send(AwarenessMessage, {
 				awareness: this.awareness,
 				clients: [this.document.clientID],
-				documentName: this.configuration.name,
+				documentName: this.effectiveName,
 			});
 		}
 	}
@@ -438,9 +467,11 @@ export class HocuspocusProvider extends EventEmitter {
 	onMessage(event: MessageEvent) {
 		const message = new IncomingMessage(event.data);
 
-		const documentName = message.readVarString();
+		const rawKey = message.readVarString();
+		// Extract actual documentName from potentially composite routing key
+		const { documentName } = parseRoutingKey(rawKey);
 
-		message.writeVarString(documentName);
+		message.writeVarString(this.effectiveName);
 
 		this.emit("message", { event, message: new IncomingMessage(event.data) });
 

package/src/HocuspocusProviderWebsocket.ts

@@ -1,13 +1,14 @@
 import { WsReadyStates } from "@hocuspocus/common";
 import { retry } from "@lifeomic/attempt";
+import { createDecoder, readVarString, readVarUint } from "lib0/decoding";
+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 {
-	WebSocketStatus,
+	MessageType,
 	type onAwarenessChangeParameters,
 	type onAwarenessUpdateParameters,
 	type onCloseParameters,
@@ -16,6 +17,7 @@ import {
 	type onOpenParameters,
 	type onOutgoingMessageParameters,
 	type onStatusParameters,
+	WebSocketStatus,
 } from "./types.ts";
 
 export type HocuspocusWebSocket = WebSocket & { identifier: string };
@@ -103,13 +105,18 @@ export interface CompleteHocuspocusProviderWebsocketConfiguration {
 }
 
 export class HocuspocusProviderWebsocket extends EventEmitter {
+	private static readonly DEDUPLICATABLE_TYPES = new Set([
+		MessageType.Awareness,
+		MessageType.QueryAwareness,
+	]);
+
 	private messageQueue: any[] = [];
 
 	public configuration: CompleteHocuspocusProviderWebsocketConfiguration = {
 		url: "",
 		autoConnect: true,
 		preserveTrailingSlash: false,
-		// @ts-ignore
+		// @ts-expect-error
 		document: undefined,
 		WebSocketPolyfill: undefined,
 		// TODO: this should depend on awareness.outdatedTime
@@ -209,7 +216,20 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
 	}
 
 	attach(provider: HocuspocusProvider) {
-		this.configuration.providerMap.set(provider.configuration.name, provider);
+		const key = provider.effectiveName;
+		const existing = this.configuration.providerMap.get(key);
+
+		if (existing && existing !== provider) {
+			// Allow replacing a provider that hasn't authenticated (e.g., after auth failure retry)
+			if (existing.isAuthenticated) {
+				throw new Error(
+					`Cannot attach two providers with the same effective name "${key}". ` +
+						"Use sessionAwareness: true to multiplex providers with the same document name.",
+				);
+			}
+		}
+
+		this.configuration.providerMap.set(key, provider);
 
 		if (this.status === WebSocketStatus.Disconnected && this.shouldConnect) {
 			this.connect();
@@ -224,11 +244,12 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
 	}
 
 	detach(provider: HocuspocusProvider) {
-		if (this.configuration.providerMap.has(provider.configuration.name)) {
+		const key = provider.effectiveName;
+		if (this.configuration.providerMap.has(key)) {
 			provider.send(CloseMessage, {
-				documentName: provider.configuration.name,
+				documentName: key,
 			});
-			this.configuration.providerMap.delete(provider.configuration.name);
+			this.configuration.providerMap.delete(key);
 		}
 	}
 
@@ -373,10 +394,31 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
 
 		this.lastMessageReceived = time.getUnixTime();
 
-		const message = new IncomingMessage(event.data);
-		const documentName = message.peekVarString();
+		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 rawKey = message.peekVarString();
+
+		const provider = this.configuration.providerMap.get(rawKey);
+		provider?.onMessage(event);
+	}
 
-		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() {
@@ -474,11 +516,45 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
 		}
 	}
 
+	private parseQueuedMessage(
+		message: Uint8Array,
+	): { documentName: string; messageType: number } | null {
+		try {
+			const decoder = createDecoder(message);
+			const documentName = readVarString(decoder);
+			const messageType = readVarUint(decoder);
+			return { documentName, messageType };
+		} catch {
+			return null;
+		}
+	}
+
+	private addToQueue(message: any) {
+		if (message instanceof Uint8Array) {
+			const parsed = this.parseQueuedMessage(message);
+			if (
+				parsed &&
+				HocuspocusProviderWebsocket.DEDUPLICATABLE_TYPES.has(parsed.messageType)
+			) {
+				this.messageQueue = this.messageQueue.filter((queued) => {
+					if (!(queued instanceof Uint8Array)) return true;
+					const queuedParsed = this.parseQueuedMessage(queued);
+					if (!queuedParsed) return true;
+					return !(
+						queuedParsed.documentName === parsed.documentName &&
+						queuedParsed.messageType === parsed.messageType
+					);
+				});
+			}
+		}
+		this.messageQueue.push(message);
+	}
+
 	send(message: any) {
 		if (this.webSocket?.readyState === WsReadyStates.Open) {
 			this.webSocket.send(message);
 		} else {
-			this.messageQueue.push(message);
+			this.addToQueue(message);
 		}
 	}
 

package/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,9 +53,6 @@ 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 });
@@ -64,7 +60,7 @@ export class MessageReceiver {
 				break;
 
 			default:
-				throw new Error(`Can’t apply message of unknown type: ${type}`);
+				console.error(`Can’t apply message of unknown type: ${type}`);
 		}
 
 		// Reply

package/src/OutgoingMessages/AuthenticationMessage.ts

@@ -3,6 +3,7 @@ import { writeAuthentication } from "@hocuspocus/common";
 import type { OutgoingMessageArguments } from "../types.ts";
 import { MessageType } from "../types.ts";
 import { OutgoingMessage } from "../OutgoingMessage.ts";
+import { version } from "../version.ts";
 
 export class AuthenticationMessage extends OutgoingMessage {
 	type = MessageType.Auth;
@@ -19,6 +20,7 @@ export class AuthenticationMessage extends OutgoingMessage {
 		writeVarString(this.encoder, args.documentName!);
 		writeVarUint(this.encoder, this.type);
 		writeAuthentication(this.encoder, args.token);
+		writeVarString(this.encoder, version);
 
 		return this.encoder;
 	}

package/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 {

package/src/version.ts

@@ -0,0 +1,5 @@
+// @ts-ignore - __HOCUSPOCUS_VERSION__ is replaced at build time by rolldown
+// eslint-disable-next-line
+export const version: string = typeof __HOCUSPOCUS_VERSION__ !== 'undefined'
+	? __HOCUSPOCUS_VERSION__
+	: 'unknown';