@rebasepro/server-postgres 0.10.1-canary.ff9ccd6 → 0.10.1-canary.g4db1bb1

package/src/services/nested-path.ts

@@ -0,0 +1,145 @@
+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/realtimeService.ts

@@ -11,6 +11,7 @@ import { RealtimeProvider, CollectionSubscriptionConfig, SingleSubscriptionConfi
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
 import { buildPropertyCallbacks, getTableName } from "@rebasepro/common";
 import { applyAuthContext } from "../security/rls-enforcement";
+import { buildJunctionLinkMap, type JunctionLink } from "./cdc/junction-tables";
 import { logger } from "@rebasepro/server";
 import { sanitizeErrorForClient } from "../utils/pg-error-utils";
 import { CdcListener, type CdcChangeEvent } from "./cdc/CdcListener";
@@ -159,6 +160,9 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
     private cdcListener?: CdcListener;
     /** Whether database-level CDC is the active cross-instance change source. */
     private cdcActive = false;
+    /** Junction table → the child lists its rows belong to, built when CDC starts. */
+    private junctionLinkMap?: Map<string, JunctionLink[]>;
+
     /** Reverse lookup: `schema.table` (and bare `table`) → collection, built when CDC starts. */
     private cdcTableMap?: Map<string, CollectionConfig>;
     /**
@@ -1795,6 +1799,7 @@ lastSeen: Date.now() });
             return;
         }
         this.cdcTableMap = this.buildCdcTableMap();
+        this.junctionLinkMap = buildJunctionLinkMap(this.registry);
         this.cdcListener = new CdcListener(connectionString, (event) => this.handleCdcEvent(event));
         try {
             // start() validates the initial connection; if it can't be established
@@ -1805,6 +1810,7 @@ lastSeen: Date.now() });
             await this.cdcListener.stop().catch(() => { /* best effort */ });
             this.cdcListener = undefined;
             this.cdcTableMap = undefined;
+            this.junctionLinkMap = undefined;
             throw err;
         }
         this.cdcActive = true;
@@ -1822,6 +1828,7 @@ lastSeen: Date.now() });
             this.cdcListener = undefined;
         }
         this.cdcTableMap = undefined;
+        this.junctionLinkMap = undefined;
         this.recentAppEmits.clear();
     }
 
@@ -1862,6 +1869,10 @@ lastSeen: Date.now() });
     private async handleCdcEvent(event: CdcChangeEvent): Promise<void> {
         const collection = this.resolveCollectionForTable(event.schema, event.table);
         if (!collection) {
+            // A junction table backs no collection, but its rows *are* a child
+            // list. Route the change to the lists it changes before giving up.
+            if (await this.handleJunctionCdcEvent(event)) return;
+
             // Unmapped table (not backed by a collection) — nothing to deliver.
             this.debugLog(`📡 [CDC] Ignoring change on unmapped table ${event.schema}.${event.table}`);
             return;
@@ -1878,6 +1889,55 @@ lastSeen: Date.now() });
         await this.notifyUpdate(path, id, row, databaseId, /* broadcast */ false, /* origin */ "cdc");
     }
 
+    /**
+     * Deliver a change on a many-to-many junction table as a change to the child
+     * lists it belongs to.
+     *
+     * Linking a tag to a post writes only `posts_tags`. That table backs no
+     * collection, so change capture dropped the event as unmapped and the
+     * subscribers of `posts/1/tags` never heard about it — every other write in
+     * the system was realtime, and this one silently was not. The junction row
+     * carries both ids, so it names its own paths exactly.
+     *
+     * Notifies the nested path rather than either endpoint collection, because
+     * invalidation walks *parent* paths and never child ones: telling `tags` it
+     * changed would not reach a subscription on `posts/1/tags`.
+     *
+     * Returns whether the table was recognised as a junction.
+     */
+    private async handleJunctionCdcEvent(event: CdcChangeEvent): Promise<boolean> {
+        const links = this.junctionLinkMap?.get(`${event.schema}.${event.table}`)
+            ?? this.junctionLinkMap?.get(event.table);
+        if (!links?.length) return false;
+
+        for (const link of links) {
+            const sourceId = event.row?.[link.sourceColumn];
+            const targetId = event.row?.[link.targetColumn];
+            if (sourceId === undefined || sourceId === null || targetId === undefined || targetId === null) {
+                this.debugLog(
+                    `📡 [CDC] Junction row on ${event.table} is missing '${link.sourceColumn}'/'${link.targetColumn}' — skipping.`
+                );
+                continue;
+            }
+
+            const path = `${link.parentCollection.slug}/${String(sourceId)}/${link.relationKey}`;
+            // An unlink removes the target from this list; a link invalidates it
+            // so each subscriber refetches under its own RLS context.
+            const row = event.op === "DELETE" ? null : { _rebase_invalidated: true };
+
+            await this.notifyUpdate(
+                path,
+                String(targetId),
+                row,
+                (link.parentCollection as { databaseId?: string }).databaseId,
+                /* broadcast */ false,
+                /* origin */ "cdc"
+            );
+        }
+
+        return true;
+    }
+
     /** Compute the canonical (possibly composite) id string from a captured row. */
     private extractIdFromCdcRow(collection: CollectionConfig, row: Record<string, unknown>): string {
         // Unaddressable falls back to a collection-level invalidation: single-row

package/src/services/row-pipeline.ts

@@ -1,4 +1,4 @@
-import { CollectionConfig, Property, Relation } from "@rebasepro/types";
+import { CollectionConfig, Property, ResolvedRelation, isManyToMany, type ResolvedVia } from "@rebasepro/types";
 import { resolveCollectionRelations, findRelation, createRelationRefWithData } from "@rebasepro/common";
 import { normalizeDbValues } from "../data-transformer";
 import { deriveRowAddress } from "./collection-helpers";
@@ -31,12 +31,11 @@ export type RelationStyle = "ref" | "inline";
  * the query has to nest one level deeper for a junction, and the row walk has
  * to unwrap that same level back out.
  */
-export function isJunctionRelation(relation: Relation): boolean {
+export function isJunctionRelation(relation: ResolvedRelation): boolean {
     // An explicit `through` says so outright.
-    if (relation.through) return true;
-    // A joinPath with an intermediate table is the same thing, spelled longhand.
-    if (relation.joinPath && relation.joinPath.length > 1) return true;
-    return false;
+    if (isManyToMany(relation)) return true;
+    // A multi-hop join path is the same thing spelled longhand.
+    return relation.kind === "via" && relation.joinPath.length > 1;
 }
 
 /**