fix: hocuspocus provider auto connect and disconnect behavior (ueberdosis#663)

* fix: hocuspocus provider auto connect and disconnect behavior

* docs: subdocuments

* docs: add documentation for preseveConnection

* fix: change name of property

Author: linspw

docs/guides/multi-subdocuments.md

@@ -93,7 +93,8 @@ const server = Server.configure({
       // Get a Y-Doc for the 'default' field …
       const defaultField = TiptapTransformer.toYdoc(
         generateSampleProsemirrorJson("What is love?"),
-        "default"[(Document, Paragraph, Text)]
+        "default",
+        [(Document, Paragraph, Text)]
       );
       // … and merge it into the given document
       data.document.merge(defaultField);
@@ -102,7 +103,8 @@ const server = Server.configure({
       // Get a Y-Doc for the 'secondary' field …
       const secondaryField = TiptapTransformer.toYdoc(
         generateSampleProsemirrorJson("Baby don't hurt me…"),
-        "secondary"[(Document, Paragraph, Text)]
+        "secondary",
+        [(Document, Paragraph, Text)]
       );
       // … and merge it into the given document
       data.document.merge(secondaryField);

docs/provider/configuration.md

@@ -14,7 +14,8 @@ tableOfContents: true
 | `document`                | The actual Y.js document. Optional, by default a new document is created and be access through provider.document.                                                                  | `new Y.Doc()`    |
 | `token`                   | An authentication token that will be passed to the server (works with strings, functions and Promises).                                                                            | `''`             |
 | `awareness`               | Awareness object, by default attached to the passed Y.js document.                                                                                                                 | `new Awareness()` |
-| `connect`                 | Whether to connect to the server after intialization.                                                                                                                              | `true`           |
+| `connect`                 | Whether to connect to the server after initialization.                                                                                                                              | `true`           |
+| `preserveConnection`                   | Whether to preserve the websocket connection after closing the provider.                                                                    | `true`          |
 | `broadcast`               | By default changes are synced between browser tabs through broadcasting.                                                                                                           | `true`           |
 | `forceSyncInterval`       | Ask the server every x ms for updates.                                                                                                                                             | `false`          |
 | `delay`                   | The delay between each attempt in milliseconds. You can provide a factor to have the delay grow exponentially.                                                                     | `1000`           |

packages/provider/src/HocuspocusProvider.ts

@@ -43,9 +43,9 @@ export type HocuspocusProviderConfiguration =
   )
 
 export interface CompleteHocuspocusProviderConfiguration {
-   /**
-    * The identifier/name of your document
-    */
+  /**
+  * The identifier/name of your document
+  */
    name: string,
   /**
    * The actual Y.js document
@@ -96,6 +96,16 @@ export interface CompleteHocuspocusProviderConfiguration {
    * Don’t output any warnings.
    */
   quiet: boolean,
+
+  /**
+   * Pass `false` to start the connection manually.
+   */
+  connect: boolean,
+
+  /**
+   * Pass `false` to close the connection manually.
+   */
+  preserveConnection: boolean,
 }
 
 export class HocuspocusProvider extends EventEmitter {
@@ -124,6 +134,8 @@ export class HocuspocusProvider extends EventEmitter {
     onAwarenessChange: () => null,
     onStateless: () => null,
     quiet: false,
+    connect: true,
+    preserveConnection: true,
   }
 
   subscribedToBroadcastChannel = false
@@ -242,6 +254,7 @@ export class HocuspocusProvider extends EventEmitter {
 
       this.configuration.websocketProvider = new HocuspocusProviderWebsocket({
         url: websocketProviderConfig.url,
+        connect: websocketProviderConfig.connect,
         parameters: websocketProviderConfig.parameters,
       })
     }
@@ -349,6 +362,9 @@ export class HocuspocusProvider extends EventEmitter {
   disconnect() {
     this.disconnectBroadcastChannel()
     this.configuration.websocketProvider.detach(this)
+    if (!this.configuration.preserveConnection) {
+      this.configuration.websocketProvider.disconnect()
+    }
   }
 
   async onOpen(event: Event) {

packages/provider/src/HocuspocusProviderWebsocket.ts

@@ -211,7 +211,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
   }
 
   attach(provider: HocuspocusProvider) {
-    if (this.status === WebSocketStatus.Disconnected) {
+    if (this.status === WebSocketStatus.Disconnected && this.shouldConnect) {
       this.connect()
     }
 

playground/frontend/src/App.vue

@@ -62,3 +62,26 @@
     </div>
   </div>
 </template>
+
+<style>
+.special-button {
+  border-radius: 8px;
+  background-color: #155EFA;
+  color: #FFFFFF;
+  padding: 8px 16px;
+}
+
+pre {
+  background: #0d0d0d;
+  color: #fff;
+  padding: 0.75rem 1rem;
+  border-radius: 0.5rem;
+}
+
+code {
+  color: inherit;
+  padding: 0;
+  background: none;
+  font-size: 0.8rem;
+}
+</style>

playground/frontend/src/pages/Awareness.vue

@@ -10,7 +10,7 @@
       :socket="provider.configuration.websocketProvider"
     />
 
-    <h2>
+    <h2 class="mb-2">
       Users
     </h2>
 
@@ -19,7 +19,7 @@
         v-for="state in states"
         :key="state.clientId"
       >
-        <span :style="`background-color: ${state.user.color}; width: 1rem; height: 1rem; margin-right: 0.5rem; display: inline-block;`" />
+        <span :style="`background-color: ${state.user?.color}; width: 1rem; height: 1rem; margin-right: 0.5rem; display: inline-block;`" />
         #{{ state.clientId }} {{ state.user.name }} ({{ state.user.clientX }}, {{ state.user.clientY }})
       </li>
     </ul>
@@ -29,9 +29,9 @@
       :key="state.clientId"
       :style="`
         position: absolute;
-        background-color: ${state.user.color};
-        top: ${state.user.clientY}px;
-        left: ${state.user.clientX}px;
+        background-color: ${state.user?.color};
+        top: ${state.user?.clientY}px;
+        left: ${state.user?.clientX}px;
         width: 12px;
         height: 12px;
         margin-left: -6px;

playground/frontend/src/pages/Index.vue

@@ -10,7 +10,7 @@
       :socket="socket"
     />
 
-    <h2>
+    <h2 class="mb-2">
       Editor
     </h2>
     <div v-if="editor">
@@ -20,15 +20,22 @@
       />
     </div>
 
-    <button @click="provider.setAwarenessField('date', Date.now())">provider.setAwarenessField('date', Date.now())</button>
+    <button
+      class="special-button"
+      @click="provider.setAwarenessField('date', Date.now())"
+    >
+      Update Date
+    </button>
+
+    <pre><code>{{ $states1 }}</code></pre>
 
     <StatusBar
       v-if="anotherProvider"
       :provider="anotherProvider"
       :socket="socket"
     />
 
-    <h2>
+    <h2 class="mb-2">
       Another Editor
     </h2>
     <div v-if="anotherEditor">
@@ -38,11 +45,19 @@
       />
     </div>
 
-    <button @click="anotherProvider.setAwarenessField('date', Date.now())">anotherProvider.setAwarenessField('date', Date.now())</button>
+    <button
+      class="special-button"
+      @click="anotherProvider.setAwarenessField('date', Date.now())"
+    >
+      Update Date
+    </button>
+
+    <pre><code>{{ $states2 }}</code></pre>
   </div>
 </template>
 
 <script setup lang="ts">
+import { ref } from 'vue'
 import { Editor, EditorContent } from '@tiptap/vue-3'
 import StarterKit from '@tiptap/starter-kit'
 import Collaboration from '@tiptap/extension-collaboration'
@@ -56,16 +71,25 @@ const socket = new HocuspocusProviderWebsocket({
   url: 'ws://127.0.0.1:1234',
 })
 
+const $states1 = ref({})
+const $states2 = ref({})
+
 const provider = new HocuspocusProvider({
   websocketProvider: socket,
   name: 'hocuspocus-demo',
   broadcast: false,
+  onAwarenessUpdate: ({ states }) => {
+    $states1.value = states
+  },
 })
 
 const anotherProvider = new HocuspocusProvider({
   websocketProvider: socket,
   name: 'hocuspocus-demo2',
   broadcast: false,
+  onAwarenessUpdate: ({ states }) => {
+    $states2.value = states
+  },
 })
 
 const editor = new Editor({
@@ -91,9 +115,10 @@ const anotherEditor = new Editor({
     }),
   ],
 })
+
 </script>
 
-<style>
+<style >
 .ProseMirror {
   border: 1px solid grey;
   padding: 1rem;

playground/frontend/src/pages/Rooms.vue

@@ -15,14 +15,15 @@
         <td class="p-3 border border-gray-300">{{ room.states }}</td>
         <td class="p-3 border border-gray-300 text-center">
           <button
-            v-if="room.status !== 'connected'"
+            v-if="room.status === 'disconnected'"
             @click="room.connect()"
             class="border-2 border-black bg-black text-white px-4 py-2 rounded"
           >
             connect
           </button>
+
           <button
-            v-if="room.status !== 'disconnected'"
+            v-else-if="room.status === 'connected'"
             @click="room.disconnect()"
             class="border-2 border-black px-4 py-2 rounded"
           >
@@ -34,43 +35,53 @@
   </div>
 </template>
 
-<script>
+<script lang="ts">
 import * as Y from 'yjs'
-// import { WebsocketProvider } from 'y-websocket'
-import { HocuspocusProvider } from '@hocuspocus/provider'
+import { ref } from 'vue'
+import { HocuspocusProvider, StatesArray } from '@hocuspocus/provider'
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { awarenessStatesToArray } from '@hocuspocus/common'
 
 class Room {
   doc = new Y.Doc()
 
   name = ''
 
-  status = 'disconnected'
+  status = ref('disconnected')
+
+  numberOfUsers = ref(0)
 
-  states = []
+  states: StatesArray = []
 
-  constructor(name) {
+  provider: HocuspocusProvider
+
+  constructor(name: string) {
     this.name = name
     // this.provider = new WebsocketProvider('ws://localhost:1234', this.name, this.doc)
     this.provider = new HocuspocusProvider({
       url: 'ws://localhost:1234',
       document: this.doc,
       name: this.name,
+      broadcast: false,
+      connect: false,
+      preserveConnection: false,
       onStatus: ({ status }) => {
-        this.status = status
+        this.status.value = status
       },
       onAwarenessUpdate: ({ states }) => {
         this.states = states
+        this.numberOfUsers.value = awarenessStatesToArray(this.provider.awareness.getStates()).filter((state => 'user' in state)).length
+      },
+      onDisconnect: () => {
+        this.states = []
+        this.numberOfUsers.value = 0
       },
     })
 
-    this.provider.setAwarenessField('user', { name: `Jon @ ${this.name}` })
-  }
-
-  get numberOfUsers() {
-    return this.provider.awareness.getStates().size
   }
 
   connect() {
+    this.provider.setAwarenessField('user', { name: `Jon @ ${this.name}` })
     this.provider.connect()
   }
 
@@ -86,7 +97,7 @@ class Room {
 export default {
   data() {
     return {
-      rooms: [],
+      rooms: [] as Room[],
     }
   },