@znight/openapi 0.0.0-stage → 0.1.0

package/dist/index.mjs

@@ -0,0 +1,777 @@
+import { a as BUILT_IN_CONVERTERS, c as OPENAPI_METADATA_VERSION, i as operationViews, n as buildOpenApiDocument, o as standardJsonSchemaConverter, r as openApiSection, s as valibotConverter, t as applyDocumentOptions } from "./build-DXunOzlI.mjs";
+import { n as OpenApiTokens, r as toYaml, t as OpenApi } from "./openapi-CQk5dHqc.mjs";
+import { createRequire } from "node:module";
+import { ErrorCode, ZnightError, resolveOptions } from "@znight/core";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { HttpResponse, NotFoundException } from "@znight/http";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+// src/decorators.ts
+function marker() {}
+const classMarker = marker;
+const methodMarker = marker;
+const classOrMethodMarker = marker;
+/**
+* Options of the document (one per application, optional). The class is never instantiated nor
+* registered as a provider; its JSDoc gives the title (first line) and the description (the rest).
+*
+* ```ts
+* /** Bookshelf API *\/
+* @OpenApiDocument({ servers: [{ url: '/api' }], security: [ApiKey], decisions: [{ when: Public, security: [] }] })
+* export class BookshelfApi {}
+* ```
+*/
+function OpenApiDocument(_options) {
+	return classMarker;
+}
+/**
+* Declares a security scheme, read statically by the compiler. At runtime it returns a frozen
+* `{ name, definition }`.
+*
+* ```ts
+* export const ApiKey = securityScheme('apiKey', { type: 'apiKey', in: 'header', name: 'x-api-key' })
+* ```
+*/
+function securityScheme(name, definition) {
+	return Object.freeze({
+		name,
+		definition
+	});
+}
+/** Overrides the JSDoc and the defaults of an operation. */
+function ApiOperation(_options) {
+	return methodMarker;
+}
+/** Tags of the operations (class and method tags are merged, class tags first). */
+function ApiTags(..._names) {
+	return classOrMethodMarker;
+}
+/**
+* Declares or overrides a response (repeatable). The body type comes from `T`
+* (`@ApiResponse<Book>(200)`) or from a Standard Schema in `schema`.
+*/
+function ApiResponse(_status, _options) {
+	return methodMarker;
+}
+/** The body of a route that reads it itself (`ctx.parseBody()`, `ctx.bodyStream()`). */
+function ApiBody(_options) {
+	return methodMarker;
+}
+/** A query parameter read outside the signature (`ctx.query`); its type is `T` (default `string`). */
+function ApiQuery(_name, _options) {
+	return methodMarker;
+}
+/** A header read by a guard or an interceptor (`x-tenant`); its type is `T` (default `string`). */
+function ApiHeader(_name, _options) {
+	return classOrMethodMarker;
+}
+/**
+* Security of the operations: the route's wins over the class's. Several arguments are
+* alternatives (OR); no argument means public (`security: []`).
+*/
+function ApiSecurity(..._requirements) {
+	return classOrMethodMarker;
+}
+/** The controller or route is not documented. */
+function ApiExclude() {
+	return classOrMethodMarker;
+}
+// src/ui.ts
+/** jsDelivr. */
+const CDN_ORIGIN = "https://cdn.jsdelivr.net";
+/** Pinned versions and SRI hashes of the UI assets. */
+const UI_PACKAGES = Object.freeze({
+	scalar: Object.freeze({
+		name: "@scalar/api-reference",
+		version: "1.75.1",
+		assets: Object.freeze([{
+			file: "dist/browser/standalone.js",
+			integrity: "sha384-G+2Q2i9l3PPfmYkk0b4BAIUrs7xb/DNaTL1wCYYab4c9dIKlCyiqzC0Qx3eq9Wf6",
+			kind: "script"
+		}])
+	}),
+	swagger: Object.freeze({
+		name: "swagger-ui-dist",
+		version: "5.33.1",
+		assets: Object.freeze([{
+			file: "swagger-ui.css",
+			integrity: "sha384-Ov4/wv3j2bmct8cDc5X4ngJZohVPzEmc6uDPH8WeljUxO5vtoykvMEfbu9Vh6RaW",
+			kind: "style"
+		}, {
+			file: "swagger-ui-bundle.js",
+			integrity: "sha384-ZPehFMQommnnuaZ4rpxgkgTT2DKFVp4hZC/7pLit+9Lek9T1YGSo23eHFbvNkXkw",
+			kind: "script"
+		}])
+	})
+});
+/** URL of a pinned asset on the CDN. */
+function cdnUrl(pkg, asset) {
+	return `${CDN_ORIGIN}/npm/${pkg.name}@${pkg.version}/${asset.file}`;
+}
+/**
+* Finds an installed UI package: from `@znight/openapi` (it is an optional peer), then from the
+* working directory. `undefined` when it is not installed or misses an asset. The same on Node.js and
+* Bun, whatever the exports map of the package says (`@scalar/api-reference` does not export its
+* `package.json`).
+*/
+function findLocalPackage(pkg, from = defaultBases()) {
+	for (const base of from) for (const manifest of manifestCandidates(pkg.name, base)) {
+		const found = readLocalPackage(pkg, manifest);
+		if (found !== void 0) return found;
+	}
+}
+/**
+* Where the manifest of `name` may be, seen from `base`: the `package.json` subpath when it resolves
+* (Bun always resolves it, Node.js only when the exports map exports it), then `<dir>/<name>/package.json`
+* in the `node_modules` directories the resolution searches.
+*/
+function manifestCandidates(name, base) {
+	let require;
+	try {
+		require = createRequire(base);
+	} catch {
+		return [];
+	}
+	const candidates = [];
+	try {
+		candidates.push(require.resolve(`${name}/package.json`));
+	} catch {}
+	for (const dir of require.resolve.paths(name) ?? []) candidates.push(join(dir, name, "package.json"));
+	return [...new Set(candidates)];
+}
+function readLocalPackage(pkg, manifest) {
+	try {
+		if (!existsSync(manifest)) return void 0;
+		const { name, version } = JSON.parse(readFileSync(manifest, "utf8"));
+		if (name !== pkg.name || typeof version !== "string") return void 0;
+		const dir = dirname(manifest);
+		return pkg.assets.every((asset) => existsSync(join(dir, asset.file))) ? {
+			dir,
+			version
+		} : void 0;
+	} catch {
+		return;
+	}
+}
+function defaultBases() {
+	return [import.meta.url, pathToFileURL(join(process.cwd(), "package.json")).href];
+}
+/** The HTML page of the UI and its Content-Security-Policy. */
+function renderUiPage(input) {
+	const pkg = UI_PACKAGES[input.kind];
+	const local = input.assetsBase !== void 0;
+	const tags = pkg.assets.map((asset) => {
+		const url = local ? `${input.assetsBase}/${asset.file.slice(asset.file.lastIndexOf("/") + 1)}` : cdnUrl(pkg, asset);
+		const integrity = local ? "" : ` integrity="${asset.integrity}" crossorigin="anonymous"`;
+		return asset.kind === "style" ? `<link rel="stylesheet" href="${escapeHtml(url)}"${integrity}>` : `<script src="${escapeHtml(url)}"${integrity}><\/script>`;
+	});
+	const styles = tags.filter((tag) => tag.startsWith("<link"));
+	const scripts = tags.filter((tag) => tag.startsWith("<script"));
+	const json = scriptJson(input.kind === "scalar" ? {
+		url: input.documentUrl,
+		withDefaultFonts: false,
+		telemetry: false,
+		...input.config
+	} : {
+		url: input.documentUrl,
+		dom_id: "#swagger-ui",
+		validatorUrl: null,
+		...input.config
+	});
+	const inline = input.kind === "scalar" ? `Scalar.createApiReference('#app', ${json})` : `window.ui = SwaggerUIBundle(${json})`;
+	const hash = `'sha256-${createHash("sha256").update(inline).digest("base64")}'`;
+	const container = input.kind === "scalar" ? "<div id=\"app\"></div>" : "<div id=\"swagger-ui\"></div>";
+	const html = [
+		"<!doctype html>",
+		"<html lang=\"en\">",
+		"<head>",
+		"<meta charset=\"utf-8\">",
+		"<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">",
+		`<title>${escapeHtml(input.title)}</title>`,
+		...styles,
+		"</head>",
+		"<body>",
+		container,
+		...scripts,
+		`<script>${inline}<\/script>`,
+		"</body>",
+		"</html>",
+		""
+	].join("\n");
+	const cdn = local ? "" : ` ${CDN_ORIGIN}`;
+	const connect = ["'self'", ...input.connect].join(" ");
+	return {
+		html,
+		csp: [
+			"default-src 'none'",
+			`script-src 'self'${cdn} ${hash}`,
+			`style-src 'self' 'unsafe-inline'${cdn}`,
+			"img-src 'self' data: https:",
+			`font-src 'self' data:${cdn}`,
+			`connect-src ${connect}`,
+			"frame-ancestors 'none'",
+			"base-uri 'none'",
+			"form-action 'none'"
+		].join("; ")
+	};
+}
+/** JSON safe inside an inline `<script>` (`<` escaped, line separators escaped). */
+function scriptJson(value) {
+	return JSON.stringify(value).replaceAll("<", "\\u003c").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029");
+}
+function escapeHtml(text) {
+	return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+}
+// src/plugin.ts
+const ENCODER = new TextEncoder();
+const ASSET_CACHE = "public, max-age=31536000, immutable";
+const PATH = /^\/[A-Za-z0-9\-._~!$&'()*+,;=:@/]*$/;
+/** The OpenAPI plugin: `OpenApiPlugin.configure()` (name `openapi`). */
+var OpenApiPlugin = class OpenApiPlugin {
+	name = "openapi";
+	#options;
+	#resolved;
+	#container;
+	#metadata;
+	#logger;
+	#http;
+	#served;
+	#building;
+	#ui;
+	#local;
+	#operations = [];
+	#active = false;
+	constructor(options) {
+		this.#options = options;
+	}
+	/**
+	* Creates the plugin. `options` may be a function of the container, evaluated once the container
+	* is ready: `OpenApiPlugin.configure(c => ({ enabled: c.get(ServerConfig).docs }))`.
+	*/
+	static configure(options = {}) {
+		return new OpenApiPlugin(options);
+	}
+	/** The classes of the `guards` option (instances are left out): `TestApp` creates them at boot. */
+	initRoots(_context) {
+		const options = this.#options;
+		if (options === null || typeof options !== "object") return [];
+		try {
+			const guards = options.guards;
+			return Array.isArray(guards) ? guards.filter((guard) => typeof guard === "function") : [];
+		} catch {
+			return [];
+		}
+	}
+	register(ctx) {
+		if (this.#active) throw new ZnightError(ErrorCode.DuplicateProvider, "This OpenApiPlugin is already used by another application", { hints: ["Call OpenApiPlugin.configure() once per application"] });
+		openApiSection(ctx.metadata);
+		if (ctx.getPlugin("http") === void 0) throw new ZnightError(ErrorCode.InvalidOpenApiDefinition, "OpenApiPlugin serves its routes through HttpPlugin, which is not registered", { hints: ["Add HttpPlugin.configure() to the plugins of the application"] });
+		this.#active = true;
+		this.#resolved = void 0;
+		this.#served = void 0;
+		this.#building = void 0;
+		this.#ui = void 0;
+		this.#local = void 0;
+		this.#container = ctx.container;
+		this.#metadata = ctx.metadata;
+		this.#logger = ctx.logger;
+		this.#http = ctx.getPlugin("http");
+		this.#operations = operationViews(ctx.metadata);
+		ctx.container.registerValue(OpenApiTokens.OpenApi, new OpenApiService(this));
+	}
+	httpRoutes(context) {
+		this.#container ??= context.container;
+		const options = this.#resolve();
+		if (!options.enabled) return [];
+		const common = {
+			...options.meta.length > 0 ? { meta: options.meta } : {},
+			...options.guards.length > 0 ? { guards: options.guards } : {}
+		};
+		const routes = [{
+			method: "GET",
+			path: options.path,
+			name: "document",
+			handler: (ctx) => this.#serveDocument(ctx, "json"),
+			...common
+		}];
+		if (options.yaml !== void 0) routes.push({
+			method: "GET",
+			path: options.yaml,
+			name: "yaml",
+			handler: (ctx) => this.#serveDocument(ctx, "yaml"),
+			...common
+		});
+		if (options.ui !== void 0) {
+			routes.push({
+				method: "GET",
+				path: options.uiPath,
+				name: "ui",
+				handler: (ctx) => this.#serveUi(ctx, context.prefix),
+				...common
+			});
+			if (this.#localPackage(options) !== void 0) routes.push({
+				method: "GET",
+				path: `${options.uiPath === "/" ? "" : options.uiPath}/_assets/*`,
+				name: "assets",
+				handler: (ctx) => this.#serveAsset(ctx),
+				...common
+			});
+		}
+		return routes;
+	}
+	async onBootstrap(ctx) {
+		this.#container = ctx.container;
+		const options = this.#resolve();
+		if (!options.enabled) return;
+		this.#checkServers(options);
+		if (options.lazy && options.file === void 0) return;
+		await this.served();
+	}
+	onReady(ctx) {
+		const options = this.#resolved;
+		const address = this.#http?.address;
+		if (options === void 0 || !options.enabled || options.ui === void 0 || address === void 0) return;
+		ctx.logger.info(`API reference: ${String(address.url).replace(/\/$/, "")}${this.#prefix()}${options.uiPath}`);
+	}
+	onDispose() {
+		this.#active = false;
+		this.#served = void 0;
+		this.#building = void 0;
+		this.#ui = void 0;
+		this.#resolved = void 0;
+	}
+	/** The views of the operations (no schema conversion). */
+	get operations() {
+		return this.#operations;
+	}
+	/** The served document and bodies, built once (shared promise; a failure is retried on the next call). */
+	served() {
+		if (this.#served !== void 0) return Promise.resolve(this.#served);
+		if (this.#building === void 0) this.#building = this.#build().then((served) => {
+			this.#served = served;
+			return served;
+		}, (error) => {
+			this.#building = void 0;
+			throw error;
+		});
+		return this.#building;
+	}
+	async #build() {
+		const options = this.#resolve();
+		const metadata = this.#metadata;
+		if (metadata === void 0) throw new ZnightError(ErrorCode.LifecycleFailed, "OpenApiPlugin: the document is only available once the plugin is registered");
+		let document;
+		let json;
+		if (options.file === void 0) {
+			const result = await buildOpenApiDocument(metadata, {
+				...options.build,
+				prefix: this.#prefix()
+			});
+			for (const warning of result.warnings) this.#logger?.warn(`${warning.code}: ${warning.message}`);
+			this.#logger?.debug("OpenAPI document built", {
+				operations: result.stats.operations,
+				schemas: result.stats.schemas,
+				ms: Math.round(result.stats.durationMs * 100) / 100
+			});
+			document = result.document;
+			json = result.json;
+		} else {
+			json = await readFile(options.file, "utf8");
+			document = parseDocumentFile(json, options.file);
+			const expected = openApiSection(metadata).fingerprint;
+			if (document["x-znight-fingerprint"] !== expected) this.#logger?.warn(`ZNIGHT030: ${options.file} is stale: it was not emitted from this build of the application (x-znight-fingerprint differs)`, { hints: ["Regenerate it: znight openapi (or znight build --openapi)"] });
+			const prefix = this.#prefix();
+			if (options.build.servers === void 0) this.#checkFileServers(options.file, document.servers, prefix);
+			const applied = applyDocumentOptions(json, metadata, {
+				...options.build,
+				prefix
+			});
+			if (applied !== void 0) {
+				document = applied.document;
+				json = applied.json;
+			}
+		}
+		const yaml = options.yaml === void 0 ? void 0 : body(await toYaml(document), "application/yaml");
+		return {
+			document,
+			json: body(json, "application/json; charset=utf-8"),
+			yaml
+		};
+	}
+	async #serveDocument(ctx, format) {
+		const options = this.#resolve();
+		let served;
+		try {
+			served = await this.served();
+		} catch (error) {
+			this.#logger?.error("OpenApiPlugin: the document cannot be built", { error: error instanceof Error ? error.message : String(error) });
+			throw error;
+		}
+		const selected = format === "json" ? served.json : served.yaml;
+		if (selected === void 0) throw new NotFoundException();
+		return conditional(ctx, selected, options.cacheControl);
+	}
+	async #serveUi(ctx, prefix) {
+		const options = this.#resolve();
+		if (this.#ui === void 0) {
+			const ui = options.ui;
+			if (ui === void 0) throw new NotFoundException();
+			let document;
+			try {
+				document = (await this.served()).document;
+			} catch {
+				document = this.#declared(options);
+			}
+			const local = this.#localPackage(options);
+			const base = prefix === "/" ? "" : prefix;
+			const uiPath = options.uiPath === "/" ? "" : options.uiPath;
+			const page = renderUiPage({
+				kind: ui.kind,
+				documentUrl: `${base}${options.path}`,
+				assetsBase: local === void 0 ? void 0 : `${base}${uiPath}/_assets/${ui.kind}@${local.version}`,
+				title: document?.info.title === void 0 ? "API reference" : `${document.info.title} — API reference`,
+				config: ui.config,
+				connect: serverOrigins(document?.servers ?? [])
+			});
+			const bytes = ENCODER.encode(page.html);
+			const rendered = {
+				html: bytes,
+				csp: page.csp,
+				etag: etagOf(bytes)
+			};
+			if (this.#served === void 0) return uiResponse(ctx, rendered);
+			this.#ui = rendered;
+		}
+		return uiResponse(ctx, this.#ui);
+	}
+	/** `info` and `servers` as declared (static template and runtime options), without building. */
+	#declared(options) {
+		const metadata = this.#metadata;
+		if (metadata === void 0) return void 0;
+		let template;
+		let servers;
+		try {
+			const section = openApiSection(metadata);
+			template = section.document.info;
+			servers = section.document.servers;
+		} catch {
+			return;
+		}
+		const info = {
+			...template,
+			...options.build.info
+		};
+		const resolved = options.build.servers ?? servers;
+		return resolved === void 0 ? { info } : {
+			info,
+			servers: resolved
+		};
+	}
+	#serveAsset(ctx) {
+		const options = this.#resolve();
+		const ui = options.ui;
+		const local = this.#localPackage(options);
+		if (ui === void 0 || local === void 0) throw new NotFoundException();
+		const requested = ctx.params["*"] ?? "";
+		const prefix = `${ui.kind}@${local.version}/`;
+		const asset = requested.startsWith(prefix) ? UI_PACKAGES[ui.kind].assets.find((candidate) => candidate.file.endsWith(`/${requested.slice(prefix.length)}`) || candidate.file === requested.slice(prefix.length)) : void 0;
+		if (asset === void 0) throw new NotFoundException();
+		return HttpResponse.file(asset.file, { root: local.dir }).withHeader("cache-control", ASSET_CACHE);
+	}
+	#localPackage(options) {
+		if (options.ui === void 0 || options.assets === "cdn") return void 0;
+		if (this.#local === void 0) {
+			this.#local = findLocalPackage(UI_PACKAGES[options.ui.kind]);
+			if (this.#local === void 0 && options.assets === "local") throw new ZnightError(ErrorCode.InvalidOpenApiDefinition, `OpenApiPlugin: assets: 'local' needs ${UI_PACKAGES[options.ui.kind].name}, which is not installed`, { hints: [`npm install ${UI_PACKAGES[options.ui.kind].name}`, "Or serve the pinned CDN copy: assets: 'cdn'"] });
+		}
+		return this.#local;
+	}
+	#prefix() {
+		try {
+			return this.#http?.prefix ?? "";
+		} catch {
+			return "";
+		}
+	}
+	#checkServers(options) {
+		const prefix = this.#prefix();
+		if (prefix === "" || options.file !== void 0 && options.build.servers === void 0) return;
+		const metadata = this.#metadata;
+		const declared = options.build.servers ?? (metadata === void 0 ? void 0 : openApiSection(metadata).document.servers);
+		this.#checkPrefix(declared ?? [], prefix);
+	}
+	/**
+	* The servers of a prebuilt file against the HTTP prefix (the file may be emitted without the
+	* prefix, or with servers of another deployment): ZNIGHT030 when it declares no servers, when a
+	* relative server does not end with the prefix, or when no server ends with it (`servers: []`,
+	* absolute servers of another path). Runtime `servers` replace the file's and skip this check.
+	*/
+	#checkFileServers(file, servers, prefix) {
+		if (prefix === "" || prefix === "/") return;
+		if (servers === void 0) {
+			this.#logger?.warn(`ZNIGHT030: ${file} declares no servers, but the HTTP prefix is "${prefix}": it is served with the server "${prefix}", and clients generated from the file would call the wrong paths`, { hints: [`Emit it with the prefix: znight openapi --prefix ${prefix}, znight build --openapi --openapi-prefix ${prefix}, or openapi({ prefix: '${prefix}' }) in vite.config`] });
+			return;
+		}
+		const declared = Array.isArray(servers) ? servers.filter((server) => typeof server?.url === "string") : [];
+		if (this.#checkPrefix(declared, prefix) > 0) return;
+		if (declared.some((server) => reflectsPrefix(server.url, prefix))) return;
+		const listed = declared.length === 0 ? "[]" : declared.map((server) => `"${server.url}"`).join(", ");
+		this.#logger?.warn(`ZNIGHT030: ${file} declares no server ending with the HTTP prefix "${prefix}" (servers: ${listed}): clients generated from the file would call the wrong paths`, { hints: [`Declare a server ending with "${prefix}" (@OpenApiDocument({ servers: [{ url: '${prefix}' }] })) and emit the file again`, "Behind a gateway that rewrites the paths, replace the servers at runtime: OpenApiPlugin.configure({ servers })"] });
+	}
+	/** Warns about each relative server that does not end with the HTTP prefix; returns how many. */
+	#checkPrefix(servers, prefix) {
+		let mismatched = 0;
+		for (const server of servers) if (server.url.startsWith("/") && !server.url.replace(/\/$/, "").endsWith(prefix)) {
+			mismatched++;
+			this.#logger?.warn(`ZNIGHT030: the OpenAPI server "${server.url}" does not end with the HTTP prefix "${prefix}": generated clients would call the wrong paths`);
+		}
+		return mismatched;
+	}
+	#resolve() {
+		if (this.#resolved !== void 0) return this.#resolved;
+		let raw;
+		if (typeof this.#options === "function") {
+			const container = this.#container;
+			if (container === void 0) throw new ZnightError(ErrorCode.LifecycleFailed, "OpenApiPlugin: its options are a function of the container, which is not ready");
+			raw = resolveOptions(this.#options, container);
+		} else raw = this.#options;
+		this.#resolved = resolvePluginOptions(raw);
+		return this.#resolved;
+	}
+};
+/** Implementation of the {@link OpenApi} external. */
+var OpenApiService = class extends OpenApi {
+	#plugin;
+	constructor(plugin) {
+		super();
+		this.#plugin = plugin;
+	}
+	get operations() {
+		return this.#plugin.operations;
+	}
+	async document() {
+		return (await this.#plugin.served()).document;
+	}
+	async json() {
+		return new TextDecoder().decode((await this.#plugin.served()).json.bytes);
+	}
+	async yaml() {
+		const served = await this.#plugin.served();
+		return served.yaml === void 0 ? toYaml(served.document) : new TextDecoder().decode(served.yaml.bytes);
+	}
+};
+/** The UI page: HTML, its Content-Security-Policy, revalidated with its ETag. */
+function uiResponse(ctx, page) {
+	return conditional(ctx, {
+		bytes: page.html,
+		etag: page.etag,
+		contentType: "text/html; charset=utf-8"
+	}, "no-cache").withHeader("content-security-policy", page.csp).withHeader("x-content-type-options", "nosniff");
+}
+function body(text, contentType) {
+	const bytes = ENCODER.encode(text);
+	return {
+		bytes,
+		etag: etagOf(bytes),
+		contentType
+	};
+}
+/** Strong ETag: base64url SHA-256, 27 characters. */
+function etagOf(bytes) {
+	return `"${createHash("sha256").update(bytes).digest("base64url").slice(0, 27)}"`;
+}
+function conditional(ctx, served, cacheControl) {
+	const headers = {
+		etag: served.etag,
+		"cache-control": cacheControl
+	};
+	if (matches(ctx.header("if-none-match"), served.etag)) return new HttpResponse(void 0, {
+		status: 304,
+		headers
+	});
+	return new HttpResponse(served.bytes, {
+		status: 200,
+		headers: {
+			...headers,
+			"content-type": served.contentType
+		}
+	});
+}
+function matches(header, etag) {
+	if (header === void 0) return false;
+	return header.split(",").some((candidate) => {
+		const tag = candidate.trim();
+		return tag === "*" || tag === etag || tag === `W/${etag}`;
+	});
+}
+/** Origins of the absolute server URLs (`connect-src` of the UI). */
+function serverOrigins(servers) {
+	const origins = /* @__PURE__ */ new Set();
+	for (const server of servers) try {
+		const url = new URL(server.url);
+		if (url.protocol === "http:" || url.protocol === "https:") origins.add(url.origin);
+	} catch {}
+	return [...origins].sort();
+}
+function parseDocumentFile(text, file) {
+	let document;
+	try {
+		document = JSON.parse(text);
+	} catch (error) {
+		throw new ZnightError(ErrorCode.InvalidOpenApiDefinition, `OpenApiPlugin: ${file} is not valid JSON`, { cause: error });
+	}
+	const version = document?.openapi;
+	if (typeof version !== "string" || !version.startsWith("3.1.")) throw new ZnightError(ErrorCode.InvalidOpenApiDefinition, `OpenApiPlugin: ${file} is not an OpenAPI 3.1 document`, { hints: ["Emit it with znight openapi (or znight build --openapi)"] });
+	return deepFreeze(document);
+}
+function deepFreeze(value) {
+	if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+		Object.freeze(value);
+		for (const item of Object.values(value)) deepFreeze(item);
+	}
+	return value;
+}
+function invalid(option, expected, value) {
+	let shown;
+	try {
+		shown = typeof value === "function" ? "a function" : JSON.stringify(value) ?? String(value);
+	} catch {
+		shown = typeof value;
+	}
+	return new ZnightError(ErrorCode.InvalidOpenApiDefinition, `Invalid OpenApiPlugin option "${option}": expected ${expected}, received ${shown}`);
+}
+const OPTION_KEYS = /* @__PURE__ */ new Set([
+	"enabled",
+	"path",
+	"yaml",
+	"ui",
+	"uiPath",
+	"assets",
+	"document",
+	"build",
+	"info",
+	"servers",
+	"filter",
+	"transform",
+	"converters",
+	"unrepresentable",
+	"meta",
+	"guards",
+	"cacheControl"
+]);
+/** Checks and defaults the options (ZNIGHT030). */
+function resolvePluginOptions(options) {
+	if (options === null || typeof options !== "object") throw invalid("options", "an object", options);
+	for (const key of Object.keys(options)) if (!OPTION_KEYS.has(key)) throw invalid(key, `one of ${[...OPTION_KEYS].join(", ")} (unknown option)`, key);
+	const enabled = options.enabled ?? true;
+	if (typeof enabled !== "boolean") throw invalid("enabled", "true or false", enabled);
+	const route = (key, fallback) => {
+		const value = options[key] ?? fallback;
+		if (typeof value !== "string" || !PATH.test(value) || value.includes("//") || value.length > 1 && value.endsWith("/")) throw invalid(key, "a static path starting with '/' ('/openapi.json')", value);
+		return value;
+	};
+	const path = route("path", "/openapi.json");
+	const uiPath = route("uiPath", "/docs");
+	const yamlOption = options.yaml ?? false;
+	if (yamlOption !== false && (typeof yamlOption !== "string" || !PATH.test(yamlOption))) throw invalid("yaml", "false or a path ('/openapi.yaml')", yamlOption);
+	const yaml = yamlOption === false ? void 0 : yamlOption;
+	const uiOption = options.ui ?? "scalar";
+	let ui;
+	if (uiOption === "scalar" || uiOption === "swagger") ui = {
+		kind: uiOption,
+		config: {}
+	};
+	else if (uiOption === false) ui = void 0;
+	else if (typeof uiOption === "object" && uiOption !== null && Object.keys(uiOption).length === 1) {
+		const kind = Object.keys(uiOption)[0];
+		const config = uiOption[kind];
+		if (kind !== "scalar" && kind !== "swagger" || typeof config !== "object" || config === null || !isJson(config)) throw invalid("ui", "'scalar', 'swagger', false, { scalar: config } or { swagger: config } (JSON config)", uiOption);
+		ui = {
+			kind,
+			config
+		};
+	} else throw invalid("ui", "'scalar', 'swagger', false, { scalar: config } or { swagger: config }", uiOption);
+	const used = [
+		path,
+		...yaml === void 0 ? [] : [yaml],
+		...ui === void 0 ? [] : [uiPath]
+	];
+	if (new Set(used).size !== used.length) throw invalid("path", "distinct paths for the document, the YAML and the UI", used);
+	const assets = options.assets ?? "auto";
+	if (assets !== "auto" && assets !== "local" && assets !== "cdn") throw invalid("assets", "'auto', 'local' or 'cdn'", assets);
+	const documentOption = options.document ?? "build";
+	let file;
+	if (documentOption !== "build") {
+		const target = documentOption?.file;
+		if (typeof target === "string" && target !== "") file = target;
+		else if (target instanceof URL) file = fileURLToPath(target);
+		else throw invalid("document", "'build' or { file: string | URL }", documentOption);
+	}
+	const build = options.build ?? "boot";
+	if (build !== "boot" && build !== "first-request") throw invalid("build", "'boot' or 'first-request'", build);
+	for (const key of ["filter", "transform"]) if (options[key] !== void 0 && typeof options[key] !== "function") throw invalid(key, "a function", options[key]);
+	if (options.converters !== void 0) {
+		if (!Array.isArray(options.converters) || options.converters.some((converter) => typeof converter?.convert !== "function")) throw invalid("converters", "an array of { name, convert(schema, context) }", options.converters);
+	}
+	if (options.unrepresentable !== void 0 && options.unrepresentable !== "error" && options.unrepresentable !== "warn") throw invalid("unrepresentable", "'error' or 'warn'", options.unrepresentable);
+	if (options.info !== void 0 && (typeof options.info !== "object" || options.info === null)) throw invalid("info", "an object", options.info);
+	if (options.servers !== void 0 && (!Array.isArray(options.servers) || options.servers.some((server) => typeof server?.url !== "string"))) throw invalid("servers", "an array of { url, description? }", options.servers);
+	const meta = options.meta ?? [];
+	if (!Array.isArray(meta)) throw invalid("meta", "an array of route metadata entries (Public.meta())", meta);
+	const guards = options.guards ?? [];
+	if (!Array.isArray(guards)) throw invalid("guards", "an array of guards (classes or instances)", guards);
+	const cacheControl = options.cacheControl ?? "no-cache";
+	if (typeof cacheControl !== "string" || cacheControl === "") throw invalid("cacheControl", "a cache-control value", cacheControl);
+	const buildOptions = {
+		...options.info === void 0 ? {} : { info: options.info },
+		...options.servers === void 0 ? {} : { servers: options.servers },
+		...options.filter === void 0 ? {} : { filter: options.filter },
+		...options.transform === void 0 ? {} : { transform: options.transform },
+		...options.converters === void 0 ? {} : { converters: options.converters },
+		...options.unrepresentable === void 0 ? {} : { unrepresentable: options.unrepresentable }
+	};
+	return {
+		enabled,
+		path,
+		yaml,
+		ui,
+		uiPath,
+		assets,
+		file,
+		lazy: build === "first-request",
+		build: buildOptions,
+		meta,
+		guards,
+		cacheControl
+	};
+}
+/**
+* Whether a server URL ends with the HTTP prefix: a relative URL (`/api`, `/v2/api/`), or the path
+* of an absolute one (`https://api.example.com/api`). A URL with variables (`{basePath}`) or that
+* cannot be parsed is not judged.
+*/
+function reflectsPrefix(url, prefix) {
+	if (url.includes("{")) return true;
+	let path = url;
+	if (/^[a-z][a-z\d+.-]*:/i.test(url)) try {
+		path = new URL(url).pathname;
+	} catch {
+		return true;
+	}
+	return path.replace(/[?#].*$/, "").replace(/\/+$/, "").endsWith(prefix.replace(/\/+$/, ""));
+}
+function isJson(value) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (Array.isArray(value)) return value.every(isJson);
+	if (typeof value === "object") {
+		const prototype = Object.getPrototypeOf(value);
+		return (prototype === Object.prototype || prototype === null) && Object.values(value).every(isJson);
+	}
+	return false;
+}
+export { ApiBody, ApiExclude, ApiHeader, ApiOperation, ApiQuery, ApiResponse, ApiSecurity, ApiTags, BUILT_IN_CONVERTERS, CDN_ORIGIN, OPENAPI_METADATA_VERSION, OpenApi, OpenApiDocument, OpenApiPlugin, OpenApiTokens, UI_PACKAGES, buildOpenApiDocument, securityScheme, standardJsonSchemaConverter, valibotConverter };
+
+//# sourceMappingURL=index.mjs.map