@rebasepro/server-postgres 0.17.3 → 0.18.0

package/src/services/cdc/CdcListener.ts

@@ -1,103 +0,0 @@
-import { logger } from "@rebasepro/server";
-import { CDC_CHANNEL } from "./trigger-cdc";
-import { PgNotifyListener } from "../pg-notify-listener";
-
-/**
- * A single database change captured by the CDC triggers and delivered over the
- * `rebase_cdc` NOTIFY channel.
- */
-export interface CdcChangeEvent {
-    schema: string;
-    table: string;
-    op: "INSERT" | "UPDATE" | "DELETE";
-    /**
-     * The changed tuple (NEW for insert/update, OLD for delete). May be a
-     * partial identity-only object when the full row overflowed the pg_notify
-     * size cap — see {@link truncated}.
-     */
-    row: Record<string, unknown>;
-    /** True when the row was reduced to its identity because it was too large to notify. */
-    truncated?: boolean;
-}
-
-/**
- * Parse a `rebase_cdc` NOTIFY payload. Returns `null` for anything malformed so
- * a single bad message can never crash the listener.
- */
-export function parseCdcPayload(payload: string): CdcChangeEvent | null {
-    let parsed: unknown;
-    try {
-        parsed = JSON.parse(payload);
-    } catch {
-        return null;
-    }
-    if (!parsed || typeof parsed !== "object") return null;
-
-    const obj = parsed as Record<string, unknown>;
-    const schema = typeof obj.schema === "string" ? obj.schema : undefined;
-    const table = typeof obj.table === "string" ? obj.table : undefined;
-    const op = obj.op;
-    if (!schema || !table) return null;
-    if (op !== "INSERT" && op !== "UPDATE" && op !== "DELETE") return null;
-
-    const row = obj.row && typeof obj.row === "object" ? (obj.row as Record<string, unknown>) : {};
-
-    return {
-        schema,
-        table,
-        op,
-        row,
-        truncated: obj.truncated === true
-    };
-}
-
-/**
- * Dedicated Postgres LISTEN client for database-level CDC.
- *
- * A {@link PgNotifyListener} — a connection outside the Drizzle pool that stays
- * open and repairs itself — plus the parsing that turns a `rebase_cdc` payload
- * into a change event. Each backend instance runs one, so every instance
- * observes every committed change regardless of which instance (or external
- * process) made the write.
- */
-export class CdcListener {
-    private readonly listener: PgNotifyListener;
-
-    constructor(connectionString: string, onEvent: (event: CdcChangeEvent) => void | Promise<void>) {
-        this.listener = new PgNotifyListener({
-            connectionString,
-            channel: CDC_CHANNEL,
-            logLabel: "[CDC]",
-            onPayload: (payload) => {
-                const event = parseCdcPayload(payload);
-                if (!event) {
-                    logger.warn("⚠️ [CDC] Dropping unparseable change notification.");
-                    return;
-                }
-                return onEvent(event);
-            }
-        });
-    }
-
-    /**
-     * Connect and begin listening. Idempotent.
-     *
-     * The **initial** connection is validated synchronously: if it cannot be
-     * established (or `LISTEN` is refused), this rejects so callers — notably
-     * `REALTIME_CDC=auto` — can detect an unusable connection and fall back to
-     * app-level realtime. Once the initial connection succeeds, later drops
-     * self-heal in the background.
-     */
-    async start(): Promise<void> {
-        if (this.listener.active) {
-            logger.warn("⚠️ [CDC] CdcListener.start() called but already running. Ignoring.");
-            return;
-        }
-        await this.listener.start();
-    }
-
-    /** Stop listening and release the connection. */
-    async stop(): Promise<void> {
-        await this.listener.stop();
-    }
-}

package/src/services/cdc/junction-tables.ts

@@ -1,91 +0,0 @@
-import { CollectionConfig, ResolvedRelation, isManyToMany } from "@rebasepro/types";
-import { resolveCollectionRelations } from "@rebasepro/common";
-
-import { PostgresCollectionRegistry } from "../../collections/PostgresCollectionRegistry";
-
-/**
- * One end of a many-to-many, as seen from the junction table.
- *
- * A junction table is not a collection, so nothing in the registry maps it to
- * one — which is why a change to it was invisible to change capture. But its
- * rows are exactly the contents of a parent's child list, so a write to it is a
- * change to `<parentSlug>/<sourceId>/<relationKey>` and to nothing else.
- */
-export interface JunctionLink {
-    schema: string;
-    /** The junction table itself, e.g. `posts_tags`. */
-    table: string;
-    /** The collection whose relation this is, e.g. `posts`. */
-    parentCollection: CollectionConfig;
-    /** The relation's key — the path segment a child list is addressed by. */
-    relationKey: string;
-    /** Junction column holding the parent's id. */
-    sourceColumn: string;
-    /** Junction column holding the target's id. */
-    targetColumn: string;
-}
-
-/**
- * Every junction table reachable from a registered collection, once per
- * relation that uses it.
- *
- * A junction is listed once per *direction* when both sides declare it, because
- * each direction addresses a different child list: `posts/1/tags` and
- * `tags/t/posts` both change when one link is written.
- */
-export function collectJunctionLinks(registry: PostgresCollectionRegistry): JunctionLink[] {
-    const links: JunctionLink[] = [];
-    const seen = new Set<string>();
-
-    for (const collection of registry.getCollections()) {
-        let relations: Record<string, ResolvedRelation>;
-        try {
-            relations = resolveCollectionRelations(collection);
-        } catch {
-            // A collection whose relations cannot be resolved (an unresolvable
-            // target, typically mid-migration) simply contributes none.
-            continue;
-        }
-
-        for (const [relationKey, relation] of Object.entries(relations)) {
-            if (!isManyToMany(relation)) continue;
-            const through = relation.through;
-
-            // Same relation registered under both its canonical name and the
-            // declaring property key would otherwise notify the same path twice.
-            const key = `${collection.slug}::${relationKey}::${through.table}`;
-            if (seen.has(key)) continue;
-            seen.add(key);
-
-            links.push({
-                schema: (collection as { schema?: string }).schema ?? "public",
-                table: through.table,
-                parentCollection: collection,
-                relationKey,
-                sourceColumn: through.sourceColumn,
-                targetColumn: through.targetColumn
-            });
-        }
-    }
-
-    return links;
-}
-
-/**
- * Index {@link collectJunctionLinks} by table, under both the qualified and the
- * bare name — a change event carries whatever the trigger reports, and a
- * collection need not declare a schema.
- */
-export function buildJunctionLinkMap(registry: PostgresCollectionRegistry): Map<string, JunctionLink[]> {
-    const map = new Map<string, JunctionLink[]>();
-
-    for (const link of collectJunctionLinks(registry)) {
-        for (const key of [`${link.schema}.${link.table}`, link.table]) {
-            const existing = map.get(key);
-            if (existing) existing.push(link);
-            else map.set(key, [link]);
-        }
-    }
-
-    return map;
-}

package/src/services/cdc/trigger-cdc.ts

@@ -1,173 +0,0 @@
-import { logger } from "@rebasepro/server";
-import type { RawSqlRunner } from "../../security/rls-enforcement";
-
-/**
- * Trigger-based Change Data Capture (CDC).
- *
- * The preferred CDC source is the write-ahead log (logical replication), which
- * — like Supabase Realtime — sees *every* commit regardless of how it was made.
- * When logical replication is unavailable (managed Postgres without
- * `wal_level=logical`, no replication privilege, no `REPLICA IDENTITY`), this
- * trigger-based fallback provides the same guarantee at the row level:
- *
- *   AFTER INSERT/UPDATE/DELETE trigger  →  pg_notify('rebase_cdc', payload)
- *
- * A single dedicated LISTEN client per backend instance consumes the channel
- * (see {@link CdcListener}) and feeds the change into the existing
- * `RealtimeService.notifyUpdate` pipeline, so subscribers see the change no
- * matter what wrote it — psql, a cron in another service, raw Drizzle/SQL, or
- * the Studio SQL editor.
- *
- * Provisioning runs from the framework's own bootstrap as the owner (server)
- * context, alongside the RLS role provisioning. It is idempotent.
- */
-
-/** Postgres NOTIFY channel carrying database-level change events. */
-export const CDC_CHANNEL = "rebase_cdc";
-
-/** Schema-qualified name of the generic trigger function. */
-export const CDC_TRIGGER_FUNCTION = "rebase.rebase_cdc_notify";
-
-/** Name of the per-table trigger (unqualified — triggers are namespaced by table). */
-export const CDC_TRIGGER_NAME = "rebase_cdc_trigger";
-
-/**
- * pg_notify hard-caps payloads at 8000 bytes and *aborts the triggering
- * statement* if the limit is exceeded. We stay comfortably under it and, for
- * wide rows, fall back to an identity-only payload so CDC can never break a
- * write. 7900 leaves headroom for the JSON envelope keys.
- */
-const MAX_NOTIFY_BYTES = 7900;
-
-const quoteIdent = (name: string): string => `"${name.replace(/"/g, "\"\"")}"`;
-const quoteLiteral = (value: string): string => `'${value.replace(/'/g, "''")}'`;
-
-/**
- * SQL that (re)creates the generic CDC trigger function. Safe to run repeatedly:
- * `CREATE OR REPLACE` updates in place without dropping dependent triggers.
- *
- * The function emits `{ schema, table, op, row }`. The `row` is the full changed
- * tuple (NEW for insert/update, OLD for delete) so the consumer can route it to
- * a collection and extract the primary key. It is *not* trusted for delivery:
- * the consumer marks the row invalidated and each subscriber re-reads it under
- * its own RLS context, so a subscriber never receives a row it cannot read.
- */
-export function buildCdcFunctionSql(): string {
-    return `
-CREATE SCHEMA IF NOT EXISTS rebase;
-
-CREATE OR REPLACE FUNCTION ${CDC_TRIGGER_FUNCTION}() RETURNS trigger
-LANGUAGE plpgsql AS $rebase_cdc$
-DECLARE
-    rec     jsonb;
-    payload text;
-BEGIN
-    IF (TG_OP = 'DELETE') THEN
-        rec := to_jsonb(OLD);
-    ELSE
-        rec := to_jsonb(NEW);
-    END IF;
-
-    payload := json_build_object(
-        'schema', TG_TABLE_SCHEMA,
-        'table',  TG_TABLE_NAME,
-        'op',     TG_OP,
-        'row',    rec
-    )::text;
-
-    -- Never let CDC abort the write: if the full row overflows the pg_notify
-    -- 8000-byte cap, emit an identity-only payload the consumer can still route
-    -- (and refetch the authoritative row from).
-    IF (octet_length(payload) > ${MAX_NOTIFY_BYTES}) THEN
-        payload := json_build_object(
-            'schema',    TG_TABLE_SCHEMA,
-            'table',     TG_TABLE_NAME,
-            'op',        TG_OP,
-            'row',       CASE WHEN rec ? 'id' THEN jsonb_build_object('id', rec->'id') ELSE '{}'::jsonb END,
-            'truncated', true
-        )::text;
-    END IF;
-
-    PERFORM pg_notify(${quoteLiteral(CDC_CHANNEL)}, payload);
-    RETURN NULL;
-END;
-$rebase_cdc$;
-`.trim();
-}
-
-/**
- * SQL that (re)attaches the CDC trigger to a single table. `DROP ... IF EXISTS`
- * before `CREATE` keeps it idempotent and picks up any function signature change.
- */
-export function buildCdcTriggerSql(schema: string, table: string): string {
-    const qualified = `${quoteIdent(schema)}.${quoteIdent(table)}`;
-    return (
-        `DROP TRIGGER IF EXISTS ${quoteIdent(CDC_TRIGGER_NAME)} ON ${qualified};\n` +
-        `CREATE TRIGGER ${quoteIdent(CDC_TRIGGER_NAME)} ` +
-        `AFTER INSERT OR UPDATE OR DELETE ON ${qualified} ` +
-        `FOR EACH ROW EXECUTE FUNCTION ${CDC_TRIGGER_FUNCTION}();`
-    );
-}
-
-export interface CdcTableRef {
-    schema: string;
-    table: string;
-}
-
-export interface ProvisionResult {
-    /** Tables the trigger was successfully attached to. */
-    installed: CdcTableRef[];
-    /** Tables that could not be provisioned (e.g. not yet migrated), with the error. */
-    skipped: Array<CdcTableRef & { reason: string }>;
-}
-
-/**
- * Idempotently install the CDC trigger function and per-table triggers.
- *
- * Runs as the owner (server) connection at bootstrap. A table that does not yet
- * exist in the database (schema drift) is skipped with a warning rather than
- * aborting the whole install, so one un-migrated collection cannot disable CDC
- * for the rest.
- */
-export async function provisionTriggerCdc(
-    run: RawSqlRunner,
-    tables: CdcTableRef[]
-): Promise<ProvisionResult> {
-    // 1. The shared trigger function (once).
-    await run(buildCdcFunctionSql());
-
-    // 2. One trigger per managed table. De-duplicate identical refs.
-    const seen = new Set<string>();
-    const installed: CdcTableRef[] = [];
-    const skipped: ProvisionResult["skipped"] = [];
-
-    for (const ref of tables) {
-        const key = `${ref.schema}.${ref.table}`;
-        if (seen.has(key)) continue;
-        seen.add(key);
-
-        try {
-            await run(buildCdcTriggerSql(ref.schema, ref.table));
-            installed.push(ref);
-        } catch (err) {
-            const reason = err instanceof Error ? err.message : String(err);
-            skipped.push({ ...ref, reason });
-            logger.warn(
-                `⚠️ [CDC] Could not attach change-capture trigger to "${key}" — ` +
-                `is the table migrated? Writes to it won't emit database-level events.`,
-                { detail: reason }
-            );
-        }
-    }
-
-    // Wiring detail. The single `Realtime source = …` line in the
-    // bootstrapper is the fact a developer acts on; how many triggers it
-    // took is for a diagnosis, and the skipped-table warning above still
-    // fires on its own.
-    logger.debug(
-        `📡 [CDC] Trigger-based change capture provisioned on ${installed.length} table(s)` +
-        (skipped.length ? ` (${skipped.length} skipped)` : "") + "."
-    );
-
-    return { installed, skipped };
-}

package/src/services/channel-bus/ChannelBus.ts

@@ -1,44 +0,0 @@
-/**
- * Runtime pieces of the channel bus that are not the contract itself.
- *
- * The interface, the frame shape and the implementer's contract live in
- * `@rebasepro/types` (`types/channel_bus.ts`), so a transport shipped as its own
- * package — a Redis one, say — depends on the contract and not on this database
- * adapter. They are re-exported here for convenience: code already importing
- * from the adapter should not have to know where the types are declared.
- */
-
-import type { ChannelBusFrame } from "@rebasepro/types";
-
-export type {
-    ChannelBus,
-    ChannelBusFrame,
-    ChannelBusHandler,
-    ChannelBusConfig,
-    ChannelBusSetting
-} from "@rebasepro/types";
-export { isChannelBusInstance } from "@rebasepro/types";
-
-/**
- * The default: no cross-instance delivery at all.
- *
- * This is what every deployment ran before the bus existed, and what a
- * single-instance deployment should keep running — `publish` resolves without
- * touching the network, so the broadcast path is the same handful of `ws.send`
- * calls it always was.
- */
-export class MemoryChannelBus {
-    readonly kind = "memory" as const;
-    readonly maxFrameBytes = Infinity;
-
-    async start(): Promise<void> { /* nothing to connect */ }
-
-    async publish(): Promise<void> { /* nowhere to publish to */ }
-
-    async stop(): Promise<void> { /* nothing to release */ }
-}
-
-/** Encoded size of a frame, for a transport's size check. */
-export function frameByteLength(frame: ChannelBusFrame): number {
-    return Buffer.byteLength(JSON.stringify(frame), "utf8");
-}