@btravstack/graphql-server 0.26.0 → 0.28.0

package/README.md

@@ -10,7 +10,12 @@ Pass `units` with `unit` to check each injected port against the module the
 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.
+options; the wildcard CORS default and Yoga console logging are disabled, and
+a masked defect is reported to `Observers` instead. GraphiQL and
+introspection stay off unless `GRAPHQL_DEVELOPER_TOOLS=true` (or
+`developerTools: true`) turns both on. `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
 disposed when the application stops.
 

package/dist/index.cjs

@@ -1,10 +1,43 @@
 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");
-let graphql_yoga = require("graphql-yoga");
 let unthrown = require("unthrown");
+//#region src/field.ts
+/**
+* A resolver's answer from a `Result`, so a modeled failure is never thrown by
+* hand. `Ok` is the field's value. `Err` is the `GraphQLError` the resolver's
+* own triage minted from its `E` — an exhaustive `mapErrCases`, or
+* `flatMapErrCases` where one refusal is `Ok(null)`, so widening `E` fails
+* every resolver that folds it — and GraphQL reports it on this
+* field's path, aliases and list indexes included, while its siblings resolve:
+* its message and `extensions` reach the client, its `originalError` does not.
+* A defect is masked to `Unexpected error.` whatever its cause, and `graphql()`
+* reports it to `Observers`.
+*
+* **It answers a `Promise`, and that is the boundary**: a GraphQL resolver
+* returns a value or a promise and reports a field's error by rejecting, so
+* this is where a `Result` leaves for GraphQL's own channel — the one place a
+* resolver needs, as `runMain` is for a process.
+*/
+const fieldResult = async (result) => {
+	const settled = await result;
+	if (settled.isDefect()) throw new Error("fieldResult: the field's result was a defect", { cause: settled.cause });
+	if (settled.isErr()) throw (0, graphql_yoga.createGraphQLError)(settled.error.message, { extensions: settled.error.extensions });
+	return settled.value;
+};
+//#endregion
 //#region src/graphql.ts
 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 graphql = (api, options) => {
 	const mount = options.prefix ?? "/graphql";
 	let end = mount.length;
@@ -12,15 +45,19 @@ 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 developerToolsSchema = _btravstack_config.Config.object({ developerTools: _btravstack_config.Config.pinned(options.developerTools, _btravstack_config.Config.boolean("GRAPHQL_DEVELOPER_TOOLS", { default: false })) });
 	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", developerToolsSchema)(services.env).map(({ developerTools }) => {
 			const config = services.config;
 			const units = services.units;
+			const observers = services.observers;
 			if (options.units !== void 0) {
 				for (const kind of requirements === void 0 ? ["anonymous"] : schemes) if ((options.units[kind] ?? options.units["anonymous"]) !== (units[kind] ?? units["anonymous"])) throw new Error(`[graphql-server] unit kind ${JSON.stringify(kind)} differs from HttpUnit`);
 			}
@@ -29,11 +66,29 @@ 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],
+					...options.plugins ?? []
+				],
+				maskedErrors: { maskError: (error, message, isDev) => {
+					const masked = (0, graphql_yoga.maskError)(error, message, isDev);
+					if (masked !== error) (0, _btravstack_core.observe)(observers, {
+						component: "graphql",
+						name: "defect",
+						attributes: {},
+						details: { "graphql.path": pathOf(error) },
+						traced: false
+					})({
+						outcome: "error",
+						cause: causeOf(error)
+					});
+					return masked;
+				} },
 				logging: false,
-				graphiql: false,
+				graphiql: developerTools,
 				landingPage: false,
 				multipart: false,
 				maxRequestBodySize: config.bodyLimit === 0 ? false : config.bodyLimit,
@@ -78,10 +133,11 @@ const graphql = (api, options) => {
 				},
 				[dispose]: () => yoga.dispose()
 			};
-		},
+		}),
 		onStop: (answerer) => answerer[dispose]()
 	});
 	return Object.assign(typed, { authenticators: api.providers });
 };
 //#endregion
+exports.fieldResult = fieldResult;
 exports.graphql = graphql;

package/dist/index.d.cts

@@ -1,25 +1,88 @@
+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";
-import { Authenticators, HttpAuth, HttpConfig, HttpHandler, HttpUnit, KindOf, Kinds, RequiresGate, SchemePortsOf, UnitFor, UnitsNeedsOf, UnitsOf } from "@btravstack/http-server/internal";
-import { GraphQLSchema } from "graphql";
-import { Plugin, YogaServerOptions } from "graphql-yoga";
+import { Authenticators, HttpAuth, HttpConfig, HttpHandler, HttpUnit, KindOf, Kinds, Principal, RequiresGate, SchemePortsOf, SchemesFrom, SchemesOf, UnitFor, UnitsNeedsOf, UnitsOf } from "@btravstack/http-server/internal";
+import { Plugin, YogaInitialContext, YogaServerOptions } from "graphql-yoga";
+//#region src/field.d.ts
+/**
+ * A resolver's answer from a `Result`, so a modeled failure is never thrown by
+ * hand. `Ok` is the field's value. `Err` is the `GraphQLError` the resolver's
+ * own triage minted from its `E` — an exhaustive `mapErrCases`, or
+ * `flatMapErrCases` where one refusal is `Ok(null)`, so widening `E` fails
+ * every resolver that folds it — and GraphQL reports it on this
+ * field's path, aliases and list indexes included, while its siblings resolve:
+ * its message and `extensions` reach the client, its `originalError` does not.
+ * A defect is masked to `Unexpected error.` whatever its cause, and `graphql()`
+ * reports it to `Observers`.
+ *
+ * **It answers a `Promise`, and that is the boundary**: a GraphQL resolver
+ * returns a value or a promise and reports a field's error by rejecting, so
+ * this is where a `Result` leaves for GraphQL's own channel — the one place a
+ * resolver needs, as `runMain` is for a process.
+ */
+export declare const fieldResult: <T>(result: AsyncResult<T, GraphQLError> | Result<T, GraphQLError>) => Promise<T>;
+//#endregion
 //#region src/graphql.d.ts
 type YogaCors = YogaServerOptions<Record<string, unknown>, Record<string, unknown>>["cors"];
 type MissingUnitPorts<U extends Readonly<Record<string, AnyPort>>, Units, K extends string> = Exclude<keyof U, keyof UnitFor<U, Units, K>>;
 type UnitGate<U extends Readonly<Record<string, AnyPort>>, Units, K extends string> = [MissingUnitPorts<U, Units, K>] extends [never] ? unknown : {
   readonly "UNIT PORT MISSING — the selected kind does not export": MissingUnitPorts<U, Units, K>;
 };
+/**
+ * The context `graphql()` hands Yoga for an operation: what a resolver and a
+ * plugin's operation hooks (`onParse`, `onValidate`, `onContextBuilding`,
+ * `onExecute`, `onSubscribe`) read beside Yoga's own `request`. `principal` is
+ * the caller `requires` resolved, `undefined` without `requires`; `unit` is the
+ * `unit` record read off the forked kind; `incoming` is the Node request.
+ *
+ * Those hooks run only once the caller is authenticated. A preflight and a
+ * refusal end in Yoga's server hooks (`onRequest`, `onResponse`), whose
+ * context is not this type, so a plugin cannot claim a principal there.
+ */
+type GraphqlContext<Principal = unknown, Unit = Readonly<Record<string, unknown>>> = {
+  readonly principal: Principal;
+  readonly incoming: IncomingMessage;
+  readonly unit: Unit;
+  readonly signal: AbortSignal;
+};
+/** The {@link GraphqlContext} one `graphql()` call builds, from its own options. */
+type ContextOf<A extends Authenticators, Units, R extends Requirements, U extends Readonly<Record<string, AnyPort>>> = GraphqlContext<[R] extends [never] ? undefined : Principal<SchemesOf<R>, SchemesFrom<A>>, UnitFor<U, Units, KindOf<R>>>;
+/**
+ * Each plugin, unless the context this call builds lacks something it reads, or
+ * the entry is not a plugin at all.
+ * Per element, because Yoga's `Plugin<C>` is invariant in `C`: a plugin typed
+ * for the real context is not a `Plugin`, so none could be widened to one.
+ */
+type PluginsGate<PS extends readonly unknown[], C> = { readonly [I in keyof PS]: PS[I] extends Plugin<infer X> ? YogaInitialContext & C extends X ? PS[I] : "PLUGIN CONTEXT MISMATCH — this plugin reads what this graphql() call does not put in its context" : {
+  readonly "NOT A PLUGIN — this entry is not a Yoga plugin": PS[I];
+}; };
 /** Serve a GraphQL schema as one answerer under the existing HTTP runtime. */
-type GraphqlOptions<A extends Authenticators, Units extends UnitsOf<A>, R extends Requirements & { readonly [I in keyof R]: OneScheme<R[I]>; }, U extends Readonly<Record<string, AnyPort>>> = {
+type GraphqlOptions<A extends Authenticators, Units extends UnitsOf<A>, R extends Requirements & { readonly [I in keyof R]: OneScheme<R[I]>; }, U extends Readonly<Record<string, AnyPort>>, PS extends readonly unknown[] = readonly Plugin[]> = {
   readonly schema: GraphQLSchema;
   readonly prefix?: `/${string}`;
   readonly cors?: YogaCors;
-  readonly plugins?: readonly Plugin[];
+  /**
+   * GraphiQL and introspection, both or neither — pins
+   * `GRAPHQL_DEVELOPER_TOOLS`, which defaults to `false`, so a deployment
+   * exposes neither unless it says so.
+   */
+  readonly developerTools?: boolean;
+  /**
+   * Yoga plugins. Each may be typed by the context it reads — a
+   * `Plugin<{ unit: … }>` — and is checked against the {@link GraphqlContext}
+   * this call builds.
+   */
+  readonly plugins?: (PS & PluginsGate<PS, ContextOf<A, Units, R, U>>) | readonly Plugin<YogaInitialContext & ContextOf<A, Units, R, U>>[];
   readonly units?: Units & { readonly [K in Exclude<keyof Units, Kinds<A>>]: never; };
   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>>(api: HttpAuth<A>, options: GraphqlOptions<A, Units, R, U>) => Provider<HttpHandler, never, HttpConfig | HttpUnit | 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">> & {
   authenticators: readonly import("@btravstack/http-server/internal").SchemeProviders<A>[];
 };
-//#endregion
+//#endregion
+export type { GraphqlContext, GraphqlOptions };

package/dist/index.d.mts

@@ -1,25 +1,88 @@
+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, RequiresGate, SchemePortsOf, UnitFor, UnitsNeedsOf, UnitsOf } from "@btravstack/http-server/internal";
-import { Plugin, YogaServerOptions } from "graphql-yoga";
+import { Authenticators, HttpAuth, HttpConfig, HttpHandler, HttpUnit, KindOf, Kinds, Principal, RequiresGate, SchemePortsOf, SchemesFrom, SchemesOf, UnitFor, UnitsNeedsOf, UnitsOf } from "@btravstack/http-server/internal";
+import { AsyncResult, Result } from "unthrown";
+import { GraphQLError, GraphQLSchema } from "graphql";
+import { IncomingMessage } from "node:http";
 import { OneScheme, Requirements } from "@btravstack/contract";
-import { GraphQLSchema } from "graphql";
+//#region src/field.d.ts
+/**
+ * A resolver's answer from a `Result`, so a modeled failure is never thrown by
+ * hand. `Ok` is the field's value. `Err` is the `GraphQLError` the resolver's
+ * own triage minted from its `E` — an exhaustive `mapErrCases`, or
+ * `flatMapErrCases` where one refusal is `Ok(null)`, so widening `E` fails
+ * every resolver that folds it — and GraphQL reports it on this
+ * field's path, aliases and list indexes included, while its siblings resolve:
+ * its message and `extensions` reach the client, its `originalError` does not.
+ * A defect is masked to `Unexpected error.` whatever its cause, and `graphql()`
+ * reports it to `Observers`.
+ *
+ * **It answers a `Promise`, and that is the boundary**: a GraphQL resolver
+ * returns a value or a promise and reports a field's error by rejecting, so
+ * this is where a `Result` leaves for GraphQL's own channel — the one place a
+ * resolver needs, as `runMain` is for a process.
+ */
+export declare const fieldResult: <T>(result: AsyncResult<T, GraphQLError> | Result<T, GraphQLError>) => Promise<T>;
+//#endregion
 //#region src/graphql.d.ts
 type YogaCors = YogaServerOptions<Record<string, unknown>, Record<string, unknown>>["cors"];
 type MissingUnitPorts<U extends Readonly<Record<string, AnyPort>>, Units, K extends string> = Exclude<keyof U, keyof UnitFor<U, Units, K>>;
 type UnitGate<U extends Readonly<Record<string, AnyPort>>, Units, K extends string> = [MissingUnitPorts<U, Units, K>] extends [never] ? unknown : {
   readonly "UNIT PORT MISSING — the selected kind does not export": MissingUnitPorts<U, Units, K>;
 };
+/**
+ * The context `graphql()` hands Yoga for an operation: what a resolver and a
+ * plugin's operation hooks (`onParse`, `onValidate`, `onContextBuilding`,
+ * `onExecute`, `onSubscribe`) read beside Yoga's own `request`. `principal` is
+ * the caller `requires` resolved, `undefined` without `requires`; `unit` is the
+ * `unit` record read off the forked kind; `incoming` is the Node request.
+ *
+ * Those hooks run only once the caller is authenticated. A preflight and a
+ * refusal end in Yoga's server hooks (`onRequest`, `onResponse`), whose
+ * context is not this type, so a plugin cannot claim a principal there.
+ */
+type GraphqlContext<Principal = unknown, Unit = Readonly<Record<string, unknown>>> = {
+  readonly principal: Principal;
+  readonly incoming: IncomingMessage;
+  readonly unit: Unit;
+  readonly signal: AbortSignal;
+};
+/** The {@link GraphqlContext} one `graphql()` call builds, from its own options. */
+type ContextOf<A extends Authenticators, Units, R extends Requirements, U extends Readonly<Record<string, AnyPort>>> = GraphqlContext<[R] extends [never] ? undefined : Principal<SchemesOf<R>, SchemesFrom<A>>, UnitFor<U, Units, KindOf<R>>>;
+/**
+ * Each plugin, unless the context this call builds lacks something it reads, or
+ * the entry is not a plugin at all.
+ * Per element, because Yoga's `Plugin<C>` is invariant in `C`: a plugin typed
+ * for the real context is not a `Plugin`, so none could be widened to one.
+ */
+type PluginsGate<PS extends readonly unknown[], C> = { readonly [I in keyof PS]: PS[I] extends Plugin<infer X> ? YogaInitialContext & C extends X ? PS[I] : "PLUGIN CONTEXT MISMATCH — this plugin reads what this graphql() call does not put in its context" : {
+  readonly "NOT A PLUGIN — this entry is not a Yoga plugin": PS[I];
+}; };
 /** Serve a GraphQL schema as one answerer under the existing HTTP runtime. */
-type GraphqlOptions<A extends Authenticators, Units extends UnitsOf<A>, R extends Requirements & { readonly [I in keyof R]: OneScheme<R[I]>; }, U extends Readonly<Record<string, AnyPort>>> = {
+type GraphqlOptions<A extends Authenticators, Units extends UnitsOf<A>, R extends Requirements & { readonly [I in keyof R]: OneScheme<R[I]>; }, U extends Readonly<Record<string, AnyPort>>, PS extends readonly unknown[] = readonly Plugin[]> = {
   readonly schema: GraphQLSchema;
   readonly prefix?: `/${string}`;
   readonly cors?: YogaCors;
-  readonly plugins?: readonly Plugin[];
+  /**
+   * GraphiQL and introspection, both or neither — pins
+   * `GRAPHQL_DEVELOPER_TOOLS`, which defaults to `false`, so a deployment
+   * exposes neither unless it says so.
+   */
+  readonly developerTools?: boolean;
+  /**
+   * Yoga plugins. Each may be typed by the context it reads — a
+   * `Plugin<{ unit: … }>` — and is checked against the {@link GraphqlContext}
+   * this call builds.
+   */
+  readonly plugins?: (PS & PluginsGate<PS, ContextOf<A, Units, R, U>>) | readonly Plugin<YogaInitialContext & ContextOf<A, Units, R, U>>[];
   readonly units?: Units & { readonly [K in Exclude<keyof Units, Kinds<A>>]: never; };
   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>>(api: HttpAuth<A>, options: GraphqlOptions<A, Units, R, U>) => Provider<HttpHandler, never, HttpConfig | HttpUnit | 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">> & {
   authenticators: readonly import("@btravstack/http-server/internal").SchemeProviders<A>[];
 };
-//#endregion
+//#endregion
+export type { GraphqlContext, GraphqlOptions };

package/dist/index.mjs

@@ -1,9 +1,42 @@
+import { createGraphQLError, createYoga, 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";
-import { createYoga } from "graphql-yoga";
 import { P } from "unthrown";
+//#region src/field.ts
+/**
+* A resolver's answer from a `Result`, so a modeled failure is never thrown by
+* hand. `Ok` is the field's value. `Err` is the `GraphQLError` the resolver's
+* own triage minted from its `E` — an exhaustive `mapErrCases`, or
+* `flatMapErrCases` where one refusal is `Ok(null)`, so widening `E` fails
+* every resolver that folds it — and GraphQL reports it on this
+* field's path, aliases and list indexes included, while its siblings resolve:
+* its message and `extensions` reach the client, its `originalError` does not.
+* A defect is masked to `Unexpected error.` whatever its cause, and `graphql()`
+* reports it to `Observers`.
+*
+* **It answers a `Promise`, and that is the boundary**: a GraphQL resolver
+* returns a value or a promise and reports a field's error by rejecting, so
+* this is where a `Result` leaves for GraphQL's own channel — the one place a
+* resolver needs, as `runMain` is for a process.
+*/
+const fieldResult = async (result) => {
+	const settled = await result;
+	if (settled.isDefect()) throw new Error("fieldResult: the field's result was a defect", { cause: settled.cause });
+	if (settled.isErr()) throw createGraphQLError(settled.error.message, { extensions: settled.error.extensions });
+	return settled.value;
+};
+//#endregion
 //#region src/graphql.ts
 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 graphql = (api, options) => {
 	const mount = options.prefix ?? "/graphql";
 	let end = mount.length;
@@ -11,15 +44,19 @@ 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 developerToolsSchema = Config.object({ developerTools: Config.pinned(options.developerTools, Config.boolean("GRAPHQL_DEVELOPER_TOOLS", { default: false })) });
 	const typed = Provider.member(HttpHandler)({
 		inject: {
+			env: Env,
 			config: HttpConfig,
 			units: HttpUnit,
+			observers: Observers,
 			...schemeDeps(schemes)
 		},
-		sync: (services) => {
+		make: (services) => Config.parse("GraphqlConfig", developerToolsSchema)(services.env).map(({ developerTools }) => {
 			const config = services.config;
 			const units = services.units;
+			const observers = services.observers;
 			if (options.units !== void 0) {
 				for (const kind of requirements === void 0 ? ["anonymous"] : schemes) if ((options.units[kind] ?? options.units["anonymous"]) !== (units[kind] ?? units["anonymous"])) throw new Error(`[graphql-server] unit kind ${JSON.stringify(kind)} differs from HttpUnit`);
 			}
@@ -28,11 +65,29 @@ 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],
+					...options.plugins ?? []
+				],
+				maskedErrors: { maskError: (error, message, isDev) => {
+					const masked = maskError(error, message, isDev);
+					if (masked !== error) observe(observers, {
+						component: "graphql",
+						name: "defect",
+						attributes: {},
+						details: { "graphql.path": pathOf(error) },
+						traced: false
+					})({
+						outcome: "error",
+						cause: causeOf(error)
+					});
+					return masked;
+				} },
 				logging: false,
-				graphiql: false,
+				graphiql: developerTools,
 				landingPage: false,
 				multipart: false,
 				maxRequestBodySize: config.bodyLimit === 0 ? false : config.bodyLimit,
@@ -77,10 +132,10 @@ const graphql = (api, options) => {
 				},
 				[dispose]: () => yoga.dispose()
 			};
-		},
+		}),
 		onStop: (answerer) => answerer[dispose]()
 	});
 	return Object.assign(typed, { authenticators: api.providers });
 };
 //#endregion
-export { graphql };
+export { fieldResult, graphql };

package/package.json

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