@jaredwray/mockhttp 1.9.0 → 2.1.0

package/dist/index.mjs

@@ -1,6 +1,8 @@
 import process$1 from "node:process";
+import { existsSync, readFileSync } from "node:fs";
 import * as fsPromises from "node:fs/promises";
 import path, { join } from "node:path";
+import { fileURLToPath } from "node:url";
 import fastifyCookie from "@fastify/cookie";
 import fastifyHelmet from "@fastify/helmet";
 import fastifyRateLimit from "@fastify/rate-limit";
@@ -12,10 +14,8 @@ import { Hookified } from "hookified";
 import * as crypto$1 from "node:crypto";
 import crypto, { randomBytes, randomInt, randomUUID, timingSafeEqual } from "node:crypto";
 import { Buffer as Buffer$1 } from "node:buffer";
-import { readFileSync } from "node:fs";
 import { brotliCompressSync, deflateSync, gzipSync } from "node:zlib";
 import { escape } from "html-escaper";
-import { fastifySwaggerUi } from "@fastify/swagger-ui";
 //#region src/bin-store.ts
 /**
 * In-memory implementation of {@link BinStore} backed by two Maps. State is
@@ -188,7 +188,7 @@ var BinManager = class {
 		this._cleanupTimer = setInterval(() => {
 			this._store.cleanupExpired(Date.now());
 		}, this._cleanupIntervalMs);
-		this._cleanupTimer.unref();
+		this._cleanupTimer.unref?.();
 	}
 	/** Stop the periodic cleanup. Idempotent. */
 	stop() {
@@ -2043,6 +2043,18 @@ const putRoute = (fastify) => {
 	}));
 };
 //#endregion
+//#region src/public-files.ts
+const defaultPublicPath$1 = join(process.cwd(), "public");
+const defaultReader = (file) => readFileSync(join(defaultPublicPath$1, file));
+let reader = defaultReader;
+/**
+* Read a file from the package `public/` directory, or from the active reader.
+*/
+async function readPublicFile(file) {
+	const bytes = await reader(file);
+	return Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+}
+//#endregion
 //#region src/routes/images/index.ts
 const imageSchema = {
 	description: "Returns an image based on Accept header (supports jpeg, png, svg, webp)",
@@ -2096,8 +2108,19 @@ const webpSchema = {
 		format: "binary"
 	} }
 };
+async function sendImage(reply, file, contentType) {
+	try {
+		const imageBuffer = await readPublicFile(file);
+		reply.type(contentType);
+		return imageBuffer;
+	} catch (error) {
+		/* v8 ignore next -- @preserve */
+		reply.code(500);
+		/* v8 ignore next -- @preserve */
+		return { error: `${error}` };
+	}
+}
 const imageRoutes = (fastify) => {
-	const publicPath = join(process.cwd(), "public");
 	fastify.get("/image", { schema: imageSchema }, async (request, reply) => {
 		const accept = request.headers.accept || "";
 		let file = "logo.png";
@@ -2115,152 +2138,19 @@ const imageRoutes = (fastify) => {
 			file = "logo.png";
 			contentType = "image/png";
 		}
-		try {
-			const imagePath = join(publicPath, file);
-			const imageBuffer = readFileSync(imagePath);
-			reply.type(contentType);
-			return imageBuffer;
-		} catch (error) {
-			/* v8 ignore next -- @preserve */
-			reply.code(500);
-			/* v8 ignore next -- @preserve */
-			return { error: `${error}` };
-		}
+		return sendImage(reply, file, contentType);
 	});
 	fastify.get("/image/jpeg", { schema: jpegSchema }, async (_request, reply) => {
-		try {
-			const imagePath = join(publicPath, "logo.jpg");
-			const imageBuffer = readFileSync(imagePath);
-			reply.type("image/jpeg");
-			return imageBuffer;
-		} catch (error) {
-			/* v8 ignore next -- @preserve */
-			reply.code(500);
-			/* v8 ignore next -- @preserve */
-			return { error: `${error}` };
-		}
+		return sendImage(reply, "logo.jpg", "image/jpeg");
 	});
 	fastify.get("/image/png", { schema: pngSchema }, async (_request, reply) => {
-		try {
-			const imagePath = join(publicPath, "logo.png");
-			const imageBuffer = readFileSync(imagePath);
-			reply.type("image/png");
-			return imageBuffer;
-		} catch (error) {
-			/* v8 ignore next -- @preserve */
-			reply.code(500);
-			/* v8 ignore next -- @preserve */
-			return { error: `${error}` };
-		}
+		return sendImage(reply, "logo.png", "image/png");
 	});
 	fastify.get("/image/svg", { schema: svgSchema }, async (_request, reply) => {
-		try {
-			const imagePath = join(publicPath, "logo.svg");
-			const imageBuffer = readFileSync(imagePath);
-			reply.type("image/svg+xml");
-			return imageBuffer;
-		} catch (error) {
-			/* v8 ignore next -- @preserve */
-			reply.code(500);
-			/* v8 ignore next -- @preserve */
-			return { error: `${error}` };
-		}
+		return sendImage(reply, "logo.svg", "image/svg+xml");
 	});
 	fastify.get("/image/webp", { schema: webpSchema }, async (_request, reply) => {
-		try {
-			const imagePath = join(publicPath, "logo.webp");
-			const imageBuffer = readFileSync(imagePath);
-			reply.type("image/webp");
-			return imageBuffer;
-		} catch (error) {
-			/* v8 ignore next -- @preserve */
-			reply.code(500);
-			/* v8 ignore next -- @preserve */
-			return { error: `${error}` };
-		}
-	});
-};
-//#endregion
-//#region src/routes/index.ts
-const indexRoute = (fastify) => {
-	fastify.get("/", { schema: { hide: true } }, async (_request, reply) => {
-		await reply.type("text/html").send(`
-	<!doctype html>
-<html>
-  <head>
-    <title>{ mockhttp }</title>
-    <meta charset="utf-8" />
-    <meta
-      name="viewport"
-      content="width=device-width, initial-scale=1" />
-    <meta name="description" content="MockHttp - A powerful HTTP mock server and httpbin replacement for API testing. Built with Fastify, TypeScript, and Docker support." />
-    <meta name="keywords" content="mock, http, httpbin, testing, api, fastify, docker, typescript, rest, mock-server, api-testing, http-testing, httpbin-alternative" />
-    <meta property="og:title" content="MockHttp - HTTP Mock Server" />
-    <meta property="og:description" content="A powerful HTTP mock server and httpbin replacement for API testing. Built with Fastify, TypeScript, and Docker support." />
-    <meta property="og:type" content="website" />
-    <meta property="og:url" content="https://mockhttp.org" />
-    <meta property="og:image" content="https://mockhttp.org/logo.png" />
-    <meta property="og:site_name" content="MockHttp" />
-    <meta name="twitter:card" content="summary" />
-    <meta name="twitter:title" content="MockHttp - HTTP Mock Server" />
-    <meta name="twitter:description" content="A powerful HTTP mock server and httpbin replacement for API testing." />
-    <meta name="twitter:image" content="https://mockhttp.org/logo.png" />
-      <style>
-      :root {
-  --scalar-custom-header-height: 70px;
-}
-.custom-header {
-  height: var(--scalar-custom-header-height);
-  background-color: var(--scalar-background-1);
-  box-shadow: inset 0 -1px 0 var(--scalar-border-color);
-  color: var(--scalar-color-1);
-  font-size: var(--scalar-font-size-2);
-  padding: 0 18px;
-  position: sticky;
-  justify-content: space-between;
-  top: 0;
-  z-index: 100;
-}
-.custom-header,
-.custom-header nav {
-  display: flex;
-  align-items: center;
-  gap: 18px;
-}
-
-.custom-header img {
-  height: var(--scalar-custom-header-height);
-  object-fit: contain;
-}
-
-.custom-header a:hover {
-  color: var(--scalar-color-2);
-}
-
-.github-corner {
-  fill: var(--scalar-border-color) !important;
-}
-
-      </style>
-  </head>
-  <body>
-  <header class="custom-header scalar-app">
-    <a href="/"><img src="/logo.svg" alt="{ mockhttp }" /></a>
-    <a href="https://github.com/jaredwray/mockhttp" class="github-corner" aria-label="View source on GitHub">
-      <svg width="70" height="70" viewBox="0 0 250 250" style="color:#fff; position: absolute; top: 0; border: 0; right: 0;" aria-hidden="true">
-      <path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path>
-      <path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path>
-      <path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path></svg></a><style>.github-corner:hover .octo-arm{animation:octocat-wave 560ms ease-in-out}@keyframes octocat-wave{0%,100%{transform:rotate(0)}20%,60%{transform:rotate(-25deg)}40%,80%{transform:rotate(10deg)}}@media (max-width:500px){.github-corner:hover .octo-arm{animation:none}.github-corner .octo-arm{animation:octocat-wave 560ms ease-in-out}}</style>
-  </header>
-
-    <script
-      id="api-reference"
-      data-url="/docs/json"><\/script>
-
-    <script src="/scalar/browser/standalone.js"><\/script>
-  </body>
-</html>
-`);
+		return sendImage(reply, "logo.webp", "image/webp");
 	});
 };
 //#endregion
@@ -3182,29 +3072,6 @@ const responseHeadersRoutes = (fastify) => {
 	});
 };
 //#endregion
-//#region src/routes/sitemap.ts
-const sitemapRoute = (fastify) => {
-	fastify.get("/sitemap.xml", { schema: { hide: true } }, async (_request, reply) => {
-		try {
-			const host = _request.headers.host ?? "mockhttp.org";
-			const xml = `<?xml version="1.0" encoding="UTF-8"?>
-                            <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-                                <url>
-                                    <loc>${_request.headers["x-forwarded-proto"]?.includes("https") ? "https" : "http"}://${host}/</loc>
-                                    <changefreq>monthly</changefreq>
-                                    <priority>1.0</priority>
-                                </url>
-                        </urlset>`;
-			await reply.type("text/xml").send(xml);
-		} catch (error) {
-			/* v8 ignore next -- @preserve */
-			fastify.log.error(error);
-			/* v8 ignore next -- @preserve */
-			await reply.status(500).send({ error: "Internal Server Error" });
-		}
-	});
-};
-//#endregion
 //#region src/routes/status-codes/index.ts
 const statusCodes = [
 	{
@@ -3487,47 +3354,30 @@ const statusCodeRoute = (fastify) => {
 	fastify.patch("/status/:code?", { schema: statusSchema }, handler);
 	fastify.delete("/status/:code?", { schema: statusSchema }, handler);
 };
-const fastifySwaggerConfig = { openapi: {
-	info: {
-		title: "Mock HTTP API",
-		description: `
+const fastifySwaggerConfig = { openapi: { info: {
+	title: "Mock HTTP API",
+	description: `
 A simple HTTP server that can be used to mock HTTP responses for testing purposes. Inspired by [httpbin](https://httpbin.org/) and built using \`nodejs\` and \`fastify\` with the idea of running it via https://mockhttp.org, via docker \`jaredwray/mockhttp\`, or nodejs \`npm install @jaredwray/mockhttp\`.
 
 * [GitHub Repository](https://github.com/jaredwray/mockhttp)
 * [Docker Image](https://hub.docker.com/r/jaredwray/mockhttp)
 * [NPM Package](https://www.npmjs.com/package/@jaredwray/mockhttp)
 
-# About mockhttp.org 
+# About mockhttp.org
 
-[mockhttp.org](https://mockhttp.org) is a free service that runs this codebase and allows you to use it for testing purposes. It is a simple way to mock HTTP responses for testing purposes. Ran via [Cloudflare](https://cloudflare.com) and [Google Cloud Run](https://cloud.google.com/run/) across 7 regions globally and can do millions of requests per second.
+[mockhttp.org](https://mockhttp.org) is a free hosted instance of this codebase for testing. It runs on a Cloudflare Worker (no containers): documentation is served from Workers Assets, and mock APIs such as \`/get\` and \`/post\` run in the Worker. The service is globally available and rate-limited (1000 requests per minute per IP) to prevent abuse.
 `,
-		version: "1.9.0"
-	},
-	consumes: ["application/json"],
-	produces: ["application/json"]
-} };
-const registerSwaggerUi = async (fastify) => {
-	await fastify.register(fastifySwaggerUi, {
-		routePrefix: "/docs",
-		uiConfig: {
-			docExpansion: "none",
-			deepLinking: false
-		},
-		uiHooks: {
-			/* v8 ignore next -- @preserve */
-			onRequest(_request, _reply, next) {
-				next();
-			},
-			/* v8 ignore next -- @preserve */
-			preHandler(_request, _reply, next) {
-				next();
-			}
-		},
-		staticCSP: true,
-		/* v8 ignore next -- @preserve */
-		transformSpecification: (swaggerObject, _request, _reply) => swaggerObject,
-		transformSpecificationClone: true
-	});
+	version: "2.1.0"
+} } };
+const withLocalServer = (spec) => {
+	spec.servers = [{
+		url: "",
+		description: "This instance"
+	}];
+	return spec;
+};
+const registerOpenApiJson = async (fastify) => {
+	fastify.get("/openapi.json", { schema: { hide: true } }, async () => withLocalServer(fastify.swagger()));
 };
 //#endregion
 //#region src/tap-manager.ts
@@ -3630,13 +3480,29 @@ var TapManager = class {
 };
 //#endregion
 //#region src/mock-http.ts
+function resolvePackageRoot(metaUrl) {
+	if (!metaUrl) return process.cwd();
+	return path.resolve(path.dirname(fileURLToPath(metaUrl)), "..");
+}
+const packageRoot = resolvePackageRoot(import.meta.url);
+const defaultSiteDistPath = path.join(packageRoot, "site", "dist");
+const defaultPublicPath = path.join(packageRoot, "public");
+const requestOrigin = (request) => {
+	const host = request.headers.host || "mockhttp.org";
+	const forwarded = request.headers["x-forwarded-proto"];
+	return `${((Array.isArray(forwarded) ? forwarded[0] : forwarded) ?? request.protocol).includes("https") ? "https" : "http"}://${host}`;
+};
 var MockHttp = class extends Hookified {
 	_port = 3e3;
 	_host = "0.0.0.0";
 	_autoDetectPort = true;
 	_helmet = true;
+	_staticFiles = true;
 	_apiDocs = true;
+	_siteDistPath = defaultSiteDistPath;
 	_logging = true;
+	_pluginTimeout;
+	_startBins = true;
 	_httpBin = {
 		httpMethods: true,
 		redirects: true,
@@ -3660,21 +3526,26 @@ var MockHttp = class extends Hookified {
 	_http1 = true;
 	_https;
 	_httpsCredentials;
-	_server = Fastify();
+	_server;
 	_taps = new TapManager();
 	_bins = new BinManager();
 	constructor(options) {
 		super(options?.hookOptions);
 		if (options?.port) this._port = options.port;
 		if (options?.host) this._host = options.host;
+		if (options?.autoDetectPort !== void 0) this._autoDetectPort = options.autoDetectPort;
 		if (options?.helmet !== void 0) this._helmet = options.helmet;
+		if (options?.staticFiles !== void 0) this._staticFiles = options.staticFiles;
 		if (options?.apiDocs !== void 0) this._apiDocs = options.apiDocs;
+		if (options?.siteDistPath !== void 0) this._siteDistPath = path.resolve(options.siteDistPath);
 		if (options?.httpBin !== void 0) this._httpBin = options.httpBin;
 		if (options?.rateLimit !== void 0) {
 			if (options.rateLimit === false) this._rateLimit = void 0;
 			else this._rateLimit = options.rateLimit;
 		}
 		if (options?.logging !== void 0) this._logging = options.logging;
+		if (options?.pluginTimeout !== void 0) this._pluginTimeout = options.pluginTimeout;
+		if (options?.startBins !== void 0) this._startBins = options.startBins;
 		if (options?.http2 !== void 0) this._http2 = options.http2;
 		if (options?.http1 !== void 0) this._http1 = options.http1;
 		if (options?.https !== void 0) {
@@ -3740,20 +3611,48 @@ var MockHttp = class extends Hookified {
 		this._helmet = helmet;
 	}
 	/**
-	* Whether to use Swagger for API documentation. Defaults to true.
+	* Whether to serve files from the package `public/` directory. Defaults to true.
+	* @default true
+	*/
+	get staticFiles() {
+		return this._staticFiles;
+	}
+	/**
+	* Whether to serve files from the package `public/` directory. Defaults to true.
+	* @default true
+	*/
+	set staticFiles(staticFiles) {
+		this._staticFiles = staticFiles;
+	}
+	/**
+	* Whether to serve the Docula documentation site and OpenAPI spec. Defaults to true.
 	* @default true
 	*/
 	get apiDocs() {
 		return this._apiDocs;
 	}
 	/**
-	* Whether to use Swagger for API documentation. Defaults to true.
+	* Whether to serve the Docula documentation site and OpenAPI spec. Defaults to true.
 	* @default true
 	*/
 	set apiDocs(apiDocs) {
 		this._apiDocs = apiDocs;
 	}
 	/**
+	* Path to the built Docula site served when `apiDocs` is enabled.
+	* @default the package `site/dist` directory
+	*/
+	get siteDistPath() {
+		return this._siteDistPath;
+	}
+	/**
+	* Path to the built Docula site served when `apiDocs` is enabled.
+	* @default the package `site/dist` directory
+	*/
+	set siteDistPath(siteDistPath) {
+		this._siteDistPath = path.resolve(siteDistPath);
+	}
+	/**
 	* Whether to enable logging. Defaults to true.
 	* @default true
 	*/
@@ -3768,6 +3667,32 @@ var MockHttp = class extends Hookified {
 		this._logging = logging;
 	}
 	/**
+	* Fastify plugin boot timeout in milliseconds. `undefined` uses Fastify's default.
+	*/
+	get pluginTimeout() {
+		return this._pluginTimeout;
+	}
+	/**
+	* Fastify plugin boot timeout in milliseconds. `undefined` uses Fastify's default.
+	*/
+	set pluginTimeout(pluginTimeout) {
+		this._pluginTimeout = pluginTimeout;
+	}
+	/**
+	* Whether to start the request-bin cleanup timer during `initialize()`.
+	* @default true
+	*/
+	get startBins() {
+		return this._startBins;
+	}
+	/**
+	* Whether to start the request-bin cleanup timer during `initialize()`.
+	* @default true
+	*/
+	set startBins(startBins) {
+		this._startBins = startBins;
+	}
+	/**
 	* HTTPS configuration. Set to true to auto-generate a self-signed certificate,
 	* or provide an HttpsOptions object with cert/key or auto-generation options.
 	*/
@@ -3851,6 +3776,7 @@ var MockHttp = class extends Hookified {
 	* The Fastify server instance.
 	*/
 	get server() {
+		this._server ??= Fastify();
 		return this._server;
 	}
 	/**
@@ -3884,15 +3810,17 @@ var MockHttp = class extends Hookified {
 		this._bins = bins;
 	}
 	/**
-	* Start the Fastify server. If the server is already running, it will be closed and restarted.
+	* Register plugins and routes without listening. Use `inject()` against
+	* `server`, or call `start()` to bind a port.
 	*/
-	async start() {
+	async initialize() {
 		this._httpsCredentials = void 0;
 		if (this._https) this._httpsCredentials = await this.resolveHttpsCredentials(this._https);
 		try {
 			/* v8 ignore next -- @preserve */
-			if (this._server) await this._server.close();
+			if (this._server?.server.listening) await this._server.close();
 			const fastifyOptions = { ...getFastifyConfig(this._logging) };
+			if (this._pluginTimeout !== void 0) fastifyOptions.pluginTimeout = this._pluginTimeout;
 			if (this._http2) fastifyOptions.http2 = true;
 			if (this._httpsCredentials) {
 				const httpsOptions = {
@@ -3912,22 +3840,14 @@ var MockHttp = class extends Hookified {
 					return reply.send(response);
 				}
 			});
-			await this._server.register(fastifyStatic, {
-				root: path.resolve("./node_modules/@scalar/api-reference/dist"),
-				prefix: "/scalar"
-			});
-			await this.server.register(fastifyStatic, {
-				root: path.resolve("./public"),
-				decorateReply: false
+			if (this._staticFiles) await this.server.register(fastifyStatic, {
+				root: defaultPublicPath,
+				wildcard: false,
+				index: false
 			});
-			await this._server.register(sitemapRoute);
 			if (this._helmet) await this._server.register(fastifyHelmet, { contentSecurityPolicy: { directives: {
 				defaultSrc: ["'self'"],
-				scriptSrc: [
-					"'self'",
-					"'unsafe-inline'",
-					"'wasm-unsafe-eval'"
-				],
+				scriptSrc: ["'self'", "'unsafe-inline'"],
 				styleSrc: ["'self'", "'unsafe-inline'"],
 				imgSrc: [
 					"'self'",
@@ -3935,13 +3855,13 @@ var MockHttp = class extends Hookified {
 					"https:"
 				],
 				fontSrc: ["'self'", "data:"],
-				connectSrc: ["'self'"],
+				connectSrc: ["'self'", "https:"],
 				frameSrc: ["'self'"],
 				objectSrc: ["'none'"],
 				upgradeInsecureRequests: []
 			} } });
 			if (this._rateLimit) await this._server.register(fastifyRateLimit, this._rateLimit);
-			if (this._apiDocs) await this.registerApiDocs();
+			if (this._apiDocs) await this.registerSwagger();
 			const { httpMethods, redirects, requestInspection, responseInspection, responseFormats, statusCodes, cookies, anything, auth, images, dynamicData, bins } = this._httpBin;
 			if (httpMethods) await this.registerHttpMethods();
 			if (statusCodes) await this.registerStatusCodeRoutes();
@@ -3956,20 +3876,32 @@ var MockHttp = class extends Hookified {
 			if (dynamicData) await this.registerDynamicDataRoutes();
 			if (bins) {
 				await this.registerBinRoutes();
-				this._bins.start();
+				if (this._startBins) this._bins.start();
 			}
+			if (this._apiDocs) await this.registerSite();
+		} catch (error) {
+			/* v8 ignore next -- @preserve */
+			this.server.log.error(error);
+		}
+	}
+	/**
+	* Start the Fastify server. If the server is already running, it will be closed and restarted.
+	*/
+	async start() {
+		await this.initialize();
+		try {
 			if (this._autoDetectPort) {
 				const originalPort = this._port;
 				this._port = await this.detectPort();
-				if (originalPort !== this._port) this._server.log.info(`Port ${originalPort} is in use, detected next available port: ${this._port}`);
+				if (originalPort !== this._port) this.server.log.info(`Port ${originalPort} is in use, detected next available port: ${this._port}`);
 			}
-			await this._server.listen({
+			await this.server.listen({
 				port: this._port,
 				host: this._host
 			});
 		} catch (error) {
 			/* v8 ignore next -- @preserve */
-			this._server.log.error(error);
+			this.server.log.error(error);
 		}
 	}
 	/**
@@ -3977,7 +3909,7 @@ var MockHttp = class extends Hookified {
 	*/
 	async close() {
 		this._bins.stop();
-		await this._server.close();
+		if (this._server) await this._server.close();
 	}
 	/**
 	* Detect the next available port to run on.
@@ -3988,21 +3920,51 @@ var MockHttp = class extends Hookified {
 		return detect(port);
 	}
 	/**
-	* This will register the API documentation routes including openapi and swagger ui.
+	* Register OpenAPI generation and the Docula documentation site.
 	* @param fastifyInstance - the server instance to register the routes on.
 	*/
 	async registerApiDocs(fastifyInstance) {
-		const fastify = fastifyInstance ?? this._server;
+		await this.registerSwagger(fastifyInstance);
+		await this.registerSite(fastifyInstance);
+	}
+	/**
+	* Register `@fastify/swagger` and the live `/openapi.json` spec route.
+	* @param fastifyInstance - the server instance to register the routes on.
+	*/
+	async registerSwagger(fastifyInstance) {
+		const fastify = fastifyInstance ?? this.server;
 		await fastify.register(fastifySwagger, fastifySwaggerConfig);
-		await registerSwaggerUi(fastify);
-		await fastify.register(indexRoute);
+		await registerOpenApiJson(fastify);
+	}
+	/**
+	* Serve the built Docula site from `siteDistPath` when the directory exists.
+	* @param fastifyInstance - the server instance to register the routes on.
+	*/
+	async registerSite(fastifyInstance) {
+		const fastify = fastifyInstance ?? this.server;
+		if (!existsSync(this._siteDistPath)) {
+			fastify.log.warn(`Docula site not found at ${this._siteDistPath}; skipping static docs`);
+			return;
+		}
+		const sitemapPath = path.join(this._siteDistPath, "sitemap.xml");
+		if (existsSync(sitemapPath)) fastify.get("/sitemap.xml", { schema: { hide: true } }, async (request, reply) => {
+			const xml = await fsPromises.readFile(sitemapPath, "utf8");
+			return reply.type("application/xml").send(xml.replaceAll("https://mockhttp.org", requestOrigin(request)));
+		});
+		await fastify.register(fastifyStatic, {
+			root: this._siteDistPath,
+			prefix: "/",
+			decorateReply: !fastify.hasReplyDecorator("sendFile"),
+			index: ["index.html"],
+			wildcard: true
+		});
 	}
 	/**
 	* Register the HTTP methods routes.
 	* @param fastifyInstance - the server instance to register the routes on.
 	*/
 	async registerHttpMethods(fastifyInstance) {
-		const fastify = fastifyInstance ?? this._server;
+		const fastify = fastifyInstance ?? this.server;
 		await fastify.register(getRoute);
 		await fastify.register(postRoute);
 		await fastify.register(deleteRoute);
@@ -4014,14 +3976,14 @@ var MockHttp = class extends Hookified {
 	* @param fastifyInstance - the server instance to register the routes on.
 	*/
 	async registerStatusCodeRoutes(fastifyInstance) {
-		await (fastifyInstance ?? this._server).register(statusCodeRoute);
+		await (fastifyInstance ?? this.server).register(statusCodeRoute);
 	}
 	/**
 	* Register the request inspection routes.
 	* @param fastifyInstance - the server instance to register the routes on.
 	*/
 	async registerRequestInspectionRoutes(fastifyInstance) {
-		const fastify = fastifyInstance ?? this._server;
+		const fastify = fastifyInstance ?? this.server;
 		await fastify.register(ipRoute);
 		await fastify.register(headersRoute);
 		await fastify.register(userAgentRoute);
@@ -4031,20 +3993,20 @@ var MockHttp = class extends Hookified {
 	* @param fastifyInstance - the server instance to register the routes on.
 	*/
 	async registerResponseInspectionRoutes(fastifyInstance) {
-		const fastify = fastifyInstance ?? this._server;
+		const fastify = fastifyInstance ?? this.server;
 		await fastify.register(cacheRoutes);
 		await fastify.register(etagRoutes);
 		await fastify.register(responseHeadersRoutes);
 	}
 	async registerResponseFormatRoutes(fastifyInstance) {
-		await (fastifyInstance ?? this._server).register(responseFormatRoutes);
+		await (fastifyInstance ?? this.server).register(responseFormatRoutes);
 	}
 	/**
 	* Register the redirect routes.
 	* @param fastifyInstance - the server instance to register the routes on.
 	*/
 	async registerRedirectRoutes(fastifyInstance) {
-		const fastify = fastifyInstance ?? this._server;
+		const fastify = fastifyInstance ?? this.server;
 		await fastify.register(absoluteRedirectRoute);
 		await fastify.register(relativeRedirectRoute);
 		await fastify.register(redirectToRoute);
@@ -4054,7 +4016,7 @@ var MockHttp = class extends Hookified {
 	* @param fastifyInstance - the server instance to register the routes on.
 	*/
 	async registerCookieRoutes(fastifyInstance) {
-		const fastify = fastifyInstance ?? this._server;
+		const fastify = fastifyInstance ?? this.server;
 		await fastify.register(fastifyCookie);
 		await fastify.register(getCookiesRoute);
 		await fastify.register(postCookieRoute);
@@ -4065,14 +4027,14 @@ var MockHttp = class extends Hookified {
 	* @param fastifyInstance - the server instance to register the routes on.
 	*/
 	async registerAnythingRoutes(fastifyInstance) {
-		await (fastifyInstance ?? this._server).register(anythingRoute);
+		await (fastifyInstance ?? this.server).register(anythingRoute);
 	}
 	/**
 	* Register the auth routes.
 	* @param fastifyInstance - the server instance to register the routes on.
 	*/
 	async registerAuthRoutes(fastifyInstance) {
-		const fastify = fastifyInstance ?? this._server;
+		const fastify = fastifyInstance ?? this.server;
 		await fastify.register(basicAuthRoute);
 		await fastify.register(hiddenBasicAuthRoute);
 		await fastify.register(bearerAuthRoute);
@@ -4083,14 +4045,14 @@ var MockHttp = class extends Hookified {
 	* @param fastifyInstance - the server instance to register the routes on.
 	*/
 	async registerImageRoutes(fastifyInstance) {
-		await (fastifyInstance ?? this._server).register(imageRoutes);
+		await (fastifyInstance ?? this.server).register(imageRoutes);
 	}
 	/**
 	* Register the dynamic data routes.
 	* @param fastifyInstance - the server instance to register the routes on.
 	*/
 	async registerDynamicDataRoutes(fastifyInstance) {
-		const fastify = fastifyInstance ?? this._server;
+		const fastify = fastifyInstance ?? this.server;
 		await fastify.register(uuidRoute);
 		await fastify.register(bytesRoute);
 		await fastify.register(streamBytesRoute);
@@ -4106,7 +4068,7 @@ var MockHttp = class extends Hookified {
 	* @param fastifyInstance - the server instance to register the routes on.
 	*/
 	async registerBinRoutes(fastifyInstance) {
-		const fastify = fastifyInstance ?? this._server;
+		const fastify = fastifyInstance ?? this.server;
 		await fastify.register(binsManagementRoute(this._bins));
 		await fastify.register(binsCaptureRoute(this._bins));
 	}
@@ -4142,6 +4104,7 @@ const start = async () => {
 	if (process$1.env.LOGGING === "false") mockHttp.logging = false;
 	/* v8 ignore next -- @preserve */
 	if (process$1.env.HTTP2 === "true") mockHttp.http2 = true;
+	if (process$1.env.AUTO_DETECT_PORT === "false") mockHttp.autoDetectPort = false;
 	await mockHttp.start();
 	return mockHttp;
 };