@znight/graphql 0.2.1 → 0.3.0

package/dist/testing.mjs

@@ -1,6 +1,651 @@
-import { n as endpointOf, r as executorOf } from "./plugin-CR_wVfRU.mjs";
-import { parseSseStream } from "@znight/http";
-import { resolveMockFn } from "@znight/testing";
+import { n as endpointOf, r as executorOf, t as GraphQLPlugin } from "./plugin-q4oz7d6s.mjs";
+import { HttpPlugin, NotFoundException, parseSseStream } from "@znight/http";
+import { TestApp, defineTestMetadata, resolveMockFn, testToken } from "@znight/testing";
+import { deepStrictEqual, ok, strictEqual } from "node:assert/strict";
+// src/conformance.ts
+/**
+* Describes the conformance scenarios of a GraphQL driver (RFC 0009 §12): queries, mutations,
+* field guards and HTTP guards, loaders batching, request-scoped providers, result mappers,
+* masking, introspection, limits, the `graphql:operation` hook, `POST` bodies other than JSON and
+* mutations over `GET` refused (CSRF) and, over SSE, subscriptions (events, completion, client
+* abort, `maxActive`, shutdown whatever the plugin order).
+*
+* ```ts
+* import { describeDriverConformance } from '@znight/graphql/testing'
+* import { yogaDriver } from '@znight/graphql/yoga'
+* import { afterAll, beforeAll, describe, it } from 'bun:test'
+*
+* describeDriverConformance({ driver: () => yogaDriver(), test: { describe, it, beforeAll, afterAll } })
+* ```
+*/
+function describeDriverConformance(options) {
+	const { test } = options;
+	const adapters = Object.entries(options.adapters ?? { default: void 0 });
+	const name = options.driver()?.name ?? "builtin";
+	test.describe(`GraphQL driver conformance: ${name}`, () => {
+		for (const [adapterName, adapter] of adapters) test.describe(`${adapterName} adapter`, () => {
+			describeOperations(options, name, adapter);
+			if (options.subscriptions !== false) describeSubscriptions(options, adapter);
+		});
+	});
+}
+const OBSERVED = Symbol("conformance.observed");
+var Catalog = class {
+	#pubsub;
+	#books = [
+		{
+			id: "1",
+			title: "Dune",
+			authorId: "herbert"
+		},
+		{
+			id: "2",
+			title: "Hyperion",
+			authorId: "simmons"
+		},
+		{
+			id: "3",
+			title: "Children of Dune",
+			authorId: "herbert"
+		}
+	];
+	[OBSERVED] = {
+		batches: [],
+		ended: [],
+		sessions: 0
+	};
+	constructor(pubsub) {
+		this.#pubsub = pubsub;
+	}
+	books() {
+		return this.#books;
+	}
+	book(args) {
+		const book = this.#books.find((candidate) => candidate.id === args.id);
+		if (book === void 0) throw new NotFoundException(`No book ${args.id}`);
+		return book;
+	}
+	secret() {
+		throw new Error("postgres://admin:secret@db");
+	}
+	async addBook(args) {
+		const book = {
+			id: String(this.#books.length + 1),
+			title: args.title,
+			authorId: "herbert"
+		};
+		this.#books.push(book);
+		await this.#pubsub.publish("bookAdded", book);
+		return book;
+	}
+	bookAdded(ctx) {
+		return this.#pubsub.subscribe("bookAdded", { signal: ctx.signal });
+	}
+	async *countdown(args) {
+		for (let n = args.from; n > 0; n--) yield await Promise.resolve(n);
+	}
+	async *forever(ctx) {
+		const signal = ctx.signal;
+		try {
+			for (let n = 1; !signal.aborted; n++) {
+				yield n;
+				await new Promise((resolve) => {
+					const timer = setTimeout(resolve, 10);
+					signal.addEventListener("abort", () => {
+						clearTimeout(timer);
+						resolve();
+					}, { once: true });
+				});
+			}
+		} finally {
+			this[OBSERVED].ended.push("forever");
+		}
+	}
+};
+var AuthorsById = class {
+	#catalog;
+	constructor(catalog) {
+		this.#catalog = catalog;
+	}
+	load(keys) {
+		this.#catalog[OBSERVED].batches.push([...keys]);
+		return Promise.resolve(keys.map((id) => ({
+			id,
+			name: id === "herbert" ? "Frank Herbert" : "Dan Simmons"
+		})));
+	}
+};
+/** Request-scoped: one per HTTP request, shared by the guard and the resolver of an operation. */
+var Session = class {
+	id;
+	user;
+	constructor(http, catalog) {
+		this.id = ++catalog[OBSERVED].sessions;
+		this.user = http.header("x-user");
+	}
+};
+var Viewer = class {
+	#session;
+	constructor(session) {
+		this.#session = session;
+	}
+	me() {
+		return {
+			id: this.#session.id,
+			user: this.#session.user ?? null
+		};
+	}
+};
+/** A field guard: editors only, read from the request-scoped session. */
+var EditorGuard = class {
+	#session;
+	constructor(session) {
+		this.#session = session;
+	}
+	canResolve() {
+		return this.#session.user === "editor";
+	}
+};
+/** An HTTP guard on the endpoint (`http.guards`). */
+var Gate = class {
+	canActivate(ctx) {
+		return ctx.header("x-block") !== "yes";
+	}
+};
+/** Errors as data (RFC 0008): a missing book is a `NotFound` of `BookResult`. */
+var Rejections = class {
+	static types = ["NotFound"];
+	toResult(error) {
+		return error instanceof NotFoundException ? {
+			__typename: "NotFound",
+			message: error.message
+		} : void 0;
+	}
+};
+/** The binding of a resolver method (what the compiler generates for `@Query()`, `@ResolveField()`...). */
+function resolver(cls, method, operation, invoke, extra = {}) {
+	return {
+		token: testToken(cls),
+		method,
+		operation,
+		guards: [],
+		meta: {},
+		invoke,
+		...extra
+	};
+}
+const TYPES = [
+	{
+		kind: "object",
+		name: "Author",
+		fields: [{
+			name: "name",
+			type: "String!"
+		}]
+	},
+	{
+		kind: "object",
+		name: "Book",
+		fields: [
+			{
+				name: "id",
+				type: "ID!"
+			},
+			{
+				name: "title",
+				type: "String!"
+			},
+			{
+				name: "author",
+				type: "Author!",
+				resolver: resolver(Catalog, "books", "field", ((_r, parent, _a, ctx) => ctx.loader(testToken(AuthorsById)).load(parent.authorId)), { loaders: [testToken(AuthorsById)] })
+			}
+		]
+	},
+	{
+		kind: "object",
+		name: "NotFound",
+		fields: [{
+			name: "message",
+			type: "String!"
+		}]
+	},
+	{
+		kind: "union",
+		name: "BookResult",
+		members: ["Book", "NotFound"],
+		discriminator: { by: "typename" }
+	},
+	{
+		kind: "object",
+		name: "Me",
+		fields: [{
+			name: "id",
+			type: "Int!"
+		}, {
+			name: "user",
+			type: "String"
+		}]
+	},
+	{
+		kind: "object",
+		name: "Query",
+		fields: [
+			{
+				name: "books",
+				type: "[Book!]!",
+				resolver: resolver(Catalog, "books", "query", ((r) => r.books()))
+			},
+			{
+				name: "book",
+				type: "BookResult!",
+				args: [{
+					name: "id",
+					type: "ID!"
+				}],
+				resolver: resolver(Catalog, "book", "query", ((r, _p, a) => ({
+					__typename: "Book",
+					...r.book(a)
+				})))
+			},
+			{
+				name: "secret",
+				type: "String",
+				resolver: resolver(Catalog, "secret", "query", ((r) => r.secret()))
+			},
+			{
+				name: "me",
+				type: "Me!",
+				resolver: resolver(Viewer, "me", "query", ((r) => r.me()))
+			}
+		]
+	},
+	{
+		kind: "object",
+		name: "Mutation",
+		fields: [{
+			name: "addBook",
+			type: "Book!",
+			args: [{
+				name: "title",
+				type: "String!"
+			}],
+			resolver: resolver(Catalog, "addBook", "mutation", ((r, _p, a) => r.addBook(a)), { guards: [testToken(EditorGuard)] })
+		}]
+	},
+	{
+		kind: "object",
+		name: "Subscription",
+		fields: [
+			{
+				name: "bookAdded",
+				type: "Book!",
+				resolver: resolver(Catalog, "bookAdded", "subscription", ((r, _p, _a, c) => r.bookAdded(c)))
+			},
+			{
+				name: "countdown",
+				type: "Int!",
+				args: [{
+					name: "from",
+					type: "Int!"
+				}],
+				resolver: resolver(Catalog, "countdown", "subscription", ((r, _p, a) => r.countdown(a)))
+			},
+			{
+				name: "forever",
+				type: "Int!",
+				resolver: resolver(Catalog, "forever", "subscription", ((r, _p, _a, c) => r.forever(c)))
+			}
+		]
+	}
+];
+function conformanceMetadata() {
+	return defineTestMetadata({
+		providers: [
+			{
+				class: Catalog,
+				deps: ["@znight/graphql#PubSub"]
+			},
+			{
+				class: AuthorsById,
+				deps: [Catalog]
+			},
+			{
+				class: Session,
+				scope: "request",
+				deps: ["@znight/http#HttpContext", Catalog]
+			},
+			{
+				class: Viewer,
+				scope: "request",
+				deps: [Session]
+			},
+			{
+				class: EditorGuard,
+				scope: "request",
+				deps: [Session]
+			},
+			Gate,
+			Rejections
+		],
+		externals: [
+			{
+				token: "@znight/graphql#GraphQLContext",
+				scope: "request",
+				providedBy: "GraphQLPlugin"
+			},
+			{
+				token: "@znight/graphql#PubSub",
+				providedBy: "GraphQLPlugin"
+			},
+			{
+				token: "@znight/graphql#GraphQLPlugin",
+				providedBy: "GraphQLPlugin"
+			},
+			{
+				token: "@znight/http#HttpContext",
+				scope: "request",
+				providedBy: "HttpPlugin"
+			},
+			{
+				token: "@znight/http#RequestId",
+				scope: "request",
+				providedBy: "HttpPlugin"
+			}
+		],
+		extensions: { graphql: {
+			version: 1,
+			schemaHash: "c0nf0rmance00000",
+			roots: {
+				query: "Query",
+				mutation: "Mutation",
+				subscription: "Subscription"
+			},
+			types: [...TYPES].sort((a, b) => a.name < b.name ? -1 : 1)
+		} }
+	});
+}
+/** The drain timeout of `HttpPlugin` in the suite: a shutdown waiting for it is a failure. */
+const DRAIN_TIMEOUT_MS = 5e3;
+/**
+* Boots the conformance application on `adapter` with `driver`, `GraphQLPlugin` after `HttpPlugin`
+* (or before it, `graphqlFirst`).
+*/
+function boot(options, adapter, graphqlFirst = false) {
+	const driver = options.driver();
+	const http = HttpPlugin.configure({
+		port: 0,
+		host: "127.0.0.1",
+		drainTimeoutMs: DRAIN_TIMEOUT_MS,
+		...adapter === void 0 ? {} : { adapter: adapter() }
+	});
+	const graphql = GraphQLPlugin.configure({
+		introspection: false,
+		resultMappers: [Rejections],
+		limits: {
+			maxAliases: 3,
+			maxDepth: 4
+		},
+		http: { guards: [Gate] },
+		subscriptions: { maxActive: 2 },
+		...driver === void 0 ? {} : { driver }
+	});
+	return TestApp.create({
+		metadata: conformanceMetadata(),
+		plugins: graphqlFirst ? [graphql, http] : [http, graphql],
+		logger: {
+			debug() {},
+			info() {},
+			warn() {},
+			error() {}
+		}
+	});
+}
+function observed(app) {
+	return app.get(testToken(Catalog))[OBSERVED];
+}
+function graphql(app) {
+	return app.app.getPlugin("graphql");
+}
+async function until(condition, what, timeoutMs = 2e3) {
+	const started = Date.now();
+	while (!condition()) {
+		if (Date.now() - started > timeoutMs) throw new Error(`conformance: ${what} did not happen within ${timeoutMs} ms`);
+		await new Promise((resolve) => setTimeout(resolve, 5));
+	}
+}
+function codes(result) {
+	return (result.errors ?? []).map((error) => error.extensions?.["code"]);
+}
+function result(response) {
+	return {
+		..."data" in response ? { data: response.data } : {},
+		...response.errors === void 0 ? {} : { errors: response.errors }
+	};
+}
+function describeOperations(options, driverName, adapter) {
+	const { test } = options;
+	let app;
+	const events = [];
+	test.beforeAll(async () => {
+		app = await boot(options, adapter);
+		app.app.hooks.on("graphql:operation", (event) => {
+			events.push({
+				driver: event.driver,
+				transport: event.transport,
+				operationName: event.operationName
+			});
+		});
+	});
+	test.afterAll(async () => {
+		await app?.close();
+	});
+	test.it("executes queries, with field resolvers batched through a loader", async () => {
+		const response = await executeOperation(app, { query: "{ books { title author { name } } }" });
+		strictEqual(response.status, 200);
+		deepStrictEqual(result(response), { data: { books: [
+			{
+				title: "Dune",
+				author: { name: "Frank Herbert" }
+			},
+			{
+				title: "Hyperion",
+				author: { name: "Dan Simmons" }
+			},
+			{
+				title: "Children of Dune",
+				author: { name: "Frank Herbert" }
+			}
+		] } });
+		deepStrictEqual(observed(app).batches.at(-1), ["herbert", "simmons"]);
+	});
+	test.it("executes mutations behind a field guard reading a request-scoped provider", async () => {
+		const denied = await executeOperation(app, { query: "mutation { addBook(title: \"Ilium\") { title } }" });
+		strictEqual(denied.status, 200);
+		deepStrictEqual(denied.data, null);
+		deepStrictEqual(codes(denied), ["FORBIDDEN"]);
+		const added = await executeOperation(app, {
+			query: "mutation Add($title: String!) { addBook(title: $title) { title author { name } } }",
+			variables: { title: "Ilium" },
+			headers: { "x-user": "editor" }
+		});
+		deepStrictEqual(result(added), { data: { addBook: {
+			title: "Ilium",
+			author: { name: "Frank Herbert" }
+		} } });
+	});
+	test.it("creates request-scoped providers once per request", async () => {
+		const first = await executeOperation(app, {
+			query: "{ a: me { id } b: me { id user } }",
+			headers: { "x-user": "ada" }
+		});
+		const second = await executeOperation(app, { query: "{ me { id } }" });
+		ok(first.data !== void 0 && first.data !== null && second.data !== void 0 && second.data !== null);
+		strictEqual(first.data.a.id, first.data.b.id);
+		strictEqual(first.data.b.user, "ada");
+		ok(second.data.me.id > first.data.a.id);
+	});
+	test.it("turns errors into data with result mappers, and masks unexpected errors", async () => {
+		const missing = await executeOperation(app, { query: "{ book(id: \"404\") { __typename ... on NotFound { message } ... on Book { title } } }" });
+		deepStrictEqual(result(missing), { data: { book: {
+			__typename: "NotFound",
+			message: "No book 404"
+		} } });
+		const secret = await executeOperation(app, { query: "{ secret }" });
+		strictEqual(secret.status, 200);
+		deepStrictEqual(result(secret), {
+			data: { secret: null },
+			errors: [{
+				message: "Unexpected error.",
+				locations: [{
+					line: 1,
+					column: 3
+				}],
+				path: ["secret"],
+				extensions: { code: "INTERNAL_SERVER_ERROR" }
+			}]
+		});
+		ok(!secret.body.includes("postgres"), "the original error leaked");
+	});
+	test.it("refuses introspection, documents past the limits and invalid documents (400)", async () => {
+		for (const [query, code] of [
+			["{ __schema { queryType { name } } }", "GRAPHQL_VALIDATION_FAILED"],
+			["{ a: me { id } b: me { id } c: me { id } d: me { id } }", "QUERY_TOO_COMPLEX"],
+			["{ books { author { name } author2: author { name } } }", void 0],
+			["{ nope }", "GRAPHQL_VALIDATION_FAILED"],
+			["{ books", "GRAPHQL_PARSE_FAILED"]
+		]) {
+			const response = await executeOperation(app, { query });
+			if (code === void 0) {
+				strictEqual(response.status, 200, query);
+				continue;
+			}
+			strictEqual(response.status, 400, query);
+			strictEqual(response.data, void 0, query);
+			deepStrictEqual([...new Set(codes(response))], [code], query);
+		}
+	});
+	test.it("runs behind the HTTP guards of the endpoint", async () => {
+		const blocked = await executeOperation(app, {
+			query: "{ books { title } }",
+			headers: { "x-block": "yes" }
+		});
+		strictEqual(blocked.status, 403);
+		strictEqual(blocked.data, void 0);
+	});
+	test.it("reports every executed operation to the graphql:operation hook, with the driver", async () => {
+		events.length = 0;
+		await executeOperation(app, { query: "query Named { books { id } }" });
+		deepStrictEqual(events, [{
+			driver: driverName,
+			transport: "http",
+			operationName: "Named"
+		}]);
+	});
+	test.it("refuses POST bodies other than JSON (415): a cross-site form never runs an operation", async () => {
+		const mutation = "mutation { addBook(title: \"Forged\") { id } }";
+		const before = await executeOperation(app, { query: "{ books { id } }" });
+		for (const [type, body] of [
+			["application/x-www-form-urlencoded", `query=${encodeURIComponent(mutation)}`],
+			["multipart/form-data; boundary=x", `--x\r\ncontent-disposition: form-data; name="query"\r\n\r\n${mutation}\r\n--x--\r\n`],
+			["text/plain", JSON.stringify({ query: mutation })],
+			["application/graphql", mutation]
+		]) {
+			const response = await app.inject({
+				method: "POST",
+				url: "/graphql",
+				headers: {
+					"content-type": type,
+					"x-user": "editor"
+				},
+				body
+			});
+			strictEqual(response.status, 415, type);
+			deepStrictEqual(response.json(), { errors: [{
+				message: "Send GraphQL requests as application/json (content-type: application/json)",
+				extensions: { code: "BAD_REQUEST" }
+			}] }, type);
+		}
+		const after = await executeOperation(app, { query: "{ books { id } }" });
+		strictEqual(after.data?.books.length, before.data?.books.length);
+	});
+	test.it("refuses mutations over GET (405, allow: POST)", async () => {
+		const before = await executeOperation(app, { query: "{ books { id } }" });
+		const response = await app.inject({
+			method: "GET",
+			url: "/graphql",
+			query: { query: "mutation { addBook(title: \"Fetched\") { id } }" },
+			headers: { "x-user": "editor" }
+		});
+		strictEqual(response.status, 405);
+		strictEqual(response.headers["allow"], "POST");
+		const after = await executeOperation(app, { query: "{ books { id } }" });
+		strictEqual(after.data?.books.length, before.data?.books.length);
+	});
+}
+function describeSubscriptions(options, adapter) {
+	const { test } = options;
+	let app;
+	test.beforeAll(async () => {
+		app = await boot(options, adapter);
+	});
+	test.afterAll(async () => {
+		await app?.close();
+	});
+	test.it("streams the events of a subscription until the client leaves", async () => {
+		const events = await subscribeOperation(app, { query: "subscription { bookAdded { title } }" });
+		strictEqual(events.status, 200);
+		await executeOperation(app, {
+			query: "mutation { addBook(title: \"Endymion\") { id } }",
+			headers: { "x-user": "editor" }
+		});
+		deepStrictEqual((await events.next()).value, { data: { bookAdded: { title: "Endymion" } } });
+		await events.return();
+		await until(() => graphql(app).activeSubscriptions === 0, "the end of the subscription");
+	});
+	test.it("completes a finite subscription", async () => {
+		const events = await subscribeOperation(app, { query: "subscription { countdown(from: 2) }" });
+		deepStrictEqual(await drain(events), [{ data: { countdown: 2 } }, { data: { countdown: 1 } }]);
+	});
+	test.it("ends the source when the client aborts, and caps the active subscriptions", async () => {
+		const ended = observed(app).ended;
+		ended.length = 0;
+		const first = await subscribeOperation(app, { query: "subscription { forever }" });
+		const second = await subscribeOperation(app, { query: "subscription { forever }" });
+		deepStrictEqual((await first.next()).value, { data: { forever: 1 } });
+		deepStrictEqual((await second.next()).value, { data: { forever: 1 } });
+		const third = await subscribeOperation(app, { query: "subscription { forever }" });
+		const refused = await third.next();
+		deepStrictEqual(codes(refused.value ?? {}), ["SERVICE_UNAVAILABLE"]);
+		await third.return();
+		await first.return();
+		await second.return();
+		await until(() => ended.length === 2, "the end of both sources");
+		await until(() => graphql(app).activeSubscriptions === 0, "the end of the subscriptions");
+	});
+	for (const graphqlFirst of [false, true]) {
+		const order = graphqlFirst ? "GraphQLPlugin before HttpPlugin" : "HttpPlugin before GraphQLPlugin";
+		test.it(`ends the subscriptions when the application stops, without waiting for the drain (${order})`, async () => {
+			const stopping = await boot(options, adapter, graphqlFirst);
+			const ended = observed(stopping).ended;
+			const events = await subscribeOperation(stopping, { query: "subscription { forever }" });
+			deepStrictEqual((await events.next()).value, { data: { forever: 1 } });
+			const rest = drain(events);
+			const started = Date.now();
+			await stopping.close();
+			const elapsed = Date.now() - started;
+			ok(elapsed < DRAIN_TIMEOUT_MS / 2, `the shutdown waited ${elapsed} ms for the drain`);
+			await until(() => ended.includes("forever"), "the end of the source on shutdown");
+			await rest;
+			strictEqual(graphql(stopping).activeSubscriptions, 0);
+		});
+	}
+}
+async function drain(events) {
+	const results = [];
+	for (let step = await events.next(); step.done !== true; step = await events.next()) results.push(step.value);
+	return results;
+}
 // src/testing.ts
 const DEFAULT_TIMEOUT_MS = 2e3;
 const RESPONSE_ACCEPT = "application/graphql-response+json, application/json;q=0.9";
@@ -301,6 +946,6 @@ var SingleResult = class {
 		return Promise.resolve();
 	}
 };
-export { executeOperation, fakeLoader, subscribeOperation };
+export { describeDriverConformance, executeOperation, fakeLoader, subscribeOperation };
 
 //# sourceMappingURL=testing.mjs.map