@toa.io/extensions.exposition 1.0.0-alpha.313 → 1.0.0-alpha.314

package/components/exposition.octets/package.json

@@ -3,8 +3,8 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@aws-sdk/client-s3": "3.1131.0",
-    "@aws-sdk/lib-storage": "3.1131.0",
+    "@aws-sdk/client-s3": "3.1133.0",
+    "@aws-sdk/lib-storage": "3.1133.0",
     "cloudinary": "2.11.0"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.exposition",
-  "version": "1.0.0-alpha.313",
+  "version": "1.0.0-alpha.314",
   "type": "module",
   "description": "Toa Exposition",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -28,11 +28,13 @@
     "!**/.env*"
   ],
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.312",
-    "@toa.io/definitions": "1.0.0-alpha.313",
+    "@toa.io/core": "1.0.0-alpha.314",
+    "@toa.io/definitions": "1.0.0-alpha.314",
     "@toa.io/generic": "1.0.0-alpha.311",
+    "@toa.io/pointer": "1.0.0-alpha.311",
     "@toa.io/schemas": "1.0.0-alpha.311",
     "content-type": "3.1.0",
+    "ioredis": "6.0.0",
     "matchacho": "0.6.1",
     "minimatch": "10.2.6",
     "msgpackr": "2.1.0",
@@ -72,5 +74,5 @@
     "lru-cache": "11.5.2",
     "paseto": "4.0.1"
   },
-  "gitHead": "7da3b2627ceeefd1fa19d5c8851be88d928523b6"
+  "gitHead": "4b7c0f4468e6fa89f95a69f43fed85c648fb033d"
 }

package/readme.md

@@ -219,6 +219,7 @@ See also [telemetry ready probe](../telemetry/readme.md#ready-probe) and
 - [OAuth authorization server](documentation/oauth.md)
 - [Consent](documentation/consent.md)
 - [BLOBs](documentation/octets.md)
+- [Realtime streams](documentation/realtime.md)
 - [Components and resources](documentation/components.md)
 - [Caching](documentation/cache.md)
 - [Features](features)

package/transpiled/Factory.d.ts

@@ -1,7 +1,12 @@
+import { Realtime } from './realtime/Factory.ts';
 import type { syntax } from './RTD/index.ts';
 import type { Connector, Contract, Locator } from '@toa.io/core';
 import type { extensions } from '@toa.io/core/types';
 export declare class Factory implements extensions.Factory {
+    /** `realtime`, declared beside `exposition`: the routes of a component's events to streams */
+    readonly keys: {
+        realtime: Realtime;
+    };
     private readonly host;
     private announcing;
     private announcements;

package/transpiled/Factory.js

@@ -2,8 +2,11 @@ import { createHash } from 'node:crypto';
 import { contract } from '@toa.io/core';
 import { Announcements } from './Announcements.js';
 import { Tenant } from './Tenant.js';
+import { Realtime } from './realtime/Factory.js';
 import { CHANNEL } from '@toa.io/definitions/extensions.exposition';
 export class Factory {
+    /** `realtime`, declared beside `exposition`: the routes of a component's events to streams */
+    keys = { realtime: new Realtime() };
     host;
     announcing;
     announcements;

package/transpiled/Factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"Factory.js","sourceRoot":"","sources":["../source/Factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,2CAA2C,CAAA;AAMnE,MAAM,OAAO,OAAO;IACD,IAAI,CAAM;IACnB,UAAU,CAAoC;IAC9C,aAAa,CAA2B;IAEhD,YAAmB,IAAU;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAEM,KAAK,CAAC,MAAM,CACjB,OAAgB,EAChB,IAAiB,EACjB,QAAkB;QAElB,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAA;QACzC,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAE9E,4EAA4E;QAC5E,MAAM,MAAM,GAA8B;YACxC,oFAAoF;YACpF,SAAS,EAAE,OAAO,CAAC,SAAU;YAC7B,SAAS,EAAE,OAAO,CAAC,IAAI;YACvB,QAAQ,EAAE,OAAO,CAAC,SAAS,KAAK,UAAU;YAC1C,IAAI;YACJ,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,QAAQ,EAAE,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC;YACtC,MAAM;SACP,CAAA;QAED,OAAO,IAAI,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAA;IAC1C,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,MAAM;QAClB,IAAI,IAAI,CAAC,aAAa,EAAE,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC1C,IAAI,CAAC,UAAU,GAAG,SAAS,CAAA;YAC3B,IAAI,CAAC,aAAa,GAAG,SAAS,CAAA;QAChC,CAAC;QAED,IAAI,CAAC,UAAU,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAA;QAEnC,OAAO,MAAM,IAAI,CAAC,UAAU,CAAA;IAC9B,CAAC;IAEO,KAAK,CAAC,QAAQ;QACpB,MAAM,aAAa,GAAG,IAAI,aAAa,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAA;QAE3E,IAAI,CAAC,aAAa,GAAG,aAAa,CAAA;QAElC,OAAO,aAAa,CAAA;IACtB,CAAC;IAEM,KAAK,CAAC,OAAO;QAClB,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,CAAA;QAEhD,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACjC,CAAC;CACF"}
+{"version":3,"file":"Factory.js","sourceRoot":"","sources":["../source/Factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,2CAA2C,CAAA;AAMnE,MAAM,OAAO,OAAO;IAClB,8FAA8F;IAC9E,IAAI,GAAG,EAAE,QAAQ,EAAE,IAAI,QAAQ,EAAE,EAAE,CAAA;IAElC,IAAI,CAAM;IACnB,UAAU,CAAoC;IAC9C,aAAa,CAA2B;IAEhD,YAAmB,IAAU;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAEM,KAAK,CAAC,MAAM,CACjB,OAAgB,EAChB,IAAiB,EACjB,QAAkB;QAElB,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAA;QACzC,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAE9E,4EAA4E;QAC5E,MAAM,MAAM,GAA8B;YACxC,oFAAoF;YACpF,SAAS,EAAE,OAAO,CAAC,SAAU;YAC7B,SAAS,EAAE,OAAO,CAAC,IAAI;YACvB,QAAQ,EAAE,OAAO,CAAC,SAAS,KAAK,UAAU;YAC1C,IAAI;YACJ,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,QAAQ,EAAE,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC;YACtC,MAAM;SACP,CAAA;QAED,OAAO,IAAI,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAA;IAC1C,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,MAAM;QAClB,IAAI,IAAI,CAAC,aAAa,EAAE,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC1C,IAAI,CAAC,UAAU,GAAG,SAAS,CAAA;YAC3B,IAAI,CAAC,aAAa,GAAG,SAAS,CAAA;QAChC,CAAC;QAED,IAAI,CAAC,UAAU,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAA;QAEnC,OAAO,MAAM,IAAI,CAAC,UAAU,CAAA;IAC9B,CAAC;IAEO,KAAK,CAAC,QAAQ;QACpB,MAAM,aAAa,GAAG,IAAI,aAAa,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAA;QAE3E,IAAI,CAAC,aAAa,GAAG,aAAa,CAAA;QAElC,OAAO,aAAa,CAAA;IACtB,CAAC;IAEM,KAAK,CAAC,OAAO;QAClB,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,CAAA;QAEhD,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACjC,CAAC;CACF"}

package/transpiled/directives/index.js

@@ -9,6 +9,7 @@ import { map } from './map/index.js';
 import { mcp } from './mcp/index.js';
 import { req } from './require/index.js';
 import { flow } from './flow/index.js';
+import { realtime } from './realtime/index.js';
 import { help } from './help/index.js';
 import { discovery } from './oauth/index.js';
 import { Site } from '../Discovery/index.js';
@@ -22,6 +23,7 @@ export const families = [
     req,
     flow,
     octets,
+    realtime,
     dev
 ];
 /**

package/transpiled/directives/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/directives/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC1C,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC1C,OAAO,EAAE,EAAE,EAAE,MAAM,eAAe,CAAA;AAClC,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AACpC,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AACpC,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAA;AAI5C,MAAM,CAAC,MAAM,QAAQ,GAAsB;IACzC,aAAa;IACb,EAAE;IACF,KAAK;IACL,GAAG;IACH,GAAG;IACH,IAAI;IACJ,GAAG;IACH,IAAI;IACJ,MAAM;IACN,GAAG;CACJ,CAAA;AACD;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/directives/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC1C,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC1C,OAAO,EAAE,EAAE,EAAE,MAAM,eAAe,CAAA;AAClC,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AACpC,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AACpC,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAA;AAI5C,MAAM,CAAC,MAAM,QAAQ,GAAsB;IACzC,aAAa;IACb,EAAE;IACF,KAAK;IACL,GAAG;IACH,GAAG;IACH,IAAI;IACJ,GAAG;IACH,IAAI;IACJ,MAAM;IACN,QAAQ;IACR,GAAG;CACJ,CAAA;AACD;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,CAAA"}

package/transpiled/directives/realtime/Hub.d.ts

@@ -0,0 +1,45 @@
+import { Stream } from './Stream.ts';
+/**
+ * The streams this gateway serves, by key.
+ *
+ * A key that has a reader here is subscribed to on its channel, and its stream in Redis is kept
+ * alive: a component writes a routed event only to a stream that exists, so a stream that expired
+ * under a reader would stop receiving. After its last reader leaves, the stream lives `expire`
+ * more seconds — the window that reader reconnects in with its token.
+ *
+ * A channel keeps nothing for a subscriber that was away. Whenever the subscriber is back, what
+ * each key was written meanwhile is read from its stream, from the last event this gateway
+ * delivered of it; each reader skips what it was given already.
+ */
+export declare class Hub {
+    private readonly keys;
+    private shards;
+    private subscribers;
+    private connecting;
+    private prefix;
+    /** Connects on the first stream it serves, not before: a gateway may serve none. */
+    connect(): Promise<void>;
+    close(): void;
+    private start;
+    open(key: string, token?: string): Promise<Stream>;
+    private enter;
+    private leave;
+    /** Creates the stream where it is gone, and answers where it ends now. */
+    private marker;
+    private read;
+    private receive;
+    private broadcast;
+    /**
+     * What every key was written while the subscriber was away. Its channels are subscribed to
+     * again first, where the client has not done it on its own, so nothing written after the read
+     * is missed.
+     */
+    private recover;
+    /** The connection a key's stream is kept on. */
+    private redis;
+    private subscriber;
+    private expire;
+    /** Well within the expiry, and no more often than the heartbeat where that is. */
+    private renewal;
+    private renew;
+}

package/transpiled/directives/realtime/Hub.js

@@ -0,0 +1,221 @@
+import { console } from 'openspan';
+import { Stream, HEARTBEAT, decode, encode } from './Stream.js';
+import { MAXLEN, Shards, expire, prefix, shard } from '../../realtime/redis.js';
+import * as measure from './measurements.js';
+/**
+ * The streams this gateway serves, by key.
+ *
+ * A key that has a reader here is subscribed to on its channel, and its stream in Redis is kept
+ * alive: a component writes a routed event only to a stream that exists, so a stream that expired
+ * under a reader would stop receiving. After its last reader leaves, the stream lives `expire`
+ * more seconds — the window that reader reconnects in with its token.
+ *
+ * A channel keeps nothing for a subscriber that was away. Whenever the subscriber is back, what
+ * each key was written meanwhile is read from its stream, from the last event this gateway
+ * delivered of it; each reader skips what it was given already.
+ */
+export class Hub {
+    keys = new Map();
+    shards = null;
+    // a subscribing connection can do nothing else, so each Redis has one of its own
+    subscribers = null;
+    connecting = null;
+    prefix = '';
+    /** Connects on the first stream it serves, not before: a gateway may serve none. */
+    async connect() {
+        this.connecting ??= this.start();
+        await this.connecting;
+    }
+    close() {
+        for (const { streams, timer } of this.keys.values()) {
+            clearInterval(timer);
+            for (const stream of streams)
+                stream.close();
+        }
+        this.keys.clear();
+        this.subscribers?.disconnect();
+        this.shards?.disconnect();
+        this.subscribers = null;
+        this.shards = null;
+        this.connecting = null;
+    }
+    async start() {
+        this.prefix = prefix();
+        const shards = new Shards();
+        const subscribers = new Shards();
+        for (const connection of [...shards.connections, ...subscribers.connections])
+            connection.on('error', (error) => console.debug('Realtime streams unreachable', {
+                error: error.code ?? error.message
+            }));
+        subscribers.connections.forEach((subscriber, i) => {
+            // a key's channel is subscribed to by the key, the prefix applying to it; what arrives is
+            // named in full
+            subscriber.on('smessage', (channel, message) => this.receive(channel.slice(this.prefix.length), message));
+            // `ready` follows every reconnect too, and what was written meanwhile never arrives
+            let connected = false;
+            subscriber.on('ready', () => {
+                if (connected)
+                    void this.recover(i);
+                connected = true;
+            });
+        });
+        this.shards = shards;
+        this.subscribers = subscribers;
+        await Promise.all([shards.connect(), subscribers.connect()]);
+    }
+    async open(key, token) {
+        await this.connect();
+        const stream = new Stream();
+        const entry = await this.enter(key, stream);
+        stream.once('close', () => this.leave(key, stream));
+        // welcome: a reader knows it is connected before anything is written
+        setTimeout(() => stream.heartbeat(), 1000).unref();
+        // written after the subscription, so nothing written after it misses this reader, and on
+        // every connection: a stream that expired while its reader was away is created again, or
+        // nothing would be written to it
+        const marker = await this.marker(key);
+        entry.last ??= marker;
+        const cursor = token === undefined ? marker : decode(token);
+        const entries = token === undefined ? [] : await this.read(key, cursor);
+        stream.cursor = cursor;
+        stream.ready(entries);
+        // nothing was written since: the reader goes on from here
+        if (entries.length === 0)
+            stream.token(encode(marker));
+        return stream;
+    }
+    async enter(key, stream) {
+        let entry = this.keys.get(key);
+        if (entry === undefined) {
+            entry = {
+                streams: new Set(),
+                last: null,
+                timer: setInterval(() => this.renew(key), this.renewal()),
+                subscribed: this.subscriber(key)
+                    .ssubscribe(key)
+                    .then(() => undefined)
+            };
+            entry.timer.unref();
+            this.keys.set(key, entry);
+        }
+        entry.streams.add(stream);
+        // the first reader subscribes, and every reader waits for it: nothing is read or written
+        // for this one before the channel carries the key
+        await entry.subscribed;
+        return entry;
+    }
+    leave(key, stream) {
+        const entry = this.keys.get(key);
+        if (entry === undefined)
+            return;
+        entry.streams.delete(stream);
+        if (entry.streams.size > 0)
+            return;
+        clearInterval(entry.timer);
+        this.keys.delete(key);
+        this.renew(key);
+        this.subscriber(key)
+            .sunsubscribe(key)
+            .catch((error) => console.debug('Realtime key not unsubscribed', { key, error }));
+    }
+    /** Creates the stream where it is gone, and answers where it ends now. */
+    async marker(key) {
+        const [[error, id]] = (await this.redis(key)
+            .multi()
+            .xadd(key, 'MAXLEN', '~', MAXLEN, '*', 'type', 'connect')
+            .expire(key, this.expire())
+            .exec());
+        if (error !== null)
+            throw error;
+        return id;
+    }
+    async read(key, after) {
+        const results = await this.redis(key).xread('STREAMS', key, after);
+        const entries = [];
+        for (const [id, fields] of records(results)) {
+            const [, event, , data] = fields;
+            // the marker a reader wrote is a position, not an event
+            if (event === 'connect')
+                continue;
+            entries.push({ id, event, data: data === undefined ? undefined : JSON.parse(data) });
+        }
+        return entries;
+    }
+    receive(key, message) {
+        const entry = this.keys.get(key);
+        if (entry === undefined)
+            return;
+        const [id, event, data] = JSON.parse(message);
+        this.broadcast(entry, { id, event, data: JSON.parse(data) });
+    }
+    broadcast(entry, event) {
+        entry.last = event.id;
+        for (const stream of entry.streams)
+            stream.deliver(event);
+        measure.deliver(event.event);
+    }
+    /**
+     * What every key was written while the subscriber was away. Its channels are subscribed to
+     * again first, where the client has not done it on its own, so nothing written after the read
+     * is missed.
+     */
+    async recover(i) {
+        const n = this.shards?.connections.length ?? 1;
+        const keys = [...this.keys.keys()].filter((key) => shard(key, n) === i);
+        if (keys.length > 0)
+            await this.subscribers?.connections[i].ssubscribe(...keys).catch((error) => {
+                console.warn('Realtime keys not subscribed again', { error });
+            });
+        for (const key of keys) {
+            const entry = this.keys.get(key);
+            // its last reader left meanwhile
+            if (entry === undefined)
+                continue;
+            try {
+                const after = entry.last ?? '0';
+                for (const event of await this.read(key, after))
+                    this.broadcast(entry, event);
+            }
+            catch (error) {
+                console.warn('Realtime key not recovered', { key, error });
+            }
+        }
+    }
+    /** The connection a key's stream is kept on. */
+    redis(key) {
+        return this.shards.of(key);
+    }
+    subscriber(key) {
+        return this.subscribers.of(key);
+    }
+    expire() {
+        return expire();
+    }
+    /** Well within the expiry, and no more often than the heartbeat where that is. */
+    renewal() {
+        return Math.min(HEARTBEAT, (this.expire() * 1000) / 3);
+    }
+    renew(key) {
+        this.shards
+            ?.of(key)
+            .expire(key, this.expire())
+            .catch((error) => {
+            // the next renewal tries again, well within the expiry
+            console.debug('Realtime key not renewed', { key, error });
+        });
+    }
+}
+/**
+ * The entries `XREAD` answers for one stream: an array of `[stream, entries]` pairs over RESP2,
+ * an object keyed by stream over RESP3, and nothing where nothing was written since.
+ */
+function records(results) {
+    if (Array.isArray(results))
+        return results.length === 0
+            ? []
+            : results[0][1];
+    if (typeof results === 'object' && results !== null)
+        return Object.values(results)[0] ?? [];
+    return [];
+}
+//# sourceMappingURL=Hub.js.map

package/transpiled/directives/realtime/Hub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Hub.js","sourceRoot":"","sources":["../../../source/directives/realtime/Hub.ts"],"names":[],"mappings":"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"}

package/transpiled/directives/realtime/Realtime.d.ts

@@ -0,0 +1,18 @@
+import type { Context } from '../../HTTP/index.ts';
+import type { DirectiveFamily, Parameter } from '../../RTD/index.ts';
+import type { Output } from '../../io.ts';
+/**
+ * `realtime:stream` answers with the stream of the key a route variable names. Who may read it is
+ * what the route's own directives say, as for anything else it serves.
+ */
+export declare class Realtime implements DirectiveFamily<Directive> {
+    readonly name = "realtime";
+    readonly mandatory = false;
+    private readonly hub;
+    create(name: string, value: unknown, _: unknown, route: string): Directive;
+    precall(directives: Directive[], context: Context, parameters: Parameter[]): Promise<Output>;
+    dispose(): void;
+}
+export interface Directive {
+    variable: string;
+}

package/transpiled/directives/realtime/Realtime.js

@@ -0,0 +1,37 @@
+import { NotFound } from '../../HTTP/index.js';
+import { configured } from '../../realtime/redis.js';
+import { Hub } from './Hub.js';
+/**
+ * `realtime:stream` answers with the stream of the key a route variable names. Who may read it is
+ * what the route's own directives say, as for anything else it serves.
+ */
+export class Realtime {
+    name = 'realtime';
+    mandatory = false;
+    hub = new Hub();
+    // the arguments every family is given a directive with
+    // eslint-disable-next-line max-params
+    create(name, value, _, route) {
+        if (name !== 'stream')
+            throw new Error(`Directive 'realtime:${name}' is not implemented`);
+        if (typeof value !== 'string' || !route.includes(`:${value}`))
+            throw new Error(`'realtime:stream' names the route variable that is the key, and '${String(value)}' ` +
+                `is not one of '${route}'`);
+        return { variable: value };
+    }
+    async precall(directives, context, parameters) {
+        const [directive] = directives;
+        const key = parameters.find(({ name }) => name === directive.variable)?.value;
+        if (key === undefined)
+            throw new Error(`Route variable '${directive.variable}' is not found`);
+        // nothing in the context declares realtime, so nothing is kept to be read
+        if (!configured())
+            throw new NotFound('Realtime streams are not configured');
+        const token = context.url.searchParams.get('token') ?? undefined;
+        return { body: await this.hub.open(key, token) };
+    }
+    dispose() {
+        this.hub.close();
+    }
+}
+//# sourceMappingURL=Realtime.js.map

package/transpiled/directives/realtime/Realtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Realtime.js","sourceRoot":"","sources":["../../../source/directives/realtime/Realtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACpD,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAK9B;;;GAGG;AACH,MAAM,OAAO,QAAQ;IACH,IAAI,GAAG,UAAU,CAAA;IACjB,SAAS,GAAG,KAAK,CAAA;IAEhB,GAAG,GAAG,IAAI,GAAG,EAAE,CAAA;IAEhC,uDAAuD;IACvD,sCAAsC;IAC/B,MAAM,CAAC,IAAY,EAAE,KAAc,EAAE,CAAU,EAAE,KAAa;QACnE,IAAI,IAAI,KAAK,QAAQ;YACnB,MAAM,IAAI,KAAK,CAAC,uBAAuB,IAAI,sBAAsB,CAAC,CAAA;QAEpE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,EAAE,CAAC;YAC3D,MAAM,IAAI,KAAK,CACb,oEAAoE,MAAM,CAAC,KAAK,CAAC,IAAI;gBACnF,kBAAkB,KAAK,GAAG,CAC7B,CAAA;QAEH,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAA;IAC5B,CAAC;IAEM,KAAK,CAAC,OAAO,CAClB,UAAuB,EACvB,OAAgB,EAChB,UAAuB;QAEvB,MAAM,CAAC,SAAS,CAAC,GAAG,UAAU,CAAA;QAC9B,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAA;QAE7E,IAAI,GAAG,KAAK,SAAS;YACnB,MAAM,IAAI,KAAK,CAAC,mBAAmB,SAAS,CAAC,QAAQ,gBAAgB,CAAC,CAAA;QAExE,0EAA0E;QAC1E,IAAI,CAAC,UAAU,EAAE;YAAE,MAAM,IAAI,QAAQ,CAAC,qCAAqC,CAAC,CAAA;QAE5E,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,SAAS,CAAA;QAEhE,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAAA;IAClD,CAAC;IAEM,OAAO;QACZ,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAA;IAClB,CAAC;CACF"}

package/transpiled/directives/realtime/Stream.d.ts

@@ -0,0 +1,38 @@
+import { Readable } from 'node:stream';
+/**
+ * One reader of a key: what it is sent, in order, and a heartbeat while nothing is.
+ *
+ * `cursor` is the id of the last event it was given. What arrives while it is being replayed to
+ * is held until the replay is done, and whatever it was given already is not given again: a replay
+ * and the channel may both carry the same event.
+ */
+export declare class Stream extends Readable {
+    cursor: string | null;
+    private held;
+    private interval;
+    private ended;
+    constructor();
+    _read(): void;
+    _destroy(error: Error | null, callback: (error?: Error | null) => void): void;
+    /** An event of the key, or one held back while the replay is in flight. */
+    deliver(entry: Entry): void;
+    /** What the replay found is sent, then what was held back meanwhile, and from now on as it comes. */
+    ready(entries: Entry[]): void;
+    token(token: string): void;
+    heartbeat(): void;
+    /** Ends it: whoever reads it gets the end, not a broken pipe. */
+    close(): void;
+    private write;
+    private send;
+    private stop;
+}
+export interface Entry {
+    id: string;
+    event: string;
+    data: unknown;
+}
+export declare function encode(id: string): string;
+export declare function decode(token: string): string;
+/** Stream ids are `<ms>-<seq>`, ordered as two numbers. */
+export declare function compare(a: string, b: string): number;
+export declare const HEARTBEAT = 16000;

package/transpiled/directives/realtime/Stream.js

@@ -0,0 +1,89 @@
+import { Readable } from 'node:stream';
+/**
+ * One reader of a key: what it is sent, in order, and a heartbeat while nothing is.
+ *
+ * `cursor` is the id of the last event it was given. What arrives while it is being replayed to
+ * is held until the replay is done, and whatever it was given already is not given again: a replay
+ * and the channel may both carry the same event.
+ */
+export class Stream extends Readable {
+    cursor = null;
+    held = [];
+    interval = null;
+    ended = false;
+    constructor() {
+        super({ objectMode: true });
+    }
+    // a stream is read from when the reply is written, and the heartbeat starts with the reading
+    _read() {
+        this.interval ??= setInterval(() => this.heartbeat(), HEARTBEAT);
+    }
+    _destroy(error, callback) {
+        this.stop();
+        callback(error);
+    }
+    /** An event of the key, or one held back while the replay is in flight. */
+    deliver(entry) {
+        if (this.held !== null) {
+            this.held.push(entry);
+            return;
+        }
+        this.write(entry);
+    }
+    /** What the replay found is sent, then what was held back meanwhile, and from now on as it comes. */
+    ready(entries) {
+        const held = this.held ?? [];
+        this.held = null;
+        for (const entry of entries)
+            this.write(entry);
+        for (const entry of held)
+            this.write(entry);
+    }
+    token(token) {
+        this.send({ event: 'token', data: token });
+    }
+    heartbeat() {
+        this.send('heartbeat ' + Date.now());
+    }
+    /** Ends it: whoever reads it gets the end, not a broken pipe. */
+    close() {
+        this.stop();
+        this.ended = true;
+        this.push(null);
+    }
+    write(entry) {
+        if (this.cursor !== null && compare(entry.id, this.cursor) <= 0)
+            return;
+        this.cursor = entry.id;
+        this.send({ event: entry.event, data: entry.data });
+        this.token(encode(entry.id));
+    }
+    send(message) {
+        if (this.ended || this.destroyed)
+            return;
+        this.push(message);
+    }
+    stop() {
+        if (this.interval !== null)
+            clearInterval(this.interval);
+        this.interval = null;
+    }
+}
+export function encode(id) {
+    return Buffer.from(id).toString('base64url');
+}
+export function decode(token) {
+    return Buffer.from(token, 'base64url').toString();
+}
+/** Stream ids are `<ms>-<seq>`, ordered as two numbers. */
+export function compare(a, b) {
+    const [ams, aseq] = a.split('-').map(BigInt);
+    const [bms, bseq] = b.split('-').map(BigInt);
+    if (ams !== bms)
+        return ams < bms ? -1 : 1;
+    if (aseq !== bseq)
+        return aseq < bseq ? -1 : 1;
+    return 0;
+}
+export const HEARTBEAT = 16_000;
+//# sourceMappingURL=Stream.js.map

package/transpiled/directives/realtime/Stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Stream.js","sourceRoot":"","sources":["../../../source/directives/realtime/Stream.ts"],"names":[],"mappings":"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"}

package/transpiled/directives/realtime/index.d.ts

@@ -0,0 +1,2 @@
+import { Realtime } from './Realtime.ts';
+export declare const realtime: Realtime;

package/transpiled/directives/realtime/index.js

@@ -0,0 +1,3 @@
+import { Realtime } from './Realtime.js';
+export const realtime = new Realtime();
+//# sourceMappingURL=index.js.map

package/transpiled/directives/realtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../source/directives/realtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC,MAAM,CAAC,MAAM,QAAQ,GAAG,IAAI,QAAQ,EAAE,CAAA"}

package/transpiled/directives/realtime/measurements.d.ts

@@ -0,0 +1 @@
+export declare function deliver(event: string): void;

package/transpiled/directives/realtime/measurements.js

@@ -0,0 +1,11 @@
+import { registry } from 'openspan';
+/**
+ * Counted where the gateway pushes an event to the readers of a key it serves. Against
+ * `toa.realtime.routed`, which the components that write events count, it says what arrived.
+ */
+const meters = registry();
+const delivered = meters.counter('toa.realtime.delivered', { event: null });
+export function deliver(event) {
+    delivered.add(1, { event });
+}
+//# sourceMappingURL=measurements.js.map

package/transpiled/directives/realtime/measurements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"measurements.js","sourceRoot":"","sources":["../../../source/directives/realtime/measurements.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnC;;;GAGG;AACH,MAAM,MAAM,GAAG,QAAQ,EAAE,CAAA;AAEzB,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,wBAAwB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;AAE3E,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;AAC7B,CAAC"}

package/transpiled/realtime/Destination.d.ts

@@ -0,0 +1,24 @@
+import { Connector, type Locator } from '@toa.io/core';
+import type { Route } from '@toa.io/definitions/extensions.exposition/realtime';
+import type { outbox } from '@toa.io/core/types';
+/**
+ * Where a component's routed events go: the stream of each of their keys, and its channel. Each
+ * event of a row is rendered by the component's own condition and payload, fitted to what its
+ * route exposes, and written in one call per Redis its keys are kept on — to the streams of them
+ * that exist, which are the ones that are consumed.
+ *
+ * At least once: a row written again by the pump is written to the streams again.
+ */
+export declare class Destination extends Connector implements outbox.Destination {
+    readonly name = "realtime";
+    readonly renders: string[];
+    rendering?: outbox.Rendering;
+    private readonly locator;
+    private readonly routes;
+    private shards;
+    constructor(locator: Locator, routes: Route[]);
+    emit(row: outbox.Row): Promise<void>;
+    protected open(): Promise<void>;
+    protected close(): Promise<void>;
+    private route;
+}