@rebasepro/server-postgres 0.10.0 → 0.10.1-canary.14e53ae

package/src/schema/ensure-collection-tables.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from "@jest/globals";
+import type { CollectionConfig } from "@rebasepro/types";
+import {
+    planCollectionSchemaEnsure,
+    ensureCollectionTables,
+    type ExistingSchema,
+    type Queryable
+} from "./ensure-collection-tables";
+
+const posts = {
+    name: "Posts",
+    slug: "posts",
+    properties: {
+        id: { name: "ID", type: "string", isId: "uuid" },
+        title: { name: "Title", type: "string" },
+        views: { name: "Views", type: "number" },
+        status: {
+            name: "Status",
+            type: "string",
+            enum: [
+                { id: "draft", label: "Draft" },
+                { id: "published", label: "Published" }
+            ]
+        }
+    }
+} as unknown as CollectionConfig;
+
+const empty = (): ExistingSchema => ({ tables: new Map(), enums: new Set() });
+
+const withTable = (key: string, columns: string[]): ExistingSchema => ({
+    tables: new Map([[key, new Set(columns)]]),
+    enums: new Set()
+});
+
+describe("planning an additive schema ensure", () => {
+    it("creates a missing table, its enum type, and its columns in that order", () => {
+        const plan = planCollectionSchemaEnsure([posts], empty());
+        const kinds = plan.actions.map(a => a.kind);
+
+        // The enum must exist before the column that references it, and the
+        // table before its own columns.
+        expect(kinds.indexOf("create-enum")).toBeLessThan(kinds.indexOf("create-table"));
+        expect(kinds.indexOf("create-table")).toBeLessThan(kinds.indexOf("add-column"));
+        expect(plan.statements.join("\n")).toMatch(/CREATE TABLE IF NOT EXISTS "public"\."posts"/);
+    });
+
+    it("adds only the columns an existing table is missing", () => {
+        const plan = planCollectionSchemaEnsure([posts], withTable("public.posts", ["id", "title"]));
+        const added = plan.actions.filter(a => a.kind === "add-column").map(a => a.target);
+
+        expect(added).toContain("public.posts.views");
+        expect(added).toContain("public.posts.status");
+        expect(added).not.toContain("public.posts.title");
+        expect(plan.actions.some(a => a.kind === "create-table")).toBe(false);
+    });
+
+    it("is a no-op against a database that is already current", () => {
+        const existing: ExistingSchema = {
+            tables: new Map([["public.posts", new Set(["id", "title", "views", "status"])]]),
+            enums: new Set(["public.posts_status"])
+        };
+        expect(planCollectionSchemaEnsure([posts], existing).actions).toEqual([]);
+    });
+
+    it("skips an enum type that already exists, since CREATE TYPE has no IF NOT EXISTS", () => {
+        const existing: ExistingSchema = { tables: new Map(), enums: new Set(["public.posts_status"]) };
+        const plan = planCollectionSchemaEnsure([posts], existing);
+        expect(plan.actions.some(a => a.kind === "create-enum")).toBe(false);
+    });
+
+    it("NEVER emits a destructive statement, whatever the database contains", () => {
+        // The core safety property. This runs unattended against customer data
+        // with nobody reading a diff, so a column the collections no longer
+        // mention must be left alone, not dropped.
+        const existing = withTable("public.posts", ["id", "title", "legacy_column", "another_old_one"]);
+        const sql = planCollectionSchemaEnsure([posts], existing).statements.join("\n");
+
+        expect(sql).not.toMatch(/\bDROP\b/i);
+        expect(sql).not.toMatch(/\bTRUNCATE\b/i);
+        expect(sql).not.toMatch(/ALTER COLUMN/i);
+        expect(sql).not.toMatch(/legacy_column/);
+    });
+
+    it("never adds a NOT NULL column, which an existing table with rows could not take", () => {
+        const sql = planCollectionSchemaEnsure([posts], withTable("public.posts", ["id"]))
+            .statements.join("\n");
+        expect(sql).not.toMatch(/NOT NULL/i);
+    });
+
+    it("leaves relation columns to a real migration rather than adding them without their key", () => {
+        const withRelation = {
+            ...posts,
+            properties: {
+                ...(posts as unknown as { properties: Record<string, unknown> }).properties,
+                author: { name: "Author", type: "reference", target: () => posts }
+            }
+        } as unknown as CollectionConfig;
+        const plan = planCollectionSchemaEnsure([withRelation], withTable("public.posts", ["id"]));
+        expect(plan.actions.some(a => a.target.endsWith(".author"))).toBe(false);
+    });
+});
+
+describe("applying the plan", () => {
+    function fakeClient(): { client: Queryable; executed: string[] } {
+        const executed: string[] = [];
+        const client: Queryable = {
+            async query<T>(sql: string): Promise<{ rows: T[] }> {
+                executed.push(sql);
+                return { rows: [] as T[] };
+            }
+        };
+        return { client, executed };
+    }
+
+    it("creates the schema, reads what exists, then applies", async () => {
+        const { client, executed } = fakeClient();
+        const plan = await ensureCollectionTables(client, [posts]);
+
+        expect(plan.actions.length).toBeGreaterThan(0);
+        expect(executed.some(s => s.includes("information_schema.columns"))).toBe(true);
+        expect(executed.some(s => s.includes("CREATE TABLE IF NOT EXISTS"))).toBe(true);
+    });
+
+    it("surfaces which statement failed rather than a bare driver error", async () => {
+        const client: Queryable = {
+            async query<T>(sql: string): Promise<{ rows: T[] }> {
+                if (sql.startsWith("CREATE TABLE")) throw new Error("permission denied");
+                return { rows: [] as T[] };
+            }
+        };
+        await expect(ensureCollectionTables(client, [posts])).rejects.toThrow(/permission denied/);
+        await expect(ensureCollectionTables(client, [posts])).rejects.toThrow(/public\.posts/);
+    });
+
+    it("does nothing when the database is already current", async () => {
+        const client: Queryable = {
+            async query<T>(sql: string): Promise<{ rows: T[] }> {
+                if (sql.includes("information_schema.columns")) {
+                    return {
+                        rows: ["id", "title", "views", "status"].map(c => ({
+                            table_schema: "public",
+                            table_name: "posts",
+                            column_name: c
+                        })) as unknown as T[]
+                    };
+                }
+                if (sql.includes("pg_type")) {
+                    return { rows: [{ schema: "public", name: "posts_status" }] as unknown as T[] };
+                }
+                return { rows: [] as T[] };
+            }
+        };
+        const plan = await ensureCollectionTables(client, [posts]);
+        expect(plan.actions).toEqual([]);
+    });
+});

package/src/schema/ensure-collection-tables.ts

@@ -0,0 +1,297 @@
+/**
+ * Bringing a database up to date with a bundle's collections, additively.
+ *
+ * ## Why this exists
+ *
+ * A managed runtime boots someone else's compiled project against a database it
+ * has never seen. Auth tables are ensured at boot already, but collection tables
+ * were not created by anything: the platform ran the app and every `/api/data/*`
+ * request answered 500 on a missing relation. `rebase db push` cannot help — it
+ * is an Atlas-driven CLI command, and the runtime image ships no CLI.
+ *
+ * ## Why additive-only, forever
+ *
+ * This runs unattended, against a database with customers' data in it, with no
+ * human reading a diff. So it may only ever do things that cannot lose data:
+ * create a missing table, add a missing column, create a missing enum type.
+ *
+ * It will **never** drop a table or a column, narrow a type, or alter a
+ * constraint. A removed field leaves its column behind; a renamed field looks
+ * like an addition and the old column stays. That is the correct trade for an
+ * automated path — the alternative is an unattended process that can silently
+ * destroy a column, which is precisely the failure `db push` was hardened
+ * against. Destructive changes stay a deliberate, human-reviewed migration.
+ *
+ * Because of that, this is safe to run on every boot, and re-running it is a
+ * no-op.
+ */
+import { type CollectionConfig, type Property, isPostgresCollectionConfig } from "@rebasepro/types";
+import { getTableName } from "@rebasepro/common";
+import {
+    getSqlColumnType,
+    resolveColumnName,
+    isIdProperty
+} from "./generate-postgres-ddl-logic";
+
+/**
+ * The subset of a database handle this needs: run a statement, get rows back.
+ *
+ * Deliberately parameterless. Everything here is DDL or catalogue reads keyed by
+ * schema name, and schema names are identifiers — they cannot be bound as
+ * parameters anyway. They are validated against {@link SAFE_IDENTIFIER} before
+ * they reach a statement, so a config that somehow carried a quote is refused
+ * rather than concatenated.
+ */
+export interface Queryable {
+    query<T = unknown>(sql: string): Promise<{ rows: T[] }>;
+}
+
+/** Postgres identifiers this module is willing to interpolate. */
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+
+function assertSafeIdentifier(value: string, what: string): string {
+    if (!SAFE_IDENTIFIER.test(value)) {
+        throw new Error(`Refusing to build SQL with an unsafe ${what}: ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+
+/** What the database currently has, as the planner needs it. */
+export interface ExistingSchema {
+    /** `schema.table` → set of column names. */
+    tables: Map<string, Set<string>>;
+    /** `schema.typename` of every enum type that already exists. */
+    enums: Set<string>;
+}
+
+export interface EnsureAction {
+    kind: "create-enum" | "create-table" | "add-column";
+    /** Qualified target, for logging: `public.posts` or `public.posts.title`. */
+    target: string;
+    sql: string;
+}
+
+export interface EnsurePlan {
+    actions: EnsureAction[];
+    /** Every statement, in dependency order. Empty when the schema is current. */
+    statements: string[];
+}
+
+function schemaOf(collection: CollectionConfig): string {
+    return isPostgresCollectionConfig(collection) && collection.schema ? collection.schema : "public";
+}
+
+function qualified(collection: CollectionConfig): string {
+    return `${schemaOf(collection)}.${getTableName(collection)}`;
+}
+
+/**
+ * Enum types a collection's properties require, as `schema.typename`.
+ *
+ * Named exactly as the DDL generator names them (`<table>_<column>`), because
+ * a column added here has to reference the same type the generator would have
+ * created — a second, differently-named type for the same field would be a
+ * silent schema fork.
+ */
+function requiredEnums(collection: CollectionConfig): { name: string; values: string[] }[] {
+    const table = getTableName(collection);
+    const schema = schemaOf(collection);
+    const out: { name: string; values: string[] }[] = [];
+    for (const [propName, prop] of Object.entries(collection.properties ?? {})) {
+        const p = prop as Property;
+        if (!("enum" in p) || !p.enum) continue;
+        if (p.type !== "string" && p.type !== "number") continue;
+        const values = (p.enum as unknown[])
+            .map(entry =>
+                entry && typeof entry === "object" && "id" in (entry as Record<string, unknown>)
+                    ? String((entry as Record<string, unknown>).id)
+                    : String(entry)
+            )
+            .filter(v => v.length > 0);
+        if (values.length === 0) continue;
+        out.push({ name: `${schema}.${table}_${resolveColumnName(propName, p)}`, values });
+    }
+    return out;
+}
+
+/** Single-quote escaping for an enum label. */
+function quoteLiteral(value: string): string {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+
+/**
+ * Decide what to add. Pure — the caller supplies what exists and runs the result.
+ *
+ * Ordering matters and is deliberate: enum types before the tables and columns
+ * that reference them, tables before the columns added to other tables (a new
+ * table may be the target of a relation), and nothing is emitted twice.
+ */
+export function planCollectionSchemaEnsure(
+    collections: CollectionConfig[],
+    existing: ExistingSchema
+): EnsurePlan {
+    const actions: EnsureAction[] = [];
+    const plannedEnums = new Set<string>();
+
+    // 1. Enum types. `CREATE TYPE` has no IF NOT EXISTS, so an existing type is
+    //    skipped by name rather than guarded in SQL.
+    for (const collection of collections) {
+        for (const { name, values } of requiredEnums(collection)) {
+            if (existing.enums.has(name) || plannedEnums.has(name)) continue;
+            plannedEnums.add(name);
+            const [schema, typeName] = name.split(".");
+            actions.push({
+                kind: "create-enum",
+                target: name,
+                sql: `CREATE TYPE "${schema}"."${typeName}" AS ENUM (${values.map(quoteLiteral).join(", ")});`
+            });
+        }
+    }
+
+    // 2. Missing tables. Only the identity column is created here; every other
+    //    column is added by step 3, so a new table and an existing table that
+    //    gained a field travel the exact same code path. One way to build a
+    //    column means one way for it to be wrong.
+    const created = new Set<string>();
+    for (const collection of collections) {
+        const key = qualified(collection);
+        if (existing.tables.has(key) || created.has(key)) continue;
+        created.add(key);
+        const schema = schemaOf(collection);
+        const table = getTableName(collection);
+        const idEntry = Object.entries(collection.properties ?? {}).find(([n, p]) =>
+            isIdProperty(n, p as Property, collection)
+        );
+        const idName = idEntry ? resolveColumnName(idEntry[0], idEntry[1] as Property) : "id";
+        const idProp = idEntry?.[1] as Property | undefined;
+        let idDef: string;
+        if (idProp?.type === "number") {
+            idDef = `"${idName}" BIGSERIAL PRIMARY KEY`;
+        } else if (
+            idProp &&
+            idProp.type === "string" &&
+            (idProp as { isId?: unknown }).isId === "uuid"
+        ) {
+            idDef = `"${idName}" UUID PRIMARY KEY DEFAULT gen_random_uuid()`;
+        } else {
+            idDef = `"${idName}" TEXT PRIMARY KEY`;
+        }
+        actions.push({
+            kind: "create-table",
+            target: key,
+            sql: `CREATE TABLE IF NOT EXISTS "${schema}"."${table}" (${idDef});`
+        });
+    }
+
+    // 3. Missing columns, on both brand-new and pre-existing tables.
+    for (const collection of collections) {
+        const key = qualified(collection);
+        const schema = schemaOf(collection);
+        const table = getTableName(collection);
+        const present = existing.tables.get(key) ?? new Set<string>();
+        for (const [propName, prop] of Object.entries(collection.properties ?? {})) {
+            const p = prop as Property;
+            if (isIdProperty(propName, p, collection)) continue;
+            // A relation's own column is emitted by the DDL generator with a
+            // foreign key; adding a bare column here would create the column
+            // without the constraint and make the generator's later output
+            // disagree with the database. Left to a real migration.
+            if (p.type === "reference" || p.type === "relation") continue;
+            const column = resolveColumnName(propName, p);
+            if (present.has(column)) continue;
+            const type = getSqlColumnType(propName, p, collection, collections);
+            actions.push({
+                kind: "add-column",
+                target: `${key}.${column}`,
+                // Never NOT NULL: an existing table with rows cannot take a
+                // non-null column without a default, and inventing one would be
+                // guessing at the customer's data.
+                sql: `ALTER TABLE "${schema}"."${table}" ADD COLUMN IF NOT EXISTS "${column}" ${type};`
+            });
+        }
+    }
+
+    return { actions, statements: actions.map(a => a.sql) };
+}
+
+/** Read what the database has, for the schemas the collections live in. */
+export async function readExistingSchema(
+    client: Queryable,
+    schemas: string[]
+): Promise<ExistingSchema> {
+    const tables = new Map<string, Set<string>>();
+    const enums = new Set<string>();
+    if (schemas.length === 0) return { tables, enums };
+
+    const inList = schemas
+        .map(schema => `'${assertSafeIdentifier(schema, "schema name")}'`)
+        .join(", ");
+
+    const { rows: columns } = await client.query<{
+        table_schema: string;
+        table_name: string;
+        column_name: string;
+    }>(
+        `SELECT table_schema, table_name, column_name
+         FROM information_schema.columns
+         WHERE table_schema IN (${inList})`
+    );
+    for (const row of columns) {
+        const key = `${row.table_schema}.${row.table_name}`;
+        if (!tables.has(key)) tables.set(key, new Set());
+        tables.get(key)!.add(row.column_name);
+    }
+
+    const { rows: enumRows } = await client.query<{ schema: string; name: string }>(
+        `SELECT n.nspname AS schema, t.typname AS name
+         FROM pg_type t
+         JOIN pg_namespace n ON t.typnamespace = n.oid
+         WHERE t.typtype = 'e' AND n.nspname IN (${inList})`
+    );
+    for (const row of enumRows) enums.add(`${row.schema}.${row.name}`);
+
+    return { tables, enums };
+}
+
+/**
+ * Bring the database up to date. Returns what it did.
+ *
+ * Each statement runs on its own rather than in one transaction: they are all
+ * independently safe and idempotent, and a single failure (an enum label that
+ * cannot be added, say) should not roll back the tables that were created fine.
+ * The error is surfaced with the statement that caused it.
+ */
+export async function ensureCollectionTables(
+    client: Queryable,
+    collections: CollectionConfig[],
+    log?: (message: string) => void
+): Promise<EnsurePlan> {
+    const schemas = Array.from(new Set(collections.map(schemaOf)));
+    for (const schema of schemas) {
+        assertSafeIdentifier(schema, "schema name");
+        if (schema !== "public") {
+            await client.query(`CREATE SCHEMA IF NOT EXISTS "${schema}";`);
+        }
+    }
+
+    const existing = await readExistingSchema(client, schemas);
+    const plan = planCollectionSchemaEnsure(collections, existing);
+
+    if (plan.actions.length === 0) {
+        log?.("Schema is up to date; nothing to create.");
+        return plan;
+    }
+
+    for (const action of plan.actions) {
+        try {
+            await client.query(action.sql);
+            log?.(`${action.kind}: ${action.target}`);
+        } catch (err) {
+            throw new Error(
+                `Failed to ${action.kind} ${action.target}: ` +
+                `${err instanceof Error ? err.message : String(err)}\n  ${action.sql}`
+            );
+        }
+    }
+    return plan;
+}

package/src/schema/generate-postgres-ddl-logic.ts

@@ -4,7 +4,7 @@ import { toSnakeCase, getPolicyNamesForRule } from "@rebasepro/utils";
 
 // --- Helper Functions ---
 
-const resolveColumnName = (propName: string, prop?: Property | null): string => {
+export const resolveColumnName = (propName: string, prop?: Property | null): string => {
     if (prop && "columnName" in prop && typeof prop.columnName === "string") {
         return prop.columnName;
     }
@@ -36,7 +36,7 @@ const getPrimaryKeyName = (collection: CollectionConfig): string => {
     return getPrimaryKeyProp(collection).name;
 };
 
-const isIdProperty = (propName: string, prop: Property, collection: CollectionConfig): boolean => {
+export const isIdProperty = (propName: string, prop: Property, collection: CollectionConfig): boolean => {
     if ("isId" in prop && Boolean(prop.isId)) return true;
     const hasExplicitId = Object.values(collection.properties ?? {}).some(p => "isId" in (p as unknown as object) && Boolean((p as unknown as Record<string, unknown>).isId));
     return !hasExplicitId && propName === "id";
@@ -90,7 +90,7 @@ const generateSinglePolicyDdl = (collection: CollectionConfig, rule: SecurityRul
     return `${ddl};\n`;
 };
 
-const getSqlColumnType = (propName: string, prop: Property, collection: CollectionConfig, collections: CollectionConfig[]): string => {
+export const getSqlColumnType = (propName: string, prop: Property, collection: CollectionConfig, collections: CollectionConfig[]): string => {
     switch (prop.type) {
         case "string": {
             const stringProp = prop as StringProperty;

package/src/services/cdc/CdcListener.ts

@@ -1,6 +1,6 @@
-import { Client as PgClient } from "pg";
 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
@@ -54,22 +54,30 @@ export function parseCdcPayload(payload: string): CdcChangeEvent | null {
 /**
  * Dedicated Postgres LISTEN client for database-level CDC.
  *
- * Mirrors the resilience of the RealtimeService cross-instance LISTEN client: a
- * standalone `pg.Client` (outside the Drizzle pool) that stays connected, and
- * transparently reconnects on error/disconnect. Each backend instance runs one,
- * so every instance observes every committed change regardless of which
- * instance (or external process) made the write.
+ * 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 client?: PgClient;
-    private running = false;
-    private reconnectTimer?: ReturnType<typeof setTimeout>;
-    private static readonly RECONNECT_DELAY_MS = 3000;
-
-    constructor(
-        private readonly connectionString: string,
-        private readonly onEvent: (event: CdcChangeEvent) => void | Promise<void>
-    ) {}
+    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.
@@ -78,90 +86,18 @@ export class CdcListener {
      * 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 via {@link scheduleReconnect}.
+     * self-heal in the background.
      */
     async start(): Promise<void> {
-        if (this.running) {
+        if (this.listener.active) {
             logger.warn("⚠️ [CDC] CdcListener.start() called but already running. Ignoring.");
             return;
         }
-        this.running = true;
-        try {
-            await this.connect({ initial: true });
-        } catch (err) {
-            this.running = false;
-            throw err;
-        }
+        await this.listener.start();
     }
 
     /** Stop listening and release the connection. */
     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> {
-        try {
-            const client = new PgClient({ connectionString: this.connectionString });
-
-            client.on("error", (err) => {
-                logger.error("❌ [CDC] LISTEN client error", { detail: err.message });
-                this.scheduleReconnect();
-            });
-
-            client.on("end", () => {
-                if (this.running) {
-                    logger.warn("⚠️ [CDC] LISTEN client disconnected unexpectedly.");
-                    this.scheduleReconnect();
-                }
-            });
-
-            client.on("notification", (msg) => {
-                if (!msg.payload) return;
-                const event = parseCdcPayload(msg.payload);
-                if (!event) {
-                    logger.warn("⚠️ [CDC] Dropping unparseable change notification.");
-                    return;
-                }
-                // Never let a handler rejection escape into the pg client.
-                Promise.resolve(this.onEvent(event)).catch((err) =>
-                    logger.error("❌ [CDC] Error handling change event", { error: err })
-                );
-            });
-
-            await client.connect();
-            await client.query(`LISTEN ${CDC_CHANNEL}`);
-            this.client = client;
-            logger.info(`📡 [CDC] Listening for database changes on channel "${CDC_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("❌ [CDC] 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();
-        }, CdcListener.RECONNECT_DELAY_MS);
+        await this.listener.stop();
     }
 }

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

@@ -0,0 +1,44 @@
+/**
+ * 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");
+}