stream-demux 10.0.1 → 10.2.0

package/README.md

@@ -96,6 +96,37 @@ function wait(duration) {
 })();
 ```
 
+## Consumer lifetime
+
+A `StreamDemux` owns its streams; each one is created on demand when a consumer
+asks for it by name and is dropped as soon as its last consumer goes away. That
+is why no cleanup is needed beyond ending consumption, which you do by breaking
+out of the `for-await-of` loop, or by calling `consumer.return()`, `kill()` or
+`killAll()`.
+
+A consequence is that a consumer must not be reused once its iteration has
+ended. Create a new one instead:
+
+```js
+let consumer = demux.stream('abc').createConsumer();
+for await (let packet of consumer) {
+  if (packet === 'stop') break;
+}
+
+// Do not iterate `consumer` again; ask the demux for a new one.
+let nextConsumer = demux.stream('abc').createConsumer();
+```
+
+Reusing a consumer after its loop has ended leaves it attached to a stream the
+demux has already dropped, so it will never receive anything written through
+`demux.write()` and cannot be reached by `kill()` or `close()`. (A consumer
+created directly on a `WritableConsumableStream` *can* be reused, because there
+the stream's lifetime is yours to manage rather than the demux's.)
+
+`demux.unstream(streamName)` detaches a stream from the demux and kills its
+consumers, so their loops end rather than hanging on a stream nothing can
+reach any more.
+
 ## Goal
 
 The goal of this module is to facilitate functional programming patterns which decrease the probability of memory leaks and race conditions.

package/index.js

@@ -3,7 +3,14 @@ const DemuxedConsumableStream = require('./demuxed-consumable-stream');
 
 class StreamDemux {
   constructor() {
-    this.streams = {};
+    // A null-prototype object is used so that stream names which collide with
+    // Object.prototype members (such as __proto__, constructor or toString)
+    // are treated as ordinary stream names instead of resolving to inherited
+    // properties. Without this, lookups such as this.streams[streamName]
+    // return an inherited value for those names; the truthiness checks
+    // throughout this class then pass and the subsequent stream method call
+    // throws a TypeError.
+    this.streams = Object.create(null);
     this._nextConsumerId = 1;
     this.generateConsumerId = () => {
       return this._nextConsumerId++;
@@ -126,6 +133,32 @@ class StreamDemux {
     return 0;
   }
 
+  // Backpressure is pending processing work: a stream counts every unprocessed
+  // item in its queue, a consumer only its own share. Queue depth instead
+  // counts the nodes a consumer still pins in memory, addressed to it or not.
+  getQueueDepth(streamName) {
+    if (this.streams[streamName]) {
+      return this.streams[streamName].getQueueDepth();
+    }
+    return 0;
+  }
+
+  getQueueDepthAll() {
+    return Object.values(this.streams).reduce(
+      (max, stream) => Math.max(max, stream.getQueueDepth()),
+      0
+    );
+  }
+
+  getConsumerQueueDepth(consumerId) {
+    for (let stream of Object.values(this.streams)) {
+      if (stream.hasConsumer(consumerId)) {
+        return stream.getConsumerQueueDepth(consumerId);
+      }
+    }
+    return 0;
+  }
+
   hasConsumer(streamName, consumerId) {
     if (this.streams[streamName]) {
       return this.streams[streamName].hasConsumer(consumerId);
@@ -153,14 +186,21 @@ class StreamDemux {
 
   createConsumer(streamName, timeout) {
     if (!this.streams[streamName]) {
-      this.streams[streamName] = new WritableConsumableStream({
+      // The callback checks the stream it belongs to rather than whatever is
+      // currently registered under streamName, so a stream which has already
+      // been replaced can never remove its successor from the map. Capturing
+      // the stream allocates nothing: the callback is stored on the stream
+      // either way, so this only adds a binding to a closure which the stream
+      // already holds, and the resulting cycle is collected along with it.
+      let stream = new WritableConsumableStream({
         generateConsumerId: this.generateConsumerId,
         removeConsumerCallback: () => {
-          if (!this.getConsumerCount(streamName)) {
+          if (this.streams[streamName] === stream && !stream.getConsumerCount()) {
             delete this.streams[streamName];
           }
         }
       });
+      this.streams[streamName] = stream;
     }
     return this.streams[streamName].createConsumer(timeout);
   }
@@ -171,7 +211,15 @@ class StreamDemux {
     return new DemuxedConsumableStream(this, streamName);
   }
 
+  // Kills the stream's consumers before detaching it. A consumer left attached
+  // to a detached stream could not be reached again through the demux: writes
+  // would go to a freshly created stream and kill()/close() could not see it,
+  // so its for-await-of loop would never end.
   unstream(streamName) {
+    let stream = this.streams[streamName];
+    if (stream) {
+      stream.kill();
+    }
     delete this.streams[streamName];
   }
 }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "stream-demux",
-  "version": "10.0.1",
+  "version": "10.2.0",
   "description": "A consumable stream demultiplexer.",
   "main": "index.js",
   "scripts": {
-    "test": "./node_modules/mocha/bin/_mocha --reporter spec --timeout 10000 --slow 10000"
+    "test": "mocha --reporter spec --timeout 10000 --slow 10000"
   },
   "repository": {
     "type": "git",
@@ -25,10 +25,10 @@
   },
   "homepage": "https://github.com/SocketCluster/stream-demux#readme",
   "devDependencies": {
-    "mocha": "^10.2.0"
+    "mocha": "^12.0.3"
   },
   "dependencies": {
     "consumable-stream": "^3.0.0",
-    "writable-consumable-stream": "^4.1.0"
+    "writable-consumable-stream": "^5.0.0"
   }
 }

package/test/test.js

@@ -895,4 +895,375 @@ describe('StreamDemux', () => {
     assert.equal(demux.hasConsumerAll(consumerA.id), true);
     assert.equal(demux.hasConsumerAll(consumerB.id), true);
   });
+
+  it('should not attribute packets addressed to one consumer to the other consumers of the same stream', async () => {
+    let consumerA = demux.stream('hello').createConsumer();
+    let consumerB = demux.stream('hello').createConsumer();
+
+    for (let i = 0; i < 10; i++) {
+      demux.writeToConsumer(consumerA.id, 'for-a' + i);
+    }
+
+    assert.equal(demux.getConsumerBackpressure(consumerA.id), 10);
+    assert.equal(demux.getConsumerBackpressure(consumerB.id), 0);
+    assert.equal(demux.getBackpressure('hello'), 10);
+    assert.equal(demux.getBackpressureAll(), 10);
+  });
+
+  it('should attribute broadcast packets to every consumer of the stream', async () => {
+    let consumerA = demux.stream('hello').createConsumer();
+    let consumerB = demux.stream('hello').createConsumer();
+
+    demux.write('hello', 'one');
+    demux.writeToConsumer(consumerA.id, 'for-a');
+    demux.write('hello', 'two');
+
+    assert.equal(demux.getConsumerBackpressure(consumerA.id), 3);
+    assert.equal(demux.getConsumerBackpressure(consumerB.id), 2);
+  });
+
+  it('should not reset a consumer timeout when a packet is addressed to a different consumer of the same stream', async () => {
+    let victim = demux.stream('hello').createConsumer(100);
+    let other = demux.stream('hello').createConsumer();
+
+    let error;
+    let consumeVictim = (async () => {
+      try {
+        for await (let packet of victim) {}
+      } catch (err) {
+        error = err;
+      }
+    })();
+
+    let spam = (async () => {
+      for (let i = 0; i < 15; i++) {
+        demux.writeToConsumer(other.id, 'spam' + i);
+        await wait(20);
+      }
+    })();
+
+    await Promise.all([consumeVictim, spam]);
+
+    assert.notEqual(error, null);
+    assert.equal(error.name, 'TimeoutError');
+  });
+
+  it('should deliver targeted packets only to the consumer they were addressed to', async () => {
+    let consumerA = demux.stream('hello').createConsumer();
+    let consumerB = demux.stream('hello').createConsumer();
+
+    let receivedA = [];
+    let receivedB = [];
+
+    let consumeA = (async () => {
+      while (true) {
+        let packet = await consumerA.next();
+        if (packet.done) break;
+        receivedA.push(packet.value);
+      }
+    })();
+    let consumeB = (async () => {
+      while (true) {
+        let packet = await consumerB.next();
+        if (packet.done) break;
+        receivedB.push(packet.value);
+      }
+    })();
+
+    await wait(10);
+
+    demux.writeToConsumer(consumerA.id, 'secret-a');
+    demux.write('hello', 'public');
+    demux.writeToConsumer(consumerB.id, 'secret-b');
+    demux.close('hello');
+
+    await Promise.all([consumeA, consumeB]);
+
+    assert.equal(JSON.stringify(receivedA), JSON.stringify(['secret-a', 'public']));
+    assert.equal(JSON.stringify(receivedB), JSON.stringify(['public', 'secret-b']));
+  });
+
+  it('should report queue depth separately from backpressure', async () => {
+    let idle = demux.stream('hello').createConsumer();
+    let active = demux.stream('hello').createConsumer();
+
+    let consumeActive = (async () => {
+      for await (let packet of active) {}
+    })();
+
+    await wait(10);
+
+    for (let i = 0; i < 10; i++) {
+      demux.writeToConsumer(active.id, 'for-active' + i);
+    }
+
+    assert.equal(demux.getConsumerBackpressure(idle.id), 0);
+    assert.equal(demux.getConsumerQueueDepth(idle.id), 10);
+    assert.equal(demux.getQueueDepth('hello'), 10);
+    assert.equal(demux.getQueueDepthAll(), 10);
+
+    await wait(50);
+
+    // The active consumer has caught up, so its own backpressure is zero, but
+    // the 10 items are still unprocessed by the idle consumer, so the stream
+    // still reports them as pending work.
+    assert.equal(demux.getConsumerBackpressure(active.id), 0);
+    assert.equal(demux.getBackpressureAll(), 10);
+    assert.equal(demux.getQueueDepthAll(), 10);
+
+    demux.close('hello');
+    await consumeActive;
+  });
+
+  it('should report zero queue depth for unknown streams and consumers', async () => {
+    assert.equal(demux.getQueueDepth('does-not-exist'), 0);
+    assert.equal(demux.getQueueDepthAll(), 0);
+    assert.equal(demux.getConsumerQueueDepth(12345), 0);
+  });
+
+  it('should drop back to zero queue depth once every consumer has caught up', async () => {
+    let consumerA = demux.stream('hello').createConsumer();
+    let consumerB = demux.stream('hello').createConsumer();
+
+    let consumeA = (async () => {
+      for await (let packet of consumerA) {}
+    })();
+    let consumeB = (async () => {
+      for await (let packet of consumerB) {}
+    })();
+
+    await wait(10);
+
+    for (let i = 0; i < 10; i++) {
+      demux.write('hello', 'hello' + i);
+    }
+
+    await wait(50);
+
+    assert.equal(demux.getQueueDepthAll(), 0);
+
+    demux.close('hello');
+    await Promise.all([consumeA, consumeB]);
+  });
+
+  it('should end a consuming loop when return() is called in the same tick as a write', async () => {
+    let consumer = demux.stream('hello').createConsumer();
+
+    let error;
+    let ended = false;
+    let consume = (async () => {
+      try {
+        for await (let packet of consumer) {}
+        ended = true;
+      } catch (err) {
+        error = err;
+      }
+    })();
+
+    await wait(10);
+
+    // The write resolves the parked next() call; the return() which follows in
+    // the same tick used to leave that call with no packet to terminate on and
+    // no currentNode to read, throwing a TypeError out of the consuming loop.
+    demux.write('hello', 'packet');
+    consumer.return();
+
+    await consume;
+
+    assert.equal(error, undefined);
+    assert.equal(ended, true);
+    assert.equal(demux.getConsumerCountAll(), 0);
+  });
+
+  it('should end a consuming loop when return() is called in the same tick as a targeted write', async () => {
+    let consumer = demux.stream('hello').createConsumer();
+
+    let error;
+    let ended = false;
+    let consume = (async () => {
+      try {
+        for await (let packet of consumer) {}
+        ended = true;
+      } catch (err) {
+        error = err;
+      }
+    })();
+
+    await wait(10);
+
+    demux.writeToConsumer(consumer.id, 'packet');
+    consumer.return();
+
+    await consume;
+
+    assert.equal(error, undefined);
+    assert.equal(ended, true);
+  });
+
+  it('should end a consuming loop when return() is called in the same tick as a close', async () => {
+    let consumer = demux.stream('hello').createConsumer();
+
+    let error;
+    let ended = false;
+    let consume = (async () => {
+      try {
+        for await (let packet of consumer) {}
+        ended = true;
+      } catch (err) {
+        error = err;
+      }
+    })();
+
+    await wait(10);
+
+    demux.close('hello', 'end');
+    consumer.return();
+
+    await consume;
+
+    assert.equal(error, undefined);
+    assert.equal(ended, true);
+  });
+
+  it('should reclaim the stream after return() races a write', async () => {
+    let consumer = demux.stream('hello').createConsumer();
+
+    let consume = (async () => {
+      for await (let packet of consumer) {}
+    })();
+
+    await wait(10);
+
+    demux.write('hello', 'packet');
+    consumer.return();
+
+    await consume;
+
+    assert.equal(demux.getConsumerCount('hello'), 0);
+    assert.equal(demux.hasConsumerAll(consumer.id), false);
+    assert.equal(Object.keys(demux.streams).length, 0);
+  });
+
+  it('should terminate consumers when their stream is detached with unstream', async () => {
+    let consumerA = demux.stream('hello').createConsumer();
+    let consumerB = demux.stream('hello').createConsumer();
+
+    let endedA = false;
+    let endedB = false;
+    let error;
+
+    let consumeA = (async () => {
+      try {
+        for await (let packet of consumerA) {}
+        endedA = true;
+      } catch (err) {
+        error = err;
+      }
+    })();
+    let consumeB = (async () => {
+      try {
+        for await (let packet of consumerB) {}
+        endedB = true;
+      } catch (err) {
+        error = err;
+      }
+    })();
+
+    await wait(10);
+
+    demux.unstream('hello');
+
+    await Promise.all([consumeA, consumeB]);
+
+    assert.equal(error, undefined);
+    assert.equal(endedA, true);
+    assert.equal(endedB, true);
+    assert.equal(consumerA.isAlive, false);
+    assert.equal(consumerB.isAlive, false);
+  });
+
+  it('should leave no stream or consumer behind after unstream', async () => {
+    let consumer = demux.stream('hello').createConsumer();
+
+    let consume = (async () => {
+      for await (let packet of consumer) {}
+    })();
+
+    await wait(10);
+
+    demux.unstream('hello');
+    await consume;
+
+    assert.equal(Object.keys(demux.streams).length, 0);
+    assert.equal(demux.getConsumerCountAll(), 0);
+    assert.equal(demux.hasConsumerAll(consumer.id), false);
+    assert.equal(demux.getConsumerStats(consumer.id), undefined);
+  });
+
+  it('should support unstream on a stream which does not exist', async () => {
+    demux.unstream('does-not-exist');
+
+    assert.equal(Object.keys(demux.streams).length, 0);
+  });
+
+  it('should let a stream be recreated after unstream', async () => {
+    let oldConsumer = demux.stream('hello').createConsumer();
+    let consumeOld = (async () => {
+      for await (let packet of oldConsumer) {}
+    })();
+
+    await wait(10);
+    demux.unstream('hello');
+    await consumeOld;
+
+    let newConsumer = demux.stream('hello').createConsumer();
+    let received = [];
+    let consumeNew = (async () => {
+      for await (let packet of newConsumer) {
+        received.push(packet);
+      }
+    })();
+
+    await wait(10);
+    demux.write('hello', 'fresh');
+    demux.close('hello');
+    await consumeNew;
+
+    assert.equal(JSON.stringify(received), JSON.stringify(['fresh']));
+  });
+
+  it('should not let a replaced stream remove its successor from the map', async () => {
+    // A consumer can outlive the stream it was created on, by being reused
+    // after return(). When it is finally removed, its stream must not delete
+    // the entry which a newer stream of the same name now owns.
+    let oldConsumer = demux.createConsumer('hello');
+    oldConsumer.return();
+    assert.equal(demux.streams['hello'], undefined);
+
+    // Reusing it re-registers it on the stream which is no longer in the map.
+    oldConsumer.next();
+    await wait(10);
+
+    let newConsumer = demux.createConsumer('hello');
+    let newStream = demux.streams['hello'];
+    let received = [];
+    let consumeNew = (async () => {
+      for await (let packet of newConsumer) {
+        received.push(packet);
+      }
+    })();
+
+    await wait(10);
+
+    oldConsumer.return();
+
+    assert.equal(demux.streams['hello'], newStream);
+    assert.equal(demux.hasConsumerAll(newConsumer.id), true);
+
+    demux.write('hello', 'still-working');
+    demux.close('hello');
+    await consumeNew;
+
+    assert.equal(JSON.stringify(received), JSON.stringify(['still-working']));
+  });
 });