@styris-ame/y-engineio 1.1.0

package/src/y-engineio.js

@@ -0,0 +1,554 @@
+/**
+ * @module provider/engineio
+ */
+
+/* eslint-env browser */
+import * as Y from 'yjs' // eslint-disable-line
+import * as bc from 'lib0/broadcastchannel'
+import * as time from 'lib0/time'
+import * as encoding from 'lib0/encoding'
+import * as decoding from 'lib0/decoding'
+import * as syncProtocol from 'y-protocols/sync'
+import * as authProtocol from 'y-protocols/auth'
+import * as awarenessProtocol from 'y-protocols/awareness'
+import { ObservableV2 } from 'lib0/observable'
+import * as math from 'lib0/math'
+import * as url from 'lib0/url'
+import * as env from 'lib0/environment'
+import { Socket as Engine } from 'engine.io-client'
+
+export const messageSync = 0
+export const messageQueryAwareness = 3
+export const messageAwareness = 1
+export const messageAuth = 2
+
+/**
+ *                       encoder,          decoder,          provider,          emitSynced, messageType
+ * @type {Array<function(encoding.Encoder, decoding.Decoder, EngineIOProvider, boolean,    number):void>}
+ */
+const messageHandlers = []
+
+messageHandlers[messageSync] = (
+  encoder,
+  decoder,
+  provider,
+  emitSynced,
+  _messageType
+) => {
+  encoding.writeVarUint(encoder, messageSync)
+  const syncMessageType = syncProtocol.readSyncMessage(
+    decoder,
+    encoder,
+    provider.doc,
+    provider
+  )
+  if (
+    emitSynced && syncMessageType === syncProtocol.messageYjsSyncStep2 &&
+    !provider.synced
+  ) {
+    provider.synced = true
+  }
+}
+
+messageHandlers[messageQueryAwareness] = (
+  encoder,
+  _decoder,
+  provider,
+  _emitSynced,
+  _messageType
+) => {
+  encoding.writeVarUint(encoder, messageAwareness)
+  encoding.writeVarUint8Array(
+    encoder,
+    awarenessProtocol.encodeAwarenessUpdate(
+      provider.awareness,
+      Array.from(provider.awareness.getStates().keys())
+    )
+  )
+}
+
+messageHandlers[messageAwareness] = (
+  _encoder,
+  decoder,
+  provider,
+  _emitSynced,
+  _messageType
+) => {
+  awarenessProtocol.applyAwarenessUpdate(
+    provider.awareness,
+    decoding.readVarUint8Array(decoder),
+    provider
+  )
+}
+
+messageHandlers[messageAuth] = (
+  _encoder,
+  decoder,
+  provider,
+  _emitSynced,
+  _messageType
+) => {
+  authProtocol.readAuthMessage(
+    decoder,
+    provider.doc,
+    (_ydoc, reason) => permissionDeniedHandler(provider, reason)
+  )
+}
+
+const messageReconnectTimeout = 30000
+
+/**
+ * @param {EngineIOProvider} provider
+ * @param {string} reason
+ */
+const permissionDeniedHandler = (provider, reason) =>
+  console.warn(`Permission denied to access ${provider.url}.\n${reason}`)
+
+/**
+ * @param {ArrayBuffer | ArrayBufferView} data
+ * @return {Uint8Array}
+ */
+const toUint8Array = (data) =>
+  data instanceof ArrayBuffer
+    ? new Uint8Array(data)
+    : new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+
+/**
+ * @param {EngineIOProvider} provider
+ * @param {Uint8Array} buf
+ * @param {boolean} emitSynced
+ * @return {encoding.Encoder}
+ */
+const readMessage = (provider, buf, emitSynced) => {
+  const decoder = decoding.createDecoder(buf)
+  const encoder = encoding.createEncoder()
+  const messageType = decoding.readVarUint(decoder)
+  const messageHandler = provider.messageHandlers[messageType]
+  if (/** @type {any} */ (messageHandler)) {
+    messageHandler(encoder, decoder, provider, emitSynced, messageType)
+  }
+  return encoder
+}
+
+/**
+ * Outsource this function so that a new engine.io connection is created immediately.
+ * I suspect that the `close` event is not always fired if there are network issues.
+ *
+ * @param {EngineIOProvider} provider
+ * @param {Engine} engine
+ * @param {any} event
+ */
+const closeEngineConnection = (provider, engine, event) => {
+  if (engine === provider.engine) {
+    provider.emit('connection-close', [event, provider])
+    provider.engine = null
+    const anyEngine = /** @type {any} */ (engine)
+    if (anyEngine._yUnsubscribe) {
+      anyEngine._yUnsubscribe()
+    }
+    engine.close()
+    provider.connecting = false
+    if (provider.connected) {
+      provider.connected = false
+      provider.synced = false
+      // update awareness (all users except local left)
+      awarenessProtocol.removeAwarenessStates(
+        provider.awareness,
+        Array.from(provider.awareness.getStates().keys()).filter((client) =>
+          client !== provider.doc.clientID
+        ),
+        provider
+      )
+      provider.emit('status', [{
+        status: 'disconnected'
+      }])
+    } else {
+      provider.unsuccessfulReconnects++
+    }
+    // Start with no reconnect timeout and increase timeout by
+    // using exponential backoff starting with 100ms
+    setTimeout(
+      setupEngine,
+      math.min(
+        math.pow(2, provider.unsuccessfulReconnects) * 100,
+        provider.maxBackoffTime
+      ),
+      provider
+    )
+  }
+}
+
+/**
+ * @param {EngineIOProvider} provider
+ */
+const setupEngine = (provider) => {
+  if (provider.shouldConnect && provider.engine === null) {
+    const engine = new provider._Engine(provider.serverUrl, {
+      ...provider.engineOptions,
+      query: { ...provider.params, room: provider.roomname }
+    })
+    engine.binaryType = 'arraybuffer'
+    provider.engine = engine
+    provider.connecting = true
+    provider.connected = false
+    provider.synced = false
+
+    const onMessage = (/** @type {any} */ data) => {
+      if (provider.engine !== engine) return
+      if (typeof data === 'string') return
+      provider.lastMessageReceived = time.getUnixTime()
+      const encoder = readMessage(provider, toUint8Array(data), true)
+      if (encoding.length(encoder) > 1) {
+        engine.send(encoding.toUint8Array(encoder))
+      }
+    }
+    const onError = (/** @type {any} */ event) => {
+      if (provider.engine !== engine) return
+      provider.emit('connection-error', [event, provider])
+    }
+    const onPing = () => {
+      if (provider.engine !== engine) return
+      provider.lastMessageReceived = time.getUnixTime()
+    }
+    const onClose = (/** @type {any} */ reason, /** @type {any} */ description) => {
+      closeEngineConnection(provider, engine, { reason, description })
+    }
+    const onOpen = () => {
+      if (provider.engine !== engine) return
+      provider.lastMessageReceived = time.getUnixTime()
+      provider.connecting = false
+      provider.connected = true
+      provider.unsuccessfulReconnects = 0
+      provider.emit('status', [{
+        status: 'connected'
+      }])
+      // always send sync step 1 when connected
+      const encoder = encoding.createEncoder()
+      encoding.writeVarUint(encoder, messageSync)
+      syncProtocol.writeSyncStep1(encoder, provider.doc)
+      engine.send(encoding.toUint8Array(encoder))
+      // broadcast local awareness state
+      if (provider.awareness.getLocalState() !== null) {
+        const encoderAwarenessState = encoding.createEncoder()
+        encoding.writeVarUint(encoderAwarenessState, messageAwareness)
+        encoding.writeVarUint8Array(
+          encoderAwarenessState,
+          awarenessProtocol.encodeAwarenessUpdate(provider.awareness, [
+            provider.doc.clientID
+          ])
+        )
+        engine.send(encoding.toUint8Array(encoderAwarenessState))
+      }
+    }
+    engine.on('message', onMessage)
+    engine.on('error', onError)
+    engine.on('ping', onPing)
+    engine.on('close', onClose)
+    engine.on('open', onOpen)
+    const anyEngine = /** @type {any} */ (engine)
+    anyEngine._yUnsubscribe = () => {
+      engine.off('message', onMessage)
+      engine.off('error', onError)
+      engine.off('ping', onPing)
+      engine.off('close', onClose)
+      engine.off('open', onOpen)
+    }
+    provider.emit('status', [{
+      status: 'connecting'
+    }])
+  }
+}
+
+/**
+ * @param {EngineIOProvider} provider
+ * @param {Uint8Array} buf
+ */
+const broadcastMessage = (provider, buf) => {
+  const engine = provider.engine
+  if (provider.connected && engine && engine.readyState === 'open') {
+    engine.send(buf)
+  }
+  if (provider.bcconnected) {
+    bc.publish(provider.bcChannel, buf, provider)
+  }
+}
+
+/**
+ * Engine.IO Provider for Yjs. Creates an engine.io connection to sync the shared
+ * document. Unlike a raw WebSocket, engine.io connects to a single endpoint and
+ * has no document name in the URL, so the room name is sent as the `room`
+ * handshake query parameter, letting the server accept or reject the connection
+ * before any sync frames are exchanged.
+ *
+ * @example
+ *   import * as Y from 'yjs'
+ *   import { EngineIOProvider } from '@styris-ame/y-engineio'
+ *   const doc = new Y.Doc()
+ *   const provider = new EngineIOProvider('http://localhost:1234', 'my-document-name', doc)
+ *
+ * @extends {ObservableV2<{ 'connection-close': (event: any,  provider: EngineIOProvider) => any, 'status': (event: { status: 'connected' | 'disconnected' | 'connecting' }) => any, 'connection-error': (event: any, provider: EngineIOProvider) => any, 'sync': (state: boolean) => any, 'synced': (state: boolean) => any }>}
+ */
+export class EngineIOProvider extends ObservableV2 {
+  /**
+   * @param {string} serverUrl engine.io server origin, e.g. 'http://localhost:1234'
+   * @param {string} roomname
+   * @param {Y.Doc} doc
+   * @param {object} opts
+   * @param {boolean} [opts.connect]
+   * @param {awarenessProtocol.Awareness} [opts.awareness]
+   * @param {Object<string,string>} [opts.params] url query params, passed to engine.io as `query`
+   * @param {object} [opts.engineOptions] options forwarded to the engine.io-client `Socket` (e.g. `path`, `transports`, `withCredentials`, `extraHeaders`)
+   * @param {typeof Engine} [opts.EngineClass] override the engine.io `Socket` constructor (e.g. for testing)
+   * @param {number} [opts.resyncInterval] Request server state every `resyncInterval` milliseconds
+   * @param {number} [opts.maxBackoffTime] Maximum amount of time to wait before trying to reconnect (we try to reconnect using exponential backoff)
+   * @param {boolean} [opts.disableBc] Disable cross-tab BroadcastChannel communication
+   */
+  constructor (serverUrl, roomname, doc, {
+    connect = true,
+    awareness = new awarenessProtocol.Awareness(doc),
+    params = {},
+    engineOptions = {},
+    EngineClass = Engine,
+    resyncInterval = -1,
+    maxBackoffTime = 2500,
+    disableBc = false
+  } = {}) {
+    super()
+    // ensure that serverUrl does not end with /
+    while (serverUrl[serverUrl.length - 1] === '/') {
+      serverUrl = serverUrl.slice(0, serverUrl.length - 1)
+    }
+    this.serverUrl = serverUrl
+    this.bcChannel = serverUrl + '/' + roomname
+    this.maxBackoffTime = maxBackoffTime
+    /**
+     * The specified url parameters. This can be safely updated. The changed parameters will be used
+     * when a new connection is established.
+     * @type {Object<string,string>}
+     */
+    this.params = params
+    /**
+     * Options forwarded verbatim to the engine.io-client `Socket`.
+     * @type {object}
+     */
+    this.engineOptions = engineOptions
+    this.roomname = roomname
+    this.doc = doc
+    this._Engine = EngineClass
+    this.awareness = awareness
+    this.connected = false
+    this.connecting = false
+    this.bcconnected = false
+    this.disableBc = disableBc
+    this.unsuccessfulReconnects = 0
+    this.messageHandlers = messageHandlers.slice()
+    /**
+     * @type {boolean}
+     */
+    this._synced = false
+    /**
+     * The engine.io-client `Socket`, or null when disconnected.
+     * @type {Engine?}
+     */
+    this.engine = null
+    this.lastMessageReceived = 0
+    /**
+     * Whether to connect to other peers or not
+     * @type {boolean}
+     */
+    this.shouldConnect = connect
+
+    /**
+     * @type {number}
+     */
+    this._resyncInterval = 0
+    if (resyncInterval > 0) {
+      this._resyncInterval = /** @type {any} */ (setInterval(() => {
+        if (this.engine && this.engine.readyState === 'open') {
+          // resend sync step 1
+          const encoder = encoding.createEncoder()
+          encoding.writeVarUint(encoder, messageSync)
+          syncProtocol.writeSyncStep1(encoder, doc)
+          this.engine.send(encoding.toUint8Array(encoder))
+        }
+      }, resyncInterval))
+    }
+
+    /**
+     * @param {ArrayBuffer} data
+     * @param {any} origin
+     */
+    this._bcSubscriber = (data, origin) => {
+      if (origin !== this) {
+        const encoder = readMessage(this, new Uint8Array(data), false)
+        if (encoding.length(encoder) > 1) {
+          bc.publish(this.bcChannel, encoding.toUint8Array(encoder), this)
+        }
+      }
+    }
+    /**
+     * Listens to Yjs updates and sends them to remote peers (engine.io and broadcastchannel)
+     * @param {Uint8Array} update
+     * @param {any} origin
+     */
+    this._updateHandler = (update, origin) => {
+      if (origin !== this) {
+        const encoder = encoding.createEncoder()
+        encoding.writeVarUint(encoder, messageSync)
+        syncProtocol.writeUpdate(encoder, update)
+        broadcastMessage(this, encoding.toUint8Array(encoder))
+      }
+    }
+    this.doc.on('update', this._updateHandler)
+    /**
+     * @param {any} changed
+     * @param {any} _origin
+     */
+    this._awarenessUpdateHandler = ({ added, updated, removed }, _origin) => {
+      const changedClients = added.concat(updated).concat(removed)
+      const encoder = encoding.createEncoder()
+      encoding.writeVarUint(encoder, messageAwareness)
+      encoding.writeVarUint8Array(
+        encoder,
+        awarenessProtocol.encodeAwarenessUpdate(awareness, changedClients)
+      )
+      broadcastMessage(this, encoding.toUint8Array(encoder))
+    }
+    this._exitHandler = () => {
+      awarenessProtocol.removeAwarenessStates(
+        this.awareness,
+        [doc.clientID],
+        'app closed'
+      )
+    }
+    if (env.isNode && typeof process !== 'undefined') {
+      process.on('exit', this._exitHandler)
+    }
+    awareness.on('update', this._awarenessUpdateHandler)
+    this._checkInterval = /** @type {any} */ (setInterval(() => {
+      if (
+        this.connected &&
+        messageReconnectTimeout <
+          time.getUnixTime() - this.lastMessageReceived
+      ) {
+        // no message received in a long time - not even your own awareness
+        // updates (which are updated every 15 seconds)
+        closeEngineConnection(this, /** @type {Engine} */ (this.engine), null)
+      }
+    }, messageReconnectTimeout / 10))
+    if (connect) {
+      this.connect()
+    }
+  }
+
+  get url () {
+    const encodedParams = url.encodeQueryParams({ ...this.params, room: this.roomname })
+    return this.serverUrl + (encodedParams.length === 0 ? '' : '?' + encodedParams)
+  }
+
+  /**
+   * @type {boolean}
+   */
+  get synced () {
+    return this._synced
+  }
+
+  set synced (state) {
+    if (this._synced !== state) {
+      this._synced = state
+      // @ts-ignore
+      this.emit('synced', [state])
+      this.emit('sync', [state])
+    }
+  }
+
+  destroy () {
+    if (this._resyncInterval !== 0) {
+      clearInterval(this._resyncInterval)
+    }
+    clearInterval(this._checkInterval)
+    this.disconnect()
+    if (env.isNode && typeof process !== 'undefined') {
+      process.off('exit', this._exitHandler)
+    }
+    this.awareness.off('update', this._awarenessUpdateHandler)
+    this.doc.off('update', this._updateHandler)
+    super.destroy()
+  }
+
+  connectBc () {
+    if (this.disableBc) {
+      return
+    }
+    if (!this.bcconnected) {
+      bc.subscribe(this.bcChannel, this._bcSubscriber)
+      this.bcconnected = true
+    }
+    // send sync step1 to bc
+    // write sync step 1
+    const encoderSync = encoding.createEncoder()
+    encoding.writeVarUint(encoderSync, messageSync)
+    syncProtocol.writeSyncStep1(encoderSync, this.doc)
+    bc.publish(this.bcChannel, encoding.toUint8Array(encoderSync), this)
+    // broadcast local state
+    const encoderState = encoding.createEncoder()
+    encoding.writeVarUint(encoderState, messageSync)
+    syncProtocol.writeSyncStep2(encoderState, this.doc)
+    bc.publish(this.bcChannel, encoding.toUint8Array(encoderState), this)
+    // write queryAwareness
+    const encoderAwarenessQuery = encoding.createEncoder()
+    encoding.writeVarUint(encoderAwarenessQuery, messageQueryAwareness)
+    bc.publish(
+      this.bcChannel,
+      encoding.toUint8Array(encoderAwarenessQuery),
+      this
+    )
+    // broadcast local awareness state
+    const encoderAwarenessState = encoding.createEncoder()
+    encoding.writeVarUint(encoderAwarenessState, messageAwareness)
+    encoding.writeVarUint8Array(
+      encoderAwarenessState,
+      awarenessProtocol.encodeAwarenessUpdate(this.awareness, [
+        this.doc.clientID
+      ])
+    )
+    bc.publish(
+      this.bcChannel,
+      encoding.toUint8Array(encoderAwarenessState),
+      this
+    )
+  }
+
+  disconnectBc () {
+    // broadcast message with local awareness state set to null (indicating disconnect)
+    const encoder = encoding.createEncoder()
+    encoding.writeVarUint(encoder, messageAwareness)
+    encoding.writeVarUint8Array(
+      encoder,
+      awarenessProtocol.encodeAwarenessUpdate(this.awareness, [
+        this.doc.clientID
+      ], new Map())
+    )
+    broadcastMessage(this, encoding.toUint8Array(encoder))
+    if (this.bcconnected) {
+      bc.unsubscribe(this.bcChannel, this._bcSubscriber)
+      this.bcconnected = false
+    }
+  }
+
+  disconnect () {
+    this.shouldConnect = false
+    this.disconnectBc()
+    if (this.engine !== null) {
+      closeEngineConnection(this, this.engine, null)
+    }
+  }
+
+  connect () {
+    this.shouldConnect = true
+    if (!this.connected && this.engine === null) {
+      setupEngine(this)
+      this.connectBc()
+    }
+  }
+}