@rebasepro/server-core 0.6.1 → 0.8.0

package/src/init.ts

@@ -1,10 +1,11 @@
 import {
     AuthAdapter,
     BackendBootstrapper,
-    BackendHooks,
     BootstrappedAuth,
     DatabaseAdapter,
     DataDriver,
+    DataSourceDefinition,
+    EntityCallbacks,
     EntityCollection,
     HealthCheckResult,
     InitializedDriver,
@@ -13,9 +14,11 @@ import {
     RealtimeProvider,
     SecurityRule
 } from "@rebasepro/types";
+import { createDataSourceRegistry, resolveDataSource } from "@rebasepro/common";
 import { BackendCollectionRegistry } from "./collections/BackendCollectionRegistry";
 import { loadCollectionsFromDirectory } from "./collections/loader";
 import { DEFAULT_DRIVER_ID, DefaultDriverRegistry, DriverRegistry } from "./services/driver-registry";
+import { createRoutedRealtimeService } from "./services/routed-realtime-service";
 import { Server } from "http";
 
 import { RestApiGenerator } from "./api/rest/api-generator";
@@ -80,7 +83,7 @@ export interface RebaseAuthConfig {
      *
      * When a request includes `Authorization: Bearer <serviceKey>`, it is
      * granted admin-level access without JWT verification. This is the
-     * Rebase equivalent of a Firebase Service Account key.
+     * Rebase equivalent of a Service Account key.
      *
      * Generate with: `node -e "logger.info(require('crypto').randomBytes(48).toString('base64'))"`
      *
@@ -89,6 +92,14 @@ export interface RebaseAuthConfig {
      */
     serviceKey?: string;
     email?: EmailConfig;
+    // ── Convenience shortcuts ─────────────────────────────────────────
+    // Each named field below is syntactic sugar that internally resolves
+    // to an `OAuthProvider` via the corresponding `create*Provider`
+    // factory at startup. They are equivalent to constructing the
+    // provider manually and passing it in the `providers` array.
+    //
+    // For providers not listed here, or for full control over the
+    // provider configuration, use the `providers` array directly.
     google?: { clientId: string; clientSecret?: string };
     linkedin?: { clientId: string; clientSecret: string };
     github?: { clientId: string; clientSecret: string };
@@ -102,8 +113,31 @@ export interface RebaseAuthConfig {
     slack?: { clientId: string; clientSecret: string };
     spotify?: { clientId: string; clientSecret: string };
     defaultRole?: string;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    providers?: OAuthProvider<any>[];
+    /**
+     * Canonical array of OAuth providers.
+     *
+     * This is the primary extension point for **all** OAuth integrations.
+     * Each entry is an `OAuthProvider<unknown>` constructed via one of
+     * the `create*Provider` factories exported from `@rebasepro/server-core`
+     * (e.g. `createGoogleProvider`, `createGitHubProvider`).
+     *
+     * The named convenience fields above (`google`, `github`, etc.) are
+     * automatically resolved into this array at startup. You can mix both
+     * approaches; named fields and explicit entries are merged (named
+     * fields are appended after explicit entries).
+     *
+     * @example
+     * ```ts
+     * import { createGoogleProvider } from "@rebasepro/server-core";
+     *
+     * auth: {
+     *   providers: [
+     *     createGoogleProvider({ clientId: "…", clientSecret: "…" }),
+     *   ],
+     * }
+     * ```
+     */
+    providers?: OAuthProvider<unknown>[];
     /**
      * Override specific parts of the built-in auth implementation.
      *
@@ -123,7 +157,11 @@ export interface RebaseAuthConfig {
      */
     hooks?: AuthHooks;
 
-    [key: string]: unknown;
+    /**
+     * Enable magic link (passwordless email) authentication.
+     * Requires email to be configured.
+     */
+    magicLink?: boolean;
 }
 
 export interface RebaseBackendConfig {
@@ -133,6 +171,16 @@ export interface RebaseBackendConfig {
     app: Hono<HonoEnv>;
     basePath?: string;
 
+    /**
+     * Declared data sources, shared with the frontend `<Rebase dataSources>`.
+     *
+     * Used to resolve each collection's engine (capabilities) and transport.
+     * Collections on a `direct`/`custom` transport are client-only: the backend
+     * still owns their schema/registry but does **not** generate server data
+     * routes for them. Server-mediated sources (the default) need no entry.
+     */
+    dataSources?: DataSourceDefinition[];
+
     /**
      * Database bootstrappers.
      */
@@ -169,11 +217,22 @@ export interface RebaseBackendConfig {
     /**
      * Storage configuration. Accepts:
      *
-     * - A `BackendStorageConfig` object (`{ type: 'local' | 's3', ... }`)
-     * - A `StorageController` instance (for custom providers like GCS, Azure, etc.)
+     * - A `BackendStorageConfig` object (`{ type: 'local' | 's3' | 'gcs', ... }`)
+     * - A `StorageController` instance (for custom providers like Azure, etc.)
      * - A `Record<string, ...>` of either, for multi-backend setups
      */
     storage?: BackendStorageConfig | StorageController | Record<string, BackendStorageConfig | StorageController>;
+
+    /**
+     * Declared storage sources. Drives the client-side StorageSourceRegistry
+     * and the transport distinction (server vs direct).
+     *
+     * Server-backed sources are auto-derived from the `storage` map — you
+     * only need explicit entries for "direct" transport sources (e.g.
+     * external storage) that the backend does not proxy.
+     */
+    storageSources?: import("@rebasepro/types").StorageSourceDefinition[];
+
     history?: unknown;
     /**
      * Default security rules applied to any collection that does not define
@@ -223,14 +282,24 @@ export interface RebaseBackendConfig {
         origin: string | string[] | ((origin: string) => boolean);
     };
     /**
-     * Backend-level hooks for intercepting collection entity data
-     * at the REST API boundary. These run server-side after database
-     * operations and before API responses are sent.
+     * Global lifecycle callbacks applied to every collection.
+     *
+     * Same type as per-collection `callbacks` — fires on **every** data path
+     * (REST API, WebSocket / realtime, server-side `rebase.data`).
      *
-     * Complement the per-collection `EntityCallbacks` system which
-     * handles collection CRUD operations.
+     * Execution order: global callbacks → collection callbacks → property callbacks.
+     *
+     * @example
+     * ```ts
+     * callbacks: {
+     *     afterRead({ entity, collection }) {
+     *         console.log(`Read ${collection.slug}/${entity.id}`);
+     *         return entity;
+     *     }
+     * }
+     * ```
      */
-    hooks?: BackendHooks;
+    callbacks?: EntityCallbacks;
 }
 
 /**
@@ -313,6 +382,16 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
     configureMiddlewares(config.app, basePath, isProduction, config);
 
     const collectionRegistry = new BackendCollectionRegistry();
+    // Declared data sources — drives engine resolution (capabilities) and the
+    // server-vs-direct transport distinction. Set before collections register
+    // so normalization can resolve each collection's engine.
+    const dataSourceRegistry = createDataSourceRegistry(config.dataSources);
+    collectionRegistry.setDataSources(dataSourceRegistry);
+
+    // Global lifecycle callbacks — applied to every collection, on all data paths.
+    if (config.callbacks) {
+        collectionRegistry.setGlobalCallbacks(config.callbacks);
+    }
     let activeCollections = config.collections || [];
     if (config.collectionsDir && activeCollections.length === 0) {
         activeCollections = await loadCollectionsFromDirectory(config.collectionsDir);
@@ -401,6 +480,56 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
     const defaultBootstrapper = bootstrappers.find(b => b.id === defaultDriverId || b.type === defaultDriverId) || bootstrappers[0];
     const defaultRealtimeService = defaultDriverResult.realtimeProvider;
 
+    // Resolve a collection path (e.g. "products", "authors/1/posts") to its
+    // data-source key — shared by the data-driver router and the realtime
+    // router. Falls back to the default key for unknown paths.
+    const keyForCollectionPath = (collectionPath: string): string => {
+        const slug = collectionPath.replace(/^\/+/, "").split("/")[0]?.split("?")[0];
+        if (!slug) return DEFAULT_DRIVER_ID;
+        const collection = collectionRegistry.get(slug) ?? collectionRegistry.getCollectionByPath(slug);
+        if (!collection) return DEFAULT_DRIVER_ID;
+        return resolveDataSource(collection, dataSourceRegistry).key;
+    };
+
+    // ── Data-source misconfiguration check ────────────────────────────────
+    // A server-transport collection whose resolved data-source key has no
+    // registered driver delegate would silently fall back to the default
+    // driver — i.e. land in the wrong database. Warn loudly so this surfaces
+    // at boot rather than as mysterious data going to the wrong engine.
+    {
+        const unresolved = new Map<string, string[]>();
+        const nonRlsEngines = new Set<string>();
+        for (const collection of activeCollections) {
+            const ds = resolveDataSource(collection, dataSourceRegistry);
+            if (ds.transport !== "server") continue; // direct/custom are client-only
+            // Server engines without row-level security enforce authorization
+            // only at the application layer — surface this so it isn't a
+            // silent assumption. (The default Postgres engine supports RLS.)
+            if (!ds.capabilities.supportsRLS) nonRlsEngines.add(ds.engine);
+            if (ds.key === DEFAULT_DRIVER_ID) continue; // always maps to the default
+            if (!driverRegistry.has(ds.key)) {
+                const slugs = unresolved.get(ds.key) ?? [];
+                slugs.push(collection.slug ?? collection.name ?? "?");
+                unresolved.set(ds.key, slugs);
+            }
+        }
+        for (const [key, slugs] of unresolved) {
+            logger.warn(
+                `[DataSource] No driver registered for data source "${key}" ` +
+                `(used by: ${slugs.join(", ")}). These collections will fall back to the ` +
+                `default driver "${defaultDriverId}" — register a bootstrapper with this id, ` +
+                `or mark the data source as a direct/custom transport in \`dataSources\`.`
+            );
+        }
+        for (const engine of nonRlsEngines) {
+            logger.warn(
+                `[DataSource] Engine "${engine}" does not support row-level security; ` +
+                `authorization for its collections is enforced only at the application layer ` +
+                `(authentication still applies). Ensure app-level checks or engine-native rules are in place.`
+            );
+        }
+    }
+
     // 2. Initialize Auth & History via the default driver's bootstrapper
     let authConfigResult: BootstrappedAuth | undefined = undefined;
     let serviceKey: string | undefined;
@@ -439,6 +568,23 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
                 }
             }
 
+            // The built-in auth subsystem (users, sessions, repository) is
+            // bootstrapped on the DEFAULT driver. If the auth collection is
+            // routed to a non-default data source, login would read/write the
+            // default engine while the collection's data views hit another —
+            // a split-brain user store. Warn loudly.
+            if (safeAuthConfig.collection) {
+                const authDs = resolveDataSource(safeAuthConfig.collection, dataSourceRegistry);
+                if (authDs.key !== DEFAULT_DRIVER_ID) {
+                    logger.warn(
+                        `[Auth] The auth collection "${safeAuthConfig.collection.slug}" is on data source ` +
+                        `"${authDs.key}", but the built-in auth system always uses the default data source. ` +
+                        `Move the auth collection to the default data source, or replace auth with an AuthAdapter ` +
+                        `that manages users in "${authDs.key}".`
+                    );
+                }
+            }
+
             // Extract the collection-level auth config (if `auth` is an object, not just `true`)
             const collectionAuth = safeAuthConfig.collection ? safeAuthConfig.collection.auth : undefined;
             const collectionAuthConfig = (typeof collectionAuth === "object" && collectionAuth !== null) ? collectionAuth : undefined;
@@ -516,8 +662,7 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
 
         if (!isAuthAdapter(config.auth)) {
             const safeAuthConfig = config.auth as RebaseAuthConfig;
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const oauthProviders: OAuthProvider<any>[] = [...(safeAuthConfig.providers || [])];
+            const oauthProviders: OAuthProvider<unknown>[] = [...(safeAuthConfig.providers || [])];
 
             // Resolve configured OAuth providers via data-driven registration.
             // Each entry maps a config key to its factory function name and required fields.
@@ -561,7 +706,8 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
                 oauthProviders,
                 serviceKey,
                 authHooks: safeAuthConfig.hooks,
-                collectionAuthConfig
+                collectionAuthConfig,
+                enableMagicLink: safeAuthConfig.magicLink ?? false
             });
         }
 
@@ -631,7 +777,10 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
 
         const storageRoutes = createStorageRoutes({
             controller: storageController,
-            requireAuth: resolveRequireAuth(config.auth)
+            registry: storageRegistry,
+            sources: config.storageSources,
+            requireAuth: resolveRequireAuth(config.auth),
+            authAdapter
         });
 
         // Apply a permissive body limit specifically for the upload endpoint
@@ -668,18 +817,39 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
             );
         }
 
+        // Multi-data-source routing: when more than one database engine is
+        // registered (e.g. Postgres + MongoDB in one instance), resolve the
+        // delegate per request from the request's collection data source. The
+        // auth middleware then scopes that delegate (RLS for Postgres, no-op
+        // for engines without `withAuth()`) into the request context. For a
+        // single-engine backend this is omitted — behaviour is unchanged.
+        const dataPathMarker = `${basePath}/data/`;
+        const resolveRequestDriver = (reqPath: string): DataDriver => {
+            const i = reqPath.indexOf(dataPathMarker);
+            const collectionPath = i >= 0 ? reqPath.slice(i + dataPathMarker.length) : reqPath;
+            const key = keyForCollectionPath(collectionPath);
+            // Use the authoritative default for the default key; otherwise the
+            // named delegate, falling back to default if it isn't registered.
+            if (!key || key === DEFAULT_DRIVER_ID) return defaultDriver;
+            return driverRegistry.get(key) ?? defaultDriver;
+        };
+        const multiEngine = bootstrappers.length > 1;
+        const resolveDriver = multiEngine ? ((c: { req: { path: string } }) => resolveRequestDriver(c.req.path)) : undefined;
+
         // Use adapter middleware when an AuthAdapter is available,
         // falling back to the built-in JWT middleware otherwise.
         if (authAdapter) {
             dataRouter.use("/*", createAdapterAuthMiddleware({
                 adapter: authAdapter,
                 driver: defaultDriver,
+                resolveDriver,
                 requireAuth: dataRequireAuth,
                 apiKeyStore
             }));
         } else {
             dataRouter.use("/*", createAuthMiddleware({
                 driver: defaultDriver,
+                resolveDriver,
                 requireAuth: dataRequireAuth,
                 serviceKey,
                 apiKeyStore
@@ -702,10 +872,16 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
             dataRouter.route("/", historyRoutes);
         }
 
+        // Only generate server data routes for server-mediated collections.
+        // Collections on a direct/custom transport are client-only — the
+        // backend must not expose a (mis-engined) endpoint for them.
+        const serverCollections = activeCollections.filter(
+            (collection) => resolveDataSource(collection, dataSourceRegistry).transport === "server"
+        );
+
         const restGenerator = new RestApiGenerator(
-            activeCollections,
+            serverCollections,
             defaultDriver,
-            config.hooks?.data,
             authAdapter
         );
         dataRouter.route("/", restGenerator.generateRoutes());
@@ -793,9 +969,10 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
             const functionsRouter = new Hono<HonoEnv>();
             functionsRouter.onError(errorHandler);
 
-            // Custom functions follow the same auth policy as data routes.
-            // Per-route auth can be further refined inside individual functions.
-            const functionsRequireAuth = resolveRequireAuth(config.auth);
+            // Custom functions do NOT require authentication at the global level by default.
+            // This allows custom functions to define public endpoints (like webhooks).
+            // Per-route auth can be further refined inside individual functions using `requireAuth`.
+            const functionsRequireAuth = false;
 
             // Use adapter middleware when available, fallback to built-in
             if (authAdapter) {
@@ -876,8 +1053,20 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
         }
     }
 
-    if (defaultBootstrapper.initializeWebsockets && defaultRealtimeService) {
-        await defaultBootstrapper.initializeWebsockets(config.server, defaultRealtimeService, defaultDriver, config.auth, authAdapter);
+    // With multiple realtime-capable engines, route subscriptions to the
+    // provider owning each collection (the realtime counterpart of the data
+    // router). The single WebSocket server is driven by this composite.
+    // Single-engine setups use the default provider unchanged.
+    const effectiveRealtimeService: RealtimeProvider = Object.keys(realtimeServices).length > 1
+        ? createRoutedRealtimeService({
+            providers: realtimeServices,
+            defaultKey: defaultDriverId,
+            resolveKey: keyForCollectionPath
+        })
+        : defaultRealtimeService as RealtimeProvider;
+
+    if (defaultBootstrapper.initializeWebsockets && effectiveRealtimeService) {
+        await defaultBootstrapper.initializeWebsockets(config.server, effectiveRealtimeService, defaultDriver, config.auth, authAdapter);
     }
 
     logger.info("Rebase Backend Initialized");
@@ -896,7 +1085,7 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
         driverRegistry,
         driver: defaultDriver,
         realtimeServices,
-        realtimeService: defaultRealtimeService as RealtimeProvider,
+        realtimeService: effectiveRealtimeService,
         auth: authConfigResult,
         history: historyConfigResult,
         storageRegistry,

package/src/services/routed-realtime-service.ts

@@ -0,0 +1,113 @@
+import { RealtimeProvider, Entity } from "@rebasepro/types";
+
+/**
+ * A realtime client message as forwarded by the WebSocket server.
+ */
+interface ClientMessage {
+    type: string;
+    payload?: Record<string, unknown>;
+    subscriptionId?: string;
+}
+
+/**
+ * The concrete realtime service surface the WebSocket server drives — the
+ * typed {@link RealtimeProvider} plus the client-connection methods that
+ * every engine's realtime service implements.
+ */
+export interface WsRealtimeService extends RealtimeProvider {
+    addClient(clientId: string, ws: unknown): void;
+    handleClientMessage(clientId: string, message: ClientMessage, authContext?: unknown): Promise<void> | void;
+}
+
+/** Channel/presence/broadcast messages are engine-agnostic pub/sub. */
+const CHANNEL_MESSAGE_TYPES = new Set([
+    "join_channel", "leave_channel", "broadcast",
+    "presence_track", "presence_untrack", "presence_state"
+]);
+
+export interface RoutedRealtimeOptions {
+    /** Per-engine realtime providers, keyed by data-source key. */
+    providers: Record<string, RealtimeProvider>;
+    /** Key of the default provider (handles channels/presence/broadcast). */
+    defaultKey: string;
+    /** Resolve a collection path to its data-source key. */
+    resolveKey: (collectionPath: string) => string;
+}
+
+/**
+ * Compose multiple per-engine {@link RealtimeProvider}s into one that routes
+ * each subscription to the provider owning the subscribed collection — the
+ * realtime counterpart of `buildRoutedRebaseData`.
+ *
+ * The WebSocket server stays single and engine-agnostic; this composite is
+ * passed in its place. Routing rules:
+ * - `subscribe_collection` / `subscribe_entity` → the provider for the
+ *   collection's data source (by `payload.path`).
+ * - `unsubscribe` → forwarded to all providers (a no-op on non-owners).
+ * - channel / presence / broadcast → the default provider (these are global
+ *   pub/sub, not bound to an engine).
+ * - `addClient` and lifecycle (`onServerReady`/`destroy`/`stopListening`) →
+ *   all providers (each registers its own ws close handler for cleanup).
+ */
+export function createRoutedRealtimeService(opts: RoutedRealtimeOptions): WsRealtimeService {
+    const { providers, defaultKey, resolveKey } = opts;
+
+    const asWs = (p: RealtimeProvider): WsRealtimeService => p as unknown as WsRealtimeService;
+    const all = (): WsRealtimeService[] => Object.values(providers).map(asWs);
+    const fallback = (): WsRealtimeService => asWs(providers[defaultKey] ?? Object.values(providers)[0]);
+    const forPath = (path?: string): WsRealtimeService => {
+        if (!path) return fallback();
+        const key = resolveKey(path);
+        return asWs(providers[key] ?? providers[defaultKey] ?? Object.values(providers)[0]);
+    };
+
+    return {
+        addClient(clientId, ws) {
+            for (const p of all()) p.addClient?.(clientId, ws);
+        },
+
+        async handleClientMessage(clientId, message, authContext) {
+            const { type } = message;
+            if (type === "subscribe_collection" || type === "subscribe_entity") {
+                await forPath(message.payload?.path as string | undefined)
+                    .handleClientMessage(clientId, message, authContext);
+                return;
+            }
+            if (type === "unsubscribe") {
+                // The owning provider acts; others no-op on an unknown id.
+                await Promise.all(all().map((p) => p.handleClientMessage(clientId, message, authContext)));
+                return;
+            }
+            // Channels/presence/broadcast (and anything else) → default provider.
+            await fallback().handleClientMessage(clientId, message, authContext);
+        },
+
+        subscribeToCollection(subscriptionId, config, callback) {
+            forPath((config as { path?: string }).path).subscribeToCollection(subscriptionId, config, callback);
+        },
+
+        subscribeToEntity(subscriptionId, config, callback) {
+            forPath((config as { path?: string }).path).subscribeToEntity(subscriptionId, config, callback);
+        },
+
+        unsubscribe(subscriptionId) {
+            for (const p of all()) p.unsubscribe(subscriptionId);
+        },
+
+        async notifyEntityUpdate(path: string, entityId: string, entity: Entity | null, databaseId?: string) {
+            await forPath(path).notifyEntityUpdate(path, entityId, entity, databaseId);
+        },
+
+        onServerReady(serverInfo) {
+            for (const p of all()) p.onServerReady?.(serverInfo);
+        },
+
+        async destroy() {
+            await Promise.all(all().map((p) => p.destroy?.()));
+        },
+
+        async stopListening() {
+            await Promise.all(all().map((p) => p.stopListening?.()));
+        }
+    };
+}