@constructive-io/graphql-server 4.10.0 → 4.11.1

package/middleware/observability/request-logger.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRequestLogger = void 0;
+const crypto_1 = require("crypto");
+const logger_1 = require("@pgpmjs/logger");
+const log = new logger_1.Logger('server');
+const SAFE_REQUEST_ID = /^[a-zA-Z0-9\-_]{1,128}$/;
+const createRequestLogger = ({ observabilityEnabled }) => {
+    return (req, res, next) => {
+        const headerRequestId = req.header('x-request-id');
+        const reqId = (headerRequestId && SAFE_REQUEST_ID.test(headerRequestId))
+            ? headerRequestId
+            : (0, crypto_1.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();
+    };
+};
+exports.createRequestLogger = createRequestLogger;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-server",
-  "version": "4.10.0",
+  "version": "4.11.1",
   "author": "Constructive <developers@constructive.io>",
   "description": "Constructive GraphQL Server",
   "main": "index.js",
@@ -26,6 +26,8 @@
     "build:dev": "makage build --dev",
     "dev": "ts-node src/run.ts",
     "dev:watch": "nodemon --watch src --ext ts --exec ts-node src/run.ts",
+    "debug:memory:analyze": "node scripts/analyze-debug-logs.mjs",
+    "debug:heap:capture": "node scripts/capture-heap-snapshot.mjs",
     "lint": "eslint . --fix",
     "test": "jest --passWithNoTests",
     "test:watch": "jest --watch",
@@ -39,55 +41,55 @@
     "backend"
   ],
   "dependencies": {
-    "@constructive-io/graphql-env": "^3.4.2",
-    "@constructive-io/graphql-types": "^3.3.2",
-    "@constructive-io/s3-utils": "^2.9.2",
-    "@constructive-io/upload-names": "^2.9.2",
+    "@constructive-io/graphql-env": "^3.4.4",
+    "@constructive-io/graphql-types": "^3.3.4",
+    "@constructive-io/s3-utils": "^2.9.3",
+    "@constructive-io/upload-names": "^2.9.3",
     "@constructive-io/url-domains": "^2.9.2",
-    "@graphile-contrib/pg-many-to-many": "2.0.0-rc.1",
-    "@graphile/simplify-inflection": "8.0.0-rc.3",
-    "@pgpmjs/env": "^2.15.2",
-    "@pgpmjs/logger": "^2.4.2",
-    "@pgpmjs/server-utils": "^3.4.2",
-    "@pgpmjs/types": "^2.19.2",
+    "@graphile-contrib/pg-many-to-many": "2.0.0-rc.2",
+    "@graphile/simplify-inflection": "8.0.0-rc.5",
+    "@pgpmjs/env": "^2.15.3",
+    "@pgpmjs/logger": "^2.4.3",
+    "@pgpmjs/server-utils": "^3.4.4",
+    "@pgpmjs/types": "^2.19.3",
     "@pgsql/quotes": "^17.1.0",
     "cors": "^2.8.6",
     "deepmerge": "^4.3.1",
     "express": "^5.2.1",
-    "gql-ast": "^3.3.2",
-    "grafast": "1.0.0-rc.7",
-    "grafserv": "1.0.0-rc.6",
-    "graphile-build": "5.0.0-rc.4",
-    "graphile-build-pg": "5.0.0-rc.5",
-    "graphile-cache": "^3.3.2",
-    "graphile-config": "1.0.0-rc.5",
-    "graphile-settings": "^4.9.0",
-    "graphile-utils": "5.0.0-rc.5",
-    "graphql": "^16.13.0",
+    "gql-ast": "^3.3.3",
+    "grafast": "1.0.0-rc.9",
+    "grafserv": "1.0.0-rc.7",
+    "graphile-build": "5.0.0-rc.6",
+    "graphile-build-pg": "5.0.0-rc.8",
+    "graphile-cache": "^3.3.4",
+    "graphile-config": "1.0.0-rc.6",
+    "graphile-settings": "^4.9.2",
+    "graphile-utils": "5.0.0-rc.8",
+    "graphql": "16.13.0",
     "graphql-upload": "^13.0.0",
-    "lru-cache": "^11.2.6",
-    "multer": "^2.1.0",
-    "pg": "^8.19.0",
-    "pg-cache": "^3.3.2",
-    "pg-env": "^1.7.2",
-    "pg-query-context": "^2.8.2",
-    "pg-sql2": "5.0.0-rc.4",
-    "postgraphile": "5.0.0-rc.7",
+    "lru-cache": "^11.2.7",
+    "multer": "^2.1.1",
+    "pg": "^8.20.0",
+    "pg-cache": "^3.3.4",
+    "pg-env": "^1.7.3",
+    "pg-query-context": "^2.8.3",
+    "pg-sql2": "5.0.0-rc.5",
+    "postgraphile": "5.0.0-rc.10",
     "postgraphile-plugin-connection-filter": "3.0.0-rc.1",
     "request-ip": "^3.3.0"
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "^3.1001.0",
+    "@aws-sdk/client-s3": "^3.1009.0",
     "@types/cors": "^2.8.17",
     "@types/express": "^5.0.6",
     "@types/graphql-upload": "^8.0.12",
-    "@types/multer": "^2.0.0",
+    "@types/multer": "^2.1.0",
     "@types/pg": "^8.18.0",
     "@types/request-ip": "^0.0.41",
-    "graphile-test": "4.5.2",
+    "graphile-test": "4.5.4",
     "makage": "^0.1.10",
     "nodemon": "^3.1.14",
     "ts-node": "^10.9.2"
   },
-  "gitHead": "180ba9eed8414667a0d6dcef99ca4bb988c73bbd"
+  "gitHead": "8afe6b19da82facbe5f3365762ba52888af5b3c9"
 }

package/server.d.ts

@@ -32,6 +32,7 @@ declare class Server {
     private shuttingDown;
     private closed;
     private httpServer;
+    private debugSampler;
     constructor(opts: ConstructiveOptions);
     listen(): HttpServer;
     flush(databaseId: string): Promise<void>;

package/server.js

@@ -8,12 +8,13 @@ const graphql_env_1 = require("@constructive-io/graphql-env");
 const logger_1 = require("@pgpmjs/logger");
 const server_utils_1 = require("@pgpmjs/server-utils");
 const url_domains_1 = require("@constructive-io/url-domains");
-const crypto_1 = require("crypto");
 const express_1 = __importDefault(require("express"));
 const graphql_upload_1 = __importDefault(require("graphql-upload"));
 const graphile_cache_1 = require("graphile-cache");
 const pg_cache_1 = require("pg-cache");
 const request_ip_1 = __importDefault(require("request-ip"));
+const debug_db_snapshot_1 = require("./diagnostics/debug-db-snapshot");
+const observability_1 = require("./diagnostics/observability");
 const api_1 = require("./middleware/api");
 const auth_1 = require("./middleware/auth");
 const cors_1 = require("./middleware/cors");
@@ -22,8 +23,12 @@ const favicon_1 = require("./middleware/favicon");
 const flush_1 = require("./middleware/flush");
 const graphile_1 = require("./middleware/graphile");
 const multipart_bridge_1 = require("./middleware/multipart-bridge");
+const debug_db_1 = require("./middleware/observability/debug-db");
+const debug_memory_1 = require("./middleware/observability/debug-memory");
+const guard_1 = require("./middleware/observability/guard");
+const request_logger_1 = require("./middleware/observability/request-logger");
 const upload_1 = require("./middleware/upload");
-const debug_memory_1 = require("./middleware/debug-memory");
+const debug_sampler_1 = require("./diagnostics/debug-sampler");
 const log = new logger_1.Logger('server');
 /**
  * Creates and starts a GraphQL server instance
@@ -61,35 +66,17 @@ class Server {
     shuttingDown = false;
     closed = false;
     httpServer = null;
+    debugSampler = null;
     constructor(opts) {
         this.opts = (0, graphql_env_1.getEnvOptions)(opts);
         const effectiveOpts = this.opts;
+        const observabilityRequested = (0, observability_1.isGraphqlObservabilityRequested)();
+        const observabilityEnabled = (0, observability_1.isGraphqlObservabilityEnabled)(effectiveOpts.server?.host);
         const app = (0, express_1.default)();
         const api = (0, api_1.createApiMiddleware)(effectiveOpts);
         const authenticate = (0, auth_1.createAuthenticateMiddleware)(effectiveOpts);
         const uploadAuthenticate = (0, upload_1.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
-                : (0, crypto_1.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 = (0, request_logger_1.createRequestLogger)({ observabilityEnabled });
         // Log startup configuration (non-sensitive values only)
         const apiOpts = effectiveOpts.api || {};
         log.info('[server] Starting with config:', {
@@ -104,9 +91,28 @@ class Server {
             exposedSchemas: apiOpts.exposedSchemas?.join(',') || 'none',
             anonRole: apiOpts.anonRole,
             roleName: apiOpts.roleName,
+            observabilityEnabled,
         });
+        if (observabilityRequested && !observabilityEnabled) {
+            const reasons = [];
+            if (!(0, observability_1.isDevelopmentObservabilityMode)()) {
+                reasons.push('NODE_ENV must be development');
+            }
+            if (!(0, observability_1.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('; ')}` : ''}`);
+        }
         (0, server_utils_1.healthz)(app);
-        app.get('/debug/memory', debug_memory_1.debugMemory);
+        if (observabilityEnabled) {
+            app.get('/debug/memory', guard_1.localObservabilityOnly, debug_memory_1.debugMemory);
+            app.get('/debug/db', guard_1.localObservabilityOnly, (0, debug_db_1.createDebugDatabaseMiddleware)(effectiveOpts));
+        }
+        else {
+            app.use('/debug', (_req, res) => {
+                res.status(404).send('Not found');
+            });
+        }
         app.use(favicon_1.favicon);
         (0, server_utils_1.trustProxy)(app, effectiveOpts.server.trustProxy);
         // Warn if a global CORS override is set in production
@@ -139,6 +145,7 @@ class Server {
         app.use(error_handler_1.notFoundHandler); // Catches unmatched routes (404)
         app.use(error_handler_1.errorHandler); // Catches all thrown errors
         this.app = app;
+        this.debugSampler = observabilityEnabled ? (0, debug_sampler_1.startDebugSampler)(effectiveOpts) : null;
     }
     listen() {
         const { server } = this.opts;
@@ -228,9 +235,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 (0, debug_db_snapshot_1.closeDebugDatabasePools)();
         if (closeCaches) {
             await Server.closeCaches({ closePools: true });
         }

package/esm/middleware/debug-memory.js

@@ -1,54 +0,0 @@
-import { getNodeEnv } from '@pgpmjs/env';
-import { Logger } from '@pgpmjs/logger';
-import { svcCache } from '@pgpmjs/server-utils';
-import { getCacheStats } from 'graphile-cache';
-import { getInFlightCount, getInFlightKeys } from './graphile';
-const log = new Logger('debug-memory');
-const toMB = (bytes) => `${(bytes / 1024 / 1024).toFixed(1)} MB`;
-/**
- * Development-only debug endpoint for monitoring memory usage and cache state.
- *
- * Mounts GET /debug/memory which returns:
- * - Node.js process memory (heap, RSS, external, array buffers)
- * - Graphile cache stats (size, max, TTL, keys with ages)
- * - Service cache size
- * - In-flight handler creation count
- * - Process uptime
- *
- * This endpoint is only available when NODE_ENV=development.
- * In production, it returns 404.
- */
-export const debugMemory = (_req, res) => {
-    if (getNodeEnv() !== 'development') {
-        res.status(404).send('Not found');
-        return;
-    }
-    const mem = process.memoryUsage();
-    const cacheStats = getCacheStats();
-    const response = {
-        memory: {
-            heapUsed: toMB(mem.heapUsed),
-            heapTotal: toMB(mem.heapTotal),
-            rss: toMB(mem.rss),
-            external: toMB(mem.external),
-            arrayBuffers: toMB(mem.arrayBuffers),
-        },
-        graphileCache: {
-            size: cacheStats.size,
-            max: cacheStats.max,
-            ttl: `${(cacheStats.ttl / 1000 / 60).toFixed(0)} min`,
-            keys: cacheStats.keys,
-        },
-        svcCache: {
-            size: svcCache.size,
-        },
-        inFlight: {
-            count: getInFlightCount(),
-            keys: getInFlightKeys(),
-        },
-        uptime: `${(process.uptime() / 60).toFixed(1)} min`,
-        timestamp: new Date().toISOString(),
-    };
-    log.debug('Memory snapshot:', response);
-    res.json(response);
-};

package/middleware/debug-memory.d.ts

@@ -1,15 +0,0 @@
-import type { RequestHandler } from 'express';
-/**
- * Development-only debug endpoint for monitoring memory usage and cache state.
- *
- * Mounts GET /debug/memory which returns:
- * - Node.js process memory (heap, RSS, external, array buffers)
- * - Graphile cache stats (size, max, TTL, keys with ages)
- * - Service cache size
- * - In-flight handler creation count
- * - Process uptime
- *
- * This endpoint is only available when NODE_ENV=development.
- * In production, it returns 404.
- */
-export declare const debugMemory: RequestHandler;

package/middleware/debug-memory.js

@@ -1,58 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.debugMemory = void 0;
-const env_1 = require("@pgpmjs/env");
-const logger_1 = require("@pgpmjs/logger");
-const server_utils_1 = require("@pgpmjs/server-utils");
-const graphile_cache_1 = require("graphile-cache");
-const graphile_1 = require("./graphile");
-const log = new logger_1.Logger('debug-memory');
-const toMB = (bytes) => `${(bytes / 1024 / 1024).toFixed(1)} MB`;
-/**
- * Development-only debug endpoint for monitoring memory usage and cache state.
- *
- * Mounts GET /debug/memory which returns:
- * - Node.js process memory (heap, RSS, external, array buffers)
- * - Graphile cache stats (size, max, TTL, keys with ages)
- * - Service cache size
- * - In-flight handler creation count
- * - Process uptime
- *
- * This endpoint is only available when NODE_ENV=development.
- * In production, it returns 404.
- */
-const debugMemory = (_req, res) => {
-    if ((0, env_1.getNodeEnv)() !== 'development') {
-        res.status(404).send('Not found');
-        return;
-    }
-    const mem = process.memoryUsage();
-    const cacheStats = (0, graphile_cache_1.getCacheStats)();
-    const response = {
-        memory: {
-            heapUsed: toMB(mem.heapUsed),
-            heapTotal: toMB(mem.heapTotal),
-            rss: toMB(mem.rss),
-            external: toMB(mem.external),
-            arrayBuffers: toMB(mem.arrayBuffers),
-        },
-        graphileCache: {
-            size: cacheStats.size,
-            max: cacheStats.max,
-            ttl: `${(cacheStats.ttl / 1000 / 60).toFixed(0)} min`,
-            keys: cacheStats.keys,
-        },
-        svcCache: {
-            size: server_utils_1.svcCache.size,
-        },
-        inFlight: {
-            count: (0, graphile_1.getInFlightCount)(),
-            keys: (0, graphile_1.getInFlightKeys)(),
-        },
-        uptime: `${(process.uptime() / 60).toFixed(1)} min`,
-        timestamp: new Date().toISOString(),
-    };
-    log.debug('Memory snapshot:', response);
-    res.json(response);
-};
-exports.debugMemory = debugMemory;