Merge pull request #759 from constructive-io/devin/1772308114-debug-memory-endpoint

feat(graphql-server): add dev-only /debug/memory endpoint for OOM debugging

Author: pyramation

graphql/server/src/middleware/debug-memory.ts

@@ -0,0 +1,61 @@
+import { getNodeEnv } from '@constructive-io/graphql-env';
+import { Logger } from '@pgpmjs/logger';
+import { svcCache } from '@pgpmjs/server-utils';
+import type { RequestHandler } from 'express';
+import { getCacheStats } from 'graphile-cache';
+import { getInFlightCount, getInFlightKeys } from './graphile';
+
+const log = new Logger('debug-memory');
+
+const toMB = (bytes: number): string => `${(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: RequestHandler = (_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);
+};

graphql/server/src/server.ts

@@ -22,6 +22,7 @@ import { flush, flushService } from './middleware/flush';
 import { graphile } from './middleware/graphile';
 import { multipartBridge } from './middleware/multipart-bridge';
 import { createUploadAuthenticateMiddleware, uploadRoute } from './middleware/upload';
+import { debugMemory } from './middleware/debug-memory';
 import { normalizeServerOptions } from './options';
 
 const log = new Logger('server');
@@ -127,6 +128,7 @@ class Server {
     });
 
     healthz(app);
+    app.get('/debug/memory', debugMemory);
     app.use(favicon);
     trustProxy(app, effectiveOpts.server.trustProxy);
     // Warn if a global CORS override is set in production