bunsane 0.3.1 → 0.3.2

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;
+}

package/core/app/requestRouter.ts

@@ -0,0 +1,309 @@
+import * as path from "path";
+import { logger as MainLogger } from "../Logger";
+import { getSerializedMetadataStorage } from "../metadata";
+import { addCorsHeaders, getCorsHeaders } from "./cors";
+import {
+    handleHealth,
+    handleReady,
+    handleRemoteHealth,
+} from "./healthEndpoints";
+import { routeStudio } from "./studioRouter";
+import { getDbStats } from "../../database/instrumentedDb";
+import type { RequestStats } from "../RequestContext";
+
+const logger = MainLogger.child({ scope: "App" });
+
+function combineSignals(signals: AbortSignal[]): AbortSignal {
+    const anyFn = (AbortSignal as any).any;
+    if (typeof anyFn === 'function') {
+        return anyFn.call(AbortSignal, signals);
+    }
+    const controller = new AbortController();
+    for (const s of signals) {
+        if (s.aborted) {
+            controller.abort((s as any).reason);
+            return controller.signal;
+        }
+        s.addEventListener('abort', () => controller.abort((s as any).reason), { once: true });
+    }
+    return controller.signal;
+}
+
+export async function handleRequest(app: any, req: Request): Promise<Response> {
+    const url = new URL(req.url);
+    const method = req.method;
+    const startTime = Date.now();
+
+    if (method === 'OPTIONS') {
+        return new Response(null, {
+            status: 204,
+            headers: getCorsHeaders(app.config.cors, req),
+        });
+    }
+
+    // Request timeout — combine framework wall-clock with client abort signal
+    // and rebind onto the request so downstream handlers (Yoga, REST) see
+    // cancellation propagation (C05).
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+        controller.abort(new Error(`Request timeout after 30000ms: ${method} ${url.pathname}`));
+        const stats = (req as any).__bunsaneStats as RequestStats | undefined;
+        logger.warn({
+            scope: 'App',
+            method,
+            path: url.pathname,
+            operationName: stats?.operationName,
+            dataLoaderCalls: stats?.dataLoaderCalls,
+            dbQueryCount: stats?.dbQueryCount,
+            msg: 'Request timeout',
+        }, `Request timeout: ${method} ${url.pathname}`);
+    }, 30000);
+    const combinedSignal = combineSignals([req.signal, controller.signal]);
+    req = new Request(req, { signal: combinedSignal });
+
+    const cors = app.config.cors;
+    const wrap = (response: Response) => addCorsHeaders(response, cors, req);
+
+    try {
+        if (url.pathname === "/health") {
+            const response = await handleHealth(app);
+            clearTimeout(timeoutId);
+            return wrap(response);
+        }
+
+        if (url.pathname === "/metrics") {
+            const metrics = await app.collectMetrics();
+            clearTimeout(timeoutId);
+            return wrap(new Response(JSON.stringify(metrics), {
+                status: 200,
+                headers: { "Content-Type": "application/json" },
+            }));
+        }
+
+        if (url.pathname === "/health/remote") {
+            const response = await handleRemoteHealth(app);
+            clearTimeout(timeoutId);
+            return wrap(response);
+        }
+
+        if (url.pathname === "/health/ready") {
+            const response = await handleReady(app);
+            clearTimeout(timeoutId);
+            return wrap(response);
+        }
+
+        if (url.pathname === "/openapi.json") {
+            clearTimeout(timeoutId);
+            return wrap(new Response(app.openAPISpecGenerator!.toJSON(), {
+                headers: { "Content-Type": "application/json" },
+            }));
+        }
+
+        if (url.pathname === "/docs") {
+            clearTimeout(timeoutId);
+            const swaggerUIHTML = `
+<!DOCTYPE html>
+<html>
+<head>
+    <title>${app.name} Documentation</title>
+    <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@5.10.3/swagger-ui.css" />
+    <style>
+        html { box-sizing: border-box; overflow: -moz-scrollbars-vertical; overflow-y: scroll; }
+        *, *:before, *:after { box-sizing: inherit; }
+        body { margin: 0; background: #fafafa; }
+    </style>
+</head>
+<body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@5.10.3/swagger-ui-bundle.js"></script>
+    <script>
+        window.onload = function() {
+            const ui = SwaggerUIBundle({
+                url: '/openapi.json',
+                dom_id: '#swagger-ui',
+                deepLinking: true,
+                presets: [
+                    SwaggerUIBundle.presets.apis,
+                    SwaggerUIBundle.presets.standalone
+                ],
+                plugins: [
+                    SwaggerUIBundle.plugins.DownloadUrl
+                ],
+                layout: "BaseLayout"
+            });
+        };
+    </script>
+</body>
+</html>`;
+            return wrap(new Response(swaggerUIHTML, {
+                headers: { "Content-Type": "text/html" },
+            }));
+        }
+
+        const studioApiResponse = await routeStudio(app, url, req, method);
+        if (studioApiResponse) {
+            clearTimeout(timeoutId);
+            return wrap(studioApiResponse);
+        }
+
+        if (
+            app.studioEnabled &&
+            (url.pathname === "/studio" || url.pathname.startsWith("/studio/"))
+        ) {
+            clearTimeout(timeoutId);
+
+            if (url.pathname.startsWith("/studio/api/")) {
+                return wrap(new Response(
+                    JSON.stringify({ error: "Studio API endpoint not found" }),
+                    { status: 404, headers: { "Content-Type": "application/json" } },
+                ));
+            }
+
+            if (!url.pathname.startsWith("/studio/assets/")) {
+                const studioIndexPath = path.join(
+                    import.meta.dirname,
+                    "..",
+                    "..",
+                    "studio",
+                    "dist",
+                    "index.html",
+                );
+                try {
+                    const studioFile = Bun.file(studioIndexPath);
+                    if (await studioFile.exists()) {
+                        let html = await studioFile.text();
+                        const metadata = getSerializedMetadataStorage();
+                        const metadataScript = `<script>window.bunsaneMetadata = ${JSON.stringify(metadata)};</script>`;
+                        html = html.replace("</head>", `${metadataScript}</head>`);
+                        return wrap(new Response(html, {
+                            headers: { "Content-Type": "text/html" },
+                        }));
+                    } else {
+                        return wrap(new Response(
+                            "Studio not built. Run `bun run build:studio` to build the studio.",
+                            { status: 404, headers: { "Content-Type": "text/plain" } },
+                        ));
+                    }
+                } catch (error) {
+                    console.log("Error loading studio index.html:", error);
+                    return wrap(new Response("Studio not available", {
+                        status: 404,
+                        headers: { "Content-Type": "text/plain" },
+                    }));
+                }
+            }
+        }
+
+        for (const [route, folder] of app.staticAssets) {
+            if (url.pathname.startsWith(route)) {
+                const relativePath = url.pathname.slice(route.length);
+                const filePath = path.join(folder, relativePath);
+                try {
+                    const file = Bun.file(filePath);
+                    if (await file.exists()) {
+                        clearTimeout(timeoutId);
+                        return wrap(new Response(file));
+                    }
+                } catch (error) {
+                    logger.error(`Error serving static file ${filePath}:`, error as any);
+                }
+            }
+        }
+
+        const endpointKey = `${method}:${url.pathname}`;
+        let endpoint = app.restEndpointMap.get(endpointKey);
+
+        if (!endpoint) {
+            for (const ep of app.restEndpoints) {
+                if (ep.method !== method) continue;
+                const pattern = ep.path.replace(/:[^/]+/g, '[^/]+');
+                const regex = new RegExp(`^${pattern}$`);
+                if (regex.test(url.pathname)) {
+                    endpoint = ep;
+                    break;
+                }
+            }
+        }
+
+        if (endpoint) {
+            try {
+                const result = await endpoint.handler(req);
+                const duration = Date.now() - startTime;
+                logger.trace(`REST ${method} ${url.pathname} completed in ${duration}ms`);
+
+                clearTimeout(timeoutId);
+                if (result instanceof Response) {
+                    return wrap(result);
+                } else {
+                    return wrap(new Response(JSON.stringify(result), {
+                        headers: { "Content-Type": "application/json" },
+                    }));
+                }
+            } catch (error) {
+                const duration = Date.now() - startTime;
+                logger.error(
+                    `Error in REST endpoint ${method} ${endpoint.path} after ${duration}ms`,
+                    error as any,
+                );
+                clearTimeout(timeoutId);
+                return wrap(new Response(
+                    JSON.stringify({
+                        error: "Internal server error",
+                        code: "INTERNAL_ERROR",
+                        ...(process.env.NODE_ENV === 'development' && {
+                            message: (error as Error)?.message,
+                        }),
+                    }),
+                    { status: 500, headers: { "Content-Type": "application/json" } },
+                ));
+            }
+        }
+
+        if (app.yoga) {
+            const response = await app.yoga(req);
+            const duration = Date.now() - startTime;
+            logger.trace(`GraphQL request completed in ${duration}ms`);
+            clearTimeout(timeoutId);
+            return response;
+        }
+
+        clearTimeout(timeoutId);
+        return wrap(new Response("Not Found", { status: 404 }));
+    } catch (error) {
+        const duration = Date.now() - startTime;
+        const stats = (req as any).__bunsaneStats as RequestStats | undefined;
+        logger.error(
+            {
+                scope: 'App',
+                method,
+                path: url.pathname,
+                duration,
+                operationName: stats?.operationName,
+                dataLoaderCalls: stats?.dataLoaderCalls,
+                dbQueryCount: stats?.dbQueryCount,
+                dbStats: getDbStats(),
+                err: error,
+            },
+            `Request failed after ${duration}ms: ${method} ${url.pathname}`,
+        );
+        clearTimeout(timeoutId);
+
+        if ((error as Error).name === "AbortError") {
+            return wrap(new Response(
+                JSON.stringify({ error: "Request timeout", code: "TIMEOUT_ERROR" }),
+                { status: 408, headers: { "Content-Type": "application/json" } },
+            ));
+        }
+
+        return wrap(new Response(
+            JSON.stringify({
+                error: "Internal server error",
+                code: "INTERNAL_ERROR",
+                ...(process.env.NODE_ENV === 'development' && {
+                    message: (error as Error)?.message,
+                }),
+            }),
+            { status: 500, headers: { "Content-Type": "application/json" } },
+        ));
+    }
+}

package/core/app/restRegistry.ts

@@ -0,0 +1,72 @@
+import { logger as MainLogger } from "../Logger";
+
+const logger = MainLogger.child({ scope: "App" });
+
+export function collectRestEndpoints(app: any, services: any[]): void {
+    for (const service of services) {
+        const endpoints = (service.constructor as any).httpEndpoints;
+        if (!endpoints) continue;
+
+        for (const endpoint of endpoints) {
+            const endpointInfo = {
+                method: endpoint.method,
+                path: endpoint.path,
+                handler: endpoint.handler.bind(service),
+                service: service,
+            };
+            logger.trace(
+                `Registered REST endpoint: [${endpoint.method}] ${endpoint.path} for service ${service.constructor.name}`,
+            );
+            app.restEndpoints.push(endpointInfo);
+            app.restEndpointMap.set(`${endpoint.method}:${endpoint.path}`, endpointInfo);
+
+            if ((endpoint.handler as any).swaggerOperation) {
+                const classTags = (service.constructor as any).swaggerClassTags || [];
+                const methodTags =
+                    (service.constructor as any).swaggerMethodTags?.[endpoint.handler.name] || [];
+                const allTags = [...classTags, ...methodTags];
+
+                logger.trace(
+                    `Generating OpenAPI spec for endpoint: [${endpoint.method}] ${endpoint.path} with tags: ${allTags.join(", ")}`,
+                );
+
+                const operation = { ...(endpoint.handler as any).swaggerOperation };
+                if (allTags.length > 0) {
+                    operation.tags = [...(operation.tags || []), ...allTags];
+                }
+
+                app.openAPISpecGenerator!.addEndpoint({
+                    method: endpoint.method,
+                    path: endpoint.path,
+                    operation,
+                });
+                logger.trace(
+                    `Registered OpenAPI spec for endpoint: [${endpoint.method}] ${endpoint.path}`,
+                );
+            } else if (app.enforceDocs) {
+                logger.warn(
+                    `No swagger operation found for endpoint: [${endpoint.method}] ${endpoint.path} in service ${service.constructor.name}`,
+                );
+                app.openAPISpecGenerator!.addEndpoint({
+                    method: endpoint.method,
+                    path: endpoint.path,
+                    operation: {
+                        summary: `No description for ${endpoint.path}. Don't use this endpoint until it's properly documented!`,
+                        requestBody: {
+                            content: {
+                                "application/json": {
+                                    schema: {},
+                                },
+                            },
+                        },
+                        responses: {
+                            "200": {
+                                description: "Success",
+                            },
+                        },
+                    },
+                });
+            }
+        }
+    }
+}