@mt-tl/server 0.1.0

package/dist/transport/ws-server.js

@@ -0,0 +1,78 @@
+import { WebSocketServer } from 'ws';
+import { noopLogger } from '@mt-tl/tl';
+import { Connection } from './connection.js';
+import { pump } from './server-common.js';
+function toBuffer(data) {
+    if (Buffer.isBuffer(data))
+        return data;
+    if (Array.isArray(data))
+        return Buffer.concat(data);
+    return Buffer.from(data);
+}
+/**
+ * WebSocket carrier for MTProto. Each binary frame is fed into the connection's
+ * transport framing; complete packets are handed to `onPacket` in arrival order.
+ */
+export class MtprotoWsServer {
+    options;
+    handlers;
+    wss;
+    lastId = 0;
+    constructor(options, handlers) {
+        this.options = options;
+        this.handlers = handlers;
+    }
+    listen() {
+        return new Promise(resolve => {
+            this.wss = new WebSocketServer({ port: this.options.port, clientTracking: false });
+            this.wss.on('connection', (socket, req) => this.onConnection(socket, req));
+            this.wss.on('listening', () => resolve());
+        });
+    }
+    /** Bound TCP port (useful when listening on port 0 in tests). */
+    get port() {
+        const addr = this.wss?.address();
+        return addr && typeof addr === 'object' ? addr.port : this.options.port;
+    }
+    onConnection(socket, req) {
+        const id = ++this.lastId;
+        // Only trust the (spoofable) X-Forwarded-For when an upstream proxy is declared.
+        const forwarded = this.options.trustProxy
+            ? req.headers['x-forwarded-for']?.split(',')[0]?.trim()
+            : undefined;
+        const remote = forwarded ?? req.socket.remoteAddress ?? undefined;
+        const log = (this.options.logger ?? noopLogger).child({ scope: 'ws', conn: id });
+        log.info('conn.open', { remote });
+        if (log.isLevelEnabled('trace')) {
+            log.trace('ws.connect', {
+                host: req.headers.host,
+                xff: req.headers['x-forwarded-for'],
+                proto: req.headers['sec-websocket-protocol'],
+                ua: req.headers['user-agent'],
+            });
+        }
+        const conn = new Connection(id, bytes => socket.send(bytes, { binary: true }), () => socket.close(), remote, this.options.defaultLayer, log);
+        this.handlers.onConnect?.(conn);
+        socket.on('message', (data) => {
+            const buf = toBuffer(data);
+            if (log.isLevelEnabled('trace'))
+                log.trace('ws.recv', { bytes: buf.length, head: buf.subarray(0, 16).toString('hex') });
+            pump(conn, buf, this.handlers);
+        });
+        socket.on('close', (code, reason) => {
+            log.info('conn.close', { code });
+            if (reason?.length && log.isLevelEnabled('trace'))
+                log.trace('ws.close', { reason: reason.toString() });
+            conn.closed = true;
+            this.handlers.onClose?.(conn);
+        });
+        socket.on('error', err => {
+            log.warn('ws.error', { err: String(err) });
+            conn.close();
+        });
+    }
+    close() {
+        this.wss?.close();
+    }
+}
+//# sourceMappingURL=ws-server.js.map

package/dist/transport/ws-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-server.js","sourceRoot":"","sources":["../../src/transport/ws-server.ts"],"names":[],"mappings":"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"}

package/dist/update-publisher.d.ts

@@ -0,0 +1,34 @@
+/** A standalone publisher returned by {@link createUpdatePublisher}. */
+export interface UpdatePublisher {
+    /** Push a TL update (`{ _: name, ... }`) to a `subject` (internal user id) —
+     * delivered to whatever node holds them. */
+    push(subject: string, update: unknown): Promise<void>;
+    /** Push to a specific auth key — including an anonymous connection (no pts). */
+    pushToAuthKey(authKeyId: string, update: unknown): Promise<void>;
+    /** Disconnect from the shared bus. */
+    close(): Promise<void>;
+}
+/** Options for {@link createUpdatePublisher}. */
+export interface UpdatePublisherConfig {
+    /** Redis URL of the shared pub/sub update bus (the same `REDIS_URL` your servers use). */
+    redisUrl: string;
+}
+/**
+ * Creates a server-push publisher for code running **outside** the server — a
+ * webhook receiver, a cron worker, another microservice. It drops the update on
+ * the shared Redis bus; the server fleet's router looks up presence and delivers
+ * it to whichever node holds the user (rendered for that client's layer). No
+ * client connection and no running server are needed — only the shared bus.
+ *
+ * Inside a handler, push with `ctx.push(subject, update)` instead — this is for
+ * cross-process pushes, which is why it needs the shared `redisUrl`.
+ *
+ * @example
+ * ```ts
+ * const updates = await createUpdatePublisher({ redisUrl: process.env.REDIS_URL! })
+ * await updates.push(subject, { _: 'updateNewMessage', message })
+ * await updates.close()
+ * ```
+ */
+export declare function createUpdatePublisher(config: UpdatePublisherConfig): Promise<UpdatePublisher>;
+//# sourceMappingURL=update-publisher.d.ts.map

package/dist/update-publisher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-publisher.d.ts","sourceRoot":"","sources":["../src/update-publisher.ts"],"names":[],"mappings":"AAGA,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC5B;gDAC4C;IAC5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrD,gFAAgF;IAChF,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAChE,sCAAsC;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAED,iDAAiD;AACjD,MAAM,WAAW,qBAAqB;IAClC,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC,CASnG"}

package/dist/update-publisher.js

@@ -0,0 +1,29 @@
+import { createRedisUpdateBus } from './lib.js';
+/**
+ * Creates a server-push publisher for code running **outside** the server — a
+ * webhook receiver, a cron worker, another microservice. It drops the update on
+ * the shared Redis bus; the server fleet's router looks up presence and delivers
+ * it to whichever node holds the user (rendered for that client's layer). No
+ * client connection and no running server are needed — only the shared bus.
+ *
+ * Inside a handler, push with `ctx.push(subject, update)` instead — this is for
+ * cross-process pushes, which is why it needs the shared `redisUrl`.
+ *
+ * @example
+ * ```ts
+ * const updates = await createUpdatePublisher({ redisUrl: process.env.REDIS_URL! })
+ * await updates.push(subject, { _: 'updateNewMessage', message })
+ * await updates.close()
+ * ```
+ */
+export async function createUpdatePublisher(config) {
+    if (!config.redisUrl)
+        throw new Error('createUpdatePublisher requires redisUrl');
+    const handle = await createRedisUpdateBus(config.redisUrl);
+    return {
+        push: (subject, update) => handle.bus.publishUpdate({ subject, update: update }),
+        pushToAuthKey: (authKeyId, update) => handle.bus.publishUpdate({ authKeyId, update: update }),
+        close: () => handle.close(),
+    };
+}
+//# sourceMappingURL=update-publisher.js.map

package/dist/update-publisher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-publisher.js","sourceRoot":"","sources":["../src/update-publisher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAoB/C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,MAA6B;IACrE,IAAI,CAAC,MAAM,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAA;IAChF,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IAC1D,OAAO;QACH,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,MAAmB,EAAE,CAAC;QAC7F,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,CACjC,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,MAAmB,EAAE,CAAC;QACxE,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE;KAC9B,CAAA;AACL,CAAC"}

package/dist/updates/mongo-update-log.d.ts

@@ -0,0 +1,13 @@
+import type { UpdateLog } from '../core/updates.js';
+/**
+ * Durable {@link UpdateLog} on MongoDB, for protocol-managed updates
+ * (`config.updates.managed`). `pts` is assigned atomically per subject via a
+ * counters document (`$inc`), so concurrent replicas never collide; each update
+ * is stored with its pts for `updates.getDifference`. Opens its own connection
+ * (the updates box is logically separate from auth/salt/session storage).
+ */
+export declare function createMongoUpdateLog(mongoUrl: string, dbName: string): Promise<{
+    log: UpdateLog;
+    close: () => Promise<void>;
+}>;
+//# sourceMappingURL=mongo-update-log.d.ts.map

package/dist/updates/mongo-update-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongo-update-log.d.ts","sourceRoot":"","sources":["../../src/updates/mongo-update-log.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAEnD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACtC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAmCzD"}

package/dist/updates/mongo-update-log.js

@@ -0,0 +1,39 @@
+/**
+ * Durable {@link UpdateLog} on MongoDB, for protocol-managed updates
+ * (`config.updates.managed`). `pts` is assigned atomically per subject via a
+ * counters document (`$inc`), so concurrent replicas never collide; each update
+ * is stored with its pts for `updates.getDifference`. Opens its own connection
+ * (the updates box is logically separate from auth/salt/session storage).
+ */
+export async function createMongoUpdateLog(mongoUrl, dbName) {
+    const { MongoClient } = await import('mongodb');
+    const client = new MongoClient(mongoUrl);
+    await client.connect();
+    const db = client.db(dbName);
+    const counters = db.collection('update_counters');
+    const log = db.collection('updates');
+    await log.createIndex({ subject: 1, pts: 1 });
+    return {
+        log: {
+            async append(subject, update) {
+                const doc = await counters.findOneAndUpdate({ _id: subject }, { $inc: { pts: 1 } }, { upsert: true, returnDocument: 'after' });
+                const pts = doc?.pts ?? 1;
+                await log.insertOne({ subject, pts, update });
+                return { pts };
+            },
+            async since(subject, sincePts) {
+                const docs = await log
+                    .find({ subject, pts: { $gt: sincePts } })
+                    .sort({ pts: 1 })
+                    .toArray();
+                return docs.map(d => ({ pts: d.pts, update: d.update }));
+            },
+            async currentPts(subject) {
+                const doc = await counters.findOne({ _id: subject });
+                return doc?.pts ?? 0;
+            },
+        },
+        close: () => client.close(),
+    };
+}
+//# sourceMappingURL=mongo-update-log.js.map

package/dist/updates/mongo-update-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongo-update-log.js","sourceRoot":"","sources":["../../src/updates/mongo-update-log.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACtC,QAAgB,EAChB,MAAc;IAEd,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAA;IAC/C,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC,QAAQ,CAAC,CAAA;IACxC,MAAM,MAAM,CAAC,OAAO,EAAE,CAAA;IACtB,MAAM,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAA;IAC5B,MAAM,QAAQ,GAAG,EAAE,CAAC,UAAU,CAA+B,iBAAiB,CAAC,CAAA;IAC/E,MAAM,GAAG,GAAG,EAAE,CAAC,UAAU,CAAsD,SAAS,CAAC,CAAA;IACzF,MAAM,GAAG,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;IAE7C,OAAO;QACH,GAAG,EAAE;YACD,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM;gBACxB,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,gBAAgB,CACvC,EAAE,GAAG,EAAE,OAAO,EAAE,EAChB,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EACpB,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,CAC5C,CAAA;gBACD,MAAM,GAAG,GAAG,GAAG,EAAE,GAAG,IAAI,CAAC,CAAA;gBACzB,MAAM,GAAG,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAA;gBAC7C,OAAO,EAAE,GAAG,EAAE,CAAA;YAClB,CAAC;YACD,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ;gBACzB,MAAM,IAAI,GAAG,MAAM,GAAG;qBACjB,IAAI,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,CAAC;qBACzC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;qBAChB,OAAO,EAAE,CAAA;gBACd,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;YAC5D,CAAC;YACD,KAAK,CAAC,UAAU,CAAC,OAAO;gBACpB,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAA;gBACpD,OAAO,GAAG,EAAE,GAAG,IAAI,CAAC,CAAA;YACxB,CAAC;SACJ;QACD,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE;KAC9B,CAAA;AACL,CAAC"}

package/dist/updates/presence-binder.d.ts

@@ -0,0 +1,29 @@
+import type { Connection } from '../transport/connection.js';
+import type { ConnectionRegistry } from '../transport/connection-registry.js';
+import type { Presence } from './presence.js';
+/**
+ * Couples a connection's authorized subject to the local registry and the global
+ * presence map. The pipeline binds on authenticated messages; the dispatcher
+ * binds/unbinds on bindUser/unbindUser effects; the carriers unbind on close.
+ */
+export interface PresenceBinder {
+    bind(conn: Connection, subject: string): void;
+    /** Register a connection by its auth key (enables push to anonymous connections). */
+    bindAuthKey(conn: Connection, authKeyId: string): void;
+    unbind(conn: Connection): void;
+}
+export declare class NoopPresenceBinder implements PresenceBinder {
+    bind(): void;
+    bindAuthKey(): void;
+    unbind(): void;
+}
+export declare class NodePresenceBinder implements PresenceBinder {
+    private readonly nodeId;
+    private readonly registry;
+    private readonly presence;
+    constructor(nodeId: string, registry: ConnectionRegistry, presence: Presence);
+    bind(conn: Connection, subject: string): void;
+    bindAuthKey(conn: Connection, authKeyId: string): void;
+    unbind(conn: Connection): void;
+}
+//# sourceMappingURL=presence-binder.d.ts.map

package/dist/updates/presence-binder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence-binder.d.ts","sourceRoot":"","sources":["../../src/updates/presence-binder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAA;AAC7E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE7C;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC3B,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7C,qFAAqF;IACrF,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACtD,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAA;CACjC;AAED,qBAAa,kBAAmB,YAAW,cAAc;IACrD,IAAI,IAAI,IAAI;IACZ,WAAW,IAAI,IAAI;IACnB,MAAM,IAAI,IAAI;CACjB;AAED,qBAAa,kBAAmB,YAAW,cAAc;IAEjD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAFR,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,kBAAkB,EAC5B,QAAQ,EAAE,QAAQ;IAGvC,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAM7C,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAKtD,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;CAUjC"}

package/dist/updates/presence-binder.js

@@ -0,0 +1,36 @@
+export class NoopPresenceBinder {
+    bind() { }
+    bindAuthKey() { }
+    unbind() { }
+}
+export class NodePresenceBinder {
+    nodeId;
+    registry;
+    presence;
+    constructor(nodeId, registry, presence) {
+        this.nodeId = nodeId;
+        this.registry = registry;
+        this.presence = presence;
+    }
+    bind(conn, subject) {
+        if (this.registry.subjectOf(conn) === subject)
+            return; // already bound — cheap no-op
+        this.registry.register(subject, conn);
+        void this.presence.add(subject, this.nodeId).catch(() => { });
+    }
+    bindAuthKey(conn, authKeyId) {
+        this.registry.registerAuthKey(authKeyId, conn); // no-op if already registered
+        void this.presence.addAuthKey(authKeyId, this.nodeId).catch(() => { });
+    }
+    unbind(conn) {
+        const { subject, authKeyId } = this.registry.unregister(conn);
+        // Only drop this node's presence once no local connection remains for the key.
+        if (subject !== undefined && !this.registry.hasSubject(subject)) {
+            void this.presence.remove(subject, this.nodeId).catch(() => { });
+        }
+        if (authKeyId !== undefined && !this.registry.hasAuthKey(authKeyId)) {
+            void this.presence.removeAuthKey(authKeyId, this.nodeId).catch(() => { });
+        }
+    }
+}
+//# sourceMappingURL=presence-binder.js.map

package/dist/updates/presence-binder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence-binder.js","sourceRoot":"","sources":["../../src/updates/presence-binder.ts"],"names":[],"mappings":"AAgBA,MAAM,OAAO,kBAAkB;IAC3B,IAAI,KAAU,CAAC;IACf,WAAW,KAAU,CAAC;IACtB,MAAM,KAAU,CAAC;CACpB;AAED,MAAM,OAAO,kBAAkB;IAEN;IACA;IACA;IAHrB,YACqB,MAAc,EACd,QAA4B,EAC5B,QAAkB;QAFlB,WAAM,GAAN,MAAM,CAAQ;QACd,aAAQ,GAAR,QAAQ,CAAoB;QAC5B,aAAQ,GAAR,QAAQ,CAAU;IACpC,CAAC;IAEJ,IAAI,CAAC,IAAgB,EAAE,OAAe;QAClC,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,OAAO;YAAE,OAAM,CAAC,8BAA8B;QACpF,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;QACrC,KAAK,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IAChE,CAAC;IAED,WAAW,CAAC,IAAgB,EAAE,SAAiB;QAC3C,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,SAAS,EAAE,IAAI,CAAC,CAAA,CAAC,8BAA8B;QAC7E,KAAK,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IACzE,CAAC;IAED,MAAM,CAAC,IAAgB;QACnB,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;QAC7D,+EAA+E;QAC/E,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9D,KAAK,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QACnE,CAAC;QACD,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAClE,KAAK,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QAC5E,CAAC;IACL,CAAC;CACJ"}

package/dist/updates/presence.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Global online-presence: which gateway node(s) currently hold a connection for
+ * a subject. Written by gateways, read by the Update Router to route updates only
+ * to nodes that actually hold the subject (no broadcast fan-out).
+ *
+ * Eventually-consistent is fine — a stale entry just routes to a node that drops
+ * the update, and the client recovers via pts/getDifference.
+ */
+export interface Presence {
+    add(subject: string, nodeId: string): Promise<void>;
+    remove(subject: string, nodeId: string): Promise<void>;
+    lookup(subject: string): Promise<string[]>;
+    /** Presence for a specific auth key (anonymous-capable delivery target). */
+    addAuthKey(authKeyId: string, nodeId: string): Promise<void>;
+    removeAuthKey(authKeyId: string, nodeId: string): Promise<void>;
+    lookupAuthKey(authKeyId: string): Promise<string[]>;
+}
+/** In-memory presence (single-process / tests). Use a Redis impl across nodes. */
+export declare class InMemoryPresence implements Presence {
+    private map;
+    private addKey;
+    private removeKey;
+    private lookupKey;
+    add(subject: string, nodeId: string): Promise<void>;
+    remove(subject: string, nodeId: string): Promise<void>;
+    lookup(subject: string): Promise<string[]>;
+    addAuthKey(authKeyId: string, nodeId: string): Promise<void>;
+    removeAuthKey(authKeyId: string, nodeId: string): Promise<void>;
+    lookupAuthKey(authKeyId: string): Promise<string[]>;
+}
+//# sourceMappingURL=presence.d.ts.map

package/dist/updates/presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../../src/updates/presence.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACrB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnD,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAC1C,4EAA4E;IAC5E,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5D,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/D,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;CACtD;AAED,kFAAkF;AAClF,qBAAa,gBAAiB,YAAW,QAAQ;IAE7C,OAAO,CAAC,GAAG,CAAiC;IAE5C,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,SAAS;IAKX,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAGnD,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAGtD,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAG1C,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAG5D,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAG/D,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAG5D"}

package/dist/updates/presence.js

@@ -0,0 +1,44 @@
+/** In-memory presence (single-process / tests). Use a Redis impl across nodes. */
+export class InMemoryPresence {
+    // Keyed by a prefixed target string: `u:<subject>` or `a:<authKeyId>`.
+    map = new Map();
+    addKey(key, nodeId) {
+        let set = this.map.get(key);
+        if (!set) {
+            set = new Set();
+            this.map.set(key, set);
+        }
+        set.add(nodeId);
+    }
+    removeKey(key, nodeId) {
+        const set = this.map.get(key);
+        if (!set)
+            return;
+        set.delete(nodeId);
+        if (set.size === 0)
+            this.map.delete(key);
+    }
+    lookupKey(key) {
+        const set = this.map.get(key);
+        return set ? [...set] : [];
+    }
+    async add(subject, nodeId) {
+        this.addKey(`u:${subject}`, nodeId);
+    }
+    async remove(subject, nodeId) {
+        this.removeKey(`u:${subject}`, nodeId);
+    }
+    async lookup(subject) {
+        return this.lookupKey(`u:${subject}`);
+    }
+    async addAuthKey(authKeyId, nodeId) {
+        this.addKey(`a:${authKeyId}`, nodeId);
+    }
+    async removeAuthKey(authKeyId, nodeId) {
+        this.removeKey(`a:${authKeyId}`, nodeId);
+    }
+    async lookupAuthKey(authKeyId) {
+        return this.lookupKey(`a:${authKeyId}`);
+    }
+}
+//# sourceMappingURL=presence.js.map

package/dist/updates/presence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.js","sourceRoot":"","sources":["../../src/updates/presence.ts"],"names":[],"mappings":"AAkBA,kFAAkF;AAClF,MAAM,OAAO,gBAAgB;IACzB,uEAAuE;IAC/D,GAAG,GAAG,IAAI,GAAG,EAAuB,CAAA;IAEpC,MAAM,CAAC,GAAW,EAAE,MAAc;QACtC,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC3B,IAAI,CAAC,GAAG,EAAE,CAAC;YACP,GAAG,GAAG,IAAI,GAAG,EAAE,CAAA;YACf,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;QAC1B,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IACnB,CAAC;IACO,SAAS,CAAC,GAAW,EAAE,MAAc;QACzC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC7B,IAAI,CAAC,GAAG;YAAE,OAAM;QAChB,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAClB,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC5C,CAAC;IACO,SAAS,CAAC,GAAW;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC7B,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IAC9B,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,OAAe,EAAE,MAAc;QACrC,IAAI,CAAC,MAAM,CAAC,KAAK,OAAO,EAAE,EAAE,MAAM,CAAC,CAAA;IACvC,CAAC;IACD,KAAK,CAAC,MAAM,CAAC,OAAe,EAAE,MAAc;QACxC,IAAI,CAAC,SAAS,CAAC,KAAK,OAAO,EAAE,EAAE,MAAM,CAAC,CAAA;IAC1C,CAAC;IACD,KAAK,CAAC,MAAM,CAAC,OAAe;QACxB,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,OAAO,EAAE,CAAC,CAAA;IACzC,CAAC;IACD,KAAK,CAAC,UAAU,CAAC,SAAiB,EAAE,MAAc;QAC9C,IAAI,CAAC,MAAM,CAAC,KAAK,SAAS,EAAE,EAAE,MAAM,CAAC,CAAA;IACzC,CAAC;IACD,KAAK,CAAC,aAAa,CAAC,SAAiB,EAAE,MAAc;QACjD,IAAI,CAAC,SAAS,CAAC,KAAK,SAAS,EAAE,EAAE,MAAM,CAAC,CAAA;IAC5C,CAAC;IACD,KAAK,CAAC,aAAa,CAAC,SAAiB;QACjC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,SAAS,EAAE,CAAC,CAAA;IAC3C,CAAC;CACJ"}

package/dist/updates/push.d.ts

@@ -0,0 +1,25 @@
+import { MigrationRegistry, type JsonValue, type Logger } from '@mt-tl/tl';
+import type { ConnectionRegistry } from '../transport/connection-registry.js';
+import type { Responder } from '../dispatch/types.js';
+import type { LayeredRegistry } from '../tl/layered-registry.js';
+/**
+ * Node-side delivery of a routed update to the user's local connections, as an
+ * encrypted server notification (msg_id % 4 == 3). Best-effort: if the user has
+ * no local connection, the update is dropped (the client recovers via pts).
+ *
+ * Each connection is rendered for its own negotiated layer: types not
+ * representable there become `updateUnsupported` (pts-bearing) or are dropped.
+ */
+export declare class PushService {
+    private readonly registry;
+    private readonly responder;
+    private readonly layered?;
+    private readonly migrations;
+    private readonly log;
+    constructor(registry: ConnectionRegistry, responder: Responder, layered?: LayeredRegistry | undefined, migrations?: MigrationRegistry, logger?: Logger);
+    deliver(subject: string, update: JsonValue): void;
+    /** Deliver to the connections of a specific auth key (anonymous-capable target). */
+    deliverToAuthKey(authKeyId: string, update: JsonValue): void;
+    private deliverTo;
+}
+//# sourceMappingURL=push.d.ts.map

package/dist/updates/push.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push.d.ts","sourceRoot":"","sources":["../../src/updates/push.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,iBAAiB,EAEjB,KAAK,SAAS,EACd,KAAK,MAAM,EAEd,MAAM,WAAW,CAAA;AAElB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAA;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAGhE;;;;;;;GAOG;AACH,qBAAa,WAAW;IAKhB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAN7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;IAC9C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;gBAGP,QAAQ,EAAE,kBAAkB,EAC5B,SAAS,EAAE,SAAS,EACpB,OAAO,CAAC,EAAE,eAAe,YAAA,EAC1C,UAAU,CAAC,EAAE,iBAAiB,EAC9B,MAAM,CAAC,EAAE,MAAM;IAMnB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI;IAIjD,oFAAoF;IACpF,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI;IAI5D,OAAO,CAAC,SAAS;CA2CpB"}

package/dist/updates/push.js

@@ -0,0 +1,72 @@
+import { fromJson, MigrationRegistry, noopLogger, } from '@mt-tl/tl';
+import { renderUpdateForLayer } from './render.js';
+/**
+ * Node-side delivery of a routed update to the user's local connections, as an
+ * encrypted server notification (msg_id % 4 == 3). Best-effort: if the user has
+ * no local connection, the update is dropped (the client recovers via pts).
+ *
+ * Each connection is rendered for its own negotiated layer: types not
+ * representable there become `updateUnsupported` (pts-bearing) or are dropped.
+ */
+export class PushService {
+    registry;
+    responder;
+    layered;
+    migrations;
+    log;
+    constructor(registry, responder, layered, migrations, logger) {
+        this.registry = registry;
+        this.responder = responder;
+        this.layered = layered;
+        this.migrations = migrations ?? new MigrationRegistry();
+        this.log = logger ?? noopLogger;
+    }
+    deliver(subject, update) {
+        this.deliverTo(this.registry.getBySubject(subject), update, { subject });
+    }
+    /** Deliver to the connections of a specific auth key (anonymous-capable target). */
+    deliverToAuthKey(authKeyId, update) {
+        this.deliverTo(this.registry.getByAuthKey(authKeyId), update, { authKeyId });
+    }
+    deliverTo(conns, update, target) {
+        const tl = fromJson(update);
+        if (!tl || typeof tl !== 'object' || Array.isArray(tl) || !('_' in tl))
+            return;
+        const base = tl;
+        const type = base._;
+        // Full update payload at debug — "what we're pushing out" (the canonical
+        // form, before per-connection layer rendering).
+        this.log.debug('update.data', { ...target, type, update });
+        // No local connection for the target — best-effort drop (the client recovers
+        // via pts on its next getDifference). Expected, so debug not error.
+        if (conns.length === 0) {
+            this.log.debug('update.nodest', { ...target, type });
+            return;
+        }
+        let delivered = 0;
+        for (const conn of conns) {
+            // The client opted out of updates on this connection (invokeWithoutUpdates).
+            if (conn.ctx.noUpdates)
+                continue;
+            // Render canonical → client layer (non-additive), then per-layer representability.
+            let body = this.migrations.down(base, conn.ctx.apiLayer);
+            if (this.layered?.hasLayers()) {
+                body = renderUpdateForLayer(body, conn.ctx.apiLayer, this.layered);
+            }
+            if (!body) {
+                this.log.debug('update.skip', { ...target, type, conn: conn.id, layer: conn.ctx.apiLayer });
+                continue;
+            }
+            try {
+                this.responder.sendEncrypted(conn, body, { isNotification: true, contentRelated: false });
+                delivered++;
+            }
+            catch (err) {
+                this.log.error('update.fail', { ...target, type, conn: conn.id, err });
+            }
+        }
+        if (delivered)
+            this.log.info('update.push', { ...target, type, conns: delivered });
+    }
+}
+//# sourceMappingURL=push.js.map

package/dist/updates/push.js.map

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

package/dist/updates/redis-bus.d.ts

@@ -0,0 +1,45 @@
+import type { NodeDelivery, UpdateMessage } from './types.js';
+import type { UpdateBus } from './update-bus.js';
+/**
+ * Minimal Redis surfaces (for testability). Pub/sub needs TWO connections: a
+ * connection in subscriber mode cannot issue regular commands, so publishing and
+ * subscribing use separate clients.
+ */
+export interface RedisPubLike {
+    publish(channel: string, message: string): Promise<unknown> | unknown;
+    quit(): Promise<unknown>;
+}
+export interface RedisSubLike {
+    subscribe(channel: string): Promise<unknown> | unknown;
+    on(event: 'message', listener: (channel: string, message: string) => void): unknown;
+    quit(): Promise<unknown>;
+}
+/**
+ * Redis pub/sub {@link UpdateBus} for multi-instance server-push (infra stays
+ * Mongo + Redis). `updates.in` carries emitted updates to the router;
+ * `updates.node.{id}` carries routed deliveries to a node.
+ *
+ * Caveat: Redis pub/sub is **fan-out**, not a work queue. Per-node channels are
+ * fine (one subscriber per nodeId). But `updates.in` is delivered to *every*
+ * subscriber — run a SINGLE router with this bus (enough for the in-process-first
+ * model), or shard `updates.in` by subject across routers. For competing-consumer
+ * semantics at very large scale, switch the bus to Redis Streams.
+ */
+export declare class RedisUpdateBus implements UpdateBus {
+    private readonly pub;
+    private readonly sub;
+    private readonly handlers;
+    constructor(pub: RedisPubLike, sub: RedisSubLike);
+    publishUpdate(msg: UpdateMessage): Promise<void>;
+    subscribeUpdates(handler: (msg: UpdateMessage) => void): void;
+    publishToNode(nodeId: string, msg: NodeDelivery): Promise<void>;
+    subscribeNode(nodeId: string, handler: (msg: NodeDelivery) => void): void;
+    close(): Promise<void>;
+}
+export interface RedisBusHandle {
+    bus: RedisUpdateBus;
+    close: () => Promise<void>;
+}
+/** Connects two Redis clients (publish + subscribe) and builds a {@link RedisUpdateBus}. */
+export declare function createRedisUpdateBus(url: string): Promise<RedisBusHandle>;
+//# sourceMappingURL=redis-bus.d.ts.map

package/dist/updates/redis-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-bus.d.ts","sourceRoot":"","sources":["../../src/updates/redis-bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IACzB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;IACrE,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;CAC3B;AACD,MAAM,WAAW,YAAY;IACzB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;IACtD,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAA;IACnF,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;CAC3B;AAKD;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,YAAW,SAAS;IAIxC,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAJxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4C;gBAGhD,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,YAAY;IAahC,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAItD,gBAAgB,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI;IAKvD,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrE,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI;IAKnE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B;AAED,MAAM,WAAW,cAAc;IAC3B,GAAG,EAAE,cAAc,CAAA;IACnB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7B;AAED,4FAA4F;AAC5F,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAM/E"}

package/dist/updates/redis-bus.js

@@ -0,0 +1,59 @@
+const CH_IN = 'updates.in';
+const nodeChannel = (nodeId) => `updates.node.${nodeId}`;
+/**
+ * Redis pub/sub {@link UpdateBus} for multi-instance server-push (infra stays
+ * Mongo + Redis). `updates.in` carries emitted updates to the router;
+ * `updates.node.{id}` carries routed deliveries to a node.
+ *
+ * Caveat: Redis pub/sub is **fan-out**, not a work queue. Per-node channels are
+ * fine (one subscriber per nodeId). But `updates.in` is delivered to *every*
+ * subscriber — run a SINGLE router with this bus (enough for the in-process-first
+ * model), or shard `updates.in` by subject across routers. For competing-consumer
+ * semantics at very large scale, switch the bus to Redis Streams.
+ */
+export class RedisUpdateBus {
+    pub;
+    sub;
+    handlers = new Map();
+    constructor(pub, sub) {
+        this.pub = pub;
+        this.sub = sub;
+        this.sub.on('message', (channel, message) => {
+            const handler = this.handlers.get(channel);
+            if (!handler)
+                return;
+            try {
+                handler(JSON.parse(message));
+            }
+            catch {
+                /* drop malformed */
+            }
+        });
+    }
+    async publishUpdate(msg) {
+        await this.pub.publish(CH_IN, JSON.stringify(msg));
+    }
+    subscribeUpdates(handler) {
+        this.handlers.set(CH_IN, handler);
+        void this.sub.subscribe(CH_IN);
+    }
+    async publishToNode(nodeId, msg) {
+        await this.pub.publish(nodeChannel(nodeId), JSON.stringify(msg));
+    }
+    subscribeNode(nodeId, handler) {
+        this.handlers.set(nodeChannel(nodeId), handler);
+        void this.sub.subscribe(nodeChannel(nodeId));
+    }
+    async close() {
+        await Promise.all([this.pub.quit().catch(() => { }), this.sub.quit().catch(() => { })]);
+    }
+}
+/** Connects two Redis clients (publish + subscribe) and builds a {@link RedisUpdateBus}. */
+export async function createRedisUpdateBus(url) {
+    const IoRedis = (await import('ioredis')).default;
+    const pub = new IoRedis(url, { lazyConnect: false });
+    const sub = new IoRedis(url, { lazyConnect: false });
+    const bus = new RedisUpdateBus(pub, sub);
+    return { bus, close: () => bus.close() };
+}
+//# sourceMappingURL=redis-bus.js.map

package/dist/updates/redis-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-bus.js","sourceRoot":"","sources":["../../src/updates/redis-bus.ts"],"names":[],"mappings":"AAkBA,MAAM,KAAK,GAAG,YAAY,CAAA;AAC1B,MAAM,WAAW,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,gBAAgB,MAAM,EAAE,CAAA;AAEhE;;;;;;;;;;GAUG;AACH,MAAM,OAAO,cAAc;IAIF;IACA;IAJJ,QAAQ,GAAG,IAAI,GAAG,EAAkC,CAAA;IAErE,YACqB,GAAiB,EACjB,GAAiB;QADjB,QAAG,GAAH,GAAG,CAAc;QACjB,QAAG,GAAH,GAAG,CAAc;QAElC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE;YACxC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;YAC1C,IAAI,CAAC,OAAO;gBAAE,OAAM;YACpB,IAAI,CAAC;gBACD,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAA;YAChC,CAAC;YAAC,MAAM,CAAC;gBACL,oBAAoB;YACxB,CAAC;QACL,CAAC,CAAC,CAAA;IACN,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,GAAkB;QAClC,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAA;IACtD,CAAC;IAED,gBAAgB,CAAC,OAAqC;QAClD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,OAAiC,CAAC,CAAA;QAC3D,KAAK,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;IAClC,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,MAAc,EAAE,GAAiB;QACjD,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAA;IACpE,CAAC;IAED,aAAa,CAAC,MAAc,EAAE,OAAoC;QAC9D,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,OAAiC,CAAC,CAAA;QACzE,KAAK,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAA;IAChD,CAAC;IAED,KAAK,CAAC,KAAK;QACP,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,CAAA;IACzF,CAAC;CACJ;AAOD,4FAA4F;AAC5F,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,GAAW;IAClD,MAAM,OAAO,GAAG,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAA;IACjD,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAA;IACpD,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAA;IACpD,MAAM,GAAG,GAAG,IAAI,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IACxC,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAA;AAC5C,CAAC"}