@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.10

package/dist/host/event-bus/event-bus.factory.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectEventBus = selectEventBus;
+exports.createEventBus = createEventBus;
+const common_1 = require("@nestjs/common");
+const config_1 = require("@nestjs/config");
+const app_metrics_service_1 = require("../metrics/app-metrics.service");
+require("./builtin-event-bus-adapters");
+const event_bus_adapter_registry_1 = require("./event-bus-adapter.registry");
+const event_bus_config_1 = require("./event-bus.config");
+const event_bus_metrics_1 = require("./event-bus.metrics");
+// =============================================================================
+// The process's one event bus (PP-1.11, issue #682; packaged by #867)
+// =============================================================================
+//
+// `PlatformHostCoreModule.forRoot()` provides `EVENT_BUS` globally through
+// these two factories, so `@Inject(EVENT_BUS)` works in every module without
+// an import edge: the bus is infrastructure in the same sense the database is.
+//
+// The adapter is looked up by id in `eventBusAdapterRegistry`: the built-ins
+// and any adapter the app registered with `registerEventBusAdapter` (PP-14.2).
+// An app may also bind a whole bus instead (`forRoot({ eventBus })`), which
+// bypasses this file.
+//
+// ONE INSTANCE PER PROCESS. The adapter's origin id is what lets a Postgres
+// listener drop its own echo; two instances in one process would each treat
+// the other's messages as remote and deliver them twice.
+//
+// The Postgres adapter's lifecycle hooks run on the factory-built instance:
+// it starts listening in `onModuleInit` (without blocking boot) and closes its
+// session in `onModuleDestroy`.
+// =============================================================================
+const logger = new common_1.Logger('EventBusModule');
+/**
+ * Parses the configured adapter and warns once about an unregistered value.
+ *
+ * @param raw - the configured value (`EVENT_BUS_ADAPTER`, or the `eventBusAdapter` option).
+ * @param options - see {@link SelectEventBusOptions}.
+ * @returns the selection.
+ * @throws Error naming the id and the registered ids, when `strict` and the id is not registered.
+ */
+function selectEventBus(raw, options = {}) {
+    const selection = (0, event_bus_config_1.parseEventBusAdapter)(raw);
+    if (!selection.recognised) {
+        if (options.strict)
+            throw (0, event_bus_adapter_registry_1.unknownEventBusAdapterError)(selection.configured.toLowerCase());
+        logger.warn(`Unrecognised EVENT_BUS_ADAPTER "${selection.configured}"; registered adapters: ` +
+            `${event_bus_adapter_registry_1.eventBusAdapterRegistry.ids().join(', ')}. Using "in-process": live events will not cross replicas.`);
+    }
+    return selection;
+}
+/**
+ * Builds the bus for a selection by calling its registered adapter.
+ *
+ * @param selection - which adapter.
+ * @param sql - the app's Prisma client (`PLATFORM_PRISMA`); required by `postgres`.
+ * @param appMetrics - where the `app.event_bus.*` counters go.
+ * @param config - the application's configuration, handed to the adapter.
+ * @returns the bus (a promise of it when the adapter is async).
+ * @throws Error naming the id and listing the registered ones when no adapter has that id; or whatever the adapter throws (`postgres` without a client).
+ */
+function createEventBus(selection, sql, appMetrics = (0, app_metrics_service_1.fallbackAppMetrics)(), config = new config_1.ConfigService()) {
+    const adapter = event_bus_adapter_registry_1.eventBusAdapterRegistry.get(selection.adapter);
+    if (!adapter)
+        throw (0, event_bus_adapter_registry_1.unknownEventBusAdapterError)(selection.adapter);
+    // `app.event_bus.*` (#680): declared in the app-metric registry, emitted
+    // through the generic `add`.
+    const metrics = (0, event_bus_metrics_1.eventBusMetricsVia)((key, value, attributes) => appMetrics.add(key, value, attributes), selection.adapter);
+    return adapter.create({ id: adapter.id, config, logger, prisma: sql, metrics });
+}
+//# sourceMappingURL=event-bus.factory.js.map

package/dist/host/event-bus/event-bus.factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.factory.js","sourceRoot":"","sources":["../../../src/host/event-bus/event-bus.factory.ts"],"names":[],"mappings":";;AA2DA,wCAUC;AAYD,wCAcC;AA/FD,2CAAwC;AACxC,2CAA+C;AAE/C,wEAAuF;AACvF,wCAAsC;AACtC,6EAAoG;AACpG,yDAAkF;AAElF,2DAAyD;AAGzD,gFAAgF;AAChF,sEAAsE;AACtE,gFAAgF;AAChF,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,+EAA+E;AAC/E,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,4EAA4E;AAC5E,sBAAsB;AACtB,EAAE;AACF,4EAA4E;AAC5E,4EAA4E;AAC5E,yDAAyD;AACzD,EAAE;AACF,4EAA4E;AAC5E,+EAA+E;AAC/E,gCAAgC;AAChC,gFAAgF;AAEhF,MAAM,MAAM,GAAG,IAAI,eAAM,CAAC,gBAAgB,CAAC,CAAC;AAkB5C;;;;;;;GAOG;AACH,SAAgB,cAAc,CAAC,GAAuB,EAAE,UAAiC,EAAE;IACzF,MAAM,SAAS,GAAG,IAAA,uCAAoB,EAAC,GAAG,CAAC,CAAC;IAC5C,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;QAC1B,IAAI,OAAO,CAAC,MAAM;YAAE,MAAM,IAAA,wDAA2B,EAAC,SAAS,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;QAC1F,MAAM,CAAC,IAAI,CACT,mCAAmC,SAAS,CAAC,UAAU,0BAA0B;YAC/E,GAAG,oDAAuB,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,4DAA4D,CAC1G,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,cAAc,CAC5B,SAA4B,EAC5B,GAAqC,EACrC,aAAgC,IAAA,wCAAkB,GAAE,EACpD,SAAwB,IAAI,sBAAa,EAAE;IAE3C,MAAM,OAAO,GAAG,oDAAuB,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC/D,IAAI,CAAC,OAAO;QAAE,MAAM,IAAA,wDAA2B,EAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAEnE,yEAAyE;IACzE,6BAA6B;IAC7B,MAAM,OAAO,GAAG,IAAA,sCAAkB,EAAC,CAAC,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,UAAU,CAAC,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;IAE1H,OAAO,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;AAClF,CAAC"}

package/dist/host/event-bus/event-bus.interface.d.ts

@@ -0,0 +1,143 @@
+/**
+ * DI token for the process's one bus. Provided, globally, by
+ * `PlatformHostCoreModule.forRoot()`. A `Symbol.for` key, so two copies of
+ * this file agree on identity.
+ *
+ * @example
+ * ```ts
+ * constructor(@Inject(EVENT_BUS) private readonly bus: EventBus) {}
+ * ```
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+export declare const EVENT_BUS: unique symbol;
+/**
+ * The adapter ids the platform ships.
+ *
+ * @stability experimental
+ */
+export type BuiltinEventBusAdapterName = 'in-process' | 'postgres';
+/**
+ * Which adapter backs a bus: a built-in id, or the id of any adapter an app
+ * registered with `registerEventBusAdapter`. The `(string & {})` keeps the
+ * built-ins offered by completion while accepting every registered id.
+ *
+ * @stability experimental
+ */
+export type EventBusAdapterName = BuiltinEventBusAdapterName | (string & {});
+/**
+ * The adapter ids the platform ships, in the order the docs list them. An app's
+ * own adapters are not here: list them with `eventBusAdapterRegistry.ids()`.
+ *
+ * @stability experimental
+ */
+export declare const BUILTIN_EVENT_BUS_ADAPTERS: readonly BuiltinEventBusAdapterName[];
+/**
+ * Alias of {@link BUILTIN_EVENT_BUS_ADAPTERS}, kept for one release.
+ *
+ * @deprecated Use {@link BUILTIN_EVENT_BUS_ADAPTERS}, or `eventBusAdapterRegistry.ids()` for every registered adapter.
+ * @stability experimental
+ */
+export declare const EVENT_BUS_ADAPTERS: readonly BuiltinEventBusAdapterName[];
+/**
+ * A logical channel name. Lower-case, dotted, at least two segments, e.g.
+ * `notifications.stream`. The first segment names the owning feature.
+ *
+ * @stability experimental
+ */
+export declare const EVENT_BUS_CHANNEL_PATTERN: RegExp;
+/**
+ * The largest serialised envelope (channel, origin and payload together) a
+ * message may have, in UTF-8 bytes.
+ *
+ * Postgres caps a NOTIFY payload at 8000 bytes; this leaves headroom for the
+ * envelope's own keys and for a future version field. Enforced on EVERY
+ * adapter so a payload that would fail in production fails in development too.
+ *
+ * @stability experimental
+ */
+export declare const EVENT_BUS_MAX_PAYLOAD_BYTES = 7500;
+/**
+ * Thrown (and caught and logged — never surfaced to the caller) for an oversize message.
+ *
+ * @stability experimental
+ */
+export declare class EventBusPayloadTooLargeError extends Error {
+    readonly channel: string;
+    readonly bytes: number;
+    /**
+     * @param channel - the logical channel the message was published on.
+     * @param bytes - the serialised envelope's size in UTF-8 bytes.
+     */
+    constructor(channel: string, bytes: number);
+}
+/**
+ * What a handler learns about a message besides its payload.
+ *
+ * @stability experimental
+ */
+export interface EventBusMeta {
+    /** Process-unique id of the publisher (random UUID per process start). */
+    origin: string;
+    /** True when this process published it. */
+    local: boolean;
+}
+/**
+ * A subscriber. Its failures are logged and isolated (rule 4).
+ *
+ * @typeParam T - the payload type, after a JSON round trip.
+ * @stability experimental
+ */
+export type EventBusHandler<T> = (payload: T, meta: EventBusMeta) => void | Promise<void>;
+/**
+ * A synchronous snapshot of the bus, for the Doctor.
+ *
+ * @stability experimental
+ */
+export interface EventBusHealth {
+    /** Which adapter backs this process's bus. */
+    adapter: EventBusAdapterName;
+    /** Always true in-process; for postgres, whether the LISTEN session is up. */
+    connected: boolean;
+    /** The most recent connection or publish error message. Never secret material. */
+    lastError: string | null;
+    /** ISO timestamp of the last successful (re)connect; the boot time in-process. */
+    lastConnectedAt: string | null;
+    /** Messages this process failed to publish (oversize, bad channel, NOTIFY error). */
+    publishFailures: number;
+    /** Times the listener has been scheduled to reconnect. Always 0 in-process. */
+    reconnects: number;
+}
+/**
+ * The process's publish/subscribe seam. See the rules at the top of this file.
+ *
+ * @stability experimental
+ */
+export interface EventBus {
+    /** Which adapter backs this bus. */
+    readonly adapter: EventBusAdapterName;
+    /** This process's origin id, as carried in `EventBusMeta.origin`. */
+    readonly origin: string;
+    /**
+     * Sends `payload` to every subscriber of `channel`, in this process and (for
+     * a shared adapter) in every other one. NEVER REJECTS: see rule 5 above.
+     */
+    publish<T>(channel: string, payload: T): Promise<void>;
+    /**
+     * Registers a handler for `channel` and returns its unsubscribe function.
+     * Issues no I/O on any adapter. Throws only for a malformed channel name,
+     * which is a programming error caught at boot.
+     */
+    subscribe<T>(channel: string, handler: EventBusHandler<T>): () => void;
+    /** A synchronous snapshot. Performs no I/O, so a Doctor check may call it freely. */
+    health(): EventBusHealth;
+    /**
+     * Releases the adapter's resources (a listener session, a connection) and
+     * stops delivering. Idempotent. Optional: an adapter with nothing to release
+     * omits it. Nest calls `onModuleDestroy` on the instance, not this method, so
+     * an adapter that holds resources implements both.
+     */
+    close?(): Promise<void>;
+}
+//# sourceMappingURL=event-bus.interface.d.ts.map

package/dist/host/event-bus/event-bus.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.interface.d.ts","sourceRoot":"","sources":["../../../src/host/event-bus/event-bus.interface.ts"],"names":[],"mappings":"AAoFA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS,EAAE,OAAO,MAAqD,CAAC;AAErF;;;;GAIG;AACH,MAAM,MAAM,0BAA0B,GAAG,YAAY,GAAG,UAAU,CAAC;AAEnE;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,0BAA0B,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE7E;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,0BAA0B,EAA+B,CAAC;AAE5G;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,0BAA0B,EAA+B,CAAC;AAEpG;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,QAAyC,CAAC;AAEhF;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AAEjD;;;;GAIG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IAMnD,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM;IANxB;;;OAGG;gBAEQ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM;CAQzB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1F;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,OAAO,EAAE,mBAAmB,CAAC;IAC7B,8EAA8E;IAC9E,SAAS,EAAE,OAAO,CAAC;IACnB,kFAAkF;IAClF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,kFAAkF;IAClF,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,qFAAqF;IACrF,eAAe,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IAEtC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvD;;;;OAIG;IACH,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IAEvE,qFAAqF;IACrF,MAAM,IAAI,cAAc,CAAC;IAEzB;;;;;OAKG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}

package/dist/host/event-bus/event-bus.interface.js

@@ -0,0 +1,154 @@
+"use strict";
+// =============================================================================
+// The cross-replica event bus (PP-1.11, issue #682)
+// =============================================================================
+//
+// A tiny publish/subscribe seam that reaches every API process sharing one
+// database, not just the one that published. It exists because two pieces of
+// state used to live in one Node heap and therefore stopped at the edge of one
+// replica:
+//
+//   - the SSE registry (`notifications/notification-stream.service.ts`), so a
+//     tab connected to replica A never saw a live event published on replica B;
+//   - the idle job worker (`jobs/job.worker.ts`), which could only learn about
+//     new work by polling.
+//
+// Both now publish and subscribe through `EVENT_BUS`. Which adapter backs it
+// is DEPLOYMENT TOPOLOGY (`EVENT_BUS_ADAPTER`, read once at boot), not a
+// runtime setting: it decides how processes talk to each other, so it has to
+// be known before any of them start.
+//
+//   - `in-process` — one `Map` in this heap. Today's single-process behaviour,
+//     and the default when the variable is unset (tests, `npm run api:dev`).
+//   - `postgres`   — `pg_notify` to publish, one dedicated `LISTEN` session to
+//     receive. No new infrastructure: the database every replica already
+//     shares is the bus. See `postgres-event-bus.ts`.
+//
+// Any other adapter (Redis, NATS, a test double) registers itself behind this
+// same interface with `registerEventBusAdapter` (./event-bus-adapter.registry.ts)
+// or is bound whole through `PlatformHostCoreModule.forRoot({ eventBus })`;
+// nothing above the interface moves.
+//
+// -----------------------------------------------------------------------------
+// SEMANTICS EVERY ADAPTER HONOURS
+// -----------------------------------------------------------------------------
+//
+//   1. LOCAL DELIVERY. A subscriber in the publishing process receives every
+//      message exactly once, with `meta.local === true`, on EVERY adapter. It
+//      runs in a microtask after `publish` was called, never inside the
+//      publisher's own stack, so a slow or throwing handler cannot reach back
+//      into the code that published.
+//
+//   2. REMOTE DELIVERY IS AT MOST ONCE, WITH NO REPLAY. Another process
+//      receives a message at most once, with `meta.local === false`. A message
+//      published while a listener is disconnected is LOST for that listener —
+//      by design. Every consumer must therefore treat the bus as a latency
+//      optimisation over a durable source of truth: the stream's clients
+//      refetch on (re)connect, and the job worker still polls.
+//
+//   3. NO ECHO. The Postgres adapter hears its own NOTIFY. The envelope carries
+//      the publisher's `origin` and an adapter DROPS messages whose origin is
+//      its own, because rule 1 has already delivered them locally.
+//
+//   4. HANDLER FAILURES ARE ISOLATED. A handler that throws (or whose promise
+//      rejects) is logged with the channel name — never the payload — and
+//      neither stops the other handlers nor reaches the publisher.
+//
+//   5. `publish` NEVER REJECTS. A failed NOTIFY, a malformed channel or an
+//      oversize payload is logged and counted (`health().publishFailures`).
+//      Publishing is always a best-effort side effect of work that has already
+//      been made durable.
+//
+//   6. NOT TRANSACTIONAL. Never publish inside a `$transaction`: a message about
+//      a write the transaction then rolls back would announce something that
+//      never happened, and a `pg_notify` on the pooled transaction connection
+//      would only be sent at COMMIT anyway. Publish AFTER the write commits —
+//      the same rule CLAUDE.md states for `notify()`.
+//
+//   7. PAYLOADS ARE JSON. Every subscriber, local or remote, receives a JSON
+//      round-trip copy of what was published (a `Date` arrives as a string on
+//      every adapter, so in-process behaviour cannot hide a bug that only shows
+//      across replicas). The serialised envelope must fit in
+//      `EVENT_BUS_MAX_PAYLOAD_BYTES`; anything larger is rejected locally
+//      (logged as `EventBusPayloadTooLargeError`) and reaches nobody. Publish a
+//      REFERENCE (an id the receiver reads from the database) for large data.
+//
+//   8. ⚠ NEVER PUT A SECRET ON THE BUS. The Postgres adapter's NOTIFY payload
+//      is readable by any session holding the application's database
+//      credentials. That is no wider than the data those credentials already
+//      read — but a token, key or password published here would be one more
+//      copy outside the encrypted credential store.
+//
+// Logical channels are dotted lower-case names (`notifications.stream`,
+// `jobs.enqueued`); the inventory lives in docs/ARCHITECTURE.md.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventBusPayloadTooLargeError = exports.EVENT_BUS_MAX_PAYLOAD_BYTES = exports.EVENT_BUS_CHANNEL_PATTERN = exports.EVENT_BUS_ADAPTERS = exports.BUILTIN_EVENT_BUS_ADAPTERS = exports.EVENT_BUS = void 0;
+/**
+ * DI token for the process's one bus. Provided, globally, by
+ * `PlatformHostCoreModule.forRoot()`. A `Symbol.for` key, so two copies of
+ * this file agree on identity.
+ *
+ * @example
+ * ```ts
+ * constructor(@Inject(EVENT_BUS) private readonly bus: EventBus) {}
+ * ```
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+exports.EVENT_BUS = Symbol.for('@marinoscar/platform/EVENT_BUS');
+/**
+ * The adapter ids the platform ships, in the order the docs list them. An app's
+ * own adapters are not here: list them with `eventBusAdapterRegistry.ids()`.
+ *
+ * @stability experimental
+ */
+exports.BUILTIN_EVENT_BUS_ADAPTERS = ['in-process', 'postgres'];
+/**
+ * Alias of {@link BUILTIN_EVENT_BUS_ADAPTERS}, kept for one release.
+ *
+ * @deprecated Use {@link BUILTIN_EVENT_BUS_ADAPTERS}, or `eventBusAdapterRegistry.ids()` for every registered adapter.
+ * @stability experimental
+ */
+exports.EVENT_BUS_ADAPTERS = exports.BUILTIN_EVENT_BUS_ADAPTERS;
+/**
+ * A logical channel name. Lower-case, dotted, at least two segments, e.g.
+ * `notifications.stream`. The first segment names the owning feature.
+ *
+ * @stability experimental
+ */
+exports.EVENT_BUS_CHANNEL_PATTERN = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9_]*)+$/;
+/**
+ * The largest serialised envelope (channel, origin and payload together) a
+ * message may have, in UTF-8 bytes.
+ *
+ * Postgres caps a NOTIFY payload at 8000 bytes; this leaves headroom for the
+ * envelope's own keys and for a future version field. Enforced on EVERY
+ * adapter so a payload that would fail in production fails in development too.
+ *
+ * @stability experimental
+ */
+exports.EVENT_BUS_MAX_PAYLOAD_BYTES = 7_500;
+/**
+ * Thrown (and caught and logged — never surfaced to the caller) for an oversize message.
+ *
+ * @stability experimental
+ */
+class EventBusPayloadTooLargeError extends Error {
+    channel;
+    bytes;
+    /**
+     * @param channel - the logical channel the message was published on.
+     * @param bytes - the serialised envelope's size in UTF-8 bytes.
+     */
+    constructor(channel, bytes) {
+        super(`Event bus message on "${channel}" is ${bytes} bytes; the limit is ` +
+            `${exports.EVENT_BUS_MAX_PAYLOAD_BYTES}. Publish a reference instead of the data.`);
+        this.channel = channel;
+        this.bytes = bytes;
+        this.name = 'EventBusPayloadTooLargeError';
+    }
+}
+exports.EventBusPayloadTooLargeError = EventBusPayloadTooLargeError;
+//# sourceMappingURL=event-bus.interface.js.map

package/dist/host/event-bus/event-bus.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.interface.js","sourceRoot":"","sources":["../../../src/host/event-bus/event-bus.interface.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,oDAAoD;AACpD,gFAAgF;AAChF,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,+EAA+E;AAC/E,WAAW;AACX,EAAE;AACF,8EAA8E;AAC9E,gFAAgF;AAChF,+EAA+E;AAC/E,2BAA2B;AAC3B,EAAE;AACF,6EAA6E;AAC7E,yEAAyE;AACzE,6EAA6E;AAC7E,qCAAqC;AACrC,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,+EAA+E;AAC/E,yEAAyE;AACzE,sDAAsD;AACtD,EAAE;AACF,8EAA8E;AAC9E,kFAAkF;AAClF,4EAA4E;AAC5E,qCAAqC;AACrC,EAAE;AACF,gFAAgF;AAChF,kCAAkC;AAClC,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,wEAAwE;AACxE,8EAA8E;AAC9E,qCAAqC;AACrC,EAAE;AACF,wEAAwE;AACxE,+EAA+E;AAC/E,8EAA8E;AAC9E,2EAA2E;AAC3E,yEAAyE;AACzE,+DAA+D;AAC/D,EAAE;AACF,gFAAgF;AAChF,8EAA8E;AAC9E,mEAAmE;AACnE,EAAE;AACF,8EAA8E;AAC9E,0EAA0E;AAC1E,mEAAmE;AACnE,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAC5E,+EAA+E;AAC/E,0BAA0B;AAC1B,EAAE;AACF,iFAAiF;AACjF,6EAA6E;AAC7E,8EAA8E;AAC9E,8EAA8E;AAC9E,sDAAsD;AACtD,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,gFAAgF;AAChF,6DAA6D;AAC7D,0EAA0E;AAC1E,gFAAgF;AAChF,8EAA8E;AAC9E,EAAE;AACF,8EAA8E;AAC9E,qEAAqE;AACrE,6EAA6E;AAC7E,4EAA4E;AAC5E,oDAAoD;AACpD,EAAE;AACF,wEAAwE;AACxE,iEAAiE;AACjE,gFAAgF;;;AAEhF;;;;;;;;;;;;GAYG;AACU,QAAA,SAAS,GAAkB,MAAM,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC;AAkBrF;;;;;GAKG;AACU,QAAA,0BAA0B,GAA0C,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;AAE5G;;;;;GAKG;AACU,QAAA,kBAAkB,GAA0C,kCAA0B,CAAC;AAEpG;;;;;GAKG;AACU,QAAA,yBAAyB,GAAG,sCAAsC,CAAC;AAEhF;;;;;;;;;GASG;AACU,QAAA,2BAA2B,GAAG,KAAK,CAAC;AAEjD;;;;GAIG;AACH,MAAa,4BAA6B,SAAQ,KAAK;IAM1C;IACA;IANX;;;OAGG;IACH,YACW,OAAe,EACf,KAAa;QAEtB,KAAK,CACH,yBAAyB,OAAO,QAAQ,KAAK,uBAAuB;YAClE,GAAG,mCAA2B,4CAA4C,CAC7E,CAAC;QANO,YAAO,GAAP,OAAO,CAAQ;QACf,UAAK,GAAL,KAAK,CAAQ;QAMtB,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AAfD,oEAeC"}

package/dist/host/event-bus/event-bus.metrics.d.ts

@@ -0,0 +1,66 @@
+import type { AppMetricDef } from '../../otel-core/index';
+import type { EventBusAdapterName } from './event-bus.interface';
+/**
+ * How one `publish` call ended.
+ *
+ * @stability experimental
+ */
+export type EventBusPublishOutcome = 
+/** Encoded and delivered locally (and, on `postgres`, NOTIFYed). */
+'published'
+/** Refused before delivery: an invalid channel, an oversize or unserialisable payload. */
+ | 'rejected'
+/** `postgres` only: delivered locally, but the NOTIFY failed, so other replicas miss it. */
+ | 'notify_failed';
+/**
+ * An event bus metric's code key.
+ *
+ * @stability experimental
+ */
+export type EventBusAppMetricKey = 'eventBusPublished' | 'eventBusDelivered' | 'eventBusReconnects';
+/**
+ * One of the event bus's metric declarations.
+ *
+ * @stability experimental
+ */
+export interface EventBusAppMetricDef extends AppMetricDef {
+    /** The metric's code key. */
+    readonly key: EventBusAppMetricKey;
+}
+/**
+ * The bus's three `app.event_bus.*` counters, registered with the platform's metrics.
+ *
+ * @stability experimental
+ */
+export declare const EVENT_BUS_APP_METRICS: readonly EventBusAppMetricDef[];
+/**
+ * What an adapter reports. Every method is fire and forget and never throws.
+ *
+ * @stability experimental
+ */
+export interface EventBusMetrics {
+    /** One `publish` call ended with `outcome`. */
+    published(channel: string, outcome: EventBusPublishOutcome): void;
+    /** One message was handed to this process's subscribers. */
+    delivered(channel: string, origin: 'local' | 'remote'): void;
+    /** The listener scheduled a reconnect. */
+    reconnect(): void;
+}
+/**
+ * Reports nothing: the default for an adapter built without a sink (tests, scripts).
+ *
+ * @stability experimental
+ */
+export declare const NOOP_EVENT_BUS_METRICS: EventBusMetrics;
+/**
+ * The sink over `AppMetricsService.add` (passed as a function, so this file
+ * imports no service). `add` never throws; the wrapper guards anyway, because
+ * a metrics fault must never reach a publisher.
+ *
+ * @param add - the counter sink (`AppMetricsService.add`).
+ * @param adapter - the adapter the counts are labelled with.
+ * @returns the sink.
+ * @stability experimental
+ */
+export declare function eventBusMetricsVia(add: (key: string, value: number, attributes: Record<string, unknown>) => void, adapter: EventBusAdapterName): EventBusMetrics;
+//# sourceMappingURL=event-bus.metrics.d.ts.map

package/dist/host/event-bus/event-bus.metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.metrics.d.ts","sourceRoot":"","sources":["../../../src/host/event-bus/event-bus.metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAgBjE;;;;GAIG;AACH,MAAM,MAAM,sBAAsB;AAChC,oEAAoE;AAClE,WAAW;AACb,0FAA0F;GACxF,UAAU;AACZ,4FAA4F;GAC1F,eAAe,CAAC;AAIpB;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,mBAAmB,GAAG,mBAAmB,GAAG,oBAAoB,CAAC;AAEpG;;;;GAIG;AACH,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD,6BAA6B;IAC7B,QAAQ,CAAC,GAAG,EAAE,oBAAoB,CAAC;CACpC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,oBAAoB,EAkChE,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAClE,4DAA4D;IAC5D,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAAC;IAC7D,0CAA0C;IAC1C,SAAS,IAAI,IAAI,CAAC;CACnB;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,eAIpC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,EAC9E,OAAO,EAAE,mBAAmB,GAC3B,eAAe,CAajB"}

package/dist/host/event-bus/event-bus.metrics.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOOP_EVENT_BUS_METRICS = exports.EVENT_BUS_APP_METRICS = void 0;
+exports.eventBusMetricsVia = eventBusMetricsVia;
+const ADAPTER = { kind: 'enum', values: ['in-process', 'postgres'] };
+/**
+ * The bus's three `app.event_bus.*` counters, registered with the platform's metrics.
+ *
+ * @stability experimental
+ */
+exports.EVENT_BUS_APP_METRICS = [
+    {
+        key: 'eventBusPublished',
+        name: 'app.event_bus.published',
+        kind: 'counter',
+        unit: '{message}',
+        description: 'Messages published on the event bus, by adapter, channel and outcome.',
+        attributes: {
+            adapter: ADAPTER,
+            channel: { kind: 'free' },
+            outcome: { kind: 'enum', values: ['published', 'rejected', 'notify_failed'] },
+        },
+    },
+    {
+        key: 'eventBusDelivered',
+        name: 'app.event_bus.delivered',
+        kind: 'counter',
+        unit: '{message}',
+        description: "Messages handed to this process's subscribers, by adapter, channel and origin (local: published here; remote: another replica).",
+        attributes: {
+            adapter: ADAPTER,
+            channel: { kind: 'free' },
+            origin: { kind: 'enum', values: ['local', 'remote'] },
+        },
+    },
+    {
+        key: 'eventBusReconnects',
+        name: 'app.event_bus.reconnects',
+        kind: 'counter',
+        unit: '{reconnect}',
+        description: 'Listener reconnects the event bus scheduled after losing its session, by adapter.',
+        attributes: { adapter: ADAPTER },
+    },
+];
+/**
+ * Reports nothing: the default for an adapter built without a sink (tests, scripts).
+ *
+ * @stability experimental
+ */
+exports.NOOP_EVENT_BUS_METRICS = {
+    published: () => undefined,
+    delivered: () => undefined,
+    reconnect: () => undefined,
+};
+/**
+ * The sink over `AppMetricsService.add` (passed as a function, so this file
+ * imports no service). `add` never throws; the wrapper guards anyway, because
+ * a metrics fault must never reach a publisher.
+ *
+ * @param add - the counter sink (`AppMetricsService.add`).
+ * @param adapter - the adapter the counts are labelled with.
+ * @returns the sink.
+ * @stability experimental
+ */
+function eventBusMetricsVia(add, adapter) {
+    const safely = (fn) => {
+        try {
+            fn();
+        }
+        catch {
+            // Never reaches the bus.
+        }
+    };
+    return {
+        published: (channel, outcome) => safely(() => add('eventBusPublished', 1, { adapter, channel, outcome })),
+        delivered: (channel, origin) => safely(() => add('eventBusDelivered', 1, { adapter, channel, origin })),
+        reconnect: () => safely(() => add('eventBusReconnects', 1, { adapter })),
+    };
+}
+//# sourceMappingURL=event-bus.metrics.js.map

package/dist/host/event-bus/event-bus.metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.metrics.js","sourceRoot":"","sources":["../../../src/host/event-bus/event-bus.metrics.ts"],"names":[],"mappings":";;;AA6HA,gDAgBC;AA/GD,MAAM,OAAO,GAAuB,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,YAAY,EAAE,UAAU,CAAC,EAAE,CAAC;AAmBzF;;;;GAIG;AACU,QAAA,qBAAqB,GAAoC;IACpE;QACE,GAAG,EAAE,mBAAmB;QACxB,IAAI,EAAE,yBAAyB;QAC/B,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,WAAW;QACjB,WAAW,EAAE,uEAAuE;QACpF,UAAU,EAAE;YACV,OAAO,EAAE,OAAO;YAChB,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;YACzB,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,WAAW,EAAE,UAAU,EAAE,eAAe,CAAC,EAAE;SAC9E;KACF;IACD;QACE,GAAG,EAAE,mBAAmB;QACxB,IAAI,EAAE,yBAAyB;QAC/B,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,WAAW;QACjB,WAAW,EACT,iIAAiI;QACnI,UAAU,EAAE;YACV,OAAO,EAAE,OAAO;YAChB,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;YACzB,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE;SACtD;KACF;IACD;QACE,GAAG,EAAE,oBAAoB;QACzB,IAAI,EAAE,0BAA0B;QAChC,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,aAAa;QACnB,WAAW,EAAE,mFAAmF;QAChG,UAAU,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE;KACjC;CACF,CAAC;AAgBF;;;;GAIG;AACU,QAAA,sBAAsB,GAAoB;IACrD,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS;IAC1B,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS;IAC1B,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS;CAC3B,CAAC;AAEF;;;;;;;;;GASG;AACH,SAAgB,kBAAkB,CAChC,GAA8E,EAC9E,OAA4B;IAE5B,MAAM,MAAM,GAAG,CAAC,EAAc,EAAE,EAAE;QAChC,IAAI,CAAC;YACH,EAAE,EAAE,CAAC;QACP,CAAC;QAAC,MAAM,CAAC;YACP,yBAAyB;QAC3B,CAAC;IACH,CAAC,CAAC;IACF,OAAO;QACL,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,mBAAmB,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QACzG,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,mBAAmB,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QACvG,SAAS,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,oBAAoB,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;KACzE,CAAC;AACJ,CAAC"}

package/dist/host/event-bus/in-process-event-bus.d.ts

@@ -0,0 +1,52 @@
+import type { EventBus, EventBusHandler, EventBusHealth } from './event-bus.interface';
+import { type EventBusMetrics } from './event-bus.metrics';
+/**
+ * The single-process adapter: a `Map` in this heap. The default.
+ *
+ * @stability experimental
+ */
+export declare class InProcessEventBus implements EventBus {
+    private readonly metrics;
+    /** Always `in-process`. */
+    readonly adapter: "in-process";
+    /** This process's origin id. */
+    readonly origin: string;
+    private readonly logger;
+    private readonly dispatcher;
+    private readonly startedAt;
+    private publishFailures;
+    private lastError;
+    constructor(origin?: string, metrics?: EventBusMetrics);
+    /**
+     * Delivers locally (and, on a shared adapter, to every other replica). Never rejects.
+     *
+     * @param channel - a logical channel ({@link EVENT_BUS_CHANNEL_PATTERN}).
+     * @param payload - JSON-serialisable data, at most {@link EVENT_BUS_MAX_PAYLOAD_BYTES} encoded.
+     */
+    publish<T>(channel: string, payload: T): Promise<void>;
+    /**
+     * Registers a handler; returns its unsubscribe function.
+     *
+     * @param channel - a logical channel.
+     * @param handler - called once per message, isolated from the publisher.
+     * @returns the unsubscribe function.
+     */
+    subscribe<T>(channel: string, handler: EventBusHandler<T>): () => void;
+    /**
+     * A synchronous snapshot; performs no I/O.
+     *
+     * @returns the bus's health.
+     */
+    health(): EventBusHealth;
+    /** Drops every handler. Idempotent; there is no connection to release. */
+    close(): Promise<void>;
+    /**
+     * Handlers on a channel. Diagnostics and tests only.
+     *
+     * @param channel - a logical channel.
+     * @returns how many handlers are subscribed.
+     */
+    handlerCount(channel: string): number;
+    private recordFailure;
+}
+//# sourceMappingURL=in-process-event-bus.d.ts.map

package/dist/host/event-bus/in-process-event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-process-event-bus.d.ts","sourceRoot":"","sources":["../../../src/host/event-bus/in-process-event-bus.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EAA0B,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAkBnF;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,QAAQ;IAc9C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAb1B,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAG,YAAY,CAAU;IACzC,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAC7D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuC;IAClE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,SAAS,CAAuB;gBAGtC,MAAM,GAAE,MAA4B,EACnB,OAAO,GAAE,eAAwC;IAKpE;;;;;OAKG;IACG,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB5D;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAItE;;;;OAIG;IACH,MAAM,IAAI,cAAc;IAWxB,0EAA0E;IACpE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAIrC,OAAO,CAAC,aAAa;CAKtB"}