@dbx-tools/postgres 0.6.62

package/lib/src/topic-bus.d.ts

@@ -0,0 +1,272 @@
+/**
+ * Topic fan-out over PostgreSQL `LISTEN`/`NOTIFY`, for telling every running
+ * instance of an app that something happened.
+ *
+ * The sibling `advisory-lock` module is about making sure only ONE connection
+ * does a thing; this one is the opposite - EVERY listening session gets every
+ * notification. That makes it the right primitive for live UI updates
+ * (an SSE stream per browser tab, a cache invalidation, a presence ping) and the
+ * wrong one for work distribution: there are no competing consumers, no acks, and
+ * no replay.
+ *
+ * Delivery is best-effort and live. `NOTIFY` reaches sessions that are listening
+ * at the moment it commits, so a listener that connects a second later never sees
+ * it, and a listener whose connection drops misses everything until the bus
+ * reconnects. Use a table or a queue when a subscriber needs durability.
+ *
+ * ONE CHANNEL, MANY TOPICS. Every bus instance listens on a single Postgres
+ * channel (`channel`, default `dbx_tools_topic_bus`) and filters by the
+ * envelope's `topic` in-process, so adding a topic costs no connection and no
+ * `LISTEN`. The tradeoff is that every listening session decodes every message on
+ * the channel; give a genuinely high-volume, unrelated stream its own `channel`
+ * rather than a topic.
+ *
+ * @module
+ */
+import { object } from "@dbx-tools/shared-core";
+import type { PgPoolLike, PgQueryable } from "./advisory-lock.ts";
+/**
+ * `@dbx-tools/shared-core` owns the JSON-round-trip rule; this alias just keeps the
+ * generic signatures below readable. Consumers import the type from shared-core.
+ */
+type SerializableValue = object.SerializableValue;
+/**
+ * Flat-keyed context travelling alongside a message body: who sent it, from
+ * where, in which deployment. Values may nest, but the keys are the addressable
+ * part - a listener filtering or labelling messages reads `metadata.user`, not a
+ * path into the body.
+ */
+export type TopicMetadata = Record<string, SerializableValue>;
+/**
+ * The wire envelope every subscriber receives, and what {@link
+ * PostgresTopicBus.broadcast} returns to the publisher.
+ *
+ * `id`, `topic`, and `publishedAt` are assigned by the bus; `type`, `metadata`,
+ * and `body` come from the caller (with automatic context merged under
+ * `metadata`). The shape is stable enough to hand straight to an SSE `data:`
+ * frame.
+ */
+export interface TopicMessage<TBody extends SerializableValue = SerializableValue> {
+    /**
+     * Per-message identity generated by the publisher, unique across instances.
+     * Suitable for dedupe when a client reconnects and for an SSE `id:` field. Not
+     * ordered, and not a database key.
+     */
+    id: string;
+    /** The topic this was broadcast on; listeners on other topics never see it. */
+    topic: string;
+    /** Caller-chosen event name, e.g. `order.updated`. Never empty. */
+    type: string;
+    /** Automatic context merged with caller metadata. See {@link TopicMetadata}. */
+    metadata: TopicMetadata;
+    /** The caller's payload, unchanged. */
+    body: TBody;
+    /**
+     * ISO-8601 publish time from the PUBLISHING process's clock, not the database's.
+     * Fine for display; do not order messages from different instances by it.
+     */
+    publishedAt: string;
+}
+/** What a caller supplies to {@link PostgresTopicBus.broadcast}. */
+export interface TopicPublishInput<TBody extends SerializableValue = SerializableValue> {
+    /** Event name, e.g. `chat.message`. Must be non-blank. */
+    type: string;
+    /**
+     * Context to attach. Wins over any automatic key of the same name, so a caller
+     * can override a machine default (`project`) or add its own (`traceId`).
+     */
+    metadata?: TopicMetadata;
+    /** The payload. Must satisfy `object.isSerializableValue`. */
+    body: TBody;
+}
+/**
+ * Subscriber callback. Invoked once per matching message on the notification
+ * connection's callback, so it should not block: a returned promise is awaited
+ * only to route a rejection to `onError`, and listeners for one message run
+ * concurrently rather than in registration order.
+ *
+ * `TBody` is unchecked at runtime. The bus guarantees the body is serializable,
+ * not that it matches the type parameter, so validate anything a listener
+ * branches on.
+ */
+export type TopicListener<TBody extends SerializableValue = SerializableValue> = (message: TopicMessage<TBody>) => void | PromiseLike<void>;
+/**
+ * Resolves metadata at publish time instead of construction time, for context a
+ * process learns late or asynchronously - a discovered public IP, an instance id
+ * from a control plane. Called on every broadcast, so memoize anything expensive;
+ * a rejection fails the broadcast.
+ */
+export type TopicMetadataProvider = () => TopicMetadata | PromiseLike<TopicMetadata>;
+/** Construction options for {@link PostgresTopicBus}. */
+export interface PostgresTopicBusOptions {
+    /**
+     * What identifies this channel - anything, not just an identifier: a name, an
+     * id, a `[env, feature]` pair, a config object. The parts are tokenized into a
+     * legal Postgres channel name with a short hash of the originals appended, so
+     * the derivation is deterministic and no call site has to sanitize. See
+     * {@link PostgresTopicBus.channelName} for the resolved name.
+     *
+     * One value or many: an array is read as multiple parts
+     * ({@link object.OneOrMany}), anything else as a single part. So
+     * `["billing", "prod"]` and `"billing_prod"` are different channels, since the
+     * hash sees different structure.
+     *
+     * Every participating process must pass EQUIVALENT parts, since a different
+     * spelling hashes to a different channel. Defaults to a shared
+     * `dbx_tools_topic_bus` channel.
+     */
+    channel?: unknown;
+    /**
+     * Extra context added to every message this bus publishes, either a fixed
+     * record or a {@link TopicMetadataProvider} called per broadcast. Overrides
+     * automatic machine keys; per-call `metadata` overrides this.
+     */
+    metadata?: TopicMetadata | TopicMetadataProvider;
+    /**
+     * Sink for failures that have no caller to throw to: a listener that rejected,
+     * a dropped notification connection, a failed reconnect attempt. Defaults to
+     * swallowing them, so wire this to a logger in anything long-running.
+     */
+    onError?: (cause: unknown) => void;
+}
+/**
+ * Broadcasts structured messages by topic and delivers them to every process
+ * listening on the same channel.
+ *
+ * CONNECTION SHAPE. Publishing borrows a pooled connection per call, like any
+ * other query. Listening cannot: `LISTEN` is session state, so the bus holds ONE
+ * dedicated client out of the pool for as long as it has subscribers, no matter
+ * how many topics or listeners are registered. Size the pool with that one
+ * long-lived checkout in mind.
+ *
+ * LIFECYCLE. Construction is inert - nothing connects until the first
+ * {@link listen} (or an explicit {@link start}). {@link close} is required to give
+ * the connection back; a closed bus stays closed and throws on further use rather
+ * than silently reconnecting. Register it with the host's shutdown hook.
+ *
+ * FAILURE HANDLING. A lost notification connection reconnects on its own with
+ * bounded backoff while subscribers remain, reporting each failed attempt through
+ * `onError`. Messages published during the gap are lost - `NOTIFY` has no replay.
+ * A throwing or rejecting listener never affects the publisher or the other
+ * listeners; its failure goes to `onError`.
+ *
+ * Not safe to share one instance across unrelated channels - construct one bus
+ * per channel. The channel itself is DERIVED from the `channel` option rather
+ * than taken literally; see {@link PostgresTopicBusOptions.channel} and
+ * {@link PostgresTopicBus.channelName}.
+ */
+export declare class PostgresTopicBus {
+    private readonly pool;
+    /**
+     * The resolved Postgres channel this bus listens and publishes on, derived from
+     * the `channel` option. Read it to confirm two processes agree, or to log what a
+     * set of parts actually resolved to.
+     */
+    readonly channelName: string;
+    private readonly metadata;
+    private readonly onError;
+    private readonly listeners;
+    private client;
+    private starting;
+    private reconnecting;
+    private readonly reconnectAbort;
+    private closed;
+    constructor(pool: PgPoolLike & PgQueryable, options?: PostgresTopicBusOptions);
+    /**
+     * Open the dedicated notification connection and `LISTEN`.
+     *
+     * Idempotent, and safe to call concurrently - overlapping calls await the same
+     * in-flight connect. {@link listen} calls this, so it is only needed to surface
+     * a connection problem at startup rather than on first subscribe. Throws if the
+     * bus is closed, or if the pool cannot hand out a connection.
+     */
+    start(): Promise<void>;
+    /**
+     * Publish a message to `topic`, returning the envelope that was sent.
+     *
+     * Resolves once Postgres has accepted the `NOTIFY`, which says nothing about
+     * anyone receiving it: sessions not listening at that moment miss it. Publishing
+     * needs no {@link start} and no subscribers.
+     *
+     * Validation is deliberately front-loaded, since a message that fails on the
+     * wire is far harder to diagnose than one rejected at the call: `TypeError` for a
+     * blank topic or type, or a body/metadata that would not round-trip through JSON
+     * unchanged (`object.isSerializableValue`); `RangeError` when the encoded
+     * envelope exceeds the `NOTIFY` payload limit, which the automatic metadata
+     * counts against - send a reference and let the receiver fetch the payload.
+     * Throws if the bus is closed.
+     */
+    broadcast<TBody extends SerializableValue>(topic: string, input: TopicPublishInput<TBody>): Promise<TopicMessage<TBody>>;
+    /**
+     * Subscribe to `topic`, returning the function that unsubscribes.
+     *
+     * Connects on first use. Several listeners may share a topic; each is called
+     * once per message. Only messages published AFTER this resolves arrive, so
+     * subscribe before triggering whatever you expect to observe.
+     *
+     * The returned function removes just this listener and is safe to call twice.
+     * The connection stays open once the last listener leaves - {@link close}
+     * releases it - so a bus that subscribes and unsubscribes per request does not
+     * churn connections.
+     */
+    listen<TBody extends SerializableValue>(topic: string, listener: TopicListener<TBody>): Promise<() => Promise<void>>;
+    /**
+     * Build the automatic half of a message's metadata.
+     *
+     * Precedence, weakest first: machine/process context, then AppKit sender
+     * identity, then this bus's configured metadata. The caller's per-message
+     * metadata is layered over the result in {@link broadcast}, so the most specific
+     * source always wins and nothing here can overwrite an explicit key.
+     */
+    private resolveMetadata;
+    /**
+     * Release the notification connection and stop delivering messages. Idempotent.
+     *
+     * Cancels any pending reconnect, drops all listeners, then `UNLISTEN`s and
+     * returns the client to the pool. A failed `UNLISTEN` is reported to the pool as
+     * a release error so the connection is DISCARDED rather than handed to the next
+     * caller still subscribed to the channel. Does not throw; the bus stays closed.
+     */
+    close(): Promise<void>;
+    /**
+     * Check out one client, attach the handlers, and `LISTEN`.
+     *
+     * The handlers are attached BEFORE the `LISTEN` round trip so a notification or
+     * error arriving mid-setup is not missed. Any failure - including the bus being
+     * closed while the connect was in flight - detaches the handlers and releases
+     * the client as errored, so a half-configured connection never returns to the
+     * pool.
+     */
+    private connect;
+    /**
+     * Route one inbound notification to the topic's listeners.
+     *
+     * Ignores other channels and undecodable payloads - the channel is shared, so
+     * both are ordinary traffic. Listeners are invoked concurrently and their
+     * rejections go to `onError`, keeping one slow or broken subscriber from
+     * stalling the notification connection.
+     */
+    private readonly handleNotification;
+    /**
+     * Handle the notification connection dying, which `pg` reports as an `error`
+     * event rather than a rejected query.
+     *
+     * The client is unusable at this point, so it is detached and released as
+     * errored (which discards it) before anything else. Reconnection only starts
+     * when there is still someone to deliver to, so an idle or closing bus does not
+     * hold a connection open chasing a channel nobody reads.
+     */
+    private readonly handleClientError;
+    /**
+     * Re-establish the notification connection with bounded exponential backoff.
+     *
+     * The first attempt is immediate, since the common case is a single dropped
+     * connection that reconnects at once; subsequent delays double from 250ms up to
+     * 5s and stay there. Retries indefinitely rather than giving up, because a Postgres restart
+     * or a rotated Lakebase credential is a recoverable outage and a silently dead
+     * listener is worse than a noisy one. Stops when the bus closes or the last
+     * listener leaves, and reports every failed attempt through `onError`.
+     */
+    private reconnect;
+}
+export {};