@geekmidas/constructs 10.0.0-alpha.11 → 10.0.0-alpha.110

package/dist/adaptors/testing.mjs

@@ -1,25 +1,63 @@
-import "../Construct-BD5neF7w.mjs";
-import "../construct-interface-Z4CpS8tK.mjs";
-import { FunctionBuilder } from "../functions-14lpEFL4.mjs";
-import "../clone-DblgEZZa.mjs";
-import { Endpoint, ResponseBuilder } from "../Endpoint-DCQPMdUX.mjs";
-import { createCookieHeaderAccessor, createObjectHeaders, publishConstructEvents, publishEvents } from "../lazyAccessors-BoJN3SMd.mjs";
-import { executeWithAuditTransaction } from "../processAudits-Dmts9H_b.mjs";
-import { HonoEndpoint } from "../HonoEndpointAdaptor-P1ahhZHu.mjs";
+import { isConsumable } from "../construct-interface.mjs";
+import { BetterAuth } from "../auth.mjs";
+import { a as publishEvents, i as publishConstructEvents, t as FunctionBuilder } from "../functions-CTI-hDem.mjs";
+import { r as ResponseBuilder, t as Endpoint } from "../Endpoint-gPXhHKhJ.mjs";
+import { t as Queue } from "../Queue-cmhqEBOB.mjs";
+import { Email } from "../email.mjs";
+import { t as KyselyDatabase } from "../kysely-B_0BAr0T.mjs";
+import { f as createObjectHeaders, s as createCookieHeaderAccessor } from "../readRequestBody-BTIl3k-D.mjs";
+import { t as Topic } from "../Topic-D2R0r24C.mjs";
+import { t as HonoEndpoint } from "../HonoEndpointAdaptor-euH1oSdY.mjs";
+import { i as executeWithAuditTransaction, n as enforceRateLimit, t as requestLogger } from "../requestLogger-pA4gi3E1.mjs";
+import { provideKey } from "@geekmidas/manifest";
+import { randomUUID } from "node:crypto";
+import { ServiceDiscovery, currentRequestContext, runWithRequestContext, serviceContext } from "@geekmidas/services";
 import { ForbiddenError } from "@geekmidas/errors";
 import { EnvironmentParser } from "@geekmidas/envkit";
-import { ServiceDiscovery, runWithRequestContext } from "@geekmidas/services";
-import { DefaultAuditor } from "@geekmidas/audit";
 import { Hono } from "hono";
+import { DefaultAuditor } from "@geekmidas/audit";
+import { TEST_CONTEXT_HEADER, currentTestContext, installContextFetch, runAsServer, runInTestContext, testContextOf } from "@geekmidas/testkit/context";
 import { http } from "msw";
-
-//#region src/endpoints/MswEndpointAdaptor.ts
+import { Browser } from "@geekmidas/testkit/browser";
+import { faker } from "@geekmidas/testkit/faker";
+import { createMailbox } from "@geekmidas/testkit/mailbox";
+import { TransactionRegistry } from "@geekmidas/testkit/transactions";
+import { setupServer } from "msw/node";
+import { afterAll, beforeAll, test } from "vitest";
+import { existsSync, readFileSync } from "node:fs";
+import tls from "node:tls";
+import { fileURLToPath } from "node:url";
+//#region src/testing/peer.ts
 /**
-* Header used to identify which test context a request belongs to.
-* Each concurrent test registers its own context (services, db transaction, etc.)
-* and the MSW handler looks it up by this header value.
+* The TCP peer a test's in-process requests arrive from.
+*
+* A feature test hands a request straight to a surface's Hono app — no
+* socket, no server — so the app's bindings have no peer to read. Deployed,
+* every request has one, and what a surface trusts follows from it: the auth
+* server honours `x-gkm-client-ip` only from an internal caller, a loopback
+* or private peer with no `Origin` and no forwarding header. With no peer at
+* all the header was dropped, and every test's session check became the same
+* client to Better Auth's rate limiter.
+*
+* So an in-process dispatch says where it came from, the way
+* `@hono/node-server` does: its bindings carry `incoming.socket.remoteAddress`.
+* The address is loopback because that is the truth — the request came from
+* this process. A browser's own address still travels in its
+* `x-forwarded-for`, which makes it outside traffic exactly as it would be
+* behind the stack's proxy.
+*
+* Only a test's dispatch passes these. A runtime with no socket of its own
+* (Lambda, Bun) still has no peer, and a request with no peer is still not an
+* internal caller's.
 */
-const TEST_CONTEXT_HEADER = "x-test-context-id";
+/** The address an in-process request presents as its peer. */
+const IN_PROCESS_PEER_ADDRESS = "127.0.0.1";
+/** Bindings for `app.fetch(request, bindings)` from inside this process. */
+function inProcessBindings() {
+	return { incoming: { socket: { remoteAddress: IN_PROCESS_PEER_ADDRESS } } };
+}
+//#endregion
+//#region src/endpoints/MswEndpointAdaptor.ts
 const MSW_HTTP_METHODS = [
 	"get",
 	"post",
@@ -67,7 +105,6 @@ function createMswHandlers(endpoints, options) {
 				break;
 			}
 		}
-		if (ctxOptions.publisher) serviceDefs.push(ctxOptions.publisher);
 		if (ctxOptions.auditorStorage !== void 0) {
 			for (const endpoint of endpoints) if (endpoint.auditorStorageService) {
 				serviceDefs.push({
@@ -98,7 +135,7 @@ function createMswHandlers(endpoints, options) {
 			});
 			const app = new Hono();
 			HonoEndpoint.addRoute(endpoint, ctx.serviceDiscovery, app);
-			const response = await app.request(request);
+			const response = await app.request(request, void 0, inProcessBindings());
 			return new Response(response.body, {
 				status: response.status,
 				statusText: response.statusText,
@@ -111,7 +148,6 @@ function createMswHandlers(endpoints, options) {
 		registerContext
 	};
 }
-
 //#endregion
 //#region src/endpoints/TestEndpointAdaptor.ts
 /**
@@ -131,6 +167,8 @@ function serializeCookie(name, value, options) {
 	return cookieString;
 }
 var TestEndpointAdaptor = class TestEndpointAdaptor {
+	endpoint;
+	serviceDiscovery;
 	static getDefaultServiceDiscover(_endpoint) {
 		return ServiceDiscovery.getInstance(new EnvironmentParser({}));
 	}
@@ -146,17 +184,17 @@ var TestEndpointAdaptor = class TestEndpointAdaptor {
 		const cookie = createCookieHeaderAccessor(ctx.headers.cookie);
 		const startTime = Date.now();
 		const requestId = ctx.requestId ?? ctx.headers["x-request-id"] ?? crypto.randomUUID();
-		const logger = this.endpoint.logger.child({
+		let logger = requestLogger(this.endpoint, {
 			requestId,
-			route: this.endpoint.route,
-			host: ctx.headers.host,
-			method: this.endpoint.method
+			host: ctx.headers.host
 		});
 		const rawDb = ctx.database;
+		const operation = `${this.endpoint.method} ${this.endpoint.route}`;
 		return runWithRequestContext({
 			logger,
 			requestId,
-			startTime
+			startTime,
+			operation
 		}, async () => {
 			const session = await this.endpoint.getSession({
 				logger,
@@ -165,7 +203,8 @@ var TestEndpointAdaptor = class TestEndpointAdaptor {
 				cookie,
 				...rawDb !== void 0 && { db: rawDb }
 			});
-			const isAuthorized = await this.endpoint.authorize({
+			logger = currentRequestContext()?.logger ?? logger;
+			if (!await this.endpoint.authorize({
 				header,
 				cookie,
 				services: ctx.services,
@@ -175,11 +214,18 @@ var TestEndpointAdaptor = class TestEndpointAdaptor {
 				body,
 				query,
 				params
-			});
-			if (!isAuthorized) {
+			})) {
 				logger.warn("Forbidden access attempt");
 				throw new ForbiddenError("Forbidden access to the endpoint", "You do not have permission to access this resource.");
 			}
+			const rateLimitHeaders = this.endpoint.rateLimit ? await enforceRateLimit(this.endpoint.rateLimit, {
+				header,
+				services: ctx.services,
+				logger,
+				session,
+				path: this.endpoint.route,
+				method: this.endpoint.method
+			}) : {};
 			const auditorStorage = ctx.auditorStorage;
 			let auditContext;
 			if (auditorStorage) {
@@ -198,24 +244,22 @@ var TestEndpointAdaptor = class TestEndpointAdaptor {
 				} catch (error) {
 					logger.error(error, "Failed to extract actor for audits");
 				}
-				const auditor = new DefaultAuditor({
-					actor,
-					storage: auditorStorage,
-					metadata: {
-						endpoint: this.endpoint.route,
-						method: this.endpoint.method
-					}
-				});
 				auditContext = {
-					auditor,
+					auditor: new DefaultAuditor({
+						actor,
+						storage: auditorStorage,
+						metadata: {
+							endpoint: this.endpoint.route,
+							method: this.endpoint.method
+						}
+					}),
 					storage: auditorStorage
 				};
 			}
 			const audits = this.endpoint.audits;
 			if (!auditContext && audits?.length) logger.warn("No auditor storage service available");
-			const result = await executeWithAuditTransaction(auditContext, async (auditor) => {
-				const trx = auditor?.getTransaction?.();
-				const db = trx ?? rawDb;
+			const { output, metadata, redirect } = await executeWithAuditTransaction(auditContext, async (auditor) => {
+				const db = auditor?.getTransaction?.() ?? rawDb;
 				const responseBuilder = new ResponseBuilder();
 				const response = await this.endpoint.handler({
 					body,
@@ -230,54 +274,56 @@ var TestEndpointAdaptor = class TestEndpointAdaptor {
 					db
 				}, responseBuilder);
 				let data = response;
-				let metadata$1 = responseBuilder.getMetadata();
+				let metadata = responseBuilder.getMetadata();
 				if (Endpoint.hasMetadata(response)) {
 					data = response.data;
-					metadata$1 = response.metadata;
+					metadata = response.metadata;
 				}
-				const output$1 = await this.endpoint.parseOutput(data);
+				const redirect = Endpoint.isRedirectStatus(metadata.status ?? this.endpoint.status);
 				return {
-					output: output$1,
-					metadata: metadata$1,
-					responseBuilder
+					output: redirect ? void 0 : await this.endpoint.parseOutput(data),
+					metadata,
+					responseBuilder,
+					redirect
 				};
-			}, async (result$1, auditor) => {
-				if (!audits?.length) return;
+			}, async (result, auditor) => {
+				if (!audits?.length || result.redirect) return;
 				for (const audit of audits) {
-					if (audit.when && !audit.when(result$1.output)) continue;
-					const payload = audit.payload(result$1.output);
-					const entityId = audit.entityId?.(result$1.output);
+					if (audit.when && !audit.when(result.output)) continue;
+					const payload = audit.payload(result.output);
+					const entityId = audit.entityId?.(result.output);
 					auditor.audit(audit.type, payload, {
 						table: audit.table,
 						entityId
 					});
 				}
 			}, { db: rawDb });
-			const { output, metadata } = result;
-			ctx.publisher && await this.serviceDiscovery.register([ctx.publisher]);
-			await publishConstructEvents(this.endpoint, output, this.serviceDiscovery);
-			const headers = { ...metadata.headers || {} };
+			if (!redirect) await publishConstructEvents(this.endpoint, output, this.serviceDiscovery, this.endpoint.logger, ctx.services);
+			const headers = {
+				...rateLimitHeaders,
+				...metadata.headers || {}
+			};
 			if (metadata.cookies && metadata.cookies.size > 0) {
 				const setCookieValues = [];
-				for (const [name, cookie$1] of metadata.cookies.entries()) setCookieValues.push(serializeCookie(name, cookie$1.value, cookie$1.options));
+				for (const [name, cookie] of metadata.cookies.entries()) setCookieValues.push(serializeCookie(name, cookie.value, cookie.options));
 				headers["set-cookie"] = setCookieValues;
 			}
 			return {
 				body: output,
-				status: metadata.status || 200,
+				status: metadata.status ?? this.endpoint.status,
 				headers
 			};
 		});
 	}
 	async request(ctx) {
-		const response = await this.fullRequest(ctx);
-		return response.body;
+		return (await this.fullRequest(ctx)).body;
 	}
 };
-
 //#endregion
 //#region src/functions/TestFunctionAdaptor.ts
 var TestFunctionAdaptor = class TestFunctionAdaptor {
+	fn;
+	serviceDiscovery;
 	static getDefaultServiceDiscovery(_fn) {
 		return ServiceDiscovery.getInstance(new EnvironmentParser({}));
 	}
@@ -293,15 +339,11 @@ var TestFunctionAdaptor = class TestFunctionAdaptor {
 		else services = await this.serviceDiscovery.register(this.fn.services);
 		let db;
 		if ("db" in ctx && ctx.db !== void 0) db = ctx.db;
-		else if (this.fn.databaseService) {
-			const dbServices = await this.serviceDiscovery.register([this.fn.databaseService]);
-			db = dbServices[this.fn.databaseService.serviceName];
-		}
+		else if (this.fn.databaseService) db = (await this.serviceDiscovery.register([this.fn.databaseService]))[this.fn.databaseService.serviceName];
 		let auditor;
 		if ("auditor" in ctx && ctx.auditor !== void 0) auditor = ctx.auditor;
 		else if (this.fn.auditorStorageService) {
-			const auditServices = await this.serviceDiscovery.register([this.fn.auditorStorageService]);
-			const storage = auditServices[this.fn.auditorStorageService.serviceName];
+			const storage = (await this.serviceDiscovery.register([this.fn.auditorStorageService]))[this.fn.auditorStorageService.serviceName];
 			auditor = new DefaultAuditor({
 				actor: {
 					id: "system",
@@ -315,11 +357,10 @@ var TestFunctionAdaptor = class TestFunctionAdaptor {
 			});
 		}
 		const requestId = `test-${Date.now()}`;
-		const startTime = Date.now();
 		return runWithRequestContext({
 			logger,
 			requestId,
-			startTime
+			startTime: Date.now()
 		}, async () => {
 			const response = await this.fn.fn({
 				input: parsedInput,
@@ -336,24 +377,26 @@ var TestFunctionAdaptor = class TestFunctionAdaptor {
 					await auditor.flush();
 				}
 			}
-			await publishEvents(logger, this.serviceDiscovery, this.fn.events, output, this.fn.publisherService);
+			await publishEvents(logger, this.serviceDiscovery, this.fn.events, output, services);
 			return output;
 		});
 	}
 };
-
 //#endregion
 //#region src/queue/TestQueueAdaptor.ts
 /**
 * In-memory test driver for a {@link Queue} worker. Hand it a batch of messages
 * and it registers the queue's services, runs the handler in a request context,
-* and returns the handler result — no SQS/pg-boss required.
+* and returns the handler result — no SQS/pg-boss required. A queue with a
+* database gets `db` registered from it, or the one the request passes.
 *
 * @example
 * const adapter = new TestQueueAdaptor(ordersQueue);
 * await adapter.invoke({ messages: [{ orderId: '123' }] });
 */
 var TestQueueAdaptor = class TestQueueAdaptor {
+	queue;
+	serviceDiscovery;
 	static getDefaultServiceDiscovery() {
 		return ServiceDiscovery.getInstance(new EnvironmentParser({}));
 	}
@@ -364,23 +407,33 @@ var TestQueueAdaptor = class TestQueueAdaptor {
 	async invoke(request) {
 		const logger = this.queue.logger.child({ test: true });
 		const services = request.services ?? await this.serviceDiscovery.register(this.queue.services);
+		const db = request.db !== void 0 ? request.db : await this.getDatabase();
 		const requestId = `test-${Date.now()}`;
 		const startTime = Date.now();
+		const operation = `queue ${this.queue.name}`;
 		return runWithRequestContext({
 			logger,
 			requestId,
-			startTime
+			startTime,
+			operation
 		}, () => this.queue.handler({
 			messages: request.messages,
 			services,
-			logger
+			logger,
+			db
 		}));
 	}
+	async getDatabase() {
+		const service = this.queue.databaseService;
+		if (!service) return void 0;
+		return (await this.serviceDiscovery.register([service]))[service.serviceName];
+	}
 };
-
 //#endregion
 //#region src/subscribers/TestSubscriberAdaptor.ts
 var TestSubscriberAdaptor = class TestSubscriberAdaptor {
+	subscriber;
+	serviceDiscovery;
 	static getDefaultServiceDiscovery() {
 		return ServiceDiscovery.getInstance(new EnvironmentParser({}));
 	}
@@ -393,19 +446,23 @@ var TestSubscriberAdaptor = class TestSubscriberAdaptor {
 		let services;
 		if (request.services) services = request.services;
 		else services = await this.serviceDiscovery.register(this.subscriber.services);
+		const db = request.db !== void 0 ? request.db : await this.getDatabase();
 		const filteredEvents = this.filterEvents(request.events);
 		if (filteredEvents.length === 0) return { batchItemFailures: [] };
 		const requestId = `test-${Date.now()}`;
 		const startTime = Date.now();
+		const operation = `subscriber ${this.subscriber.topicName ?? "test"}`;
 		return runWithRequestContext({
 			logger,
 			requestId,
-			startTime
+			startTime,
+			operation
 		}, async () => {
 			const result = await this.subscriber.handler({
 				events: filteredEvents,
 				services,
-				logger
+				logger,
+				db
 			});
 			let output = result;
 			if (this.subscriber.outputSchema && result) {
@@ -413,16 +470,607 @@ var TestSubscriberAdaptor = class TestSubscriberAdaptor {
 				if (validationResult.issues) throw new Error("Subscriber output validation failed");
 				output = validationResult.value;
 			}
-			await publishEvents(logger, this.serviceDiscovery, this.subscriber.events, output, this.subscriber.publisherService);
 			return output;
 		});
 	}
+	async getDatabase() {
+		const service = this.subscriber.databaseService;
+		if (!service) return void 0;
+		return (await this.serviceDiscovery.register([service]))[service.serviceName];
+	}
 	filterEvents(events) {
 		if (!this.subscriber.subscribedEvents) return events;
 		return events.filter((event) => this.subscriber.subscribedEvents.includes(event.type));
 	}
 };
-
 //#endregion
-export { TEST_CONTEXT_HEADER, TestEndpointAdaptor, TestFunctionAdaptor, TestQueueAdaptor, TestSubscriberAdaptor, createMswHandlers };
+//#region src/testing/manifest.ts
+/**
+* The test manifest: what `gkm test` knows about an app, written down for the
+* suite it starts.
+*
+* `gkm test` discovers the constructs, reconciles the test stage and resolves
+* its environment — then, until this existed, threw all of it away and left a
+* test to declare it again by hand. The manifest keeps it: which construct and
+* endpoint is exported where, and the environment the test stage resolved,
+* under the keys the constructs themselves derive. A feature test is built from
+* it, so nothing a test says can drift from what the app declares.
+*/
+/** The environment variable `gkm test` names the manifest in. */
+const TEST_MANIFEST_ENV = "GKM_TEST_MANIFEST";
+/**
+* Read a test manifest: from a path, a `file:` URL, or — given nothing — the
+* one `gkm test` named in `GKM_TEST_MANIFEST`.
+*/
+function loadTestManifest(from) {
+	const location = from ?? process.env["GKM_TEST_MANIFEST"];
+	if (!location) throw new NoTestManifest();
+	trustLocalEdge();
+	const path = location instanceof URL || location.startsWith("file:") ? fileURLToPath(location) : location;
+	return JSON.parse(readFileSync(path, "utf-8"));
+}
+let trusted = false;
+/**
+* Trust the local edge's certificate authority in this thread.
+*
+* `NODE_EXTRA_CA_CERTS` does it for a process started with it — which a
+* suite started by `gkm test` is, and one started by plain `vitest` or an
+* editor is not: its setup only learns the path once Vitest is running, and a
+* worker *thread* shares that process and keeps a TLS store of its own. Every
+* feature test loads the manifest, so this is the one place each worker passes
+* through.
+*/
+function trustLocalEdge() {
+	const certificate = process.env.NODE_EXTRA_CA_CERTS;
+	if (trusted || !certificate || !existsSync(certificate)) return;
+	trusted = true;
+	tls.setDefaultCACertificates([...tls.getCACertificates("default"), readFileSync(certificate, "utf-8")]);
+}
+/** A feature test ran without a manifest to build itself from. */
+var NoTestManifest = class extends Error {
+	constructor() {
+		super(`No test manifest: run the suite with \`gkm test\`, or add \`globalSetup: ['@geekmidas/cli/vitest']\` to the root vitest config — either writes one and names it in ${TEST_MANIFEST_ENV}.`);
+		this.name = "NoTestManifest";
+	}
+};
+//#endregion
+//#region src/testing/featureTest.ts
+/**
+* `featureTest`: an app, driven the way it runs deployed.
+*
+* A browser signs in and calls the API; the API calls the auth server; each
+* over its URL, each database in its own transaction. Nothing runs as a server:
+* every URL an app's constructs answer on is served in-process through MSW,
+* from the real handler, for the test that made the request. Everything else
+* with a real local equivalent — Postgres, Mailpit, MinIO — is used directly.
+*
+* It is built from the test manifest `gkm test` writes — the constructs and
+* endpoints the app exports, and the environment the test stage resolved — so
+* a test declares none of it. `gkm test` also generates the configured `it`
+* and a `Browser` with a typed client per surface:
+*
+* ```ts
+* import { it } from '#test';
+*
+* it('shows the signed-in user their profile', async ({ browser, mailbox }) => {
+*   await browser.auth.signIn.magicLink({ email: 'ada@shop.test' });
+*   await browser.visit((await mailbox('ada@shop.test').last()).link!);
+*   expect(await browser.api.get('/profile')).toMatchObject({ email: 'ada@shop.test' });
+* });
+* ```
+*/
+/** Every test in flight in this process, by id. */
+const contexts = /* @__PURE__ */ new Map();
+/** Databases already resolving to test transactions — patched once each. */
+const bound = /* @__PURE__ */ new WeakSet();
+function featureTest(options = {}) {
+	const manifest = options.manifest ?? loadTestManifest();
+	const BrowserClass = options.browser ?? Browser;
+	let app;
+	let factoryDatabases = [];
+	let owned = [];
+	let network;
+	let restoreFetch = () => {};
+	beforeAll(async () => {
+		app = await load(manifest, options.modules ?? {});
+		owned = ownDatabases(app, manifest);
+		factoryDatabases = databasesFor(options.factories ?? {}, owned);
+		for (const database of app.databases) bindToTests(database);
+		network = setupServer(...surfaceHandlers(app.endpoints, manifest.env), ...app.auths.map((auth) => authHandler(auth, manifest.env, app.envParser)), ...Object.entries(options.fakes ?? {}).flatMap(([id, fake]) => fakeHandler(id, fake, manifest.env)));
+		network.listen({ onUnhandledRequest(request, print) {
+			if (isLocal(new URL(request.url))) return;
+			print.error();
+		} });
+		const restoreStamp = installContextFetch();
+		const stamped = globalThis.fetch;
+		globalThis.fetch = deliveringFetch(stamped, (id) => {
+			const state = contexts.get(id);
+			return state ? deliver(app, state, id) : Promise.resolve();
+		});
+		restoreFetch = () => {
+			globalThis.fetch = stamped;
+			restoreStamp();
+		};
+	});
+	afterAll(() => {
+		restoreFetch();
+		network?.close();
+	});
+	const run = (name, fn) => async () => {
+		const id = randomUUID();
+		faker.seed(seedOf(name));
+		const state = {
+			transactions: new TransactionRegistry(),
+			discovery: new ServiceDiscovery(app.envParser),
+			surfaces: /* @__PURE__ */ new Map(),
+			auth: /* @__PURE__ */ new Map(),
+			addresses: /* @__PURE__ */ new Set(),
+			published: /* @__PURE__ */ new Map(),
+			pending: [],
+			delivering: false
+		};
+		const readMail = app.readMail;
+		if (readMail) state.mailbox = (address) => {
+			state.addresses.add(address);
+			return readMail(address);
+		};
+		contexts.set(id, state);
+		await state.discovery.register(recorders(app.channels, state));
+		try {
+			await runInTestContext(id, async () => {
+				const browser = new BrowserClass();
+				const restore = browser.install();
+				try {
+					const transaction = (database) => state.transactions.get(database.id, urlOf(database, app.envParser), database.clientConfig);
+					const db = { get: (name) => {
+						const database = owned.find((candidate) => candidate.service.serviceName === name);
+						if (!database) throw new UnknownDatabase(name, owned.map((candidate) => candidate.service.serviceName));
+						return transaction(database);
+					} };
+					const built = /* @__PURE__ */ new Map();
+					await fn({
+						browser,
+						db,
+						factories: { get: (name) => {
+							const database = factoryDatabases.find(([candidate]) => candidate === name)?.[1];
+							if (!database) throw new UnknownFactory(name, factoryDatabases.map(([candidate]) => candidate));
+							let factory = built.get(name);
+							if (!factory) {
+								factory = transaction(database).then(options.factories[name]);
+								built.set(name, factory);
+							}
+							return factory;
+						} },
+						faker,
+						mailbox: (address) => {
+							if (!state.mailbox) throw new NoInbox();
+							return state.mailbox(address);
+						},
+						published: (channel) => [...state.published.get(channel.id) ?? []],
+						services: { get: (name) => resolveService(app, state, name) },
+						subscriber: (subscriber) => thenDeliver(new TestSubscriberAdaptor(subscriber, state.discovery), () => deliver(app, state, id)),
+						queue: (queue) => thenDeliver(new TestQueueAdaptor(queue, state.discovery), () => deliver(app, state, id))
+					});
+				} finally {
+					restore();
+				}
+			});
+		} finally {
+			contexts.delete(id);
+			await Promise.all([state.transactions.rollbackAll(), ...[...state.addresses].map((address) => app.readMail?.(address).clear())]);
+		}
+	};
+	const it = ((name, fn, timeout) => test(name, run(name, fn), timeout));
+	it.only = (name, fn, timeout) => test.only(name, run(name, fn), timeout);
+	it.skip = (name, fn, timeout) => test.skip(name, run(name, fn), timeout);
+	return it;
+}
+/**
+* A test's faker seed, from its name: the same test draws the same data on
+* every run, and two tests draw different data.
+*/
+function seedOf(name) {
+	let hash = 0;
+	for (const char of name) hash = Math.imul(hash, 31) + char.charCodeAt(0) | 0;
+	return hash >>> 0;
+}
+/**
+* Import what the manifest points at.
+*
+* The same modules the app runs, so a construct here *is* the app's construct —
+* the one its endpoints were built from — never a copy declared again.
+*/
+async function load(manifest, modules) {
+	const envParser = new EnvironmentParser({ ...manifest.env });
+	const imported = async ({ file, export: name }) => (modules[file] ?? await import(file))[name];
+	const constructs = await Promise.all(Object.values(manifest.constructs).map(({ source }) => imported(source)));
+	const endpoints = (await Promise.all(manifest.endpoints.map(({ source }) => imported(source)))).filter((value) => Endpoint.isEndpoint(value));
+	const subscribers = (await Promise.all((manifest.subscribers ?? []).map(async ({ source }) => ({
+		name: source.export,
+		subscriber: await imported(source)
+	})))).filter((entry) => entry.subscriber?.__IS_SUBSCRIBER__ === true);
+	const unique = (values) => [...new Set(values)];
+	const databases = unique(constructs.filter((value) => value instanceof KyselyDatabase));
+	const auths = unique(constructs.filter((value) => value instanceof BetterAuth));
+	const emails = unique(constructs.filter((value) => value instanceof Email));
+	const consumables = unique(constructs.filter(isConsumable));
+	const channels = unique(constructs.filter((value) => value instanceof Topic || value instanceof Queue));
+	const inbox = emails.map((email) => manifest.env[provideKey(email.id, "inboxUrl")]).find(Boolean);
+	return {
+		envParser,
+		endpoints,
+		databases,
+		auths,
+		emails,
+		channels,
+		consumables,
+		subscribers,
+		...inbox ? { readMail: createMailbox({ inbox }) } : {}
+	};
+}
+/**
+* A publisher that records rather than sends, under the name a topic or queue
+* is injected by — `services.users` — which is also the one `.event(users, …)`
+* publishes through.
+*/
+function recorders(channels, state) {
+	return channels.map((channel) => {
+		const publisher = { async publish(messages) {
+			const sent = messages.map(({ type, payload }) => ({
+				type,
+				payload
+			}));
+			state.published.set(channel.id, [...state.published.get(channel.id) ?? [], ...sent]);
+			state.pending.push({
+				channel,
+				messages: sent
+			});
+		} };
+		return {
+			serviceName: channel.service.serviceName,
+			register: () => publisher
+		};
+	});
+}
+/**
+* The databases a test is handed: the app's own. A schema tenant an auth server
+* owns is reached through that server, as the app reaches it, and a reader is
+* the same database through a read-only role — neither is another database to
+* test against.
+*/
+function ownDatabases(app, manifest) {
+	const owners = new Set(app.auths.map((auth) => auth.databaseId));
+	return app.databases.filter((database) => !owners.has(database.id) && manifest.constructs[database.id]?.kind !== "database-reader");
+}
+/** Each factory's database, found by the service name it is keyed by. */
+function databasesFor(factories, databases) {
+	return Object.keys(factories).map((name) => {
+		const database = databases.find((candidate) => candidate.service.serviceName === name);
+		if (!database) throw new UnknownFactory(name, databases.map((candidate) => candidate.service.serviceName));
+		return [name, database];
+	});
+}
+/**
+* Make a database resolve, inside a test, to that test's transaction.
+*
+* Everything reaches a database through its service — an endpoint through
+* service discovery, the auth server through its tenant directly — so this is
+* the one place a test's connection can be handed over. Outside a test it is
+* the database it always was.
+*/
+/** Rounds of delivery before a chain of consumers is called a loop. */
+const MAX_DELIVERY_ROUNDS = 25;
+/**
+* Deliver what this test published, in-process, as the broker would — and
+* keep delivering what the consumers publish in turn, until nothing is left.
+*
+* - A queue's messages go to its one consumer, as a batch.
+* - A topic's events go to every subscriber that named their type, and only
+*   those: fan-out, as the filter policy (SNS) or the per-subscriber queue
+*   (pg-boss) does it.
+* - Each payload is checked against the consumer's schema first. Turning an
+*   SNS envelope or an SQS record into `{ type, payload }` is each adaptor's
+*   job and tested there; what is tested here is what the handler is handed.
+* - Consumers run as the server side of this test, so their databases are
+*   this test's transactions and their writes roll back with it.
+* - A consumer that throws fails the test. Deployed, the message would be
+*   retried; here a retry would only hide the bug.
+*/
+async function deliver(app, state, id) {
+	if (state.delivering) return;
+	state.delivering = true;
+	try {
+		for (let round = 0; state.pending.length > 0; round++) {
+			if (round === MAX_DELIVERY_ROUNDS) throw new DeliveryDidNotSettle(MAX_DELIVERY_ROUNDS, [...new Set(state.pending.map(({ channel }) => channel.id))]);
+			for (const { channel, messages } of state.pending.splice(0)) if (channel instanceof Queue) await toQueue(channel, messages, state, id);
+			else await toSubscribers(channel, messages, app, state, id);
+		}
+	} finally {
+		state.delivering = false;
+	}
+}
+async function toQueue(queue, messages, state, id) {
+	const payloads = [];
+	for (const message of messages) payloads.push(await accepted(queue.messageSchema, message, `queue '${queue.name}'`));
+	await runAsServer(id, () => new TestQueueAdaptor(queue, state.discovery).invoke({ messages: payloads })).catch((error) => {
+		throw new DeliveryFailed(`queue '${queue.name}'`, messages, error);
+	});
+}
+async function toSubscribers(topic, messages, app, state, id) {
+	for (const { name, subscriber } of app.subscribers) {
+		if (subscriber.topicName !== topic.name) continue;
+		const named = messages.filter(({ type }) => (subscriber.subscribedEvents ?? []).includes(type));
+		if (named.length === 0) continue;
+		const consumer = `subscriber '${name}'`;
+		const events = [];
+		for (const message of named) {
+			const schema = topic.eventSchemas[message.type];
+			events.push({
+				type: message.type,
+				payload: await accepted(schema, message, consumer)
+			});
+		}
+		await runAsServer(id, () => new TestSubscriberAdaptor(subscriber, state.discovery).invoke({ events })).catch((error) => {
+			throw new DeliveryFailed(consumer, named, error);
+		});
+	}
+}
+/** The payload, if the consumer's schema takes it — what the handler is handed. */
+async function accepted(schema, message, consumer) {
+	const standard = schema?.["~standard"];
+	if (!standard) return message.payload;
+	const result = await standard.validate(message.payload);
+	if (result.issues) throw new MessageRejected(consumer, message, result.issues);
+	return result.value;
+}
+/** `fetch`, delivering what the test published once each of its requests answers. */
+function deliveringFetch(inner, settle) {
+	return async (input, init) => {
+		const context = currentTestContext();
+		const response = await inner(input, init);
+		if (context?.side === "client") await settle(context.id);
+		return response;
+	};
+}
+/** An adaptor whose `invoke` delivers what it published before returning. */
+function thenDeliver(adaptor, settle) {
+	const invoke = adaptor.invoke.bind(adaptor);
+	adaptor.invoke = (async (...args) => {
+		const result = await invoke(...args);
+		await settle();
+		return result;
+	});
+	return adaptor;
+}
+function bindToTests(database) {
+	if (bound.has(database)) return;
+	bound.add(database);
+	const service = database.service;
+	const register = service.register;
+	service.register = (options) => {
+		const context = currentTestContext();
+		const state = context && contexts.get(context.id);
+		if (!state) return register(options);
+		return state.transactions.get(database.id, urlOf(database, options.envParser), database.clientConfig);
+	};
+}
+function urlOf(database, envParser) {
+	return envParser.create((get) => ({ url: get(provideKey(database.id, "url")).string() })).parse().url;
+}
+/** Each surface's endpoints, served at its URL for the test that asked. */
+function surfaceHandlers(endpoints, env) {
+	const bySurface = /* @__PURE__ */ new Map();
+	for (const endpoint of endpoints) {
+		const surface = endpoint.surface?.id;
+		if (!surface) continue;
+		bySurface.set(surface, [...bySurface.get(surface) ?? [], endpoint]);
+	}
+	return [...bySurface].flatMap(([surface, served]) => {
+		const base = env[provideKey(surface, "url")];
+		if (!base) return [];
+		return http.all(`${trim(base)}/*`, ({ request }) => serve(request, async (state) => {
+			let app = state.surfaces.get(surface);
+			if (!app) {
+				app = Promise.resolve().then(() => {
+					const hono = new Hono();
+					HonoEndpoint.addRoutes(served, state.discovery, hono);
+					return hono;
+				});
+				state.surfaces.set(surface, app);
+			}
+			return (await app).fetch(request, inProcessBindings());
+		}));
+	});
+}
+/**
+* An external API's app fake, answering at the URL the test stage resolved for
+* it — so a handler that calls Polar calls the fake, and the test sets up
+* nothing.
+*
+* Not per test, unlike a surface: a fake stands in for somebody else's server,
+* which no test's transaction reaches. An image fake has no handler here — its
+* container answers on localhost, which is let through.
+*/
+function fakeHandler(id, fake, env) {
+	const base = env[provideKey(id, "url")];
+	if (fake.kind !== "app" || !base) return [];
+	return [http.all(`${trim(base)}/*`, ({ request }) => fake.handler.fetch(request))];
+}
+/**
+* A construct's client for this test, by service name — through the test's own
+* discovery, so a topic or queue is its recorder and a database its
+* transaction, exactly as the test's endpoints get them.
+*/
+async function resolveService(app, state, name) {
+	const construct = app.consumables.find((candidate) => candidate.service.serviceName === name);
+	if (!construct) throw new UnknownService(name, app.consumables.map((candidate) => candidate.service.serviceName));
+	return (await state.discovery.register([construct.service]))[name];
+}
+/** An auth server, served at its URL, on the transaction of the test that asked. */
+function authHandler(auth, env, envParser) {
+	const base = trim(env[provideKey(auth.id, "url")] ?? "");
+	return http.all(`${base}/*`, ({ request }) => serve(request, async (state) => {
+		let app = state.auth.get(auth);
+		if (!app) {
+			app = auth.server({
+				envParser,
+				context: serviceContext
+			}).then(({ app }) => app);
+			state.auth.set(auth, app);
+		}
+		return (await app).fetch(request, inProcessBindings());
+	}));
+}
+/** Handle a request as the server side of the test it was made for. */
+async function serve(request, handle) {
+	const id = testContextOf(request);
+	const state = id ? contexts.get(id) : void 0;
+	if (!id || !state) throw new UnknownTestContext(request.url, id);
+	return runAsServer(id, () => handle(state));
+}
+function trim(url) {
+	return url.replace(/\/$/, "");
+}
+function isLocal(url) {
+	return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname.endsWith(".localhost");
+}
+/**
+* Sign a test's browser in the way a person does: ask the auth server for a
+* magic link, open the email it sent, follow the link.
+*
+* What the generated `browser.signIn(email)` calls. The address's mail is
+* cleared first — so the link is this request's, not one an earlier test left
+* — and cleared again after the test, like any address a test reads. Returns
+* the session the auth server then reports, as better-auth hands it back.
+*/
+async function signInWithMagicLink(browser, auth, email = freshAddress()) {
+	const context = currentTestContext();
+	const state = context && contexts.get(context.id);
+	if (!state) throw new UnknownTestContext("signIn", context?.id);
+	if (!state.mailbox) throw new NoInbox();
+	const inbox = state.mailbox(email);
+	await inbox.clear();
+	const requested = await auth.signIn.magicLink({ email });
+	if (requested.error) throw new SignInFailed(email, `the auth server refused the magic link: ${requested.error.message ?? "no reason given"}`);
+	const mail = await inbox.last();
+	if (!mail.link) throw new SignInFailed(email, "its email held no link");
+	await browser.visit(mail.link);
+	const { data } = await auth.getSession();
+	if (!data) throw new SignInFailed(email, "the auth server reported no session after the link was opened");
+	return data;
+}
+/**
+* An address nobody else signs in as — what `browser.signIn()` uses when the
+* test does not care who it is.
+*
+* Unique rather than only seeded: tests in other files run at the same time,
+* against the same Mailpit and the same unique columns, and a seeded address
+* repeats wherever two tests share a name. The readable half is the seeded
+* faker's, so a failure still names somebody.
+*/
+function freshAddress() {
+	return `${faker.internet.username().toLowerCase().replace(/[^a-z0-9]/g, "")}.${randomUUID().slice(0, 8)}@example.test`;
+}
+/** `browser.signIn` finished without a session. */
+var SignInFailed = class extends Error {
+	email;
+	reason;
+	constructor(email, reason) {
+		super(`Signing ${email} in failed: ${reason}.`);
+		this.email = email;
+		this.reason = reason;
+		this.name = "SignInFailed";
+	}
+};
+/** A request reached an in-process server without a test to belong to. */
+var UnknownTestContext = class extends Error {
+	url;
+	id;
+	constructor(url, id) {
+		super(id ? `${url} was requested for test ${id}, which is not running. A request that outlives its test — an un-awaited call — lands here.` : `${url} was requested outside any test. Make the request inside a featureTest, so it reaches that test's transactions.`);
+		this.url = url;
+		this.id = id;
+		this.name = "UnknownTestContext";
+	}
+};
+/** `mailbox` was used in an app that declares no Email construct. */
+var NoInbox = class extends Error {
+	constructor() {
+		super("mailbox() reads the inbox of the app's Email construct, and none was found in featureTest's modules — or `gkm test` did not inject its <ID>_INBOX_URL.");
+		this.name = "NoInbox";
+	}
+};
+/** `db.get(name)` named no database the test is handed. */
+var UnknownDatabase = class extends Error {
+	database;
+	known;
+	constructor(database, known) {
+		super(`db.get('${database}') names no database of this app's. ` + (known.length > 0 ? `Its databases: ${known.join(", ")}. ` : "It declares no database of its own. ") + "A tenant an auth server owns is reached through that server, and a reader through the database it reads.");
+		this.database = database;
+		this.known = known;
+		this.name = "UnknownDatabase";
+	}
+};
+/** A factory keyed by a service name no database the app declares has. */
+var UnknownFactory = class extends Error {
+	factory;
+	known;
+	constructor(factory, known) {
+		super(`There is a test factory for '${factory}', and no database this app declares is called that. ` + (known.length > 0 ? `Its databases: ${known.join(", ")}. ` : "It declares no database. ") + `Name the file after the database construct: test/factories/<construct>.ts.`);
+		this.factory = factory;
+		this.known = known;
+		this.name = "UnknownFactory";
+	}
+};
+/** A published message the consumer's own schema refuses. */
+var MessageRejected = class extends Error {
+	consumer;
+	published;
+	issues;
+	constructor(consumer, published, issues) {
+		super(`${consumer} refuses '${published.type}': ${issues.map((issue) => issue.message).join("; ")}. What is published must be what the consumer's schema takes — fix the producer, or the schema.`);
+		this.consumer = consumer;
+		this.published = published;
+		this.issues = issues;
+		this.name = "MessageRejected";
+	}
+};
+/** A consumer that threw while handling what the test published. */
+var DeliveryFailed = class extends Error {
+	consumer;
+	messages;
+	cause;
+	constructor(consumer, messages, cause) {
+		super(`${consumer} failed handling ${messages.map(({ type }) => `'${type}'`).join(", ")}: ${cause?.message ?? String(cause)}. Deployed, the message would be retried; here the failure is the result.`, { cause });
+		this.consumer = consumer;
+		this.messages = messages;
+		this.cause = cause;
+		this.name = "DeliveryFailed";
+	}
+};
+/** Consumers that kept publishing to each other without settling. */
+var DeliveryDidNotSettle = class extends Error {
+	rounds;
+	channels;
+	constructor(rounds, channels) {
+		super(`Delivery did not settle after ${rounds} rounds — consumers are still publishing to ${channels.join(", ")}. A consumer that publishes to what triggers it loops forever deployed too.`);
+		this.rounds = rounds;
+		this.channels = channels;
+		this.name = "DeliveryDidNotSettle";
+	}
+};
+/** `services.get(name)` for a name no construct of the app is served by. */
+var UnknownService = class extends Error {
+	serviceName;
+	available;
+	constructor(serviceName, available) {
+		super(`The app declares no construct served as '${serviceName}'. Its services are: ${available.join(", ") || "none"}.`);
+		this.serviceName = serviceName;
+		this.available = available;
+		this.name = "UnknownService";
+	}
+};
+//#endregion
+export { DeliveryDidNotSettle, DeliveryFailed, IN_PROCESS_PEER_ADDRESS, MessageRejected, NoInbox, NoTestManifest, SignInFailed, TEST_CONTEXT_HEADER, TEST_MANIFEST_ENV, TestEndpointAdaptor, TestFunctionAdaptor, TestQueueAdaptor, TestSubscriberAdaptor, UnknownDatabase, UnknownFactory, UnknownService, UnknownTestContext, createMswHandlers, featureTest, inProcessBindings, loadTestManifest, signInWithMagicLink };
+
 //# sourceMappingURL=testing.mjs.map