entangld 2.7.1 → 2.7.2

package/API.md

@@ -12,6 +12,9 @@
 <dt><a href="#EntangldTimeoutError">EntangldTimeoutError</a> ⇐ <code><a href="#EntangldError">EntangldError</a></code></dt>
 <dd><p>Error for a request which got no reply in time.</p>
 </dd>
+<dt><a href="#EntangldAbortError">EntangldAbortError</a> ⇐ <code><a href="#EntangldError">EntangldError</a></code></dt>
+<dd><p>Default reason for requests ended by abort().</p>
+</dd>
 <dt><a href="#RPCError">RPCError</a></dt>
 <dd><p>Remote Error class for Entangld.</p>
 </dd>
@@ -58,6 +61,7 @@ Synchronized Event Store
     * [.namespace()](#Entangld+namespace) ⇒ <code>string</code>
     * [.attach(namespace, obj)](#Entangld+attach)
     * [.detach([namespace], [obj])](#Entangld+detach) ⇒ <code>boolean</code>
+    * [.abort([reason])](#Entangld+abort) ⇒ <code>number</code>
     * [.transmit(func)](#Entangld+transmit)
     * [.receive(msg, obj)](#Entangld+receive)
     * [.push(path, data, [limit])](#Entangld+push)
@@ -136,6 +140,37 @@ one parameter.
 | [namespace] | <code>string</code> | the namespace. |
 | [obj] | <code>object</code> | the store object. |
 
+<a name="Entangld+abort"></a>
+
+### entangld.abort([reason]) ⇒ <code>number</code>
+Abort every request waiting on a reply from an attached store
+
+Each one rejects with reason, and its time limit and signal listener
+are cleared, so nothing is left to hold the process open. A reply
+which arrives later is ignored. Attachments, subscriptions, local
+functions which are still running and requests made afterwards are
+not affected, so this is safe to call more than once.
+
+Use it when no reply can arrive any more, for example when a process
+is shutting down or its link has closed. detach() doesn't do this: a
+request doesn't belong to a store, and its reply can still arrive if
+the same store is attached again.
+
+Future work: abort(reason, obj), to abort only the requests sent to
+one store, for example when one of several sockets closes. Requests
+are kept by uuid alone (see get()), and a reply is matched by its
+uuid whichever store it came from, so each request would first need
+to record the obj it was sent to. That obj must be the one passed to
+attach(), not its namespace, since a namespace can be detached and
+attached to another store while a request waits. See the README.
+
+**Kind**: instance method of [<code>Entangld</code>](#Entangld)  
+**Returns**: <code>number</code> - how many requests were aborted.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [reason] | <code>\*</code> | what the requests reject with. Defaults to an EntangldAbortError. |
+
 <a name="Entangld+transmit"></a>
 
 ### entangld.transmit(func)
@@ -411,6 +446,13 @@ Error class for Entangld.
 ## EntangldTimeoutError ⇐ [<code>EntangldError</code>](#EntangldError)
 Error for a request which got no reply in time.
 
+**Kind**: global class  
+**Extends**: [<code>EntangldError</code>](#EntangldError)  
+<a name="EntangldAbortError"></a>
+
+## EntangldAbortError ⇐ [<code>EntangldError</code>](#EntangldError)
+Default reason for requests ended by abort().
+
 **Kind**: global class  
 **Extends**: [<code>EntangldError</code>](#EntangldError)  
 <a name="RPCError"></a>

package/README.md

@@ -225,6 +225,30 @@ try {
 child.set("job.progress", 100); // Nobody is told
 ```
 
+### Aborting waiting requests
+
+When no reply can arrive any more, for example when a process is shutting down or its link has closed, `abort()` ends
+every request waiting on an attached store. Each one rejects, with an `EntangldAbortError` or the reason you pass, and
+its time limit is cleared. A pending `timeout_ms` would otherwise keep the process running until it fires.
+
+```js
+const { EntangldAbortError } = Entangld.error;
+
+const request = parent.get("child.job.slow", undefined, { timeout_ms: 30000 });
+
+parent.abort(); // Returns how many requests it aborted
+
+try {
+    await request;
+} catch (err) {
+    console.log(err instanceof EntangldAbortError); // true
+}
+```
+
+`abort()` changes nothing else. Attachments, subscriptions, local functions which are still running and later requests
+carry on, so it is safe to call more than once. `detach()` doesn't abort requests, since a reply can still arrive if the
+same store is attached again.
+
 ### Over sockets
 
 Each side of a socket gets its own store. The socket stands in for the store on the other side.
@@ -298,12 +322,41 @@ Over a socket that rarely matters, but it can for local stores holding values wh
 
 ## Known limitations
 
-- `detach()` doesn't end subscriptions from or through that store, and doesn't touch requests waiting on it.
+- `detach()` doesn't end subscriptions from or through that store, and doesn't touch requests waiting on it. Use
+  `abort()` to end waiting requests.
+- `abort()` ends the requests waiting on every attached store. It can't yet end only one store's requests.
 - Querying a parent can't include the contents of attached stores.
 - Deref mode turns values into JSON and back, which is inefficient and loses values like `Map`.
 - Some unit tests depend on the state left by earlier tests.
 - `unsubscribe_tree()` needs a test that it throws when it can't remove every subscription.
 
+## Future work
+
+### Aborting one store's requests: `abort(reason, obj)`
+
+A store with several attached stores, like a server with a socket per client, may want to end only the requests sent
+over one link when that link closes, and leave the rest waiting. `abort(reason)` can't do that, because a request
+doesn't know which store it was sent to:
+
+- Requests are kept by uuid alone, as `_requests[uuid] = { resolve, reject }`.
+- A reply is matched by its uuid, whichever store it came from.
+
+What it would need:
+
+1. **Record the store with each request.** `get()` would save the `obj` it transmitted to alongside `resolve` and
+   `reject`. It must be the `obj` passed to `attach()`, not the namespace. A namespace can be detached and attached to
+   a different store while a request waits, and the request still belongs to the store it was sent to.
+2. **Filter in `abort()`.** With an `obj`, reject only that store's requests. Without one, reject them all, as now. An
+   `obj` which was never attached aborts nothing, rather than throwing, since it may have been detached already.
+3. **Decide what a reply from another store means.** Once requests know their store, `receive()` could check that a
+   reply came from it. That is stricter than today, and could break setups where replies arrive through a different
+   object than the one requests go out on, so it should be its own change.
+4. **Tests:** only the named store's requests reject; others still resolve; a request sent before its namespace was
+   re-attached to another store belongs to the old store; and the call with no `obj` is unchanged.
+
+Even then, the trigger for it would be the link closing, not `detach()`. A detach and re-attach over the same link can
+still deliver the reply.
+
 ## Development
 
 ```sh

package/lib/Datastore.js

@@ -19,7 +19,7 @@ function check_signal(signal) {
 
 const Entangld_Message = require("./Message.js");
 const Subscription = require("./Subscription.js");
-const { EntangldError, EntangldTimeoutError, RPCError } = require("./error.js");
+const { EntangldError, EntangldTimeoutError, EntangldAbortError, RPCError } = require("./error.js");
 const {
     is_beneath,
     extract_from_path,
@@ -163,6 +163,41 @@ class Entangld extends EventEmitter {
             && this._namespaces.delete(obj);
     }
 
+    /**
+     * Abort every request waiting on a reply from an attached store
+     *
+     * Each one rejects with reason, and its time limit and signal listener
+     * are cleared, so nothing is left to hold the process open. A reply
+     * which arrives later is ignored. Attachments, subscriptions, local
+     * functions which are still running and requests made afterwards are
+     * not affected, so this is safe to call more than once.
+     *
+     * Use it when no reply can arrive any more, for example when a process
+     * is shutting down or its link has closed. detach() doesn't do this: a
+     * request doesn't belong to a store, and its reply can still arrive if
+     * the same store is attached again.
+     *
+     * Future work: abort(reason, obj), to abort only the requests sent to
+     * one store, for example when one of several sockets closes. Requests
+     * are kept by uuid alone (see get()), and a reply is matched by its
+     * uuid whichever store it came from, so each request would first need
+     * to record the obj it was sent to. That obj must be the one passed to
+     * attach(), not its namespace, since a namespace can be detached and
+     * attached to another store while a request waits. See the README.
+     *
+     * @param {*} [reason] what the requests reject with. Defaults to an
+     * EntangldAbortError.
+     * @return {number} how many requests were aborted.
+     */
+    abort(reason = new EntangldAbortError()) {
+        const requests = Object.values(this._requests);
+        this._requests = {};
+
+        for (const request of requests) request.reject(reason);
+
+        return requests.length;
+    }
+
     /**
      * Transmit
      *
@@ -209,8 +244,8 @@ class Entangld extends EventEmitter {
 
         } else if (msg.type == "value") {
             // Incoming value reply
-            let resolve = this._requests[msg.uuid];
-            if (resolve) resolve(msg.value);
+            let request = this._requests[msg.uuid];
+            if (request) request.resolve(msg.value);
 
             //Clean up request
             delete this._requests[msg.uuid];
@@ -579,8 +614,8 @@ class Entangld extends EventEmitter {
         // Request the data from the remote store
         const msg = Entangld_Message.get(tree, params);
 
-        const reply = new Promise((res) => {
-            this._requests[msg.uuid] = res;
+        const reply = new Promise((resolve, reject) => {
+            this._requests[msg.uuid] = { resolve, reject };
             this._transmit(msg, obj);
         });
 

package/lib/error.js

@@ -26,6 +26,17 @@ class EntangldTimeoutError extends EntangldError {
     }
 }
 
+/**
+ * Default reason for requests ended by abort().
+ *
+ * @extends EntangldError
+ */
+class EntangldAbortError extends EntangldError {
+    constructor(message = "Request aborted") {
+        super(message);
+    }
+}
+
 /**
  * Remote Error class for Entangld.
  */
@@ -54,5 +65,6 @@ class RPCError extends Error {
 module.exports = exports = {
     EntangldError,
     EntangldTimeoutError,
+    EntangldAbortError,
     RPCError,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangld",
-  "version": "2.7.1",
+  "version": "2.7.2",
   "description": "Synchronized key-value stores with RPCs and events",
   "main": "index.js",
   "browser": {

package/test/abort.js

@@ -0,0 +1,160 @@
+const assert = require("assert");
+const { spawn } = require("child_process");
+const path = require("path");
+const { getEventListeners } = require("events");
+const Entangld = require("../lib/Datastore.js");
+const { EntangldError, EntangldAbortError } = require("../lib/error.js");
+
+// Resolve to the error a promise rejects with, or fail if it resolves
+function rejection(promise) {
+    return promise.then(
+        (val) => assert.fail(`Expected a rejection, got ${val}`),
+        (err) => err
+    );
+}
+
+// Attach store b to store a. Messages from a are delivered only if allow(msg)
+function linked_stores(allow = () => true) {
+    const a = new Entangld();
+    const b = new Entangld();
+
+    a.transmit((msg, store) => {
+        if (allow(msg)) store.receive(msg, a);
+    });
+    b.transmit((msg, store) => store.receive(msg, b));
+
+    a.attach("b", b);
+    b.attach("a", a);
+
+    return { a, b };
+}
+
+describe("abort", () => {
+
+    it("rejects every waiting request with the reason", async () => {
+        const { a } = linked_stores(() => false);
+        const reason = new Error("stopping");
+
+        const first = a.get("b.one");
+        const second = a.call_rpc("b.two", [ 1 ], { timeout_ms: 60000 });
+
+        assert.strictEqual(a.abort(reason), 2);
+        assert.strictEqual(await rejection(first), reason);
+        assert.strictEqual(await rejection(second), reason);
+        assert.strictEqual(Object.keys(a._requests).length, 0);
+    });
+
+    it("rejects with an EntangldAbortError by default", async () => {
+        const { a } = linked_stores(() => false);
+
+        const request = a.get("b.value");
+        a.abort();
+
+        const err = await rejection(request);
+        assert.ok(err instanceof EntangldAbortError);
+        assert.ok(err instanceof EntangldError);
+        assert.strictEqual(err.name, "EntangldAbortError");
+    });
+
+    it("clears the time limit and the signal listener", async () => {
+        const { a } = linked_stores(() => false);
+        const controller = new AbortController();
+
+        const request = a.get("b.value", undefined, { timeout_ms: 60000, signal: controller.signal });
+        assert.strictEqual(getEventListeners(controller.signal, "abort").length, 1);
+
+        a.abort();
+        await rejection(request);
+
+        assert.strictEqual(getEventListeners(controller.signal, "abort").length, 0);
+    });
+
+    it("lets the process exit while a request with a time limit waits", function () {
+        this.timeout(10000);
+
+        // The request's timer would hold the process open for a minute
+        const script = `
+            const Entangld = require(${JSON.stringify(path.join(__dirname, "../lib/Datastore.js"))});
+            const a = new Entangld();
+            a.transmit(() => { });
+            a.attach("b", {});
+            a.get("b.value", undefined, { timeout_ms: 60000 }).catch(() => { });
+            setTimeout(() => a.abort(), 10);
+        `;
+
+        return new Promise((resolve, reject) => {
+            const started = Date.now();
+            const child = spawn(process.execPath, [ "-e", script ], { stdio: "inherit" });
+            const timer = setTimeout(() => {
+                child.kill();
+                reject(new Error("The process was still running after 5 s"));
+            }, 5000);
+
+            child.on("exit", (code) => {
+                clearTimeout(timer);
+                try {
+                    assert.strictEqual(code, 0);
+                    assert.ok(Date.now() - started < 5000);
+                    resolve();
+                } catch (err) {
+                    reject(err);
+                }
+            });
+        });
+    });
+
+    it("ignores a reply which arrives after aborting", async () => {
+        const { a, b } = linked_stores(() => false);
+        const sent = [];
+        a.transmit((msg) => sent.push(msg));
+
+        const request = a.get("b.value");
+        a.abort();
+        await rejection(request);
+
+        assert.doesNotThrow(() => {
+            a.receive({ type: "value", uuid: sent[0].uuid, value: 1 }, b);
+        });
+    });
+
+    it("leaves later requests, attachments and subscriptions alone", async () => {
+        const { a, b } = linked_stores();
+        const seen = [];
+
+        await a.subscribe("b.value", (path, value) => seen.push(value));
+        b.set("value", 1);
+
+        assert.strictEqual(a.abort(), 0);
+        assert.strictEqual(a.abort(), 0);
+
+        b.set("value", 2);
+        assert.deepStrictEqual(seen, [ 1, 2 ]);
+        assert.deepStrictEqual(a.namespaces, [ "b" ]);
+        assert.strictEqual(await a.get("b.value"), 2);
+    });
+
+    it("doesn't end local functions which are running", async () => {
+        const store = new Entangld();
+        let finish;
+        store.set("slow", () => new Promise((resolve) => { finish = resolve; }));
+
+        const request = store.get("slow", undefined, { timeout_ms: 60000 });
+        assert.strictEqual(store.abort(), 0);
+
+        finish(5);
+        assert.strictEqual(await request, 5);
+    });
+
+    it("isn't done by detach(), so a reply after attaching again still arrives", async () => {
+        const { a, b } = linked_stores(() => false);
+        const sent = [];
+        a.transmit((msg) => sent.push(msg));
+
+        const request = a.get("b.value");
+        a.detach("b");
+        a.attach("b", b);
+
+        a.receive({ type: "value", uuid: sent[0].uuid, value: 7 }, b);
+        assert.strictEqual(await request, 7);
+    });
+});