@soundworks/core 4.0.0-alpha.7 → 5.0.0

package/src/server/SharedStatePrivate.js

@@ -0,0 +1,277 @@
+import ParameterBag from '../common/ParameterBag.js';
+import {
+  DELETE_REQUEST,
+  DELETE_RESPONSE,
+  DELETE_NOTIFICATION,
+  DETACH_REQUEST,
+  DETACH_RESPONSE,
+  UPDATE_REQUEST,
+  UPDATE_RESPONSE,
+  UPDATE_ABORT,
+  UPDATE_NOTIFICATION,
+} from '../common/constants.js';
+import {
+  kServerStateManagerDeletePrivateState,
+  kServerStateManagerGetUpdateHooks,
+} from '../server/ServerStateManager.js';
+
+/**
+ * Filter update object according to filter list.
+ * Return identity is filter is null
+ * @param {object} updates
+ * @param {array|null} filter
+ * @private
+ */
+function filterUpdates(updates, filter) {
+  if (filter === null) {
+    return updates;
+  }
+
+  return filter.reduce((acc, key) => {
+    if (key in updates) {
+      acc[key] = updates[key];
+    }
+    return acc;
+  }, {});
+}
+
+export const kSharedStatePrivateAttachClient = Symbol('soundworks:shared-state-private-attach-client');
+export const kSharedStatePrivateDetachClient = Symbol('soundworks:shared-state-private-detach-client');
+export const kSharedStatePrivateGetValues = Symbol('soundworks:shared-state-private-get-values');
+
+/**
+ * The "real" state, this instance is kept private by the server.StateManager.
+ * It can only be accessed through a SharedState proxy.
+ *
+ * @private
+ */
+class SharedStatePrivate {
+  #id = null;
+  #className = null;
+  #manager = null;
+  #parameters = null;
+  #creatorId = null;
+  #creatorInstanceId = null;
+  #attachedClients = new Map();
+
+  constructor(manager, className, classDefinition, id, initValues = {}) {
+    this.#manager = manager;
+    this.#className = className;
+    this.#id = id;
+    // This can throw but will be catch in ServerStateManager CREATE_REQUEST handler
+    this.#parameters = new ParameterBag(classDefinition, initValues);
+  }
+
+  get id() {
+    return this.#id;
+  }
+
+  get className() {
+    return this.#className;
+  }
+
+  get creatorId() {
+    return this.#creatorId;
+  }
+
+  get creatorInstanceId() {
+    return this.#creatorInstanceId;
+  }
+
+  get attachedClients() {
+    return this.#attachedClients;
+  }
+
+  get parameters() {
+    return this.#parameters;
+  }
+
+  [kSharedStatePrivateGetValues]() {
+    return this.#parameters.getValues();
+  }
+
+  [kSharedStatePrivateAttachClient](instanceId, client, isOwner, filter) {
+    const clientInfos = { client, isOwner, filter };
+    this.#attachedClients.set(instanceId, clientInfos);
+
+    if (isOwner) {
+      this.#creatorId = client.id;
+      this.#creatorInstanceId = instanceId;
+    }
+
+    // attach client listeners
+    client.transport.addListener(`${UPDATE_REQUEST}-${this.id}-${instanceId}`, async (reqId, updates) => {
+      // apply registered hooks
+      const hooks = this.#manager[kServerStateManagerGetUpdateHooks](this.className);
+      const values = this.#parameters.getValues();
+      let hookAborted = false;
+
+      // cf. https://github.com/collective-soundworks/soundworks/issues/45
+      for (let hook of hooks.values()) {
+        const result = await hook(updates, values);
+
+        if (result === null) { // explicit abort if hook returns null
+          hookAborted = true;
+          break;
+        } else if (result === undefined) { // implicit continue if hook returns undefined
+          continue;
+        } else { // the hook returned an updates object
+          updates = result;
+        }
+      }
+
+      if (hookAborted === false) {
+        let acknowledgedUpdates = {};
+        let hasUpdates = false;
+
+        for (let name in updates) {
+          const [newValue, changed] = this.#parameters.set(name, updates[name]);
+          // if `filterChange` is set to `false` we don't check if the value
+          // has been changed or not, it is always propagated to client states
+          const { event, filterChange } = this.#parameters.getDescription(name);
+
+          // if event type reset internal value to null
+          if (event) {
+            this.#parameters.set(name, null);
+          }
+
+          if ((filterChange && changed) || !filterChange) {
+            acknowledgedUpdates[name] = newValue;
+            hasUpdates = true;
+          }
+        }
+
+        if (hasUpdates) {
+          // Normal case
+          //
+          // We need to handle cases where:
+          // - client state (client.id: 2) sends a request
+          // - server attached state (client.id: -1) spot a problem and overrides the value
+          // We want the remote client (id: 2) to receive in the right order:
+          // * 1. the value it requested,
+          // * 2. the value overridden by the server-side attached state (id: -1)
+          //
+          // This problem is now better solved with the the updateHook system,
+          // nevertheless we don't want to introduce inconsistencies here
+          //
+          // Then we propagate server-side last, because as the server transport
+          // is synchronous it can break ordering if a subscription function makes
+          // itself an update in reaction to an update. Propagating to server last
+          // allows to maintain network messages order consistent.
+          //
+          // @note - instanceId correspond to unique remote state id
+
+          // propagate RESPONSE to the client that originates the request if not the server
+          if (client.id !== -1) {
+            // no need to filter updates on requested, is blocked on client-side
+            client.transport.emit(
+              `${UPDATE_RESPONSE}-${this.id}-${instanceId}`,
+              reqId,
+              acknowledgedUpdates,
+            );
+          }
+
+          // propagate NOTIFICATION to all attached clients except server
+          for (let [peerInstanceId, clientInfos] of this.#attachedClients) {
+            const peer = clientInfos.client;
+
+            if (instanceId !== peerInstanceId && peer.id !== -1) {
+              const filter = clientInfos.filter;
+              const filteredUpdates = filterUpdates(acknowledgedUpdates, filter);
+
+              // propagate only if there something left after applying the filter
+              if (Object.keys(filteredUpdates).length > 0) {
+                peer.transport.emit(
+                  `${UPDATE_NOTIFICATION}-${this.id}-${peerInstanceId}`,
+                  filteredUpdates,
+                );
+              }
+            }
+          }
+
+          // propagate RESPONSE to server if it is the requester
+          if (client.id === -1) {
+            // no need to filter updates on requested, is blocked on client-side
+            client.transport.emit(
+              `${UPDATE_RESPONSE}-${this.id}-${instanceId}`,
+              reqId,
+              acknowledgedUpdates,
+            );
+          }
+
+          // propagate NOTIFICATION to other state attached on the server
+          for (let [peerInstanceId, clientInfos] of this.#attachedClients) {
+            const peer = clientInfos.client;
+
+            if (instanceId !== peerInstanceId && peer.id === -1) {
+              const filter = clientInfos.filter;
+              const filteredUpdates = filterUpdates(acknowledgedUpdates, filter);
+
+              if (Object.keys(filteredUpdates).length > 0) {
+                peer.transport.emit(
+                  `${UPDATE_NOTIFICATION}-${this.id}-${peerInstanceId}`,
+                  filteredUpdates,
+                );
+              }
+            }
+          }
+        } else {
+          // propagate back to the requester that the update has been aborted
+          // ignore all other attached clients.
+          client.transport.emit(`${UPDATE_ABORT}-${this.id}-${instanceId}`, reqId, updates);
+        }
+      } else {
+        // retrieve values from inner state (also handle immediate appropriately)
+        const oldValues = {};
+
+        for (let name in updates) {
+          oldValues[name] = this.#parameters.get(name);
+        }
+        // aborted by hook (updates have been overridden to {})
+        client.transport.emit(`${UPDATE_ABORT}-${this.id}-${instanceId}`, reqId, oldValues);
+      }
+    });
+
+    if (isOwner) {
+      // delete only if creator
+      client.transport.addListener(`${DELETE_REQUEST}-${this.id}-${instanceId}`, async reqId => {
+        // make sure hooks have been called when `delete()` fulfills
+        await this.#manager[kServerStateManagerDeletePrivateState](this);
+        // --------------------------------------------------------------------
+        // WARNING - MAKE SURE WE DON'T HAVE PROBLEM W/ THAT
+        // --------------------------------------------------------------------
+        // @todo - propagate server-side last, because if a subscription function sends a
+        // message to a client, network messages order are kept coherent
+        // this._subscriptions.forEach(func => func(updated));
+        for (let [instanceId, clientInfos] of this.#attachedClients) {
+          const attached = clientInfos.client;
+          this[kSharedStatePrivateDetachClient](instanceId, attached);
+
+          if (instanceId === this.#creatorInstanceId) {
+            attached.transport.emit(`${DELETE_RESPONSE}-${this.id}-${instanceId}`, reqId);
+          } else {
+            attached.transport.emit(`${DELETE_NOTIFICATION}-${this.id}-${instanceId}`);
+          }
+        }
+      });
+    } else {
+      // detach only if not creator
+      client.transport.addListener(`${DETACH_REQUEST}-${this.id}-${instanceId}`, (reqId) => {
+        this[kSharedStatePrivateDetachClient](instanceId, client);
+        client.transport.emit(`${DETACH_RESPONSE}-${this.id}-${instanceId}`, reqId);
+      });
+    }
+  }
+
+  [kSharedStatePrivateDetachClient](instanceId, client) {
+    this.#attachedClients.delete(instanceId);
+    // delete listeners
+    client.transport.removeAllListeners(`${UPDATE_REQUEST}-${this.id}-${instanceId}`);
+    client.transport.removeAllListeners(`${DELETE_REQUEST}-${this.id}-${instanceId}`);
+    client.transport.removeAllListeners(`${DETACH_REQUEST}-${this.id}-${instanceId}`);
+  }
+}
+
+export default SharedStatePrivate;
+
+

package/src/server/audit-network-latency.worker.js

@@ -1,6 +1,10 @@
-import { parentPort } from 'node:worker_threads';
-
-import { getTime } from '@ircam/sc-gettime';
+// @note - We use this common js syntax so that the server can be bundled to cjs
+// which allows to build a server that can be accepted by Max `node.script`
+//
+// Should move back to regular esm module once Max has fixed its loader
+export default `
+const { parentPort } = require('node:worker_threads');
+const { hrtime } =  require('node:process');
 
 let stack = [];
 let averageLatencyWindow = 5;
@@ -9,7 +13,17 @@ let averageLatencyPeriod = 2;
 let intervalId = null;
 let meanLatency = 0;
 
-parentPort.on('message', msg => {
+// workaround that sc-utils is pure ecmascript module
+// 2024/09/06 - Just copy getTime implementation so that we don't even need the node_modules
+const start = hrtime.bigint();
+
+function getTime() {
+  const now = hrtime.bigint();
+  const delta = now - start;
+  return Number(delta) * 1e-9;
+}
+
+parentPort.on('message', async msg => {
   switch (msg.type) {
     case 'config': {
       averageLatencyWindow = msg.value.averageLatencyWindow;
@@ -55,3 +69,4 @@ function computeAverageLatency() {
     });
   }
 }
+`;

package/src/server/{audit-schema.js → audit-state-class-description.js}

@@ -1,5 +1,6 @@
 /**
- * Internal schema used to audit the application.
+ * Internal shared state class used to audit the application.
+ * @private
  */
 export default {
   /**
@@ -17,7 +18,7 @@ export default {
   },
 
   /**
-   * Average latency in seconds computed from ping/pong.
+   * Average latency in seconds computed from ping/pong information.
    */
   averageNetworkLatency: {
     type: 'float',

package/src/server/create-http-server.js

@@ -0,0 +1,127 @@
+import http from 'node:http';
+import https from 'node:https';
+import fs from 'node:fs';
+import {
+  X509Certificate,
+  createPrivateKey,
+} from 'node:crypto';
+
+import pem from 'pem';
+import equal from 'fast-deep-equal';
+
+import logger from '../common/logger.js';
+
+/**
+ * @private
+ * @return {HttpServer|HttpsServer}
+ */
+export async function createHttpServer(server) {
+  const serverConfig = server.config;
+
+  if (serverConfig.env.useHttps !== true) {
+    return http.createServer();
+  }
+
+  // https is more tricky
+  const httpsInfos = serverConfig.env.httpsInfos;
+  let useSelfSigned = false;
+
+  if (!httpsInfos || equal(httpsInfos, { cert: null, key: null })) {
+    useSelfSigned = true;
+  }
+
+  let httpsCertsInfos = null;
+  let httpsServer = null;
+
+  if (!useSelfSigned) {
+    try {
+      // existence of file is checked in constructor
+      let cert = fs.readFileSync(httpsInfos.cert);
+      let key = fs.readFileSync(httpsInfos.key);
+
+      let x509 = null;
+      // this fails with self-signed certificates for whatever reason...
+      try {
+        x509 = new X509Certificate(cert);
+      } catch {
+        throw new TypeError(`Cannot create https.Server: Invalid https cert file`);
+      }
+
+      try {
+        const keyObj = createPrivateKey(key);
+
+        if (!x509.checkPrivateKey(keyObj)) {
+          throw new TypeError(`Cannot create https.Server: Invalid https key file`);
+        }
+      } catch {
+        throw new TypeError(`Cannot create https.Server: Invalid https key file`);
+      }
+
+      // check is certificate is still valid
+      const now = Date.now();
+      const certExpire = Date.parse(x509.validTo);
+      const isValid = now < certExpire;
+
+      const diff = certExpire - now;
+      const daysRemaining = Math.round(diff / 1000 / 60 / 60 / 24);
+
+      httpsCertsInfos = {
+        selfSigned: false,
+        CN: x509.subject.split('=')[1],
+        altNames: x509.subjectAltName.split(',').map(e => e.trim().split(':')[1]),
+        validFrom: x509.validFrom,
+        validTo: x509.validTo,
+        isValid: isValid,
+        daysRemaining: daysRemaining,
+      };
+
+      httpsServer = https.createServer({ key, cert });
+    } catch (err) {
+      logger.error(`
+Invalid certificate files, please check your:
+- key file: ${httpsInfos.key}
+- cert file: ${httpsInfos.cert}
+      `);
+
+      throw err;
+    }
+  } else {
+    // generate self signed certs or reused already existing ones
+    let cert = await server.db.get('httpsCert');
+    let key = await server.db.get('httpsKey');
+
+    if (!cert || !key) {
+      try {
+        const result = await new Promise((resolve, reject) => {
+          pem.createCertificate({ days: 1, selfSigned: true }, async (err, keys) => {
+            if (err) {
+              reject(err);
+              return;
+            }
+
+            resolve({
+              cert: keys.certificate,
+              key: keys.serviceKey,
+            });
+          });
+        });
+
+        cert = result.cert;
+        key = result.key;
+        // store the generated certs to reuse on next start
+        await server.db.set('httpsCert', cert);
+        await server.db.set('httpsKey', key);
+      } catch (err) {
+        logger.error(err.stack);
+        throw err;
+      }
+    }
+
+    httpsCertsInfos = { selfSigned: true };
+    httpsServer = https.createServer({ cert, key });
+  }
+
+  logger.httpsCertsInfos(httpsCertsInfos);
+
+  return httpsServer;
+}

package/src/server/crypto.js

@@ -21,18 +21,19 @@ const encryptionIV = crypto
   .substring(0, 16);
 
 
+/** @private */
 export function encryptData(obj) {
   const data = JSON.stringify(obj);
-  const cipher = crypto.createCipheriv(encryptionMethod, key, encryptionIV)
-  return Buffer.from(
-    cipher.update(data, 'utf8', 'hex') + cipher.final('hex')
-  ).toString('base64')
+  const cipher = crypto.createCipheriv(encryptionMethod, key, encryptionIV);
+
+  return Buffer.from(cipher.update(data, 'utf8', 'hex') + cipher.final('hex')).toString('base64');
 }
 
+/** @private */
 export function decryptData(encryptedData) {
-  const buff = Buffer.from(encryptedData, 'base64')
-  const decipher = crypto.createDecipheriv(encryptionMethod, key, encryptionIV)
+  const buff = Buffer.from(encryptedData, 'base64');
+  const decipher = crypto.createDecipheriv(encryptionMethod, key, encryptionIV);
 
-  const decrypted = `${decipher.update(buff.toString('utf8'), 'hex', 'utf8')}${decipher.final('utf8')}`
+  const decrypted = `${decipher.update(buff.toString('utf8'), 'hex', 'utf8')}${decipher.final('utf8')}`;
   return JSON.parse(decrypted);
 }

package/src/server/index.js

@@ -1,25 +1,68 @@
 /**
- * Server-side part of the *soundworks* framework.
- *
- * ```
- * import '@soundworks/helpers/polyfills.js';
- * import { Server } from '@soundworks/core/server.js';
- * import { loadConfig } from '../utils/load-config.js';
+ * @license
+ * Copyright (c) 2014-present IRCAM – Centre Pompidou (France, Paris)
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+// these types must be defined here, so that they can be imported into the application
+
+/**
+ * The role of the client in the application.
  *
- * // - General documentation: https://soundworks.dev/
- * // - API documentation:     https://soundworks.dev/api
- * // - Issue Tracker:         https://github.com/collective-soundworks/soundworks/issues
- * // - Wizard & Tools:        `npx soundworks`
+ * For browser client, this information is used to create the URL endpoint.
  *
- * const config = loadConfig(process.env.ENV, import.meta.url);
+ * @typedef ClientRole
+ * @type {string}
+ */
+/**
+ * @typedef ClientDescription
+ * @type {object}
+ * @property {'browser'|'node'} runtime - Runtime on which the client is aimed at running
+ * @property {boolean} [default=false] - For browser client, define is the client should be
+ *   accessible at the default / root HTTP endpoint
+ */
+/**
+ * Application configuration object.
  *
- * const server = new Server(config);
- * server.setDefaultTemplateConfig();
+ * @typedef ServerAppConfig
+ * @type {object}
+ * @property {object<ClientRole, ClientDescription>} clients - Definition of the application clients.
+ * @property {string} [name=''] - Name of the application.
+ * @property {string} [author=''] - Name of the author.
+ */
+/**
+ * Environment configuration object.
  *
- * await server.start();
- * ```
+ * @typedef ServerEnvConfig
+ * @type {objecy}
+ * @property {'development'|'production'} type - If set to 'production', will enforce
+ *  some security feature (e.g. blocking access to sensitive APIs, etc.) based on
+ *  the `auth`.
+ * @property {number} port - Port on which the server is listening.
+ * @property {string} serverAddress - Domain name or IP of the server.
+ *  Mandatory when node clients are declared
+ * @property {boolean} useHttps - Define is the server run in http or in https.
+ * @property {object} [httpsInfos=null] - Path to cert files ( cert, key } for https.
+ *  If not given and `useHttps` is `true` self certified certificates will be created.
+ * @property {string} [httpsInfos.cert=null] - Path to cert file.
+ * @property {string} [httpsInfos.key=null] - Path to key file.
+ * @property {object} [auth=null] - Configuration object for authenticating clients
+ *  using simple HTTP authentication.
+ * @property {array.<ClientRole>} [auth.client=[]] - List of client role that must authenticate.
+ * @property {login} [auth.login=''] - Login
+ * @property {login} [auth.password=''] - Password
+ * @property {string} [env.baseUrl=''] - If running behind a proxy, base URL of the application.
+ */
+/**
+ * Configuration object for the server.
  *
- * @namespace server
+ * @typedef ServerConfig
+ * @type {object}
+ * @property {AppConfig} app - Application configuration object.
+ * @property {ServerEnvConfig} env - Environment configuration object.
  */
+
 export { default as Server } from './Server.js';
-export { default as Context } from './Context.js';
+export { default as ServerPlugin } from './ServerPlugin.js';
+export { default as ServerContext } from './ServerContext.js';
+export { default as version } from '../common/version.js';