@toa.io/extensions.realtime 1.0.0-alpha.30 → 1.0.0-alpha.300

package/components/realtime.streams/manifest.toa.yaml

@@ -0,0 +1,49 @@
+namespace: realtime
+name: streams
+
+operations:
+  create:
+    input:
+      properties:
+        key:
+          type: string
+        token:
+          type: string
+      type: object
+  push:
+    output: { type: 'null' }
+    bindings: ~ # only for internal use
+    input:
+      properties:
+        data: {}
+        key:
+          type: string
+        event:
+          type: string
+      type: object
+      required:
+        - key
+        - event
+
+configuration:
+  schema:
+    properties:
+      maxlen:
+        type: number
+      expire:
+        type: number
+    type: object
+    # both have defaults, so the component reads them without checking
+    required: [maxlen, expire]
+
+  defaults:
+    maxlen: 1000
+    expire: 300
+
+state: ~
+stash: ~
+
+exposition:
+  /:key:
+    auth:id: key
+    GET: create

package/components/realtime.streams/operations/create.js

@@ -0,0 +1,65 @@
+import { Stream, Stash } from './lib/index.js';
+export class Effect {
+    streams = new Map();
+    stash;
+    logs;
+    mount(context) {
+        context.state.streams = this.streams;
+        context.state.stash = new Stash(context.stash, context.configuration, context.logs);
+        this.logs = context.logs;
+        this.stash = context.state.stash;
+    }
+    unmount() {
+        this.logs.info('Destroying streams', { count: this.streams.size });
+        // closed, not destroyed: destroying a stream that is still piped to a response
+        // makes end-of-stream report a premature close, which reaches no one and takes
+        // the process down.
+        for (const stream of this.streams.values())
+            stream.close();
+    }
+    async execute(input) {
+        const key = input.key;
+        if (!this.streams.has(key)) {
+            const stream = this.createStream(key);
+            this.streams.set(key, stream);
+            this.logs.debug('Stream created', { key });
+        }
+        // welcome
+        setTimeout(() => this.streams.get(key)?.heartbeat(), 1000);
+        if (input.token === undefined)
+            void this.stash.connect(key).then((token) => {
+                if (token instanceof Error)
+                    this.logs.error('Failed to connect to stash', { key, error: token });
+                else
+                    this.streams.get(key)?.push({ event: 'token', data: token });
+            });
+        else
+            void this.stash.pop(key, input.token).then((result) => {
+                if (result === null)
+                    return;
+                if ('code' in result && result.code === 'NO_RESULTS')
+                    return;
+                if (result instanceof Error) {
+                    this.logs.error('Failed to pop from stash', { key, error: result });
+                    return;
+                }
+                const stream = this.streams.get(key);
+                if (stream === undefined)
+                    return;
+                const [token, events] = result;
+                for (const event of events)
+                    stream.push({ event: event.event, data: event.data });
+                stream.push({ event: 'token', data: token });
+            });
+        return this.streams.get(key);
+    }
+    createStream(key) {
+        const stream = new Stream();
+        stream.events.once('destroy', () => {
+            this.logs.debug('Stream destroyed', { key });
+            this.streams.delete(key);
+        });
+        return stream;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY3JlYXRlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc291cmNlL2NyZWF0ZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFHQSxPQUFPLEVBQUUsTUFBTSxFQUFFLEtBQUssRUFBRSxNQUFNLGdCQUFnQixDQUFBO0FBRTlDLE1BQU0sT0FBTyxNQUFNO0lBQ0EsT0FBTyxHQUFHLElBQUksR0FBRyxFQUFrQixDQUFBO0lBQzVDLEtBQUssQ0FBUTtJQUNiLElBQUksQ0FBSztJQUVWLEtBQUssQ0FBQyxPQUFnQjtRQUMzQixPQUFPLENBQUMsS0FBSyxDQUFDLE9BQU8sR0FBRyxJQUFJLENBQUMsT0FBTyxDQUFBO1FBQ3BDLE9BQU8sQ0FBQyxLQUFLLENBQUMsS0FBSyxHQUFHLElBQUksS0FBSyxDQUFDLE9BQU8sQ0FBQyxLQUFLLEVBQUUsT0FBTyxDQUFDLGFBQWEsRUFBRSxPQUFPLENBQUMsSUFBSSxDQUFDLENBQUE7UUFFbkYsSUFBSSxDQUFDLElBQUksR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFBO1FBQ3hCLElBQUksQ0FBQyxLQUFLLEdBQUcsT0FBTyxDQUFDLEtBQUssQ0FBQyxLQUFLLENBQUE7SUFDbEMsQ0FBQztJQUVNLE9BQU87UUFDWixJQUFJLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxvQkFBb0IsRUFBRSxFQUFFLEtBQUssRUFBRSxJQUFJLENBQUMsT0FBTyxDQUFDLElBQUksRUFBRSxDQUFDLENBQUE7UUFFbEUsK0VBQStFO1FBQy9FLCtFQUErRTtRQUMvRSxvQkFBb0I7UUFDcEIsS0FBSyxNQUFNLE1BQU0sSUFBSSxJQUFJLENBQUMsT0FBTyxDQUFDLE1BQU0sRUFBRTtZQUFFLE1BQU0sQ0FBQyxLQUFLLEVBQUUsQ0FBQTtJQUM1RCxDQUFDO0lBRU0sS0FBSyxDQUFDLE9BQU8sQ0FBQyxLQUFZO1FBQy9CLE1BQU0sR0FBRyxHQUFHLEtBQUssQ0FBQyxHQUFHLENBQUE7UUFFckIsSUFBSSxDQUFDLElBQUksQ0FBQyxPQUFP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

package/components/realtime.streams/operations/lib/Stash.js

@@ -0,0 +1,86 @@
+export class Stash {
+    stash;
+    configuration;
+    logs;
+    constructor(stash, configuration, logs) {
+        this.stash = stash;
+        this.configuration = configuration;
+        this.logs = logs;
+    }
+    async connect(key) {
+        return await this.xadd(key, 'connect');
+    }
+    async push(key, event, data) {
+        return await this.xadd(key, event, data);
+    }
+    async pop(key, token) {
+        const stamp = this.decode(token);
+        const results = await this.stash
+            .xread('STREAMS', key, stamp)
+            .catch((error) => error);
+        if (results === null)
+            return ERR_NO_RESULTS;
+        if (results instanceof Error)
+            return results;
+        const items = entries(results);
+        if (items === null)
+            return null;
+        const events = [];
+        let lastStamp = null;
+        for (const item of items) {
+            const [, event, , json] = item[1];
+            lastStamp = item[0];
+            const data = json === undefined ? undefined : JSON.parse(json);
+            if (data === undefined)
+                this.logs.debug('Undefined event payload', { key, event });
+            events.push({ event, data });
+        }
+        if (lastStamp === null)
+            return null;
+        return [this.encode(lastStamp), events];
+    }
+    async xadd(key, event, data) {
+        const args = ['MAXLEN', '~', this.configuration.maxlen, '*', 'type', event];
+        if (data !== undefined)
+            args.push('data', JSON.stringify(data));
+        const results = await this.stash
+            .multi()
+            .xadd(key, ...args)
+            .expire(key, this.configuration.expire)
+            .exec()
+            .catch((error) => error);
+        if (results === null)
+            return ERR_NO_RESULTS;
+        if (results instanceof Error)
+            return results;
+        const [[error, stamp]] = results;
+        if (error !== null)
+            return error;
+        return this.encode(stamp);
+    }
+    encode(token) {
+        return Buffer.from(token).toString('base64url');
+    }
+    decode(token) {
+        return Buffer.from(token, 'base64url').toString();
+    }
+}
+/**
+ * `xread` answers with an array of `[stream, entries]` pairs over RESP2 and with an
+ * object keyed by stream name over RESP3. One stream is read, so either way it is the
+ * first, and an empty answer means nothing has been added since the token.
+ */
+function entries(results) {
+    if (Array.isArray(results))
+        return results.length === 0 ? null : results[0][1];
+    if (typeof results === 'object' && results !== null) {
+        const streams = Object.values(results);
+        return streams.length === 0 ? null : streams[0];
+    }
+    return null;
+}
+class NoResultsError extends Error {
+    code = 'NO_RESULTS';
+}
+const ERR_NO_RESULTS = new NoResultsError();
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiU3Rhc2guanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zb3VyY2UvbGliL1N0YXNoLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUVBLE1BQU0sT0FBTyxLQUFLO0lBQ0MsS0FBSyxDQUFPO0lBQ1osYUFBYSxDQUFlO0lBQzVCLElBQUksQ0FBSztJQUUxQixZQUFtQixLQUFVLEVBQUUsYUFBNEIsRUFBRSxJQUFTO1FBQ3BFLElBQUksQ0FBQyxLQUFLLEdBQUcsS0FBSyxDQUFBO1FBQ2xCLElBQUksQ0FBQyxhQUFhLEdBQUcsYUFBYSxDQUFBO1FBQ2xDLElBQUksQ0FBQyxJQUFJLEdBQUcsSUFBSSxDQUFBO0lBQ2xCLENBQUM7SUFFTSxLQUFLLENBQUMsT0FBTyxDQUFDLEdBQVc7UUFDOUIsT0FBTyxNQUFNLElBQUksQ0FBQyxJQUFJLENBQUMsR0FBRyxFQUFFLFNBQVMsQ0FBQyxDQUFBO0lBQ3hDLENBQUM7SUFFTSxLQUFLLENBQUMsSUFBSSxDQUFDLEdBQVcsRUFBRSxLQUFhLEVBQUUsSUFBYTtRQUN6RCxPQUFPLE1BQU0sSUFBSSxDQUFDLElBQUksQ0FBQyxHQUFHLEVBQUUsS0FBSyxFQUFFLElBQUksQ0FBQyxDQUFBO0lBQzFDLENBQUM7SUFFTSxLQUFLLENBQUMsR0FBRyxDQUNkLEdBQVcsRUFDWCxLQUFhO1FBRWIsTUFBTSxLQUFLLEdBQUcsSUFBSSxDQUFDLE1BQU0sQ0FBQyxLQUFLLENBQUMsQ0FBQTtRQUVoQyxNQUFNLE9BQU8sR0FBRyxNQUFNLElBQUksQ0FBQyxLQUFLO2FBQzdCLEtBQUssQ0FBQyxTQUFTLEVBQUUsR0FBRyxFQUFFLEtBQUssQ0FBQzthQUM1QixLQUFLLENBQUMsQ0FBQyxLQUFZLEVBQUUsRUFBRSxDQUFDLEtBQUssQ0FBQyxDQUFBO1FBRWpDLElBQUksT0FBTyxLQUFLLElBQUk7WUFBRSxPQUFPLGNBQWMsQ0FBQTtRQUUzQyxJQUFJLE9BQU8sWUFBWSxLQUFLO1lBQUUsT0FBTyxPQUFPLENBQUE7UUFF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

package/components/realtime.streams/operations/lib/Stream.js

@@ -0,0 +1,43 @@
+import { EventEmitter } from 'node:events';
+import { Readable } from 'node:stream';
+export class Stream extends Readable {
+    events = new EventEmitter();
+    interval = null;
+    ended = false;
+    constructor() {
+        super(objectMode);
+    }
+    // has to be here
+    _read() {
+        if (this.interval === null)
+            this.interval = setInterval(() => this.heartbeat(), HEARTBEAT_INTERVAL);
+    }
+    _destroy(error, callback) {
+        if (this.interval !== null)
+            clearInterval(this.interval);
+        this.events.emit('destroy');
+        super._destroy(error, callback);
+    }
+    /** Ends the stream: whoever reads it gets EOF rather than a broken pipe. */
+    close() {
+        this.ended = true;
+        if (this.interval !== null) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+        this.push(null);
+    }
+    heartbeat(stream = this) {
+        if (this.ended)
+            return false;
+        const resume = stream.push('heartbeat ' + Date.now());
+        if (!resume && this.interval !== null) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+        return resume;
+    }
+}
+const HEARTBEAT_INTERVAL = 16_000; // why?
+const objectMode = { objectMode: true };
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiU3RyZWFtLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc291cmNlL2xpYi9TdHJlYW0udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLGFBQWEsQ0FBQTtBQUMxQyxPQUFPLEVBQUUsUUFBUSxFQUFFLE1BQU0sYUFBYSxDQUFBO0FBRXRDLE1BQU0sT0FBTyxNQUFPLFNBQVEsUUFBUTtJQUMzQixNQUFNLEdBQUcsSUFBSSxZQUFZLEVBQUUsQ0FBQTtJQUUxQixRQUFRLEdBQTBCLElBQUksQ0FBQTtJQUN0QyxLQUFLLEdBQUcsS0FBSyxDQUFBO0lBRXJCO1FBQ0UsS0FBSyxDQUFDLFVBQVUsQ0FBQyxDQUFBO0lBQ25CLENBQUM7SUFFRCxpQkFBaUI7SUFDRCxLQUFLO1FBQ25CLElBQUksSUFBSSxDQUFDLFFBQVEsS0FBSyxJQUFJO1lBQ3hCLElBQUksQ0FBQyxRQUFRLEdBQUcsV0FBVyxDQUFDLEdBQUcsRUFBRSxDQUFDLElBQUksQ0FBQyxTQUFTLEVBQUUsRUFBRSxrQkFBa0IsQ0FBQyxDQUFBO0lBQzNFLENBQUM7SUFFZSxRQUFRLENBQ3RCLEtBQW1CLEVBQ25CLFFBQXdDO1FBRXhDLElBQUksSUFBSSxDQUFDLFFBQVEsS0FBSyxJQUFJO1lBQUUsYUFBYSxDQUFDLElBQUksQ0FBQyxRQUFRLENBQUMsQ0FBQTtRQUV4RCxJQUFJLENBQUMsTUFBTSxDQUFDLElBQUksQ0FBQyxTQUFTLENBQUMsQ0FBQTtRQUUzQixLQUFLLENBQUMsUUFBUSxDQUFDLEtBQUssRUFBRSxRQUFRLENBQUMsQ0FBQTtJQUNqQyxDQUFDO0lBRUQsNEVBQTRFO0lBQ3JFLEtBQUs7UUFDVixJQUFJLENBQUMsS0FBSyxHQUFHLElBQUksQ0FBQTtRQUVqQixJQUFJLElBQUksQ0FBQyxRQUFRLEtBQUssSUFBSSxFQUFFLENBQUM7WUFDM0IsYUFBYSxDQUFDLElBQUksQ0FBQyxRQUFRLENBQUMsQ0FBQTtZQUM1QixJQUFJLENBQUMsUUFBUSxHQUFHLElBQUksQ0FBQTtRQUN0QixDQUFDO1FBRUQsSUFBSSxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsQ0FBQTtJQUNqQixDQUFDO0lBRU0sU0FBUyxDQUFDLE1BQU0sR0FBYSxJQUFJO1FBQ3RDLElBQUksSUFBSSxDQUFDLEtBQUs7WUFBRSxPQUFPLEtBQUssQ0FBQTtRQUU1QixNQUFNLE1BQU0sR0FBRyxNQUFNLENBQUMsSUFBSSxDQUFDLFlBQVksR0FBRyxJQUFJLENBQUMsR0FBRyxFQUFFLENBQUMsQ0FBQTtRQUVyRCxJQUFJLENBQUMsTUFBTSxJQUFJLElBQUksQ0FBQyxRQUFRLEtBQUssSUFBSSxFQUFFLENBQUM7WUFDdEMsYUFBYSxDQUFDLElBQUksQ0FBQyxRQUFRLENBQUMsQ0FBQTtZQUM1QixJQUFJLENBQUMsUUFBUSxHQUFHLElBQUksQ0FBQTtRQUN0QixDQUFDO1FBRUQsT0FBTyxNQUFNLENBQUE7SUFDZixDQUFDO0NBQ0Y7QUFFRCxNQUFNLGtCQUFrQixHQUFHLE1BQU0sQ0FBQSxDQUFDLE9BQU87QUFDekMsTUFBTSxVQUFVLEdBQUcsRUFBRSxVQUFVLEVBQUUsSUFBSSxFQUFFLENBQUEifQ==

package/components/realtime.streams/operations/lib/index.js

@@ -0,0 +1,3 @@
+export { Stash } from './Stash.js';
+export { Stream } from './Stream.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zb3VyY2UvbGliL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxLQUFLLEVBQUUsTUFBTSxZQUFZLENBQUE7QUFDbEMsT0FBTyxFQUFFLE1BQU0sRUFBRSxNQUFNLGFBQWEsQ0FBQSJ9

package/components/realtime.streams/operations/push.js

@@ -0,0 +1,10 @@
+export async function effect({ key, event, data }, context) {
+    context.state.streams.get(key)?.push({ event, data });
+    void context.state.stash.push(key, event, data).then((token) => {
+        if (token instanceof Error)
+            context.logs.error('Failed to push to stash', { key, error: token });
+        else
+            context.state.streams.get(key)?.push({ event: 'token', data: token });
+    });
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicHVzaC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NvdXJjZS9wdXNoLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUVBLE1BQU0sQ0FBQyxLQUFLLFVBQVUsTUFBTSxDQUMxQixFQUFFLEdBQUcsRUFBRSxLQUFLLEVBQUUsSUFBSSxFQUFhLEVBQy9CLE9BQWdCO0lBRWhCLE9BQU8sQ0FBQyxLQUFLLENBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxHQUFHLENBQUMsRUFBRSxJQUFJLENBQUMsRUFBRSxLQUFLLEVBQUUsSUFBSSxFQUFFLENBQUMsQ0FBQTtJQUVyRCxLQUFLLE9BQU8sQ0FBQyxLQUFLLENBQUMsS0FBSyxDQUFDLElBQUksQ0FBQyxHQUFHLEVBQUUsS0FBSyxFQUFFLElBQUksQ0FBQyxDQUFDLElBQUksQ0FBQyxDQUFDLEtBQUssRUFBRSxFQUFFO1FBQzdELElBQUksS0FBSyxZQUFZLEtBQUs7WUFDeEIsT0FBTyxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMseUJBQXlCLEVBQUUsRUFBRSxHQUFHLEVBQUUsS0FBSyxFQUFFLEtBQUssRUFBRSxDQUFDLENBQUE7O1lBQ2pFLE9BQU8sQ0FBQyxLQUFLLENBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxHQUFHLENBQUMsRUFBRSxJQUFJLENBQUMsRUFBRSxLQUFLLEVBQUUsT0FBTyxFQUFFLElBQUksRUFBRSxLQUFLLEVBQUUsQ0FBQyxDQUFBO0lBQzVFLENBQUMsQ0FBQyxDQUFBO0FBQ0osQ0FBQyJ9

package/components/realtime.streams/source/create.ts

@@ -0,0 +1,94 @@
+import { type Readable } from 'node:stream'
+import { type Operation } from '@toa.io/bridges.node'
+import { type Context } from '../types/index.js'
+import { Stream, Stash } from './lib/index.js'
+
+export class Effect implements Operation {
+  private readonly streams = new Map<string, Stream>()
+  private stash!: Stash
+  private logs: any
+
+  public mount(context: Context): void {
+    context.state.streams = this.streams
+    context.state.stash = new Stash(context.stash, context.configuration, context.logs)
+
+    this.logs = context.logs
+    this.stash = context.state.stash
+  }
+
+  public unmount(): void {
+    this.logs.info('Destroying streams', { count: this.streams.size })
+
+    // closed, not destroyed: destroying a stream that is still piped to a response
+    // makes end-of-stream report a premature close, which reaches no one and takes
+    // the process down.
+    for (const stream of this.streams.values()) stream.close()
+  }
+
+  public async execute(input: Input): Promise<Readable> {
+    const key = input.key
+
+    if (!this.streams.has(key)) {
+      const stream = this.createStream(key)
+
+      this.streams.set(key, stream)
+      this.logs.debug('Stream created', { key })
+    }
+
+    // welcome
+    setTimeout(() => this.streams.get(key)?.heartbeat(), 1000)
+
+    if (input.token === undefined)
+      void this.stash.connect(key).then((token) => {
+        if (token instanceof Error)
+          this.logs.error('Failed to connect to stash', { key, error: token })
+        else this.streams.get(key)?.push({ event: 'token', data: token })
+      })
+    else
+      void this.stash.pop(key, input.token).then((result) => {
+        if (result === null) return
+
+        if ('code' in result && result.code === 'NO_RESULTS') return
+
+        if (result instanceof Error) {
+          this.logs.error('Failed to pop from stash', { key, error: result })
+
+          return
+        }
+
+        const stream = this.streams.get(key)
+
+        if (stream === undefined) return
+
+        const [token, events] = result
+
+        for (const event of events as Event[])
+          stream.push({ event: event.event, data: event.data })
+
+        stream.push({ event: 'token', data: token })
+      })
+
+    return this.streams.get(key)!
+  }
+
+  private createStream(key: string): Stream {
+    const stream = new Stream()
+
+    stream.events.once('destroy', () => {
+      this.logs.debug('Stream destroyed', { key })
+      this.streams.delete(key)
+    })
+
+    return stream
+  }
+}
+
+interface Input {
+  key: string
+  token?: string
+}
+
+interface Event {
+  event: string
+  data: unknown
+}

package/components/realtime.streams/source/lib/Stash.ts

@@ -0,0 +1,131 @@
+import type { Redis } from 'ioredis'
+
+export class Stash {
+  private readonly stash: Redis
+  private readonly configuration: Configuration
+  private readonly logs: any
+
+  public constructor(stash: any, configuration: Configuration, logs: any) {
+    this.stash = stash
+    this.configuration = configuration
+    this.logs = logs
+  }
+
+  public async connect(key: string): Promise<string | Error> {
+    return await this.xadd(key, 'connect')
+  }
+
+  public async push(key: string, event: string, data: unknown): Promise<string | Error> {
+    return await this.xadd(key, event, data)
+  }
+
+  public async pop(
+    key: string,
+    token: string
+  ): Promise<[string, Event[]] | null | Error> {
+    const stamp = this.decode(token)
+
+    const results = await this.stash
+      .xread('STREAMS', key, stamp)
+      .catch((error: Error) => error)
+
+    if (results === null) return ERR_NO_RESULTS
+
+    if (results instanceof Error) return results
+
+    const items = entries(results)
+
+    if (items === null) return null
+
+    const events: Event[] = []
+
+    let lastStamp: string | null = null
+
+    for (const item of items) {
+      const [, event, , json] = item[1]
+
+      lastStamp = item[0]
+
+      const data = json === undefined ? undefined : JSON.parse(json)
+
+      if (data === undefined) this.logs.debug('Undefined event payload', { key, event })
+
+      events.push({ event, data })
+    }
+
+    if (lastStamp === null) return null
+
+    return [this.encode(lastStamp), events]
+  }
+
+  private async xadd(
+    key: string,
+    event: string,
+    data?: unknown
+  ): Promise<string | Error> {
+    const args = ['MAXLEN', '~', this.configuration.maxlen, '*', 'type', event]
+
+    if (data !== undefined) args.push('data', JSON.stringify(data))
+
+    const results = await this.stash
+      .multi()
+      .xadd(key, ...args)
+      .expire(key, this.configuration.expire)
+      .exec()
+      .catch((error: Error) => error)
+
+    if (results === null) return ERR_NO_RESULTS
+
+    if (results instanceof Error) return results
+
+    const [[error, stamp]] = results
+
+    if (error !== null) return error
+
+    return this.encode(stamp as string)
+  }
+
+  private encode(token: string): string {
+    return Buffer.from(token).toString('base64url')
+  }
+
+  private decode(token: string): string {
+    return Buffer.from(token, 'base64url').toString()
+  }
+}
+
+/**
+ * `xread` answers with an array of `[stream, entries]` pairs over RESP2 and with an
+ * object keyed by stream name over RESP3. One stream is read, so either way it is the
+ * first, and an empty answer means nothing has been added since the token.
+ */
+function entries(results: unknown): Entry[] | null {
+  if (Array.isArray(results))
+    return results.length === 0 ? null : (results[0] as [string, Entry[]])[1]
+
+  if (typeof results === 'object' && results !== null) {
+    const streams = Object.values(results as Record<string, Entry[]>)
+
+    return streams.length === 0 ? null : streams[0]
+  }
+
+  return null
+}
+
+type Entry = [stamp: string, fields: string[]]
+
+interface Configuration {
+  maxlen: number
+  expire: number
+}
+
+interface Event {
+  event: string
+  data: unknown
+}
+
+class NoResultsError extends Error {
+  public readonly code = 'NO_RESULTS'
+}
+
+const ERR_NO_RESULTS = new NoResultsError()

package/components/realtime.streams/source/lib/Stream.ts

@@ -0,0 +1,58 @@
+import { EventEmitter } from 'node:events'
+import { Readable } from 'node:stream'
+
+export class Stream extends Readable {
+  public events = new EventEmitter()
+
+  private interval: NodeJS.Timeout | null = null
+  private ended = false
+
+  public constructor() {
+    super(objectMode)
+  }
+
+  // has to be here
+  public override _read(): void {
+    if (this.interval === null)
+      this.interval = setInterval(() => this.heartbeat(), HEARTBEAT_INTERVAL)
+  }
+
+  public override _destroy(
+    error: Error | null,
+    callback: (error?: Error | null) => void
+  ): void {
+    if (this.interval !== null) clearInterval(this.interval)
+
+    this.events.emit('destroy')
+
+    super._destroy(error, callback)
+  }
+
+  /** Ends the stream: whoever reads it gets EOF rather than a broken pipe. */
+  public close(): void {
+    this.ended = true
+
+    if (this.interval !== null) {
+      clearInterval(this.interval)
+      this.interval = null
+    }
+
+    this.push(null)
+  }
+
+  public heartbeat(stream: Readable = this): boolean {
+    if (this.ended) return false
+
+    const resume = stream.push('heartbeat ' + Date.now())
+
+    if (!resume && this.interval !== null) {
+      clearInterval(this.interval)
+      this.interval = null
+    }
+
+    return resume
+  }
+}
+
+const HEARTBEAT_INTERVAL = 16_000 // why?
+const objectMode = { objectMode: true }

package/components/realtime.streams/source/lib/index.ts

@@ -0,0 +1,2 @@
+export { Stash } from './Stash.js'
+export { Stream } from './Stream.js'

package/components/realtime.streams/source/push.ts

@@ -0,0 +1,14 @@
+import { type Context, type PushInput } from '../types/index.js'
+
+export async function effect(
+  { key, event, data }: PushInput,
+  context: Context
+): Promise<void> {
+  context.state.streams.get(key)?.push({ event, data })
+
+  void context.state.stash.push(key, event, data).then((token) => {
+    if (token instanceof Error)
+      context.logs.error('Failed to push to stash', { key, error: token })
+    else context.state.streams.get(key)?.push({ event: 'token', data: token })
+  })
+}

package/components/{streams → realtime.streams}/tsconfig.json

@@ -1,7 +1,8 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../../../tsconfig.component.json",
   "compilerOptions": {
     "outDir": "./operations",
+    "rootDir": "./source"
   },
   "include": [
     "source"

package/components/realtime.streams/types/index.d.ts

@@ -0,0 +1,20 @@
+export * from './toa.d.ts'
+
+// What a manifest does not state belongs here, and every run keeps it.
+
+import type { Logs } from '@toa.io/extensions.telemetry'
+import type { Stash as Redis } from '@toa.io/extensions.stash'
+import type { Configuration } from './toa.js'
+import type { Stream } from '../source/lib/Stream.js'
+import type { Stash } from '../source/lib/Stash.js'
+
+/** What this component keeps between calls: the streams it serves, and what backs them. */
+export interface Context {
+  stash: Redis
+  state: {
+    streams: Map<string, Stream>
+    stash: Stash
+  }
+  logs: Logs
+  configuration: Configuration
+}

package/components/realtime.streams/types/toa.d.ts

@@ -0,0 +1,30 @@
+// Written by `toa types`. Every run rewrites it.
+// What a manifest does not state belongs in a file of your own.
+
+import type { Options } from '@toa.io/core/types'
+import type { FetchInit } from '@toa.io/extensions.fetch'
+import type { Stash } from '@toa.io/extensions.stash'
+import type { Logs, Span } from '@toa.io/extensions.telemetry'
+
+export type CreateInput = {
+  key?: string
+  token?: string
+}
+
+export type PushInput = {
+  data?: unknown
+  key: string
+  event: string
+}
+
+export type PushOutput = null
+
+export interface Component {
+  create: (request: { input: CreateInput, task?: boolean }, options?: Options) => Promise<unknown>
+  push: (request: { input: PushInput, task?: boolean }, options?: Options) => Promise<PushOutput>
+}
+
+export interface Configuration {
+  maxlen: number
+  expire: number
+}