@qwickapps/server 1.2.0 → 1.3.0

package/dist/core/gateway.d.ts

@@ -2,63 +2,162 @@
  * Gateway Server for @qwickapps/server
  *
  * Provides a production-ready gateway pattern that:
- * 1. Serves the control panel UI (always responsive)
- * 2. Proxies API requests to an internal service
- * 3. Provides health and diagnostics endpoints
+ * 1. Proxies multiple apps mounted at configurable paths
+ * 2. Each app runs at `/` on its own internal port
+ * 3. Gateway handles path rewriting automatically
+ * 4. Provides health and diagnostics endpoints
  *
  * Architecture:
- *   Internet → Gateway (GATEWAY_PORT, public) → Service (SERVICE_PORT, internal)
+ *   Internet → Gateway (:3000) → [Control Panel (:3001), Admin (:3002), API (:3003), ...]
  *
- * The gateway is always responsive even if the internal service is down,
- * allowing diagnostics and error visibility.
+ * Port Scheme:
+ *   - 3000: Gateway (public)
+ *   - 3001: Control Panel
+ *   - 3002+: Additional apps
+ *
+ * Each app is isolated and can be served from any mount path without rebuilding.
  *
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
 import type { Application } from 'express';
 import type { Server } from 'http';
-import type { ControlPanelConfig, ControlPanelPlugin, Logger } from './types.js';
+import type { ControlPanelConfig, Logger } from './types.js';
+import type { Plugin, PluginConfig } from './plugin-registry.js';
 import { createControlPanel } from './control-panel.js';
 import { type LoggingConfig } from './logging.js';
+/**
+ * Maintenance mode configuration for a mounted app
+ */
+export interface MaintenanceConfig {
+    /** Enable maintenance mode - blocks all requests with maintenance page */
+    enabled: boolean;
+    /** Custom page title (default: "Under Maintenance") */
+    title?: string;
+    /** Custom message to display */
+    message?: string;
+    /**
+     * Expected time when service will be back.
+     * Can be ISO date string, relative time ("2 hours", "30 minutes"), or "soon"
+     */
+    expectedBackAt?: string;
+    /** URL for support/contact (shows "Contact Support" link) */
+    contactUrl?: string;
+    /** Allow specific paths to bypass maintenance (e.g., ["/api/health", "/api/status"]) */
+    bypassPaths?: string[];
+}
+/**
+ * Fallback page configuration when a service is unavailable (proxy error)
+ */
+export interface FallbackConfig {
+    /** Custom page title (default: "Service Unavailable") */
+    title?: string;
+    /** Custom message (default: "This service is temporarily unavailable") */
+    message?: string;
+    /** Show "Try Again" button (default: true) */
+    showRetry?: boolean;
+    /** Auto-refresh interval in seconds (0 = disabled, default: 30) */
+    autoRefresh?: number;
+}
+/**
+ * Configuration for a mounted app
+ */
+export interface MountedAppConfig {
+    /** Mount path (e.g., '/admin', '/api') */
+    path: string;
+    /** Display name for the app (used in status pages) */
+    name?: string;
+    /** App source configuration */
+    source: {
+        /** Proxy to an internal service */
+        type: 'proxy';
+        /** Target URL (e.g., 'http://localhost:3002') */
+        target: string;
+        /** Enable WebSocket proxying */
+        ws?: boolean;
+    } | {
+        /** Serve static files */
+        type: 'static';
+        /** Path to static files directory */
+        directory: string;
+        /** Enable SPA mode (serve index.html for all routes) */
+        spa?: boolean;
+    };
+    /** Whether to strip the mount path prefix when proxying (default: true) */
+    stripPrefix?: boolean;
+    /** Route guard for this app */
+    guard?: ControlPanelConfig['guard'];
+    /**
+     * Maintenance mode configuration.
+     * When enabled, all requests to this app show a maintenance page.
+     */
+    maintenance?: MaintenanceConfig;
+    /**
+     * Fallback page configuration for when the service is unavailable.
+     * Shown when proxy encounters connection errors (service down/crashed).
+     */
+    fallback?: FallbackConfig;
+}
 /**
  * Gateway configuration
  */
 export interface GatewayConfig {
-    /** Port for the gateway (public-facing). Defaults to GATEWAY_PORT env or 3101 */
-    gatewayPort?: number;
-    /** Port for the internal service. Defaults to SERVICE_PORT env or 3100 */
-    servicePort?: number;
-    /** Product name for the control panel */
+    /** Port for the gateway (public-facing). Defaults to GATEWAY_PORT env or 3000 */
+    port?: number;
+    /** Product name for the gateway */
     productName: string;
     /** Product version */
     version?: string;
     /**
-     * URL to the product logo image (SVG, PNG, etc.).
-     * Used on the default landing page when no frontend app is configured.
+     * URL path to the product logo icon (SVG, PNG, etc.).
+     * Used on landing pages and passed to the control panel React UI.
+     * Example: '/cpanel/logo.svg'
      */
-    logoUrl?: string;
-    /** Branding configuration */
+    logoIconUrl?: string;
+    /** Branding configuration (primaryColor, favicon) */
     branding?: ControlPanelConfig['branding'];
     /** CORS origins */
     corsOrigins?: string[];
-    /** Control panel plugins */
-    plugins?: ControlPanelPlugin[];
-    /** Quick links for the control panel */
-    links?: ControlPanelConfig['links'];
-    /** Path to custom React UI dist folder for the control panel */
-    customUiPath?: string;
     /**
-     * Mount path for the control panel.
-     * Defaults to '/cpanel'.
+     * Mounted apps configuration.
+     * Each app runs at `/` on its own port, gateway proxies to it at the configured path.
+     *
+     * @example
+     * ```typescript
+     * apps: [
+     *   { path: '/cpanel', source: { type: 'proxy', target: 'http://localhost:3001' } },
+     *   { path: '/admin', source: { type: 'proxy', target: 'http://localhost:3002', ws: true } },
+     *   { path: '/api', source: { type: 'proxy', target: 'http://localhost:3003' } },
+     *   { path: '/docs', source: { type: 'static', directory: './dist-docs', spa: true } },
+     * ]
+     * ```
      */
-    controlPanelPath?: string;
+    apps?: MountedAppConfig[];
     /**
-     * Route guard for the control panel.
-     * Defaults to auto-generated basic auth.
+     * Control panel configuration.
+     * The control panel is a special built-in app that can be enabled/disabled.
      */
-    controlPanelGuard?: ControlPanelConfig['guard'];
+    controlPanel?: {
+        /** Enable the built-in control panel (default: true) */
+        enabled?: boolean;
+        /** Mount path for control panel (default: '/cpanel') */
+        path?: string;
+        /** Port for internal control panel server (default: 3001) */
+        port?: number;
+        /** Control panel plugins */
+        plugins?: Array<{
+            plugin: Plugin;
+            config?: PluginConfig;
+        }>;
+        /** Quick links */
+        links?: ControlPanelConfig['links'];
+        /** Custom UI path */
+        customUiPath?: string;
+        /** Route guard */
+        guard?: ControlPanelConfig['guard'];
+    };
     /**
      * Frontend app configuration for the root path (/).
-     * If not provided, root path is not handled by the gateway.
+     * If not provided, shows a default landing page with system status.
      */
     frontendApp?: {
         /** Redirect to another URL */
@@ -74,84 +173,65 @@ export interface GatewayConfig {
                 label: string;
                 url: string;
             }>;
+            branding?: {
+                primaryColor?: string;
+            };
         };
     };
-    /**
-     * API paths to proxy to the internal service.
-     * Defaults to ['/api/v1'] if not specified.
-     * The gateway always proxies /health to the internal service.
-     */
-    proxyPaths?: string[];
     /** Logger instance */
     logger?: Logger;
     /** Logging configuration */
     logging?: LoggingConfig;
 }
-/**
- * Service factory function type
- * Called with the service port, should return an object with:
- * - app: Express application (or compatible)
- * - server: HTTP server (created by calling listen)
- * - shutdown: Async function to gracefully shut down the service
- */
-export interface ServiceFactory {
-    (port: number): Promise<{
-        app: Application;
-        server: Server;
-        shutdown: () => Promise<void>;
-    }>;
-}
 /**
  * Gateway instance returned by createGateway
  */
 export interface GatewayInstance {
-    /** The control panel instance */
-    controlPanel: ReturnType<typeof createControlPanel>;
-    /** The internal service (if started) */
-    service: {
-        app: Application;
-        server: Server;
-        shutdown: () => Promise<void>;
-    } | null;
-    /** Start the gateway and internal service */
+    /** The gateway Express app */
+    app: Application;
+    /** HTTP server */
+    server: Server | null;
+    /** The internal control panel (if enabled) */
+    controlPanel: ReturnType<typeof createControlPanel> | null;
+    /** Mounted apps information */
+    mountedApps: Array<{
+        path: string;
+        type: 'proxy' | 'static';
+        target?: string;
+    }>;
+    /** Start the gateway */
     start: () => Promise<void>;
     /** Stop everything gracefully */
     stop: () => Promise<void>;
     /** Gateway port */
-    gatewayPort: number;
-    /** Service port */
-    servicePort: number;
+    port: number;
 }
 /**
- * Create a gateway that proxies to an internal service
+ * Create a gateway that proxies to multiple internal services
  *
  * @param config - Gateway configuration
- * @param serviceFactory - Factory function to create the internal service
  * @returns Gateway instance
  *
  * @example
  * ```typescript
  * import { createGateway } from '@qwickapps/server';
  *
- * const gateway = createGateway(
- *   {
- *     productName: 'My Service',
- *     gatewayPort: 3101,
- *     servicePort: 3100,
+ * const gateway = createGateway({
+ *   productName: 'My Product',
+ *   port: 3000,
+ *   controlPanel: {
+ *     path: '/cpanel',
+ *     port: 3001,
+ *     plugins: [...],
  *   },
- *   async (port) => {
- *     const app = createMyApp();
- *     const server = app.listen(port);
- *     return {
- *       app,
- *       server,
- *       shutdown: async () => { server.close(); },
- *     };
- *   }
- * );
+ *   apps: [
+ *     { path: '/api', source: { type: 'proxy', target: 'http://localhost:3002' } },
+ *     { path: '/docs', source: { type: 'static', directory: './docs' } },
+ *   ],
+ * });
  *
  * await gateway.start();
  * ```
  */
-export declare function createGateway(config: GatewayConfig, serviceFactory: ServiceFactory): GatewayInstance;
+export declare function createGateway(config: GatewayConfig): GatewayInstance;
 //# sourceMappingURL=gateway.d.ts.map

package/dist/core/gateway.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../src/core/gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAmC,MAAM,SAAS,CAAC;AAG5E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAA4C,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAM5F;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IAEpB,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAE1C,mBAAmB;IACnB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IAEvB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAE/B,wCAAwC;IACxC,KAAK,CAAC,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAEpC,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAEhD;;;OAGG;IACH,WAAW,CAAC,EAAE;QACZ,8BAA8B;QAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,oCAAoC;QACpC,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,iCAAiC;QACjC,WAAW,CAAC,EAAE;YACZ,KAAK,EAAE,MAAM,CAAC;YACd,OAAO,CAAC,EAAE,MAAM,CAAC;YACjB,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB,KAAK,CAAC,EAAE,KAAK,CAAC;gBAAE,KAAK,EAAE,MAAM,CAAC;gBAAC,GAAG,EAAE,MAAM,CAAA;aAAE,CAAC,CAAC;SAC/C,CAAC;KACH,CAAC;IAEF;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAEtB,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QACtB,GAAG,EAAE,WAAW,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;KAC/B,CAAC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,YAAY,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;IAEpD,wCAAwC;IACxC,OAAO,EAAE;QACP,GAAG,EAAE,WAAW,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;KAC/B,GAAG,IAAI,CAAC;IAET,6CAA6C;IAC7C,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3B,iCAAiC;IACjC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC;IAEpB,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAkeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,EACrB,cAAc,EAAE,cAAc,GAC7B,eAAe,CAoOjB"}
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../src/core/gateway.ts"],"names":[],"mappings":"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"}