@soundworks/core 4.0.0-alpha.1 → 4.0.0-alpha.11

package/src/client/Socket.js

@@ -1,3 +1,5 @@
+import { isBrowser } from '@ircam/sc-utils';
+import fetch from 'cross-fetch';
 import WebSocket from 'isomorphic-ws';
 
 import {
@@ -7,7 +9,6 @@ import {
   unpackStringMessage,
 } from '../common/sockets-utils.js';
 import logger from '../common/logger.js';
-import { isBrowser } from '../common/utils.js';
 
 // WebSocket events:
 //
@@ -28,35 +29,34 @@ import { isBrowser } from '../common/utils.js';
 /**
  * The Socket class is a simple publish / subscribe wrapper built on top of the
  * [isomorphic-ws](https://github.com/heineiuo/isomorphic-ws) library.
- * An instance of `Socket` is automatically created by the `soundworks.Client`.
+ * An instance of `Socket` is automatically created by the `soundworks.Client`
+ * (see {@link client.Client#socket}).
  *
- * _Important: In most cases, you should consider using a {@link client.SharedState} rather than
- * sending messages directly through the sockets._
+ * _Important: In most cases, you should consider using a {@link client.SharedState}
+ * rather than directly using the sockets._
  *
  * The Socket class concurrently opens two different WebSockets:
- * - a socket configured with `binaryType = 'string'` for JSON compatible string
- *  messages.
- * - a socket configured with `binaryType=arraybuffer` for efficient streaming
+ * - a socket configured with `binaryType = 'blob'` for JSON compatible data
+ *  types (i.e. string, number, boolean, object, array and null).
+ * - a socket configured with `binaryType= 'arraybuffer'` for efficient streaming
  *  of binary data.
  *
  * Both sockets re-emits all "native" ws events ('open', 'upgrade', 'close', 'error'
  *  and 'message'.
  *
- * See {@link client.Client#socket}
- *
  * @memberof client
  * @hideconstructor
  */
 class Socket {
   constructor() {
     /**
-     * WebSocket instance w/ string protocol, i.e. `binaryType = 'string'`.
+     * WebSocket instance configured with `binaryType = 'blob'`.
      *
      * @private
      */
     this.ws = null;
     /**
-     * WebSocket instance w/ binary protocol, i.e. `binaryType = 'arraybuffer'`.
+     * WebSocket instance configured with `binaryType = 'arraybuffer'`.
      *
      * @private
      */
@@ -111,7 +111,11 @@ class Socket {
       };
     }
 
-    const queryParams = `role=${role}&key=${key}`;
+    let queryParams = `role=${role}&key=${key}`;
+
+    if (config.token) {
+      queryParams += `&token=${config.token}`;
+    }
 
     // ----------------------------------------------------------
     // init string socket
@@ -147,19 +151,22 @@ class Socket {
 
         // cf. https://github.com/collective-soundworks/soundworks/issues/17
         ws.addEventListener('error', e => {
-          if (e.type === 'error' && e.error.code === 'ECONNREFUSED') {
-            if (!connectionRefusedLogged) {
-              logger.log('[soundworks.Socket] Connection refused, waiting for the server to start');
-              connectionRefusedLogged = true;
-            }
-
+          if (e.type === 'error') {
             if (ws.terminate) {
               ws.terminate();
             } else {
               ws.close();
             }
 
-            setTimeout(trySocket, 1000);
+            // for node clients, retry connection
+            if (e.error && e.error.code === 'ECONNREFUSED') {
+              if (!connectionRefusedLogged) {
+                logger.log('[soundworks.Socket] Connection refused, waiting for the server to start');
+                connectionRefusedLogged = true;
+              }
+
+              setTimeout(trySocket, 1000);
+            }
           }
         });
       };
@@ -231,6 +238,22 @@ class Socket {
     return Promise.resolve();
   }
 
+  /**
+   * Removes all listeners and immediately close the two sockets. Is automatically
+   * called on `client.stop()`
+   *
+   * @private
+   */
+  async terminate() {
+    this.removeAllListeners();
+    this.removeAllBinaryListeners();
+
+    this.ws.close();
+    this.binaryWs.close();
+
+    return Promise.resolve();
+  }
+
   /**
    * @param {boolean} binary - Emit to either the string or binary socket.
    * @param {string} channel - Channel name.
@@ -293,10 +316,11 @@ class Socket {
   }
 
   /**
-   * Send JSON compatible messages on a given channel.
+   * Send messages with JSON compatible data types on a given channel.
    *
-   * @param {string} channel - Channel name of the message.
-   * @param {...*} args - Message list, as many as needed, of any serializable type).
+   * @param {string} channel - Channel name.
+   * @param {...*} args - Payload of the message. As many arguments as needed, of
+   *  JSON compatible data types (i.e. string, number, boolean, object, array and null).
    */
   send(channel, ...args) {
     const msg = packStringMessage(channel, ...args);
@@ -304,10 +328,12 @@ class Socket {
   }
 
   /**
-   * Listen to JSON compatible messages on a given channel.
+   * Listen messages with JSON compatible data types on a given channel.
    *
-   * @param {string} channel - Channel name of the message.
-   * @param {Function} callback - Callback to execute when a message is received.
+   * @param {string} channel - Channel name.
+   * @param {Function} callback - Callback to execute when a message is received,
+   *  arguments of the callback function will match the arguments sent using the
+   *  {@link server.Socket#send} method.
    */
   addListener(channel, callback) {
     this._addListener(this._stringListeners, channel, callback);
@@ -316,7 +342,7 @@ class Socket {
   /**
    * Remove a listener from JSON compatible messages on a given channel.
    *
-   * @param {string} channel - Channel name of the message.
+   * @param {string} channel - Channel name.
    * @param {Function} callback - Callback to remove.
    */
   removeListener(channel, callback) {
@@ -324,9 +350,9 @@ class Socket {
   }
 
   /**
-   * Remove all listeners from JSON compatible messages on a given channel.
+   * Remove all listeners of messages with JSON compatible data types.
    *
-   * @param {string} channel - Channel name of the message.
+   * @param {string} channel - Channel name.
    */
   removeAllListeners(channel = null) {
     this._removeAllListeners(this._stringListeners, channel);
@@ -335,7 +361,7 @@ class Socket {
   /**
    * Send binary messages on a given channel.
    *
-   * @param {string} channel - Channel name of the message.
+   * @param {string} channel - Channel name.
    * @param {TypedArray} typedArray - Binary data to be sent.
    */
   sendBinary(channel, typedArray) {
@@ -344,9 +370,9 @@ class Socket {
   }
 
   /**
-   * Listen binary messages on a given channel.
+   * Listen binary messages on a given channel
    *
-   * @param {string} channel - Channel name of the message.
+   * @param {string} channel - Channel name.
    * @param {Function} callback - Callback to execute when a message is received.
    */
   addBinaryListener(channel, callback) {
@@ -354,36 +380,23 @@ class Socket {
   }
 
   /**
-   * Remove a listener from binary compatible messages on a given channel
+   * Remove a listener of binary compatible messages from a given channel
    *
-   * @param {string} channel - Channel of the message.
-   * @param {Function} callback - Callback to cancel.
+   * @param {string} channel - Channel name.
+   * @param {Function} callback - Callback to remove.
    */
   removeBinaryListener(channel, callback) {
     this._removeListener(this._binaryListeners, channel, callback);
   }
 
   /**
-   * Remove all listeners from binary compatible messages on a given channel
+   * Remove all listeners of binary compatible messages on a given channel
    *
    * @param {string} channel - Channel of the message.
    */
   removeAllBinaryListeners(channel = null) {
     this._removeAllListeners(this._binaryListeners, channel);
   }
-
-  /**
-   * Removes all listeners and immediately close the two sockets.
-   */
-  async terminate() {
-    this.removeAllListeners();
-    this.removeAllBinaryListeners();
-
-    this.ws.close();
-    this.binaryWs.close();
-
-    return Promise.resolve();
-  }
 }
 
 export default Socket;

package/src/client/index.js

@@ -1,36 +1,3 @@
-/**
- * Configuration object for a client running in a browser runtime.
- *
- * @typedef BrowserClientConfig
- * @memberof client
- * @type {object}
- * @property {string} role - Role of the client in the application (e.g. 'player', 'controller').
- * @property {object} [app] - Application configration object.
- * @property {string} [app.name=''] - Name of the application.
- * @property {string} [app.author=''] - Name of the author.
- * @property {object} [env] - Environment configration object.
- * @property {string} [env.websockets={}] - Configuration options for websockets.
- * @property {string} [env.subpath=''] - If running behind a proxy, path to the application.
- */
-
-/**
- * Configuration object for a client running in a node runtime.
- *
- * @typedef NodeClientConfig
- * @memberof client
- * @type {object}
- * @property {string} role - Role of the client in the application (e.g. 'player', 'controller').
- * @property {object} [app] - Application configration object.
- * @property {string} [app.name=''] - Name of the application.
- * @property {string} [app.author=''] - Name of the author.
- * @property {object} env - Environment configration object.
- * @property {boolean} env.serverAddress - Domain name or IP of the server.
- * @property {boolean} env.useHttps - Define is the server run in http or in https.
- * @property {boolean} env.port - Port on which the server is listening.
- * @property {string} [env.websockets={}] - Configuration options for websockets.
- * @property {string} [env.subpath=''] - If running behind a proxy, path to the application.
- */
-
 /**
  * Client-side part of the `soundworks` framework.
  *

package/src/common/BasePlugin.js

@@ -5,26 +5,10 @@ import merge from 'lodash.merge';
  */
 class BasePlugin {
   constructor(id) {
-    /**
-     * User defined ID of the plugin.
-     *
-     * @type {string}
-     * @see {@link client.PluginManager#register}
-     * @see {@link server.PluginManager#register}
-     */
-    this.id = id;
-
-    /**
-     * Type of the plugin, i.e. the ClassName.
-     *
-     * Usefull to do perform some logic based on certain types of plugins without
-     * knowing under which `id` they have been registered. (e.g. creating some generic
-     * views, etc.)
-     *
-     * @type {string}
-     * @readonly
-     */
-    this.type = this.constructor.name;
+    /** @private */
+    this._id = id;
+    /** @private */
+    this._type = this.constructor.name;
 
     /**
      * Options of the plugin.
@@ -58,6 +42,32 @@ class BasePlugin {
     this._onStateChangeCallbacks = new Set();
   }
 
+  /**
+   * User defined ID of the plugin.
+   *
+   * @type {string}
+   * @readonly
+   * @see {@link client.PluginManager#register}
+   * @see {@link server.PluginManager#register}
+   */
+  get id() {
+    return this._id;
+  }
+
+  /**
+   * Type of the plugin, i.e. the ClassName.
+   *
+   * Usefull to do perform some logic based on certain types of plugins without
+   * knowing under which `id` they have been registered. (e.g. creating some generic
+   * views, etc.)
+   *
+   * @type {string}
+   * @readonly
+   */
+  get type() {
+    return this._type;
+  }
+
   /**
    * Start the plugin. This method is automatically called during the client or
    * server `init()` lifecyle step. After `start()` is fulfilled the plugin should

package/src/common/BasePluginManager.js

@@ -1,7 +1,6 @@
-import isPlainObject from 'is-plain-obj';
+import { isPlainObject, isString } from '@ircam/sc-utils';
 
 import logger from './logger.js';
-import { isString } from './utils.js';
 
 /**
  * Shared functionnality between server-side and client-size plugin manager
@@ -14,7 +13,7 @@ class BasePluginManager {
     /** @private */
     this._node = node;
     /** @private */
-    this._registeredPlugins = new Map();
+    this._dependencies = new Map();
     /** @private */
     this._instances = new Map();
     /** @private */
@@ -68,11 +67,37 @@ class BasePluginManager {
       throw new Error(`[soundworks.PluginManager] Invalid argument, "pluginManager.register" fourth optionnal argument should be an array`);
     }
 
-    if (this._registeredPlugins.has(id)) {
-      throw new Error(`[soundworks:PluginManager] Plugin "${id}" of type "${ctor.name}" already registered`);
+    if (this._instances.has(id)) {
+      throw new Error(`[soundworks:PluginManager] Plugin "${id}" already registered`);
     }
 
-    this._registeredPlugins.set(id, { ctor, options, deps });
+    // we instanciate the plugin here, so that a plugin can register another one
+    // in its own constructor.
+    //
+    // the dependencies must be created first, so that the instance can call
+    // addDependency in its constructor
+    this._dependencies.set(id, deps);
+
+    const instance = new ctor(this._node, id, options);
+    this._instances.set(id, instance);
+  }
+
+  /**
+   * Manually add a dependency to a given plugin. Usefull to require a plugin
+   * within a plugin
+   *
+   */
+  addDependency(pluginId, dependencyId) {
+    const deps = this._dependencies.get(pluginId);
+    deps.push(dependencyId);
+  }
+
+  /**
+   * Returns the list of the registered plugins ids
+   * @returns {string[]}
+   */
+  getRegisteredPlugins() {
+    return Array.from(this._instances.keys());
   }
 
   /**
@@ -89,26 +114,25 @@ class BasePluginManager {
 
     this.status = 'inited';
     // instanciate all plugins
-    for (let [id, { ctor, options }] of this._registeredPlugins.entries()) {
-      const instance = new ctor(this._node, id, options);
-      this._instances.set(id, instance);
+    for (let [id, instance] of this._instances.entries()) {
       instance.onStateChange(_values => this._propagateStateChange(instance));
     }
 
     // propagate all 'idle' statuses before start
     this._propagateStateChange();
 
-    const promises = Array.from(this._registeredPlugins.keys()).map(id => this.getUnsafe(id));
+    const promises = Array.from(this._instances.keys()).map(id => this.unsafeGet(id));
 
     try {
       await Promise.all(promises);
       this.status = 'started';
-    } catch(err) {
+    } catch (err) {
       this.status = 'errored';
-      throw new Error(err);
+      throw err; // throw initial error
     }
   }
 
+  /** @private */
   async stop() {
     for (let instance of this._instances.values()) {
       await instance.stop();
@@ -117,17 +141,17 @@ class BasePluginManager {
 
   /**
    * Retrieve an fully started instance of a registered plugin, without checking
-   * that the pluginManager is started. This is important for starting the plugin
-   * manager itself.
+   * that the pluginManager has started. This is required for starting the plugin
+   * manager itself and to require a plugin from within another plugin
    *
    * @private
    */
-  async getUnsafe(id) {
+  async unsafeGet(id) {
     if (!isString(id)) {
       throw new Error(`[soundworks.PluginManager] Invalid argument, "pluginManager.get(name)" argument should be a string`);
     }
 
-    if (!this._registeredPlugins.has(id)) {
+    if (!this._instances.has(id)) {
       throw new Error(`[soundworks:PluginManager] Cannot get plugin "${id}", plugin is not registered`);
     }
 
@@ -136,7 +160,7 @@ class BasePluginManager {
     // to dynamically register and launch plugins at runtime.
     //
     // if (!this._instances.has(id)) {
-    //   const { ctor, options } = this._registeredPlugins.get(id);
+    //   const { ctor, options } = this._dependencies.get(id);
     //   const instance = new ctor(this._node, id, options);
     //   this._instances.set(id, instance);
     // }
@@ -144,8 +168,8 @@ class BasePluginManager {
     const instance = this._instances.get(id);
 
     // recursively get the dependency chain
-    const { deps } = this._registeredPlugins.get(id);
-    const promises = deps.map(id => this.getUnsafe(id));
+    const deps = this._dependencies.get(id);
+    const promises = deps.map(id => this.unsafeGet(id));
 
     await Promise.all(promises);
 
@@ -161,7 +185,7 @@ class BasePluginManager {
         this._instanceStartPromises.set(id, startPromise);
 
         await startPromise;
-      } catch(err) {
+      } catch (err) {
         errored = true;
         this._propagateStateChange(instance, 'errored');
         throw err;