@webda/postgres 4.0.0-beta.1 → 4.0.0-beta.3

package/README.md

@@ -0,0 +1,125 @@
+# @webda/postgres module
+
+This module is part of Webda Application Framework that allows you to quickly develop applications with all modern prerequisites: Security, Extensibility, GraphQL, REST, CloudNative [https://webda.io](https://webda.io)
+
+<img src="https://webda.io/images/webda.svg" width="128" />
+
+![CI](https://github.com/loopingz/webda.io/workflows/CI/badge.svg)
+
+[![Join the chat at https://gitter.im/loopingz/webda](https://badges.gitter.im/loopingz/webda.svg)](https://gitter.im/loopingz/webda?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![codecov](https://codecov.io/gh/loopingz/webda.io/branch/main/graph/badge.svg?token=8N9DNM3K3O)](https://codecov.io/gh/loopingz/webda.io)
+[![SonarCloud.io](https://sonarcloud.io/api/project_badges/measure?project=loopingz_webda.io&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=loopingz_webda.io)
+![CodeQL](https://github.com/loopingz/webda.io/workflows/CodeQL/badge.svg)
+
+<!-- README_HEADER -->
+
+# @webda/postgres
+
+> PostgreSQL-backed Store for Webda — persists model instances as JSONB rows in Postgres with automatic table creation, view generation, and full WebdaQL query support.
+
+## When to use it
+
+- You want a relational database backing store for Webda models with ACID guarantees.
+- You are already running PostgreSQL and want Webda models to live alongside existing tables.
+- You need to query across models using familiar SQL tooling while keeping the Webda model API.
+
+## Install
+
+```bash
+pnpm add @webda/postgres
+```
+
+## Configuration
+
+```json
+{
+  "services": {
+    "postStore": {
+      "type": "PostgresStore",
+      "model": "MyApp/Post",
+      "postgresqlServer": {
+        "host": "localhost",
+        "port": 5432,
+        "database": "myapp",
+        "user": "webda",
+        "password": "${POSTGRES_PASSWORD}"
+      },
+      "autoCreateTable": true
+    }
+  }
+}
+```
+
+Or rely on libpq environment variables (`PGHOST`, `PGPORT`, `PGDATABASE`, `PGUSER`, `PGPASSWORD`):
+
+```json
+{
+  "services": {
+    "postStore": {
+      "type": "PostgresStore",
+      "model": "MyApp/Post",
+      "autoCreateTable": true
+    }
+  }
+}
+```
+
+| Parameter | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `postgresqlServer` | `ClientConfig` \| `PoolConfig` | libpq env vars | No | PostgreSQL connection config (host, port, database, user, password) |
+| `usePool` | boolean | `false` | No | Use a connection pool (`pg.Pool`) instead of a single client |
+| `autoCreateTable` | boolean | `true` | No | Automatically create the JSONB table if it does not exist |
+| `viewPrefix` | string | `""` | No | Prefix for auto-generated SQL views |
+| `views` | string[] | `["regex:.*"]` | No | Regexp list of model names to generate views for |
+
+## Usage
+
+```typescript
+import { CoreModel, Model, Expose } from "@webda/core";
+
+@Model()
+export class Post extends CoreModel {
+  @Expose() title: string;
+  @Expose() content: string;
+  @Expose() publishedAt: Date;
+}
+
+// With PostgresStore configured, the standard Webda model API is backed by Postgres:
+const post = new Post();
+post.title = "Hello Postgres";
+await post.save();                               // INSERT INTO posts ...
+
+const found = await Post.ref(post.uuid).get();  // SELECT ... WHERE uuid = ?
+const results = await Post.query("title CONTAINS 'Hello'"); // filtered query
+
+// The table schema uses JSONB:
+//   CREATE TABLE IF NOT EXISTS posts (
+//     uuid TEXT PRIMARY KEY,
+//     data JSONB NOT NULL
+//   );
+```
+
+## Reference
+
+- API reference: see the auto-generated typedoc at `docs/pages/Modules/postgres/`.
+- Source: [`packages/postgres`](https://github.com/loopingz/webda.io/tree/main/packages/postgres)
+- Related: [`@webda/mongodb`](../mongodb) for a document-store alternative; [`@webda/aws`](../aws) for `DynamoStore`; [`@webda/core`](../core) for the `Store` base class.
+
+<!-- README_FOOTER -->
+## Sponsors
+
+<!--
+Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor](mailto:sponsor@webda.io)
+-->
+
+Arize AI is a machine learning observability and model monitoring platform. It helps you visualize, monitor, and explain your machine learning models. [Learn more](https://arize.com)
+
+[<img src="https://arize.com/hubfs/arize/brand/arize-logomark-1.png" width="200">](https://arize.com)
+
+Loopingz is a software development company that provides consulting and development services. [Learn more](https://loopingz.com)
+
+[<img src="https://loopingz.com/images/logo.png" width="200">](https://loopingz.com)
+
+Tellae is an innovative consulting firm specialized in cities transportation issues. We provide our clients, both public and private, with solutions to support your strategic and operational decisions. [Learn more](https://tellae.fr)
+
+[<img src="https://tellae.fr/" width="200">](https://tellae.fr)

package/lib/index.d.ts

@@ -1,2 +1,5 @@
-export * from "./postgresstore.js";
+export * from "./postgrespubsub.service.js";
+export * from "./postgresqueue.service.js";
+export * from "./postgresstore.service.js";
 export * from "./sqlstore.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC"}

package/lib/index.js

@@ -1,3 +1,5 @@
-export * from "./postgresstore.js";
+export * from "./postgrespubsub.service.js";
+export * from "./postgresqueue.service.js";
+export * from "./postgresstore.service.js";
 export * from "./sqlstore.js";
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC"}

package/lib/pgpool.d.ts

@@ -0,0 +1,40 @@
+import pg, { PoolConfig } from "pg";
+/**
+ * Build the registry key for a config. Exposed for tests.
+ *
+ * @param config - the pg pool config (may be undefined — pg falls back to PG* env)
+ * @returns the registry key
+ */
+export declare function poolKey(config: PoolConfig | undefined): string;
+/**
+ * Acquire a shared `pg.Pool` for the given config. Pools are cached by
+ * stable config-hash; callers that pass the same config (regardless of
+ * key order) get the same pool back. Each `acquirePool` increments a
+ * refcount; the pool is `end()`ed when the last consumer calls
+ * {@link releasePool}.
+ *
+ * Use this for stateless workloads (queries, queue receive, pub/sub
+ * publish). LISTEN must use a dedicated `pg.Client` because the
+ * subscription is bound to a single connection — pooled connections
+ * rotate and would silently drop the subscription.
+ *
+ * @param config - the pg pool config
+ * @returns the shared pool
+ */
+export declare function acquirePool(config: PoolConfig | undefined): pg.Pool;
+/**
+ * Release a previously-acquired pool. When the refcount reaches zero,
+ * the pool is `end()`ed and removed from the registry. Releasing a
+ * config that was never acquired (or already drained) is a no-op so
+ * `stop()` paths can call this unconditionally.
+ *
+ * @param config - the same config that was passed to {@link acquirePool}
+ * @returns a promise that resolves once the pool has been ended (or immediately if still in use / unknown)
+ */
+export declare function releasePool(config: PoolConfig | undefined): Promise<void>;
+/**
+ * Test-only: drain and forget every shared pool. Used between specs to
+ * keep the registry from leaking handles across files.
+ */
+export declare function __resetPools(): Promise<void>;
+//# sourceMappingURL=pgpool.d.ts.map

package/lib/pgpool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pgpool.d.ts","sourceRoot":"","sources":["../src/pgpool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAyCpC;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,EAAE,CAAC,IAAI,CAUnE;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAU/E;AAED;;;GAGG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAUlD"}

package/lib/pgpool.js

@@ -0,0 +1,101 @@
+import pg from "pg";
+/**
+ * Stable JSON serializer that sorts object keys so two configs with the
+ * same content but different key order hash to the same registry key.
+ *
+ * Functions and classes (e.g. `pg.Pool` custom types) are dropped — pools
+ * configured with non-serializable hooks must be created directly.
+ *
+ * @param value - any JSON-serializable value
+ * @returns a stable string representation
+ */
+function stableStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return "[" + value.map(stableStringify).join(",") + "]";
+    }
+    const keys = Object.keys(value).sort();
+    return ("{" +
+        keys
+            .map(k => {
+            const v = value[k];
+            if (typeof v === "function")
+                return undefined;
+            return JSON.stringify(k) + ":" + stableStringify(v);
+        })
+            .filter(s => s !== undefined)
+            .join(",") +
+        "}");
+}
+const registry = new Map();
+/**
+ * Build the registry key for a config. Exposed for tests.
+ *
+ * @param config - the pg pool config (may be undefined — pg falls back to PG* env)
+ * @returns the registry key
+ */
+export function poolKey(config) {
+    return stableStringify(config ?? {});
+}
+/**
+ * Acquire a shared `pg.Pool` for the given config. Pools are cached by
+ * stable config-hash; callers that pass the same config (regardless of
+ * key order) get the same pool back. Each `acquirePool` increments a
+ * refcount; the pool is `end()`ed when the last consumer calls
+ * {@link releasePool}.
+ *
+ * Use this for stateless workloads (queries, queue receive, pub/sub
+ * publish). LISTEN must use a dedicated `pg.Client` because the
+ * subscription is bound to a single connection — pooled connections
+ * rotate and would silently drop the subscription.
+ *
+ * @param config - the pg pool config
+ * @returns the shared pool
+ */
+export function acquirePool(config) {
+    const key = poolKey(config);
+    const entry = registry.get(key);
+    if (entry) {
+        entry.refCount++;
+        return entry.pool;
+    }
+    const pool = new pg.Pool(config);
+    registry.set(key, { pool, refCount: 1 });
+    return pool;
+}
+/**
+ * Release a previously-acquired pool. When the refcount reaches zero,
+ * the pool is `end()`ed and removed from the registry. Releasing a
+ * config that was never acquired (or already drained) is a no-op so
+ * `stop()` paths can call this unconditionally.
+ *
+ * @param config - the same config that was passed to {@link acquirePool}
+ * @returns a promise that resolves once the pool has been ended (or immediately if still in use / unknown)
+ */
+export async function releasePool(config) {
+    const key = poolKey(config);
+    const entry = registry.get(key);
+    if (!entry)
+        return;
+    entry.refCount--;
+    if (entry.refCount > 0)
+        return;
+    registry.delete(key);
+    await entry.pool.end().catch(() => {
+        /* already ended */
+    });
+}
+/**
+ * Test-only: drain and forget every shared pool. Used between specs to
+ * keep the registry from leaking handles across files.
+ */
+export async function __resetPools() {
+    const entries = [...registry.values()];
+    registry.clear();
+    await Promise.all(entries.map(e => e.pool.end().catch(() => {
+        /* already ended */
+    })));
+}
+//# sourceMappingURL=pgpool.js.map

package/lib/pgpool.js.map

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

package/lib/postgrespubsub.service.d.ts

@@ -0,0 +1,131 @@
+import { PubSubService, ServiceParameters } from "@webda/core";
+import { CancelablePromise } from "@webda/utils";
+import pg, { ClientConfig } from "pg";
+/**
+ * Configuration for {@link PostgresPubSubService}.
+ */
+export declare class PostgresPubSubParameters extends ServiceParameters {
+    /**
+     * Channel name passed to LISTEN / NOTIFY. Must be a valid Postgres
+     * identifier (lowercased, no quoting). Defaults to the service name.
+     * @pattern /^[a-z_][a-z0-9_]*$/
+     * @example "myapp_events"
+     * @example "user_notifications"
+     * @example "cache_invalidation"
+     * @example "orders"
+     */
+    channel?: string;
+    /**
+     * Connection settings forwarded to `pg.Client`. By default `pg` reads
+     * standard PG* environment variables.
+     */
+    postgresqlServer?: ClientConfig;
+    /**
+     * Reconnect delay in milliseconds when the LISTEN connection drops. A
+     * randomized jitter is added to keep crash-loop reconnects from
+     * stampeding.
+     *
+     * @default 500
+     */
+    reconnectDelay?: number;
+    /**
+     * @override
+     * @param params - the input parameters
+     * @returns this
+     */
+    load(params?: any): this;
+}
+interface Subscriber<T> {
+    callback: (event: T) => Promise<void>;
+    proto?: {
+        new (): T;
+    };
+}
+/**
+ * Pub/sub backed by Postgres' native LISTEN / NOTIFY. A long-lived
+ * `pg.Client` (NOT a pool — pools rotate connections, but each LISTEN is
+ * scoped to the connection that issued it) holds the subscription;
+ * publishes go through `pg_notify(channel, payload)`. The 8 kB NOTIFY
+ * payload cap is enforced in {@link sendMessage} — for larger payloads,
+ * stash them in a row and notify the row id.
+ *
+ * Disconnects trigger a randomized-backoff reconnect so the listener
+ * survives transient network or restart blips.
+ *
+ * @WebdaModda PostgresPubSub
+ */
+export default class PostgresPubSubService<T = any, K extends PostgresPubSubParameters = PostgresPubSubParameters> extends PubSubService<T, K> {
+    /**
+     * Long-lived listener client. One per service instance because LISTEN is
+     * scoped to the connection that issued it — a pool would silently rotate
+     * and drop the subscription.
+     */
+    protected client?: pg.Client;
+    /**
+     * Shared pool used for the publish side (`pg_notify`). Acquired from
+     * the per-config pool registry so multiple services that target the
+     * same database share connections instead of each spinning up their
+     * own pool. Subscribe-only services skip this and never publish.
+     */
+    protected publishPool?: pg.Pool;
+    /**
+     * Local callback registrations. Notifications dispatch to all of them.
+     */
+    protected callbacks: Set<Subscriber<T>>;
+    /**
+     * Set during {@link stop} so reconnect handlers don't try to come back
+     * after teardown.
+     */
+    protected stopping: boolean;
+    /**
+     * Channel name used for LISTEN/NOTIFY. Resolved at init time so we can
+     * default to the service's name when not configured.
+     * @returns the channel name
+     */
+    protected channel(): string;
+    /**
+     * @override
+     * @returns this service
+     */
+    init(): Promise<this>;
+    /**
+     * Open a fresh client, run LISTEN, and wire the notification handler.
+     */
+    protected connect(): Promise<void>;
+    /**
+     * Schedule a reconnect after a short randomized backoff.
+     */
+    protected handleDisconnect(): void;
+    /**
+     * Decode a notification payload and run every registered callback
+     * against it.
+     * @param payload - the raw NOTIFY payload string
+     */
+    protected dispatch(payload: string): void;
+    /**
+     * @override
+     * @param event - the event to publish
+     */
+    sendMessage(event: T): Promise<void>;
+    /**
+     * @override
+     * @returns 0 — pub/sub is transient, no queueing
+     */
+    size(): Promise<number>;
+    /**
+     * @override
+     * @param callback - invoked with each event received
+     * @param eventPrototype - optional class to rehydrate JSON into
+     * @param onBind - invoked once the subscription is registered
+     * @returns a cancelable subscription handle
+     */
+    consume(callback: (event: T) => Promise<void>, eventPrototype?: {
+        new (): T;
+    }, onBind?: () => void): CancelablePromise;
+    /**
+     * @override
+     */
+    stop(): Promise<void>;
+}
+export { PostgresPubSubService };
+//# sourceMappingURL=postgrespubsub.service.d.ts.map

package/lib/postgrespubsub.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgrespubsub.service.d.ts","sourceRoot":"","sources":["../src/postgrespubsub.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAa,MAAM,cAAc,CAAC;AAE5D,OAAO,EAAE,EAAE,EAAE,YAAY,EAAc,MAAM,IAAI,CAAC;AAUlD;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,iBAAiB;IAC7D;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,YAAY,CAAC;IAChC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,IAAI,CAAC,MAAM,GAAE,GAAQ,GAAG,IAAI,CAI3B;CACF;AAED,UAAU,UAAU,CAAC,CAAC;IACpB,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,CAAA;KAAE,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,OAAO,OAAO,qBAAqB,CACxC,CAAC,GAAG,GAAG,EACP,CAAC,SAAS,wBAAwB,GAAG,wBAAwB,CAC7D,SAAQ,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC;IAC3B;;;;OAIG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,SAAS,CAAC,WAAW,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC;IAChC;;OAEG;IACH,SAAS,CAAC,SAAS,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAa;IACpD;;;OAGG;IACH,SAAS,CAAC,QAAQ,UAAS;IAE3B;;;;OAIG;IACH,SAAS,CAAC,OAAO,IAAI,MAAM,CAE1B;IAED;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAI1B;IAED;;OAEG;IACH,UAAgB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAmBvC;IAED;;OAEG;IACH,SAAS,CAAC,gBAAgB,IAAI,IAAI,CAQjC;IAED;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAuBxC;IAED;;;OAGG;IACG,WAAW,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBzC;IAED;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAE5B;IAED;;;;;;OAMG;IACH,OAAO,CACL,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,EACrC,cAAc,CAAC,EAAE;QAAE,QAAQ,CAAC,CAAA;KAAE,EAC9B,MAAM,CAAC,EAAE,MAAM,IAAI,GAClB,iBAAiB,CAUnB;IAED;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAoB1B;CACF;AAED,OAAO,EAAE,qBAAqB,EAAE,CAAC"}

package/lib/postgrespubsub.service.js

@@ -0,0 +1,208 @@
+import { PubSubService, ServiceParameters } from "@webda/core";
+import { CancelablePromise, JSONUtils } from "@webda/utils";
+import { useLog } from "@webda/workout";
+import pg from "pg";
+import { acquirePool, releasePool } from "./pgpool.js";
+/**
+ * NOTIFY's payload limit is 8000 bytes (the underlying NAMEDATALEN /
+ * NOTIFY_PAYLOAD_LIMIT). We keep a small safety margin to leave room for
+ * the protocol overhead.
+ */
+const NOTIFY_PAYLOAD_MAX = 7900;
+/**
+ * Configuration for {@link PostgresPubSubService}.
+ */
+export class PostgresPubSubParameters extends ServiceParameters {
+    /**
+     * @override
+     * @param params - the input parameters
+     * @returns this
+     */
+    load(params = {}) {
+        super.load(params);
+        this.reconnectDelay ?? (this.reconnectDelay = 500);
+        return this;
+    }
+}
+/**
+ * Pub/sub backed by Postgres' native LISTEN / NOTIFY. A long-lived
+ * `pg.Client` (NOT a pool — pools rotate connections, but each LISTEN is
+ * scoped to the connection that issued it) holds the subscription;
+ * publishes go through `pg_notify(channel, payload)`. The 8 kB NOTIFY
+ * payload cap is enforced in {@link sendMessage} — for larger payloads,
+ * stash them in a row and notify the row id.
+ *
+ * Disconnects trigger a randomized-backoff reconnect so the listener
+ * survives transient network or restart blips.
+ *
+ * @WebdaModda PostgresPubSub
+ */
+export default class PostgresPubSubService extends PubSubService {
+    constructor() {
+        super(...arguments);
+        /**
+         * Local callback registrations. Notifications dispatch to all of them.
+         */
+        this.callbacks = new Set();
+        /**
+         * Set during {@link stop} so reconnect handlers don't try to come back
+         * after teardown.
+         */
+        this.stopping = false;
+    }
+    /**
+     * Channel name used for LISTEN/NOTIFY. Resolved at init time so we can
+     * default to the service's name when not configured.
+     * @returns the channel name
+     */
+    channel() {
+        return this.parameters.channel ?? this.getName().toLowerCase();
+    }
+    /**
+     * @override
+     * @returns this service
+     */
+    async init() {
+        await super.init();
+        await this.connect();
+        return this;
+    }
+    /**
+     * Open a fresh client, run LISTEN, and wire the notification handler.
+     */
+    async connect() {
+        // Validate the channel name before opening any connection: LISTEN
+        // can't be parameterized so the channel name gets inlined into SQL,
+        // which makes it a query-injection vector. Failing fast here keeps
+        // the bad-input case independent of database reachability.
+        const ch = this.channel();
+        if (!/^[a-z_][a-z0-9_]*$/.test(ch)) {
+            throw new Error(`Invalid channel name "${ch}" — must match /^[a-z_][a-z0-9_]*$/`);
+        }
+        const client = new pg.Client(this.parameters.postgresqlServer);
+        client.on("notification", (msg) => {
+            if (msg.channel !== this.channel())
+                return;
+            this.dispatch(msg.payload ?? "");
+        });
+        client.on("error", err => useLog("WARN", `PostgresPubSub client error: ${err.message}`));
+        client.on("end", () => this.handleDisconnect());
+        await client.connect();
+        await client.query(`LISTEN ${ch}`);
+        this.client = client;
+    }
+    /**
+     * Schedule a reconnect after a short randomized backoff.
+     */
+    handleDisconnect() {
+        if (this.stopping)
+            return;
+        this.client = undefined;
+        const delay = this.parameters.reconnectDelay + Math.floor(Math.random() * 250);
+        setTimeout(() => {
+            if (this.stopping)
+                return;
+            this.connect().catch(err => useLog("WARN", `PostgresPubSub reconnect failed: ${err.message}`));
+        }, delay);
+    }
+    /**
+     * Decode a notification payload and run every registered callback
+     * against it.
+     * @param payload - the raw NOTIFY payload string
+     */
+    dispatch(payload) {
+        let raw;
+        try {
+            raw = payload === "" ? undefined : JSONUtils.parse(payload);
+        }
+        catch (err) {
+            this.metrics?.errors?.inc();
+            useLog("WARN", `PostgresPubSub invalid payload: ${err.message}`);
+            return;
+        }
+        this.metrics?.messages_received?.inc();
+        for (const sub of this.callbacks) {
+            const event = sub.proto && raw ? Object.assign(new sub.proto(), raw) : raw;
+            const start = Date.now();
+            sub
+                .callback(event)
+                .catch(err => {
+                this.metrics?.errors?.inc();
+                useLog("ERROR", `PostgresPubSub callback failed: ${err.message}`);
+            })
+                .finally(() => {
+                this.metrics?.processing_duration?.observe((Date.now() - start) / 1000);
+            });
+        }
+    }
+    /**
+     * @override
+     * @param event - the event to publish
+     */
+    async sendMessage(event) {
+        if (!this.client)
+            throw new Error("PostgresPubSub not connected");
+        const payload = JSONUtils.stringify(event);
+        if (Buffer.byteLength(payload, "utf-8") > NOTIFY_PAYLOAD_MAX) {
+            throw new Error(`PostgresPubSub payload exceeds Postgres' 8 kB NOTIFY limit. Stash large payloads in a row and notify the row id instead.`);
+        }
+        this.metrics?.messages_sent?.inc();
+        // Lazily acquire a shared publish pool: subscribe-only services never
+        // call sendMessage and so never pay the connection cost. Acquired
+        // pools are reference-counted in the registry, so multiple postgres
+        // services pointing at the same database share connections.
+        if (!this.publishPool) {
+            this.publishPool = acquirePool(this.parameters.postgresqlServer);
+        }
+        await this.publishPool.query("SELECT pg_notify($1, $2)", [this.channel(), payload]);
+    }
+    /**
+     * @override
+     * @returns 0 — pub/sub is transient, no queueing
+     */
+    async size() {
+        return 0;
+    }
+    /**
+     * @override
+     * @param callback - invoked with each event received
+     * @param eventPrototype - optional class to rehydrate JSON into
+     * @param onBind - invoked once the subscription is registered
+     * @returns a cancelable subscription handle
+     */
+    consume(callback, eventPrototype, onBind) {
+        const entry = { callback, proto: eventPrototype };
+        this.callbacks.add(entry);
+        onBind?.();
+        return new CancelablePromise(resolve => resolve(), async () => {
+            this.callbacks.delete(entry);
+        });
+    }
+    /**
+     * @override
+     */
+    async stop() {
+        this.stopping = true;
+        this.callbacks.clear();
+        if (this.client) {
+            const client = this.client;
+            this.client = undefined;
+            try {
+                await client.query(`UNLISTEN ${this.channel()}`);
+            }
+            catch {
+                /* connection may already be dead */
+            }
+            await client.end().catch(() => {
+                /* already ended */
+            });
+        }
+        if (this.publishPool) {
+            this.publishPool = undefined;
+            await releasePool(this.parameters.postgresqlServer);
+        }
+        await super.stop();
+    }
+}
+export { PostgresPubSubService };
+//# sourceMappingURL=postgrespubsub.service.js.map

package/lib/postgrespubsub.service.js.map

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