@constructive-io/graphql-server 4.10.0 → 4.11.0

package/esm/middleware/observability/graphile-build-stats.js

@@ -0,0 +1,165 @@
+const MAX_BUILD_EVENTS = 100;
+const MAX_AGGREGATE_KEYS = 100;
+const buildStats = {
+    started: 0,
+    succeeded: 0,
+    failed: 0,
+    totalMs: 0,
+    maxMs: 0,
+    lastMs: 0,
+    lastKey: null,
+    lastStartedAt: null,
+    lastFinishedAt: null,
+    lastError: null,
+    lastServiceKey: null,
+    lastDatabaseId: null,
+    recentEvents: [],
+    byServiceKey: new Map(),
+};
+const pushBuildEvent = (event) => {
+    buildStats.recentEvents.push(event);
+    if (buildStats.recentEvents.length > MAX_BUILD_EVENTS) {
+        buildStats.recentEvents.splice(0, buildStats.recentEvents.length - MAX_BUILD_EVENTS);
+    }
+};
+const updateAggregate = (map, key, durationMs) => {
+    const hasKey = map.has(key);
+    if (!hasKey && map.size >= MAX_AGGREGATE_KEYS) {
+        const oldestKey = map.keys().next().value;
+        if (oldestKey) {
+            map.delete(oldestKey);
+        }
+    }
+    const current = map.get(key) ?? {
+        count: 0,
+        totalMs: 0,
+        maxMs: 0,
+        lastMs: 0,
+        lastAt: null,
+    };
+    current.count += 1;
+    current.totalMs += durationMs;
+    current.maxMs = Math.max(current.maxMs, durationMs);
+    current.lastMs = durationMs;
+    current.lastAt = new Date().toISOString();
+    // Keep LRU order by reinserting after each update.
+    if (hasKey) {
+        map.delete(key);
+    }
+    map.set(key, current);
+};
+const recordBuildStart = (context, startedAt) => {
+    buildStats.started += 1;
+    buildStats.lastKey = context.cacheKey;
+    buildStats.lastStartedAt = new Date(startedAt).toISOString();
+    buildStats.lastServiceKey = context.serviceKey;
+    buildStats.lastDatabaseId = context.databaseId;
+    pushBuildEvent({
+        type: 'start',
+        cacheKey: context.cacheKey,
+        serviceKey: context.serviceKey,
+        databaseId: context.databaseId,
+        timestamp: new Date(startedAt).toISOString(),
+    });
+};
+const recordBuildSuccess = (context, startedAt) => {
+    const durationMs = Date.now() - startedAt;
+    buildStats.succeeded += 1;
+    buildStats.totalMs += durationMs;
+    buildStats.maxMs = Math.max(buildStats.maxMs, durationMs);
+    buildStats.lastMs = durationMs;
+    buildStats.lastFinishedAt = new Date().toISOString();
+    buildStats.lastError = null;
+    buildStats.lastServiceKey = context.serviceKey;
+    buildStats.lastDatabaseId = context.databaseId;
+    if (context.serviceKey) {
+        updateAggregate(buildStats.byServiceKey, context.serviceKey, durationMs);
+    }
+    pushBuildEvent({
+        type: 'success',
+        cacheKey: context.cacheKey,
+        serviceKey: context.serviceKey,
+        databaseId: context.databaseId,
+        durationMs,
+        timestamp: new Date().toISOString(),
+    });
+};
+const recordBuildFailure = (context, startedAt, error) => {
+    const durationMs = Date.now() - startedAt;
+    buildStats.failed += 1;
+    buildStats.totalMs += durationMs;
+    buildStats.maxMs = Math.max(buildStats.maxMs, durationMs);
+    buildStats.lastMs = durationMs;
+    buildStats.lastFinishedAt = new Date().toISOString();
+    buildStats.lastError = error instanceof Error ? error.message : String(error);
+    buildStats.lastServiceKey = context.serviceKey;
+    buildStats.lastDatabaseId = context.databaseId;
+    pushBuildEvent({
+        type: 'failure',
+        cacheKey: context.cacheKey,
+        serviceKey: context.serviceKey,
+        databaseId: context.databaseId,
+        durationMs,
+        error: error instanceof Error ? error.message : String(error),
+        timestamp: new Date().toISOString(),
+    });
+};
+export const observeGraphileBuild = async (context, fn, opts) => {
+    if (!opts.enabled) {
+        return fn();
+    }
+    const startedAt = Date.now();
+    recordBuildStart(context, startedAt);
+    try {
+        const result = await fn();
+        recordBuildSuccess(context, startedAt);
+        return result;
+    }
+    catch (error) {
+        recordBuildFailure(context, startedAt, error);
+        throw error;
+    }
+};
+export const resetGraphileBuildStats = () => {
+    buildStats.started = 0;
+    buildStats.succeeded = 0;
+    buildStats.failed = 0;
+    buildStats.totalMs = 0;
+    buildStats.maxMs = 0;
+    buildStats.lastMs = 0;
+    buildStats.lastKey = null;
+    buildStats.lastStartedAt = null;
+    buildStats.lastFinishedAt = null;
+    buildStats.lastError = null;
+    buildStats.lastServiceKey = null;
+    buildStats.lastDatabaseId = null;
+    buildStats.recentEvents = [];
+    buildStats.byServiceKey.clear();
+};
+export function getGraphileBuildStats() {
+    const completed = buildStats.succeeded + buildStats.failed;
+    const withAverages = (map) => Object.fromEntries([...map.entries()].map(([key, value]) => [
+        key,
+        {
+            ...value,
+            averageMs: value.count > 0 ? value.totalMs / value.count : 0,
+        },
+    ]));
+    return {
+        started: buildStats.started,
+        succeeded: buildStats.succeeded,
+        failed: buildStats.failed,
+        totalMs: buildStats.totalMs,
+        maxMs: buildStats.maxMs,
+        lastMs: buildStats.lastMs,
+        averageMs: completed > 0 ? buildStats.totalMs / completed : 0,
+        lastKey: buildStats.lastKey,
+        lastStartedAt: buildStats.lastStartedAt,
+        lastFinishedAt: buildStats.lastFinishedAt,
+        lastError: buildStats.lastError,
+        lastServiceKey: buildStats.lastServiceKey,
+        lastDatabaseId: buildStats.lastDatabaseId,
+        recentEvents: [...buildStats.recentEvents],
+        byServiceKey: withAverages(buildStats.byServiceKey),
+    };
+}

package/esm/middleware/observability/guard.js

@@ -0,0 +1,14 @@
+import { isLoopbackAddress, isLoopbackHost } from '../../diagnostics/observability';
+export const localObservabilityOnly = (req, res, next) => {
+    const remoteAddress = req.socket.remoteAddress;
+    if (isLoopbackAddress(remoteAddress)) {
+        next();
+        return;
+    }
+    const hostHeader = req.headers.host;
+    if (!remoteAddress && isLoopbackHost(hostHeader)) {
+        next();
+        return;
+    }
+    res.status(404).send('Not found');
+};

package/esm/middleware/observability/request-logger.js

@@ -0,0 +1,42 @@
+import { randomUUID } from 'crypto';
+import { Logger } from '@pgpmjs/logger';
+const log = new Logger('server');
+const SAFE_REQUEST_ID = /^[a-zA-Z0-9\-_]{1,128}$/;
+export const createRequestLogger = ({ observabilityEnabled }) => {
+    return (req, res, next) => {
+        const headerRequestId = req.header('x-request-id');
+        const reqId = (headerRequestId && SAFE_REQUEST_ID.test(headerRequestId))
+            ? headerRequestId
+            : randomUUID();
+        const start = process.hrtime.bigint();
+        let finished = false;
+        req.requestId = reqId;
+        const host = req.hostname || req.headers.host || 'unknown';
+        const ip = req.clientIp ?? req.ip ?? 'unknown';
+        log.debug(`[${reqId}] -> ${req.method} ${req.originalUrl} host=${host} ip=${ip}`);
+        res.on('finish', () => {
+            finished = true;
+            const durationMs = Number(process.hrtime.bigint() - start) / 1e6;
+            const apiInfo = req.api
+                ? `db=${req.api.dbname} schemas=${req.api.schema?.join(',') || 'none'}`
+                : 'api=unresolved';
+            const authInfo = req.token ? 'auth=token' : 'auth=anon';
+            const svcInfo = req.svc_key ? `svc=${req.svc_key}` : 'svc=unset';
+            log.debug(`[${reqId}] <- ${res.statusCode} ${req.method} ${req.originalUrl} (${durationMs.toFixed(1)} ms) ${apiInfo} ${svcInfo} ${authInfo}`);
+        });
+        if (observabilityEnabled) {
+            res.on('close', () => {
+                if (finished) {
+                    return;
+                }
+                const durationMs = Number(process.hrtime.bigint() - start) / 1e6;
+                const apiInfo = req.api
+                    ? `db=${req.api.dbname} schemas=${req.api.schema?.join(',') || 'none'}`
+                    : 'api=unresolved';
+                log.warn(`[${reqId}] connection closed before response completed ` +
+                    `${req.method} ${req.originalUrl} (${durationMs.toFixed(1)} ms) ${apiInfo}`);
+            });
+        }
+        next();
+    };
+};

package/esm/server.js

@@ -2,12 +2,13 @@ import { getEnvOptions } from '@constructive-io/graphql-env';
 import { Logger } from '@pgpmjs/logger';
 import { healthz, poweredBy, svcCache, trustProxy } from '@pgpmjs/server-utils';
 import { middleware as parseDomains } from '@constructive-io/url-domains';
-import { randomUUID } from 'crypto';
 import express from 'express';
 import graphqlUpload from 'graphql-upload';
 import { graphileCache, closeAllCaches } from 'graphile-cache';
 import { getPgPool } from 'pg-cache';
 import requestIp from 'request-ip';
+import { closeDebugDatabasePools } from './diagnostics/debug-db-snapshot';
+import { isDevelopmentObservabilityMode, isGraphqlObservabilityEnabled, isGraphqlObservabilityRequested, isLoopbackHost, } from './diagnostics/observability';
 import { createApiMiddleware } from './middleware/api';
 import { createAuthenticateMiddleware } from './middleware/auth';
 import { cors } from './middleware/cors';
@@ -16,8 +17,12 @@ import { favicon } from './middleware/favicon';
 import { flush, flushService } from './middleware/flush';
 import { graphile } from './middleware/graphile';
 import { multipartBridge } from './middleware/multipart-bridge';
+import { createDebugDatabaseMiddleware } from './middleware/observability/debug-db';
+import { debugMemory } from './middleware/observability/debug-memory';
+import { localObservabilityOnly } from './middleware/observability/guard';
+import { createRequestLogger } from './middleware/observability/request-logger';
 import { createUploadAuthenticateMiddleware, uploadRoute } from './middleware/upload';
-import { debugMemory } from './middleware/debug-memory';
+import { startDebugSampler } from './diagnostics/debug-sampler';
 const log = new Logger('server');
 /**
  * Creates and starts a GraphQL server instance
@@ -54,35 +59,17 @@ class Server {
     shuttingDown = false;
     closed = false;
     httpServer = null;
+    debugSampler = null;
     constructor(opts) {
         this.opts = getEnvOptions(opts);
         const effectiveOpts = this.opts;
+        const observabilityRequested = isGraphqlObservabilityRequested();
+        const observabilityEnabled = isGraphqlObservabilityEnabled(effectiveOpts.server?.host);
         const app = express();
         const api = createApiMiddleware(effectiveOpts);
         const authenticate = createAuthenticateMiddleware(effectiveOpts);
         const uploadAuthenticate = createUploadAuthenticateMiddleware(effectiveOpts);
-        const SAFE_REQUEST_ID = /^[a-zA-Z0-9\-_]{1,128}$/;
-        const requestLogger = (req, res, next) => {
-            const headerRequestId = req.header('x-request-id');
-            const reqId = (headerRequestId && SAFE_REQUEST_ID.test(headerRequestId))
-                ? headerRequestId
-                : randomUUID();
-            const start = process.hrtime.bigint();
-            req.requestId = reqId;
-            const host = req.hostname || req.headers.host || 'unknown';
-            const ip = req.clientIp || req.ip;
-            log.debug(`[${reqId}] -> ${req.method} ${req.originalUrl} host=${host} ip=${ip}`);
-            res.on('finish', () => {
-                const durationMs = Number(process.hrtime.bigint() - start) / 1e6;
-                const apiInfo = req.api
-                    ? `db=${req.api.dbname} schemas=${req.api.schema?.join(',') || 'none'}`
-                    : 'api=unresolved';
-                const authInfo = req.token ? 'auth=token' : 'auth=anon';
-                const svcInfo = req.svc_key ? `svc=${req.svc_key}` : 'svc=unset';
-                log.debug(`[${reqId}] <- ${res.statusCode} ${req.method} ${req.originalUrl} (${durationMs.toFixed(1)} ms) ${apiInfo} ${svcInfo} ${authInfo}`);
-            });
-            next();
-        };
+        const requestLogger = createRequestLogger({ observabilityEnabled });
         // Log startup configuration (non-sensitive values only)
         const apiOpts = effectiveOpts.api || {};
         log.info('[server] Starting with config:', {
@@ -97,9 +84,28 @@ class Server {
             exposedSchemas: apiOpts.exposedSchemas?.join(',') || 'none',
             anonRole: apiOpts.anonRole,
             roleName: apiOpts.roleName,
+            observabilityEnabled,
         });
+        if (observabilityRequested && !observabilityEnabled) {
+            const reasons = [];
+            if (!isDevelopmentObservabilityMode()) {
+                reasons.push('NODE_ENV must be development');
+            }
+            if (!isLoopbackHost(effectiveOpts.server?.host)) {
+                reasons.push('server host must be localhost, 127.0.0.1, or ::1');
+            }
+            log.warn(`GRAPHQL_OBSERVABILITY_ENABLED was requested but observability remains disabled${reasons.length > 0 ? `: ${reasons.join('; ')}` : ''}`);
+        }
         healthz(app);
-        app.get('/debug/memory', debugMemory);
+        if (observabilityEnabled) {
+            app.get('/debug/memory', localObservabilityOnly, debugMemory);
+            app.get('/debug/db', localObservabilityOnly, createDebugDatabaseMiddleware(effectiveOpts));
+        }
+        else {
+            app.use('/debug', (_req, res) => {
+                res.status(404).send('Not found');
+            });
+        }
         app.use(favicon);
         trustProxy(app, effectiveOpts.server.trustProxy);
         // Warn if a global CORS override is set in production
@@ -132,6 +138,7 @@ class Server {
         app.use(notFoundHandler); // Catches unmatched routes (404)
         app.use(errorHandler); // Catches all thrown errors
         this.app = app;
+        this.debugSampler = observabilityEnabled ? startDebugSampler(effectiveOpts) : null;
     }
     listen() {
         const { server } = this.opts;
@@ -221,9 +228,14 @@ class Server {
         this.closed = true;
         this.shuttingDown = true;
         await this.removeEventListener();
+        if (this.debugSampler) {
+            await this.debugSampler.stop();
+            this.debugSampler = null;
+        }
         if (this.httpServer?.listening) {
             await new Promise((resolve) => this.httpServer.close(() => resolve()));
         }
+        await closeDebugDatabasePools();
         if (closeCaches) {
             await Server.closeCaches({ closePools: true });
         }

package/middleware/graphile.js

@@ -15,7 +15,9 @@ const graphile_settings_1 = require("graphile-settings");
 const pg_cache_1 = require("pg-cache");
 const pg_env_1 = require("pg-env");
 require("./types"); // for Request type
+const observability_1 = require("../diagnostics/observability");
 const api_errors_1 = require("../errors/api-errors");
+const graphile_build_stats_1 = require("./observability/graphile-build-stats");
 const maskErrorLog = new logger_1.Logger('graphile:maskError');
 const SAFE_ERROR_CODES = new Set([
     // GraphQL standard
@@ -179,6 +181,7 @@ const buildPreset = (connectionString, schemas, anonRole, roleName) => ({
     },
 });
 const graphile = (opts) => {
+    const observabilityEnabled = (0, observability_1.isGraphqlObservabilityEnabled)(opts.server?.host);
     return async (req, res, next) => {
         const label = reqLabel(req);
         try {
@@ -242,7 +245,11 @@ const graphile = (opts) => {
             const connectionString = (0, pg_cache_1.buildConnectionString)(pgConfig.user, pgConfig.password, pgConfig.host, pgConfig.port, pgConfig.database);
             // Create promise and store in in-flight map BEFORE try block
             const preset = buildPreset(connectionString, schema || [], anonRole, roleName);
-            const creationPromise = (0, graphile_cache_1.createGraphileInstance)({ preset, cacheKey: key });
+            const creationPromise = (0, graphile_build_stats_1.observeGraphileBuild)({
+                cacheKey: key,
+                serviceKey: key,
+                databaseId: api.databaseId ?? null,
+            }, () => (0, graphile_cache_1.createGraphileInstance)({ preset, cacheKey: key }), { enabled: observabilityEnabled });
             creating.set(key, creationPromise);
             try {
                 const instance = await creationPromise;

package/middleware/observability/debug-db.d.ts

@@ -0,0 +1,3 @@
+import type { ConstructiveOptions } from '@constructive-io/graphql-types';
+import type { RequestHandler } from 'express';
+export declare const createDebugDatabaseMiddleware: (opts: ConstructiveOptions) => RequestHandler;

package/middleware/observability/debug-db.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDebugDatabaseMiddleware = void 0;
+const logger_1 = require("@pgpmjs/logger");
+const debug_db_snapshot_1 = require("../../diagnostics/debug-db-snapshot");
+const log = new logger_1.Logger('debug-db');
+const createDebugDatabaseMiddleware = (opts) => {
+    return async (_req, res) => {
+        try {
+            const response = await (0, debug_db_snapshot_1.getDebugDatabaseSnapshot)(opts);
+            log.debug('Database debug snapshot', {
+                activeActivity: response.activeActivity.length,
+                blockedActivity: response.blockedActivity.length,
+                lockSummary: response.lockSummary.length,
+            });
+            res.json(response);
+        }
+        catch (error) {
+            log.error('Failed to fetch debug DB snapshot', error);
+            res.status(500).json({
+                error: 'Failed to fetch database debug snapshot',
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    };
+};
+exports.createDebugDatabaseMiddleware = createDebugDatabaseMiddleware;

package/middleware/observability/debug-memory.d.ts

@@ -0,0 +1,2 @@
+import type { RequestHandler } from 'express';
+export declare const debugMemory: RequestHandler;

package/middleware/observability/debug-memory.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.debugMemory = void 0;
+const logger_1 = require("@pgpmjs/logger");
+const debug_memory_snapshot_1 = require("../../diagnostics/debug-memory-snapshot");
+const log = new logger_1.Logger('debug-memory');
+const debugMemory = (_req, res) => {
+    const response = (0, debug_memory_snapshot_1.getDebugMemorySnapshot)();
+    log.debug('Memory snapshot:', response);
+    res.json(response);
+};
+exports.debugMemory = debugMemory;

package/middleware/observability/graphile-build-stats.d.ts

@@ -0,0 +1,45 @@
+export interface GraphileBuildEvent {
+    type: 'start' | 'success' | 'failure';
+    cacheKey: string;
+    serviceKey: string | null;
+    databaseId: string | null;
+    durationMs?: number;
+    error?: string;
+    timestamp: string;
+}
+interface GraphileBuildAggregate {
+    count: number;
+    totalMs: number;
+    maxMs: number;
+    lastMs: number;
+    lastAt: string | null;
+}
+interface GraphileBuildContext {
+    cacheKey: string;
+    serviceKey: string | null;
+    databaseId: string | null;
+}
+export declare const observeGraphileBuild: <T>(context: GraphileBuildContext, fn: () => Promise<T>, opts: {
+    enabled: boolean;
+}) => Promise<T>;
+export declare const resetGraphileBuildStats: () => void;
+export declare function getGraphileBuildStats(): {
+    started: number;
+    succeeded: number;
+    failed: number;
+    totalMs: number;
+    maxMs: number;
+    lastMs: number;
+    averageMs: number;
+    lastKey: string | null;
+    lastStartedAt: string | null;
+    lastFinishedAt: string | null;
+    lastError: string | null;
+    lastServiceKey: string | null;
+    lastDatabaseId: string | null;
+    recentEvents: GraphileBuildEvent[];
+    byServiceKey: Record<string, GraphileBuildAggregate & {
+        averageMs: number;
+    }>;
+};
+export {};

package/middleware/observability/graphile-build-stats.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetGraphileBuildStats = exports.observeGraphileBuild = void 0;
+exports.getGraphileBuildStats = getGraphileBuildStats;
+const MAX_BUILD_EVENTS = 100;
+const MAX_AGGREGATE_KEYS = 100;
+const buildStats = {
+    started: 0,
+    succeeded: 0,
+    failed: 0,
+    totalMs: 0,
+    maxMs: 0,
+    lastMs: 0,
+    lastKey: null,
+    lastStartedAt: null,
+    lastFinishedAt: null,
+    lastError: null,
+    lastServiceKey: null,
+    lastDatabaseId: null,
+    recentEvents: [],
+    byServiceKey: new Map(),
+};
+const pushBuildEvent = (event) => {
+    buildStats.recentEvents.push(event);
+    if (buildStats.recentEvents.length > MAX_BUILD_EVENTS) {
+        buildStats.recentEvents.splice(0, buildStats.recentEvents.length - MAX_BUILD_EVENTS);
+    }
+};
+const updateAggregate = (map, key, durationMs) => {
+    const hasKey = map.has(key);
+    if (!hasKey && map.size >= MAX_AGGREGATE_KEYS) {
+        const oldestKey = map.keys().next().value;
+        if (oldestKey) {
+            map.delete(oldestKey);
+        }
+    }
+    const current = map.get(key) ?? {
+        count: 0,
+        totalMs: 0,
+        maxMs: 0,
+        lastMs: 0,
+        lastAt: null,
+    };
+    current.count += 1;
+    current.totalMs += durationMs;
+    current.maxMs = Math.max(current.maxMs, durationMs);
+    current.lastMs = durationMs;
+    current.lastAt = new Date().toISOString();
+    // Keep LRU order by reinserting after each update.
+    if (hasKey) {
+        map.delete(key);
+    }
+    map.set(key, current);
+};
+const recordBuildStart = (context, startedAt) => {
+    buildStats.started += 1;
+    buildStats.lastKey = context.cacheKey;
+    buildStats.lastStartedAt = new Date(startedAt).toISOString();
+    buildStats.lastServiceKey = context.serviceKey;
+    buildStats.lastDatabaseId = context.databaseId;
+    pushBuildEvent({
+        type: 'start',
+        cacheKey: context.cacheKey,
+        serviceKey: context.serviceKey,
+        databaseId: context.databaseId,
+        timestamp: new Date(startedAt).toISOString(),
+    });
+};
+const recordBuildSuccess = (context, startedAt) => {
+    const durationMs = Date.now() - startedAt;
+    buildStats.succeeded += 1;
+    buildStats.totalMs += durationMs;
+    buildStats.maxMs = Math.max(buildStats.maxMs, durationMs);
+    buildStats.lastMs = durationMs;
+    buildStats.lastFinishedAt = new Date().toISOString();
+    buildStats.lastError = null;
+    buildStats.lastServiceKey = context.serviceKey;
+    buildStats.lastDatabaseId = context.databaseId;
+    if (context.serviceKey) {
+        updateAggregate(buildStats.byServiceKey, context.serviceKey, durationMs);
+    }
+    pushBuildEvent({
+        type: 'success',
+        cacheKey: context.cacheKey,
+        serviceKey: context.serviceKey,
+        databaseId: context.databaseId,
+        durationMs,
+        timestamp: new Date().toISOString(),
+    });
+};
+const recordBuildFailure = (context, startedAt, error) => {
+    const durationMs = Date.now() - startedAt;
+    buildStats.failed += 1;
+    buildStats.totalMs += durationMs;
+    buildStats.maxMs = Math.max(buildStats.maxMs, durationMs);
+    buildStats.lastMs = durationMs;
+    buildStats.lastFinishedAt = new Date().toISOString();
+    buildStats.lastError = error instanceof Error ? error.message : String(error);
+    buildStats.lastServiceKey = context.serviceKey;
+    buildStats.lastDatabaseId = context.databaseId;
+    pushBuildEvent({
+        type: 'failure',
+        cacheKey: context.cacheKey,
+        serviceKey: context.serviceKey,
+        databaseId: context.databaseId,
+        durationMs,
+        error: error instanceof Error ? error.message : String(error),
+        timestamp: new Date().toISOString(),
+    });
+};
+const observeGraphileBuild = async (context, fn, opts) => {
+    if (!opts.enabled) {
+        return fn();
+    }
+    const startedAt = Date.now();
+    recordBuildStart(context, startedAt);
+    try {
+        const result = await fn();
+        recordBuildSuccess(context, startedAt);
+        return result;
+    }
+    catch (error) {
+        recordBuildFailure(context, startedAt, error);
+        throw error;
+    }
+};
+exports.observeGraphileBuild = observeGraphileBuild;
+const resetGraphileBuildStats = () => {
+    buildStats.started = 0;
+    buildStats.succeeded = 0;
+    buildStats.failed = 0;
+    buildStats.totalMs = 0;
+    buildStats.maxMs = 0;
+    buildStats.lastMs = 0;
+    buildStats.lastKey = null;
+    buildStats.lastStartedAt = null;
+    buildStats.lastFinishedAt = null;
+    buildStats.lastError = null;
+    buildStats.lastServiceKey = null;
+    buildStats.lastDatabaseId = null;
+    buildStats.recentEvents = [];
+    buildStats.byServiceKey.clear();
+};
+exports.resetGraphileBuildStats = resetGraphileBuildStats;
+function getGraphileBuildStats() {
+    const completed = buildStats.succeeded + buildStats.failed;
+    const withAverages = (map) => Object.fromEntries([...map.entries()].map(([key, value]) => [
+        key,
+        {
+            ...value,
+            averageMs: value.count > 0 ? value.totalMs / value.count : 0,
+        },
+    ]));
+    return {
+        started: buildStats.started,
+        succeeded: buildStats.succeeded,
+        failed: buildStats.failed,
+        totalMs: buildStats.totalMs,
+        maxMs: buildStats.maxMs,
+        lastMs: buildStats.lastMs,
+        averageMs: completed > 0 ? buildStats.totalMs / completed : 0,
+        lastKey: buildStats.lastKey,
+        lastStartedAt: buildStats.lastStartedAt,
+        lastFinishedAt: buildStats.lastFinishedAt,
+        lastError: buildStats.lastError,
+        lastServiceKey: buildStats.lastServiceKey,
+        lastDatabaseId: buildStats.lastDatabaseId,
+        recentEvents: [...buildStats.recentEvents],
+        byServiceKey: withAverages(buildStats.byServiceKey),
+    };
+}

package/middleware/observability/guard.d.ts

@@ -0,0 +1,2 @@
+import type { RequestHandler } from 'express';
+export declare const localObservabilityOnly: RequestHandler;

package/middleware/observability/guard.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localObservabilityOnly = void 0;
+const observability_1 = require("../../diagnostics/observability");
+const localObservabilityOnly = (req, res, next) => {
+    const remoteAddress = req.socket.remoteAddress;
+    if ((0, observability_1.isLoopbackAddress)(remoteAddress)) {
+        next();
+        return;
+    }
+    const hostHeader = req.headers.host;
+    if (!remoteAddress && (0, observability_1.isLoopbackHost)(hostHeader)) {
+        next();
+        return;
+    }
+    res.status(404).send('Not found');
+};
+exports.localObservabilityOnly = localObservabilityOnly;

package/middleware/observability/request-logger.d.ts

@@ -0,0 +1,6 @@
+import type { RequestHandler } from 'express';
+interface RequestLoggerOptions {
+    observabilityEnabled: boolean;
+}
+export declare const createRequestLogger: ({ observabilityEnabled }: RequestLoggerOptions) => RequestHandler;
+export {};