@soundworks/core 5.5.0 → 5.7.0

package/src/server/ServerStateManager.js

@@ -1,9 +1,16 @@
-import { counter, isString, isPlainObject, isFunction } from '@ircam/sc-utils';
-import clonedeep from 'lodash/cloneDeep.js';
+import {
+  counter,
+  isString,
+  isPlainObject,
+  isFunction,
+} from '@ircam/sc-utils';
 
 import BaseStateManager, {
   kStateManagerInit,
 } from '../common/BaseStateManager.js';
+import {
+  checkValidFilters,
+} from '../common/shared-state-utils.js';
 import BatchedTransport from '../common/BatchedTransport.js';
 import ParameterBag from '../common/ParameterBag.js';
 import {
@@ -32,7 +39,7 @@ import SharedStatePrivate, {
   kSharedStatePrivateGetValues,
 } from './SharedStatePrivate.js';
 
-import logger from '../common/logger.js';
+import warnings from '../common/logs/warnings.js';
 
 
 const generateStateId = counter();
@@ -201,248 +208,251 @@ class ServerStateManager extends BaseStateManager {
 
     this[kStateManagerClientsByNodeId].set(nodeId, client);
 
-    // ---------------------------------------------
-    // CREATE
-    // ---------------------------------------------
-    client.transport.addListener(
-      CREATE_REQUEST,
-      async (reqId, className, initValues = {}) => {
-        if (this.#classes.has(className)) {
-          try {
-            const classDescription = this.#classes.get(className);
-            const stateId = generateStateId();
-            const instanceId = instanceIdGenerator();
-
-            // apply create hooks on init values
-            const hooks = this.#createHooksByClassName.get(className);
-            let hookAborted = false;
-
-            for (let hook of hooks.values()) {
-              const result = await hook(initValues);
-
-              if (result === null) { // explicit abort
-                hookAborted = true;
-                break;
-              } else if (result === undefined) { // implicit continue
-                continue;
-              } else {
-                initValues = result;
-              }
-            }
-
-            if (hookAborted) {
-              throw new Error(`A 'serverStateManagerCreateHook' explicitly aborted state creation of class '${className}' by returning 'null'`);
-            }
-
-            const state = new SharedStatePrivate(this, className, classDescription, stateId, initValues);
-            // attach client to the state as owner
-            const isOwner = true;
-            const filter = null;
-            state[kSharedStatePrivateAttachClient](instanceId, client, isOwner, filter);
-
-            this.#sharedStatePrivateById.set(stateId, state);
-
-            const currentValues = state.parameters.getValues();
-
-            client.transport.emit(
-              CREATE_RESPONSE,
-              reqId,
-              stateId,
-              instanceId,
-              className,
-              classDescription,
-              currentValues,
-            );
-
-            const isObservable = this.#isObservableState(state);
-
-            if (isObservable) {
-              this.#observers.forEach(observer => {
-                observer.transport.emit(OBSERVE_NOTIFICATION, className, stateId, nodeId);
-              });
-            }
-          } catch (err) {
-            const msg = `${err.message}`;
-            client.transport.emit(CREATE_ERROR, reqId, msg);
-          }
-        } else {
-          const msg = `Undefined SharedStateClassName '${className}'`;
-          client.transport.emit(CREATE_ERROR, reqId, msg);
+    client.transport.addListener(CREATE_REQUEST, this.#onCreateRequest(client));
+    client.transport.addListener(ATTACH_REQUEST, this.#onAttachRequest(client));
+    client.transport.addListener(OBSERVE_REQUEST, this.#onObserveRequest(client));
+    client.transport.addListener(UNOBSERVE_NOTIFICATION, this.#onUnobserveNotification(client));
+    client.transport.addListener(GET_CLASS_DESCRIPTION_REQUEST, this.#onClassDescriptionRequest(client));
+  }
+
+  /**
+   * Remove a client from the manager and clean all related states.
+   *
+   * This method is automatically called by the {@link Server} when a client disconnects.
+   *
+   * @param {number} nodeId - Id of the client node, as given in
+   *  {@link client.StateManager}
+   *
+   * @private
+   */
+  [kServerStateManagerRemoveClient](nodeId) {
+    // remove from observers
+    const client = this[kStateManagerClientsByNodeId].get(nodeId);
+    this.#observers.delete(client);
+    // delete from client list
+    this[kStateManagerClientsByNodeId].delete(nodeId);
+
+    // loop through all states to clean them
+    for (let state of this.#sharedStatePrivateById.values()) {
+      let shouldDelete = nodeId === state.ownerId;
+
+      // loop through clients of this state
+      for (let [instanceId, clientInfos] of state.attachedClients) {
+        const { client, isOwner } = clientInfos;
+
+        // if client is the disconnected one, remove from the state known clients
+        if (nodeId === client.id) {
+          state[kSharedStatePrivateDetachClient](instanceId, client);
         }
-      },
-    );
 
-    // ---------------------------------------------
-    // ATTACH (when creator, is attached by default)
-    // ---------------------------------------------
-    client.transport.addListener(
-      ATTACH_REQUEST,
-      (reqId, className, stateId = null, filter = null) => {
-        if (this.#classes.has(className)) {
-          let state = null;
-
-          if (stateId !== null && this.#sharedStatePrivateById.has(stateId)) {
-            state = this.#sharedStatePrivateById.get(stateId);
-          } else if (stateId === null) {
-            // if no `stateId` given, we try to find the first state with the given
-            // `className` in the list, this allow a client to attach to a global
-            // state created by the server (or some persistent client) without
-            // having to know the `stateId` (e.g. some global state...)
-            for (let existingState of this.#sharedStatePrivateById.values()) {
-              if (existingState.className === className) {
-                state = existingState;
-                break;
-              }
-            }
-          }
+        // notify client of state deletion if not owner
+        if (shouldDelete && !isOwner) {
+          client.transport.emit(`${DELETE_NOTIFICATION}-${state.id}-${instanceId}`);
+        }
+      }
+
+      if (shouldDelete) {
+        // clean private state
+        this[kServerStateManagerDeletePrivateState](state);
+      }
+    }
+  }
+
+  #isObservableState(state) {
+    // is observable if not in private states list
+    return !PRIVATE_STATES.includes(state.className);
+  }
+
+  #onCreateRequest = client => {
+    return async (reqId, className, initValues = {}) => {
+      if (!this.#classes.has(className)) {
+        const msg = `Undefined SharedStateClassName '${className}'`;
+        client.transport.emit(CREATE_ERROR, reqId, msg);
+        return;
+      }
+
+      try {
+        const classDescription = this.#classes.get(className);
+        const stateId = generateStateId();
+        const instanceId = instanceIdGenerator();
+
+        // apply create hooks on init values
+        const hooks = this.#createHooksByClassName.get(className);
+        let hookAborted = false;
 
-          if (state !== null) {
-            // @note - we use a unique remote id to allow a client to attach
-            // several times to the same state.
-            // i.e. same state -> several remote attach on the same node
-            const instanceId = instanceIdGenerator();
-            const isOwner = false;
-            const currentValues = state.parameters.getValues();
-            const classDescription = this.#classes.get(className);
-
-            // if filter given, check that all filter entries are valid class keys
-            // @todo - improve error reporting: report invalid filters
-            if (filter !== null) {
-              const keys = Object.keys(classDescription);
-              const isValid = filter.reduce((acc, key) => acc && keys.includes(key), true);
-
-              if (!isValid) {
-                const msg = `Invalid filter (${filter.join(', ')}) for class '${className}'`;
-                return client.transport.emit(ATTACH_ERROR, reqId, msg);
-              }
-            }
-
-            state[kSharedStatePrivateAttachClient](instanceId, client, isOwner, filter);
-
-            client.transport.emit(
-              ATTACH_RESPONSE,
-              reqId,
-              state.id,
-              instanceId,
-              className,
-              classDescription,
-              currentValues,
-              filter,
-            );
+        for (let hook of hooks.values()) {
+          const result = await hook(initValues);
 
+          if (result === null) { // explicit abort
+            hookAborted = true;
+            break;
+          } else if (result === undefined) { // implicit continue
+            continue;
           } else {
-            const msg = `No existing state for class "${className}" with stateId: "${stateId}"`;
-            client.transport.emit(ATTACH_ERROR, reqId, msg);
+            initValues = result;
           }
-        } else {
-          const msg = `Undefined SharedStateClassName '${className}'`;
-          client.transport.emit(ATTACH_ERROR, reqId, msg);
         }
-      },
-    );
 
-    // ---------------------------------------------
-    // OBSERVE PEERS (be notified when a state is created, lazy)
-    // ---------------------------------------------
-    client.transport.addListener(OBSERVE_REQUEST, (reqId, observedClassName) => {
-      if (observedClassName === null || this.#classes.has(observedClassName)) {
-        const list = [];
+        if (hookAborted) {
+          throw new Error(`A 'serverStateManagerCreateHook' explicitly aborted state creation of class '${className}' by returning 'null'`);
+        }
 
-        this.#sharedStatePrivateById.forEach(state => {
-          const isObservable = this.#isObservableState(state);
+        const state = new SharedStatePrivate(this, className, classDescription, stateId, initValues);
+        // attach client to the state as owner
+        const isOwner = true;
+        const filter = null;
+        state[kSharedStatePrivateAttachClient](instanceId, client, isOwner, filter);
 
-          if (isObservable) {
-            const { className, id, creatorId } = state;
-            list.push([className, id, creatorId]);
-          }
-        });
+        this.#sharedStatePrivateById.set(stateId, state);
 
-        // add client to observers first because if some synchronous server side
-        // callback throws, the client would never be added to the list
-        this.#observers.add(client);
+        const currentValues = state.parameters.getValues();
 
-        client.transport.emit(OBSERVE_RESPONSE, reqId, ...list);
-      } else {
-        const msg = `Undefined SharedStateClassName '${observedClassName}'`;
-        client.transport.emit(OBSERVE_ERROR, reqId, msg);
+        client.transport.emit(
+          CREATE_RESPONSE,
+          reqId,
+          stateId,
+          instanceId,
+          className,
+          classDescription,
+          currentValues,
+        );
+
+        const isObservable = this.#isObservableState(state);
+
+        if (isObservable) {
+          this.#observers.forEach(observer => {
+            observer.transport.emit(OBSERVE_NOTIFICATION, className, stateId, client.id);
+          });
+        }
+      } catch (err) {
+        client.transport.emit(CREATE_ERROR, reqId, err.message);
+      }
+    };
+  };
+
+  #onAttachRequest = client => {
+    return (reqId, className, stateId = null, options = null) => {
+      if (!this.#classes.has(className)) {
+        const msg = `Undefined SharedStateClassName '${className}'`;
+        client.transport.emit(ATTACH_ERROR, reqId, msg);
+        return;
       }
-    });
 
-    client.transport.addListener(UNOBSERVE_NOTIFICATION, () => {
-      this.#observers.delete(client);
-    });
+      let state = null;
+
+      if (stateId !== null && this.#sharedStatePrivateById.has(stateId)) {
+        state = this.#sharedStatePrivateById.get(stateId);
+      } else if (stateId === null) {
+        // if no `stateId` given, we try to find the first state with the given
+        // `className` in the list, this allow a client to attach to a global
+        // state created by the server (or some persistent client) without
+        // having to know the `stateId` (e.g. some global state...)
+        for (let existingState of this.#sharedStatePrivateById.values()) {
+          if (existingState.className === className) {
+            state = existingState;
+            break;
+          }
+        }
+      }
 
-    // ---------------------------------------------
-    // GET CLASS DESCRIPTION
-    // ---------------------------------------------
-    client.transport.addListener(GET_CLASS_DESCRIPTION_REQUEST, (reqId, className) => {
-      if (this.#classes.has(className)) {
+      if (state !== null) {
+        // @note - we use a unique remote id to allow a client to attach
+        // several times to the same state.
+        // i.e. same state -> several remote attach on the same node
+        const instanceId = instanceIdGenerator();
+        const isOwner = false;
+        const currentValues = state.parameters.getValues();
         const classDescription = this.#classes.get(className);
+
+        // If filters are defined, check that all given values are valid param names
+        // Note that we need the class description, so it's more efficient to check here
+        // to avoid a network roundtrip
+        if (options !== null) {
+
+          try {
+            checkValidFilters(options, className, classDescription);
+          } catch (err) {
+            return client.transport.emit(ATTACH_ERROR, reqId, err.message);
+          }
+        }
+
+        state[kSharedStatePrivateAttachClient](instanceId, client, isOwner, options);
+
         client.transport.emit(
-          GET_CLASS_DESCRIPTION_RESPONSE,
+          ATTACH_RESPONSE,
           reqId,
+          state.id,
+          instanceId,
           className,
           classDescription,
+          currentValues,
+          options,
         );
+
       } else {
-        const msg = `Undefined SharedStateClassName '${className}'`;
-        client.transport.emit(GET_CLASS_DESCRIPTION_ERROR, reqId, msg);
+        const msg = `No existing state for class "${className}" with stateId: "${stateId}"`;
+        client.transport.emit(ATTACH_ERROR, reqId, msg);
       }
-    });
-  }
+    };
+  };
 
   /**
-   * Remove a client from the manager. Clean all created or attached states.
-   *
-   * This is automatically handled by the {@link Server} when a client disconnects.
-   *
-   * @param {number} nodeId - Id of the client node, as given in
-   *  {@link client.StateManager}
-   *
-   * @private
+   * @todo - Something seems to be wrong here. If a client observe different classes,
+   * what happens if it unobserve one of them.
+   * Looks to be tested cf. `should properly behave with several observers`
+   * but the logic is not clear, the should be documented properly
    */
-  [kServerStateManagerRemoveClient](nodeId) {
-    for (let [_id, state] of this.#sharedStatePrivateById.entries()) {
-      let deleteState = false;
+  #onObserveRequest = client => {
+    // Note that `observedClassName` is only handled client-side, this allows
+    // to have several observe in parallel without much bookkeeping at the price
+    // of not minimizing network load
+    return (reqId, observedClassName) => {
+      if (observedClassName === null || this.#classes.has(observedClassName)) {
+        const list = [];
 
-      // define if the client is the creator of the state, in which case
-      // everybody must delete it
-      for (let [instanceId, clientInfos] of state.attachedClients) {
-        const attachedClient = clientInfos.client;
+        this.#sharedStatePrivateById.forEach(state => {
+          const isObservable = this.#isObservableState(state);
 
-        if (nodeId === attachedClient.id && instanceId === state.creatorInstanceId) {
-          deleteState = true;
-        }
-      }
+          if (isObservable) {
+            const { className, id, ownerId } = state;
+            list.push([className, id, ownerId]);
+          }
+        });
 
-      for (let [instanceId, clientInfos] of state.attachedClients) {
-        const attachedClient = clientInfos.client;
+        // Add client to observers first because if some synchronous server side
+        // callback throws, the client would never be added to the list
+        this.#observers.add(client);
 
-        if (nodeId === attachedClient.id) {
-          state[kSharedStatePrivateDetachClient](instanceId, attachedClient);
-        }
+        client.transport.emit(OBSERVE_RESPONSE, reqId, ...list);
+      } else {
+        const msg = `Undefined SharedStateClassName '${observedClassName}'`;
+        client.transport.emit(OBSERVE_ERROR, reqId, msg);
+      }
+    };
+  };
 
-        if (deleteState) {
-          if (instanceId !== state.creatorInstanceId) {
-            // send notification to other attached nodes
-            attachedClient.transport.emit(`${DELETE_NOTIFICATION}-${state.id}-${instanceId}`);
-          }
+  #onUnobserveNotification = client => {
+    return () => this.#observers.delete(client);
+  };
 
-          this[kServerStateManagerDeletePrivateState](state);
-        }
+  #onClassDescriptionRequest = client => {
+    return (reqId, className) => {
+      if (!this.#classes.has(className)) {
+        const msg = `Undefined SharedStateClassName '${className}'`;
+        client.transport.emit(GET_CLASS_DESCRIPTION_ERROR, reqId, msg);
+        return;
       }
-    }
 
-    // if is an observer, delete it
-    const client = this[kStateManagerClientsByNodeId].get(nodeId);
-    this.#observers.delete(client);
-    this[kStateManagerClientsByNodeId].delete(nodeId);
-  }
+      const classDescription = this.#classes.get(className);
 
-  #isObservableState(state) {
-    // is observable if not in private states list
-    return !PRIVATE_STATES.includes(state.className);
-  }
+      client.transport.emit(
+        GET_CLASS_DESCRIPTION_RESPONSE,
+        reqId,
+        className,
+        classDescription,
+      );
+    };
+  };
 
   /**
    * Define a generic class from which {@link SharedState}s can be created.
@@ -486,21 +496,13 @@ class ServerStateManager extends BaseStateManager {
       throw new TypeError(`Cannot execute 'defineClass' (${className}) on ServerStateManager: ${err.message}`);
     }
 
-    this.#classes.set(className, clonedeep(classDescription));
+    this.#classes.set(className, structuredClone(classDescription));
     // create hooks list
     this.#createHooksByClassName.set(className, new Set());
     this.#updateHooksByClassName.set(className, new Set());
     this.#deleteHooksByClassName.set(className, new Set());
   }
 
-  /**
-   * @deprecated Use {@link ServerStateManager#defineClass} instead.
-   */
-  registerSchema(className, classDescription) {
-    logger.deprecated('ServerStateManager#registerSchema', 'ServerStateManager#defineClass', '4.0.0-alpha.29');
-    this.defineClass(className, classDescription);
-  }
-
   /**
    * Delete a whole class of {@link SharedState}.
    *
@@ -539,14 +541,6 @@ class ServerStateManager extends BaseStateManager {
     this.#deleteHooksByClassName.delete(className);
   }
 
-  /**
-   * @deprecated Use {@link ServerStateManager#defineClass} instead.
-   */
-  deleteSchema(className) {
-    logger.deprecated('ServerStateManager#deleteSchema', 'ServerStateManager#deleteClass', '4.0.0-alpha.29');
-    this.deleteClass(className);
-  }
-
   /**
    * Check wether a {@link SharedState} is defined or not, given its {@link SharedStateClassName}
    *
@@ -713,6 +707,27 @@ class ServerStateManager extends BaseStateManager {
 
     return () => hooks.delete(updateHook);
   }
+
+  // ---------------------------------------------------------------------------
+  // DEPRECATED
+  // ---------------------------------------------------------------------------
+
+  /**
+   * @deprecated Use {@link ServerStateManager#defineClass} instead.
+   */
+  registerSchema(className, classDescription) {
+    warnings.deprecated('ServerStateManager#registerSchema', 'ServerStateManager#defineClass', '4.0.0-alpha.29');
+    this.defineClass(className, classDescription);
+  }
+
+  /**
+   * @deprecated Use {@link ServerStateManager#defineClass} instead.
+   */
+  deleteSchema(className) {
+    warnings.deprecated('ServerStateManager#deleteSchema', 'ServerStateManager#deleteClass', '4.0.0-alpha.29');
+    this.deleteClass(className);
+  }
+
 }
 
 export default ServerStateManager;