@soundworks/core 3.7.0 → 4.0.0-alpha.0

package/src/server/SharedState.js

@@ -0,0 +1,86 @@
+import BaseSharedState from '../common/BaseSharedState.js';
+
+// this file exists only for documentation purposes
+
+/**
+ * @callback server.SharedState~onUpdateCallback
+ * @param {Object} newValues - Key / value pairs of the updates that have been
+ *  applied to the state.
+ * @param {Object} oldValues - Key / value pairs of the updated params before
+ *  the updates has been applied to the state.
+ * @param {Mixed} [context=null] - Optionnal context object that has been passed
+ *  with the values updates in the `set` call.
+ */
+
+/**
+ * Delete the registered {@link server.SharedState~onUpdateCallback}.
+ *
+ * @callback server.SharedState~deleteOnUpdateCallback
+ */
+
+
+/**
+ * The `SharedState` is one of the most important and versatile abstraction provided
+ * by `soundworks`. It represents a set of parameters that are synchronized accross
+ * every nodes of the application (clients and server) that declared some interest
+ * to the shared state.
+ *
+ * A `SharedState` is created according to a "schema" (in the sense of a database
+ * schema) that must be declared and registered server-side. Any number of `SharedState`s
+ * can be created from a single schema.
+ *
+ * A shared state can be created both by the clients or by the server (in which case
+ * it is generally considered as a global state of the application). Similarly any
+ * node of the application (clients or server) can declare interest and "attach" to
+ * a state created by another node. All node attached to a state can modify its values
+ * and/or react to the modifications applied by other nodes.
+ *
+ * Tutorial: {@link https://soundworks.dev/guide/state-manager.html}
+ *
+ * ```
+ * // server-side
+ * import { Server } from '@soundworks/server/index.js';
+ *
+ * const server = new Server(config);
+ * // declare and register the schema of a shared state.
+ * server.stateManager.registerSchema('some-global-state', {
+ *   myRandom: {
+ *     type: 'float',
+ *     default: 0,
+ *   }
+ * });
+ *
+ * await server.start();
+ *
+ * // create a global state server-side
+ * const globalState = await server.stateManager.create('some-global-state');
+ * // listen and react to the changes made by the clients
+ * globalState.onUpdate(updates => console.log(updates));
+ * ```
+ *
+ * ```
+ * // client-side
+ * import { Client } from '@soundworks/client.index.js';
+ *
+ * const client = new Client(config);
+ * await client.start();
+ *
+ * // attach to the global state created by the server
+ * const globalState = await client.stateManager.attach('some-global-state');
+ *
+ * // update the value of a `myRandom` parameter every seconds
+ * setInterval(() => {
+ *   globalState.set({ myRandom: Math.random() });
+ * }, 1000);
+ * ``
+ *
+ * @memberof server
+ * @extends BaseSharedState
+ * @inheritdoc
+ * @hideconstructor
+ * @see {server.StateManager}
+ */
+class SharedState extends BaseSharedState {}
+
+export default SharedState;
+

package/{server → src/server}/Socket.js

@@ -1,13 +1,12 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-
-var _socketsEncoderDecoder = require("../common/sockets-encoder-decoder.js");
-
-const noop = () => {}; // const CONNECTING = 0;
+import { getTime } from '@ircam/sc-gettime';
+import {
+  packBinaryMessage,
+  unpackBinaryMessage,
+  packStringMessage,
+  unpackStringMessage,
+} from '../common/sockets-utils.js';
+
+// const CONNECTING = 0;
 // const OPEN = 1;
 // const CLOSING = 2;
 // const CLOSED = 3;
@@ -24,10 +23,9 @@ const noop = () => {}; // const CONNECTING = 0;
  *
  * @memberof server
  */
-
-
 class Socket {
   constructor(ws, binaryWs, rooms, sockets, options = {}) {
+
     /**
      * Reference to the sockets object, is mainly dedicated to allow
      * broadcasting from a given socket instance.
@@ -36,122 +34,163 @@ class Socket {
      * socket.sockets.broadcast('my-room', this, 'update-value', 1);
      */
     this.sockets = sockets;
+
     /**
      * `ws` socket instance configured with `binaryType=blob` (string)
      * @private
      * @type {Object}
      */
-
     this.ws = ws;
+
     /**
      * `ws` socket instance configured with `binaryType=arraybuffer` (TypedArray)
      * @private
      * @type {Object}
      */
-
     this.binaryWs = binaryWs;
+
     /**
      * `ws` socket instance configured with `binaryType=arraybuffer` (TypedArray)
      * @private
      * @type {Map}
      */
-
     this.rooms = rooms;
+
     /**
      * Configuration object
      * @type {Object}
      */
-
     this.config = {
       pingInterval: 5 * 1000,
-      ...options
+      ...options,
     };
+
     this._stringListeners = new Map();
-    this._binaryListeners = new Map(); // ----------------------------------------------------------
+    this._binaryListeners = new Map();
+
+    // ----------------------------------------------------------
     // init string socket
     // ----------------------------------------------------------
-
     this.ws.addEventListener('message', e => {
-      const [channel, args] = (0, _socketsEncoderDecoder.unpackStringMessage)(e.data);
-
+      const [channel, args] = unpackStringMessage(e.data);
       this._emit(false, channel, ...args);
-    }); // broadcast all `ws` "native" events
+    });
 
-    ['close', 'error', 'message', 'open', 'ping', 'pong', 'unexpected-response', 'upgrade'].forEach(eventName => {
+    // broadcast all `ws` "native" events
+    [
+      'close',
+      'error',
+      'message',
+      'open',
+      'ping',
+      'pong',
+      'unexpected-response',
+      'upgrade',
+    ].forEach(eventName => {
       this.ws.addEventListener(eventName, e => {
         this._emit(false, eventName, e.data);
       });
-    }); // ----------------------------------------------------------
+    });
+
+    // ----------------------------------------------------------
     // init binary socket
     // ----------------------------------------------------------
-
     this.binaryWs.addEventListener('message', e => {
-      const [channel, data] = (0, _socketsEncoderDecoder.unpackBinaryMessage)(e.data);
-
+      const [channel, data] = unpackBinaryMessage(e.data);
       this._emit(true, channel, data);
-    }); // broadcast all `ws` "native" events
+    });
 
-    ['close', 'error', 'message', 'open', 'ping', 'pong', 'unexpected-response', 'upgrade'].forEach(eventName => {
+    // broadcast all `ws` "native" events
+    [
+      'close',
+      'error',
+      'message',
+      'open',
+      'ping',
+      'pong',
+      'unexpected-response',
+      'upgrade',
+    ].forEach(eventName => {
       this.binaryWs.addEventListener(eventName, e => {
         this._emit(true, eventName, e.data);
       });
-    }); // heartbeat system (run only on string socket), adapted from:
-    // https://github.com/websockets/ws#how-to-detect-and-close-broken-connections
+    });
 
-    this._isAlive = true; // heartbeat system, only on "regular" socket
+    // heartbeat system (run only on string socket), adapted from:
+    // https://github.com/websockets/ws#how-to-detect-and-close-broken-connections
+    this._isAlive = true;
+    let msg = {
+      type: 'add-measurement',
+      value: {
+        ping: 0,
+        pong: 0,
+      },
+    };
 
+    // heartbeat system, only on "regular" socket
     this.ws.on('pong', () => {
       this._isAlive = true;
+
+      msg.value.pong = getTime();
+      this.sockets._latencyStatsWorker.postMessage(msg);
     });
+
     this._intervalId = setInterval(() => {
       if (this._isAlive === false) {
         // emit a 'close' event to go trough all the disconnection pipeline
         this._emit(false, 'close');
-
-        return; // return this.ws.terminate();
+        return;
       }
 
       this._isAlive = false;
-      this.ws.ping(noop);
+      msg.value.ping = getTime();
+
+      this.ws.ping();
     }, this.config.pingInterval);
-    this.ws.addListener('error', _err => {// console.log(this.clientId, err);
-    });
   }
+
   /**
    * Called when the string socket closes (aka client reload).
    */
-
   /** @private */
-
-
   terminate() {
-    clearInterval(this._intervalId); // clean rooms
-
+    // clear ping/pong check
+    clearInterval(this._intervalId);
+    // clean rooms
     for (let [_key, room] of this.rooms) {
       room.delete(this);
-    } // clear references to sockets and rooms
-
+    }
 
+    // clear references to sockets and rooms
     this.sockets = null;
-    this.rooms = null; // clear all listeners
+    this.rooms = null;
 
+    // clear all listeners
     this._stringListeners.clear();
-
-    this._binaryListeners.clear(); // clear "native" listeners
-
-
-    [this.binaryWs, this.ws].forEach(socket => {
-      ['close', 'error', 'message', 'open', 'ping', 'pong', 'unexpected-response', 'upgrade'].forEach(eventName => {
+    this._binaryListeners.clear();
+
+    // clear "native" listeners
+    [this.binaryWs, this.ws].forEach((socket) => {
+      [
+        'close',
+        'error',
+        'message',
+        'open',
+        'ping',
+        'pong',
+        'unexpected-response',
+        'upgrade',
+      ].forEach(eventName => {
         socket.removeAllListeners(eventName);
       });
-    }); // clear binarySocket as this is called from the string one.
+    });
 
+    // clear binarySocket as this is called from the string one.
     this.binaryWs.terminate();
     this.ws.terminate();
   }
-  /** @private */
-
 
+  /** @private */
   _emit(binary, channel, ...args) {
     const listeners = binary ? this._binaryListeners : this._stringListeners;
 
@@ -160,9 +199,8 @@ class Socket {
       callbacks.forEach(callback => callback(...args));
     }
   }
-  /** @private */
-
 
+  /** @private */
   _addListener(listeners, channel, callback) {
     if (!listeners.has(channel)) {
       listeners.set(channel, new Set());
@@ -171,9 +209,8 @@ class Socket {
     const callbacks = listeners.get(channel);
     callbacks.add(callback);
   }
-  /** @private */
-
 
+  /** @private */
   _removeListener(listeners, channel, callback) {
     if (listeners.has(channel)) {
       const callbacks = listeners.get(channel);
@@ -184,20 +221,18 @@ class Socket {
       }
     }
   }
-  /** @private */
-
 
+  /** @private */
   _removeAllListeners(listeners, channel) {
     if (listeners.has(channel)) {
       listeners.delete(channel);
     }
   }
+
   /**
    * Add the socket to a room
    * @param {String} roomId - Id of the room
    */
-
-
   addToRoom(roomId) {
     if (!this.rooms.has(roomId)) {
       this.rooms.set(roomId, new Set());
@@ -206,122 +241,113 @@ class Socket {
     const room = this.rooms.get(roomId);
     room.add(this);
   }
+
   /**
    * Remove the socket from a room
    * @param {String} roomId - Id of the room
    */
-
-
   removeFromRoom(roomId) {
     if (this.rooms.has(roomId)) {
       const room = this.rooms.get(roomId);
       room.delete(this);
     }
   }
+
   /**
    * Sends JSON compatible messages on a given channel
    *
    * @param {String} channel - Channel of the message
    * @param {...*} args - Arguments of the message (as many as needed, of any type)
    */
-
-
   send(channel, ...args) {
-    const msg = (0, _socketsEncoderDecoder.packStringMessage)(channel, ...args); // 0 CONNECTING  Socket has been created. The connection is not yet open.
+    const msg = packStringMessage(channel, ...args);
+
+    // 0 CONNECTING  Socket has been created. The connection is not yet open.
     // 1 OPEN  The connection is open and ready to communicate.
     // 2 CLOSING The connection is in the process of closing.
     // 3 CLOSED  The connection is closed or couldn't be opened.
-
     if (this.ws.readyState === 1) {
-      this.ws.send(msg, err => {
+      this.ws.send(msg, (err) => {
         if (err) {
           console.error('error sending msg:', channel, args, err);
         }
       });
     }
   }
+
   /**
    * Listen JSON compatible messages on a given channel
    *
    * @param {String} channel - Channel of the message
    * @param {Function} callback - Callback to execute when a message is received
    */
-
-
   addListener(channel, callback) {
     this._addListener(this._stringListeners, channel, callback);
   }
+
   /**
    * Remove a listener from JSON compatible messages on a given channel
    *
    * @param {String} channel - Channel of the message
    * @param {Function} callback - Callback to cancel
    */
-
-
   removeListener(channel, callback) {
     this._removeListener(this._stringListeners, channel, callback);
   }
+
   /**
    * Remove all listeners from JSON compatible messages on a given channel
    *
    * @param {String} channel - Channel of the message
    */
-
-
   removeAllListeners(channel) {
     this._removeAllListeners(this._stringListeners, channel);
   }
+
   /**
    * Sends binary messages on a given channel
    *
    * @param {String} channel - Channel of the message
    * @param {TypedArray} typedArray - Data to send
    */
-
-
   sendBinary(channel, typedArray) {
-    const msg = (0, _socketsEncoderDecoder.packBinaryMessage)(channel, typedArray);
-    this.binaryWs.send(msg, err => {
+    const msg = packBinaryMessage(channel, typedArray);
+
+    this.binaryWs.send(msg, (err) => {
       if (err) {
         console.error('error sending msg:', channel, typedArray);
       }
     });
   }
+
   /**
    * Listen binary messages on a given channel
    *
    * @param {String} channel - Channel of the message
    * @param {Function} callback - Callback to execute when a message is received
    */
-
-
   addBinaryListener(channel, callback) {
     this._addListener(this._binaryListeners, channel, callback);
   }
+
   /**
    * Remove a listener from binary compatible messages on a given channel
    *
    * @param {String} channel - Channel of the message
    * @param {Function} callback - Callback to cancel
    */
-
-
   removeBinaryListener(channel, callback) {
     this._removeListener(this._binaryListeners, channel, callback);
   }
+
   /**
    * Remove all listeners from binary compatible messages on a given channel
    *
    * @param {String} channel - Channel of the message
    */
-
-
   removeAllBinaryListeners(channel) {
     this._removeAllListeners(this._binaryListeners, channel);
   }
-
 }
 
-var _default = Socket;
-exports.default = _default;
+export default Socket;