@constructive-io/graphql-env 3.32.2 → 3.33.0

package/README.md

@@ -44,6 +44,61 @@ In addition to all environment variables supported by `@pgpmjs/env`, this packag
 ### GraphQL Schema
 - `GRAPHILE_SCHEMA` - Comma-separated list of PostgreSQL schemas to expose
 
+Schema-scoped introspection is configured through the Graphile preset in
+`pgpm.json` or runtime options. The map is keyed by the final PostgreSQL
+service name: omit a service or set it to `false` for stock introspection, set
+it to `true` for scoped defaults, or provide `catalogTypes` and
+`capabilityExtensions` explicitly.
+
+### Scoped introspection environment overrides
+
+The server maps these variables to
+`graphile.preset.gather.pgScopedIntrospection.main`. `main` is the internal
+PostgreSQL service name, not the routing service name (such as `local`).
+
+| Variable | Accepted values |
+| --- | --- |
+| `GRAPHILE_SCOPED_INTROSPECTION` | `true` or `false` |
+| `GRAPHILE_SCOPED_INTROSPECTION_CATALOG_TYPES` | `all` or `dependency-closure` |
+| `GRAPHILE_SCOPED_INTROSPECTION_CAPABILITY_EXTENSIONS` | Comma-separated extension names, e.g. `pg_trgm,vector` |
+
+- Unset variables do not override `pgpm.json`. With neither configuration nor
+  environment settings, introspection remains stock.
+- `true` enables scoped introspection while preserving advanced options in
+  `pgpm.json`; without advanced options it uses Crystal's defaults
+  (`catalogTypes: "all"`).
+- Either advanced variable alone enables scoped introspection, including when
+  the config file sets `main: false`.
+- Explicit `false` overrides both advanced variables and the config file.
+  Advanced variables are ignored, even if malformed, so one switch is enough
+  to roll back to stock.
+- Advanced options override only their own field. Extension lists replace the
+  configured array, trim names and remove duplicates. An explicitly empty or
+  whitespace-only extension variable clears the list to `[]`; unset preserves it.
+- An empty or whitespace-only enable variable means unset. Other enable values
+  must be lowercase `true` or `false` (surrounding whitespace is allowed).
+  Catalog values must match one of the two lowercase choices exactly; an empty
+  catalog value is invalid. Empty CSV items such as `pg_trgm,,vector` are invalid.
+  Invalid active settings fail option resolution with the variable name.
+- Precedence remains defaults < config file < environment < explicit runtime
+  options. These variables affect only `main`.
+
+```bash
+# Enable default scoped introspection
+export GRAPHILE_SCOPED_INTROSPECTION=true
+
+# Optionally customize it
+export GRAPHILE_SCOPED_INTROSPECTION_CATALOG_TYPES=dependency-closure
+export GRAPHILE_SCOPED_INTROSPECTION_CAPABILITY_EXTENSIONS=pg_trgm,vector
+
+# Roll back without removing the advanced variables
+export GRAPHILE_SCOPED_INTROSPECTION=false
+```
+
+Restart the server after changing its environment. `capabilityExtensions`
+retains introspection metadata for extension capabilities; it does not install
+PostgreSQL extensions or change the API's exposed schemas.
+
 ### Feature Flags
 - `FEATURES_SIMPLE_INFLECTION` - Enable simple inflection plugin
 - `FEATURES_OPPOSITE_BASE_NAMES` - Enable opposite base names
@@ -65,7 +120,11 @@ GraphQL defaults are provided by `@constructive-io/graphql-types`:
 
 ```typescript
 {
-  graphile: { schema: [] },
+  graphile: {
+    schema: [],
+    extends: [],
+    preset: {}
+  },
   features: {
     simpleInflection: true,
     oppositeBaseNames: true,
@@ -82,6 +141,41 @@ GraphQL defaults are provided by `@constructive-io/graphql-types`:
 }
 ```
 
+For example, this enables scoped introspection with the defaults for the
+server's default `main` service:
+
+```json
+{
+  "graphile": {
+    "preset": {
+      "gather": {
+        "pgScopedIntrospection": { "main": true }
+      }
+    }
+  }
+}
+```
+
+Advanced options can be supplied when a service needs a specific catalog
+policy or extension capability:
+
+```json
+{
+  "graphile": {
+    "preset": {
+      "gather": {
+        "pgScopedIntrospection": {
+          "main": {
+            "catalogTypes": "dependency-closure",
+            "capabilityExtensions": ["pg_trgm"]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 ## When to Use
 
 - Use `@constructive-io/graphql-env` for Constructive applications that need GraphQL/Graphile configuration

package/env.js

@@ -2,10 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getGraphQLEnvVars = void 0;
 const _12factor_env_1 = require("12factor-env");
+const scoped_introspection_1 = require("./scoped-introspection");
 /**
  * @param env - Environment object to read from (defaults to process.env for backwards compatibility)
  */
 const getGraphQLEnvVars = (env = process.env) => {
+    const scopedIntrospection = (0, scoped_introspection_1.getScopedIntrospectionEnv)(env);
     const { GRAPHILE_SCHEMA, FEATURES_SIMPLE_INFLECTION, FEATURES_OPPOSITE_BASE_NAMES, FEATURES_POSTGIS, API_ROUTING_SCHEMA, API_IS_PUBLIC, API_EXPOSED_SCHEMAS, API_META_SCHEMAS, API_ANON_ROLE, API_ROLE_NAME, API_FLUSH_TOKEN, API_INTROSPECTION_ROLE, EMBEDDER_PROVIDER, EMBEDDER_MODEL, EMBEDDER_BASE_URL, CHAT_PROVIDER, CHAT_MODEL, CHAT_BASE_URL, SMS_PROVIDER, SMS_SENDER_ID, SMS_REQUEST_TIMEOUT_MS, SEND_SMS_DRY_RUN, DEVSMS_BASE_URL } = env;
     // Keep this function as a partial env-override parser. SMS runtime defaults
     // belong to the consuming application; injecting them here would incorrectly
@@ -19,6 +21,13 @@ const getGraphQLEnvVars = (env = process.env) => {
         DEVSMS_BASE_URL);
     return {
         graphile: {
+            ...(scopedIntrospection !== undefined && {
+                preset: {
+                    gather: {
+                        pgScopedIntrospection: { main: scopedIntrospection }
+                    }
+                }
+            }),
             ...(GRAPHILE_SCHEMA && {
                 schema: GRAPHILE_SCHEMA.includes(',')
                     ? GRAPHILE_SCHEMA.split(',').map(s => s.trim())

package/esm/env.js

@@ -1,8 +1,10 @@
 import { parseEnvBoolean, parseEnvNumber } from '12factor-env';
+import { getScopedIntrospectionEnv } from './scoped-introspection';
 /**
  * @param env - Environment object to read from (defaults to process.env for backwards compatibility)
  */
 export const getGraphQLEnvVars = (env = process.env) => {
+    const scopedIntrospection = getScopedIntrospectionEnv(env);
     const { GRAPHILE_SCHEMA, FEATURES_SIMPLE_INFLECTION, FEATURES_OPPOSITE_BASE_NAMES, FEATURES_POSTGIS, API_ROUTING_SCHEMA, API_IS_PUBLIC, API_EXPOSED_SCHEMAS, API_META_SCHEMAS, API_ANON_ROLE, API_ROLE_NAME, API_FLUSH_TOKEN, API_INTROSPECTION_ROLE, EMBEDDER_PROVIDER, EMBEDDER_MODEL, EMBEDDER_BASE_URL, CHAT_PROVIDER, CHAT_MODEL, CHAT_BASE_URL, SMS_PROVIDER, SMS_SENDER_ID, SMS_REQUEST_TIMEOUT_MS, SEND_SMS_DRY_RUN, DEVSMS_BASE_URL } = env;
     // Keep this function as a partial env-override parser. SMS runtime defaults
     // belong to the consuming application; injecting them here would incorrectly
@@ -16,6 +18,13 @@ export const getGraphQLEnvVars = (env = process.env) => {
         DEVSMS_BASE_URL);
     return {
         graphile: {
+            ...(scopedIntrospection !== undefined && {
+                preset: {
+                    gather: {
+                        pgScopedIntrospection: { main: scopedIntrospection }
+                    }
+                }
+            }),
             ...(GRAPHILE_SCHEMA && {
                 schema: GRAPHILE_SCHEMA.includes(',')
                     ? GRAPHILE_SCHEMA.split(',').map(s => s.trim())

package/esm/scoped-introspection.d.ts

@@ -0,0 +1,3 @@
+import type { PgScopedIntrospectionServiceConfig } from '@constructive-io/graphql-types';
+/** Partial override for the server-owned `main` service; absence is not a default. */
+export declare const getScopedIntrospectionEnv: (environment: NodeJS.ProcessEnv) => PgScopedIntrospectionServiceConfig | undefined;

package/esm/scoped-introspection.js

@@ -0,0 +1,42 @@
+import { cleanEnv, enumerated, EnvError, makeValidator, parseEnvList, str } from '12factor-env';
+// Unlike the generic list validator, this configuration permits an explicit
+// empty list (clear the configured extensions), but rejects empty CSV items.
+const capabilityExtensions = makeValidator((value) => {
+    if (value.trim() === '')
+        return [];
+    if (value.split(',').some((item) => item.trim() === '')) {
+        throw new EnvError('Expected comma-separated extension names without empty items');
+    }
+    return [...new Set(parseEnvList(value))];
+});
+/** Partial override for the server-owned `main` service; absence is not a default. */
+export const getScopedIntrospectionEnv = (environment) => {
+    const enabled = cleanEnv({
+        GRAPHILE_SCOPED_INTROSPECTION: environment.GRAPHILE_SCOPED_INTROSPECTION?.trim() || undefined
+    }, {
+        GRAPHILE_SCOPED_INTROSPECTION: str({
+            choices: ['true', 'false'],
+            default: undefined
+        })
+    }).GRAPHILE_SCOPED_INTROSPECTION;
+    // The rollback switch works even if stale advanced settings are malformed.
+    if (enabled === 'false')
+        return false;
+    const options = cleanEnv(environment, {
+        GRAPHILE_SCOPED_INTROSPECTION_CATALOG_TYPES: enumerated(['all', 'dependency-closure'], { default: undefined }),
+        GRAPHILE_SCOPED_INTROSPECTION_CAPABILITY_EXTENSIONS: capabilityExtensions({
+            default: undefined
+        })
+    });
+    const catalogTypes = options.GRAPHILE_SCOPED_INTROSPECTION_CATALOG_TYPES;
+    const extensions = options.GRAPHILE_SCOPED_INTROSPECTION_CAPABILITY_EXTENSIONS;
+    if (enabled === undefined && catalogTypes === undefined && extensions === undefined) {
+        return undefined;
+    }
+    // An object enables scoped introspection while deepmerge preserves advanced
+    // fields from pgpm.json. A literal `true` would discard those fields.
+    return {
+        ...(catalogTypes !== undefined && { catalogTypes }),
+        ...(extensions !== undefined && { capabilityExtensions: extensions })
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-env",
-  "version": "3.32.2",
+  "version": "3.33.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "Constructive environment configuration with GraphQL/Graphile support",
   "main": "index.js",
@@ -30,8 +30,8 @@
   },
   "dependencies": {
     "12factor-env": "^1.32.1",
-    "@constructive-io/graphql-types": "^3.31.2",
-    "@pgpmjs/env": "^2.43.6",
+    "@constructive-io/graphql-types": "^3.32.0",
+    "@pgpmjs/env": "^2.44.0",
     "deepmerge": "^4.3.1"
   },
   "keywords": [
@@ -45,5 +45,5 @@
   "devDependencies": {
     "makage": "^0.8.0"
   },
-  "gitHead": "9bba983b38395277e0400294aaa380e586b049d4"
+  "gitHead": "399437801c27b070312125f3f0ee821ce16e183e"
 }

package/scoped-introspection.d.ts

@@ -0,0 +1,3 @@
+import type { PgScopedIntrospectionServiceConfig } from '@constructive-io/graphql-types';
+/** Partial override for the server-owned `main` service; absence is not a default. */
+export declare const getScopedIntrospectionEnv: (environment: NodeJS.ProcessEnv) => PgScopedIntrospectionServiceConfig | undefined;

package/scoped-introspection.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getScopedIntrospectionEnv = void 0;
+const _12factor_env_1 = require("12factor-env");
+// Unlike the generic list validator, this configuration permits an explicit
+// empty list (clear the configured extensions), but rejects empty CSV items.
+const capabilityExtensions = (0, _12factor_env_1.makeValidator)((value) => {
+    if (value.trim() === '')
+        return [];
+    if (value.split(',').some((item) => item.trim() === '')) {
+        throw new _12factor_env_1.EnvError('Expected comma-separated extension names without empty items');
+    }
+    return [...new Set((0, _12factor_env_1.parseEnvList)(value))];
+});
+/** Partial override for the server-owned `main` service; absence is not a default. */
+const getScopedIntrospectionEnv = (environment) => {
+    const enabled = (0, _12factor_env_1.cleanEnv)({
+        GRAPHILE_SCOPED_INTROSPECTION: environment.GRAPHILE_SCOPED_INTROSPECTION?.trim() || undefined
+    }, {
+        GRAPHILE_SCOPED_INTROSPECTION: (0, _12factor_env_1.str)({
+            choices: ['true', 'false'],
+            default: undefined
+        })
+    }).GRAPHILE_SCOPED_INTROSPECTION;
+    // The rollback switch works even if stale advanced settings are malformed.
+    if (enabled === 'false')
+        return false;
+    const options = (0, _12factor_env_1.cleanEnv)(environment, {
+        GRAPHILE_SCOPED_INTROSPECTION_CATALOG_TYPES: (0, _12factor_env_1.enumerated)(['all', 'dependency-closure'], { default: undefined }),
+        GRAPHILE_SCOPED_INTROSPECTION_CAPABILITY_EXTENSIONS: capabilityExtensions({
+            default: undefined
+        })
+    });
+    const catalogTypes = options.GRAPHILE_SCOPED_INTROSPECTION_CATALOG_TYPES;
+    const extensions = options.GRAPHILE_SCOPED_INTROSPECTION_CAPABILITY_EXTENSIONS;
+    if (enabled === undefined && catalogTypes === undefined && extensions === undefined) {
+        return undefined;
+    }
+    // An object enables scoped introspection while deepmerge preserves advanced
+    // fields from pgpm.json. A literal `true` would discard those fields.
+    return {
+        ...(catalogTypes !== undefined && { catalogTypes }),
+        ...(extensions !== undefined && { capabilityExtensions: extensions })
+    };
+};
+exports.getScopedIntrospectionEnv = getScopedIntrospectionEnv;