@btravstack/graphql-server 0.27.0 → 0.29.0

package/README.md

@@ -11,7 +11,11 @@ selected request kind actually forks. Pass the same `units` record to
 `httpServer({ unit: units })` so the runtime can apply unit test overrides.
 Yoga plugins and CORS policy are explicit
 options; the wildcard CORS default and Yoga console logging are disabled, and
-a masked defect is reported to `Observers` instead. `fieldResult(result)`
+a masked defect is reported to `Observers` instead. GraphiQL,
+introspection and "Did you mean …" suggestions stay off unless
+`GRAPHQL_DEVELOPER_TOOLS=true` (or `developerTools: true`) turns them on. A
+document over `GRAPHQL_MAX_TOKENS` (default `1000`, pinned by `maxTokens`) is
+refused by the parser, before validation. `fieldResult(result)`
 answers a resolver from an `AsyncResult`, with a refusal on its own field's
 path.
 Preflights use Yoga's CORS policy before authentication, and Yoga plugins are

package/dist/index.cjs

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let graphql_yoga = require("graphql-yoga");
+let _btravstack_config = require("@btravstack/config");
 let _btravstack_core = require("@btravstack/core");
 let _btravstack_di = require("@btravstack/di");
 let _btravstack_http_server_internal = require("@btravstack/http-server/internal");
@@ -33,6 +34,25 @@ const dispose = Symbol("graphql.dispose");
 /** What failed: GraphQL locates a resolver's error by wrapping it, and a log line walks `cause`, not `originalError`. */
 const causeOf = (error) => typeof error === "object" && error !== null && "originalError" in error && error.originalError ? error.originalError : error;
 const pathOf = (error) => typeof error === "object" && error !== null && "path" in error && Array.isArray(error.path) ? error.path.join(".") : void 0;
+const noIntrospection = (context) => ({ Field: (node) => {
+	if (node.name.value === "__schema" || node.name.value === "__type") context.reportError((0, graphql_yoga.createGraphQLError)(`GraphQL introspection is not allowed, but the query contained ${node.name.value}`, { nodes: [node] }));
+} });
+const withoutIntrospection = { onValidate: ({ addValidationRule }) => addValidationRule(noIntrospection) };
+const SUGGESTION = / Did you mean [^?]*\?/g;
+const hideSuggestion = (error) => {
+	if (error instanceof Error) error.message = error.message.replace(SUGGESTION, "");
+};
+const hideSuggestionsIn = (payload) => (0, graphql_yoga.handleStreamOrSingleExecutionResult)(payload, ({ result }) => result.errors?.forEach(hideSuggestion));
+const withoutSuggestions = {
+	onValidate: () => ({ result }) => result.forEach(hideSuggestion),
+	onExecute: () => ({ onExecuteDone: hideSuggestionsIn }),
+	onSubscribe: () => ({ onSubscribeResult: hideSuggestionsIn })
+};
+const DEFAULT_MAX_TOKENS = 1e3;
+const tokenLimit = (maxTokens) => ({ onParse: ({ parseFn, setParseFn }) => setParseFn((source, options) => parseFn(source, {
+	...options,
+	maxTokens
+})) });
 const graphql = (api, options) => {
 	const mount = options.prefix ?? "/graphql";
 	let end = mount.length;
@@ -40,14 +60,22 @@ const graphql = (api, options) => {
 	const prefix = mount.slice(0, end);
 	const requirements = options.requires;
 	const schemes = [...new Set(requirements?.flatMap((requirement) => Object.keys(requirement)) ?? [])];
+	const configSchema = _btravstack_config.Config.object({
+		developerTools: _btravstack_config.Config.pinned(options.developerTools, _btravstack_config.Config.boolean("GRAPHQL_DEVELOPER_TOOLS", { default: false })),
+		maxTokens: _btravstack_config.Config.pinned(options.maxTokens === false ? 0 : options.maxTokens, _btravstack_config.Config.integer("GRAPHQL_MAX_TOKENS", {
+			default: DEFAULT_MAX_TOKENS,
+			min: 0
+		}))
+	});
 	const typed = _btravstack_di.Provider.member(_btravstack_http_server_internal.HttpHandler)({
 		inject: {
+			env: _btravstack_config.Env,
 			config: _btravstack_http_server_internal.HttpConfig,
 			units: _btravstack_http_server_internal.HttpUnit,
 			observers: _btravstack_core.Observers,
 			...(0, _btravstack_http_server_internal.schemeDeps)(schemes)
 		},
-		sync: (services) => {
+		make: (services) => _btravstack_config.Config.parse("GraphqlConfig", configSchema)(services.env).map(({ developerTools, maxTokens }) => {
 			const config = services.config;
 			const units = services.units;
 			const observers = services.observers;
@@ -59,9 +87,14 @@ const graphql = (api, options) => {
 				schema: options.schema,
 				graphqlEndpoint: prefix,
 				cors: options.cors ?? (config.corsOrigin === "" ? false : { origin: config.corsOrigin.split(",").map((origin) => origin.trim()) }),
-				plugins: [{ onRequest: ({ serverContext, fetchAPI, endResponse }) => {
-					if (serverContext.refusalStatus !== void 0) endResponse(new fetchAPI.Response(null, { status: serverContext.refusalStatus }));
-				} }, ...options.plugins ?? []],
+				plugins: [
+					{ onRequest: ({ serverContext, fetchAPI, endResponse }) => {
+						if (serverContext.refusalStatus !== void 0) endResponse(new fetchAPI.Response(null, { status: serverContext.refusalStatus }));
+					} },
+					...developerTools ? [] : [withoutIntrospection, withoutSuggestions],
+					...maxTokens === 0 ? [] : [tokenLimit(maxTokens)],
+					...options.plugins ?? []
+				],
 				maskedErrors: { maskError: (error, message, isDev) => {
 					const masked = (0, graphql_yoga.maskError)(error, message, isDev);
 					if (masked !== error) (0, _btravstack_core.observe)(observers, {
@@ -77,7 +110,7 @@ const graphql = (api, options) => {
 					return masked;
 				} },
 				logging: false,
-				graphiql: false,
+				graphiql: developerTools,
 				landingPage: false,
 				multipart: false,
 				maxRequestBodySize: config.bodyLimit === 0 ? false : config.bodyLimit,
@@ -122,7 +155,7 @@ const graphql = (api, options) => {
 				},
 				[dispose]: () => yoga.dispose()
 			};
-		},
+		}),
 		onStop: (answerer) => answerer[dispose]()
 	});
 	return Object.assign(typed, { authenticators: api.providers });

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { GraphQLError, GraphQLSchema } from "graphql";
 import { AsyncResult, Result } from "unthrown";
 import { IncomingMessage } from "node:http";
+import { ConfigInvalid, EnvReading } from "@btravstack/config";
 import { OneScheme, Requirements } from "@btravstack/contract";
 import { Observers } from "@btravstack/core";
 import { AnyPort, Provider, Scope } from "@btravstack/di";
@@ -64,6 +65,19 @@ type GraphqlOptions<A extends Authenticators, Units extends UnitsOf<A>, R extend
   readonly schema: GraphQLSchema;
   readonly prefix?: `/${string}`;
   readonly cors?: YogaCors;
+  /**
+   * GraphiQL, introspection and the "Did you mean …" suggestions in an error,
+   * all or none — pins `GRAPHQL_DEVELOPER_TOOLS`, which defaults to `false`, so
+   * a deployment exposes none of them unless it says so.
+   */
+  readonly developerTools?: boolean;
+  /**
+   * Pins `GRAPHQL_MAX_TOKENS` (default `1000`) — the most tokens graphql-js
+   * parses in one document before refusing it, so an oversized document is
+   * refused before any validation rule runs on it. `false` pins the unbounded
+   * `0`.
+   */
+  readonly maxTokens?: number | false;
   /**
    * Yoga plugins. Each may be typed by the context it reads — a
    * `Plugin<{ unit: … }>` — and is checked against the {@link GraphqlContext}
@@ -74,7 +88,7 @@ type GraphqlOptions<A extends Authenticators, Units extends UnitsOf<A>, R extend
   readonly unit?: U & UnitGate<U, Units, KindOf<R>>;
   readonly requires?: R & RequiresGate<R, { readonly [K in keyof A]: A[K]["scope"]; }>;
 };
-export declare const graphql: <A extends Authenticators, Units extends UnitsOf<A> = Record<never, never>, const R extends Requirements & { readonly [I in keyof R]: OneScheme<R[I]>; } = never, U extends Readonly<Record<string, AnyPort>> = Record<never, never>, const PS extends readonly unknown[] = []>(api: HttpAuth<A>, options: GraphqlOptions<A, Units, R, U, PS>) => Provider<HttpHandler, never, HttpConfig | HttpUnit | Observers | Scope | SchemePortsOf<R> | UnitsNeedsOf<Units>> & {
+export declare const graphql: <A extends Authenticators, Units extends UnitsOf<A> = Record<never, never>, const R extends Requirements & { readonly [I in keyof R]: OneScheme<R[I]>; } = never, U extends Readonly<Record<string, AnyPort>> = Record<never, never>, const PS extends readonly unknown[] = []>(api: HttpAuth<A>, options: GraphqlOptions<A, Units, R, U, PS>) => Provider<HttpHandler, ConfigInvalid, HttpConfig | HttpUnit | Observers | Scope | SchemePortsOf<R> | UnitsNeedsOf<Units> | EnvReading<never, "GRAPHQL_DEVELOPER_TOOLS" | "GRAPHQL_MAX_TOKENS">> & {
   authenticators: readonly import("@btravstack/http-server/internal").SchemeProviders<A>[];
 };
 //#endregion

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import { Plugin, YogaInitialContext, YogaServerOptions } from "graphql-yoga";
+import { ConfigInvalid, EnvReading } from "@btravstack/config";
 import { Observers } from "@btravstack/core";
 import { AnyPort, Provider, Scope } from "@btravstack/di";
 import { Authenticators, HttpAuth, HttpConfig, HttpHandler, HttpUnit, KindOf, Kinds, Principal, RequiresGate, SchemePortsOf, SchemesFrom, SchemesOf, UnitFor, UnitsNeedsOf, UnitsOf } from "@btravstack/http-server/internal";
@@ -64,6 +65,19 @@ type GraphqlOptions<A extends Authenticators, Units extends UnitsOf<A>, R extend
   readonly schema: GraphQLSchema;
   readonly prefix?: `/${string}`;
   readonly cors?: YogaCors;
+  /**
+   * GraphiQL, introspection and the "Did you mean …" suggestions in an error,
+   * all or none — pins `GRAPHQL_DEVELOPER_TOOLS`, which defaults to `false`, so
+   * a deployment exposes none of them unless it says so.
+   */
+  readonly developerTools?: boolean;
+  /**
+   * Pins `GRAPHQL_MAX_TOKENS` (default `1000`) — the most tokens graphql-js
+   * parses in one document before refusing it, so an oversized document is
+   * refused before any validation rule runs on it. `false` pins the unbounded
+   * `0`.
+   */
+  readonly maxTokens?: number | false;
   /**
    * Yoga plugins. Each may be typed by the context it reads — a
    * `Plugin<{ unit: … }>` — and is checked against the {@link GraphqlContext}
@@ -74,7 +88,7 @@ type GraphqlOptions<A extends Authenticators, Units extends UnitsOf<A>, R extend
   readonly unit?: U & UnitGate<U, Units, KindOf<R>>;
   readonly requires?: R & RequiresGate<R, { readonly [K in keyof A]: A[K]["scope"]; }>;
 };
-export declare const graphql: <A extends Authenticators, Units extends UnitsOf<A> = Record<never, never>, const R extends Requirements & { readonly [I in keyof R]: OneScheme<R[I]>; } = never, U extends Readonly<Record<string, AnyPort>> = Record<never, never>, const PS extends readonly unknown[] = []>(api: HttpAuth<A>, options: GraphqlOptions<A, Units, R, U, PS>) => Provider<HttpHandler, never, HttpConfig | HttpUnit | Observers | Scope | SchemePortsOf<R> | UnitsNeedsOf<Units>> & {
+export declare const graphql: <A extends Authenticators, Units extends UnitsOf<A> = Record<never, never>, const R extends Requirements & { readonly [I in keyof R]: OneScheme<R[I]>; } = never, U extends Readonly<Record<string, AnyPort>> = Record<never, never>, const PS extends readonly unknown[] = []>(api: HttpAuth<A>, options: GraphqlOptions<A, Units, R, U, PS>) => Provider<HttpHandler, ConfigInvalid, HttpConfig | HttpUnit | Observers | Scope | SchemePortsOf<R> | UnitsNeedsOf<Units> | EnvReading<never, "GRAPHQL_DEVELOPER_TOOLS" | "GRAPHQL_MAX_TOKENS">> & {
   authenticators: readonly import("@btravstack/http-server/internal").SchemeProviders<A>[];
 };
 //#endregion

package/dist/index.mjs

@@ -1,4 +1,5 @@
-import { createGraphQLError, createYoga, maskError } from "graphql-yoga";
+import { createGraphQLError, createYoga, handleStreamOrSingleExecutionResult, maskError } from "graphql-yoga";
+import { Config, Env } from "@btravstack/config";
 import { Observers, observe } from "@btravstack/core";
 import { Provider } from "@btravstack/di";
 import { HttpConfig, HttpHandler, HttpUnit, forkUnit, principalOf, resolveScheme, schemeDeps, schemeServices } from "@btravstack/http-server/internal";
@@ -32,6 +33,25 @@ const dispose = Symbol("graphql.dispose");
 /** What failed: GraphQL locates a resolver's error by wrapping it, and a log line walks `cause`, not `originalError`. */
 const causeOf = (error) => typeof error === "object" && error !== null && "originalError" in error && error.originalError ? error.originalError : error;
 const pathOf = (error) => typeof error === "object" && error !== null && "path" in error && Array.isArray(error.path) ? error.path.join(".") : void 0;
+const noIntrospection = (context) => ({ Field: (node) => {
+	if (node.name.value === "__schema" || node.name.value === "__type") context.reportError(createGraphQLError(`GraphQL introspection is not allowed, but the query contained ${node.name.value}`, { nodes: [node] }));
+} });
+const withoutIntrospection = { onValidate: ({ addValidationRule }) => addValidationRule(noIntrospection) };
+const SUGGESTION = / Did you mean [^?]*\?/g;
+const hideSuggestion = (error) => {
+	if (error instanceof Error) error.message = error.message.replace(SUGGESTION, "");
+};
+const hideSuggestionsIn = (payload) => handleStreamOrSingleExecutionResult(payload, ({ result }) => result.errors?.forEach(hideSuggestion));
+const withoutSuggestions = {
+	onValidate: () => ({ result }) => result.forEach(hideSuggestion),
+	onExecute: () => ({ onExecuteDone: hideSuggestionsIn }),
+	onSubscribe: () => ({ onSubscribeResult: hideSuggestionsIn })
+};
+const DEFAULT_MAX_TOKENS = 1e3;
+const tokenLimit = (maxTokens) => ({ onParse: ({ parseFn, setParseFn }) => setParseFn((source, options) => parseFn(source, {
+	...options,
+	maxTokens
+})) });
 const graphql = (api, options) => {
 	const mount = options.prefix ?? "/graphql";
 	let end = mount.length;
@@ -39,14 +59,22 @@ const graphql = (api, options) => {
 	const prefix = mount.slice(0, end);
 	const requirements = options.requires;
 	const schemes = [...new Set(requirements?.flatMap((requirement) => Object.keys(requirement)) ?? [])];
+	const configSchema = Config.object({
+		developerTools: Config.pinned(options.developerTools, Config.boolean("GRAPHQL_DEVELOPER_TOOLS", { default: false })),
+		maxTokens: Config.pinned(options.maxTokens === false ? 0 : options.maxTokens, Config.integer("GRAPHQL_MAX_TOKENS", {
+			default: DEFAULT_MAX_TOKENS,
+			min: 0
+		}))
+	});
 	const typed = Provider.member(HttpHandler)({
 		inject: {
+			env: Env,
 			config: HttpConfig,
 			units: HttpUnit,
 			observers: Observers,
 			...schemeDeps(schemes)
 		},
-		sync: (services) => {
+		make: (services) => Config.parse("GraphqlConfig", configSchema)(services.env).map(({ developerTools, maxTokens }) => {
 			const config = services.config;
 			const units = services.units;
 			const observers = services.observers;
@@ -58,9 +86,14 @@ const graphql = (api, options) => {
 				schema: options.schema,
 				graphqlEndpoint: prefix,
 				cors: options.cors ?? (config.corsOrigin === "" ? false : { origin: config.corsOrigin.split(",").map((origin) => origin.trim()) }),
-				plugins: [{ onRequest: ({ serverContext, fetchAPI, endResponse }) => {
-					if (serverContext.refusalStatus !== void 0) endResponse(new fetchAPI.Response(null, { status: serverContext.refusalStatus }));
-				} }, ...options.plugins ?? []],
+				plugins: [
+					{ onRequest: ({ serverContext, fetchAPI, endResponse }) => {
+						if (serverContext.refusalStatus !== void 0) endResponse(new fetchAPI.Response(null, { status: serverContext.refusalStatus }));
+					} },
+					...developerTools ? [] : [withoutIntrospection, withoutSuggestions],
+					...maxTokens === 0 ? [] : [tokenLimit(maxTokens)],
+					...options.plugins ?? []
+				],
 				maskedErrors: { maskError: (error, message, isDev) => {
 					const masked = maskError(error, message, isDev);
 					if (masked !== error) observe(observers, {
@@ -76,7 +109,7 @@ const graphql = (api, options) => {
 					return masked;
 				} },
 				logging: false,
-				graphiql: false,
+				graphiql: developerTools,
 				landingPage: false,
 				multipart: false,
 				maxRequestBodySize: config.bodyLimit === 0 ? false : config.bodyLimit,
@@ -121,7 +154,7 @@ const graphql = (api, options) => {
 				},
 				[dispose]: () => yoga.dispose()
 			};
-		},
+		}),
 		onStop: (answerer) => answerer[dispose]()
 	});
 	return Object.assign(typed, { authenticators: api.providers });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/graphql-server",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "The GraphQL Yoga answerer for @btravstack/http-server",
   "keywords": [
     "graphql",
@@ -41,10 +41,11 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@btravstack/contract": "0.27.0",
-    "@btravstack/core": "0.27.0",
-    "@btravstack/di": "0.27.0",
-    "@btravstack/http-server": "0.27.0",
+    "@btravstack/config": "0.29.0",
+    "@btravstack/contract": "0.29.0",
+    "@btravstack/core": "0.29.0",
+    "@btravstack/di": "0.29.0",
+    "@btravstack/http-server": "0.29.0",
     "@btravstack/tsconfig": "0.4.0",
     "@types/node": "26.6.4",
     "@unthrown/vitest": "5.12.0",
@@ -58,11 +59,12 @@
     "vitest": "5.0.3"
   },
   "peerDependencies": {
-    "@btravstack/contract": "^0.27.0",
-    "@btravstack/core": "^0.27.0",
-    "@btravstack/di": "^0.27.0",
-    "@btravstack/http-server": "^0.27.0",
-    "graphql": "^16.0.0 || ^17.0.0",
+    "@btravstack/config": "^0.29.0",
+    "@btravstack/contract": "^0.29.0",
+    "@btravstack/core": "^0.29.0",
+    "@btravstack/di": "^0.29.0",
+    "@btravstack/http-server": "^0.29.0",
+    "graphql": "^16.6.0 || ^17.0.0",
     "graphql-yoga": "^5.24.1",
     "unthrown": "^5.7.0"
   },