@rebasepro/server-core 0.4.0 → 0.6.0

package/src/init.ts

@@ -25,18 +25,18 @@ import { createBuiltinAuthAdapter } from "./auth/builtin-auth-adapter";
 import { errorHandler } from "./api/errors";
 import { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
-import { csrf } from "hono/csrf";
 import { HonoEnv } from "./api/types";
 import { configureLogLevel } from "./utils/logging";
 import { logger } from "./utils/logger";
-import { requestLogger } from "./utils/request-logger";
+import { configureMiddlewares } from "./init/middlewares";
+import { initializeStorage } from "./init/storage";
+import { mountOpenApiDocs } from "./init/docs";
+import { createHealthCheck } from "./init/health";
+import { createShutdown } from "./init/shutdown";
 import { configureJwt, requireAdmin, requireAuth } from "./auth";
 import {
     BackendStorageConfig,
-    createStorageController,
     createStorageRoutes,
-    DEFAULT_STORAGE_ID,
-    DefaultStorageRegistry,
     StorageController,
     StorageRegistry
 } from "./storage";
@@ -82,7 +82,7 @@ export interface RebaseAuthConfig {
      * granted admin-level access without JWT verification. This is the
      * Rebase equivalent of a Firebase Service Account key.
      *
-     * Generate with: `node -e "console.log(require('crypto').randomBytes(48).toString('base64'))"`
+     * Generate with: `node -e "logger.info(require('crypto').randomBytes(48).toString('base64'))"`
      *
      * Set via `REBASE_SERVICE_KEY` in your `.env`.
      * Must be at least 32 characters.
@@ -223,9 +223,9 @@ export interface RebaseBackendConfig {
         origin: string | string[] | ((origin: string) => boolean);
     };
     /**
-     * Backend-level hooks for intercepting admin data (users, roles)
-     * at the API boundary. These run server-side after database reads
-     * and before API responses are sent.
+     * 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.
      *
      * Complement the per-collection `EntityCallbacks` system which
      * handles collection CRUD operations.
@@ -309,36 +309,8 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
     const basePath = config.basePath || "/api";
     const isProduction = process.env.NODE_ENV === "production";
 
-    // ─── Request Body Size Limit ─────────────────────────────────────────
-    const maxBodySize = config.maxBodySize ?? 10 * 1024 * 1024; // 10MB default
-    if (maxBodySize > 0) {
-        config.app.use(`${basePath}/*`, bodyLimit({
-            maxSize: maxBodySize,
-            onError: (c) => {
-                return c.json({
-                    error: {
-                        message: `Request body too large. Maximum size is ${Math.round(maxBodySize / 1024 / 1024)}MB.`,
-                        code: "PAYLOAD_TOO_LARGE"
-                    }
-                }, 413);
-            }
-        }));
-        logger.info("Request body limit configured", { maxSizeMB: Math.round(maxBodySize / 1024 / 1024) });
-    }
-
-    // ─── CSRF Protection (opt-in) ────────────────────────────────────────
-    // BaaS APIs are consumed by mobile apps, SPAs on different origins, and
-    // CLI/SDK tools. CSRF is only enabled when the developer explicitly
-    // configures it with allowed origins.
-    if (config.csrf?.origin) {
-        config.app.use(`${basePath}/*`, csrf({
-            origin: config.csrf.origin
-        }));
-        logger.info("CSRF protection enabled");
-    }
-
-    // ─── Request Logging ─────────────────────────────────────────────────
-    config.app.use(`${basePath}/*`, requestLogger());
+    // Configure Hono middlewares (Request ID, body limit, CSRF, CORS warning, logging)
+    configureMiddlewares(config.app, basePath, isProduction, config);
 
     const collectionRegistry = new BackendCollectionRegistry();
     let activeCollections = config.collections || [];
@@ -380,7 +352,7 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
             initializeHistory: dbAdapter.initializeHistory,
             initializeWebsockets: dbAdapter.initializeWebsockets,
             getAdmin: dbAdapter.getAdmin,
-            mountRoutes: dbAdapter.mountRoutes,
+            mountRoutes: dbAdapter.mountRoutes
         };
         bootstrappers = [wrappedBootstrapper];
     }
@@ -395,7 +367,7 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
 
     // 1. Initialize all drivers
     for (const bootstrapper of bootstrappers) {
-        const b = bootstrapper as BackendBootstrapper & { id?: string; isDefault?: boolean };
+        const b = bootstrapper;
         logger.info("Running bootstrapper for driver", { driverId: b.id || bootstrapper.type });
         if (b.isDefault) {
             defaultDriverId = b.id || bootstrapper.type;
@@ -413,7 +385,9 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
 
         if (bootstrapper.initializeRealtime) {
             const realtime = await bootstrapper.initializeRealtime({}, driverResult);
-            realtimeServices[b.id || bootstrapper.type] = realtime as RealtimeProvider;
+            if (realtime) {
+                realtimeServices[b.id || bootstrapper.type] = realtime;
+            }
         }
     }
 
@@ -424,9 +398,7 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
     if (!defaultDriver || !defaultDriverResult) {
         throw new Error("Default driver not initialized by bootstrappers");
     }
-    const defaultBootstrapper = bootstrappers.find(b => (b as BackendBootstrapper & {
-        id?: string
-    }).id === defaultDriverId || b.type === defaultDriverId) || bootstrappers[0];
+    const defaultBootstrapper = bootstrappers.find(b => b.id === defaultDriverId || b.type === defaultDriverId) || bootstrappers[0];
     const defaultRealtimeService = defaultDriverResult.realtimeProvider;
 
     // 2. Initialize Auth & History via the default driver's bootstrapper
@@ -449,11 +421,27 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
             // Populate authConfigResult for backward compatibility
             // (the return type still exposes `auth?: BootstrappedAuth`)
             authConfigResult = {
-                userService: authAdapter.userManagement ?? {},
+                userService: authAdapter.userManagement ?? {}
             };
         } else {
             // ── RebaseAuthConfig — wrap in built-in adapter ──
             const safeAuthConfig = config.auth as RebaseAuthConfig;
+
+            // Auto-discover the auth collection from activeCollections if not explicitly set
+            if (!safeAuthConfig.collection) {
+                const foundAuthCollection = activeCollections.find(c => {
+                    const isAuth = c.auth;
+                    return isAuth === true || (isAuth && typeof isAuth === "object" && isAuth.enabled === true);
+                });
+                if (foundAuthCollection) {
+                    safeAuthConfig.collection = foundAuthCollection;
+                    logger.info("Auto-discovered auth collection from collection definitions", { slug: foundAuthCollection.slug });
+                }
+            }
+
+            // 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;
             if (safeAuthConfig.jwtSecret) {
                 configureJwt({
                     secret: safeAuthConfig.jwtSecret,
@@ -467,7 +455,7 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
                 if (safeAuthConfig.serviceKey.length < 32) {
                     throw new Error(
                         "REBASE_SERVICE_KEY is too short. Must be at least 32 characters. " +
-                        "Generate one with: node -e \"console.log(require('crypto').randomBytes(48).toString('base64'))\""
+                        "Generate one with: node -e \"logger.info(require('crypto').randomBytes(48).toString('base64'))\""
                     );
                 }
                 serviceKey = safeAuthConfig.serviceKey;
@@ -478,23 +466,8 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
                 logger.info("Bootstrapping authentication via driver protocol");
                 authConfigResult = await defaultBootstrapper.initializeAuth(config.auth, defaultDriverResult);
 
-                // Build the built-in auth adapter from bootstrapper results
-                if (authConfigResult) {
-                    const oauthProviders: OAuthProvider<unknown>[] = [...(safeAuthConfig.providers || [])];
-                    // OAuth providers are resolved later in route mounting,
-                    // but we need them here for the adapter
-                    authAdapter = createBuiltinAuthAdapter({
-                        authRepository: authConfigResult.authRepository as import("./auth/interfaces").AuthRepository ?? authConfigResult.userService as import("./auth/interfaces").AuthRepository,
-                        emailService: authConfigResult.emailService as import("./email").EmailService,
-                        emailConfig: safeAuthConfig.email,
-                        allowRegistration: safeAuthConfig.allowRegistration ?? false,
-                        defaultRole: safeAuthConfig.defaultRole,
-                        oauthProviders,
-                        serviceKey,
-                        hooks: config.hooks,
-                        authHooks: safeAuthConfig.hooks,
-                    });
-                }
+                // The built-in auth adapter is created after OAuth providers
+                // are resolved (below) so it only needs to be constructed once.
 
                 logger.info("Authentication initialized");
             } else {
@@ -527,50 +500,12 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
     }
 
     // 3. Initialize Storage
-    let storageRegistry: StorageRegistry | undefined;
-    let storageController: StorageController | undefined;
-
-    if (config.storage) {
-        logger.info("Configuring storage");
-        const controllers: Record<string, StorageController> = {};
-
-        // Helper: resolve a single storage entry to a controller
-        const toController = (entry: BackendStorageConfig | StorageController, label: string): StorageController => {
-            // Duck-type: if it has putObject, it's already a controller instance
-            if (typeof (entry as StorageController).putObject === "function") {
-                return entry as StorageController;
-            }
-            // Otherwise it's a config object — use the built-in factory
-            const conf = entry as BackendStorageConfig;
-            if (isProduction && conf.type === "local") {
-                logger.warn(`Storage backend "${label}" uses local filesystem in production. ` +
-                    "Files will be lost on container restart. " +
-                    "Configure S3-compatible storage or a custom StorageController.");
-            }
-            return createStorageController(conf);
-        };
-
-        if (typeof config.storage === "object" && ("type" in config.storage || typeof (config.storage as StorageController).putObject === "function")) {
-            // Single storage config or controller
-            controllers[DEFAULT_STORAGE_ID] = toController(config.storage as BackendStorageConfig | StorageController, DEFAULT_STORAGE_ID);
-        } else {
-            // Multi-backend record
-            for (const [storageId, entry] of Object.entries(config.storage as Record<string, BackendStorageConfig | StorageController>)) {
-                controllers[storageId] = toController(entry, storageId);
-            }
-        }
-
-        if (Object.keys(controllers).length > 0) {
-            storageRegistry = DefaultStorageRegistry.create(controllers);
-            storageController = storageRegistry.getDefault();
-            logger.info("Initialized storage backends", { count: Object.keys(controllers).length });
-        }
-    }
+    const { storageRegistry, storageController } = initializeStorage(config.storage, isProduction);
 
     // basePath already resolved above
 
     // 4. Mount API Routes
-    if (config.auth && authAdapter) {
+    if (config.auth) {
         // ── Auth Capabilities Endpoint ───────────────────────────────────
         // Exposes adapter capabilities so the frontend knows what's available
         // (login form vs external redirect, OAuth providers, etc.)
@@ -584,70 +519,39 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const oauthProviders: OAuthProvider<any>[] = [...(safeAuthConfig.providers || [])];
 
-            if (safeAuthConfig.google?.clientId) {
-                const { createGoogleProvider } = await import("./auth");
-                oauthProviders.push(createGoogleProvider(safeAuthConfig.google));
-            }
-
-            if (safeAuthConfig.linkedin?.clientId && safeAuthConfig.linkedin?.clientSecret) {
-                const { createLinkedinProvider } = await import("./auth");
-                oauthProviders.push(createLinkedinProvider(safeAuthConfig.linkedin as {
-                    clientId: string;
-                    clientSecret: string
-                }));
-            }
-
-            if (safeAuthConfig.github?.clientId && safeAuthConfig.github?.clientSecret) {
-                const { createGitHubProvider } = await import("./auth");
-                oauthProviders.push(createGitHubProvider(safeAuthConfig.github));
-            }
-
-            if (safeAuthConfig.microsoft?.clientId && safeAuthConfig.microsoft?.clientSecret) {
-                const { createMicrosoftProvider } = await import("./auth");
-                oauthProviders.push(createMicrosoftProvider(safeAuthConfig.microsoft));
-            }
-
-            if (safeAuthConfig.apple?.clientId && safeAuthConfig.apple?.teamId && safeAuthConfig.apple?.keyId && safeAuthConfig.apple?.privateKey) {
-                const { createAppleProvider } = await import("./auth");
-                oauthProviders.push(createAppleProvider(safeAuthConfig.apple));
-            }
-
-            if (safeAuthConfig.facebook?.clientId && safeAuthConfig.facebook?.clientSecret) {
-                const { createFacebookProvider } = await import("./auth");
-                oauthProviders.push(createFacebookProvider(safeAuthConfig.facebook));
-            }
-
-            if (safeAuthConfig.twitter?.clientId && safeAuthConfig.twitter?.clientSecret) {
-                const { createTwitterProvider } = await import("./auth");
-                oauthProviders.push(createTwitterProvider(safeAuthConfig.twitter));
-            }
-
-            if (safeAuthConfig.discord?.clientId && safeAuthConfig.discord?.clientSecret) {
-                const { createDiscordProvider } = await import("./auth");
-                oauthProviders.push(createDiscordProvider(safeAuthConfig.discord));
-            }
-
-            if (safeAuthConfig.gitlab?.clientId && safeAuthConfig.gitlab?.clientSecret) {
-                const { createGitLabProvider } = await import("./auth");
-                oauthProviders.push(createGitLabProvider(safeAuthConfig.gitlab));
-            }
-
-            if (safeAuthConfig.bitbucket?.clientId && safeAuthConfig.bitbucket?.clientSecret) {
-                const { createBitbucketProvider } = await import("./auth");
-                oauthProviders.push(createBitbucketProvider(safeAuthConfig.bitbucket));
-            }
-
-            if (safeAuthConfig.slack?.clientId && safeAuthConfig.slack?.clientSecret) {
-                const { createSlackProvider } = await import("./auth");
-                oauthProviders.push(createSlackProvider(safeAuthConfig.slack));
-            }
-
-            if (safeAuthConfig.spotify?.clientId && safeAuthConfig.spotify?.clientSecret) {
-                const { createSpotifyProvider } = await import("./auth");
-                oauthProviders.push(createSpotifyProvider(safeAuthConfig.spotify));
+            // Resolve configured OAuth providers via data-driven registration.
+            // Each entry maps a config key to its factory function name and required fields.
+            const OAUTH_PROVIDERS: Array<{
+                key: keyof RebaseAuthConfig;
+                factory: string;
+                requiredFields: string[];
+            }> = [
+                { key: "google", factory: "createGoogleProvider", requiredFields: ["clientId"] },
+                { key: "linkedin", factory: "createLinkedinProvider", requiredFields: ["clientId", "clientSecret"] },
+                { key: "github", factory: "createGitHubProvider", requiredFields: ["clientId", "clientSecret"] },
+                { key: "microsoft", factory: "createMicrosoftProvider", requiredFields: ["clientId", "clientSecret"] },
+                { key: "apple", factory: "createAppleProvider", requiredFields: ["clientId", "teamId", "keyId", "privateKey"] },
+                { key: "facebook", factory: "createFacebookProvider", requiredFields: ["clientId", "clientSecret"] },
+                { key: "twitter", factory: "createTwitterProvider", requiredFields: ["clientId", "clientSecret"] },
+                { key: "discord", factory: "createDiscordProvider", requiredFields: ["clientId", "clientSecret"] },
+                { key: "gitlab", factory: "createGitLabProvider", requiredFields: ["clientId", "clientSecret"] },
+                { key: "bitbucket", factory: "createBitbucketProvider", requiredFields: ["clientId", "clientSecret"] },
+                { key: "slack", factory: "createSlackProvider", requiredFields: ["clientId", "clientSecret"] },
+                { key: "spotify", factory: "createSpotifyProvider", requiredFields: ["clientId", "clientSecret"] }
+            ];
+
+            for (const { key, factory, requiredFields } of OAUTH_PROVIDERS) {
+                const providerConfig = safeAuthConfig[key] as Record<string, unknown> | undefined;
+                if (providerConfig && requiredFields.every(f => Boolean(providerConfig[f]))) {
+                    const authModule = await import("./auth");
+                    const createFn = (authModule as unknown as Record<string, (cfg: unknown) => OAuthProvider<unknown>>)[factory];
+                    oauthProviders.push(createFn(providerConfig));
+                }
             }
 
             // Re-create the built-in adapter with all resolved OAuth providers
+            const reCollectionAuth = safeAuthConfig.collection ? safeAuthConfig.collection.auth : undefined;
+            const collectionAuthConfig = (typeof reCollectionAuth === "object" && reCollectionAuth !== null) ? reCollectionAuth : undefined;
             authAdapter = createBuiltinAuthAdapter({
                 authRepository: authConfigResult!.authRepository as import("./auth/interfaces").AuthRepository ?? authConfigResult!.userService as import("./auth/interfaces").AuthRepository,
                 emailService: authConfigResult!.emailService as import("./email").EmailService,
@@ -656,13 +560,13 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
                 defaultRole: safeAuthConfig.defaultRole,
                 oauthProviders,
                 serviceKey,
-                hooks: config.hooks,
                 authHooks: safeAuthConfig.hooks,
+                collectionAuthConfig
             });
         }
 
         // ── Mount auth & admin routes via the adapter ────────────────────
-        if (authAdapter.createAuthRoutes) {
+        if (authAdapter && authAdapter.createAuthRoutes) {
             const authRoutes = authAdapter.createAuthRoutes();
             if (authRoutes) {
                 config.app.route(`${basePath}/auth`, authRoutes);
@@ -670,7 +574,7 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
             }
         }
 
-        if (authAdapter.createAdminRoutes) {
+        if (authAdapter && authAdapter.createAdminRoutes) {
             const adminRoutes = authAdapter.createAdminRoutes();
             if (adminRoutes) {
                 config.app.route(`${basePath}/admin`, adminRoutes);
@@ -690,7 +594,7 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
         // Mount API key admin routes
         const apiKeyRoutes = createApiKeyRoutes({
             store: apiKeyStore,
-            serviceKey,
+            serviceKey
         });
         config.app.route(`${basePath}/admin/api-keys`, apiKeyRoutes);
         logger.info("API key admin routes mounted", { path: `${basePath}/admin/api-keys` });
@@ -721,7 +625,7 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
         // maxFileSize (default 50MB), which overrides the global API body limit.
         const storageMaxSize = (
             config.storage && typeof config.storage === "object" && "type" in config.storage
-                ? (config.storage as BackendStorageConfig & { maxFileSize?: number }).maxFileSize
+                ? (config.storage as BackendStorageConfig).maxFileSize
                 : undefined
         ) ?? 50 * 1024 * 1024;
 
@@ -771,14 +675,14 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
                 adapter: authAdapter,
                 driver: defaultDriver,
                 requireAuth: dataRequireAuth,
-                apiKeyStore,
+                apiKeyStore
             }));
         } else {
             dataRouter.use("/*", createAuthMiddleware({
                 driver: defaultDriver,
                 requireAuth: dataRequireAuth,
                 serviceKey,
-                apiKeyStore,
+                apiKeyStore
             }));
         }
 
@@ -798,45 +702,19 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
             dataRouter.route("/", historyRoutes);
         }
 
-        const restGenerator = new RestApiGenerator(activeCollections, defaultDriver, config.hooks?.data);
+        const restGenerator = new RestApiGenerator(
+            activeCollections,
+            defaultDriver,
+            config.hooks?.data,
+            authAdapter
+        );
         dataRouter.route("/", restGenerator.generateRoutes());
 
         config.app.route(`${basePath}/data`, dataRouter);
     }
 
     // ── OpenAPI / Swagger ─────────────────────────────────────────────────
-    if (config.enableSwagger !== false && activeCollections.length > 0) {
-        const { generateOpenApiSpec } = await import("./api/openapi-generator");
-
-        config.app.get(`${basePath}/docs`, (c) => {
-            const spec = generateOpenApiSpec(activeCollections, {
-                basePath,
-                requireAuth: resolveRequireAuth(config.auth)
-            });
-            return c.json(spec);
-        });
-
-        if (process.env.NODE_ENV !== "production") {
-            config.app.get(`${basePath}/swagger`, (c) => {
-                return c.html(`<!DOCTYPE html>
-<html>
-<head>
-    <title>Rebase API Documentation</title>
-    <meta charset="utf-8"/>
-    <meta name="viewport" content="width=device-width, initial-scale=1"/>
-    <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css"/>
-    <style>body{margin:0;padding:0;}</style>
-</head>
-<body>
-    <div id="swagger-ui"></div>
-    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
-    <script>SwaggerUIBundle({ url: '${basePath}/docs', dom_id: '#swagger-ui' });</script>
-</body>
-</html>`);
-            });
-            logger.info("Swagger UI available", { path: `${basePath}/swagger` });
-        }
-    }
+    await mountOpenApiDocs(config.app, basePath, config.enableSwagger, activeCollections, resolveRequireAuth(config.auth));
 
     // ─── Server-side singleton ────────────────────────────────────────────
     // Build the admin-level RebaseClient and expose it as the `rebase` singleton.
@@ -925,14 +803,14 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
                     adapter: authAdapter,
                     driver: defaultDriver,
                     requireAuth: functionsRequireAuth,
-                    apiKeyStore,
+                    apiKeyStore
                 }));
             } else {
                 functionsRouter.use("/*", createAuthMiddleware({
                     driver: defaultDriver,
                     requireAuth: functionsRequireAuth,
                     serviceKey,
-                    apiKeyStore,
+                    apiKeyStore
                 }));
             }
 
@@ -998,101 +876,21 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
         }
     }
 
-    if ((defaultBootstrapper as BackendBootstrapper & {
-        initializeWebsockets?: (...args: unknown[]) => unknown
-    }).initializeWebsockets) {
-        await (defaultBootstrapper as BackendBootstrapper & {
-            initializeWebsockets: (...args: unknown[]) => unknown
-        }).initializeWebsockets(config.server, defaultRealtimeService, defaultDriver, config.auth, authAdapter);
+    if (defaultBootstrapper.initializeWebsockets && defaultRealtimeService) {
+        await defaultBootstrapper.initializeWebsockets(config.server, defaultRealtimeService, defaultDriver, config.auth, authAdapter);
     }
 
     logger.info("Rebase Backend Initialized");
 
     // ── Deep Health Check ─────────────────────────────────────────────────
-    const healthCheck = async (): Promise<HealthCheckResult> => {
-        const start = performance.now();
-        try {
-            // Use admin.executeSql if available (Postgres), otherwise try fetchCollection as a probe
-            const admin = defaultDriver.admin;
-            if (isSQLAdmin(admin)) {
-                await admin.executeSql("SELECT 1");
-            } else {
-                // Fallback: try a lightweight fetch to confirm driver is responsive
-                await defaultDriver.fetchCollection({
-                    path: "__health_check_nonexistent__",
-                    limit: 1
-                });
-            }
-            const latencyMs = Math.round(performance.now() - start);
-            return {
-                healthy: true,
-                latencyMs
-            };
-        } catch (error: unknown) {
-            const latencyMs = Math.round(performance.now() - start);
-            logger.error("Health check failed", {
-                error: error instanceof Error ? error : new Error(String(error)),
-                latencyMs
-            });
-            return {
-                healthy: false,
-                latencyMs,
-                details: {
-                    error: error instanceof Error ? error.message : String(error)
-                }
-            };
-        }
-    };
+    const healthCheck = createHealthCheck(defaultDriver);
 
     // ── Graceful Shutdown ─────────────────────────────────────────────────
-    const shutdown = (timeoutMs = 15_000): Promise<void> => {
-        return new Promise<void>((resolve) => {
-            (async () => {
-                logger.info("Shutting down Rebase Backend...");
-
-                // 1. Stop cron scheduler
-                if (cronScheduler) {
-                    cronScheduler.stop();
-                    logger.info("Cron scheduler stopped");
-                }
-
-                // 2. Tear down realtime services (LISTEN clients, debounce timers,
-                //    subscriptions). Must happen BEFORE pool.end() so that pending
-                //    timer callbacks don't fire against a closed pool.
-                for (const [key, rt] of Object.entries(realtimeServices)) {
-                    try {
-                        const rtWithLifecycle = rt as RealtimeProvider & {
-                            destroy?: () => Promise<void>;
-                            stopListening?: () => Promise<void>
-                        };
-                        if (typeof rtWithLifecycle.destroy === "function") {
-                            await rtWithLifecycle.destroy();
-                            logger.info(`Realtime service "${key}" destroyed`);
-                        } else if (typeof rtWithLifecycle.stopListening === "function") {
-                            await rtWithLifecycle.stopListening();
-                            logger.info(`Realtime service "${key}" LISTEN client stopped`);
-                        }
-                    } catch (err) {
-                        logger.warn(`Error destroying realtime service "${key}":`, { error: err });
-                    }
-                }
-
-                // 3. Close the HTTP server (stop accepting, drain in-flight)
-                config.server.close(() => {
-                    logger.info("HTTP server closed");
-                    resolve();
-                });
-
-                // 4. Force-resolve after timeout (unless disabled with 0)
-                if (timeoutMs > 0) {
-                    setTimeout(() => {
-                        logger.warn(`Forced shutdown after ${timeoutMs / 1000}s timeout`);
-                        resolve();
-                    }, timeoutMs).unref();
-                }
-            })();
-        });
-    };
+    const shutdown = createShutdown({
+        server: config.server,
+        cronScheduler,
+        realtimeServices
+    });
 
     return {
         driverRegistry,

package/src/serve-spa.ts

@@ -2,6 +2,7 @@ import { Hono } from "hono";
 import { serveStatic } from "@hono/node-server/serve-static";
 import * as path from "path";
 import * as fs from "fs";
+import fsp from "node:fs/promises";
 import { logger } from "./utils/logger.js";
 
 /**
@@ -59,6 +60,9 @@ export function serveSPA<E extends import("hono").Env>(app: Hono<E>, config: Ser
     // Build list of paths to exclude from SPA handling
     const allExcludePaths = [apiBasePath, ...excludePaths];
 
+    // Cache the index.html content to avoid re-reading from disk on every navigation request.
+    let cachedHtml: string | null = null;
+
     // SPA fallback - serve index.html for all non-excluded routes
     app.get("*", async (c, next) => {
         // Skip excluded paths (API, health checks, etc.)
@@ -68,13 +72,16 @@ export function serveSPA<E extends import("hono").Env>(app: Hono<E>, config: Ser
 
         const indexPath = path.join(frontendPath, indexFile);
 
-        if (!fs.existsSync(indexPath)) {
-            logger.warn(`⚠️ Index file not found: ${indexPath}`);
-            return next();
+        if (!cachedHtml) {
+            try {
+                cachedHtml = await fsp.readFile(indexPath, "utf-8");
+            } catch {
+                logger.warn(`⚠️ Index file not found: ${indexPath}`);
+                return next();
+            }
         }
 
-        const html = fs.readFileSync(indexPath, "utf-8");
-        return c.html(html);
+        return c.html(cachedHtml);
     });
 
     logger.info(`✅ SPA serving enabled from: ${frontendPath}`);

package/src/services/driver-registry.ts

@@ -12,6 +12,7 @@
  */
 
 import { DataDriver } from "@rebasepro/types";
+import { logger } from "../utils/logger";
 
 /**
  * The default driver identifier used when:
@@ -95,7 +96,7 @@ export class DefaultDriverRegistry implements DriverRegistry {
             if (!registry.has(DEFAULT_DRIVER_ID) && registry.size() > 0) {
                 // If no explicit "(default)", use the first one as default
                 const firstId = Object.keys(input)[0];
-                console.warn(
+                logger.warn(
                     `[DriverRegistry] No "${DEFAULT_DRIVER_ID}" driver provided. ` +
                     `Using "${firstId}" as the default.`
                 );
@@ -108,7 +109,7 @@ export class DefaultDriverRegistry implements DriverRegistry {
 
     register(id: string, delegate: DataDriver): void {
         if (this.delegates.has(id)) {
-            console.warn(`[DriverRegistry] Overwriting driver with id "${id}"`);
+            logger.warn(`[DriverRegistry] Overwriting driver with id "${id}"`);
         }
         this.delegates.set(id, delegate);
     }
@@ -144,7 +145,7 @@ export class DefaultDriverRegistry implements DriverRegistry {
         }
 
         // Fallback to default with warning
-        console.warn(
+        logger.warn(
             `[DriverRegistry] Driver "${id}" not found, falling back to "${DEFAULT_DRIVER_ID}"`
         );
         return this.getDefault();