@hocuspocus/provider 2.3.1 → 2.4.0-rc.0

package/dist/packages/provider/src/HocuspocusProvider.d.ts

@@ -21,8 +21,13 @@ export interface CompleteHocuspocusProviderConfiguration {
     broadcast: boolean;
     /**
      * An Awareness instance to keep the presence state of all clients.
+     *
+     * You can disable sharing awareness information by passing `null`.
+     * Note that having no awareness information shared across all connections will break our ping checks
+     * and thus trigger reconnects. You should always have at least one Provider with enabled awareness per
+     * socket connection, or ensure that the Provider receives messages before running into `HocuspocusProviderWebsocket.messageReconnectTimeout`.
      */
-    awareness: Awareness;
+    awareness: Awareness | null;
     /**
      * A token that’s sent to the backend for authentication purposes.
      */
@@ -68,6 +73,9 @@ export interface CompleteHocuspocusProviderConfiguration {
      */
     preserveConnection: boolean;
 }
+export declare class AwarenessError extends Error {
+    code: number;
+}
 export declare class HocuspocusProvider extends EventEmitter {
     configuration: CompleteHocuspocusProviderConfiguration;
     subscribedToBroadcastChannel: boolean;
@@ -94,7 +102,7 @@ export declare class HocuspocusProvider extends EventEmitter {
     onStatus({ status }: onStatusParameters): void;
     setConfiguration(configuration?: Partial<HocuspocusProviderConfiguration>): void;
     get document(): Y.Doc;
-    get awareness(): Awareness;
+    get awareness(): Awareness | null;
     get hasUnsyncedChanges(): boolean;
     incrementUnsyncedChanges(): void;
     decrementUnsyncedChanges(): void;

package/dist/packages/server/src/Document.d.ts

@@ -24,7 +24,7 @@ export declare class Document extends Doc {
      */
     constructor(name: string, logger: Debugger, yDocOptions: {});
     /**
-     * Check if the Document is empty
+     * Check if the Document (XMLFragment or Map) is empty
      */
     isEmpty(fieldName: string): boolean;
     /**

package/dist/packages/server/src/IncomingMessage.d.ts

@@ -7,10 +7,13 @@ export declare class IncomingMessage {
      */
     decoder: Decoder;
     /**
-     * Access to the reply.
+     * Private encoder; can be undefined.
+     *
+     * Lazy creation of the encoder speeds up IncomingMessages that need only a decoder.
      */
-    encoder: Encoder;
+    private encoderInternal?;
     constructor(input: any);
+    get encoder(): Encoder;
     readVarUint8Array(): Uint8Array;
     readVarUint(): number;
     readVarString(): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hocuspocus/provider",
-  "version": "2.3.1",
+  "version": "2.4.0-rc.0",
   "description": "hocuspocus provider",
   "homepage": "https://hocuspocus.dev",
   "keywords": [
@@ -29,7 +29,7 @@
     "dist"
   ],
   "dependencies": {
-    "@hocuspocus/common": "^2.3.1",
+    "@hocuspocus/common": "^2.4.0-rc.0",
     "@lifeomic/attempt": "^3.0.2",
     "lib0": "^0.2.47",
     "ws": "^7.5.9"

package/src/HocuspocusProvider.ts

@@ -58,8 +58,13 @@ export interface CompleteHocuspocusProviderConfiguration {
   broadcast: boolean,
   /**
    * An Awareness instance to keep the presence state of all clients.
+   *
+   * You can disable sharing awareness information by passing `null`.
+   * Note that having no awareness information shared across all connections will break our ping checks
+   * and thus trigger reconnects. You should always have at least one Provider with enabled awareness per
+   * socket connection, or ensure that the Provider receives messages before running into `HocuspocusProviderWebsocket.messageReconnectTimeout`.
    */
-  awareness: Awareness,
+  awareness: Awareness | null,
   /**
    * A token that’s sent to the backend for authentication purposes.
    */
@@ -108,6 +113,10 @@ export interface CompleteHocuspocusProviderConfiguration {
   preserveConnection: boolean,
 }
 
+export class AwarenessError extends Error {
+  code = 1001
+}
+
 export class HocuspocusProvider extends EventEmitter {
   public configuration: CompleteHocuspocusProviderConfiguration = {
     name: '',
@@ -163,7 +172,7 @@ export class HocuspocusProvider extends EventEmitter {
     this.setConfiguration(configuration)
 
     this.configuration.document = configuration.document ? configuration.document : new Y.Doc()
-    this.configuration.awareness = configuration.awareness ? configuration.awareness : new Awareness(this.document)
+    this.configuration.awareness = configuration.awareness !== undefined ? configuration.awareness : new Awareness(this.document)
 
     this.on('open', this.configuration.onOpen)
     this.on('message', this.configuration.onMessage)
@@ -197,16 +206,16 @@ export class HocuspocusProvider extends EventEmitter {
     this.configuration.websocketProvider.on('destroy', this.configuration.onDestroy)
     this.configuration.websocketProvider.on('destroy', this.forwardDestroy)
 
-    this.awareness.on('update', () => {
-      this.emit('awarenessUpdate', { states: awarenessStatesToArray(this.awareness.getStates()) })
+    this.awareness?.on('update', () => {
+      this.emit('awarenessUpdate', { states: awarenessStatesToArray(this.awareness!.getStates()) })
     })
 
-    this.awareness.on('change', () => {
-      this.emit('awarenessChange', { states: awarenessStatesToArray(this.awareness.getStates()) })
+    this.awareness?.on('change', () => {
+      this.emit('awarenessChange', { states: awarenessStatesToArray(this.awareness!.getStates()) })
     })
 
     this.document.on('update', this.documentUpdateHandler.bind(this))
-    this.awareness.on('update', this.awarenessUpdateHandler.bind(this))
+    this.awareness?.on('update', this.awarenessUpdateHandler.bind(this))
     this.registerEventListeners()
 
     if (this.configuration.forceSyncInterval) {
@@ -292,7 +301,9 @@ export class HocuspocusProvider extends EventEmitter {
   }
 
   pageUnload() {
-    removeAwarenessStates(this.awareness, [this.document.clientID], 'window unload')
+    if (this.awareness) {
+      removeAwarenessStates(this.awareness, [this.document.clientID], 'window unload')
+    }
   }
 
   registerEventListeners() {
@@ -395,7 +406,7 @@ export class HocuspocusProvider extends EventEmitter {
     this.incrementUnsyncedChanges()
     this.send(SyncStepOneMessage, { document: this.document, documentName: this.configuration.name })
 
-    if (this.awareness.getLocalState() !== null) {
+    if (this.awareness && this.awareness.getLocalState() !== null) {
       this.send(AwarenessMessage, {
         awareness: this.awareness,
         clients: [this.document.clientID],
@@ -440,11 +451,13 @@ export class HocuspocusProvider extends EventEmitter {
     this.synced = false
 
     // update awareness (all users except local left)
-    removeAwarenessStates(
-      this.awareness,
-      Array.from(this.awareness.getStates().keys()).filter(client => client !== this.document.clientID),
-      this,
-    )
+    if (this.awareness) {
+      removeAwarenessStates(
+        this.awareness,
+        Array.from(this.awareness.getStates().keys()).filter(client => client !== this.document.clientID),
+        this,
+      )
+    }
   }
 
   destroy() {
@@ -454,11 +467,13 @@ export class HocuspocusProvider extends EventEmitter {
       clearInterval(this.intervals.forceSync)
     }
 
-    removeAwarenessStates(this.awareness, [this.document.clientID], 'provider destroy')
+    if (this.awareness) {
+      removeAwarenessStates(this.awareness, [this.document.clientID], 'provider destroy')
+    }
 
     this.disconnect()
 
-    this.awareness.off('update', this.awarenessUpdateHandler)
+    this.awareness?.off('update', this.awarenessUpdateHandler)
     this.document.off('update', this.documentUpdateHandler)
 
     this.removeAllListeners()
@@ -530,18 +545,22 @@ export class HocuspocusProvider extends EventEmitter {
       this.broadcast(SyncStepOneMessage, { document: this.document })
       this.broadcast(SyncStepTwoMessage, { document: this.document })
       this.broadcast(QueryAwarenessMessage, { document: this.document })
-      this.broadcast(AwarenessMessage, { awareness: this.awareness, clients: [this.document.clientID], document: this.document })
+      if (this.awareness) {
+        this.broadcast(AwarenessMessage, { awareness: this.awareness, clients: [this.document.clientID], document: this.document })
+      }
     })
   }
 
   disconnectBroadcastChannel() {
     // broadcast message with local awareness state set to null (indicating disconnect)
-    this.send(AwarenessMessage, {
-      awareness: this.awareness,
-      clients: [this.document.clientID],
-      states: new Map(),
-      documentName: this.configuration.name,
-    }, true)
+    if (this.awareness) {
+      this.send(AwarenessMessage, {
+        awareness: this.awareness,
+        clients: [this.document.clientID],
+        states: new Map(),
+        documentName: this.configuration.name,
+      }, true)
+    }
 
     if (this.subscribedToBroadcastChannel) {
       bc.unsubscribe(this.broadcastChannel, this.boundBroadcastChannelSubscriber)
@@ -562,6 +581,9 @@ export class HocuspocusProvider extends EventEmitter {
   }
 
   setAwarenessField(key: string, value: any) {
+    if (!this.awareness) {
+      throw new AwarenessError(`Cannot set awareness field "${key}" to ${JSON.stringify(value)}. You have disabled Awareness for this provider by explicitly passing awareness: null in the provider configuration.`)
+    }
     this.awareness.setLocalStateField(key, value)
   }
 }

package/src/HocuspocusProviderWebsocket.ts

@@ -98,8 +98,6 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
     url: '',
     // @ts-ignore
     document: undefined,
-    // @ts-ignore
-    awareness: undefined,
     WebSocketPolyfill: undefined,
     parameters: {},
     connect: true,
@@ -358,7 +356,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
       return
     }
 
-    // Don’t close then connection while waiting for the first message
+    // Don’t close the connection while waiting for the first message
     if (!this.lastMessageReceived) {
       return
     }
@@ -369,7 +367,8 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
     }
 
     // No message received in a long time, not even your own
-    // Awareness updates, which are updated every 15 seconds.
+    // Awareness updates, which are updated every 15 seconds
+    // if awareness is enabled.
     this.closeTries += 1
     // https://bugs.webkit.org/show_bug.cgi?id=247943
     if (this.closeTries > 2) {

package/src/MessageReceiver.ts

@@ -97,6 +97,8 @@ export class MessageReceiver {
   }
 
   private applyAwarenessMessage(provider: HocuspocusProvider) {
+    if (!provider.awareness) return
+
     const { message } = this
 
     awarenessProtocol.applyAwarenessUpdate(
@@ -117,6 +119,8 @@ export class MessageReceiver {
   }
 
   private applyQueryAwarenessMessage(provider: HocuspocusProvider) {
+    if (!provider.awareness) return
+
     const { message } = this
 
     message.writeVarUint(MessageType.Awareness)