entangld 2.6.0 → 2.7.1

package/lib/Datastore.js

@@ -1,10 +1,25 @@
-const { randomUUID: uuidv4 } = require("node:crypto");
+const uuidv4 = require("./uuid.js");
 const EventEmitter = require("events");
 const uuid_regex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const MAX_TIMEOUT_MS = 2147483647; // Longer setTimeout delays fire after 1 ms
+
+/**
+ * Check that an optional signal looks like an AbortSignal
+ *
+ * @private
+ * @param {AbortSignal} [signal] the signal to check.
+ * @throws {TypeError} if signal is not undefined or an AbortSignal.
+ */
+function check_signal(signal) {
+    if (signal === undefined) return;
+    if (signal === null || typeof (signal.addEventListener) != "function"
+        || typeof (signal.removeEventListener) != "function")
+        throw TypeError("signal must be an AbortSignal");
+}
 
 const Entangld_Message = require("./Message.js");
 const Subscription = require("./Subscription.js");
-const { EntangldError, RPCError } = require("./error.js");
+const { EntangldError, EntangldTimeoutError, RPCError } = require("./error.js");
 const {
     is_beneath,
     extract_from_path,
@@ -114,7 +129,7 @@ class Entangld extends EventEmitter {
 
         // Re-subscribe
         subscriptions.forEach(s => {
-            this._subscribe(s.path, s.callback, s.upstream, s.uuid, s.every);
+            this._subscribe(s.path, s.callback, s.upstream, s.uuid, s.every, s.signal);
         });
     }
 
@@ -195,7 +210,7 @@ class Entangld extends EventEmitter {
         } else if (msg.type == "value") {
             // Incoming value reply
             let resolve = this._requests[msg.uuid];
-            resolve(msg.value);
+            if (resolve) resolve(msg.value);
 
             //Clean up request
             delete this._requests[msg.uuid];
@@ -405,11 +420,17 @@ class Entangld extends EventEmitter {
      *
      * @param {string} path the path to query (like "system.voltage").
      * @param {Array} [args=[]] the arguments to pass to the RPC.
+     * @param {object} [options]
+     * @param {number} [options.timeout_ms] reject with an EntangldTimeoutError
+     * if no reply arrives within this many milliseconds. This stops the wait,
+     * not the RPC, which may still run. Omit to wait indefinitely.
+     * @param {AbortSignal} [options.signal] reject with signal.reason when
+     * this aborts. This also stops the wait, not the RPC.
      * @throws {RPCError} if the rpc call experienced an error
      * @return {Promise} promise resolving to return value of the rpc
      */
-    async call_rpc(path, args=[]) {
-        return this.get(path,args).then((args) => {
+    async call_rpc(path, args=[], { timeout_ms, signal }={}) {
+        return this.get(path,args,{ timeout_ms, signal }).then((args) => {
             if ( !Array.isArray(args) || args.length != 2) throw new EntangldError(`Endpoint is not configured for RPC: '${path}'`);
             if (args[0] === false) throw RPCError.from_remote_error(args[1]);
             if ( typeof(args[0]) == "string" ) return args[0];
@@ -471,14 +492,31 @@ class Entangld extends EventEmitter {
      * @param {string} path the path to query (like "system.voltage").
      * @param {object} [params] the parameters to be passed to the remote
      * function (RPC) or the maximum depth of the returned object (normal mode).
-     *
-     * @throws {TypeError} if path is not a string.
+     * @param {object} [options]
+     * @param {number} [options.timeout_ms] reject with an EntangldTimeoutError
+     * if no value arrives within this many milliseconds. Applies to remote
+     * paths and to local functions. It is never sent to a remote store. Omit
+     * to wait indefinitely.
+     * @param {AbortSignal} [options.signal] reject with signal.reason when
+     * this aborts. If it has already aborted, nothing is sent and no function
+     * is called. This only stops the wait, not any work a remote store or
+     * local function has started.
+     *
+     * @throws {TypeError} if path is not a string, timeout_ms is not a
+     * positive number of at most 2147483647, or signal is not an AbortSignal.
      * @return {Promise} promise resolving to the object at that path.
      */
-    get(path, params) {
+    get(path, params, { timeout_ms, signal }={}) {
         // Sanity check
         if (typeof (path) != "string")
             throw TypeError("path must be a string");
+        if (timeout_ms !== undefined
+            && !(Number.isFinite(timeout_ms) && timeout_ms > 0 && timeout_ms <= MAX_TIMEOUT_MS))
+            throw TypeError(`timeout_ms must be a positive number of at most ${MAX_TIMEOUT_MS}`);
+        check_signal(signal);
+
+        if (signal !== undefined && signal.aborted)
+            return Promise.reject(signal.reason);
 
         // If an attach()ed store path masks (matches but is shorter than) the
         // path, we are returning that store
@@ -501,7 +539,7 @@ class Entangld extends EventEmitter {
                     && result.constructor.name == "Promise") ?
                     result : new Promise((res) => res(result));
 
-                return p.then((val) => {
+                return this._with_limits(p, path, { timeout_ms, signal }).then((val) => {
 
                     // If we have a remaining path, try to navigate it before
                     // returning
@@ -541,11 +579,65 @@ class Entangld extends EventEmitter {
         // Request the data from the remote store
         const msg = Entangld_Message.get(tree, params);
 
-        return new Promise((res) => {
+        const reply = new Promise((res) => {
             this._requests[msg.uuid] = res;
             this._transmit(msg, obj);
         });
 
+        return this._with_limits(reply, path, { timeout_ms, signal }, () => {
+            delete this._requests[msg.uuid];
+        });
+    }
+
+    /**
+     * Reject if a promise does not settle in time, or a signal aborts first
+     *
+     * @private
+     * @param {Promise} promise the promise to wait on.
+     * @param {string} path the path being read, for the timeout error.
+     * @param {object} limits
+     * @param {number} [limits.timeout_ms] the time limit.
+     * @param {AbortSignal} [limits.signal] the signal to watch.
+     * @param {function} [on_limit] cleanup to run if a limit is reached.
+     *
+     * @return {Promise} the original promise if there are no limits, otherwise
+     * a promise which settles as the original does, or rejects when a limit
+     * is reached.
+     */
+    _with_limits(promise, path, { timeout_ms, signal }, on_limit = () => { }) {
+
+        if (timeout_ms === undefined && signal === undefined) return promise;
+
+        let timer;
+        let on_abort;
+
+        const stop = () => {
+            clearTimeout(timer);
+            if (signal !== undefined) signal.removeEventListener("abort", on_abort);
+        };
+
+        const limit = new Promise((_, reject) => {
+            const give_up = (err) => {
+                stop();
+                on_limit();
+                reject(err);
+            };
+
+            if (timeout_ms !== undefined) {
+                timer = setTimeout(() => {
+                    give_up(new EntangldTimeoutError(path, timeout_ms));
+                }, timeout_ms);
+            }
+
+            if (signal !== undefined) {
+                on_abort = () => give_up(signal.reason);
+                signal.addEventListener("abort", on_abort);
+            }
+        });
+
+        promise.then(stop, stop);
+
+        return Promise.race([promise, limit]);
     }
 
     /**
@@ -582,14 +674,24 @@ class Entangld extends EventEmitter {
      *
      * @param {string} path the path to watch.  Use of '*' is allowed as a wildcard (e.g. "system.*")
      * @param {function} func the callback - will be of the form (path, value).
-     * @param {number|null} [every=null] the number of `set` messages to wait before calling callback
-     *
-     * @throws {TypeError} if path is not a string.
+     * @param {number|null|object} [options=null] an options object, or the value of options.every.
+     * @param {number|null} [options.every=null] the number of `set` messages to wait before calling callback
+     * @param {AbortSignal} [options.signal] unsubscribe when this aborts. If it
+     * has already aborted, no subscription is created. The uuid is still
+     * returned, as it would be for a subscription which has since ended.
+     * Calling unsubscribe() after an abort throws, see unsubscribe().
+     *
+     * @throws {TypeError} if path is not a string, or signal is not an AbortSignal.
      * @return {uuidv4} - the uuid of the subscription
      */
-    subscribe(path, func, every = null) {
+    subscribe(path, func, options = null) {
+
+        const is_object = typeof (options) == "object" && options !== null;
+        const { every = null, signal } = is_object ? options : { every: options };
 
-        return this._subscribe(path, func, null, null, every);
+        check_signal(signal);
+
+        return this._subscribe(path, func, null, null, every, signal);
     }
 
     /**
@@ -603,6 +705,8 @@ class Entangld extends EventEmitter {
      * @param {function} func the callback - will be of the form (path, value).
      * @param {(Entangld|null)} [upstream=null] the Engangld next upstream in the path.
      * @param {(uuidv4|null)} [uuid=null] the UUID to use for this subscription.
+     * @param {number|null} [every=null] the number of `set` messages to wait before calling callback
+     * @param {AbortSignal} [signal] unsubscribe when this aborts.
      *
      * @emits {str} subscription - when this datastore is the terminal datastore of a
      *                             subscription request, this datastore emits the path
@@ -610,7 +714,7 @@ class Entangld extends EventEmitter {
      * @throws {TypeError} if path is not a string.
      * @return {uuidv4} - the uuid of the subscription
      */
-    _subscribe(path, func, upstream = null, uuid = null, every = null) {
+    _subscribe(path, func, upstream = null, uuid = null, every = null, signal = undefined) {
 
 
         // Supply a UUID if none provided
@@ -621,6 +725,8 @@ class Entangld extends EventEmitter {
         if (typeof (path) != "string")
             throw TypeError("path must be a string");
 
+        if (signal !== undefined && signal.aborted) return uuid;
+
         let [obj, /*namespace*/, tree] = this._get_remote_object(path);
 
         // Create the subscription object
@@ -644,6 +750,15 @@ class Entangld extends EventEmitter {
         // Add the new subscription here
         this._subscriptions.push(new_sub);
 
+        if (signal !== undefined) {
+            new_sub.watch_signal(signal, () => {
+                // Unlike unsubscribe(), finding nothing here isn't an error
+                this._unsubscribe(this._subscriptions.filter(
+                    s => s.matches_uuid(uuid) && !s.is_pass_through
+                ));
+            });
+        }
+
         // Commission any subscribes downstream, if this is a remote subscription
         if (new_sub.has_downstream) {
             const msg = Entangld_Message.subscribe(tree, uuid, every);
@@ -682,6 +797,11 @@ class Entangld extends EventEmitter {
      * path will be deleted, so if you have multiple subscriptions on a single path,
      * and only want one of them to be removed, you must provide the uuid instead.
      *
+     * Caution - this throws if the subscription has already ended. That includes
+     * a subscription ended by its signal, or a signal which had already aborted
+     * when subscribe() was called. If you mix signals with explicit unsubscribes,
+     * check `signal.aborted` first or catch the error.
+     *
      * @param {(String|uuidv4)} path_or_uuid - the path (or uuid) to unwatch.
      * @throws {EntangldError} if no subscriptions were found.
      * @return {number} count of subscriptions removed.
@@ -766,9 +886,12 @@ class Entangld extends EventEmitter {
         const uuids = subscriptions.map(s => s.uuid);
 
         // Drop all subscriptions with matching uuid
-        this._subscriptions = this._subscriptions.filter(
-            s => !(uuids.includes(s.uuid))
-        );
+        this._subscriptions = this._subscriptions.filter((s) => {
+            if (!uuids.includes(s.uuid)) return true;
+
+            s.unwatch_signal();
+            return false;
+        });
 
         // Notify the downstream for any deleted subscriptions that are remote
         subscriptions.forEach((s) => {

package/lib/Message.js

@@ -1,31 +1,30 @@
-const { randomUUID: uuidv4 } = require("node:crypto");
+const uuidv4 = require("./uuid.js");
 
 /**
  * Message class for Entangld.
  *
  * These messages are used for executing datastore operations between
  * remote datastores. In these relationships, there is always an upstream
- * and downstream pair, so that `get`, `set`, `push` and `subscribe` messages
- * are created upstream and passed downstream while `event` and `value` messages
- * are created downstream and are passed back up. `unsubscribe` events can travel
- * in both directions. To maintain consistency, the internal `.path` attribute
+ * and downstream pair, so that `get`, `set`, `push`, `subscribe` and `unsubscribe`
+ * messages are created upstream and passed downstream while `event` and `value`
+ * messages are created downstream and are passed back up. To maintain consistency,
+ * the internal `.path` attribute
  * will always refer a path relative to the downstream datastore, since the
  * downstream datastores do not necessarilly have access to the upstream store
  * structure, and so cannot generally construct upstream paths. This means that
  * the `.path` attribute is a `tree` relative to the upstream datastore, and
  * the upstream path can be reconstructed as:
- * ```javascript
- *  > upstream._namespaces.get(downstream) + "." + msg.path;
+ * ```js
+ * upstream._namespaces.get(downstream) + "." + msg.path;
  * ```
- * Since `unsubscribe` messages can pass either upstream or downstream, the notion
- * of a path is ill-defined, and so unsubscribe messages should have their `.path`
- * attributes set to undefined or null.
+ * Since `unsubscribe` messages identify a subscription by its `.uuid`, they should
+ * have their `.path` attributes set to undefined or null.
  *
  * Most messages will also have a `.uuid` attribute. For `get`/`value` messages,
  * this allows for the value to be properly linked back up with the original `get`
  * message. For the `subscribe`/`unsubscribe`/`event` messages, this allows for
  * callback functions to be trigger properly, and for unsubscribe messages to
- * propogate both directions. `set`/`push` messages do not use the `.uuid` attribute
+ * propogate down the chain. `set`/`push` messages do not use the `.uuid` attribute
  * since they require no response.
  */
 class Entangld_Message {

package/lib/Subscription.js

@@ -38,6 +38,29 @@ class Subscription {
             this.every = every;
         }
         this.index = -1; // guarentee that the first `set` triggers
+        this.signal = undefined;
+        this._on_abort = undefined;
+    }
+
+    /**
+     * Run a callback when a signal aborts
+     *
+     * @param {AbortSignal} signal - the signal to watch
+     * @param {function} on_abort - the callback
+     */
+    watch_signal(signal, on_abort) {
+        this.signal = signal;
+        this._on_abort = on_abort;
+        signal.addEventListener("abort", on_abort);
+    }
+
+    /**
+     * Stop watching this subscription's signal, if it has one
+     */
+    unwatch_signal() {
+        if (this.signal === undefined) return;
+
+        this.signal.removeEventListener("abort", this._on_abort);
     }
 
     /**

package/lib/error.js

@@ -12,6 +12,20 @@ class EntangldError extends Error {
     }
 }
 
+/**
+ * Error for a request which got no reply in time.
+ *
+ * @extends EntangldError
+ */
+class EntangldTimeoutError extends EntangldError {
+    constructor(path, timeout_ms) {
+        super(`No reply for '${path}' within ${timeout_ms} ms`);
+
+        this.path = path;
+        this.timeout_ms = timeout_ms;
+    }
+}
+
 /**
  * Remote Error class for Entangld.
  */
@@ -39,5 +53,6 @@ class RPCError extends Error {
 
 module.exports = exports = {
     EntangldError,
+    EntangldTimeoutError,
     RPCError,
 };

package/lib/uuid.js

@@ -0,0 +1,51 @@
+/**
+ * A random (v4) uuid, in Node and in browsers.
+ *
+ * Browsers on secure pages and Node 19 and later have crypto.randomUUID() on
+ * globalThis. Node 18 has it in its crypto module, which the "browser" field in
+ * package.json leaves out of browser bundles. A browser page that isn't secure
+ * (plain http, not localhost) has only crypto.getRandomValues().
+ *
+ * @author Claude <noreply@anthropic.com>
+ * Reviewed-by: Jonathan D. B. Van Schenck <jvschenck@novadynamics.com>
+ */
+
+/**
+ * A v4 uuid from 16 random bytes.
+ *
+ * @param {Uint8Array} bytes
+ * @return {string}
+ */
+function format_v4(bytes) {
+    bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC 4122 variant
+    const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+/**
+ * Pick the uuid source for this runtime.
+ *
+ * @param {object} [web_crypto] - globalThis.crypto, if any.
+ * @param {Function} [load_node_crypto] - returns Node's crypto module, or {} in a browser bundle.
+ * @return {Function} returns a new uuid string.
+ */
+// randomUUID needs Node 14.17 anyway, which has globalThis
+function make_uuid(web_crypto = globalThis.crypto, load_node_crypto = () => require("crypto")) { // eslint-disable-line node/no-unsupported-features/es-builtins
+    if ( typeof web_crypto?.randomUUID == "function" ) return () => web_crypto.randomUUID();
+    let node_crypto = {};
+    try {
+        node_crypto = load_node_crypto() || {};
+    } catch (err) {
+        // Not in Node
+    }
+    if ( typeof node_crypto.randomUUID == "function" ) return () => node_crypto.randomUUID();
+    if ( typeof web_crypto?.getRandomValues == "function" ) {
+        return () => format_v4(web_crypto.getRandomValues(new Uint8Array(16)));
+    }
+    throw new Error("entangld needs crypto.randomUUID or crypto.getRandomValues");
+}
+
+module.exports = make_uuid();
+module.exports.make_uuid = make_uuid;
+module.exports.format_v4 = format_v4;

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "entangld",
-  "version": "2.6.0",
+  "version": "2.7.1",
   "description": "Synchronized key-value stores with RPCs and events",
   "main": "index.js",
+  "browser": {
+    "crypto": false
+  },
   "jshintConfig": {
     "esversion": 6,
     "unused": true