@rebasepro/server-core 0.5.0 → 0.6.0

package/src/email/smtp-email-service.ts

@@ -1,5 +1,6 @@
 import { createTransport, Transporter } from "nodemailer";
 import { EmailService, EmailSendOptions, EmailConfig } from "./types";
+import { logger } from "../utils/logger";
 
 /**
  * Safely parse a hostname from a URL string
@@ -90,7 +91,7 @@ export class SMTPEmailService implements EmailService {
             });
         } catch (error: unknown) {
             const message = error instanceof Error ? error.message : String(error);
-            console.error("Failed to send email:", message);
+            logger.error("Failed to send email", { detail: message });
             throw new Error(`Failed to send email: ${message}`);
         }
     }
@@ -108,7 +109,7 @@ export class SMTPEmailService implements EmailService {
             return true;
         } catch (error: unknown) {
             const message = error instanceof Error ? error.message : String(error);
-            console.error("SMTP connection verification failed:", message);
+            logger.error("SMTP connection verification failed", { detail: message });
             return false;
         }
     }

package/src/env.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import * as crypto from "crypto";
+import { logger } from "./utils/logger";
 
 /**
  * Generate a cryptographically secure random secret (hex-encoded).
@@ -112,7 +113,7 @@ const rebaseEnvSchema = z.object({
     S3_ACCESS_KEY_ID: z.string().optional(),
     S3_SECRET_ACCESS_KEY: z.string().optional(),
     S3_ENDPOINT: z.string().url().optional(),
-    S3_FORCE_PATH_STYLE: optionalBoolString,
+    S3_FORCE_PATH_STYLE: optionalBoolString
 });
 
 /** Inferred type of the validated environment. */
@@ -157,8 +158,8 @@ export type RebaseEnv = z.infer<typeof rebaseEnvSchema>;
  * ```
  */
 export function loadEnv(): RebaseEnv;
-export function loadEnv<E extends z.AnyZodObject>(options: { extend: E }): RebaseEnv & z.infer<E>;
-export function loadEnv(options?: { extend?: z.AnyZodObject }): Record<string, unknown> {
+export function loadEnv<E extends z.ZodObject<z.ZodRawShape>>(options: { extend: E }): RebaseEnv & z.infer<E>;
+export function loadEnv(options?: { extend?: z.ZodObject<z.ZodRawShape> }): Record<string, unknown> {
     // Auto-generate dev secrets before validation so the Zod schema sees valid values.
     const isProduction = process.env.NODE_ENV === "production";
     const autoGeneratedSecrets: string[] = [];
@@ -186,15 +187,15 @@ export function loadEnv(options?: { extend?: z.AnyZodObject }): Record<string, u
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 message: "CORS_ORIGINS or FRONTEND_URL must be set in production to secure the API.",
-                path: ["CORS_ORIGINS"],
+                path: ["CORS_ORIGINS"]
             });
         }
         if (d.NODE_ENV === "production" && autoGeneratedSecrets.length > 0) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 message: `${autoGeneratedSecrets.join(", ")} must be explicitly set in production. ` +
-                    `Do not rely on auto-generated secrets outside development.`,
-                path: [autoGeneratedSecrets[0]],
+                    "Do not rely on auto-generated secrets outside development.",
+                path: [autoGeneratedSecrets[0]]
             });
         }
         if (d.NODE_ENV === "production" && !d.ALLOW_LOCALHOST_IN_PRODUCTION) {
@@ -204,7 +205,7 @@ export function loadEnv(options?: { extend?: z.AnyZodObject }): Record<string, u
                     ctx.addIssue({
                         code: z.ZodIssueCode.custom,
                         message: `Environment variable ${key} contains a local/loopback URL or host "${value}". Deployed instances must not connect to localhost.`,
-                        path: [key],
+                        path: [key]
                     });
                 }
             }
@@ -215,10 +216,10 @@ export function loadEnv(options?: { extend?: z.AnyZodObject }): Record<string, u
 
     // Warn after successful parse so the server still starts in dev.
     if (autoGeneratedSecrets.length > 0) {
-        console.warn(
+        logger.warn(
             `⚠️  Auto-generated secrets for: ${autoGeneratedSecrets.join(", ")}. ` +
-            `These are ephemeral — existing tokens will be invalidated on restart. ` +
-            `Set them explicitly in .env for persistent sessions.`,
+            "These are ephemeral — existing tokens will be invalidated on restart. " +
+            "Set them explicitly in .env for persistent sessions."
         );
     }
 

package/src/index.ts

@@ -44,6 +44,7 @@ export * from "./storage";
 export * from "./utils/logging";
 export * from "./utils/logger";
 export * from "./utils/request-logger";
+export * from "./utils/request-id";
 export * from "./utils/sql";
 
 // Entity history

package/src/init/docs.ts

@@ -0,0 +1,47 @@
+import { Hono } from "hono";
+import { EntityCollection } from "@rebasepro/types";
+import { HonoEnv } from "../api/types";
+import { logger } from "../utils/logger";
+
+export async function mountOpenApiDocs(
+    app: Hono<HonoEnv>,
+    basePath: string,
+    enableSwagger: boolean | undefined,
+    activeCollections: EntityCollection[],
+    requireAuth: boolean
+): Promise<void> {
+    if (enableSwagger === false || activeCollections.length === 0) {
+        return;
+    }
+
+    const { generateOpenApiSpec } = await import("../api/openapi-generator");
+
+    app.get(`${basePath}/docs`, (c) => {
+        const spec = generateOpenApiSpec(activeCollections, {
+            basePath,
+            requireAuth
+        });
+        return c.json(spec);
+    });
+
+    if (process.env.NODE_ENV !== "production") {
+        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` });
+    }
+}

package/src/init/health.ts

@@ -0,0 +1,37 @@
+import { DataDriver, HealthCheckResult, isSQLAdmin } from "@rebasepro/types";
+import { logger } from "../utils/logger";
+
+export function createHealthCheck(defaultDriver: DataDriver): () => Promise<HealthCheckResult> {
+    return async (): Promise<HealthCheckResult> => {
+        const start = performance.now();
+        try {
+            const admin = defaultDriver.admin;
+            if (isSQLAdmin(admin)) {
+                await admin.executeSql("SELECT 1");
+            } else {
+                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)
+                }
+            };
+        }
+    };
+}

package/src/init/middlewares.ts

@@ -0,0 +1,61 @@
+import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { csrf } from "hono/csrf";
+import { HonoEnv } from "../api/types";
+import { requestId } from "../utils/request-id";
+import { requestLogger } from "../utils/request-logger";
+import { logger } from "../utils/logger";
+
+interface MiddlewareConfig {
+    maxBodySize?: number;
+    csrf?: {
+        origin: string | string[] | ((origin: string) => boolean);
+    };
+}
+
+export function configureMiddlewares(
+    app: Hono<HonoEnv>,
+    basePath: string,
+    isProduction: boolean,
+    config: MiddlewareConfig
+): void {
+    // Request ID (correlation)
+    app.use(`${basePath}/*`, requestId());
+
+    // Request Body Size Limit
+    const maxBodySize = config.maxBodySize ?? 10 * 1024 * 1024; // 10MB default
+    if (maxBodySize > 0) {
+        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)
+    if (config.csrf?.origin) {
+        app.use(`${basePath}/*`, csrf({
+            origin: config.csrf.origin
+        }));
+        logger.info("CSRF protection enabled");
+    }
+
+    // CORS Warning
+    if (!isProduction && !process.env.CORS_ORIGINS && !process.env.FRONTEND_URL) {
+        logger.warn(
+            "No CORS configuration detected (CORS_ORIGINS / FRONTEND_URL not set). " +
+            "The API will accept requests from any origin. " +
+            "Set CORS_ORIGINS in your .env file to restrict access."
+        );
+    }
+
+    // Request Logging
+    app.use(`${basePath}/*`, requestLogger());
+}

package/src/init/shutdown.ts

@@ -0,0 +1,56 @@
+import { Server } from "http";
+import { RealtimeProvider } from "@rebasepro/types";
+import { logger } from "../utils/logger";
+
+interface ShutdownConfig {
+    server: Server;
+    cronScheduler?: { stop(): void };
+    realtimeServices: Record<string, RealtimeProvider>;
+}
+
+export function createShutdown(config: ShutdownConfig): (timeoutMs?: number) => Promise<void> {
+    return (timeoutMs = 15_000): Promise<void> => {
+        return new Promise<void>((resolve) => {
+            (async () => {
+                logger.info("Shutting down Rebase Backend...");
+
+                // 1. Stop cron scheduler
+                if (config.cronScheduler) {
+                    config.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(config.realtimeServices)) {
+                    try {
+                        if (typeof rt.destroy === "function") {
+                            await rt.destroy();
+                            logger.info(`Realtime service "${key}" destroyed`);
+                        } else if (typeof rt.stopListening === "function") {
+                            await rt.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();
+                }
+            })();
+        });
+    };
+}

package/src/init/storage.ts

@@ -0,0 +1,57 @@
+import {
+    BackendStorageConfig,
+    createStorageController,
+    DEFAULT_STORAGE_ID,
+    DefaultStorageRegistry,
+    StorageController,
+    StorageRegistry
+} from "../storage";
+import { logger } from "../utils/logger";
+
+export function initializeStorage(
+    storageConfig: BackendStorageConfig | StorageController | Record<string, BackendStorageConfig | StorageController> | undefined,
+    isProduction: boolean
+): { storageRegistry?: StorageRegistry; storageController?: StorageController } {
+    if (!storageConfig) return {};
+
+    logger.info("Configuring storage");
+    const controllers: Record<string, StorageController> = {};
+
+    const toController = (entry: BackendStorageConfig | StorageController, label: string): StorageController => {
+        if (typeof (entry as StorageController).putObject === "function") {
+            return entry as StorageController;
+        }
+        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 storageConfig === "object" &&
+        ("type" in storageConfig || typeof (storageConfig as StorageController).putObject === "function")
+    ) {
+        controllers[DEFAULT_STORAGE_ID] = toController(
+            storageConfig as BackendStorageConfig | StorageController,
+            DEFAULT_STORAGE_ID
+        );
+    } else {
+        for (const [storageId, entry] of Object.entries(
+            storageConfig as Record<string, BackendStorageConfig | StorageController>
+        )) {
+            controllers[storageId] = toController(entry, storageId);
+        }
+    }
+
+    if (Object.keys(controllers).length > 0) {
+        const storageRegistry = DefaultStorageRegistry.create(controllers);
+        const storageController = storageRegistry.getDefault();
+        logger.info("Initialized storage backends", { count: Object.keys(controllers).length });
+        return { storageRegistry, storageController };
+    }
+
+    return {};
+}