@constructive-io/graphql-server 3.1.1 → 4.0.1

package/esm/middleware/auth.js

@@ -8,6 +8,7 @@ const isDev = () => getNodeEnv() === 'development';
 export 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;
@@ -17,19 +18,26 @@ export 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,
                 };
@@ -39,25 +47,28 @@ export 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 pgQueryContext({
                         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: [
                             {
@@ -71,8 +82,15 @@ export 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/esm/middleware/error-handler.js

@@ -0,0 +1,86 @@
+import { getNodeEnv } from '@constructive-io/graphql-env';
+import { Logger } from '@pgpmjs/logger';
+import { isApiError } from '../errors/api-errors';
+import errorPage404Message from '../errors/404-message';
+import errorPage50x from '../errors/50x';
+import './types';
+const log = new Logger('error-handler');
+const isDevelopment = () => 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 (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 (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 ? errorPage50x : errorPage404Message(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 (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 });
+    }
+};
+export 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);
+};
+export 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(errorPage404Message(message));
+    }
+};

package/esm/middleware/favicon.js

@@ -0,0 +1,12 @@
+const FAVICON_BASE64 = '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';
+const faviconBuffer = Buffer.from(FAVICON_BASE64, 'base64');
+export 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();
+};

package/esm/middleware/graphile.js

@@ -1,12 +1,116 @@
 import { Logger } from '@pgpmjs/logger';
-import { graphileCache } from 'graphile-cache';
-import { getGraphileSettings as getSettings } from 'graphile-settings';
-import { getPgPool } from 'pg-cache';
-import { postgraphile } from 'postgraphile';
+import { createGraphileInstance, graphileCache } from 'graphile-cache';
+import { ConstructivePreset, makePgService } from 'graphile-settings';
+import { buildConnectionString } from 'pg-cache';
+import { getPgEnvOptions } from 'pg-env';
 import './types'; // for Request type
-import PublicKeySignature from '../plugins/PublicKeySignature';
+import { HandlerCreationError } from '../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.
+ */
+export function getInFlightCount() {
+    return creating.size;
+}
+/**
+ * Returns the cache keys for all currently in-flight handler creation operations.
+ * Useful for monitoring and debugging.
+ */
+export function getInFlightKeys() {
+    return [...creating.keys()];
+}
+/**
+ * Clears the in-flight map. Used for testing purposes.
+ */
+export function clearInFlightMap() {
+    creating.clear();
+}
 const log = new 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: [ConstructivePreset],
+    pgServices: [
+        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,
+                },
+            };
+        },
+    },
+});
 export const graphile = (opts) => {
     return async (req, res, next) => {
         const label = reqLabel(req);
@@ -23,76 +127,57 @@ export const graphile = (opts) => {
             }
             const { dbname, anonRole, roleName, schema } = api;
             const schemaLabel = schema?.join(',') || 'unknown';
+            // =========================================================================
+            // Phase A: Cache Check (fast path)
+            // =========================================================================
             const cached = 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 = getSettings({
-                ...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(PublicKeySignature(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 = 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 = getPgEnvOptions({
                 ...opts.pg,
                 database: dbname,
             });
-            const handler = postgraphile(pgPool, schema, graphileOpts);
-            graphileCache.set(key, {
-                pgPool,
-                pgPoolKey: dbname,
-                handler,
-            });
-            log.info(`${label} Cached PostGraphile handler key=${key} db=${dbname}`);
-            return handler(req, res, next);
+            const connectionString = 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 = createGraphileInstance({ preset, cacheKey: key });
+            creating.set(key, creationPromise);
+            try {
+                const instance = await creationPromise;
+                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 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/esm/options.js

@@ -0,0 +1,232 @@
+/**
+ * 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 deepmerge from 'deepmerge';
+import { graphileDefaults, graphileFeatureDefaults, apiDefaults } from '@constructive-io/graphql-types';
+// ============================================
+// Default Configuration
+// ============================================
+/**
+ * Default configuration values for GraphQL server
+ *
+ * Provides sensible defaults for all currently active fields.
+ */
+export const serverDefaults = {
+    pg: {
+        host: 'localhost',
+        port: 5432,
+        user: 'postgres',
+        password: 'password',
+        database: 'postgres'
+    },
+    server: {
+        host: 'localhost',
+        port: 3000,
+        trustProxy: false,
+        strictAuth: false
+    },
+    api: apiDefaults,
+    graphile: graphileDefaults,
+    features: graphileFeatureDefaults
+};
+// ============================================
+// Type Guards
+// ============================================
+/**
+ * List of all recognized fields in ConstructiveOptions
+ */
+const RECOGNIZED_FIELDS = [
+    'pg',
+    'server',
+    'api',
+    'graphile',
+    'features',
+    'db',
+    'cdn',
+    'deployment',
+    'migrations',
+    'jobs'
+];
+/**
+ * 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 function isConstructiveOptions(opts) {
+    if (opts === null || opts === undefined) {
+        return false;
+    }
+    if (typeof opts !== 'object') {
+        return false;
+    }
+    const obj = opts;
+    // Check for at least one recognized field from the interface
+    const hasRecognizedField = RECOGNIZED_FIELDS.some((field) => field in obj);
+    if (!hasRecognizedField) {
+        return false;
+    }
+    // Validate that recognized fields have object values (not primitives)
+    for (const field of RECOGNIZED_FIELDS) {
+        if (field in obj && obj[field] !== undefined && obj[field] !== null) {
+            if (typeof obj[field] !== 'object') {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+/**
+ * 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 function hasPgConfig(opts) {
+    if (opts === null || opts === undefined || typeof opts !== 'object') {
+        return false;
+    }
+    return 'pg' in opts && opts.pg !== undefined;
+}
+/**
+ * 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 function hasServerConfig(opts) {
+    if (opts === null || opts === undefined || typeof opts !== 'object') {
+        return false;
+    }
+    return 'server' in opts && opts.server !== undefined;
+}
+/**
+ * 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 function hasApiConfig(opts) {
+    if (opts === null || opts === undefined || typeof opts !== 'object') {
+        return false;
+    }
+    return 'api' in opts && opts.api !== undefined;
+}
+// ============================================
+// Internal Utilities
+// ============================================
+/**
+ * Array merge strategy that replaces arrays (source wins over target).
+ * This ensures that when a user specifies an array value, it replaces
+ * the default rather than merging/concatenating.
+ *
+ * @internal
+ */
+const replaceArrays = (_target, source) => source;
+// ============================================
+// Utility Functions
+// ============================================
+/**
+ * Legacy field names that indicate old configuration format
+ */
+const LEGACY_FIELDS = [
+    'schemas', // Old array-style schema config (should be graphile.schema)
+    'pgConfig', // Old naming (should be pg)
+    'serverPort', // Flat config (should be server.port)
+    'serverHost', // Flat config (should be server.host)
+    'dbConfig', // Old naming (should be db)
+    'postgraphile', // Old Graphile v4 naming (should be graphile)
+    'pgPool', // Direct pool config (deprecated)
+    'jwtSecret', // Flat JWT config (should be in api or auth)
+    'watchPg' // Old PostGraphile v4 option
+];
+/**
+ * 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 function isLegacyOptions(opts) {
+    if (opts === null || opts === undefined || typeof opts !== 'object') {
+        return false;
+    }
+    const obj = opts;
+    return LEGACY_FIELDS.some((field) => field in obj);
+}
+/**
+ * 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 function normalizeServerOptions(opts) {
+    // Deep merge with defaults - user options override defaults
+    return deepmerge(serverDefaults, opts, { arrayMerge: replaceArrays });
+}