@kronos-ts/rabbitmq 0.2.1 → 0.3.0

package/dist/amqp-query-updates-transport.d.ts

@@ -0,0 +1,75 @@
+import type { AmqpConnection } from "./connection.js";
+import type { RabbitMqResolvedConfig } from "./rabbitmq.js";
+/**
+ * Wire envelope for subscription-query update broadcasts.
+ *
+ * `kind: "update"` carries a payload to deliver to all matching local subscribers.
+ * `kind: "complete"` / `"completeExceptionally"` signal end-of-stream for all
+ * subscribers of the given query name on every process.
+ *
+ * `senderId` identifies the publishing instance so a process can drop its own
+ * loopback messages (the local query bus has already fanned out locally).
+ */
+export interface RabbitMqQueryUpdateEnvelope {
+    readonly kind: "update" | "complete" | "completeExceptionally";
+    readonly senderId: string;
+    readonly queryName: string;
+    readonly update?: unknown;
+    readonly error?: {
+        readonly name?: string;
+        readonly message: string;
+        readonly stack?: string;
+    };
+    /**
+     * Serialized form of a structured `payloadEquals` filter. When present,
+     * receivers apply it against each local subscriber's stored query payload
+     * before delivering. Function filters do not serialize and therefore arrive
+     * without this field, causing the receiver to deliver to all local
+     * subscribers of {@link queryName}.
+     */
+    readonly payloadEquals?: Record<string, unknown>;
+}
+export interface RabbitMqQueryUpdatesTransport {
+    /** Publish an update / complete envelope to every subscribed instance. */
+    publish(envelope: RabbitMqQueryUpdateEnvelope): Promise<void>;
+    /** Bind this instance's queue to the routing key for the query name. Idempotent. */
+    bindQueryName(queryName: string): Promise<void>;
+    /** Unbind this instance's queue from the routing key. Idempotent. */
+    unbindQueryName(queryName: string): Promise<void>;
+    /** Set the in-process handler invoked when an inbound update arrives. */
+    setHandler(handler: (envelope: RabbitMqQueryUpdateEnvelope) => void): void;
+    /** Stable identifier for this publisher; appears as `senderId` on outbound envelopes. */
+    readonly senderId: string;
+}
+/**
+ * AMQP broadcast transport for subscription-query updates.
+ *
+ * Topology: a topic exchange (`<prefix>.query-updates`) and one exclusive
+ * auto-delete queue per instance (`<prefix>.query-updates.<service>.<instance>`).
+ * The bus dynamically binds the queue to a routing key per active query name.
+ *
+ * Consume mode is no-ack: updates are best-effort. Losing one update means a
+ * subscriber will see a stale view until the next emit — same recovery model
+ * as Axon Server when a broker round-trip is dropped.
+ */
+export declare class AmqpRabbitMqQueryUpdatesTransport implements RabbitMqQueryUpdatesTransport {
+    private readonly config;
+    private readonly connection;
+    private channel;
+    private connectPromise;
+    private closed;
+    private handler;
+    private readonly boundKeys;
+    readonly senderId: string;
+    constructor(config: RabbitMqResolvedConfig, connection: AmqpConnection);
+    connect(): Promise<void>;
+    private doConnect;
+    close(): Promise<void>;
+    publish(envelope: RabbitMqQueryUpdateEnvelope): Promise<void>;
+    bindQueryName(queryName: string): Promise<void>;
+    unbindQueryName(queryName: string): Promise<void>;
+    setHandler(handler: (envelope: RabbitMqQueryUpdateEnvelope) => void): void;
+    private handleInbound;
+    private requireChannel;
+}
+//# sourceMappingURL=amqp-query-updates-transport.d.ts.map

package/dist/amqp-query-updates-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amqp-query-updates-transport.d.ts","sourceRoot":"","sources":["../src/amqp-query-updates-transport.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACrD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAE3D;;;;;;;;;GASG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,uBAAuB,CAAA;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;QACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KACxB,CAAA;IACD;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjD;AAED,MAAM,WAAW,6BAA6B;IAC5C,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7D,oFAAoF;IACpF,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/C,qEAAqE;IACrE,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjD,yEAAyE;IACzE,UAAU,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,2BAA2B,KAAK,IAAI,GAAG,IAAI,CAAA;IAC1E,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,iCAAkC,YAAW,6BAA6B;IAUnF,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAV7B,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,cAAc,CAA2B;IACjD,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,OAAO,CAA+D;IAC9E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAE9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;gBAGN,MAAM,EAAE,sBAAsB,EAC9B,UAAU,EAAE,cAAc;IAKvC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAMhB,SAAS;IA6BjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,OAAO,CAAC,QAAQ,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC;IAa7D,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc/C,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcvD,UAAU,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,2BAA2B,KAAK,IAAI,GAAG,IAAI;IAI1E,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,cAAc;CAIvB"}

package/dist/amqp-query-updates-transport.js

@@ -0,0 +1,105 @@
+/**
+ * AMQP broadcast transport for subscription-query updates.
+ *
+ * Topology: a topic exchange (`<prefix>.query-updates`) and one exclusive
+ * auto-delete queue per instance (`<prefix>.query-updates.<service>.<instance>`).
+ * The bus dynamically binds the queue to a routing key per active query name.
+ *
+ * Consume mode is no-ack: updates are best-effort. Losing one update means a
+ * subscriber will see a stale view until the next emit — same recovery model
+ * as Axon Server when a broker round-trip is dropped.
+ */
+export class AmqpRabbitMqQueryUpdatesTransport {
+    config;
+    connection;
+    channel;
+    connectPromise;
+    closed = false;
+    handler;
+    boundKeys = new Set();
+    senderId;
+    constructor(config, connection) {
+        this.config = config;
+        this.connection = connection;
+        this.senderId = `${config.identity.serviceName}.${config.identity.instanceId}`;
+    }
+    async connect() {
+        if (this.connectPromise)
+            return this.connectPromise;
+        this.connectPromise = this.doConnect();
+        return this.connectPromise;
+    }
+    async doConnect() {
+        this.channel = await this.connection.channel();
+        await this.channel.assertExchange(this.config.topology.queryUpdatesExchange, "topic", {
+            durable: true,
+        });
+        await this.channel.assertQueue(this.config.topology.queryUpdatesQueue(), {
+            durable: false,
+            exclusive: true,
+            autoDelete: true,
+        });
+        await this.channel.consume(this.config.topology.queryUpdatesQueue(), (msg) => this.handleInbound(msg), { noAck: true });
+        // Rebind any routing keys requested before connect resolved.
+        for (const key of this.boundKeys) {
+            await this.channel.bindQueue(this.config.topology.queryUpdatesQueue(), this.config.topology.queryUpdatesExchange, key);
+        }
+    }
+    async close() {
+        this.closed = true;
+        await this.channel?.close().catch(() => { });
+    }
+    async publish(envelope) {
+        await this.connect();
+        if (this.closed)
+            return;
+        const channel = this.requireChannel();
+        const routingKey = this.config.topology.queryUpdatesRoutingKey(envelope.queryName);
+        channel.publish(this.config.topology.queryUpdatesExchange, routingKey, Buffer.from(JSON.stringify(envelope)), { contentType: "application/json", persistent: false });
+    }
+    async bindQueryName(queryName) {
+        const routingKey = this.config.topology.queryUpdatesRoutingKey(queryName);
+        if (this.boundKeys.has(routingKey))
+            return;
+        this.boundKeys.add(routingKey);
+        await this.connect();
+        if (this.closed)
+            return;
+        const channel = this.requireChannel();
+        await channel.bindQueue(this.config.topology.queryUpdatesQueue(), this.config.topology.queryUpdatesExchange, routingKey);
+    }
+    async unbindQueryName(queryName) {
+        const routingKey = this.config.topology.queryUpdatesRoutingKey(queryName);
+        if (!this.boundKeys.has(routingKey))
+            return;
+        this.boundKeys.delete(routingKey);
+        if (this.closed)
+            return;
+        const channel = this.channel;
+        if (!channel)
+            return;
+        await channel.unbindQueue(this.config.topology.queryUpdatesQueue(), this.config.topology.queryUpdatesExchange, routingKey);
+    }
+    setHandler(handler) {
+        this.handler = handler;
+    }
+    handleInbound(msg) {
+        if (!msg)
+            return;
+        if (!this.handler)
+            return;
+        try {
+            const envelope = JSON.parse(msg.content.toString("utf8"));
+            this.handler(envelope);
+        }
+        catch {
+            // Malformed envelopes are dropped — broadcast is best-effort.
+        }
+    }
+    requireChannel() {
+        if (!this.channel)
+            throw new Error("RabbitMQ query-updates transport is not connected");
+        return this.channel;
+    }
+}
+//# sourceMappingURL=amqp-query-updates-transport.js.map

package/dist/amqp-query-updates-transport.js.map

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

package/dist/distributed-subscriber-registry.d.ts

@@ -0,0 +1,132 @@
+import type { AmqpConnection } from "./connection.js";
+import type { RabbitMqResolvedConfig } from "./rabbitmq.js";
+/**
+ * A subscription known to the cluster — either owned locally on this instance
+ * or owned by another instance and learned over gossip.
+ */
+export interface SubscriberRecord {
+    readonly subId: string;
+    readonly queryName: string;
+    readonly payload: unknown;
+    readonly ownerInstanceId: string;
+}
+export interface SerializedError {
+    readonly name?: string;
+    readonly message: string;
+    readonly stack?: string;
+}
+/**
+ * Targeted message delivered to the owner of a specific subscription. The
+ * owner applies it locally against the buffered subscriber stream.
+ */
+export type DeliverEnvelope = {
+    readonly kind: "update";
+    readonly subId: string;
+    readonly update: unknown;
+} | {
+    readonly kind: "complete";
+    readonly subId: string;
+} | {
+    readonly kind: "completeExceptionally";
+    readonly subId: string;
+    readonly error: SerializedError;
+};
+/**
+ * Gossip envelopes broadcast to every instance over the fanout exchange.
+ *
+ * `claim`/`release` keep the cluster-wide subscriber mirror in sync. `sync`
+ * announces a fresh instance and prompts peers to re-emit their owned claims
+ * so the joiner can bootstrap its mirror.
+ *
+ * Every envelope carries the publisher's `ownerInstanceId` so receivers can
+ * drop their own loopback (the local mirror was already updated synchronously
+ * on the publish path).
+ */
+export type GossipEnvelope = {
+    readonly kind: "claim";
+    readonly ownerInstanceId: string;
+    readonly subId: string;
+    readonly queryName: string;
+    readonly payload: unknown;
+} | {
+    readonly kind: "release";
+    readonly ownerInstanceId: string;
+    readonly subId: string;
+} | {
+    readonly kind: "syncRequest";
+    readonly requesterId: string;
+};
+export interface DistributedSubscriberRegistry {
+    /** Stable identifier for this process. */
+    readonly instanceId: string;
+    /** Add (or overwrite) a locally-owned subscriber and broadcast the claim. */
+    claim(record: Omit<SubscriberRecord, "ownerInstanceId">): Promise<void>;
+    /** Remove a locally-owned subscriber and broadcast the release. */
+    release(subId: string): Promise<void>;
+    /** Iterate every record in the cluster-wide mirror (locally owned + remote). */
+    records(): IterableIterator<SubscriberRecord>;
+    /**
+     * Route a delivery to the owner of `subId`. Local owners are dispatched
+     * synchronously to the in-process handler; remote owners receive a direct-
+     * queue publish keyed by their instanceId.
+     */
+    deliver(envelope: DeliverEnvelope): Promise<void>;
+    /** Set the handler invoked when a `DeliverEnvelope` for a local sub arrives. */
+    setDeliverHandler(handler: (envelope: DeliverEnvelope) => void): void;
+    connect(): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * AMQP-backed implementation.
+ *
+ * Topology:
+ *
+ *   - `<prefix>.subscribers.gossip` — fanout exchange. Every instance owns an
+ *     exclusive auto-delete queue bound to it. Carries claim / release /
+ *     syncRequest messages.
+ *
+ *   - `<prefix>.subscribers.direct` — direct exchange. Every instance owns an
+ *     exclusive auto-delete queue bound by routing key equal to its
+ *     `instanceId`. Carries DeliverEnvelope messages targeted at the owner.
+ *
+ * Consume mode is no-ack on both queues — the registry is a best-effort eventual
+ * mirror. A dropped claim is healed by the next sync request; a dropped deliver
+ * looks like a missed update, the same failure mode the broker-routed model has
+ * when a stream segment is lost.
+ *
+ * Loopback dedup: the publisher applies its own claim/release to the local
+ * mirror synchronously before publishing, and ignores its own envelopes on the
+ * inbound side via `ownerInstanceId === instanceId`.
+ *
+ * Joiner protocol: on connect the new instance publishes a `syncRequest`.
+ * Existing peers respond by re-broadcasting each of their owned claims over
+ * the same fanout exchange. New instance fills its mirror as they arrive; in
+ * the meantime emits routed to subs the joiner has yet to learn about are
+ * dropped on the joiner side — by design, since the joiner can't have any of
+ * its own subscribers yet either. The window self-closes as the mirror fills.
+ */
+export declare class AmqpDistributedSubscriberRegistry implements DistributedSubscriberRegistry {
+    private readonly config;
+    private readonly connection;
+    private channel;
+    private connectPromise;
+    private closed;
+    private deliverHandler;
+    private readonly mirror;
+    private readonly locallyOwnedSubIds;
+    readonly instanceId: string;
+    constructor(config: RabbitMqResolvedConfig, connection: AmqpConnection);
+    connect(): Promise<void>;
+    private doConnect;
+    close(): Promise<void>;
+    claim(record: Omit<SubscriberRecord, "ownerInstanceId">): Promise<void>;
+    release(subId: string): Promise<void>;
+    records(): IterableIterator<SubscriberRecord>;
+    deliver(envelope: DeliverEnvelope): Promise<void>;
+    setDeliverHandler(handler: (envelope: DeliverEnvelope) => void): void;
+    private publishGossip;
+    private handleGossip;
+    private handleDirect;
+    private requireChannel;
+}
+//# sourceMappingURL=distributed-subscriber-registry.d.ts.map

package/dist/distributed-subscriber-registry.d.ts.map

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

package/dist/distributed-subscriber-registry.js

@@ -0,0 +1,192 @@
+/**
+ * AMQP-backed implementation.
+ *
+ * Topology:
+ *
+ *   - `<prefix>.subscribers.gossip` — fanout exchange. Every instance owns an
+ *     exclusive auto-delete queue bound to it. Carries claim / release /
+ *     syncRequest messages.
+ *
+ *   - `<prefix>.subscribers.direct` — direct exchange. Every instance owns an
+ *     exclusive auto-delete queue bound by routing key equal to its
+ *     `instanceId`. Carries DeliverEnvelope messages targeted at the owner.
+ *
+ * Consume mode is no-ack on both queues — the registry is a best-effort eventual
+ * mirror. A dropped claim is healed by the next sync request; a dropped deliver
+ * looks like a missed update, the same failure mode the broker-routed model has
+ * when a stream segment is lost.
+ *
+ * Loopback dedup: the publisher applies its own claim/release to the local
+ * mirror synchronously before publishing, and ignores its own envelopes on the
+ * inbound side via `ownerInstanceId === instanceId`.
+ *
+ * Joiner protocol: on connect the new instance publishes a `syncRequest`.
+ * Existing peers respond by re-broadcasting each of their owned claims over
+ * the same fanout exchange. New instance fills its mirror as they arrive; in
+ * the meantime emits routed to subs the joiner has yet to learn about are
+ * dropped on the joiner side — by design, since the joiner can't have any of
+ * its own subscribers yet either. The window self-closes as the mirror fills.
+ */
+export class AmqpDistributedSubscriberRegistry {
+    config;
+    connection;
+    channel;
+    connectPromise;
+    closed = false;
+    deliverHandler;
+    mirror = new Map();
+    locallyOwnedSubIds = new Set();
+    instanceId;
+    constructor(config, connection) {
+        this.config = config;
+        this.connection = connection;
+        this.instanceId = `${config.identity.serviceName}.${config.identity.instanceId}`;
+    }
+    async connect() {
+        if (this.connectPromise)
+            return this.connectPromise;
+        this.connectPromise = this.doConnect();
+        return this.connectPromise;
+    }
+    async doConnect() {
+        this.channel = await this.connection.channel();
+        const ch = this.channel;
+        await ch.assertExchange(this.config.topology.subscribersGossipExchange, "fanout", {
+            durable: true,
+        });
+        await ch.assertExchange(this.config.topology.subscribersDirectExchange, "direct", {
+            durable: true,
+        });
+        const gossipQueue = this.config.topology.subscribersGossipQueue();
+        const directQueue = this.config.topology.subscribersDirectQueue();
+        await ch.assertQueue(gossipQueue, { durable: false, exclusive: true, autoDelete: true });
+        await ch.assertQueue(directQueue, { durable: false, exclusive: true, autoDelete: true });
+        await ch.bindQueue(gossipQueue, this.config.topology.subscribersGossipExchange, "");
+        await ch.bindQueue(directQueue, this.config.topology.subscribersDirectExchange, this.instanceId);
+        await ch.consume(gossipQueue, (msg) => this.handleGossip(msg), { noAck: true });
+        await ch.consume(directQueue, (msg) => this.handleDirect(msg), { noAck: true });
+        // Announce ourselves so existing peers re-broadcast their owned claims.
+        this.publishGossip({ kind: "syncRequest", requesterId: this.instanceId });
+    }
+    async close() {
+        this.closed = true;
+        await this.channel?.close().catch(() => { });
+    }
+    async claim(record) {
+        const full = { ...record, ownerInstanceId: this.instanceId };
+        this.mirror.set(full.subId, full);
+        this.locallyOwnedSubIds.add(full.subId);
+        await this.connect();
+        if (this.closed)
+            return;
+        this.publishGossip({
+            kind: "claim",
+            ownerInstanceId: this.instanceId,
+            subId: full.subId,
+            queryName: full.queryName,
+            payload: full.payload,
+        });
+    }
+    async release(subId) {
+        this.mirror.delete(subId);
+        this.locallyOwnedSubIds.delete(subId);
+        await this.connect();
+        if (this.closed)
+            return;
+        this.publishGossip({ kind: "release", ownerInstanceId: this.instanceId, subId });
+    }
+    *records() {
+        for (const record of this.mirror.values())
+            yield record;
+    }
+    async deliver(envelope) {
+        const record = this.mirror.get(envelope.subId);
+        if (!record)
+            return;
+        if (record.ownerInstanceId === this.instanceId) {
+            this.deliverHandler?.(envelope);
+            return;
+        }
+        await this.connect();
+        if (this.closed)
+            return;
+        const ch = this.requireChannel();
+        ch.publish(this.config.topology.subscribersDirectExchange, record.ownerInstanceId, Buffer.from(JSON.stringify(envelope)), { contentType: "application/json", persistent: false });
+    }
+    setDeliverHandler(handler) {
+        this.deliverHandler = handler;
+    }
+    publishGossip(envelope) {
+        if (this.closed)
+            return;
+        const ch = this.channel;
+        if (!ch)
+            return;
+        ch.publish(this.config.topology.subscribersGossipExchange, "", Buffer.from(JSON.stringify(envelope)), { contentType: "application/json", persistent: false });
+    }
+    handleGossip(msg) {
+        if (!msg)
+            return;
+        let envelope;
+        try {
+            envelope = JSON.parse(msg.content.toString("utf8"));
+        }
+        catch {
+            return;
+        }
+        if (envelope.kind === "claim") {
+            // Loopback — local mirror already updated synchronously by claim().
+            if (envelope.ownerInstanceId === this.instanceId)
+                return;
+            this.mirror.set(envelope.subId, {
+                subId: envelope.subId,
+                queryName: envelope.queryName,
+                payload: envelope.payload,
+                ownerInstanceId: envelope.ownerInstanceId,
+            });
+        }
+        else if (envelope.kind === "release") {
+            if (envelope.ownerInstanceId === this.instanceId)
+                return;
+            this.mirror.delete(envelope.subId);
+        }
+        else if (envelope.kind === "syncRequest") {
+            // Skip our own announcement; respond to every other instance by
+            // re-broadcasting our owned claims over the same fanout exchange.
+            if (envelope.requesterId === this.instanceId)
+                return;
+            for (const subId of this.locallyOwnedSubIds) {
+                const record = this.mirror.get(subId);
+                if (!record)
+                    continue;
+                this.publishGossip({
+                    kind: "claim",
+                    ownerInstanceId: this.instanceId,
+                    subId: record.subId,
+                    queryName: record.queryName,
+                    payload: record.payload,
+                });
+            }
+        }
+    }
+    handleDirect(msg) {
+        if (!msg)
+            return;
+        if (!this.deliverHandler)
+            return;
+        let envelope;
+        try {
+            envelope = JSON.parse(msg.content.toString("utf8"));
+        }
+        catch {
+            return;
+        }
+        this.deliverHandler(envelope);
+    }
+    requireChannel() {
+        if (!this.channel)
+            throw new Error("Distributed subscriber registry is not connected");
+        return this.channel;
+    }
+}
+//# sourceMappingURL=distributed-subscriber-registry.js.map

package/dist/distributed-subscriber-registry.js.map

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

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { rabbitMq, resolveRabbitMqConfig, type RabbitMqExtensionConfig, type Rab
 export { createRabbitMqTopologyNames, type RabbitMqTopologyConfig, type RabbitMqTopologyNames, } from "./topology.js";
 export { createRabbitMqCommandBus, type RabbitMqCommandEnvelope, type RabbitMqCommandReplyEnvelope, type RabbitMqCommandTransport, type RabbitMqCommandBusOptions, } from "./command-bus.js";
 export { createRabbitMqQueryBus, type RabbitMqQueryEnvelope, type RabbitMqQueryReplyEnvelope, type RabbitMqQueryTransport, type RabbitMqQueryBusOptions, } from "./query-bus.js";
+export { AmqpDistributedSubscriberRegistry, type DistributedSubscriberRegistry, type SubscriberRecord, type DeliverEnvelope, type GossipEnvelope, } from "./distributed-subscriber-registry.js";
 export { AmqpRabbitMqCommandTransport } from "./amqp-command-transport.js";
 export { AmqpRabbitMqQueryTransport } from "./amqp-query-transport.js";
 export { createAmqpConnection, type AmqpConnection, type AmqpConnect, } from "./connection.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,qBAAqB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,2BAA2B,EAChC,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,GAC5B,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,2BAA2B,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,wBAAwB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,4BAA4B,EACjC,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EACL,sBAAsB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,GAC7B,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAA;AAC1E,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAA;AAEtE,OAAO,EACL,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,WAAW,GACjB,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,qBAAqB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,2BAA2B,EAChC,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,GAC5B,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,2BAA2B,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,wBAAwB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,4BAA4B,EACjC,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EACL,sBAAsB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,GAC7B,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACL,iCAAiC,EACjC,KAAK,6BAA6B,EAClC,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,sCAAsC,CAAA;AAE7C,OAAO,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAA;AAC1E,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAA;AAEtE,OAAO,EACL,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,WAAW,GACjB,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -2,6 +2,7 @@ export { rabbitMq, resolveRabbitMqConfig, } from "./rabbitmq.js";
 export { createRabbitMqTopologyNames, } from "./topology.js";
 export { createRabbitMqCommandBus, } from "./command-bus.js";
 export { createRabbitMqQueryBus, } from "./query-bus.js";
+export { AmqpDistributedSubscriberRegistry, } from "./distributed-subscriber-registry.js";
 export { AmqpRabbitMqCommandTransport } from "./amqp-command-transport.js";
 export { AmqpRabbitMqQueryTransport } from "./amqp-query-transport.js";
 export { createAmqpConnection, } from "./connection.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,qBAAqB,GAMtB,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,2BAA2B,GAG5B,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,wBAAwB,GAKzB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EACL,sBAAsB,GAKvB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAA;AAC1E,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAA;AAEtE,OAAO,EACL,oBAAoB,GAGrB,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,qBAAqB,GAMtB,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,2BAA2B,GAG5B,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,wBAAwB,GAKzB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EACL,sBAAsB,GAKvB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACL,iCAAiC,GAKlC,MAAM,sCAAsC,CAAA;AAE7C,OAAO,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAA;AAC1E,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAA;AAEtE,OAAO,EACL,oBAAoB,GAGrB,MAAM,iBAAiB,CAAA"}

package/dist/query-bus.d.ts

@@ -1,5 +1,6 @@
 import type { QueryBus, QueryMessage } from "@kronos-ts/messaging";
 import type { RabbitMqResolvedConfig } from "./rabbitmq.js";
+import type { DistributedSubscriberRegistry } from "./distributed-subscriber-registry.js";
 export interface RabbitMqQueryEnvelope {
     readonly kind: "query";
     readonly requestId: string;
@@ -23,16 +24,31 @@ export interface RabbitMqQueryTransport {
 export interface RabbitMqQueryBusOptions {
     readonly localSegment: QueryBus;
     readonly transport: RabbitMqQueryTransport;
+    readonly subscriberRegistry?: DistributedSubscriberRegistry;
     readonly config: RabbitMqResolvedConfig;
 }
 /**
  * Distributed query bus decorator.
  *
- * Direct request/reply queries (`query` + `subscribe`) route over RabbitMQ.
- * Subscription queries (`subscriptionQuery`, `subscribeToUpdates`, `emitUpdate`,
- * `completeSubscription*`) remain process-local and delegate to the local
- * segment — distributing subscription-query update streams over RabbitMQ is
- * intentionally out of scope for this version (see rabbitmq-extension-plan.md).
+ * Direct request/reply queries (`query` + `subscribe`) route over the
+ * request/reply transport.
+ *
+ * Subscription queries use a distributed-mirror model. Every subscribe
+ * publishes a `claim` over the gossip fanout exchange so every instance
+ * learns about it; every unsubscribe publishes a `release`. Each instance
+ * keeps a cluster-wide `Map<subId, SubscriberRecord>` mirror.
+ *
+ * `emitUpdate` walks the mirror locally (it holds every cluster-wide
+ * subscriber's payload), applies the filter — function predicates work
+ * because evaluation happens colocated with the payload, not over the wire —
+ * and routes per-subscriber delivery via the registry. Local subs are
+ * dispatched in-process; remote subs receive a `DeliverEnvelope` on the
+ * owner's direct queue.
+ *
+ * The same model handles `completeSubscription` and
+ * `completeSubscriptionExceptionally`.
+ *
+ * Falls back to local-only behaviour when no `subscriberRegistry` is supplied.
  */
 export declare function createRabbitMqQueryBus(options: RabbitMqQueryBusOptions): QueryBus;
 //# sourceMappingURL=query-bus.d.ts.map

package/dist/query-bus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-bus.d.ts","sourceRoot":"","sources":["../src/query-bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAA2B,MAAM,sBAAsB,CAAA;AAG3F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAE3D,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;QACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KACxB,CAAA;CACF;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAA;IAC9E,SAAS,CACP,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,CAAC,QAAQ,EAAE,qBAAqB,KAAK,OAAO,CAAC,0BAA0B,CAAC,GAChF,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,sBAAsB,CAAA;IAC1C,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAA;CACxC;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,QAAQ,CA4EjF"}
+{"version":3,"file":"query-bus.d.ts","sourceRoot":"","sources":["../src/query-bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EAIb,MAAM,sBAAsB,CAAA;AAQ7B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAC3D,OAAO,KAAK,EAEV,6BAA6B,EAC9B,MAAM,sCAAsC,CAAA;AAE7C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;QACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KACxB,CAAA;CACF;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAA;IAC9E,SAAS,CACP,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,CAAC,QAAQ,EAAE,qBAAqB,KAAK,OAAO,CAAC,0BAA0B,CAAC,GAChF,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,sBAAsB,CAAA;IAC1C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,6BAA6B,CAAA;IAC3D,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAA;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,QAAQ,CAmOjF"}