@constructive-io/graphql-server 5.25.2 → 5.27.0

package/esm/middleware/graphile-introspection.js

@@ -0,0 +1,65 @@
+import { resolvePreset } from 'graphile-config';
+import { makePgService } from 'graphile-settings';
+const SCOPED_INTROSPECTION_PLUGIN = 'ConstructivePgIntrospectionPlugin';
+let scopedIntrospectionPresetPromise;
+const loadScopedIntrospectionPreset = () => {
+    scopedIntrospectionPresetPromise ??=
+        import('graphile-scoped-introspection').then(({ ScopedIntrospectionPreset }) => ScopedIntrospectionPreset);
+    return scopedIntrospectionPresetPromise;
+};
+/**
+ * Resolve caller-provided Graphile configuration before deciding whether the
+ * optional scoped introspection package is needed. Graphile config applies
+ * nested `extends` entries before the containing preset, so this preserves the
+ * same precedence used by the eventual schema build.
+ */
+export const resolveCallerPreset = (graphileOptions) => {
+    const preset = graphileOptions?.preset;
+    const presets = [
+        ...(graphileOptions?.extends ?? []),
+        ...(preset ? [preset] : [])
+    ];
+    return presets.length > 0 ? resolvePreset({ extends: presets }) : undefined;
+};
+const hasLocalScopedIntrospectionPreset = (preset) => preset?.plugins.some((plugin) => plugin.name === SCOPED_INTROSPECTION_PLUGIN) ??
+    false;
+const hasUpstreamIntrospectionDisabled = (preset) => preset?.disablePlugins.includes('PgIntrospectionPlugin') ?? false;
+/**
+ * Select the stock or scoped introspection wiring once, while constructing a
+ * server-owned schema handler. The stock branch returns before the scoped
+ * package (and its upstream contract sentinel) is loaded.
+ */
+export const makeIntrospectionWiring = async (pool, schemas, graphileOptions, loadScopedPreset = loadScopedIntrospectionPreset, introspectionRole) => {
+    const pgSettingsForIntrospection = introspectionRole ? { role: introspectionRole } : undefined;
+    const pgService = makePgService({ pool, schemas, pgSettingsForIntrospection });
+    const callerPreset = resolveCallerPreset(graphileOptions);
+    const scopedConfig = callerPreset?.gather?.pgScopedIntrospection;
+    const hasScopedConfiguration = scopedConfig !== undefined;
+    // An explicitly supplied local preset already installs the replacement
+    // plugin. Keep that path synchronous and avoid importing the optional
+    // package a second time. A raw plugin entry may omit the stock plugin's
+    // disablement, so add that narrow preset to keep the replacement atomic.
+    if (hasLocalScopedIntrospectionPreset(callerPreset)) {
+        return {
+            presets: hasUpstreamIntrospectionDisabled(callerPreset)
+                ? []
+                : [{ disablePlugins: ['PgIntrospectionPlugin'] }],
+            pgService
+        };
+    }
+    if (!hasScopedConfiguration) {
+        return {
+            presets: [],
+            pgService
+        };
+    }
+    // Load the replacement whenever the map is supplied, including an empty map,
+    // entries set to false, or entries keyed by an unknown service. The
+    // replacement owns validation; leaving it out would cause Graphile's stock
+    // plugin to silently ignore the gather option in those cases.
+    const scopedPreset = await loadScopedPreset();
+    return {
+        presets: [scopedPreset],
+        pgService
+    };
+};

package/esm/middleware/graphile.js

@@ -5,7 +5,7 @@ import { getNodeEnv } from '@pgpmjs/env';
 import { Logger } from '@pgpmjs/logger';
 import { createGraphileInstance, graphileCache } from 'graphile-cache';
 import { createFunctionBindingsPlugin } from 'graphile-function-bindings';
-import { createConstructivePreset, makePgService } from 'graphile-settings';
+import { createConstructivePreset } from 'graphile-settings';
 import { getPgPool } from 'pg-cache';
 import { getPgEnvOptions } from 'pg-env';
 import { isGraphqlObservabilityEnabled } from '../diagnostics/observability';
@@ -14,6 +14,7 @@ import { respondWithGraphQLError } from '../errors/graphql-response';
 import { AuthCookiePlugin } from '../plugins/auth-cookie-plugin';
 import { createErrorEventsPlugin } from '../plugins/error-events-plugin';
 import { RequestProtectionPlugin } from '../plugins/request-protection-plugin';
+import { makeIntrospectionWiring } from './graphile-introspection';
 import { maskError } from './mask-error';
 import { observeGraphileBuild } from './observability/graphile-build-stats';
 const isDev = () => getNodeEnv() === 'development';
@@ -56,10 +57,19 @@ const reqLabel = (req) => (req.requestId ? `[${req.requestId}]` : '[req]');
  * plugin preset.  Without settings the default preset is used
  * (everything on except aggregates).
  */
-const buildPreset = (pool, schemas, anonRole, roleName, introspectionRole, databaseSettings, apiId, compute) => {
+const buildPreset = async (pool, schemas, anonRole, roleName, introspectionRole, graphileOptions, databaseSettings, apiId, compute) => {
+    const introspection = await makeIntrospectionWiring(pool, schemas, graphileOptions, undefined, introspectionRole);
+    const configuredPreset = graphileOptions?.preset ?? {};
     return {
-        extends: [createConstructivePreset(databaseSettings)],
+        ...configuredPreset,
+        extends: [
+            createConstructivePreset(databaseSettings),
+            ...(graphileOptions?.extends ?? []),
+            ...(configuredPreset.extends ?? []),
+            ...introspection.presets
+        ],
         plugins: [
+            ...(configuredPreset.plugins ?? []),
             AuthCookiePlugin,
             RequestProtectionPlugin,
             createErrorEventsPlugin(pool),
@@ -83,20 +93,7 @@ const buildPreset = (pool, schemas, anonRole, roleName, introspectionRole, datab
                 ]
                 : [])
         ],
-        pgServices: [
-            makePgService({
-                pool,
-                schemas,
-                // Introspection runs outside any request, so it has no served role to
-                // inherit: unset, it reads the catalog as whatever role the pool
-                // connected as (a superuser in most deployments) and the schema
-                // advertises that role's reach. Naming the role keeps schema shape
-                // tied to a bounded role's grants.
-                ...(introspectionRole && {
-                    pgSettingsForIntrospection: { role: introspectionRole }
-                })
-            })
-        ],
+        pgServices: [introspection.pgService],
         grafserv: {
             graphqlPath: '/graphql',
             graphiqlPath: '/graphiql',
@@ -304,18 +301,21 @@ export const graphile = (opts) => {
             // Route through pg-cache so the pool is tracked and can be cleaned up
             // properly, preventing leaked connections during database teardown.
             const pool = getPgPool(pgConfig);
-            // Create promise and store in in-flight map BEFORE try block
-            const compute = api.apiId ? await req.constructive?.useModule('compute') : undefined;
-            const preset = buildPreset(pool, schema || [], anonRole, roleName, opts.api?.introspectionRole, api.databaseSettings, api.apiId, compute);
-            const creationPromise = observeGraphileBuild({
-                cacheKey: key,
-                serviceKey: key,
-                databaseId: api.databaseId ?? null
-            }, () => createGraphileInstance({
-                preset,
-                cacheKey: key,
-                enableRealtime: api.databaseSettings?.enableRealtime
-            }), { enabled: observabilityEnabled });
+            // Register the creation promise before any asynchronous preset work so
+            // concurrent requests coalesce while optional plugin modules load.
+            const creationPromise = (async () => {
+                const compute = api.apiId ? await req.constructive?.useModule('compute') : undefined;
+                const preset = await buildPreset(pool, schema || [], anonRole, roleName, opts.api?.introspectionRole, opts.graphile, api.databaseSettings, api.apiId, compute);
+                return observeGraphileBuild({
+                    cacheKey: key,
+                    serviceKey: key,
+                    databaseId: api.databaseId ?? null
+                }, () => createGraphileInstance({
+                    preset,
+                    cacheKey: key,
+                    enableRealtime: api.databaseSettings?.enableRealtime
+                }), { enabled: observabilityEnabled });
+            })();
             creating.set(key, creationPromise);
             try {
                 const instance = await creationPromise;

package/middleware/graphile-introspection.d.ts

@@ -0,0 +1,23 @@
+import type { GraphileOptions } from '@constructive-io/graphql-types';
+import { type GraphileConfig } from 'graphile-config';
+import type { Pool } from 'pg';
+export interface IntrospectionWiring {
+    presets: GraphileConfig.Preset[];
+    pgService: GraphileConfig.PgServiceConfiguration;
+}
+export type ScopedIntrospectionPresetLoader = () => Promise<GraphileConfig.Preset>;
+type ResolvedCallerPreset = GraphileConfig.ResolvedPreset | undefined;
+/**
+ * Resolve caller-provided Graphile configuration before deciding whether the
+ * optional scoped introspection package is needed. Graphile config applies
+ * nested `extends` entries before the containing preset, so this preserves the
+ * same precedence used by the eventual schema build.
+ */
+export declare const resolveCallerPreset: (graphileOptions: GraphileOptions | undefined) => ResolvedCallerPreset;
+/**
+ * Select the stock or scoped introspection wiring once, while constructing a
+ * server-owned schema handler. The stock branch returns before the scoped
+ * package (and its upstream contract sentinel) is loaded.
+ */
+export declare const makeIntrospectionWiring: (pool: Pool, schemas: string[], graphileOptions: GraphileOptions | undefined, loadScopedPreset?: ScopedIntrospectionPresetLoader, introspectionRole?: string) => Promise<IntrospectionWiring>;
+export {};

package/middleware/graphile-introspection.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeIntrospectionWiring = exports.resolveCallerPreset = void 0;
+const graphile_config_1 = require("graphile-config");
+const graphile_settings_1 = require("graphile-settings");
+const SCOPED_INTROSPECTION_PLUGIN = 'ConstructivePgIntrospectionPlugin';
+let scopedIntrospectionPresetPromise;
+const loadScopedIntrospectionPreset = () => {
+    scopedIntrospectionPresetPromise ??=
+        import('graphile-scoped-introspection').then(({ ScopedIntrospectionPreset }) => ScopedIntrospectionPreset);
+    return scopedIntrospectionPresetPromise;
+};
+/**
+ * Resolve caller-provided Graphile configuration before deciding whether the
+ * optional scoped introspection package is needed. Graphile config applies
+ * nested `extends` entries before the containing preset, so this preserves the
+ * same precedence used by the eventual schema build.
+ */
+const resolveCallerPreset = (graphileOptions) => {
+    const preset = graphileOptions?.preset;
+    const presets = [
+        ...(graphileOptions?.extends ?? []),
+        ...(preset ? [preset] : [])
+    ];
+    return presets.length > 0 ? (0, graphile_config_1.resolvePreset)({ extends: presets }) : undefined;
+};
+exports.resolveCallerPreset = resolveCallerPreset;
+const hasLocalScopedIntrospectionPreset = (preset) => preset?.plugins.some((plugin) => plugin.name === SCOPED_INTROSPECTION_PLUGIN) ??
+    false;
+const hasUpstreamIntrospectionDisabled = (preset) => preset?.disablePlugins.includes('PgIntrospectionPlugin') ?? false;
+/**
+ * Select the stock or scoped introspection wiring once, while constructing a
+ * server-owned schema handler. The stock branch returns before the scoped
+ * package (and its upstream contract sentinel) is loaded.
+ */
+const makeIntrospectionWiring = async (pool, schemas, graphileOptions, loadScopedPreset = loadScopedIntrospectionPreset, introspectionRole) => {
+    const pgSettingsForIntrospection = introspectionRole ? { role: introspectionRole } : undefined;
+    const pgService = (0, graphile_settings_1.makePgService)({ pool, schemas, pgSettingsForIntrospection });
+    const callerPreset = (0, exports.resolveCallerPreset)(graphileOptions);
+    const scopedConfig = callerPreset?.gather?.pgScopedIntrospection;
+    const hasScopedConfiguration = scopedConfig !== undefined;
+    // An explicitly supplied local preset already installs the replacement
+    // plugin. Keep that path synchronous and avoid importing the optional
+    // package a second time. A raw plugin entry may omit the stock plugin's
+    // disablement, so add that narrow preset to keep the replacement atomic.
+    if (hasLocalScopedIntrospectionPreset(callerPreset)) {
+        return {
+            presets: hasUpstreamIntrospectionDisabled(callerPreset)
+                ? []
+                : [{ disablePlugins: ['PgIntrospectionPlugin'] }],
+            pgService
+        };
+    }
+    if (!hasScopedConfiguration) {
+        return {
+            presets: [],
+            pgService
+        };
+    }
+    // Load the replacement whenever the map is supplied, including an empty map,
+    // entries set to false, or entries keyed by an unknown service. The
+    // replacement owns validation; leaving it out would cause Graphile's stock
+    // plugin to silently ignore the gather option in those cases.
+    const scopedPreset = await loadScopedPreset();
+    return {
+        presets: [scopedPreset],
+        pgService
+    };
+};
+exports.makeIntrospectionWiring = makeIntrospectionWiring;

package/middleware/graphile.js

@@ -20,6 +20,7 @@ const graphql_response_1 = require("../errors/graphql-response");
 const auth_cookie_plugin_1 = require("../plugins/auth-cookie-plugin");
 const error_events_plugin_1 = require("../plugins/error-events-plugin");
 const request_protection_plugin_1 = require("../plugins/request-protection-plugin");
+const graphile_introspection_1 = require("./graphile-introspection");
 const mask_error_1 = require("./mask-error");
 const graphile_build_stats_1 = require("./observability/graphile-build-stats");
 const isDev = () => (0, env_1.getNodeEnv)() === 'development';
@@ -62,10 +63,19 @@ const reqLabel = (req) => (req.requestId ? `[${req.requestId}]` : '[req]');
  * plugin preset.  Without settings the default preset is used
  * (everything on except aggregates).
  */
-const buildPreset = (pool, schemas, anonRole, roleName, introspectionRole, databaseSettings, apiId, compute) => {
+const buildPreset = async (pool, schemas, anonRole, roleName, introspectionRole, graphileOptions, databaseSettings, apiId, compute) => {
+    const introspection = await (0, graphile_introspection_1.makeIntrospectionWiring)(pool, schemas, graphileOptions, undefined, introspectionRole);
+    const configuredPreset = graphileOptions?.preset ?? {};
     return {
-        extends: [(0, graphile_settings_1.createConstructivePreset)(databaseSettings)],
+        ...configuredPreset,
+        extends: [
+            (0, graphile_settings_1.createConstructivePreset)(databaseSettings),
+            ...(graphileOptions?.extends ?? []),
+            ...(configuredPreset.extends ?? []),
+            ...introspection.presets
+        ],
         plugins: [
+            ...(configuredPreset.plugins ?? []),
             auth_cookie_plugin_1.AuthCookiePlugin,
             request_protection_plugin_1.RequestProtectionPlugin,
             (0, error_events_plugin_1.createErrorEventsPlugin)(pool),
@@ -89,20 +99,7 @@ const buildPreset = (pool, schemas, anonRole, roleName, introspectionRole, datab
                 ]
                 : [])
         ],
-        pgServices: [
-            (0, graphile_settings_1.makePgService)({
-                pool,
-                schemas,
-                // Introspection runs outside any request, so it has no served role to
-                // inherit: unset, it reads the catalog as whatever role the pool
-                // connected as (a superuser in most deployments) and the schema
-                // advertises that role's reach. Naming the role keeps schema shape
-                // tied to a bounded role's grants.
-                ...(introspectionRole && {
-                    pgSettingsForIntrospection: { role: introspectionRole }
-                })
-            })
-        ],
+        pgServices: [introspection.pgService],
         grafserv: {
             graphqlPath: '/graphql',
             graphiqlPath: '/graphiql',
@@ -310,18 +307,21 @@ const graphile = (opts) => {
             // Route through pg-cache so the pool is tracked and can be cleaned up
             // properly, preventing leaked connections during database teardown.
             const pool = (0, pg_cache_1.getPgPool)(pgConfig);
-            // Create promise and store in in-flight map BEFORE try block
-            const compute = api.apiId ? await req.constructive?.useModule('compute') : undefined;
-            const preset = buildPreset(pool, schema || [], anonRole, roleName, opts.api?.introspectionRole, api.databaseSettings, api.apiId, compute);
-            const creationPromise = (0, graphile_build_stats_1.observeGraphileBuild)({
-                cacheKey: key,
-                serviceKey: key,
-                databaseId: api.databaseId ?? null
-            }, () => (0, graphile_cache_1.createGraphileInstance)({
-                preset,
-                cacheKey: key,
-                enableRealtime: api.databaseSettings?.enableRealtime
-            }), { enabled: observabilityEnabled });
+            // Register the creation promise before any asynchronous preset work so
+            // concurrent requests coalesce while optional plugin modules load.
+            const creationPromise = (async () => {
+                const compute = api.apiId ? await req.constructive?.useModule('compute') : undefined;
+                const preset = await buildPreset(pool, schema || [], anonRole, roleName, opts.api?.introspectionRole, opts.graphile, api.databaseSettings, api.apiId, compute);
+                return (0, graphile_build_stats_1.observeGraphileBuild)({
+                    cacheKey: key,
+                    serviceKey: key,
+                    databaseId: api.databaseId ?? null
+                }, () => (0, graphile_cache_1.createGraphileInstance)({
+                    preset,
+                    cacheKey: key,
+                    enableRealtime: api.databaseSettings?.enableRealtime
+                }), { enabled: observabilityEnabled });
+            })();
             creating.set(key, creationPromise);
             try {
                 const instance = await creationPromise;

package/middleware/types.d.ts

@@ -1,17 +1,5 @@
-import type { RequestProtection } from '@constructive-io/express-context';
-import type { ApiStructure } from '../types';
-export type ConstructiveAPIToken = {
-    id?: string;
-    user_id?: string;
-    principal_id?: string;
-    session_id?: string;
-    access_level?: string;
-    kind?: string;
-    root_session_id?: string;
-    parent_session_id?: string;
-    intent?: string;
-    [key: string]: unknown;
-};
+import type { ApiStructure, ConstructiveAPIToken, RequestProtection } from '@constructive-io/express-context';
+export type { ConstructiveAPIToken } from '@constructive-io/express-context';
 declare global {
     namespace Express {
         interface Request {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-server",
-  "version": "5.25.2",
+  "version": "5.27.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "Constructive GraphQL Server",
   "main": "index.js",
@@ -41,41 +41,42 @@
     "backend"
   ],
   "dependencies": {
-    "@agentic-kit/ollama": "2.14.0",
-    "@constructive-io/csrf": "^0.29.1",
-    "@constructive-io/errors": "^0.16.1",
-    "@constructive-io/express-context": "^0.31.1",
-    "@constructive-io/graphql-env": "^3.32.2",
-    "@constructive-io/graphql-types": "^3.31.2",
-    "@constructive-io/llm-env": "^0.14.1",
-    "@constructive-io/query-builder": "^3.13.7",
-    "@constructive-io/s3-utils": "^2.33.1",
-    "@constructive-io/url-domains": "^2.30.1",
+    "@agentic-kit/ollama": "2.15.0",
+    "@constructive-io/csrf": "^0.30.0",
+    "@constructive-io/errors": "^0.18.0",
+    "@constructive-io/express-context": "^0.33.0",
+    "@constructive-io/graphql-env": "^3.34.0",
+    "@constructive-io/graphql-types": "^3.33.0",
+    "@constructive-io/llm-env": "^0.15.0",
+    "@constructive-io/query-builder": "^3.15.0",
+    "@constructive-io/s3-utils": "^2.34.0",
+    "@constructive-io/url-domains": "^2.31.0",
     "@graphile-contrib/pg-many-to-many": "2.0.0-rc.2",
-    "@pgpmjs/env": "^2.43.6",
-    "@pgpmjs/logger": "^2.25.1",
-    "@pgpmjs/server-utils": "^3.27.6",
-    "@pgpmjs/types": "^2.53.4",
+    "@pgpmjs/env": "^2.45.0",
+    "@pgpmjs/logger": "^2.26.0",
+    "@pgpmjs/server-utils": "^3.29.0",
+    "@pgpmjs/types": "^2.55.0",
     "cors": "^2.8.6",
     "deepmerge": "^4.3.1",
     "express": "^5.2.1",
-    "gql-ast": "^3.24.1",
+    "gql-ast": "^3.25.0",
     "grafast": "1.1.2",
     "grafserv": "1.0.1",
     "graphile-build": "5.1.1",
     "graphile-build-pg": "5.1.3",
-    "graphile-cache": "^4.12.6",
+    "graphile-cache": "^4.14.0",
     "graphile-config": "1.1.0",
-    "graphile-function-bindings": "^1.14.7",
-    "graphile-settings": "^6.21.9",
+    "graphile-function-bindings": "^1.16.0",
+    "graphile-scoped-introspection": "^0.3.0",
+    "graphile-settings": "^6.23.0",
     "graphile-utils": "5.0.3",
     "graphql": "16.13.0",
     "graphql-upload": "^13.0.0",
     "lru-cache": "^11.2.7",
     "pg": "^8.21.0",
-    "pg-cache": "^3.27.6",
-    "pg-env": "^1.31.1",
-    "pg-query-context": "^2.30.1",
+    "pg-cache": "^3.29.0",
+    "pg-env": "^1.32.0",
+    "pg-query-context": "^2.31.0",
     "pg-sql2": "5.0.1",
     "postgraphile": "5.1.4",
     "request-ip": "^3.3.0"
@@ -90,11 +91,11 @@
     "@types/request-ip": "^0.0.41",
     "@types/supertest": "^7.2.1",
     "cookie-parser": "^1.4.7",
-    "graphile-test": "5.14.7",
+    "graphile-test": "5.16.0",
     "makage": "^0.8.0",
     "nodemon": "^3.1.14",
     "supertest": "^7.2.2",
     "ts-node": "^10.9.2"
   },
-  "gitHead": "9bba983b38395277e0400294aaa380e586b049d4"
+  "gitHead": "baa84094b8541eb5000701b0060aa5b298032dc7"
 }