bunsane 0.3.0 → 0.3.2

package/core/app/bootstrap.ts

@@ -0,0 +1,133 @@
+import ApplicationLifecycle, {
+    ApplicationPhase,
+    type PhaseChangeEvent,
+} from "../ApplicationLifecycle";
+import { logger as MainLogger } from "../Logger";
+import ServiceRegistry from "../../service/ServiceRegistry";
+import { SchedulerManager } from "../SchedulerManager";
+import { registerScheduledTasks } from "../../scheduler";
+import {
+    RemoteManager,
+    registerRemoteHandlers,
+    setRemoteManager,
+    type RemoteManagerConfig,
+} from "../remote";
+import { setupGraphQL } from "./graphqlSetup";
+import { collectRestEndpoints } from "./restRegistry";
+
+const logger = MainLogger.child({ scope: "App" });
+
+export function createPhaseListener(app: any): (event: PhaseChangeEvent) => Promise<void> {
+    return async (event: PhaseChangeEvent) => {
+        const phase = event.detail;
+        logger.info(`Application phase changed to: ${phase}`);
+        for (const plugin of app.plugins) {
+            if (plugin.onPhaseChange) {
+                await plugin.onPhaseChange(phase, app);
+            }
+        }
+        switch (phase) {
+            case ApplicationPhase.DATABASE_READY:
+                await runDatabaseReadyPhase(app);
+                break;
+            case ApplicationPhase.SYSTEM_READY:
+                await runSystemReadyPhase(app);
+                break;
+            case ApplicationPhase.APPLICATION_READY:
+                await runApplicationReadyPhase(app);
+                break;
+        }
+    };
+}
+
+export async function runDatabaseReadyPhase(app: any): Promise<void> {
+    try {
+        await app.warmUpPreparedStatementCache();
+    } catch (error) {
+        logger.warn("Failed to warm up prepared statement cache:", error as any);
+    }
+}
+
+export async function runSystemReadyPhase(app: any): Promise<void> {
+    try {
+        const { CacheManager } = await import('../cache/CacheManager');
+        const cacheManager = CacheManager.getInstance();
+        const config = cacheManager.getConfig();
+
+        if (config.enabled) {
+            const isHealthy = await cacheManager.getProvider().ping();
+            if (isHealthy) {
+                logger.info({ scope: 'cache', component: 'App', msg: 'Cache health check passed' });
+            } else {
+                logger.warn({ scope: 'cache', component: 'App', msg: 'Cache health check failed' });
+            }
+        }
+    } catch (error) {
+        logger.warn({ scope: 'cache', component: 'App', msg: 'Cache health check error', error });
+    }
+
+    try {
+        setupGraphQL(app);
+
+        const services = ServiceRegistry.getServices();
+
+        const scheduler = SchedulerManager.getInstance();
+        scheduler.config.enableLogging = app.config.scheduler.logging;
+
+        for (const service of services) {
+            try {
+                registerScheduledTasks(service);
+            } catch (error) {
+                logger.warn(`Failed to register scheduled tasks for service ${service.constructor.name}`);
+                logger.warn(error);
+            }
+        }
+        logger.info(`Registered scheduled tasks for ${services.length} services`);
+
+        if (app.remoteConfig) {
+            try {
+                const rmConfig: RemoteManagerConfig = {
+                    appName: app.remoteConfig.appName || app.name,
+                    ...app.remoteConfig,
+                };
+                app.remote = new RemoteManager(rmConfig);
+                setRemoteManager(app.remote);
+                await app.remote.start();
+
+                for (const service of services) {
+                    try {
+                        registerRemoteHandlers(service);
+                    } catch (error) {
+                        logger.warn(`Failed to register remote handlers for service ${service.constructor.name}`);
+                        logger.warn(error);
+                    }
+                }
+                logger.info(`RemoteManager initialized for app "${rmConfig.appName}"`);
+            } catch (error) {
+                logger.error("Failed to start RemoteManager:");
+                logger.error(error);
+            }
+        }
+
+        collectRestEndpoints(app, services);
+
+        ApplicationLifecycle.setPhase(ApplicationPhase.APPLICATION_READY);
+    } catch (error) {
+        // SYSTEM_READY failures must not be swallowed silently. Without this,
+        // the app stays forever in SYSTEM_READY (isReady=false,
+        // /health/ready → 503 forever) and k8s rollout hangs with no
+        // observable cause. Surface so readiness probe reports it (C09).
+        app.isReady = false;
+        logger.fatal({ scope: 'app', component: 'App', err: error }, 'Fatal error during SYSTEM_READY phase — marking app unready');
+        if (process.env.NODE_ENV === 'test') {
+            throw error;
+        }
+        setTimeout(() => process.exit(1), 100).unref?.();
+    }
+}
+
+export async function runApplicationReadyPhase(app: any): Promise<void> {
+    if (process.env.NODE_ENV !== "test") {
+        app.start();
+    }
+}

package/core/app/cors.ts

@@ -0,0 +1,94 @@
+import type { CorsConfig } from "../App";
+
+export function assertValidCorsConfig(cors: CorsConfig): void {
+    if (cors.origin === undefined) {
+        throw new Error('[CORS] `origin` is required. Pass an explicit string, array, function, or "*" if you truly want to allow everyone.');
+    }
+    if (cors.credentials && cors.origin === '*') {
+        console.warn('[CORS] Warning: credentials=true with origin="*" is invalid per spec. Origin will be reflected from request.');
+    }
+}
+
+export function validateOrigin(
+    cors: CorsConfig | undefined,
+    requestOrigin: string | null | undefined,
+): string | null {
+    if (!cors || !requestOrigin) return null;
+
+    const configOrigin = cors.origin;
+
+    if (configOrigin === undefined) return null;
+
+    if (configOrigin === '*') {
+        return cors.credentials ? requestOrigin : '*';
+    }
+
+    if (typeof configOrigin === 'string') {
+        return requestOrigin === configOrigin ? configOrigin : null;
+    }
+
+    if (Array.isArray(configOrigin)) {
+        return configOrigin.includes(requestOrigin) ? requestOrigin : null;
+    }
+
+    if (typeof configOrigin === 'function') {
+        return configOrigin(requestOrigin) ? requestOrigin : null;
+    }
+
+    return null;
+}
+
+export function getCorsHeaders(
+    cors: CorsConfig | undefined,
+    req?: Request,
+): Record<string, string> {
+    if (!cors) return {};
+
+    const requestOrigin = req?.headers.get('Origin');
+    const allowedOrigin = validateOrigin(cors, requestOrigin);
+
+    if (requestOrigin && !allowedOrigin) return {};
+
+    const headers: Record<string, string> = {
+        'Access-Control-Allow-Methods': cors.methods?.join(', ') || 'GET, POST, PUT, DELETE, OPTIONS',
+        'Access-Control-Allow-Headers': cors.allowedHeaders?.join(', ') || 'Content-Type, Authorization',
+        'Vary': 'Origin',
+    };
+    if (allowedOrigin) {
+        headers['Access-Control-Allow-Origin'] = allowedOrigin;
+    }
+
+    if (cors.credentials) {
+        headers['Access-Control-Allow-Credentials'] = 'true';
+    }
+
+    if (cors.exposedHeaders?.length) {
+        headers['Access-Control-Expose-Headers'] = cors.exposedHeaders.join(', ');
+    }
+
+    if (cors.maxAge !== undefined) {
+        headers['Access-Control-Max-Age'] = String(cors.maxAge);
+    }
+
+    return headers;
+}
+
+export function addCorsHeaders(
+    response: Response,
+    cors: CorsConfig | undefined,
+    req?: Request,
+): Response {
+    const corsHeaders = getCorsHeaders(cors, req);
+    if (Object.keys(corsHeaders).length === 0) return response;
+
+    const newHeaders = new Headers(response.headers);
+    for (const [key, value] of Object.entries(corsHeaders)) {
+        newHeaders.set(key, value);
+    }
+
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: newHeaders,
+    });
+}

package/core/app/graphqlSetup.ts

@@ -0,0 +1,56 @@
+import ServiceRegistry from "../../service/ServiceRegistry";
+import { type Plugin } from "graphql-yoga";
+import { createYogaInstance } from "../../gql";
+import { createRequestContextPlugin } from "../RequestContext";
+
+export function setupGraphQL(app: any): void {
+    const schema = ServiceRegistry.getSchema();
+
+    const wrappedContextFactory = app.contextFactory
+        ? async (yogaContext: any) => {
+              const userContext = await app.contextFactory(yogaContext);
+              return {
+                  ...yogaContext,
+                  ...userContext,
+              };
+          }
+        : undefined;
+
+    const envDepth = process.env.GRAPHQL_MAX_DEPTH;
+    if (envDepth) {
+        app.graphqlMaxDepth = parseInt(envDepth, 10);
+    }
+    const envComplexity = process.env.GRAPHQL_MAX_COMPLEXITY;
+    if (envComplexity) {
+        const parsed = parseInt(envComplexity, 10);
+        if (Number.isFinite(parsed) && parsed >= 0) {
+            app.graphqlMaxComplexity = parsed;
+        }
+    }
+
+    const yogaOptions = {
+        cors: app.config.cors,
+        maxDepth: app.graphqlMaxDepth || undefined,
+        maxComplexity: app.graphqlMaxComplexity,
+    };
+
+    const effectivePlugins: Plugin[] = app.requestContextPluginEnabled
+        ? [createRequestContextPlugin(), ...app.yogaPlugins]
+        : [...app.yogaPlugins];
+
+    if (schema) {
+        app.yoga = createYogaInstance(
+            schema,
+            effectivePlugins,
+            wrappedContextFactory,
+            yogaOptions,
+        );
+    } else {
+        app.yoga = createYogaInstance(
+            undefined,
+            effectivePlugins,
+            wrappedContextFactory,
+            yogaOptions,
+        );
+    }
+}

package/core/app/healthEndpoints.ts

@@ -0,0 +1,31 @@
+import { deepHealthCheck, readinessCheck } from "../health";
+
+export async function handleHealth(_app: any): Promise<Response> {
+    const health = await deepHealthCheck();
+    return new Response(JSON.stringify(health.result), {
+        status: health.httpStatus,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+
+export async function handleReady(app: any): Promise<Response> {
+    const ready = await readinessCheck(app.isReady, app.isShuttingDown);
+    return new Response(JSON.stringify(ready.result), {
+        status: ready.httpStatus,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+
+export async function handleRemoteHealth(app: any): Promise<Response> {
+    if (!app.remote) {
+        return new Response(
+            JSON.stringify({ healthy: false, error: "Remote subsystem not enabled" }),
+            { status: 503, headers: { "Content-Type": "application/json" } },
+        );
+    }
+    const health = await app.remote.health();
+    return new Response(JSON.stringify(health), {
+        status: health.healthy ? 200 : 503,
+        headers: { "Content-Type": "application/json" },
+    });
+}

package/core/app/metricsCollector.ts

@@ -0,0 +1,27 @@
+import { logger as MainLogger } from "../Logger";
+import { SchedulerManager } from "../SchedulerManager";
+import { preparedStatementCache } from "../../database/PreparedStatementCache";
+import { getDbStats } from "../../database/instrumentedDb";
+
+const logger = MainLogger.child({ scope: "App" });
+
+export async function collectMetrics(app: any) {
+    let cacheStats = null;
+    try {
+        const { CacheManager } = await import('../cache/CacheManager');
+        cacheStats = await CacheManager.getInstance().getStats();
+    } catch (err) {
+        logger.warn({ err }, 'metrics: cache stats unavailable');
+    }
+
+    return {
+        timestamp: new Date().toISOString(),
+        uptime: process.uptime(),
+        process: process.memoryUsage(),
+        cache: cacheStats,
+        scheduler: SchedulerManager.getInstance().getMetrics(),
+        preparedStatements: preparedStatementCache.getStats(),
+        db: getDbStats(),
+        remote: app.remote ? app.remote.getMetrics() : null,
+    };
+}

package/core/app/preparedStatementWarmup.ts

@@ -0,0 +1,55 @@
+import { ComponentRegistry } from "../components";
+import { logger as MainLogger } from "../Logger";
+import { preparedStatementCache } from "../../database/PreparedStatementCache";
+import db from "../../database";
+
+const logger = MainLogger.child({ scope: "App" });
+
+export async function warmUpPreparedStatementCache(_app: any): Promise<void> {
+    const components = ComponentRegistry.getComponents();
+
+    if (components.length === 0) {
+        logger.trace("No components registered yet, skipping cache warm-up");
+        return;
+    }
+
+    const commonQueries: Array<{ sql: string; key: string }> = [];
+
+    commonQueries.push({
+        sql: "SELECT COUNT(*) as count FROM (SELECT DISTINCT ec.entity_id as id FROM entity_components ec WHERE ec.deleted_at IS NULL) AS subquery",
+        key: "count_all_entities",
+    });
+
+    for (let i = 0; i < Math.min(5, components.length); i++) {
+        const component = components[i];
+        if (component) {
+            const { name } = component;
+            const typeId = ComponentRegistry.getComponentId(name);
+            if (typeId) {
+                commonQueries.push({
+                    sql: `SELECT DISTINCT ec.entity_id as id FROM entity_components ec WHERE ec.type_id = '${typeId}' AND ec.deleted_at IS NULL LIMIT 10`,
+                    key: `find_${name.toLowerCase()}_sample`,
+                });
+            }
+        }
+    }
+
+    if (components.length >= 2) {
+        const typeIds = components
+            .slice(0, 3)
+            .map((component: { name: string; ctor: any }) =>
+                ComponentRegistry.getComponentId(component.name)
+            )
+            .filter((id: string | undefined) => id)
+            .join("','");
+
+        if (typeIds) {
+            commonQueries.push({
+                sql: `SELECT DISTINCT ec.entity_id as id FROM entity_components ec WHERE ec.type_id IN ('${typeIds}') AND ec.deleted_at IS NULL LIMIT 10`,
+                key: "find_multi_component_sample",
+            });
+        }
+    }
+
+    await preparedStatementCache.warmUp(commonQueries, db);
+}

package/core/app/processHandlers.ts

@@ -0,0 +1,43 @@
+import { logger as MainLogger } from "../Logger";
+
+const logger = MainLogger.child({ scope: "App" });
+
+export function registerProcessHandlers(app: any): void {
+    if (app.processHandlersRegistered) return;
+
+    app.sigTermHandler = () => {
+        logger.info({ scope: 'app', component: 'App', msg: 'Received SIGTERM' });
+        app.shutdown().finally(() => process.exit(0));
+    };
+    app.sigIntHandler = () => {
+        logger.info({ scope: 'app', component: 'App', msg: 'Received SIGINT' });
+        app.shutdown().finally(() => process.exit(0));
+    };
+    process.once('SIGTERM', app.sigTermHandler);
+    process.once('SIGINT', app.sigIntHandler);
+
+    app.unhandledRejectionHandler = (reason: unknown, _promise: Promise<unknown>) => {
+        logger.error({ scope: 'app', component: 'App', reason, msg: 'Unhandled promise rejection' });
+    };
+    app.uncaughtExceptionHandler = (error: Error) => {
+        logger.fatal({ scope: 'app', component: 'App', err: error, msg: 'Uncaught exception — shutting down' });
+        app.shutdown().finally(() => process.exit(1));
+    };
+    process.on('unhandledRejection', app.unhandledRejectionHandler);
+    process.on('uncaughtException', app.uncaughtExceptionHandler);
+
+    app.processHandlersRegistered = true;
+}
+
+export function unregisterProcessHandlers(app: any): void {
+    if (!app.processHandlersRegistered) return;
+    if (app.sigTermHandler) process.removeListener('SIGTERM', app.sigTermHandler);
+    if (app.sigIntHandler) process.removeListener('SIGINT', app.sigIntHandler);
+    if (app.unhandledRejectionHandler) process.removeListener('unhandledRejection', app.unhandledRejectionHandler);
+    if (app.uncaughtExceptionHandler) process.removeListener('uncaughtException', app.uncaughtExceptionHandler);
+    app.sigTermHandler = null;
+    app.sigIntHandler = null;
+    app.unhandledRejectionHandler = null;
+    app.uncaughtExceptionHandler = null;
+    app.processHandlersRegistered = false;
+}