@rebasepro/server-postgres 0.17.3 → 0.18.0

package/src/services/junction-writes.ts

@@ -1,295 +0,0 @@
-import { and, eq, inArray, sql } from "drizzle-orm";
-import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
-import { ApiError, logger } from "@rebasepro/server";
-import type { ResolvedVia } from "@rebasepro/types";
-import { DrizzleClient } from "../interfaces";
-import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
-import { relationMisconfigured } from "./collection-helpers";
-import { explainZeroRowWrite } from "./write-denial";
-
-/**
- * Writing a many-to-many means writing rows in a junction table, and doing that
- * needs three things: the table, the column naming the row being written from,
- * and the column naming the far side.
- *
- * Those three used to be re-derived at each of the four call sites — twice for
- * `through`, twice for `joinPath`, in the owning and the inverse direction —
- * and the two `joinPath` derivations did not agree. The inverse one keyed off
- * `step.table`; the owning one asked `getTableNamesFromColumns` which table a
- * step's columns belonged to, and that answers `""` for an unqualified column
- * name. So for `{ table: "posts_tags", on: { from: "id", to: "tag_id" } }` —
- * the form the docs and every fixture use — no branch matched, both columns
- * stayed null, and the write was skipped with a warning nobody reads. Writing
- * a to-many `via` relation did nothing at all.
- *
- * Hence one binder, keyed on `step.table` (always present) and accepting the
- * qualified `table.column` form where it is used.
- */
-export interface JunctionBinding {
-    table: PgTable;
-    /** The junction column holding the id of the row being written from. */
-    parentColumn: AnyPgColumn;
-    /** The junction column holding the id of the row on the far side. */
-    targetColumn: AnyPgColumn;
-    /** `<collection>.<relation>`, for error messages. */
-    label: string;
-}
-
-/** A junction that cannot be resolved is a broken relation, not a no-op. */
-const misconfigured = (label: string, detail: string): ApiError =>
-    relationMisconfigured(label, detail);
-
-function column(table: PgTable, name: string | undefined, label: string, role: string): AnyPgColumn {
-    const col = name ? table[name as keyof typeof table] as AnyPgColumn : undefined;
-    if (!col) {
-        throw misconfigured(label, `no ${role} column '${name ?? "?"}' on the junction table`);
-    }
-    return col;
-}
-
-/** The junction a `manyToMany` names outright. */
-export function bindThroughJunction(
-    registry: PostgresCollectionRegistry,
-    through: { table: string; sourceColumn: string; targetColumn: string },
-    label: string
-): JunctionBinding {
-    const table = registry.getTable(through.table);
-    if (!table) {
-        throw misconfigured(label, `no table '${through.table}' in the registry`);
-    }
-    return {
-        table,
-        parentColumn: column(table, through.sourceColumn, label, "source"),
-        targetColumn: column(table, through.targetColumn, label, "target"),
-        label
-    };
-}
-
-/** The bare column name, whether written as `col` or `table.col`. */
-const columnPart = (spec: string | string[]): string => {
-    const one = Array.isArray(spec) ? spec[0] : spec;
-    return one.includes(".") ? one.split(".")[1] : one;
-};
-
-/** The table a column spec names, or undefined when it is unqualified. */
-const tablePart = (spec: string | string[]): string | undefined => {
-    const one = Array.isArray(spec) ? spec[0] : spec;
-    return one.includes(".") ? one.split(".")[0] : undefined;
-};
-
-/**
- * The junction a `via` relation reaches through, from either end.
- *
- * A step is `{ table: T, on: { from, to } }` where `from` names a column on
- * whatever the walk was standing on and `to` names one on `T`. That positional
- * meaning is what makes the unqualified form work at all, so the walk carries
- * the previous table rather than asking the column names where they live.
- */
-export function bindJoinPathJunction(
-    registry: PostgresCollectionRegistry,
-    joinPath: ResolvedVia["joinPath"],
-    parentTableName: string,
-    targetTableName: string,
-    label: string
-): JunctionBinding {
-    const junctionName = joinPath
-        .map(step => step.table)
-        .find(table => table !== parentTableName && table !== targetTableName);
-
-    if (!junctionName) {
-        throw misconfigured(label, "its joinPath has no table between the two ends to hold the links");
-    }
-
-    const table = registry.getTable(junctionName);
-    if (!table) {
-        throw misconfigured(label, `no table '${junctionName}' in the registry`);
-    }
-
-    let parentColumnName: string | undefined;
-    let targetColumnName: string | undefined;
-    let previousTable = parentTableName;
-
-    for (const step of joinPath) {
-        const fromTable = tablePart(step.on.from) ?? previousTable;
-        const toTable = tablePart(step.on.to) ?? step.table;
-
-        // Take the column on the junction's own side of the step, and let the
-        // other side say which end of the relation this step reached.
-        if (toTable === junctionName && fromTable === parentTableName) {
-            parentColumnName = columnPart(step.on.to);
-        } else if (fromTable === junctionName && toTable === parentTableName) {
-            parentColumnName = columnPart(step.on.from);
-        } else if (toTable === junctionName && fromTable === targetTableName) {
-            targetColumnName = columnPart(step.on.to);
-        } else if (fromTable === junctionName && toTable === targetTableName) {
-            targetColumnName = columnPart(step.on.from);
-        }
-
-        previousTable = step.table;
-    }
-
-    if (!parentColumnName || !targetColumnName) {
-        throw misconfigured(
-            label,
-            `its joinPath does not connect '${parentTableName}' and '${targetTableName}' through '${junctionName}'`
-        );
-    }
-
-    return {
-        table,
-        parentColumn: column(table, parentColumnName, label, "source"),
-        targetColumn: column(table, targetColumnName, label, "target"),
-        label
-    };
-}
-
-/**
- * Remove one link, leaving the row on the far side alone.
- *
- * This is what `DELETE authors/1/tags/5` has to mean for a many-to-many: the
- * target is shared, so deleting the row would remove the tag from every other
- * post that uses it.
- */
-export async function removeJunctionLink(
-    tx: DrizzleClient,
-    binding: JunctionBinding,
-    parentId: unknown,
-    targetId: unknown,
-    subject: { parent: string; relation: string }
-): Promise<void> {
-    const conditions = [
-        eq(binding.parentColumn, parentId),
-        eq(binding.targetColumn, targetId)
-    ];
-    const result = await tx.delete(binding.table).where(and(...conditions));
-
-    // The link is the row here, so the junction's own policies decide. Callers
-    // establish membership first, over this same handle, which is what makes a
-    // zero-row delete meaningful rather than ambiguous.
-    if ((result.rowCount ?? 0) === 0) {
-        throw await explainZeroRowWrite(
-            tx,
-            binding.table,
-            conditions,
-            `Not allowed to unlink "${targetId}" from "${subject.parent}" "${parentId}": ` +
-            "a row-level security policy rejected the write.",
-            `No "${subject.relation}" link between "${subject.parent}" "${parentId}" ` +
-            `and "${targetId}" to remove.`
-        );
-    }
-
-    logger.info(`Unlinked '${subject.relation}' ${targetId} from ${subject.parent} ${parentId}`);
-}
-
-/**
- * Make the junction say that `parentId` is linked to exactly `targetIds`, by
- * diffing against what is linked now rather than replacing the set.
- *
- * A save of the parent used to delete every junction row for it and re-insert
- * the ids the browser sent — a list the browser assembled from a read it did
- * earlier. Three things followed, all data loss rather than display:
- *
- *  - **Lost update.** Two editors with post 7 open: A adds tag X and saves, B
- *    saves any field from a form that predates it, and X is gone with nothing
- *    reported to either of them.
- *  - **A partially-read set is a partially-deleted set.** The read that fills
- *    the form runs under RLS, so a user who may edit the parent but cannot see
- *    some of the linked rows gets a shorter list — and writing it back deleted
- *    the links they were never shown. The select that drives the diff runs in
- *    this same transaction under the same policies, so a link the caller cannot
- *    read is in neither list and survives the save.
- *  - **Junction payload columns.** A junction carrying its own columns
- *    (`position`, `role`, `created_at`) lost them on every save, because every
- *    row was re-inserted with only the two keys. Untouched links are left alone.
- *
- * The insert is `ON CONFLICT DO NOTHING`, so two sessions adding the same link
- * concurrently is a no-op rather than a unique violation.
- */
-export async function applyJunctionMembership(
-    tx: DrizzleClient,
-    binding: JunctionBinding,
-    parentId: unknown,
-    targetIds: unknown[]
-): Promise<void> {
-    const existingRows = await tx
-        .select({ targetId: binding.targetColumn })
-        .from(binding.table)
-        .where(eq(binding.parentColumn, parentId));
-
-    // Keyed by `String(...)` because a junction key can come back from the
-    // driver as a string where the parsed value is a number, and a diff that
-    // missed that would delete and re-insert every link on every save.
-    const existingById = new Map<string, unknown>();
-    for (const row of existingRows as Array<{ targetId: unknown }>) {
-        if (row.targetId === null || row.targetId === undefined) continue;
-        existingById.set(String(row.targetId), row.targetId);
-    }
-
-    const wantedById = new Map<string, unknown>();
-    for (const targetId of targetIds) {
-        if (targetId === null || targetId === undefined) continue;
-        wantedById.set(String(targetId), targetId);
-    }
-
-    const removed = [...existingById.entries()]
-        .filter(([key]) => !wantedById.has(key))
-        .map(([, value]) => value);
-    const added = [...wantedById.entries()]
-        .filter(([key]) => !existingById.has(key))
-        .map(([, value]) => value);
-
-    if (removed.length > 0) {
-        await removeLinks(tx, binding, parentId, removed);
-    }
-
-    if (added.length > 0) {
-        await tx.insert(binding.table)
-            .values(added.map(targetId => ({
-                [binding.parentColumn.name]: parentId,
-                [binding.targetColumn.name]: targetId
-            })))
-            .onConflictDoNothing();
-    }
-}
-
-/**
- * Drop the named links, and refuse to call it done if the database kept any.
- *
- * Every id here came out of the select in {@link applyJunctionMembership}, on
- * this same handle, so all of them were visible. Fewer deletions than that means
- * something refused them — and a save that reports success while the membership
- * it stored is not the membership it was given has told the caller something
- * untrue about the database.
- */
-async function removeLinks(
-    tx: DrizzleClient,
-    binding: JunctionBinding,
-    parentId: unknown,
-    removed: unknown[]
-): Promise<void> {
-    const conditions = [
-        eq(binding.parentColumn, parentId),
-        inArray(binding.targetColumn, removed)
-    ];
-    const result = await tx.delete(binding.table).where(and(...conditions));
-    const deleted = result.rowCount ?? 0;
-
-    if (deleted >= removed.length) return;
-
-    const survivors = await tx
-        .select({ present: sql<number>`1` })
-        .from(binding.table)
-        .where(and(...conditions))
-        .limit(1);
-
-    // Nothing survived: a concurrent session removed the rest between the
-    // select and the delete. The membership is what the caller asked for,
-    // which is all this promised.
-    if (survivors.length === 0) return;
-
-    throw ApiError.forbidden(
-        `Not allowed to remove ${removed.length - deleted} of ${removed.length} link(s) ` +
-        `for relation '${binding.label}': a row-level security policy rejected the write.`,
-        "WRITE_DENIED"
-    );
-}

package/src/services/nested-path.ts

@@ -1,145 +0,0 @@
-import { CollectionConfig, ResolvedRelation } 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: ResolvedRelation;
-    /** `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: ResolvedRelation): boolean {
-    return relation.shared;
-}
-
-/**
- * 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 {
-    const { relation } = hop;
-
-    // Read the flag rather than re-deriving the rule. This guard used to test
-    // `cardinality !== "many"`, which let a to-many `via` through even though
-    // its type declares `writable: false` — a second expression of one rule,
-    // free to disagree with the first, which is the shape of defect this union
-    // exists to remove.
-    if (relation.writable && relation.cardinality === "many") return;
-
-    if (!relation.writable) {
-        throw ApiError.badRequest(
-            `"${path}" ends in '${hop.relationKey}', a \`via\` relation. Rebase will not infer how to write ` +
-            `through an arbitrary join chain — write the row at "${hop.targetCollection.slug}" directly.`,
-            "RELATION_NOT_WRITABLE"
-        );
-    }
-
-    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

@@ -1,151 +0,0 @@
-/**
- * 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;
-        // Held here rather than only inside the `try` so the failure path can
-        // still reach it: everything below `connect()` can throw, and until
-        // `this.client` is assigned nothing else in this class knows the
-        // connection exists. Left unreleased it stays open on the server while
-        // `scheduleReconnect` opens another — one leaked backend per attempt,
-        // every few seconds, for as long as the failure lasts.
-        let pending: PgClient | undefined;
-        try {
-            const client = new PgClient({ connectionString });
-            pending = client;
-
-            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;
-            // Adopted: `stop()` and `scheduleReconnect` will close it now.
-            pending = undefined;
-            logger.debug(`📡 ${logLabel} Listening on channel "${channel}".`);
-        } catch (err) {
-            // Never adopted, so nothing else will ever close it.
-            if (pending) {
-                try { await pending.end(); } catch { /* already dead */ }
-            }
-            // 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);
-    }
-}