@rebasepro/server-postgresql 0.4.0 → 0.5.0

package/README.md

@@ -1,106 +1,86 @@
-# @rebasepro/postgresql
+# @rebasepro/server-postgresql
 
-PostgreSQL data source client for Rebase with real-time WebSocket connectivity.
-
-This package provides a complete client-side implementation for connecting Rebase applications to PostgreSQL backends, featuring real-time synchronization via WebSockets.
+PostgreSQL database driver for Rebase, built on Drizzle ORM.
 
 ## Installation
 
 ```bash
-npm install @rebasepro/postgresql @rebasepro/core
+pnpm add @rebasepro/server-postgresql
 ```
 
-## Usage
+## What This Package Does
 
-### Basic Setup with React Hook
+Implements the Rebase `DatabaseAdapter` / `BackendBootstrapper` interfaces for PostgreSQL. It provides connection pooling, a Drizzle-based data driver, Postgres LISTEN/NOTIFY realtime, auth table management, entity history, schema generation, branching, read replicas, and WebSocket support. Plug it into `@rebasepro/server-core` via `createPostgresAdapter()` or `createPostgresBootstrapper()`.
 
-```typescript
-import { usePostgresDataSource } from "@rebasepro/postgresql";
-import { Rebase } from "@rebasepro/core";
-
-function App() {
-    const dataSource = usePostgresDataSource({
-        baseUrl: "http://localhost:3001",
-        websocketUrl: "ws://localhost:3001", // Optional, will be inferred from baseUrl
-        headers: { // Optional
-            "Authorization": "Bearer your-token"
-        }
-    });
-
-    return (
-        <Rebase
-            dataSource={dataSource}
-            collections={collections}
-            // ... other props
-        />
-    );
-}
-```
+## Key Exports
 
-### Creating Data Source Directly
+| Export | Description |
+|--------|-------------|
+| `createPostgresAdapter(config)` | Creates a `DatabaseAdapter` for use with `initializeRebaseBackend({ database: ... })`. Recommended API. |
+| `createPostgresBootstrapper(config)` | Lower-level `BackendBootstrapper` factory. Used internally by the adapter. |
+| `createPostgresDatabaseConnection(url, schema?, poolConfig?)` | Creates a production-grade pooled Drizzle connection. Returns `{ db, pool, connectionString }`. |
+| `createDirectDatabaseConnection(url, schema?, poolConfig?)` | Non-pooled connection for LISTEN/NOTIFY and advisory locks (bypasses PgBouncer). |
+| `createReadReplicaConnection(url, schema?, poolConfig?)` | Read-only connection for routing reads to replicas. |
+| `PostgresBackendDriver` | The `DataDriver` implementation — CRUD, filtering, RLS, subcollections, admin SQL. |
+| `RealtimeService` | Postgres LISTEN/NOTIFY-based `RealtimeProvider`. |
+| `DatabasePoolManager` | Per-branch/per-tenant dynamic pool management (used with `ADMIN_CONNECTION_STRING`). |
+| `PostgresCollectionRegistry` | Collection → Drizzle table registry with enum and relation tracking. |
+| `BranchService` | Database branching (schema-level isolation). |
+| `generateDrizzleSchema(collections)` | Generates Drizzle schema code from collection definitions. |
+| `createAuthSchema(schemaName?)` | Generates Drizzle tables for the auth system (`users`, `roles`, `user_roles`). |
 
-```typescript
-import { createPostgresDataSource } from "@rebasepro/postgresql";
+## Quick Start
 
-const dataSource = createPostgresDataSource({
-    baseUrl: "http://localhost:3001",
-    websocketUrl: "ws://localhost:3001"
+```typescript
+import { createPostgresDatabaseConnection } from "@rebasepro/server-postgresql";
+import { createPostgresAdapter } from "@rebasepro/server-postgresql";
+import { initializeRebaseBackend } from "@rebasepro/server-core";
+import * as schema from "./generated/schema";
+
+// Create connection
+const { db, pool } = createPostgresDatabaseConnection(
+  process.env.DATABASE_URL,
+  schema
+);
+
+// Create adapter and pass to server-core
+const database = createPostgresAdapter({
+  connection: db,
+  connectionString: process.env.DATABASE_URL,
+  schema: { tables: schema },
 });
-```
 
-## Features
-
-- **Real-time Synchronization**: WebSocket-based real-time updates for collections and entities
-- **Automatic Reconnection**: Built-in reconnection logic with exponential backoff
-- **Type Safety**: Full TypeScript support with Rebase core types
-- **Error Handling**: Comprehensive error handling with custom error types
-- **Connection Management**: Connection status monitoring and queue management
-
-## API
-
-### Configuration
+const backend = await initializeRebaseBackend({
+  app,
+  server,
+  database,
+  collections,
+  auth: { /* ... */ },
+});
 
-```typescript
-interface PostgresDataSourceConfig {
-    baseUrl: string;           // Backend server URL
-    websocketUrl?: string;     // WebSocket URL (optional)
-    headers?: Record<string, string>; // Custom headers (optional)
-}
+// Graceful shutdown
+process.on("SIGTERM", async () => {
+  await backend.shutdown();
+  await pool.end();
+});
 ```
 
-### Methods
-
-The PostgreSQL data source implements all Rebase `DataSource` methods:
-
-- `fetchCollection<M>(props): Promise<Entity<M>[]>`
-- `fetchEntity<M>(props): Promise<Entity<M> | undefined>`
-- `saveEntity<M>(props): Promise<Entity<M>>`
-- `deleteEntity<M>(props): Promise<void>`
-- `checkUniqueField(...): Promise<boolean>`
-- `generateEntityId(...): string`
-- `countEntities<M>(props): Promise<number>`
-- `listenCollection<M>(props): () => void`
-- `listenEntity<M>(props): () => void`
-
-## Backend Requirements
-
-This client expects a WebSocket-enabled backend that handles the following message types:
-
-- `FETCH_COLLECTION`
-- `FETCH_ENTITY`
-- `SAVE_ENTITY`
-- `DELETE_ENTITY`
-- `CHECK_UNIQUE_FIELD`
-- `GENERATE_ENTITY_ID`
-- `COUNT_ENTITIES`
-- `subscribe_collection`
-- `subscribe_entity`
-- `unsubscribe`
-
-## Development
-
-This package is part of the Rebase monorepo. For development instructions, see the main repository README.
-
-## License
-
-MIT
+## Connection Pool Defaults
+
+| Option | Default |
+|--------|---------|
+| `max` | 20 |
+| `idleTimeoutMillis` | 30,000 |
+| `connectionTimeoutMillis` | 10,000 |
+| `queryTimeout` | 30,000 |
+| `statementTimeout` | 30,000 |
+| `keepAlive` | true |
+
+## Related Packages
+
+| Package | Role |
+|---------|------|
+| `@rebasepro/server-core` | Backend orchestrator that consumes this adapter |
+| `@rebasepro/types` | Shared interfaces (`DatabaseAdapter`, `BackendBootstrapper`, `DataDriver`) |
+| `@rebasepro/sdk-generator` | Generates typed SDKs from collections |
+| `@rebasepro/common` | Default collections and shared utilities |

package/dist/common/src/util/permissions.d.ts

@@ -1,6 +1,14 @@
-import { AuthController, Entity, EntityCollection, User } from "@rebasepro/types";
-export declare function checkOperation<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, entity: Entity<M> | null, targetOperation: "select" | "insert" | "update" | "delete"): boolean;
-export declare function canReadCollection<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>): boolean;
-export declare function canEditEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, path: string, entity: Entity<M> | null): boolean;
-export declare function canCreateEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, path: string, entity: Entity<M> | null): boolean;
-export declare function canDeleteEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, path: string, entity: Entity<M> | null): boolean;
+import { Entity, EntityCollection, User } from "@rebasepro/types";
+/**
+ * Minimal auth context for permission checking.
+ * Only requires the user object — avoids forcing callers to construct
+ * a full AuthController just to check permissions.
+ */
+export interface AuthContext<USER extends User = User> {
+    user: USER | null;
+}
+export declare function checkOperation<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, entity: Entity<M> | null, targetOperation: "select" | "insert" | "update" | "delete"): boolean;
+export declare function canReadCollection<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>): boolean;
+export declare function canEditEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;
+export declare function canCreateEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;
+export declare function canDeleteEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;

package/dist/index.es.js

@@ -3964,39 +3964,18 @@ function serializePropertyToServer(value, property) {
       }
       return value;
     }
-    case "binary":
-      if (typeof value === "string") {
-        if (value.startsWith("data:application/octet-stream;base64,")) {
-          const base64Data = value.split(",")[1];
-          if (base64Data) {
-            return Buffer.from(base64Data, "base64");
-          }
-        }
-      }
-      if (Buffer.isBuffer(value)) {
-        return value;
-      }
+    case "binary": {
+      const decoded = tryDecodeBase64DataUrl(value);
+      if (decoded) return decoded;
+      if (Buffer.isBuffer(value)) return value;
       return value;
+    }
     case "string":
-      if (typeof value === "string") {
-        if (value.startsWith("data:application/octet-stream;base64,")) {
-          const base64Data = value.split(",")[1];
-          if (base64Data) {
-            return Buffer.from(base64Data, "base64");
-          }
-        }
-      }
-      return value;
-    default:
-      if (typeof value === "string") {
-        if (value.startsWith("data:application/octet-stream;base64,")) {
-          const base64Data = value.split(",")[1];
-          if (base64Data) {
-            return Buffer.from(base64Data, "base64");
-          }
-        }
-      }
+    default: {
+      const decoded = tryDecodeBase64DataUrl(value);
+      if (decoded) return decoded;
       return value;
+    }
   }
 }
 async function parseDataFromServer(data, collection, db, registry) {
@@ -4116,21 +4095,36 @@ async function parseDataFromServer(data, collection, db, registry) {
   }
   return result;
 }
-function parsePropertyFromServer(value, property, collection, propertyKey) {
-  if (value === null || value === void 0) {
-    return value;
+function tryDecodeBase64DataUrl(value) {
+  if (typeof value !== "string") return null;
+  if (!value.startsWith("data:application/octet-stream;base64,")) return null;
+  const base64Data = value.split(",")[1];
+  return base64Data ? Buffer.from(base64Data, "base64") : null;
+}
+function tryResolveBuffer(value) {
+  if (Buffer.isBuffer(value)) return value;
+  if (typeof value === "object" && value !== null) {
+    const rawVal = value;
+    if (rawVal.type === "Buffer" && Array.isArray(rawVal.data)) {
+      return Buffer.from(rawVal.data);
+    }
   }
+  return null;
+}
+function bufferToStringOrBase64(buf) {
+  for (let i = 0; i < buf.length; i++) {
+    const b = buf[i];
+    if ((b < 32 || b > 126) && b !== 9 && b !== 10 && b !== 13) {
+      return `data:application/octet-stream;base64,${buf.toString("base64")}`;
+    }
+  }
+  return buf.toString("utf8");
+}
+function parsePropertyFromServer(value, property, collection, propertyKey) {
+  if (value === null || value === void 0) return value;
   switch (property.type) {
     case "binary": {
-      let buf = null;
-      if (Buffer.isBuffer(value)) {
-        buf = value;
-      } else if (typeof value === "object" && value !== null) {
-        const rawVal = value;
-        if (rawVal.type === "Buffer" && Array.isArray(rawVal.data)) {
-          buf = Buffer.from(rawVal.data);
-        }
-      }
+      const buf = tryResolveBuffer(value);
       if (buf) {
         return `data:application/octet-stream;base64,${buf.toString("base64")}`;
       }
@@ -4138,28 +4132,9 @@ function parsePropertyFromServer(value, property, collection, propertyKey) {
     }
     case "string": {
       if (typeof value === "string") return value;
-      let isBuffer = false;
-      let buf = null;
-      if (Buffer.isBuffer(value)) {
-        isBuffer = true;
-        buf = value;
-      } else if (typeof value === "object" && value !== null) {
-        const rawVal = value;
-        if (rawVal.type === "Buffer" && Array.isArray(rawVal.data)) {
-          isBuffer = true;
-          buf = Buffer.from(rawVal.data);
-        }
-      }
-      if (isBuffer && buf) {
-        let isPrintable = true;
-        for (let i = 0; i < buf.length; i++) {
-          const b = buf[i];
-          if ((b < 32 || b > 126) && b !== 9 && b !== 10 && b !== 13) {
-            isPrintable = false;
-            break;
-          }
-        }
-        return isPrintable ? buf.toString("utf8") : `data:application/octet-stream;base64,${buf.toString("base64")}`;
+      const buf = tryResolveBuffer(value);
+      if (buf) {
+        return bufferToStringOrBase64(buf);
       }
       if (typeof value === "object" && value !== null) {
         try {
@@ -4273,28 +4248,9 @@ function parsePropertyFromServer(value, property, collection, propertyKey) {
       return null;
     }
     default: {
-      let isBuffer = false;
-      let buf = null;
-      if (Buffer.isBuffer(value)) {
-        isBuffer = true;
-        buf = value;
-      } else if (typeof value === "object" && value !== null) {
-        const rawVal = value;
-        if (rawVal.type === "Buffer" && Array.isArray(rawVal.data)) {
-          isBuffer = true;
-          buf = Buffer.from(rawVal.data);
-        }
-      }
-      if (isBuffer && buf) {
-        let isPrintable = true;
-        for (let i = 0; i < buf.length; i++) {
-          const b = buf[i];
-          if ((b < 32 || b > 126) && b !== 9 && b !== 10 && b !== 13) {
-            isPrintable = false;
-            break;
-          }
-        }
-        return isPrintable ? buf.toString("utf8") : `data:application/octet-stream;base64,${buf.toString("base64")}`;
+      const buf = tryResolveBuffer(value);
+      if (buf) {
+        return bufferToStringOrBase64(buf);
       }
       return value;
     }
@@ -6487,12 +6443,12 @@ class EntityPersistService {
    */
   extractCauseMessage(error) {
     if (!error || typeof error !== "object") return null;
-    const err = error;
-    if (err.cause && typeof err.cause === "object") {
-      const deeper = this.extractCauseMessage(err.cause);
+    if (!(error instanceof Error)) return null;
+    if (error.cause && typeof error.cause === "object") {
+      const deeper = this.extractCauseMessage(error.cause);
       if (deeper) return deeper;
-      if (err.cause instanceof Error && err.cause.message) {
-        return err.cause.message;
+      if (error.cause instanceof Error && error.cause.message) {
+        return error.cause.message;
       }
     }
     return null;
@@ -6513,12 +6469,17 @@ class EntityPersistService {
    */
   extractPgError(error) {
     if (!error || typeof error !== "object") return null;
-    const err = error;
-    if (err.code && /^[0-9A-Z]{5}$/.test(err.code)) {
-      return err;
+    if (!(error instanceof Error)) {
+      if ("cause" in error && error.cause && typeof error.cause === "object") {
+        return this.extractPgError(error.cause);
+      }
+      return null;
+    }
+    if ("code" in error && typeof error.code === "string" && /^[0-9A-Z]{5}$/.test(error.code)) {
+      return error;
     }
-    if (err.cause && typeof err.cause === "object") {
-      return this.extractPgError(err.cause);
+    if (error.cause && typeof error.cause === "object") {
+      return this.extractPgError(error.cause);
     }
     return null;
   }
@@ -7633,7 +7594,7 @@ class AuthenticatedPostgresBackendDriver {
     return this.withTransaction((delegate) => delegate.deleteEntity(props));
   }
   async deleteAll(path2) {
-    return this.delegate.deleteAll(path2);
+    return this.withTransaction((delegate) => delegate.deleteAll(path2));
   }
   async checkUniqueField(path2, name, value, entityId, collection) {
     return this.withTransaction((delegate) => delegate.checkUniqueField(path2, name, value, entityId, collection));
@@ -7712,6 +7673,7 @@ class DatabasePoolManager {
     }
     await Promise.all(promises2);
     this.pools.clear();
+    this.drizzleInstances.clear();
   }
 }
 function createAuthSchema(usersSchemaName = "rebase") {
@@ -9605,20 +9567,19 @@ class RealtimeService extends EventEmitter {
   }
 }
 const PostgresRealtimeProvider = RealtimeService;
-const clientSessions = /* @__PURE__ */ new Map();
 const WS_RATE_LIMIT = 2e3;
 const WS_RATE_WINDOW_MS = 6e4;
 const ADMIN_ONLY_TYPES = /* @__PURE__ */ new Set(["EXECUTE_SQL", "FETCH_DATABASES", "FETCH_ROLES", "FETCH_UNMAPPED_TABLES", "FETCH_TABLE_METADATA", "FETCH_CURRENT_DATABASE", "CREATE_BRANCH", "DELETE_BRANCH", "LIST_BRANCHES"]);
 function extractErrorMessage(error) {
   if (!error) return "Unknown error";
-  if (typeof error === "object") {
-    const err = error;
-    if (err.cause) {
-      return extractErrorMessage(err.cause);
-    }
-    if (typeof err.message === "string") {
-      return err.message;
+  if (error instanceof Error) {
+    if ("cause" in error && error.cause) {
+      return extractErrorMessage(error.cause);
     }
+    return error.message;
+  }
+  if (typeof error === "object" && "message" in error && typeof error.message === "string") {
+    return error.message;
   }
   return String(error);
 }
@@ -9626,14 +9587,10 @@ function isAdminSession(session) {
   if (!session?.user) return false;
   if (session.user.isAdmin) return true;
   if (!session.user.roles) return false;
-  return session.user.roles.some((r) => {
-    if (typeof r === "string") return r === "admin";
-    if (r && typeof r === "object" && "isAdmin" in r) return r.isAdmin;
-    if (r && typeof r === "object" && "id" in r) return r.id === "admin";
-    return false;
-  });
+  return session.user.roles.some((r) => r === "admin");
 }
 function createPostgresWebSocket(server, realtimeService, driver, authConfig, authAdapter) {
+  const clientSessions = /* @__PURE__ */ new Map();
   const isProduction = process.env.NODE_ENV === "production";
   const wsDebug = (...args) => {
     if (!isProduction) console.debug(...args);
@@ -9772,13 +9729,23 @@ function createPostgresWebSocket(server, realtimeService, driver, authConfig, au
         }
         const getScopedDelegate = async () => {
           const session = clientSessions.get(clientId);
-          if ("withAuth" in driver && typeof driver.withAuth === "function") {
+          if (typeof driver.withAuth === "function") {
             try {
               const userForAuth = session?.user ? {
                 uid: session.user.userId,
+                displayName: null,
+                email: null,
+                photoURL: null,
+                providerId: "websocket",
+                isAnonymous: false,
                 roles: session.user.roles ?? []
               } : {
                 uid: "anon",
+                displayName: null,
+                email: null,
+                photoURL: null,
+                providerId: "websocket",
+                isAnonymous: true,
                 roles: ["anon"]
               };
               return await driver.withAuth(userForAuth);