entangld 2.1.6 → 2.3.0

package/lib/Message.js

@@ -0,0 +1,148 @@
+const { v4:uuidv4 } = require("uuid");
+
+/**
+ * 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
+ * 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;
+ * ```
+ * 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.
+ *
+ * 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
+ * since they require no response.
+ */
+class Entangld_Message {
+
+    constructor({type, path, value, uuid, params, every}) {
+
+        this.type = type;
+        this.path = path;
+        this.value = value;
+        this.uuid = uuid;
+        this.params = params;
+        this.every = every;
+    }
+
+    // ----------------------
+    //    Class Methods
+    // ----------------------
+    /**
+     * Create a `get` message for remote datastores
+     *
+     * @param {string} tree - the path relative to the remote datastore
+     * @param {*} [get_params=undefined] - any parameters to be passed to the
+     *                                        remote datastore's local get function
+     * @return {Entangld_Message} - The get message to pass to the remote datastore
+     */
+    static get(tree, get_params) {
+        return new this({
+            type: "get",
+            path : tree, // path needs to be relative to downstream store
+            value : get_params,
+            uuid : uuidv4() // Gets generate a new uuid
+        });
+    }
+
+    /**
+     * Create a `value` message in response to a `get` message
+     *
+     * @param {Entangld_Message} get_msg - the `get` message which this is in response to
+     * @param value - the value of the `get`
+     * @return {Entangld_Message} - The `value` message to pass back
+     */
+    static value(get_msg, value) {
+        return new this({
+            type: "value",
+            path : get_msg.path, // Resond with the get's path, which is relative to this store
+            value : value,
+            uuid : get_msg.uuid // Respond with the get's uuid
+        });
+    }
+
+    /**
+     * Create a `set`/`push` message for a remote datastore
+     *
+     * @param {Object} obj - The parameter object for the set/push
+     * @param {string} obj.type - either "set" or "push"
+     * @param {string} obj.tree - the path (relative to the downstream datastore)
+     * @param {*} obj.value - the value to insert into the datastore
+     * @param {*} obj.params - any additional parameters
+     * @return {Entangld_Message} - the "set" or "push" message
+     */
+    static setpush({type = "set", tree, value, params}) {
+        if (!["set", "push"].includes(type)) { throw new Error(`Invalid type (${type}) for setpush`); }
+        return new this({
+            type: type,
+            path : tree,
+            value : value,
+            params : params
+        });
+    }
+
+    /**
+    * Construct subscribe message
+    *
+    * @param {string} tree - the path (relative to the downstream datastore)
+    * @param {uuidv4} uuid - the subscription uuid
+    * @return {Entangld_Message} the `subscribe` message
+    */
+    static subscribe(tree, uuid, every = null) {
+        return new this({
+            type : "subscribe",
+            path : tree,
+            uuid : uuid,
+            every : every
+        });
+    }
+
+    /**
+     * Create an `event` message to return data to subscribe callbacks
+     *
+     * @param {string} path - the path (relative to the downstream store)
+     * @param {*} value - the updated datastore value at the path
+     * @param {uuidv4} uuid - the uuid of the subscribe being triggered
+     * @return {Entangld_Message} the `event` message
+     */
+    static event(path, value, uuid) {
+        return new this({
+            type : "event",
+            path : path,
+            value : value,
+            uuid : uuid
+        });
+    }
+
+
+    /**
+     * Create an unsubscribe message for a subscription uuid
+     *
+     * @param {String} uuid - the subscription uuid
+     */
+    static unsubscribe(uuid) {
+        return new this({
+            type: "unsubscribe",
+            // path is ommitted from unsubscribe messages
+            uuid : uuid
+        });
+    }
+
+}
+
+module.exports = exports = Entangld_Message;

package/lib/Subscription.js

@@ -0,0 +1,216 @@
+
+const {
+    is_beneath
+} = require("./utils.js");
+
+/**
+ * A datastore subscription object
+ */
+class Subscription {
+    /**
+     * Constructor
+     *
+     * @param {Object} obj - the configuration object
+     * @param {string} obj.path - the datastore path (relative to this datastore)
+     *                             of the subscription
+     * @param {uuidv4} obj.uuid - the uuid of the subscription chain
+     * @param {function} obj.callback - the callback function, with signature (path, value),
+     *                               where path is relative to this datastore
+     * @param {(Entangld|null)} obj.downstream - the downstream datastore (if any)
+     *                                          associated with this subscription
+     * @param {(Entangld|null)} obj.upstream - the upstream datastore (if any)
+     *                                          associated with this subscription
+     * @param {(number|null)} obj.every - how many `set` messages to wait before calling callback
+     * @return {Subscription} - the subscription object
+     */
+    constructor({path, uuid, callback, downstream, upstream, every}) {
+        this.path = path;
+        this.downstream = downstream || null;
+        this.upstream = upstream || null;
+        this.uuid = uuid;
+        this.callback = callback;
+        this._has_cb = (typeof(callback) === "function");
+        this._is_counting = (this.downstream === null);
+        every = parseInt(every);
+        if ( isNaN(every) || every < 1 ) {
+            this.every = 1;
+        } else {
+            this.every = every;
+        }
+        this.index = -1; // guarentee that the first `set` triggers
+    }
+
+    /**
+     * Apply this callback function
+     *
+     * Note, this method also tracks the number of times that a callback
+     * function is called (if this subscription is terminal), so that if
+     * the subscriptions are throttled by specifying an `this.every`,
+     * this method will only call the callback function every `this.every`
+     * times it receives a `set` message. If this subscription is not
+     * terminal, then the callback function is called every time.
+     *
+     * This method also is safed when a callback function is not give (i.e.
+     * by the `this.static_copy()` method).
+     */
+    call(...args) {
+        if ( !this._has_cb ) return;
+        if ( this._is_counting ) {
+            this.index = (this.index + 1) % this.every;
+            if ( this.index !== 0 ) return;
+        }
+        this.callback(...args);
+    }
+
+    /**
+     * Check if subscription is a `pass through` type
+     *
+     * Pass throughs are as the links in a chain of subscriptions to allows
+     * subscriptions to remote datastores. One store acts as the `head`, where
+     * the callback function is registered, an all others are `path through` datastores
+     * which simply pass event messages back up to the head subscription.
+     *
+     * @return {Boolean}
+     */
+    get is_pass_through() {
+        return this.has_upstream;
+    }
+
+    /**
+     * Check if this subscription will be directly given data by a datastore
+     *
+     * @return {Boolean}
+     */
+    get is_terminal() {
+        return !this.has_downstream;
+    }
+
+    /**
+     * Check if this subscription will apply a user-supplied callback to data
+     *
+     * @return {Boolean}
+     */
+    get is_head() {
+        return !this.has_upstream;
+    }
+
+    /**
+     * Check if subscription has any downstream subscriptions
+     *
+     * It the subscription refers to a remote datastore (the downstream), this
+     * getter will return a true. Note that !this.has_downstream will check if
+     * the subscription is the `tail` subscription object in a subscription chain.
+     *
+     * @return {Boolean}
+     */
+    get has_downstream() {
+        return this.downstream !== null;
+    }
+
+    /**
+     * Check if subscription has any upstream subscriptions
+     *
+     * It the subscription passes data back to a remote datastore (the upstream), this
+     * getter will return a true.
+     *
+     * @return {Boolean}
+     */
+    get has_upstream() {
+        return this.upstream !== null;
+    }
+
+
+    /**
+     * Check if a different `Subscription` object matches this subscription
+     *
+     * @param {Subscription} sub - a different subscription
+     * @return {Boolean} - True if the subscriptions match
+     */
+    matches_subscription(sub) {
+        return this.matches_uuid(sub.uuid) && this.matches_path(sub.path);
+    }
+
+    /**
+     * Check if an `event` message matches this subscription
+     *
+     * @param {Entangld_Message} msg - a received message from a downstream datastore
+     * @return {Boolean} - True if the message is associated with the subscription
+     */
+    matches_event_message(msg) {
+        // should be above, otherwise events below a subscription won't
+        // trigger the callback. I.e. subscribing to `flower` won't
+        // trigger when someone sets `flower.color`
+        return this.matches_uuid(msg.uuid) && this.is_above(msg.path);
+    }
+
+    /**
+     * Check if an `unsubscribe` message matches this subscription
+     *
+     * @param {Entangld_Message} msg - a received message from a downstream datastore
+     * @return {Boolean} - True if the message is associated with the subscription
+     */
+    matches_unsubscribe_message(msg) {
+        return this.matches_uuid(msg.uuid);
+    }
+
+    /**
+     * Check if a provided path matches this path
+     *
+     * @param {String} path - a path string to check against
+     * @return {Boolean} - true if the path matches
+     */
+    matches_path(path) {
+        return this.path === path;
+    }
+
+    /**
+     * Check if a provided uuid matches this uuid
+     *
+     * @param {uuidv4} uuid - a uuid string to check against
+     * @return {Boolean} - true if the path matches
+     */
+    matches_uuid(uuid) {
+        return this.uuid === uuid;
+    }
+
+    /**
+     * Check if subscription path is beneath a provided path
+     *
+     * @param {String} path - a path string to check against
+     * @return {Boolean} - true if the subscription is beneath the path
+     */
+    is_beneath(path) {
+        return is_beneath(this.path, path, 'a');
+    }
+
+    /**
+     * Check if subscription path is above a provided path
+     *
+     * @param {String} path - a path string to check against
+     * @return {Boolean} - true if the subscription is beneath the path
+     */
+    is_above(path) {
+        return is_beneath(path, this.path, 'b');
+    }
+
+    /**
+     * Get a copy of this subscription without external references
+     *
+     * This creates a copy, except the upstream/downstream references
+     * are set to true (if they exist) or null (if they don't. Addtionally,
+     * the callback function is excluded.
+     *
+     * @return {Subscription} a copy of this subscription object
+     */
+    static_copy() {
+        return new Subscription({
+            path : this.path,
+            uuid : this.uuid,
+            downstream : (this.downstream === null ? null : true),
+            upstream : (this.upstream === null ? null : true),
+            every : this.every
+        });
+    }
+}
+
+module.exports = exports = Subscription;

package/lib/error.js

@@ -0,0 +1,43 @@
+
+
+/**
+ * Error class for Entangld.
+ */
+class EntangldError extends Error {
+    constructor(message) {
+        super(message);
+
+        this.name = this.constructor.name;
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+
+/**
+ * Remote Error class for Entangld.
+ */
+class RPCError extends Error {
+    static serialize_local_error(err) {
+        const json = {};
+        for ( const key of Object.getOwnPropertyNames(err) ) {
+            json[key] = err[key];
+        }
+        json.Type = err.constructor.name;
+        return json;
+    }
+
+    static from_remote_error(err_obj) {
+        const rpc_error = new this();
+        const old_stack = rpc_error.stack;
+        for ( const key of Object.keys(err_obj) ) {
+            rpc_error[key] = err_obj[key];
+        }
+
+        rpc_error.stack = `\n${rpc_error.stack}\n    ∧∧∧ --- Remote\n    ∨∨∨ --- Local\n${old_stack.split("\n").slice(1).join("\n")}`;
+        return rpc_error;
+    }
+}
+
+module.exports = exports = {
+    EntangldError,
+    RPCError,
+};

package/lib/utils.js

@@ -0,0 +1,263 @@
+
+/**
+ * Deep copy an object
+ *
+ * Uses JSON parse methods so things that don't work in JSON will disappear,
+ * with the special exception of functions which are replaced by their return
+ * values (or if the function returns a promise, the value that it resolves to).
+ *
+ * If you pass undefined, it will return a promise resolving to undefined.
+ *
+ * @private
+ * @param {object} original the object to copy.
+ * @return {Promise} a promise resolving to a completely new, de-referenced
+ * object containing only objects and values.
+ */
+function dereferenced_copy(original) {
+
+    // Undefined passes through
+    if (original === undefined)
+        return new Promise((res) => { res(undefined); });
+
+    // Make a copy of o.  It will be missing any functions
+    let copy = JSON.parse(JSON.stringify(original));
+
+    // A container to hold the copy (so we can have a recursive function
+    // replace it using a key)
+    let container = { "copy": copy };
+
+    // We will store our promises here
+    let promises = [];
+
+    // Recursively call all functions in o, placing their values in copy.
+    // Promises are tracked also.
+    function recurse(o, c, parent, key) {
+
+        // If o is a function, get its value and return a promise
+        if (typeof (o) == "function") {
+
+            // Call the function
+            let result = o();
+
+            // If the function itself returns a promise, save it and make it
+            // replace the object with a result
+            if (result && result.constructor && result.constructor.name
+                && result.constructor.name == "Promise") {
+
+                promises.push(promises, result);
+                result.then((val) => {
+
+                    parent[key] = val;
+                });
+            } else {
+
+                // Replace the object directly
+                parent[key] = result;
+            }
+
+            return;
+        }
+
+
+        // If o is not an object, return
+        if (typeof (o) != "object") return;
+
+        // Otherwise, iterate keys and call ourselves recursively
+        for (let key in o) {
+
+            recurse(o[key], c[key], c, key);
+        }
+    }
+
+    recurse(original, copy, container, "copy");
+
+    // Wait for all promises to fulfil, then return the copy
+    return Promise.all(promises).then(() => Promise.resolve(copy));
+}
+
+
+/**
+ * Extract from path.
+ *
+ * Given an object, extracts a child object using a string path.
+ *
+ * @private
+ * @param {object} obj the object we are extracting from.
+ * @param {string} path the path to find beneath obj.
+ * @return {Array<object, string>} array containing [result, remaining_path].
+ * result will be undefined if path can't be found.  If we encounter a function
+ * in our search, result will be the function and remaining_path will be the
+ * remaining part of path.
+ */
+function extract_from_path(obj, path) {
+
+    // Empty path means get everything
+    if (path === "") return [obj, ""];
+
+
+    let keys = path.split(".");
+    let key;
+    let o = obj;
+
+    while ((key = keys.shift())) {
+
+        if (key in o) {
+
+            o = o[key];
+
+            // If o is a function, we can't go any farther
+            if (typeof (o) == "function") {
+
+                return [o, keys.join(".")];
+            }
+
+        } else {
+
+            return [undefined, ""];
+        }
+
+    }
+
+    return [o, ""];
+}
+
+/**
+ * Partial copy.
+ *
+ * Return a partial copy of an object (depth limited).  DOES NOT DE-REFERENCE!
+ *
+ * @private
+ * @param {object} object the object to copy
+ * @param {number} max_depth the maximum depth to copy (0 returns object keys)
+ * @return {object} partial copy of an object limited by max_depth.
+ */
+function partial_copy(o, max_depth) {
+
+    // Trivial case, return object untouched if no max_depth
+    if (typeof (max_depth) != "number") return o;
+
+    // If o is not an object, return it
+    if (typeof (o) != "object") return o;
+
+    let c =  (Array.isArray(o)) ? [] : {};
+
+    // If max_depth has been exceeded, return the empty object or array
+    if (max_depth < 0) return c;
+
+    // Otherwise, iterate keys and call ourselves recursively
+    for (let key in o) {
+
+        if (typeof (o[key]) != "object") {
+
+            c[key] = o[key];
+
+        } else {
+
+            c[key] = partial_copy(o[key], max_depth - 1);
+        }
+    }
+
+    return c;
+}
+
+/**
+ * Is beneath
+ *
+ * Is `a` under `b`? E.g. is "system.bus.voltage" equal to or beneath "system.bus"?
+ *
+ * @private
+ * @param {string} a the string tested for "insideness"
+ * @param {string} b the string tested for "outsideness" (wildcard '*' allowed)
+ * @param {string} [allow_wildcard = false] allow wildcards, one of ('a', 'b', false).  Default is false (no wildcard allowed)
+ * @return boolean
+ */
+function is_beneath(a, b, allow_wildcard=false) {
+
+    // Everything is beneath the top ("")
+    if(b==="") return true;
+
+    // If paths are both blank, they are equal
+    if(b==="" && a==="") return true;
+
+    let A=a.split(".");
+    let B=b.split(".");
+
+    // A is not beneath B if any part is not the same.  Check for this.
+    switch (allow_wildcard) {
+
+        case "a":
+        // Allow wildcard in A
+            while(A.length && B.length){
+
+                let A_part=A.shift();
+                if(A_part!=B.shift() && A_part != "*") return false;
+            }
+            break;
+
+        case "b":
+        // Allow wildcard in B
+            while(A.length && B.length){
+
+                let B_part=B.shift();
+                if(B_part!=A.shift() && B_part != "*") return false;
+            }
+            break;
+
+        default:
+        // No wildcards allowed
+            while(A.length && B.length){
+
+                if(A.shift()!=B.shift()) return false;
+            }
+    }
+
+    // A is not beneath B if B is longer
+    if(B.length) return false;
+
+    return true;
+}
+
+function parameter_parser(func_string) {
+    let out = "";
+    let reading = false;
+    let inside = 0;
+    for ( const char of func_string ) {
+        if ( !reading ) {
+            if ( char === "(" ) reading = true;
+            continue;
+        }
+        switch ( char ) {
+            case "(":
+            case "{":
+            case "[":
+                inside++;
+                break;
+            case ")":
+            case "}":
+            case "]":
+                inside--;
+                break;
+            case ",":
+                if ( inside == 0 ) {
+                    out += "\x00";
+                    continue;
+                } else {
+                    out += char;
+                }
+                break;
+            default:
+                out += char;
+        }
+
+        if ( inside < 0 ) break;
+    }
+    return out.split("\x00").map((p)=>p.trim()).filter((p)=>p.length);
+}
+
+module.exports = exports = {
+    is_beneath,
+    extract_from_path,
+    partial_copy,
+    dereferenced_copy,
+    parameter_parser
+};