@constructive-io/graphql-server 3.1.1 → 4.0.0

package/middleware/auth.js

@@ -14,6 +14,7 @@ const isDev = () => (0, graphql_env_1.getNodeEnv)() === 'development';
 const createAuthenticateMiddleware = (opts) => {
     return async (req, res, next) => {
         const api = req.api;
+        log.info(`[auth] middleware called, api=${api ? 'present' : 'missing'}`);
         if (!api) {
             res.status(500).send('Missing API info');
             return;
@@ -23,19 +24,26 @@ const createAuthenticateMiddleware = (opts) => {
             database: api.dbname,
         });
         const rlsModule = api.rlsModule;
+        log.info(`[auth] rlsModule=${rlsModule ? 'present' : 'missing'}, ` +
+            `authenticate=${rlsModule?.authenticate ?? 'none'}, ` +
+            `authenticateStrict=${rlsModule?.authenticateStrict ?? 'none'}, ` +
+            `privateSchema=${rlsModule?.privateSchema?.schemaName ?? 'none'}`);
         if (!rlsModule) {
-            if (isDev())
-                log.debug('No RLS module configured, skipping auth');
+            log.info('[auth] No RLS module configured, skipping auth');
             return next();
         }
-        const authFn = opts.server.strictAuth
+        const authFn = opts.server?.strictAuth
             ? rlsModule.authenticateStrict
             : rlsModule.authenticate;
+        log.info(`[auth] strictAuth=${opts.server?.strictAuth ?? false}, authFn=${authFn ?? 'none'}`);
         if (authFn && rlsModule.privateSchema.schemaName) {
             const { authorization = '' } = req.headers;
             const [authType, authToken] = authorization.split(' ');
             let token = {};
+            log.info(`[auth] authorization header present=${!!authorization}, ` +
+                `authType=${authType ?? 'none'}, hasToken=${!!authToken}`);
             if (authType?.toLowerCase() === 'bearer' && authToken) {
+                log.info('[auth] Processing bearer token authentication');
                 const context = {
                     'jwt.claims.ip_address': req.clientIp,
                 };
@@ -45,25 +53,28 @@ const createAuthenticateMiddleware = (opts) => {
                 if (req.get('User-Agent')) {
                     context['jwt.claims.user_agent'] = req.get('User-Agent');
                 }
+                const authQuery = `SELECT * FROM "${rlsModule.privateSchema.schemaName}"."${authFn}"($1)`;
+                log.info(`[auth] Executing auth query: ${authQuery}`);
                 try {
                     const result = await (0, pg_query_context_1.default)({
                         client: pool,
                         context,
-                        query: `SELECT * FROM "${rlsModule.privateSchema.schemaName}"."${authFn}"($1)`,
+                        query: authQuery,
                         variables: [authToken],
                     });
+                    log.info(`[auth] Query result: rowCount=${result?.rowCount}`);
                     if (result?.rowCount === 0) {
+                        log.info('[auth] No rows returned, returning UNAUTHENTICATED');
                         res.status(200).json({
                             errors: [{ extensions: { code: 'UNAUTHENTICATED' } }],
                         });
                         return;
                     }
                     token = result.rows[0];
-                    if (isDev())
-                        log.debug(`Auth success: role=${token.role}`);
+                    log.info(`[auth] Auth success: role=${token.role}, user_id=${token.user_id}`);
                 }
                 catch (e) {
-                    log.error('Auth error:', e.message);
+                    log.error('[auth] Auth error:', e.message);
                     res.status(200).json({
                         errors: [
                             {
@@ -77,8 +88,15 @@ const createAuthenticateMiddleware = (opts) => {
                     return;
                 }
             }
+            else {
+                log.info('[auth] No bearer token provided, using anonymous auth');
+            }
             req.token = token;
         }
+        else {
+            log.info(`[auth] Skipping auth: authFn=${authFn ?? 'none'}, ` +
+                `privateSchema=${rlsModule.privateSchema?.schemaName ?? 'none'}`);
+        }
         next();
     };
 };

package/middleware/error-handler.d.ts

@@ -0,0 +1,4 @@
+import type { ErrorRequestHandler, NextFunction, Request, Response } from 'express';
+import './types';
+export declare const errorHandler: ErrorRequestHandler;
+export declare const notFoundHandler: (req: Request, res: Response, _next: NextFunction) => void;

package/middleware/error-handler.js

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.notFoundHandler = exports.errorHandler = void 0;
+const graphql_env_1 = require("@constructive-io/graphql-env");
+const logger_1 = require("@pgpmjs/logger");
+const api_errors_1 = require("../errors/api-errors");
+const _404_message_1 = __importDefault(require("../errors/404-message"));
+const _50x_1 = __importDefault(require("../errors/50x"));
+require("./types");
+const log = new logger_1.Logger('error-handler');
+const isDevelopment = () => (0, graphql_env_1.getNodeEnv)() === 'development';
+const wantsJson = (req) => {
+    const accept = req.get('Accept') || '';
+    return accept.includes('application/json') || accept.includes('application/graphql-response+json');
+};
+const sanitizeMessage = (error) => {
+    if (isDevelopment())
+        return error.message;
+    if ((0, api_errors_1.isApiError)(error))
+        return error.message;
+    if (error.message?.includes('ECONNREFUSED'))
+        return 'Service temporarily unavailable';
+    if (error.message?.includes('timeout') || error.message?.includes('ETIMEDOUT'))
+        return 'Request timed out';
+    if (error.message?.includes('does not exist'))
+        return 'The requested resource does not exist';
+    return 'An unexpected error occurred';
+};
+const categorizeError = (err) => {
+    if ((0, api_errors_1.isApiError)(err)) {
+        return {
+            statusCode: err.statusCode,
+            code: err.code,
+            message: sanitizeMessage(err),
+            logLevel: err.statusCode >= 500 ? 'error' : 'warn',
+        };
+    }
+    if (err.message?.includes('ECONNREFUSED') || err.message?.includes('connection terminated')) {
+        return { statusCode: 503, code: 'SERVICE_UNAVAILABLE', message: sanitizeMessage(err), logLevel: 'error' };
+    }
+    if (err.message?.includes('timeout') || err.message?.includes('ETIMEDOUT')) {
+        return { statusCode: 504, code: 'GATEWAY_TIMEOUT', message: sanitizeMessage(err), logLevel: 'error' };
+    }
+    return { statusCode: 500, code: 'INTERNAL_ERROR', message: sanitizeMessage(err), logLevel: 'error' };
+};
+const sendResponse = (req, res, { statusCode, code, message }) => {
+    if (wantsJson(req)) {
+        res.status(statusCode).json({ error: { code, message, requestId: req.requestId } });
+    }
+    else {
+        res.status(statusCode).send(statusCode >= 500 ? _50x_1.default : (0, _404_message_1.default)(message));
+    }
+};
+const logError = (err, req, level) => {
+    const context = {
+        requestId: req.requestId,
+        path: req.path,
+        method: req.method,
+        host: req.get('host'),
+        databaseId: req.databaseId,
+        svcKey: req.svc_key,
+        clientIp: req.clientIp,
+    };
+    if ((0, api_errors_1.isApiError)(err)) {
+        log[level]({ event: 'api_error', code: err.code, statusCode: err.statusCode, message: err.message, ...context });
+    }
+    else {
+        log[level]({ event: 'unexpected_error', name: err.name, message: err.message, stack: isDevelopment() ? err.stack : undefined, ...context });
+    }
+};
+const errorHandler = (err, req, res, _next) => {
+    if (res.headersSent) {
+        log.warn({ event: 'headers_already_sent', requestId: req.requestId, path: req.path, errorMessage: err.message });
+        return;
+    }
+    const response = categorizeError(err);
+    logError(err, req, response.logLevel);
+    sendResponse(req, res, response);
+};
+exports.errorHandler = errorHandler;
+const notFoundHandler = (req, res, _next) => {
+    const message = `Route not found: ${req.method} ${req.path}`;
+    log.warn({ event: 'route_not_found', path: req.path, method: req.method, requestId: req.requestId });
+    if (wantsJson(req)) {
+        res.status(404).json({ error: { code: 'NOT_FOUND', message, requestId: req.requestId } });
+    }
+    else {
+        res.status(404).send((0, _404_message_1.default)(message));
+    }
+};
+exports.notFoundHandler = notFoundHandler;

package/middleware/favicon.d.ts

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

package/middleware/favicon.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.favicon = void 0;
+const FAVICON_BASE64 = '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';
+const faviconBuffer = Buffer.from(FAVICON_BASE64, 'base64');
+const favicon = (req, res, next) => {
+    if (req.path === '/favicon.ico' && req.method === 'GET') {
+        res.setHeader('Content-Type', 'image/x-icon');
+        res.setHeader('Content-Length', faviconBuffer.length);
+        res.setHeader('Cache-Control', 'public, max-age=86400');
+        res.status(200).send(faviconBuffer);
+        return;
+    }
+    next();
+};
+exports.favicon = favicon;

package/middleware/graphile.d.ts

@@ -1,4 +1,18 @@
 import { ConstructiveOptions } from '@constructive-io/graphql-types';
 import { RequestHandler } from 'express';
 import './types';
+/**
+ * Returns the number of currently in-flight handler creation operations.
+ * Useful for monitoring and debugging.
+ */
+export declare function getInFlightCount(): number;
+/**
+ * Returns the cache keys for all currently in-flight handler creation operations.
+ * Useful for monitoring and debugging.
+ */
+export declare function getInFlightKeys(): string[];
+/**
+ * Clears the in-flight map. Used for testing purposes.
+ */
+export declare function clearInFlightMap(): void;
 export declare const graphile: (opts: ConstructiveOptions) => RequestHandler;

package/middleware/graphile.js

@@ -1,18 +1,122 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.graphile = void 0;
+exports.getInFlightCount = getInFlightCount;
+exports.getInFlightKeys = getInFlightKeys;
+exports.clearInFlightMap = clearInFlightMap;
 const logger_1 = require("@pgpmjs/logger");
 const graphile_cache_1 = require("graphile-cache");
 const graphile_settings_1 = require("graphile-settings");
 const pg_cache_1 = require("pg-cache");
-const postgraphile_1 = require("postgraphile");
+const pg_env_1 = require("pg-env");
 require("./types"); // for Request type
-const PublicKeySignature_1 = __importDefault(require("../plugins/PublicKeySignature"));
+const api_errors_1 = require("../errors/api-errors");
+/**
+ * Custom maskError function that always returns the original error.
+ *
+ * By default, grafserv masks errors for security (hiding sensitive database errors
+ * from clients). We disable this masking to show full error messages.
+ *
+ * Upstream reference:
+ * - grafserv defaultMaskError: node_modules/grafserv/dist/options.js
+ * - SafeError interface: grafast isSafeError() - errors implementing SafeError
+ *   are shown as-is even with default masking
+ *
+ * If you need to restore masking behavior, see the upstream implementation which:
+ * 1. Returns GraphQLError instances as-is
+ * 2. Returns SafeError instances with their message exposed
+ * 3. Masks other errors with a hash/ID and logs the original
+ */
+const maskError = (error) => {
+    return error;
+};
+// =============================================================================
+// Single-Flight Pattern: In-Flight Tracking
+// =============================================================================
+/**
+ * Tracks in-flight handler creation promises to prevent duplicate creations.
+ * When multiple concurrent requests arrive for the same cache key, only the
+ * first request creates the handler while others wait on the same promise.
+ */
+const creating = new Map();
+/**
+ * Returns the number of currently in-flight handler creation operations.
+ * Useful for monitoring and debugging.
+ */
+function getInFlightCount() {
+    return creating.size;
+}
+/**
+ * Returns the cache keys for all currently in-flight handler creation operations.
+ * Useful for monitoring and debugging.
+ */
+function getInFlightKeys() {
+    return [...creating.keys()];
+}
+/**
+ * Clears the in-flight map. Used for testing purposes.
+ */
+function clearInFlightMap() {
+    creating.clear();
+}
 const log = new logger_1.Logger('graphile');
 const reqLabel = (req) => req.requestId ? `[${req.requestId}]` : '[req]';
+/**
+ * Build a PostGraphile v5 preset for a tenant
+ */
+const buildPreset = (connectionString, schemas, anonRole, roleName) => ({
+    extends: [graphile_settings_1.ConstructivePreset],
+    pgServices: [
+        (0, graphile_settings_1.makePgService)({
+            connectionString,
+            schemas,
+        }),
+    ],
+    grafserv: {
+        graphqlPath: '/graphql',
+        graphiqlPath: '/graphiql',
+        graphiql: true,
+        maskError,
+    },
+    grafast: {
+        explain: process.env.NODE_ENV === 'development',
+        context: (requestContext) => {
+            // In grafserv/express/v4, the request is available at requestContext.expressv4.req
+            const req = requestContext?.expressv4?.req;
+            const context = {};
+            if (req) {
+                if (req.databaseId) {
+                    context['jwt.claims.database_id'] = req.databaseId;
+                }
+                if (req.clientIp) {
+                    context['jwt.claims.ip_address'] = req.clientIp;
+                }
+                if (req.get('origin')) {
+                    context['jwt.claims.origin'] = req.get('origin');
+                }
+                if (req.get('User-Agent')) {
+                    context['jwt.claims.user_agent'] = req.get('User-Agent');
+                }
+                if (req.token?.user_id) {
+                    return {
+                        pgSettings: {
+                            role: roleName,
+                            'jwt.claims.token_id': req.token.id,
+                            'jwt.claims.user_id': req.token.user_id,
+                            ...context,
+                        },
+                    };
+                }
+            }
+            return {
+                pgSettings: {
+                    role: anonRole,
+                    ...context,
+                },
+            };
+        },
+    },
+});
 const graphile = (opts) => {
     return async (req, res, next) => {
         const label = reqLabel(req);
@@ -29,76 +133,57 @@ const graphile = (opts) => {
             }
             const { dbname, anonRole, roleName, schema } = api;
             const schemaLabel = schema?.join(',') || 'unknown';
+            // =========================================================================
+            // Phase A: Cache Check (fast path)
+            // =========================================================================
             const cached = graphile_cache_1.graphileCache.get(key);
             if (cached) {
                 log.debug(`${label} PostGraphile cache hit key=${key} db=${dbname} schemas=${schemaLabel}`);
                 return cached.handler(req, res, next);
             }
             log.debug(`${label} PostGraphile cache miss key=${key} db=${dbname} schemas=${schemaLabel}`);
-            const options = (0, graphile_settings_1.getGraphileSettings)({
-                ...opts,
-                graphile: {
-                    ...opts.graphile,
-                    schema: schema,
-                },
-            });
-            const pubkey_challenge = api.apiModules.find((mod) => mod.name === 'pubkey_challenge');
-            if (pubkey_challenge && pubkey_challenge.data) {
-                log.info(`${label} Enabling PublicKeySignature plugin for ${dbname}`);
-                options.appendPlugins.push((0, PublicKeySignature_1.default)(pubkey_challenge.data));
-            }
-            options.appendPlugins = options.appendPlugins ?? [];
-            if (opts.graphile?.appendPlugins) {
-                options.appendPlugins.push(...opts.graphile.appendPlugins);
-            }
-            options.pgSettings = async function pgSettings(request) {
-                const gqlReq = request;
-                const settingsLabel = reqLabel(gqlReq);
-                const context = {
-                    [`jwt.claims.database_id`]: gqlReq.databaseId,
-                    [`jwt.claims.ip_address`]: gqlReq.clientIp,
-                };
-                if (gqlReq.get('origin')) {
-                    context['jwt.claims.origin'] = gqlReq.get('origin');
+            // =========================================================================
+            // Phase B: In-Flight Check (single-flight coalescing)
+            // =========================================================================
+            const inFlight = creating.get(key);
+            if (inFlight) {
+                log.debug(`${label} Coalescing request for PostGraphile[${key}] - waiting for in-flight creation`);
+                try {
+                    const instance = await inFlight;
+                    return instance.handler(req, res, next);
                 }
-                if (gqlReq.get('User-Agent')) {
-                    context['jwt.claims.user_agent'] = gqlReq.get('User-Agent');
+                catch (error) {
+                    // Re-throw to be caught by outer try-catch
+                    throw error;
                 }
-                if (gqlReq?.token?.user_id) {
-                    log.debug(`${settingsLabel} pgSettings role=${roleName} db=${gqlReq.databaseId} ip=${gqlReq.clientIp}`);
-                    return {
-                        role: roleName,
-                        [`jwt.claims.token_id`]: gqlReq.token.id,
-                        [`jwt.claims.user_id`]: gqlReq.token.user_id,
-                        ...context,
-                    };
-                }
-                log.debug(`${settingsLabel} pgSettings role=${anonRole} db=${gqlReq.databaseId} ip=${gqlReq.clientIp}`);
-                return { role: anonRole, ...context };
-            };
-            options.graphqlRoute = '/graphql';
-            options.graphiqlRoute = '/graphiql';
-            options.graphileBuildOptions = {
-                ...options.graphileBuildOptions,
-                ...opts.graphile?.graphileBuildOptions,
-            };
-            const graphileOpts = {
-                ...options,
-                ...opts.graphile?.overrideSettings,
-            };
-            log.info(`${label} Building PostGraphile handler key=${key} db=${dbname} schemas=${schemaLabel} role=${roleName} anon=${anonRole}`);
-            const pgPool = (0, pg_cache_1.getPgPool)({
+            }
+            // =========================================================================
+            // Phase C: Create New Handler (first request for this key)
+            // =========================================================================
+            log.info(`${label} Building PostGraphile v5 handler key=${key} db=${dbname} schemas=${schemaLabel} role=${roleName} anon=${anonRole}`);
+            const pgConfig = (0, pg_env_1.getPgEnvOptions)({
                 ...opts.pg,
                 database: dbname,
             });
-            const handler = (0, postgraphile_1.postgraphile)(pgPool, schema, graphileOpts);
-            graphile_cache_1.graphileCache.set(key, {
-                pgPool,
-                pgPoolKey: dbname,
-                handler,
-            });
-            log.info(`${label} Cached PostGraphile handler key=${key} db=${dbname}`);
-            return handler(req, res, next);
+            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 });
+            creating.set(key, creationPromise);
+            try {
+                const instance = await creationPromise;
+                graphile_cache_1.graphileCache.set(key, instance);
+                log.info(`${label} Cached PostGraphile v5 handler key=${key} db=${dbname}`);
+                return instance.handler(req, res, next);
+            }
+            catch (error) {
+                log.error(`${label} Failed to create PostGraphile[${key}]:`, error);
+                throw new api_errors_1.HandlerCreationError(`Failed to create handler for ${key}: ${error instanceof Error ? error.message : String(error)}`, { cacheKey: key, cause: error instanceof Error ? error.message : String(error) });
+            }
+            finally {
+                // Always clean up in-flight tracker
+                creating.delete(key);
+            }
         }
         catch (e) {
             log.error(`${label} PostGraphile middleware error`, e);

package/options.d.ts

@@ -0,0 +1,131 @@
+/**
+ * GraphQL Server Options - Configuration utilities
+ *
+ * This module provides type-safe configuration utilities for the GraphQL server.
+ * It includes type guards for runtime validation and utility functions for
+ * configuration normalization.
+ *
+ * The main configuration type is `ConstructiveOptions` from @constructive-io/graphql-types.
+ *
+ * @module options
+ */
+import type { PgConfig } from 'pg-env';
+import type { ServerOptions, CDNOptions, DeploymentOptions, MigrationOptions, JobsConfig, PgTestConnectionOptions } from '@pgpmjs/types';
+import type { ConstructiveOptions, GraphileOptions, GraphileFeatureOptions, ApiOptions } from '@constructive-io/graphql-types';
+export type { PgConfig, ServerOptions, CDNOptions, DeploymentOptions, MigrationOptions, JobsConfig, PgTestConnectionOptions, GraphileOptions, GraphileFeatureOptions, ApiOptions, ConstructiveOptions };
+export type CdnOptions = CDNOptions;
+export type JobsOptions = JobsConfig;
+export type DbOptions = PgTestConnectionOptions;
+/**
+ * Default configuration values for GraphQL server
+ *
+ * Provides sensible defaults for all currently active fields.
+ */
+export declare const serverDefaults: Partial<ConstructiveOptions>;
+/**
+ * Type guard to validate if an unknown value is a valid ConstructiveOptions object
+ *
+ * Validates that:
+ * 1. The value is a non-null object
+ * 2. Contains at least one recognized field from the interface
+ * 3. All recognized fields that exist have object values (not primitives)
+ *
+ * @param opts - Unknown value to validate
+ * @returns True if opts is a valid ConstructiveOptions object
+ *
+ * @example
+ * ```typescript
+ * if (isConstructiveOptions(unknownConfig)) {
+ *   // TypeScript knows unknownConfig is ConstructiveOptions
+ *   const { pg, server } = unknownConfig;
+ * }
+ * ```
+ */
+export declare function isConstructiveOptions(opts: unknown): opts is ConstructiveOptions;
+/**
+ * Type guard to check if an object has PostgreSQL configuration
+ *
+ * @param opts - Unknown value to check
+ * @returns True if opts has a defined pg property
+ *
+ * @example
+ * ```typescript
+ * if (hasPgConfig(config)) {
+ *   console.log(config.pg.host);
+ * }
+ * ```
+ */
+export declare function hasPgConfig(opts: unknown): opts is {
+    pg: Partial<PgConfig>;
+};
+/**
+ * Type guard to check if an object has HTTP server configuration
+ *
+ * @param opts - Unknown value to check
+ * @returns True if opts has a defined server property
+ *
+ * @example
+ * ```typescript
+ * if (hasServerConfig(config)) {
+ *   console.log(config.server.port);
+ * }
+ * ```
+ */
+export declare function hasServerConfig(opts: unknown): opts is {
+    server: ServerOptions;
+};
+/**
+ * Type guard to check if an object has API configuration
+ *
+ * @param opts - Unknown value to check
+ * @returns True if opts has a defined api property
+ *
+ * @example
+ * ```typescript
+ * if (hasApiConfig(config)) {
+ *   console.log(config.api.exposedSchemas);
+ * }
+ * ```
+ */
+export declare function hasApiConfig(opts: unknown): opts is {
+    api: ApiOptions;
+};
+/**
+ * Detects if the given options object uses a deprecated/legacy format
+ *
+ * Checks for presence of legacy field names that indicate the configuration
+ * needs to be migrated to ConstructiveOptions format.
+ *
+ * @param opts - Unknown value to check
+ * @returns True if legacy configuration patterns are detected
+ *
+ * @example
+ * ```typescript
+ * if (isLegacyOptions(config)) {
+ *   console.warn('Detected legacy configuration format. Please migrate to ConstructiveOptions.');
+ * }
+ * ```
+ */
+export declare function isLegacyOptions(opts: unknown): boolean;
+/**
+ * Normalizes input to a ConstructiveOptions object with defaults applied
+ *
+ * Accepts ConstructiveOptions and returns a fully normalized object
+ * with default values applied via deep merge. User-provided values override defaults.
+ *
+ * @param opts - ConstructiveOptions to normalize
+ * @returns ConstructiveOptions with defaults filled in
+ *
+ * @example
+ * ```typescript
+ * // Partial config - missing fields filled from defaults
+ * const normalized = normalizeServerOptions({
+ *   pg: { database: 'myapp' }
+ * });
+ *
+ * // normalized.pg.host === 'localhost' (from default)
+ * // normalized.pg.database === 'myapp' (from user config)
+ * // normalized.server.port === 3000 (from default)
+ * ```
+ */
+export declare function normalizeServerOptions(opts: ConstructiveOptions): ConstructiveOptions;