@hocuspocus/provider 1.0.0-alpha.28 → 1.0.0-alpha.29

package/dist/packages/common/src/CloseEvents.d.ts

@@ -0,0 +1,23 @@
+export interface CloseEvent {
+    code: number;
+    reason: string;
+}
+/**
+ * The server successfully processed the request, asks that the requester reset
+ * its document view, and is not returning any content.
+ */
+export declare const ResetConnection: CloseEvent;
+/**
+ * Similar to Forbidden, but specifically for use when authentication is required and has
+ * failed or has not yet been provided.
+ */
+export declare const Unauthorized: CloseEvent;
+/**
+ * The request contained valid data and was understood by the server, but the server
+ * is refusing action.
+ */
+export declare const Forbidden: CloseEvent;
+/**
+ * The server timed out waiting for the request.
+ */
+export declare const ConnectionTimeout: CloseEvent;

package/dist/packages/common/src/index.d.ts

@@ -1 +1,2 @@
 export * from './auth';
+export * from './CloseEvents';

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

@@ -1,10 +1,11 @@
-import { HocuspocusProvider, HocuspocusProviderOptions } from './HocuspocusProvider';
-export interface HocuspocusCloudProviderOptions extends HocuspocusProviderOptions {
+import { HocuspocusProvider, HocuspocusProviderConfiguration } from './HocuspocusProvider';
+export declare type HocuspocusCloudProviderConfiguration = Required<Pick<HocuspocusProviderConfiguration, 'name'>> & Partial<HocuspocusProviderConfiguration> & AdditionalHocuspocusCloudProviderConfiguration;
+export interface AdditionalHocuspocusCloudProviderConfiguration {
     /**
      * A Hocuspocus Cloud key, get one here: https://hocuspocus.cloud/
      */
     key: string;
 }
 export declare class HocuspocusCloudProvider extends HocuspocusProvider {
-    constructor(options: HocuspocusCloudProviderOptions);
+    constructor(configuration: HocuspocusCloudProviderConfiguration);
 }

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

@@ -10,7 +10,8 @@ export declare enum WebSocketStatus {
     Connected = "connected",
     Disconnected = "disconnected"
 }
-export interface HocuspocusProviderOptions {
+export declare type HocuspocusProviderConfiguration = Required<Pick<CompleteHocuspocusProviderConfiguration, 'url' | 'name'>> & Partial<CompleteHocuspocusProviderConfiguration>;
+export interface CompleteHocuspocusProviderConfiguration {
     /**
      * URL of your @hocuspocus/server instance
      */
@@ -104,9 +105,13 @@ export interface HocuspocusProviderOptions {
     onDestroy: () => void;
     onAwarenessUpdate: (states: any) => void;
     onAwarenessChange: (states: any) => void;
+    /**
+     * Don’t output any warnings.
+     */
+    quiet: boolean;
 }
 export declare class HocuspocusProvider extends EventEmitter {
-    options: HocuspocusProviderOptions;
+    configuration: CompleteHocuspocusProviderConfiguration;
     subscribedToBroadcastChannel: boolean;
     webSocket: WebSocket | null;
     shouldConnect: boolean;
@@ -120,8 +125,8 @@ export declare class HocuspocusProvider extends EventEmitter {
         resolve: (value?: any) => void;
         reject: (reason?: any) => void;
     } | null;
-    constructor(options?: Partial<HocuspocusProviderOptions>);
-    setOptions(options?: Partial<HocuspocusProviderOptions>): void;
+    constructor(configuration: HocuspocusProviderConfiguration);
+    setConfiguration(configuration?: Partial<HocuspocusProviderConfiguration>): void;
     connect(): Promise<void>;
     createWebSocketConnection(): Promise<unknown>;
     resolveConnectionAttempt(): void;

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

@@ -2,8 +2,8 @@
 import AsyncLock from 'async-lock';
 import WebSocket from 'ws';
 import { IncomingMessage as HTTPIncomingMessage } from 'http';
+import { CloseEvent } from '@hocuspocus/common';
 import Document from './Document';
-import { CloseEvent } from './types';
 import { MessageLogger } from './Debugger';
 declare class Connection {
     webSocket: WebSocket;

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

@@ -23,7 +23,7 @@ export declare class Hocuspocus {
      * Configure the server
      */
     configure(configuration: Partial<Configuration>): Hocuspocus;
-    get authenticationRequired(): boolean;
+    get requiresAuthentication(): boolean;
     /**
      * Start the server
      */
@@ -46,7 +46,14 @@ export declare class Hocuspocus {
      */
     destroy(): Promise<any>;
     /**
-     * Handle the incoming WebSocket connection
+     * The `handleConnection` method receives incoming WebSocket connections,
+     * runs all hooks:
+     *
+     *  - onConnect for all connections
+     *  - onAuthenticate only if required
+     *
+     * … and if nothings fails it’ll fully establish the connection and
+     * load the Document then.
      */
     handleConnection(incoming: WebSocket, request: IncomingMessage, documentName: string, context?: any): void;
     /**

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

@@ -25,8 +25,9 @@ export interface AwarenessUpdate {
     updated: Array<any>;
     removed: Array<any>;
 }
-export interface ConnectionConfig {
+export interface ConnectionConfiguration {
     readOnly: boolean;
+    requiresAuthentication: boolean;
     isAuthenticated: boolean;
 }
 export interface Extension {
@@ -87,7 +88,7 @@ export interface onAuthenticatePayload {
     requestParameters: URLSearchParams;
     socketId: string;
     token: string;
-    connection: ConnectionConfig;
+    connection: ConnectionConfiguration;
 }
 export interface onConnectPayload {
     documentName: string;
@@ -96,7 +97,7 @@ export interface onConnectPayload {
     requestHeaders: IncomingHttpHeaders;
     requestParameters: URLSearchParams;
     socketId: string;
-    connection: ConnectionConfig;
+    connection: ConnectionConfiguration;
 }
 export interface onLoadDocumentPayload {
     context: any;
@@ -106,7 +107,7 @@ export interface onLoadDocumentPayload {
     requestHeaders: IncomingHttpHeaders;
     requestParameters: URLSearchParams;
     socketId: string;
-    connection: ConnectionConfig;
+    connection: ConnectionConfiguration;
 }
 export interface onChangePayload {
     clientsCount: number;
@@ -152,7 +153,3 @@ export interface onConfigurePayload {
     yjsVersion: string;
     instance: Hocuspocus;
 }
-export interface CloseEvent {
-    code: number;
-    reason: string;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hocuspocus/provider",
-  "version": "1.0.0-alpha.28",
+  "version": "1.0.0-alpha.29",
   "description": "hocuspocus provider",
   "homepage": "https://hocuspocus.dev",
   "keywords": [
@@ -28,10 +28,11 @@
     "dist"
   ],
   "dependencies": {
+    "@hocuspocus/common": "^1.0.0-alpha.4",
     "@lifeomic/attempt": "^3.0.1",
     "lib0": "^0.2.43",
     "y-protocols": "^1.0.5",
     "yjs": "^13.5.22"
   },
-  "gitHead": "8ffe8d8f4d10ba33f4f203806bd1d4415bef5dc3"
+  "gitHead": "87b715d1d28c603702879f4413c17d2c4a38c51a"
 }

package/src/HocuspocusCloudProvider.ts

@@ -1,6 +1,14 @@
-import { HocuspocusProvider, HocuspocusProviderOptions } from './HocuspocusProvider'
+import {
+  HocuspocusProvider,
+  HocuspocusProviderConfiguration,
+} from './HocuspocusProvider'
 
-export interface HocuspocusCloudProviderOptions extends HocuspocusProviderOptions {
+export type HocuspocusCloudProviderConfiguration =
+  Required<Pick<HocuspocusProviderConfiguration, 'name'>> &
+  Partial<HocuspocusProviderConfiguration> &
+  AdditionalHocuspocusCloudProviderConfiguration
+
+export interface AdditionalHocuspocusCloudProviderConfiguration {
   /**
    * A Hocuspocus Cloud key, get one here: https://hocuspocus.cloud/
    */
@@ -8,19 +16,19 @@ export interface HocuspocusCloudProviderOptions extends HocuspocusProviderOption
 }
 
 export class HocuspocusCloudProvider extends HocuspocusProvider {
-  constructor(options: HocuspocusCloudProviderOptions) {
-    if (!options.url) {
-      options.url = 'wss://connect.hocuspocus.cloud'
+  constructor(configuration: HocuspocusCloudProviderConfiguration) {
+    if (!configuration.url) {
+      configuration.url = 'wss://connect.hocuspocus.cloud'
     }
 
-    if (options.key) {
-      if (!options.parameters) {
-        options.parameters = {}
+    if (configuration.key) {
+      if (!configuration.parameters) {
+        configuration.parameters = {}
       }
 
-      options.parameters.key = options.key
+      configuration.parameters.key = configuration.key
     }
 
-    super(options as HocuspocusProviderOptions)
+    super(configuration as HocuspocusProviderConfiguration)
   }
 }

package/src/HocuspocusProvider.ts

@@ -6,6 +6,7 @@ import * as mutex from 'lib0/mutex'
 import * as url from 'lib0/url'
 import { Event, CloseEvent, MessageEvent } from 'ws'
 import { retry } from '@lifeomic/attempt'
+import { Forbidden, Unauthorized } from '@hocuspocus/common'
 import EventEmitter from './EventEmitter'
 import { IncomingMessage } from './IncomingMessage'
 import { MessageReceiver } from './MessageReceiver'
@@ -26,15 +27,19 @@ export enum WebSocketStatus {
   Disconnected = 'disconnected',
 }
 
-export interface HocuspocusProviderOptions {
+export type HocuspocusProviderConfiguration =
+  Required<Pick<CompleteHocuspocusProviderConfiguration, 'url' | 'name'>>
+  & Partial<CompleteHocuspocusProviderConfiguration>
+
+export interface CompleteHocuspocusProviderConfiguration {
   /**
    * URL of your @hocuspocus/server instance
    */
-  url: string,
-  /**
-   * The identifier/name of your document
-   */
-  name: string,
+   url: string,
+   /**
+    * The identifier/name of your document
+    */
+   name: string,
   /**
    * The actual Y.js document
    */
@@ -116,17 +121,21 @@ export interface HocuspocusProviderOptions {
   onDestroy: () => void,
   onAwarenessUpdate: (states: any) => void,
   onAwarenessChange: (states: any) => void,
+  /**
+   * Don’t output any warnings.
+   */
+  quiet: boolean,
 }
 
 export class HocuspocusProvider extends EventEmitter {
-  public options: HocuspocusProviderOptions = {
+  public configuration: CompleteHocuspocusProviderConfiguration = {
+    name: '',
+    url: '',
     // @ts-ignore
     document: undefined,
     // @ts-ignore
     awareness: undefined,
     WebSocketPolyfill: undefined,
-    url: '',
-    name: '',
     token: null,
     parameters: {},
     connect: true,
@@ -163,6 +172,7 @@ export class HocuspocusProvider extends EventEmitter {
     onDestroy: () => null,
     onAwarenessUpdate: () => null,
     onAwarenessChange: () => null,
+    quiet: false,
   }
 
   subscribedToBroadcastChannel = false
@@ -191,27 +201,27 @@ export class HocuspocusProvider extends EventEmitter {
     reject: (reason?: any) => void
   } | null = null
 
-  constructor(options: Partial<HocuspocusProviderOptions> = {}) {
+  constructor(configuration: HocuspocusProviderConfiguration) {
     super()
-    this.setOptions(options)
-
-    this.options.document = options.document ? options.document : new Y.Doc()
-    this.options.awareness = options.awareness ? options.awareness : new Awareness(this.document)
-    this.options.WebSocketPolyfill = options.WebSocketPolyfill ? options.WebSocketPolyfill : WebSocket
-
-    this.on('open', this.options.onOpen)
-    this.on('authenticated', this.options.onAuthenticated)
-    this.on('authenticationFailed', this.options.onAuthenticationFailed)
-    this.on('connect', this.options.onConnect)
-    this.on('message', this.options.onMessage)
-    this.on('outgoingMessage', this.options.onOutgoingMessage)
-    this.on('synced', this.options.onSynced)
-    this.on('status', this.options.onStatus)
-    this.on('disconnect', this.options.onDisconnect)
-    this.on('close', this.options.onClose)
-    this.on('destroy', this.options.onDestroy)
-    this.on('awarenessUpdate', this.options.onAwarenessUpdate)
-    this.on('awarenessChange', this.options.onAwarenessChange)
+    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.WebSocketPolyfill = configuration.WebSocketPolyfill ? configuration.WebSocketPolyfill : WebSocket
+
+    this.on('open', this.configuration.onOpen)
+    this.on('authenticated', this.configuration.onAuthenticated)
+    this.on('authenticationFailed', this.configuration.onAuthenticationFailed)
+    this.on('connect', this.configuration.onConnect)
+    this.on('message', this.configuration.onMessage)
+    this.on('outgoingMessage', this.configuration.onOutgoingMessage)
+    this.on('synced', this.configuration.onSynced)
+    this.on('status', this.configuration.onStatus)
+    this.on('disconnect', this.configuration.onDisconnect)
+    this.on('close', this.configuration.onClose)
+    this.on('destroy', this.configuration.onDestroy)
+    this.on('awarenessUpdate', this.configuration.onAwarenessUpdate)
+    this.on('awarenessChange', this.configuration.onAwarenessChange)
 
     this.awareness.on('update', () => {
       this.emit('awarenessUpdate', { states: awarenessStatesToArray(this.awareness.getStates()) })
@@ -227,18 +237,18 @@ export class HocuspocusProvider extends EventEmitter {
 
     this.intervals.connectionChecker = setInterval(
       this.checkConnection.bind(this),
-      this.options.messageReconnectTimeout / 10,
+      this.configuration.messageReconnectTimeout / 10,
     )
 
-    if (this.options.forceSyncInterval) {
+    if (this.configuration.forceSyncInterval) {
       this.intervals.forceSync = setInterval(
         this.forceSync.bind(this),
-        this.options.forceSyncInterval,
+        this.configuration.forceSyncInterval,
       )
     }
 
-    if (typeof options.connect !== 'undefined') {
-      this.shouldConnect = options.connect
+    if (typeof configuration.connect !== 'undefined') {
+      this.shouldConnect = configuration.connect
     }
 
     if (!this.shouldConnect) {
@@ -248,8 +258,8 @@ export class HocuspocusProvider extends EventEmitter {
     this.connect()
   }
 
-  public setOptions(options: Partial<HocuspocusProviderOptions> = {}): void {
-    this.options = { ...this.options, ...options }
+  public setConfiguration(configuration: Partial<HocuspocusProviderConfiguration> = {}): void {
+    this.configuration = { ...this.configuration, ...configuration }
   }
 
   async connect() {
@@ -262,14 +272,14 @@ export class HocuspocusProvider extends EventEmitter {
 
     try {
       await retry(this.createWebSocketConnection.bind(this), {
-        delay: this.options.delay,
-        initialDelay: this.options.initialDelay,
-        factor: this.options.factor,
-        maxAttempts: this.options.maxAttempts,
-        minDelay: this.options.minDelay,
-        maxDelay: this.options.maxDelay,
-        jitter: this.options.jitter,
-        timeout: this.options.timeout,
+        delay: this.configuration.delay,
+        initialDelay: this.configuration.initialDelay,
+        factor: this.configuration.factor,
+        maxAttempts: this.configuration.maxAttempts,
+        minDelay: this.configuration.minDelay,
+        maxDelay: this.configuration.maxDelay,
+        jitter: this.configuration.jitter,
+        timeout: this.configuration.timeout,
         beforeAttempt: context => {
           if (!this.shouldConnect) {
             context.abort()
@@ -288,7 +298,7 @@ export class HocuspocusProvider extends EventEmitter {
   createWebSocketConnection() {
     return new Promise((resolve, reject) => {
       // Init the WebSocket connection
-      const ws = new this.options.WebSocketPolyfill(this.url)
+      const ws = new this.configuration.WebSocketPolyfill(this.url)
       ws.binaryType = 'arraybuffer'
       ws.onmessage = this.onMessage.bind(this)
       ws.onclose = this.onClose.bind(this)
@@ -322,11 +332,11 @@ export class HocuspocusProvider extends EventEmitter {
   }
 
   get document() {
-    return this.options.document
+    return this.configuration.document
   }
 
   get awareness() {
-    return this.options.awareness
+    return this.configuration.awareness
   }
 
   checkConnection() {
@@ -341,7 +351,7 @@ export class HocuspocusProvider extends EventEmitter {
     }
 
     // Don’t close the connection when a message was received recently
-    if (this.options.messageReconnectTimeout >= time.getUnixTime() - this.lastMessageReceived) {
+    if (this.configuration.messageReconnectTimeout >= time.getUnixTime() - this.lastMessageReceived) {
       return
     }
 
@@ -401,17 +411,17 @@ export class HocuspocusProvider extends EventEmitter {
 
   // Ensure that the URL always ends with /
   get serverUrl() {
-    while (this.options.url[this.options.url.length - 1] === '/') {
-      return this.options.url.slice(0, this.options.url.length - 1)
+    while (this.configuration.url[this.configuration.url.length - 1] === '/') {
+      return this.configuration.url.slice(0, this.configuration.url.length - 1)
     }
 
-    return this.options.url
+    return this.configuration.url
   }
 
   get url() {
-    const encodedParams = url.encodeQueryParams(this.options.parameters)
+    const encodedParams = url.encodeQueryParams(this.configuration.parameters)
 
-    return `${this.serverUrl}/${this.options.name}${encodedParams.length === 0 ? '' : `?${encodedParams}`}`
+    return `${this.serverUrl}/${this.configuration.name}${encodedParams.length === 0 ? '' : `?${encodedParams}`}`
   }
 
   get synced(): boolean {
@@ -429,7 +439,7 @@ export class HocuspocusProvider extends EventEmitter {
   }
 
   get isAuthenticationRequired(): boolean {
-    return !!this.options.token && !this.isAuthenticated
+    return !!this.configuration.token && !this.isAuthenticated
   }
 
   disconnect() {
@@ -456,12 +466,12 @@ export class HocuspocusProvider extends EventEmitter {
   }
 
   async getToken() {
-    if (typeof this.options.token === 'function') {
-      const token = await this.options.token()
+    if (typeof this.configuration.token === 'function') {
+      const token = await this.configuration.token()
       return token
     }
 
-    return this.options.token
+    return this.configuration.token
   }
 
   async webSocketConnectionEstablished() {
@@ -535,15 +545,29 @@ export class HocuspocusProvider extends EventEmitter {
       this.emit('disconnect', { event })
     }
 
+    if (event.code === Unauthorized.code) {
+      if (!this.configuration.quiet) {
+        console.warn('[HocuspocusProvider] An authentication token is required, but you didn’t send one. Try adding a `token` to your HocuspocusProvider configuration. Won’t try again.')
+      }
+
+      this.shouldConnect = false
+    }
+
+    if (event.code === Forbidden.code) {
+      if (!this.configuration.quiet) {
+        console.warn('[HocuspocusProvider] The provided authentication token isn’t allowed to connect to this server. Will try again.')
+      }
+    }
+
     if (this.connectionAttempt) {
-      // Okay, that connection attempt failed …
+      // That connection attempt failed.
       this.rejectConnectionAttempt()
     } else if (this.shouldConnect) {
-      // The connection was closed by the server, so let’s just try again.
+      // The connection was closed by the server. Let’s just try again.
       this.connect()
     }
 
-    // If we’ll reconnect anyway, we’re done for now.
+    // If we’ll reconnect, we’re done for now.
     if (this.shouldConnect) {
       return
     }
@@ -590,7 +614,7 @@ export class HocuspocusProvider extends EventEmitter {
   }
 
   get broadcastChannel() {
-    return `${this.serverUrl}/${this.options.name}`
+    return `${this.serverUrl}/${this.configuration.name}`
   }
 
   broadcastChannelSubscriber(data: ArrayBuffer) {
@@ -631,7 +655,7 @@ export class HocuspocusProvider extends EventEmitter {
   }
 
   broadcast(Message: ConstructableOutgoingMessage, args?: any) {
-    if (!this.options.broadcast) {
+    if (!this.configuration.broadcast) {
       return
     }
 

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

@@ -1,4 +0,0 @@
-import { CloseEvent } from './types';
-export declare const Forbidden: CloseEvent;
-export declare const ResetConnection: CloseEvent;
-export declare const CloseEvents: CloseEvent[];