@rebasepro/server-postgres 0.9.1-canary.1d2d8b5 → 0.9.1-canary.58368ce

package/src/services/collection-helpers.ts

@@ -2,6 +2,15 @@ import { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
 import { CollectionConfig, Property } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
 import { getTableName } from "@rebasepro/common";
+import { logger } from "@rebasepro/server";
+
+// Row identity is derived on both sides of the wire — the driver parses an
+// incoming address into key columns, the admin derives one from a served row —
+// so the implementation lives in `common` and both agree by construction.
+export { buildCompositeId, parseIdValues, COMPOSITE_ID_SEPARATOR } from "@rebasepro/common";
+export type { PrimaryKeyInfo } from "@rebasepro/common";
+import { buildCompositeId, COMPOSITE_ID_SEPARATOR, getDeclaredPrimaryKeys } from "@rebasepro/common";
+import type { PrimaryKeyInfo } from "@rebasepro/common";
 
 /**
  * Shared helper functions for row operations.
@@ -49,7 +58,7 @@ export function getTableForCollection(collection: CollectionConfig, registry: Po
     return table;
 }
 
-export function getPrimaryKeys(collection: CollectionConfig, registry: PostgresCollectionRegistry): { fieldName: string; type: "string" | "number"; isUUID?: boolean }[] {
+export function getPrimaryKeys(collection: CollectionConfig, registry: PostgresCollectionRegistry): PrimaryKeyInfo[] {
     const table = getTableForCollection(collection, registry);
 
     // Fallback to explicitly defined isId properties
@@ -68,7 +77,7 @@ export function getPrimaryKeys(collection: CollectionConfig, registry: PostgresC
     }
 
     // Otherwise infer from Drizzle schema
-    const keys: { fieldName: string; type: "string" | "number"; isUUID?: boolean }[] = [];
+    const keys: PrimaryKeyInfo[] = [];
     for (const [key, colRaw] of Object.entries(table)) {
         const col = colRaw as AnyPgColumn;
         if (col && typeof col === "object" && "primary" in col && col.primary) {
@@ -96,56 +105,132 @@ isUUID });
     return keys;
 }
 
-export function parseIdValues(idValue: string | number, primaryKeys: { fieldName: string; type: "string" | "number"; isUUID?: boolean }[]): Record<string, string | number> {
-    const result: Record<string, string | number> = {};
+/**
+ * Collections whose key the *browser* cannot resolve, and what it will do
+ * instead.
+ *
+ * The two sides resolve keys from different evidence. This driver reads, in
+ * order: properties marked `isId`, the primary keys of the Drizzle schema, then
+ * a column literally named `id`. The admin shares the `CollectionConfig` — it
+ * compiles the same collection files into its bundle — but never the Drizzle
+ * schema, so the middle tier is invisible to it.
+ *
+ * Nothing can normalize this at runtime: the server does not serve the admin
+ * its collections, so a key resolved here cannot be handed over there. The
+ * config files are the only thing both sides read, so the fix is an edit to
+ * them, and the most this can do is say exactly which edit.
+ *
+ * Two shapes, and the second is the dangerous one:
+ *
+ * - No `isId`, no `id` property → the admin resolves no address, warns in the
+ *   console, and rows cannot be opened or linked.
+ * - No `isId`, but an `id` property that is *not* the key → the admin addresses
+ *   rows by `id` while this driver reads the address as the real key. Nothing
+ *   errors: the addresses look right and route wrong.
+ */
+export function findUnresolvableKeyCollections(
+    collections: CollectionConfig[],
+    registry: PostgresCollectionRegistry
+): { collection: CollectionConfig; keys: PrimaryKeyInfo[]; shadowedByIdProperty: boolean }[] {
+    const findings: { collection: CollectionConfig; keys: PrimaryKeyInfo[]; shadowedByIdProperty: boolean }[] = [];
+
+    for (const collection of collections) {
+        // Declared `isId` is the tier both sides share: if it is there, they agree.
+        if (getDeclaredPrimaryKeys(collection).length > 0) continue;
+
+        let keys: PrimaryKeyInfo[];
+        try {
+            keys = getPrimaryKeys(collection, registry);
+        } catch {
+            // No registered table — nothing resolved here either, so there is no
+            // disagreement to report.
+            continue;
+        }
+        if (keys.length === 0) continue;
 
-    if (primaryKeys.length === 0) {
-        return result;
-    }
+        // A single key named `id` is the last tier on both sides: they agree
+        // without anything being declared.
+        if (keys.length === 1 && keys[0].fieldName === "id") continue;
 
-    if (primaryKeys.length === 1) {
-        const pk = primaryKeys[0];
-        if (pk.type === "number" && !pk.isUUID) {
-            const parsed = typeof idValue === "number" ? idValue : parseInt(String(idValue), 10);
-            if (isNaN(parsed)) {
-                throw new Error(`Invalid numeric ID: ${idValue}`);
-            }
-            result[pk.fieldName] = parsed;
-        } else {
-            result[pk.fieldName] = String(idValue);
-        }
-        return result;
+        findings.push({
+            collection,
+            keys,
+            shadowedByIdProperty: Boolean(collection.properties?.id)
+        });
     }
 
-    // Composite key - split by :::
-    const parts = String(idValue).split(":::");
-    if (parts.length !== primaryKeys.length) {
-        throw new Error(`Composite ID parts mismatch. Expected ${primaryKeys.length}, got ${parts.length} for ID: ${idValue}`);
-    }
+    return findings;
+}
 
-    for (let i = 0; i < primaryKeys.length; i++) {
-        const pk = primaryKeys[i];
-        const val = parts[i];
-        if (pk.type === "number" && !pk.isUUID) {
-            const parsed = parseInt(val, 10);
-            if (isNaN(parsed)) {
-                throw new Error(`Invalid numeric ID component: ${val}`);
-            }
-            result[pk.fieldName] = parsed;
-        } else {
-            result[pk.fieldName] = val;
-        }
+/**
+ * Report the collections from {@link findUnresolvableKeyCollections} at boot,
+ * with the edit that fixes each one.
+ *
+ * Grouped by failure, not by collection: the shadowed case is a routing bug and
+ * the silent case is a missing feature, and they deserve different urgency.
+ */
+export function warnOnKeysTheAdminCannotResolve(
+    collections: CollectionConfig[],
+    registry: PostgresCollectionRegistry
+): void {
+    const findings = findUnresolvableKeyCollections(collections, registry);
+    if (findings.length === 0) return;
+
+    const edit = (f: { collection: CollectionConfig; keys: PrimaryKeyInfo[] }) =>
+        `${f.collection.slug}: mark ${f.keys.map(k => `\`${k.fieldName}\``).join(" and ")} with ` +
+        `\`isId: ${f.keys[0].isUUID ? "\"uuid\"" : f.keys[0].type === "number" ? "\"increment\"" : "true"}\``;
+
+    const shadowed = findings.filter(f => f.shadowedByIdProperty);
+    const silent = findings.filter(f => !f.shadowedByIdProperty);
+
+    if (shadowed.length > 0) {
+        logger.warn(
+            `⚠️ These collections declare no \`isId\`, and their key is only in the drizzle schema — but they ` +
+            `do have a property called \`id\`. The admin has no way to know \`id\` is not the key, so it will ` +
+            `address rows by it while this server reads the address as the real key: the links look right and ` +
+            `route wrong. Nothing will error.\n\n` +
+            shadowed.map(f => `  • ${edit(f)}`).join("\n") + "\n"
+        );
     }
 
-    return result;
+    if (silent.length > 0) {
+        logger.warn(
+            `⚠️ These collections declare no \`isId\`, and their key is only in the drizzle schema, which the ` +
+            `admin never sees. It will resolve no address for their rows, so detail links, caching and ` +
+            `relations will not work for them:\n\n` +
+            silent.map(f => `  • ${edit(f)}`).join("\n") + "\n"
+        );
+    }
 }
 
-export function buildCompositeId(values: Record<string, unknown>, primaryKeys: { fieldName: string; type: "string" | "number"; isUUID?: boolean }[]): string {
-    if (primaryKeys.length === 0) {
-        return "";
-    }
-    if (primaryKeys.length === 1) {
-        return String(values[primaryKeys[0].fieldName] ?? "");
+/**
+ * The address of a row: derived from the collection's primary keys, because a
+ * row does not carry one — it is exactly its columns.
+ *
+ * Falls back to a literal `id` column, which covers the two cases where the
+ * keys cannot be resolved: a row that reached us from somewhere other than the
+ * postgres driver, and a collection whose table the registry cannot look up
+ * (`getPrimaryKeys` throws for an unregistered table rather than returning
+ * nothing). Returns `""` when there is no key and no `id` — callers decide what
+ * that means, since "unaddressable" is a different answer in a notification
+ * (broadcast a wildcard) than in a save (fail).
+ */
+export function deriveRowAddress(
+    row: Record<string, unknown>,
+    collection: CollectionConfig,
+    registry: PostgresCollectionRegistry
+): string {
+    try {
+        const composite = buildCompositeId(row, getPrimaryKeys(collection, registry));
+        // An all-empty composite is indistinguishable from a missing key, and
+        // `buildCompositeId` returns "" for no keys at all.
+        if (composite && composite.split(COMPOSITE_ID_SEPARATOR).some(part => part !== "")) {
+            return composite;
+        }
+    } catch {
+        /* unresolvable table or keys — fall through to the literal column */
     }
-    return primaryKeys.map(pk => String(values[pk.fieldName] ?? "")).join(":::");
+    if (row.id !== undefined && row.id !== null) return String(row.id);
+    return "";
 }
+

package/src/services/dataService.ts

@@ -154,9 +154,10 @@ export class DataService implements DataRepository {
         collectionPath: string,
         values: Partial<M>,
         id?: string | number,
-        databaseId?: string
+        databaseId?: string,
+        options?: { upsert?: boolean }
     ): Promise<Record<string, unknown>> {
-        return this.persistService.save<M>(collectionPath, values, id, databaseId);
+        return this.persistService.save<M>(collectionPath, values, id, databaseId, options);
     }
 
     /**

package/src/services/index.ts

@@ -8,6 +8,7 @@ export {
     getCollectionByPath,
     getTableForCollection,
     getPrimaryKeys,
+    deriveRowAddress,
     parseIdValues,
     buildCompositeId
 } from "./collection-helpers";

package/src/services/realtimeService.ts

@@ -14,7 +14,7 @@ import { applyAuthContext } from "../security/rls-enforcement";
 import { logger } from "@rebasepro/server";
 import { sanitizeErrorForClient } from "../utils/pg-error-utils";
 import { CdcListener, type CdcChangeEvent } from "./cdc/CdcListener";
-import { getPrimaryKeys, buildCompositeId } from "./collection-helpers";
+import { deriveRowAddress, getPrimaryKeys, type PrimaryKeyInfo } from "./collection-helpers";
 
 /** Channel name used for Postgres LISTEN/NOTIFY cross-instance realtime. */
 const PG_NOTIFY_CHANNEL = "rebase_entity_changes";
@@ -390,7 +390,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                 authContext
             );
 
-            this.sendCollectionUpdate(clientId, subscriptionId, rows);
+            this.sendCollectionUpdate(clientId, subscriptionId, rows, request.path);
 
         } catch (error) {
             const sanitized = sanitizeErrorForClient(error, request.path);
@@ -554,7 +554,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                     // Phase 1: Send instant row-level patch (no DB query)
                     // This gives immediate cross-tab feedback
                     if (!row || !(row as Record<string, unknown>)?._rebase_invalidated) {
-                        this.sendCollectionPatch(subscription.clientId, subscriptionId, id, row);
+                        this.sendCollectionPatch(subscription.clientId, subscriptionId, id, row, notifyPath);
                     }
 
                     // Phase 2: Schedule a deferred full refetch for correctness
@@ -609,7 +609,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             if (!this._subscriptions.has(subscriptionId)) return;
             try {
                 const rows = await this.fetchCollectionWithAuth(notifyPath, subscription.collectionRequest!, subscription.authContext);
-                this.sendCollectionUpdate(subscription.clientId, subscriptionId, rows);
+                this.sendCollectionUpdate(subscription.clientId, subscriptionId, rows, notifyPath);
             } catch (error) {
                 const sanitized = sanitizeErrorForClient(error, notifyPath);
                 this.sendError(subscription.clientId, sanitized.message, subscriptionId, sanitized.code);
@@ -910,11 +910,12 @@ roles: activeAuth.roles },
         return await this.dataService.fetchOne(notifyPath, id);
     }
 
-    private sendCollectionUpdate(clientId: string, subscriptionId: string, rows: Record<string, unknown>[]) {
+    private sendCollectionUpdate(clientId: string, subscriptionId: string, rows: Record<string, unknown>[], path: string) {
         const message: CollectionUpdateMessage = {
             type: "collection_update",
             subscriptionId,
-            rows: rows
+            rows: rows,
+            pks: this.primaryKeysForPath(path)
         };
         this.sendMessage(clientId, message);
     }
@@ -931,17 +932,43 @@ roles: activeAuth.roles },
     /**
      * Send a lightweight row-level patch to a collection subscriber.
      * The client can merge this into its cached data for instant feedback.
+     *
+     * The key columns ride along: the patch names a row by address, and the
+     * client has to find that row among the ones it cached — which carry
+     * columns and no address. The SDK holds no collection config to derive one
+     * from, so this is the only place the mapping can come from.
      */
-    private sendCollectionPatch(clientId: string, subscriptionId: string, id: string, row: Record<string, unknown> | null) {
+    private sendCollectionPatch(
+        clientId: string,
+        subscriptionId: string,
+        id: string,
+        row: Record<string, unknown> | null,
+        notifyPath: string
+    ) {
         const message: CollectionPatchMessage = {
             type: "collection_patch",
             subscriptionId,
             id,
-            row: row
+            row: row,
+            pks: this.primaryKeysForPath(notifyPath)
         };
         this.sendMessage(clientId, message);
     }
 
+    /** The key columns of the collection at `path`, if they can be resolved. */
+    private primaryKeysForPath(path: string): PrimaryKeyInfo[] | undefined {
+        try {
+            const collection = this.registry.getCollectionByPath(path);
+            if (!collection) return undefined;
+            const keys = getPrimaryKeys(collection, this.registry);
+            return keys.length > 0 ? keys : undefined;
+        } catch {
+            // Unregistered table, or a relation path with no collection of its
+            // own: the client keeps its pre-existing `id` behaviour.
+            return undefined;
+        }
+    }
+
     private sendError(clientId: string, error: string, subscriptionId?: string, code?: string) {
         const message = {
             type: "error" as const,
@@ -1294,17 +1321,9 @@ lastSeen: Date.now() });
 
     /** Compute the canonical (possibly composite) id string from a captured row. */
     private extractIdFromCdcRow(collection: CollectionConfig, row: Record<string, unknown>): string {
-        try {
-            const primaryKeys = getPrimaryKeys(collection, this.registry);
-            const composite = buildCompositeId(row, primaryKeys);
-            if (composite && composite !== ":::") return composite;
-        } catch {
-            /* fall through to id-field / wildcard */
-        }
-        // Fallbacks: a plain `id` column (common), else a collection-level
-        // invalidation ("*") — single-row subs won't match but collection subs refetch.
-        if (row.id !== undefined && row.id !== null) return String(row.id);
-        return "*";
+        // Unaddressable falls back to a collection-level invalidation: single-row
+        // subs won't match, but collection subs still refetch.
+        return deriveRowAddress(row, collection, this.registry) || "*";
     }
 
     // ── App/CDC de-duplication ──

package/src/websocket.ts

@@ -620,9 +620,12 @@ roles: ["anon"] };
                 if (error instanceof Error) {
                     logger.error("Stack trace", { detail: error.stack });
                 }
+                // Unwrap the cause chain: a Drizzle failure reports itself as
+                // "Failed query: <sql> params:", which tells the user nothing and
+                // echoes the statement back at them. The reason is in the cause.
                 const errorMessage = process.env.NODE_ENV === "production"
                     ? "An unexpected error occurred"
-                    : (error instanceof Error ? error.message : "An unexpected error occurred");
+                    : extractErrorMessage(error);
                 const errorResponse = {
                     type: "ERROR",
                     requestId,

package/dist/schema/auth-default-policies.d.ts

@@ -1,10 +0,0 @@
-import { CollectionConfig, SecurityRule } from "@rebasepro/types";
-/**
- * Returns the security rules that should be applied to a collection: the
- * author's explicit `securityRules` plus the framework defaults described in
- * the module doc (baseline server/admin read for all collections; self-read
- * and the admin write gate for auth collections).
- *
- * Collections that opt out via `disableDefaultPolicies` are returned unchanged.
- */
-export declare function getEffectiveSecurityRules(collection: CollectionConfig): SecurityRule[];

package/src/schema/auth-default-policies.ts

@@ -1,132 +0,0 @@
-import { CollectionConfig, SecurityRule, SecurityOperation, AuthCollectionConfig, PolicyExpression, isPostgresCollectionConfig, policy } from "@rebasepro/types";
-import { getTableName } from "@rebasepro/common";
-
-/**
- * Default RLS policies injected by the schema generator.
- *
- * Rebase's enforcement model is unified: authenticated (user-context) requests
- * run under the restricted `rebase_user` role, so Postgres RLS binds *every*
- * statement — reads and writes. A collection's `securityRules` are the whole
- * authorization model. The server context (auth flows, migrations,
- * `dataAsAdmin`) runs as the owner and bypasses RLS.
- *
- * Because RLS default-denies, every collection is **locked by default**: with
- * no rules, only the server context and admins can touch it. The generator
- * injects that safe baseline:
- *
- * **For every collection**
- *  1. A permissive **server-or-admin SELECT** grant.
- *  2. A permissive **server-or-admin write** grant (insert/update/delete).
- *
- * Author `securityRules` are permissive and OR together, so explicit rules only
- * *broaden* access from this locked baseline (e.g. "users read/write their own
- * rows").
- *
- * **For auth collections additionally**
- *  3. A permissive **self SELECT** grant (`id = auth.uid()`), so users can read
- *     their own row (profile, session bootstrap) without every app re-declaring
- *     it.
- *  4. A **restrictive** admin write gate. Restrictive policies are AND'd with
- *     every other policy, so a write is rejected unless the caller is an admin
- *     (or the server context) — even if the author also wrote a permissive rule
- *     such as "a user may edit their own row". Without this, a permissive owner
- *     rule would let a user change their own `roles`.
- *
- * The server context is recognised as `auth.uid() IS NULL` (`policy.serverContext()`)
- * — the built-in flows that run without a user (signup, migrations) set no user
- * GUC — which also lets the owner connection satisfy these policies even under
- * FORCE RLS. A *user* request never reaches that state: an anonymous one carries
- * `ANONYMOUS_USER_ID`, precisely so it cannot pass for the server here.
- *
- * Opt out with `disableDefaultPolicies: true` to take full responsibility for
- * the collection's RLS.
- */
-// Expressed structurally (not as raw SQL) so the admin UI can evaluate it
-// exactly — the framework's most security-critical policies must be reflected
-// precisely, not left as un-evaluable raw clauses. Compiles to
-// `auth.uid() IS NULL OR (string_to_array(auth.roles(), ',') && ARRAY['admin'])`.
-//
-// `serverContext()`, emphatically not `not(authenticated())`: the server arm of
-// this grant must match the server context and nothing else. Anonymous visitors
-// are not signed in either, so a negated `authenticated()` would hand them the
-// server-or-admin grant on every collection's default policy.
-const SERVER_OR_ADMIN_EXPR: PolicyExpression = policy.or(
-    policy.serverContext(),
-    policy.rolesOverlap(["admin"])
-);
-
-/** Write operations that must be admin-gated by default on auth collections. */
-const DEFAULT_GUARDED_OPS: SecurityOperation[] = ["insert", "update", "delete"];
-
-/** Whether a collection is flagged as an authentication collection. */
-function isAuthCollection(collection: CollectionConfig): boolean {
-    const auth = collection.auth;
-    return auth === true || (typeof auth === "object" && (auth as AuthCollectionConfig)?.enabled === true);
-}
-
-/** The property marked as the row id (falls back to `id`). */
-function getIdPropertyName(collection: CollectionConfig): string {
-    for (const [name, prop] of Object.entries(collection.properties ?? {})) {
-        if (prop && typeof prop === "object" && "isId" in prop && (prop as { isId?: unknown }).isId) {
-            return name;
-        }
-    }
-    return "id";
-}
-
-/**
- * Returns the security rules that should be applied to a collection: the
- * author's explicit `securityRules` plus the framework defaults described in
- * the module doc (baseline server/admin read for all collections; self-read
- * and the admin write gate for auth collections).
- *
- * Collections that opt out via `disableDefaultPolicies` are returned unchanged.
- */
-export function getEffectiveSecurityRules(collection: CollectionConfig): SecurityRule[] {
-    const explicit = [...((isPostgresCollectionConfig(collection) ? collection.securityRules : undefined) ?? [])];
-
-    if (collection.disableDefaultPolicies) {
-        return explicit;
-    }
-
-    const tableName = getTableName(collection);
-    const injected: SecurityRule[] = [];
-
-    // Baseline read + write: the server context and admins can always operate.
-    // RLS default-denies under the user role, so without these a rule-less
-    // collection would be locked to everyone — including the admin studio.
-    // Author rules are permissive and broaden access from here.
-    injected.push({
-        name: `${tableName}_default_admin_read`,
-        operations: ["select"],
-        condition: SERVER_OR_ADMIN_EXPR
-    });
-    injected.push({
-        name: `${tableName}_default_admin_write`,
-        operations: [...DEFAULT_GUARDED_OPS],
-        condition: SERVER_OR_ADMIN_EXPR,
-        check: SERVER_OR_ADMIN_EXPR
-    });
-
-    if (isAuthCollection(collection)) {
-        // Self-read: a user can always read their own row.
-        injected.push({
-            name: `${tableName}_default_self_read`,
-            operations: ["select"],
-            condition: policy.compare(policy.field(getIdPropertyName(collection)), "eq", policy.authUid())
-        });
-
-        // Restrictive gate: AND'd with all other policies, so no permissive rule
-        // (e.g. an owner "edit your own row" rule) can let a non-admin change
-        // privileged columns like `roles`.
-        injected.push({
-            name: `${tableName}_require_admin_write`,
-            mode: "restrictive",
-            operations: [...DEFAULT_GUARDED_OPS],
-            condition: SERVER_OR_ADMIN_EXPR,
-            check: SERVER_OR_ADMIN_EXPR
-        });
-    }
-
-    return [...explicit, ...injected];
-}