@rebasepro/server-postgres 0.10.1-canary.a54c057 → 0.10.1-canary.af2af91

package/src/services/nested-path.ts

@@ -0,0 +1,130 @@
+import { CollectionConfig, Relation } from "@rebasepro/types";
+import { findRelation, resolveCollectionRelations } from "@rebasepro/common";
+import { ApiError } from "@rebasepro/server";
+
+import { getCollectionByPath } from "./collection-helpers";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+
+/**
+ * The last hop of a nested collection path, e.g. `authors/1/posts`.
+ *
+ * The walk that produces this was written out four separate times — in
+ * `FetchService.fetchCollectionFromPath`, `FetchService.countEntitiesFromPath`,
+ * `PersistService.save` and `CollectionRegistry.getCollectionByPath` — and had
+ * drifted, so the read path and the write path did not agree on which relation
+ * a path named. It lives here once now.
+ */
+export interface NestedPathHop {
+    /** The collection the final relation is declared on (e.g. `authors`). */
+    parentCollection: CollectionConfig;
+    /** The parent's id as it appeared in the path, unparsed. */
+    parentId: string;
+    /** The path segment that named the relation (e.g. `posts`). */
+    relationKey: string;
+    relation: Relation;
+    /** `relation.target()`, resolved once. */
+    targetCollection: CollectionConfig;
+}
+
+/**
+ * True when `path` addresses rows through a relation rather than a root
+ * collection.
+ *
+ * Any separator at all counts — a root collection slug never contains one — so
+ * a malformed path like `collection/id` is a *broken* nested path and gets
+ * reported as one by {@link resolveNestedPath}, rather than being looked up as
+ * a root collection whose slug happens to contain a slash.
+ */
+export function isNestedPath(path: string): boolean {
+    return path.includes("/");
+}
+
+export function splitPathSegments(path: string): string[] {
+    return path.split("/").filter(s => s && s !== "undefined");
+}
+
+/**
+ * Walk a nested collection path down to the relation it ends in.
+ *
+ * Returns `undefined` for a plain root-collection path so callers can keep the
+ * root case on its existing code path. Throws when the path is malformed, or
+ * when a segment names a relation that does not exist — the same errors the
+ * individual walks used to raise, with the available names attached.
+ */
+export function resolveNestedPath(
+    path: string,
+    registry: PostgresCollectionRegistry
+): NestedPathHop | undefined {
+    if (!isNestedPath(path)) return undefined;
+
+    const segments = splitPathSegments(path);
+    if (segments.length < 3 || segments.length % 2 === 0) {
+        throw new Error(`Invalid relation path: ${path}. Expected format: collection/id/relation`);
+    }
+
+    let parentCollection = getCollectionByPath(segments[0], registry);
+    let parentId = segments[1];
+
+    for (let i = 2; i < segments.length; i += 2) {
+        const relationKey = segments[i];
+        const resolvedRelations = resolveCollectionRelations(parentCollection);
+        const relation = findRelation(resolvedRelations, relationKey);
+
+        if (!relation) {
+            const available = Object.keys(resolvedRelations).join(", ") || "(none)";
+            throw new Error(
+                `Relation '${relationKey}' not found in collection '${parentCollection.slug}'. Available relations: [${available}]`
+            );
+        }
+
+        const targetCollection = relation.target();
+
+        if (i === segments.length - 1) {
+            return {
+                parentCollection,
+                parentId,
+                relationKey,
+                relation,
+                targetCollection
+            };
+        }
+
+        parentCollection = targetCollection;
+        parentId = segments[i + 1];
+    }
+
+    // Unreachable: the loop returns on the final segment, and the odd-length
+    // check above guarantees there is one.
+    throw new Error(`Unable to resolve path: ${path}`);
+}
+
+/**
+ * A relation reached through a junction table — many-to-many, or a multi-hop
+ * `joinPath`. The target row is shared with other parents, so writing "through"
+ * such a path addresses the *link*, not the row.
+ */
+export function isJunctionBackedRelation(relation: Relation): boolean {
+    return Boolean(relation.through) || Boolean(relation.joinPath && relation.joinPath.length > 1);
+}
+
+/**
+ * Reject a nested write whose final segment is a to-one relation.
+ *
+ * There is no column on the target row that records a to-one parent — the
+ * foreign key lives on the *parent* table. The write path used to fall through
+ * to `relation.localKey` here and stamp the parent's own FK column onto the
+ * target row, which either raised an opaque "column does not exist" or, when a
+ * column of that name happened to exist on the target, silently wrote the wrong
+ * one.
+ */
+export function assertWritableThrough(hop: NestedPathHop, path: string): void {
+    if (hop.relation.cardinality !== "many") {
+        throw ApiError.badRequest(
+            `"${path}" ends in the to-one relation '${hop.relationKey}', which cannot be written through: ` +
+            `the foreign key for a to-one relation lives on '${hop.parentCollection.slug}', not on ` +
+            `'${hop.targetCollection.slug}'. Write the target row at "${hop.targetCollection.slug}" and set ` +
+            `'${hop.relationKey}' on the parent instead.`,
+            "RELATION_NOT_WRITABLE"
+        );
+    }
+}

package/src/services/pg-notify-listener.ts

@@ -0,0 +1,137 @@
+/**
+ * A dedicated, self-healing Postgres `LISTEN` connection.
+ *
+ * Every cross-instance feature in the backend needs the same thing: one
+ * connection *outside* the Drizzle pool that stays open, holds a `LISTEN`, and
+ * comes back on its own after the database or the network drops it. CDC needed
+ * it first; the channel bus needs it too. This is that connection, with the one
+ * behaviour that matters to callers preserved: the **first** connect is
+ * validated and rethrown, so a caller can fall back to a different strategy,
+ * while every later drop is repaired quietly in the background.
+ *
+ * `LISTEN` is session state, so this connection must not go through a
+ * transaction-mode pooler (PgBouncer): give it the direct database URL.
+ */
+
+import { Client as PgClient } from "pg";
+import { logger } from "@rebasepro/server";
+
+export interface PgNotifyListenerOptions {
+    /** Direct Postgres connection string (must bypass a transaction-mode pooler). */
+    connectionString: string;
+    /** NOTIFY channel to LISTEN on. Must be a plain identifier — it is interpolated. */
+    channel: string;
+    /** Called for every notification payload received. */
+    onPayload: (payload: string) => void | Promise<void>;
+    /** Prefix for log lines, e.g. `"[CDC]"`. */
+    logLabel: string;
+    /** Delay before a reconnect attempt. */
+    reconnectDelayMs?: number;
+}
+
+const DEFAULT_RECONNECT_DELAY_MS = 3000;
+/** Guards the identifier interpolated into `LISTEN`. */
+const SAFE_CHANNEL = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export class PgNotifyListener {
+    private client?: PgClient;
+    private running = false;
+    private reconnectTimer?: ReturnType<typeof setTimeout>;
+
+    constructor(private readonly options: PgNotifyListenerOptions) {
+        if (!SAFE_CHANNEL.test(options.channel)) {
+            throw new Error(`Unsafe NOTIFY channel name "${options.channel}" — expected a plain SQL identifier.`);
+        }
+    }
+
+    /** Whether the listener is meant to be connected right now. */
+    get active(): boolean {
+        return this.running;
+    }
+
+    /**
+     * Connect and begin listening. Idempotent.
+     *
+     * Rejects if the *initial* connection or `LISTEN` fails, leaving the
+     * listener stopped — callers use that to degrade deliberately instead of
+     * running blind against a channel nothing is delivering.
+     */
+    async start(): Promise<void> {
+        if (this.running) return;
+        this.running = true;
+        try {
+            await this.connect({ initial: true });
+        } catch (err) {
+            this.running = false;
+            throw err;
+        }
+    }
+
+    /** Stop listening and release the connection. Idempotent. */
+    async stop(): Promise<void> {
+        this.running = false;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+        if (this.client) {
+            try {
+                await this.client.end();
+            } catch { /* ignore close errors */ }
+            this.client = undefined;
+        }
+    }
+
+    private async connect({ initial = false }: { initial?: boolean } = {}): Promise<void> {
+        const { connectionString, channel, onPayload, logLabel } = this.options;
+        try {
+            const client = new PgClient({ connectionString });
+
+            client.on("error", (err) => {
+                logger.error(`❌ ${logLabel} LISTEN client error`, { detail: err.message });
+                this.scheduleReconnect();
+            });
+
+            client.on("end", () => {
+                if (this.running) {
+                    logger.warn(`⚠️ ${logLabel} LISTEN client disconnected unexpectedly.`);
+                    this.scheduleReconnect();
+                }
+            });
+
+            client.on("notification", (msg) => {
+                if (!msg.payload) return;
+                // A handler rejection must never surface as an unhandled
+                // rejection inside the pg client's event emitter.
+                Promise.resolve(onPayload(msg.payload)).catch((err) =>
+                    logger.error(`❌ ${logLabel} Error handling notification`, { error: err })
+                );
+            });
+
+            await client.connect();
+            await client.query(`LISTEN ${channel}`);
+            this.client = client;
+            logger.info(`📡 ${logLabel} Listening on channel "${channel}".`);
+        } catch (err) {
+            // Surface the initial failure so callers can choose to fall back;
+            // for reconnects, keep retrying quietly in the background.
+            if (initial) throw err;
+            logger.error(`❌ ${logLabel} Failed to connect LISTEN client`, { error: err });
+            this.scheduleReconnect();
+        }
+    }
+
+    private scheduleReconnect(): void {
+        if (!this.running || this.reconnectTimer) return;
+
+        this.reconnectTimer = setTimeout(async () => {
+            this.reconnectTimer = undefined;
+            if (!this.running) return;
+            if (this.client) {
+                try { await this.client.end(); } catch { /* ignore */ }
+                this.client = undefined;
+            }
+            await this.connect();
+        }, this.options.reconnectDelayMs ?? DEFAULT_RECONNECT_DELAY_MS);
+    }
+}