graphile-scoped-introspection 0.2.0

package/index.d.ts

@@ -0,0 +1,4 @@
+export type { PgScopedIntrospectionConfig, PgScopedIntrospectionServiceConfig, SchemaScopedIntrospectionOptions, ScopedCatalogTypes, } from './plugin';
+export { ConstructivePgIntrospectionPlugin, ScopedIntrospectionPreset, scopedIntrospectionUpstreamContract, } from './plugin';
+export type { SchemaScopedIntrospectionPlan, SchemaScopedIntrospectionQuery, SchemaScopedIntrospectionScope, } from './scoped-introspection-query';
+export { makeSchemaScopedIntrospectionPlan, makeSchemaScopedIntrospectionQuery, validateSchemaScopedIntrospection, } from './scoped-introspection-query';

package/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSchemaScopedIntrospection = exports.makeSchemaScopedIntrospectionQuery = exports.makeSchemaScopedIntrospectionPlan = exports.scopedIntrospectionUpstreamContract = exports.ScopedIntrospectionPreset = exports.ConstructivePgIntrospectionPlugin = void 0;
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "ConstructivePgIntrospectionPlugin", { enumerable: true, get: function () { return plugin_1.ConstructivePgIntrospectionPlugin; } });
+Object.defineProperty(exports, "ScopedIntrospectionPreset", { enumerable: true, get: function () { return plugin_1.ScopedIntrospectionPreset; } });
+Object.defineProperty(exports, "scopedIntrospectionUpstreamContract", { enumerable: true, get: function () { return plugin_1.scopedIntrospectionUpstreamContract; } });
+var scoped_introspection_query_1 = require("./scoped-introspection-query");
+Object.defineProperty(exports, "makeSchemaScopedIntrospectionPlan", { enumerable: true, get: function () { return scoped_introspection_query_1.makeSchemaScopedIntrospectionPlan; } });
+Object.defineProperty(exports, "makeSchemaScopedIntrospectionQuery", { enumerable: true, get: function () { return scoped_introspection_query_1.makeSchemaScopedIntrospectionQuery; } });
+Object.defineProperty(exports, "validateSchemaScopedIntrospection", { enumerable: true, get: function () { return scoped_introspection_query_1.validateSchemaScopedIntrospection; } });

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "graphile-scoped-introspection",
+  "version": "0.2.0",
+  "description": "Opt-in schema-scoped PostgreSQL introspection for Graphile",
+  "author": "Constructive <developers@constructive.io>",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "dependencies": {
+    "@constructive-io/graphql-types": "^3.32.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "graphql": "16.13.0",
+    "makage": "^0.8.0",
+    "pgsql-test": "^5.14.0",
+    "postgraphile": "5.1.4"
+  },
+  "peerDependencies": {
+    "@dataplan/pg": "^1.1.1",
+    "graphile-build": "^5.1.1",
+    "graphile-build-pg": "5.1.3",
+    "graphile-config": "^1.1.0",
+    "pg-introspection": "^1.0.1"
+  },
+  "keywords": [
+    "postgraphile",
+    "graphile",
+    "constructive",
+    "plugin",
+    "postgres",
+    "introspection"
+  ],
+  "gitHead": "399437801c27b070312125f3f0ee821ce16e183e"
+}

package/plugin.d.ts

@@ -0,0 +1,21 @@
+import 'graphile-build';
+import type { GraphileConfig } from 'graphile-config';
+export type { PgScopedIntrospectionConfig, PgScopedIntrospectionServiceConfig, SchemaScopedIntrospectionOptions, ScopedCatalogTypes, } from '@constructive-io/graphql-types';
+/**
+ * CNC-owned atomic replacement for graphile-build-pg's introspection plugin.
+ * Stock-only configurations delegate to the upstream helper unchanged.
+ */
+export declare const ConstructivePgIntrospectionPlugin: GraphileConfig.Plugin;
+/** Disable upstream atomically before installing the CNC replacement. */
+export declare const ScopedIntrospectionPreset: GraphileConfig.Preset;
+export declare const scopedIntrospectionUpstreamContract: Readonly<{
+    package: "graphile-build-pg";
+    version: "5.1.3";
+    pluginName: keyof GraphileConfig.Plugins;
+    namespace: keyof GraphileConfig.GatherHelpers;
+    hasInitialCache: boolean;
+    hasInitialState: boolean;
+    hasWatch: boolean;
+    helperNames: string[];
+    hookNames: string[];
+}>;

package/plugin.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scopedIntrospectionUpstreamContract = exports.ScopedIntrospectionPreset = exports.ConstructivePgIntrospectionPlugin = void 0;
+require("graphile-build");
+const pg_1 = require("@dataplan/pg");
+const graphile_build_pg_1 = require("graphile-build-pg");
+const pg_introspection_1 = require("pg-introspection");
+const scoped_introspection_query_1 = require("./scoped-introspection-query");
+const upstreamGather = graphile_build_pg_1.PgIntrospectionPlugin.gather;
+const upstreamHelpers = upstreamGather?.helpers;
+const upstreamGetIntrospection = upstreamHelpers?.getIntrospection;
+const SUPPORTED_GRAPHILE_BUILD_PG_VERSION = '5.1.3';
+if (graphile_build_pg_1.version !== SUPPORTED_GRAPHILE_BUILD_PG_VERSION) {
+    throw new Error(`Unsupported graphile-build-pg introspection contract: expected ${SUPPORTED_GRAPHILE_BUILD_PG_VERSION}, received ${graphile_build_pg_1.version}`);
+}
+if (!upstreamGather || !upstreamHelpers || !upstreamGetIntrospection) {
+    throw new Error('graphile-build-pg PgIntrospectionPlugin no longer exposes the expected gather contract');
+}
+function getIntrospectionQuery(pgService, config) {
+    if (config === undefined || config === false) {
+        return {
+            query: { text: (0, pg_introspection_1.makeIntrospectionQuery)() },
+            scopedPlan: null,
+        };
+    }
+    const options = config === true ? {} : config;
+    const scopedPlan = (0, scoped_introspection_query_1.makeSchemaScopedIntrospectionPlan)(pgService.schemas ?? [], options);
+    return {
+        query: scopedPlan.query,
+        scopedPlan,
+    };
+}
+function assertScopedIntrospectionServices(pgServices, options) {
+    if (options === undefined)
+        return;
+    if (options === null ||
+        typeof options !== 'object' ||
+        Array.isArray(options)) {
+        throw new Error('pgScopedIntrospection must be an object keyed by PostgreSQL service name');
+    }
+    const serviceNames = new Set((pgServices ?? []).map((pgService) => pgService.name));
+    const unknownServiceNames = Object.keys(options).filter((serviceName) => !serviceNames.has(serviceName));
+    if (unknownServiceNames.length > 0) {
+        throw new Error(`Schema-scoped introspection configured for unknown PostgreSQL service(s): ${unknownServiceNames.join(', ')}`);
+    }
+    for (const [serviceName, config] of Object.entries(options)) {
+        if (config !== true &&
+            config !== false &&
+            (config === null ||
+                typeof config !== 'object' ||
+                Array.isArray(config))) {
+            throw new Error(`Schema-scoped introspection configuration for service '${serviceName}' must be true, false, or an options object`);
+        }
+    }
+}
+// Adapted from graphile-build-pg@5.1.3
+// dist/plugins/PgIntrospectionPlugin.js. The upstream function is private, so
+// mixed/scoped services must retain this service validation/query seam locally.
+async function introspectPgServices(pgServices, scopedIntrospection) {
+    assertScopedIntrospectionServices(pgServices, scopedIntrospection);
+    if (!pgServices)
+        return [];
+    const seenNames = new Map();
+    const seenPgSettingsKeys = new Map();
+    const seenWithPgClientKeys = new Map();
+    return Promise.all(pgServices.map(async (pgService, i) => {
+        const { name, pgSettingsKey, withPgClientKey } = pgService;
+        if (!name)
+            throw new Error(`pgServices[${i}] has no name`);
+        if (!withPgClientKey) {
+            throw new Error(`pgServices[${i}] has no withPgClientKey`);
+        }
+        const duplicateName = seenNames.get(name);
+        if (duplicateName !== undefined) {
+            throw new Error(`pgServices[${i}] has the same name as pgServices[${duplicateName}] (${JSON.stringify(name)})`);
+        }
+        seenNames.set(name, i);
+        const duplicateClientKey = seenWithPgClientKeys.get(withPgClientKey);
+        if (duplicateClientKey !== undefined) {
+            throw new Error(`pgServices[${i}] has the same withPgClientKey as pgServices[${duplicateClientKey}] (${JSON.stringify(withPgClientKey)})`);
+        }
+        seenWithPgClientKeys.set(withPgClientKey, i);
+        if (pgSettingsKey) {
+            const duplicateSettingsKey = seenPgSettingsKeys.get(pgSettingsKey);
+            if (duplicateSettingsKey !== undefined) {
+                throw new Error(`pgServices[${i}] has the same pgSettingsKey as pgServices[${duplicateSettingsKey}] (${JSON.stringify(pgSettingsKey)})`);
+            }
+            seenPgSettingsKeys.set(pgSettingsKey, i);
+        }
+        const { query, scopedPlan } = getIntrospectionQuery(pgService, scopedIntrospection?.[name]);
+        const result = await (0, pg_1.withPgClientFromPgService)(pgService, pgService.pgSettingsForIntrospection ?? null, (client) => client.query(query));
+        const [row] = result.rows;
+        if (!row)
+            throw new Error('Introspection failed');
+        return {
+            pgService,
+            introspectionText: row.introspection,
+            scopedPlan,
+        };
+    }));
+}
+async function announceIntrospection(info, introspections) {
+    await Promise.all(introspections.map(async ({ introspection, pgService }) => {
+        const announce = async (eventName, entities) => {
+            await Promise.all(entities.map((entity) => info.process(eventName, { entity, serviceName: pgService.name })));
+        };
+        await info.process('pgIntrospection_introspection', {
+            introspection,
+            serviceName: pgService.name,
+        });
+        await announce('pgIntrospection_namespace', introspection.namespaces);
+        await announce('pgIntrospection_class', introspection.classes);
+        await announce('pgIntrospection_attribute', introspection.attributes);
+        await announce('pgIntrospection_constraint', introspection.constraints);
+        await announce('pgIntrospection_proc', introspection.procs);
+        await announce('pgIntrospection_role', introspection.roles);
+        await announce('pgIntrospection_auth_member', introspection.auth_members);
+        await announce('pgIntrospection_type', introspection.types);
+        await announce('pgIntrospection_enum', introspection.enums);
+        await announce('pgIntrospection_extension', introspection.extensions);
+        await announce('pgIntrospection_index', introspection.indexes);
+        await announce('pgIntrospection_language', introspection.languages);
+        await announce('pgIntrospection_range', introspection.ranges);
+        await announce('pgIntrospection_depend', introspection.depends);
+        await announce('pgIntrospection_description', introspection.descriptions);
+    }));
+}
+// Adapted from graphile-build-pg@5.1.3
+// dist/plugins/PgIntrospectionPlugin.js. Upstream does not expose its
+// cache/parse/announcement flow independently from the stock query.
+function getConstructiveIntrospection(info) {
+    const pgServices = info.resolvedPreset.pgServices ?? [];
+    const scopedIntrospection = info.options.pgScopedIntrospection;
+    assertScopedIntrospectionServices(pgServices, scopedIntrospection);
+    const hasScopedService = Object.values(scopedIntrospection ?? {}).some((config) => config === true || (config !== false && config !== undefined));
+    if (!hasScopedService) {
+        return upstreamGetIntrospection(info);
+    }
+    return (info.state.getIntrospectionPromise ??
+        (info.state.getIntrospectionPromise = (async () => {
+            if (info.cache.dirty) {
+                info.cache.introspectionResultsPromise = null;
+                info.cache.dirty = false;
+            }
+            const introspectionPromise = info.cache.introspectionResultsPromise ??
+                (info.cache.introspectionResultsPromise =
+                    introspectPgServices(pgServices, scopedIntrospection));
+            introspectionPromise.then(null, () => {
+                info.cache.introspectionResultsPromise = null;
+            });
+            const rawIntrospections = await introspectionPromise;
+            // Keep the raw result promise for clean gathers. Parsed introspection is
+            // intentionally rebuilt because gather plugins may mutate their copy.
+            const introspections = rawIntrospections.map(({ pgService, introspectionText, scopedPlan }) => {
+                const introspection = (0, pg_introspection_1.parseIntrospectionResults)(introspectionText);
+                if (scopedPlan) {
+                    try {
+                        (0, scoped_introspection_query_1.validateSchemaScopedIntrospection)(introspection, scopedPlan);
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        throw new Error(`Schema-scoped introspection validation failed for PostgreSQL service '${pgService.name}': ${message}`, { cause: error });
+                    }
+                }
+                return { pgService, introspection };
+            });
+            // Announcements may call back into getIntrospection, so expose the
+            // resolved gather-local value before broadcasting entities.
+            info.state.getIntrospectionPromise = introspections;
+            await announceIntrospection(info, introspections);
+            return introspections;
+        })()));
+}
+async function getRangeByType(info, serviceName, typeId) {
+    const introspections = await info.helpers.pgIntrospection.getIntrospection();
+    const relevant = introspections.find((result) => result.pgService.name === serviceName);
+    if (!relevant)
+        throw new Error(`Could not find database '${serviceName}'`);
+    return relevant.introspection.ranges.find((range) => range.rngtypid === typeId || range.rngmultitypid === typeId);
+}
+/**
+ * CNC-owned atomic replacement for graphile-build-pg's introspection plugin.
+ * Stock-only configurations delegate to the upstream helper unchanged.
+ */
+exports.ConstructivePgIntrospectionPlugin = {
+    name: 'ConstructivePgIntrospectionPlugin',
+    description: 'Adds opt-in schema-scoped PostgreSQL introspection for Constructive',
+    version: graphile_build_pg_1.PgIntrospectionPlugin.version,
+    provides: ['PgIntrospectionPlugin'],
+    before: ['PgRegistryPlugin'],
+    gather: {
+        ...upstreamGather,
+        helpers: {
+            ...upstreamHelpers,
+            getIntrospection: getConstructiveIntrospection,
+            getRangeByType,
+        },
+    },
+};
+/** Disable upstream atomically before installing the CNC replacement. */
+exports.ScopedIntrospectionPreset = {
+    disablePlugins: ['PgIntrospectionPlugin'],
+    plugins: [exports.ConstructivePgIntrospectionPlugin],
+};
+exports.scopedIntrospectionUpstreamContract = Object.freeze({
+    package: 'graphile-build-pg',
+    version: SUPPORTED_GRAPHILE_BUILD_PG_VERSION,
+    pluginName: graphile_build_pg_1.PgIntrospectionPlugin.name,
+    namespace: upstreamGather.namespace,
+    hasInitialCache: typeof upstreamGather.initialCache === 'function',
+    hasInitialState: typeof upstreamGather.initialState === 'function',
+    hasWatch: typeof upstreamGather.watch === 'function',
+    helperNames: Object.keys(upstreamHelpers).sort(),
+    hookNames: Object.keys(upstreamGather.hooks ?? {}).sort(),
+});

package/scoped-introspection-query.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Scoped catalog SQL adapted from Graphile Crystal's
+ * utils/pg-introspection/src/scopedIntrospection.ts at commit
+ * 441cef73b0a12ed24343b7f38241af28b6454280, which is MIT licensed
+ * (Copyright © 2023 Benjie Gillam). This is a static, CNC-owned query
+ * generator: it does not inspect or rewrite the upstream query at runtime.
+ */
+import type { SchemaScopedIntrospectionOptions, ScopedCatalogTypes } from '@constructive-io/graphql-types';
+import type { Introspection } from 'pg-introspection';
+export type { SchemaScopedIntrospectionOptions, ScopedCatalogTypes, } from '@constructive-io/graphql-types';
+export interface SchemaScopedIntrospectionQuery {
+    text: string;
+    values: [string[], string[]];
+}
+export interface SchemaScopedIntrospectionScope {
+    schemas: readonly string[];
+    catalogTypes: ScopedCatalogTypes;
+    capabilityExtensions: readonly string[];
+}
+export interface SchemaScopedIntrospectionPlan {
+    query: SchemaScopedIntrospectionQuery;
+    scope: SchemaScopedIntrospectionScope;
+}
+/**
+ * Builds a parameterized introspection plan scoped to the requested schemas
+ * and the transitive object dependencies required by their objects.
+ */
+export declare const makeSchemaScopedIntrospectionPlan: (schemas: readonly string[], options?: SchemaScopedIntrospectionOptions) => SchemaScopedIntrospectionPlan;
+/**
+ * Builds only the query portion of a schema-scoped introspection plan.
+ *
+ * Prefer `makeSchemaScopedIntrospectionPlan()` when the results will be
+ * parsed and validated by this package.
+ */
+export declare const makeSchemaScopedIntrospectionQuery: (schemas: readonly string[], options?: SchemaScopedIntrospectionOptions) => SchemaScopedIntrospectionQuery;
+/** Validates that an introspection result satisfies its scoped query plan. */
+export declare function validateSchemaScopedIntrospection(introspection: Introspection, plan: SchemaScopedIntrospectionPlan): void;