@jaredwray/mockhttp 2.1.0 → 3.0.1

package/dist/index.mjs

@@ -13,195 +13,10 @@ import Fastify from "fastify";
 import { Hookified } from "hookified";
 import * as crypto$1 from "node:crypto";
 import crypto, { randomBytes, randomInt, randomUUID, timingSafeEqual } from "node:crypto";
+import Keyv from "keyv";
 import { Buffer as Buffer$1 } from "node:buffer";
 import { brotliCompressSync, deflateSync, gzipSync } from "node:zlib";
 import { escape } from "html-escaper";
-//#region src/bin-store.ts
-/**
-* In-memory implementation of {@link BinStore} backed by two Maps. State is
-* lost when the process exits.
-*/
-var InMemoryBinStore = class {
-	_bins = /* @__PURE__ */ new Map();
-	_requests = /* @__PURE__ */ new Map();
-	createBin(bin) {
-		this._bins.set(bin.id, bin);
-		this._requests.set(bin.id, []);
-	}
-	getBin(id) {
-		return this._bins.get(id);
-	}
-	listBins() {
-		return [...this._bins.values()];
-	}
-	deleteBin(id) {
-		this._requests.delete(id);
-		return this._bins.delete(id);
-	}
-	addRequest(binId, req, max) {
-		const bin = this._bins.get(binId);
-		const list = this._requests.get(binId);
-		if (!bin || !list) return;
-		list.unshift(req);
-		while (list.length > max && list.length > 0) list.pop();
-		bin.requestCount = list.length;
-	}
-	getRequests(binId) {
-		return [...this._requests.get(binId) ?? []];
-	}
-	getRequest(binId, reqId) {
-		return this._requests.get(binId)?.find((r) => r.id === reqId);
-	}
-	clearRequests(binId) {
-		const bin = this._bins.get(binId);
-		if (!bin) return;
-		this._requests.set(binId, []);
-		bin.requestCount = 0;
-	}
-	cleanupExpired(now) {
-		const removed = [];
-		for (const [id, bin] of this._bins) if (Date.parse(bin.expiresAt) <= now) {
-			this._bins.delete(id);
-			this._requests.delete(id);
-			removed.push(id);
-		}
-		return removed;
-	}
-};
-//#endregion
-//#region src/bin-manager.ts
-const DEFAULT_TTL_MS = 864e5;
-const DEFAULT_MAX_REQUESTS = 100;
-const DEFAULT_MAX_BODY_SIZE = 1048576;
-const DEFAULT_ID_LENGTH = 12;
-const DEFAULT_CLEANUP_INTERVAL_MS = 6e4;
-/**
-* Manages request bins: ephemeral URL endpoints that capture incoming HTTP
-* requests so they can be inspected later.
-*/
-var BinManager = class {
-	_store;
-	_defaultTtlMs;
-	_maxRequestsPerBin;
-	_maxBodySize;
-	_idLength;
-	_cleanupIntervalMs;
-	_cleanupTimer;
-	constructor(options) {
-		this._store = options?.store ?? new InMemoryBinStore();
-		this._defaultTtlMs = options?.defaultTtlMs ?? DEFAULT_TTL_MS;
-		this._maxRequestsPerBin = Math.max(0, options?.maxRequestsPerBin ?? DEFAULT_MAX_REQUESTS);
-		this._maxBodySize = options?.maxBodySize ?? DEFAULT_MAX_BODY_SIZE;
-		this._idLength = options?.idLength ?? DEFAULT_ID_LENGTH;
-		this._cleanupIntervalMs = options?.cleanupIntervalMs ?? DEFAULT_CLEANUP_INTERVAL_MS;
-	}
-	/** Underlying storage backend. */
-	get store() {
-		return this._store;
-	}
-	/** Maximum captured body size in bytes. */
-	get maxBodySize() {
-		return this._maxBodySize;
-	}
-	/** Maximum number of requests retained per bin. */
-	get maxRequestsPerBin() {
-		return this._maxRequestsPerBin;
-	}
-	/** Default bin lifetime in milliseconds. */
-	get defaultTtlMs() {
-		return this._defaultTtlMs;
-	}
-	/** Create a new bin with the configured TTL. */
-	createBin() {
-		const id = this.generateId();
-		const now = Date.now();
-		const bin = {
-			id,
-			createdAt: new Date(now).toISOString(),
-			expiresAt: new Date(now + this._defaultTtlMs).toISOString(),
-			requestCount: 0
-		};
-		this._store.createBin(bin);
-		return bin;
-	}
-	/**
-	* Look up a bin by id. Returns `undefined` if the bin does not exist or
-	* has expired (in which case it is also lazily removed).
-	*/
-	getBin(id) {
-		const bin = this._store.getBin(id);
-		if (!bin) return;
-		if (Date.parse(bin.expiresAt) <= Date.now()) {
-			this._store.deleteBin(id);
-			return;
-		}
-		return bin;
-	}
-	/** List all non-expired bins. */
-	listBins() {
-		const now = Date.now();
-		const result = [];
-		for (const bin of this._store.listBins()) {
-			if (Date.parse(bin.expiresAt) <= now) {
-				this._store.deleteBin(bin.id);
-				continue;
-			}
-			result.push(bin);
-		}
-		return result;
-	}
-	/** Delete a bin. Returns true if the bin existed. */
-	deleteBin(id) {
-		return this._store.deleteBin(id);
-	}
-	/**
-	* Record an incoming request against a bin. Returns the stored
-	* {@link CapturedRequest}, or `undefined` if the bin does not exist or is
-	* expired.
-	*/
-	recordRequest(binId, raw) {
-		if (!this.getBin(binId)) return;
-		const captured = {
-			...raw,
-			id: this.generateId(),
-			binId,
-			capturedAt: (/* @__PURE__ */ new Date()).toISOString()
-		};
-		this._store.addRequest(binId, captured, this._maxRequestsPerBin);
-		return captured;
-	}
-	/** List captured requests for a bin (newest first). */
-	getRequests(binId) {
-		return this._store.getRequests(binId);
-	}
-	/** Look up a single captured request. */
-	getRequest(binId, reqId) {
-		return this._store.getRequest(binId, reqId);
-	}
-	/** Clear all captured requests in a bin. */
-	clearRequests(binId) {
-		this._store.clearRequests(binId);
-	}
-	/** Start the periodic cleanup of expired bins. */
-	start() {
-		if (this._cleanupTimer) return;
-		this._cleanupTimer = setInterval(() => {
-			this._store.cleanupExpired(Date.now());
-		}, this._cleanupIntervalMs);
-		this._cleanupTimer.unref?.();
-	}
-	/** Stop the periodic cleanup. Idempotent. */
-	stop() {
-		if (this._cleanupTimer) {
-			clearInterval(this._cleanupTimer);
-			this._cleanupTimer = void 0;
-		}
-	}
-	generateId() {
-		return randomUUID().replaceAll("-", "").slice(0, this._idLength);
-	}
-};
-//#endregion
 //#region src/certificate.ts
 function encodeLength(length) {
 	if (length < 128) return Buffer.from([length]);
@@ -478,6 +293,310 @@ function getFastifyConfig(logging = true) {
 	};
 }
 //#endregion
+//#region src/bin-store-diagnostics.ts
+const ENCODING_HINT = "Percent-encode reserved characters in the username and password (@ : / ? # [ ] $).";
+const loggedPhases = /* @__PURE__ */ new WeakMap();
+/** Error whose message is already safe to return to clients. */
+var BinStoreFailure = class extends Error {
+	binStoreFailure = true;
+	constructor(message, cause) {
+		super(message, cause === void 0 ? void 0 : { cause });
+		this.name = "BinStoreFailure";
+	}
+};
+function isBinStoreFailure(error) {
+	return error instanceof BinStoreFailure || typeof error === "object" && error !== null && "binStoreFailure" in error && error.binStoreFailure === true;
+}
+function mongoUriFacts(uri) {
+	if (!uri) return {
+		present: false,
+		scheme: null
+	};
+	if (uri.startsWith("mongodb+srv://")) return {
+		present: true,
+		scheme: "mongodb+srv"
+	};
+	if (uri.startsWith("mongodb://")) return {
+		present: true,
+		scheme: "mongodb"
+	};
+	return {
+		present: true,
+		scheme: null
+	};
+}
+/**
+* Shape flags only. A normal URI has one `@` or zero `@`.
+* A second `@` makes the driver throw `Invalid connection string` before the network call.
+*/
+function uriShape(uri) {
+	return {
+		whitespace: /\s/.test(uri),
+		wrappedQuotes: uri.startsWith("\"") || uri.startsWith("'") || uri.endsWith("\"") || uri.endsWith("'"),
+		extraAt: uri.split("@").length - 1 > 1
+	};
+}
+function replaceSecret(message, secret) {
+	if (secret.length < 3) return message;
+	if (/^[a-z]+$/i.test(secret) && secret.length < 8) return message;
+	return message.split(secret).join("[redacted]");
+}
+function sensitiveParts(uri) {
+	const parts = [];
+	const body = uri.replace(/^mongodb(?:\+srv)?:\/\//i, "");
+	const at = body.lastIndexOf("@");
+	if (at >= 0) {
+		const userinfo = body.slice(0, at);
+		const colon = userinfo.indexOf(":");
+		if (colon >= 0) parts.push(userinfo.slice(0, colon), userinfo.slice(colon + 1));
+		else if (userinfo) parts.push(userinfo);
+		const hostname = (body.slice(at + 1).split(/[/?]/)[0] ?? "").split(":")[0] ?? "";
+		if (hostname) parts.push(hostname);
+	} else {
+		const hostname = (body.split(/[/?]/)[0] ?? "").split(":")[0] ?? "";
+		if (hostname) parts.push(hostname);
+	}
+	return parts;
+}
+function redactSecrets(message, uri) {
+	let out = message;
+	if (uri) {
+		out = out.split(uri).join("[redacted-uri]");
+		for (const part of sensitiveParts(uri)) out = replaceSecret(out, part);
+	}
+	out = out.replace(/mongodb(?:\+srv)?:\/\/\S+/gi, "[redacted-uri]");
+	out = out.replace(/\/\/([^/\s:@]+):([^/\s@]+)@/g, "//[redacted]:[redacted]@");
+	return out;
+}
+/**
+* Add the encode hint only when the driver message is already a parse error.
+* A DNS error or a scheme error keeps its own text.
+*/
+function withEncodingHint(message) {
+	if (!/invalid connection string|unescaped characters/i.test(message) || message.includes("Percent-encode")) return message;
+	return `${message}. ${ENCODING_HINT}`;
+}
+function redactStoreError(error, uri) {
+	const name = error instanceof Error && error.name ? error.name : "Error";
+	const raw = error instanceof Error ? error.message : "Bin store request failed";
+	const codeValue = typeof error === "object" && error !== null && "code" in error && error.code != null ? error.code : null;
+	const code = typeof codeValue === "string" || typeof codeValue === "number" ? codeValue : null;
+	return {
+		name,
+		message: withEncodingHint(redactSecrets(raw, uri)),
+		code
+	};
+}
+function alreadyLogged(error, phase) {
+	if (typeof error !== "object" || error === null) return false;
+	let phases = loggedPhases.get(error);
+	if (!phases) {
+		phases = /* @__PURE__ */ new Set();
+		loggedPhases.set(error, phases);
+	}
+	if (phases.has(phase)) return true;
+	phases.add(phase);
+	return false;
+}
+/** One JSON line. Safe to print in Workers logs. */
+function logBinStore(input) {
+	if (input.error !== void 0 && alreadyLogged(input.error, input.phase)) return;
+	const facts = mongoUriFacts(input.uri);
+	const payload = {
+		source: "mockhttp.bin-store",
+		phase: input.phase,
+		store: input.store,
+		uriPresent: facts.present,
+		scheme: facts.scheme
+	};
+	if (input.uri) payload.uriShape = uriShape(input.uri);
+	if (input.connected !== void 0) payload.connected = input.connected;
+	if (input.latencyMs !== void 0) payload.latencyMs = input.latencyMs;
+	if (input.error !== void 0) payload.error = redactStoreError(input.error, input.uri);
+	const line = JSON.stringify(payload);
+	if (input.level === "info") {
+		console.info(line);
+		return;
+	}
+	console.error(line);
+}
+//#endregion
+//#region src/mock-http-bins.ts
+const DEFAULT_TTL_MS = 864e5;
+const DEFAULT_MAX_REQUESTS = 100;
+const DEFAULT_MAX_BODY_SIZE = 131072;
+const DEFAULT_ID_LENGTH = 12;
+const BIN_KEY_PREFIX = "bin:";
+/**
+* Stores request bins in Keyv.
+* The default store is `new Keyv()`, which keeps data in memory.
+*/
+var MockHttpBins = class {
+	_keyv;
+	_defaultTtlMs;
+	_maxRequestsPerBin;
+	_maxBodySize;
+	_idLength;
+	_locks = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this._keyv = options?.keyv ?? new Keyv();
+		this._defaultTtlMs = options?.defaultTtlMs ?? DEFAULT_TTL_MS;
+		this._maxRequestsPerBin = Math.max(0, options?.maxRequestsPerBin ?? DEFAULT_MAX_REQUESTS);
+		this._maxBodySize = options?.maxBodySize ?? DEFAULT_MAX_BODY_SIZE;
+		this._idLength = options?.idLength ?? DEFAULT_ID_LENGTH;
+	}
+	/** Keyv instance that stores the bins. */
+	get keyv() {
+		return this._keyv;
+	}
+	/** Maximum captured body size in bytes. */
+	get maxBodySize() {
+		return this._maxBodySize;
+	}
+	/** Maximum number of requests in one bin. */
+	get maxRequestsPerBin() {
+		return this._maxRequestsPerBin;
+	}
+	/** Default bin lifetime in milliseconds. */
+	get defaultTtlMs() {
+		return this._defaultTtlMs;
+	}
+	/**
+	* Create a new bin with the configured lifetime.
+	* Throws when Keyv does not store the bin.
+	*/
+	async createBin() {
+		const id = this.generateId();
+		const now = Date.now();
+		const bin = {
+			id,
+			createdAt: new Date(now).toISOString(),
+			expiresAt: new Date(now + this._defaultTtlMs).toISOString(),
+			requestCount: 0
+		};
+		await this.save({
+			bin,
+			requests: []
+		});
+		return bin;
+	}
+	/**
+	* Look up a bin by id.
+	* Returns `undefined` when the bin does not exist or Keyv has expired it.
+	* A failed read also returns `undefined` when the Keyv instance has an `error` listener.
+	*/
+	async getBin(id) {
+		return (await this._keyv.get(this.binKey(id)))?.bin;
+	}
+	/**
+	* List the bins that Keyv still holds.
+	* Throws when the Keyv store has no iterator.
+	* When the Keyv instance has an `error` listener, a failed walk returns the bins read before the error.
+	*/
+	async listBins() {
+		if (!this.canIterate()) throw new Error("MockHttpBins: the configured Keyv store does not support iteration; listBins() is unavailable");
+		const bins = [];
+		for await (const [key, value] of this._keyv.iterator()) if (key.startsWith(BIN_KEY_PREFIX)) bins.push(value.bin);
+		return bins;
+	}
+	/**
+	* Delete a bin. Returns true when the bin existed.
+	* The delete waits for captures already queued for that bin, so a capture cannot write the bin back.
+	*/
+	async deleteBin(id) {
+		return this.enqueue(id, () => this._keyv.delete(this.binKey(id)));
+	}
+	/**
+	* Record a request for a bin.
+	* Returns `undefined` when the bin does not exist.
+	* Throws when Keyv does not store the capture.
+	*/
+	async recordRequest(binId, raw) {
+		const captured = {
+			...raw,
+			id: this.generateId(),
+			binId,
+			capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		return await this.enqueue(binId, () => this.appendRequest(binId, captured)) ? captured : void 0;
+	}
+	/** List captured requests for a bin, newest first. */
+	async getRequests(binId) {
+		return [...(await this._keyv.get(this.binKey(binId)))?.requests ?? []];
+	}
+	/** Look up one captured request. */
+	async getRequest(binId, reqId) {
+		return (await this._keyv.get(this.binKey(binId)))?.requests.find((request) => request.id === reqId);
+	}
+	/**
+	* Remove captured requests and keep the bin.
+	* Returns false when the bin does not exist.
+	* Throws when Keyv does not store the change.
+	*/
+	async clearRequests(binId) {
+		return this.enqueue(binId, async () => {
+			const doc = await this._keyv.get(this.binKey(binId));
+			if (!doc) return false;
+			doc.requests = [];
+			doc.bin.requestCount = 0;
+			await this.save(doc);
+			return true;
+		});
+	}
+	/** Keyv 6 yields nothing when the store has no iterator. Listing must fail instead. */
+	canIterate() {
+		return typeof this._keyv.store.iterator === "function";
+	}
+	/** Returns false when the bin does not exist. */
+	async appendRequest(binId, captured) {
+		const doc = await this._keyv.get(this.binKey(binId));
+		if (!doc) return false;
+		doc.requests.unshift(captured);
+		while (doc.requests.length > this._maxRequestsPerBin) doc.requests.pop();
+		doc.bin.requestCount = doc.requests.length;
+		await this.save(doc);
+		return true;
+	}
+	/**
+	* Write a bin document with a TTL from its lifetime.
+	* Keyv returns false or throws when the write fails. Both cases throw here.
+	*/
+	async save(doc) {
+		const message = `MockHttpBins: could not save bin ${doc.bin.id}`;
+		let saved;
+		try {
+			saved = await this._keyv.set(this.binKey(doc.bin.id), doc, this.ttlFor(doc.bin));
+		} catch (cause) {
+			if (isBinStoreFailure(cause)) throw new BinStoreFailure(`${message}. ${cause.message}`, cause);
+			throw new Error(message, { cause });
+		}
+		if (!saved) throw new Error(message);
+	}
+	/**
+	* Run writes for one bin in order.
+	* A failed write does not block the next write for that bin.
+	*/
+	enqueue(id, fn) {
+		const run = (this._locks.get(id) ?? Promise.resolve()).then(fn);
+		const settled = run.then(() => void 0, () => void 0);
+		this._locks.set(id, settled);
+		settled.finally(() => {
+			if (this._locks.get(id) === settled) this._locks.delete(id);
+		});
+		return run;
+	}
+	/** Keyv keeps a key without a TTL forever, so the TTL never drops below 1 ms. */
+	ttlFor(bin) {
+		return Math.max(1, Date.parse(bin.expiresAt) - Date.now());
+	}
+	binKey(id) {
+		return `${BIN_KEY_PREFIX}${id}`;
+	}
+	generateId() {
+		return randomUUID().replaceAll("-", "").slice(0, this._idLength);
+	}
+};
+//#endregion
 //#region src/routes/anything/index.ts
 const anythingSchema = {
 	description: "Will return anything that you send it",
@@ -907,9 +1026,9 @@ const captureSchema = {
 const TEXT_CONTENT_TYPE_REGEX = /^(text\/|application\/(json|xml|x-www-form-urlencoded|javascript))/i;
 /**
 * Create a Fastify plugin that registers the catch-all bin capture endpoint
-* at `/b/:id` and `/b/:id/*`, with the provided {@link BinManager} injected.
+* at `/b/:id` and `/b/:id/*`, with the provided {@link MockHttpBins} injected.
 */
-const binsCaptureRoute = (binManager) => {
+const binsCaptureRoute = (bins) => {
 	return (fastify) => {
 		fastify.removeAllContentTypeParsers();
 		fastify.addContentTypeParser("*", { parseAs: "buffer" }, (_request, body, done) => {
@@ -918,10 +1037,9 @@ const binsCaptureRoute = (binManager) => {
 		const handler = async (request, reply) => {
 			const { id } = request.params;
 			const rest = request.params["*"] ?? "";
-			if (!binManager.getBin(id)) return reply.code(404).send({ error: "bin_not_found" });
 			const raw = request.body;
 			const bodySize = raw?.length ?? 0;
-			const max = binManager.maxBodySize;
+			const max = bins.maxBodySize;
 			const truncated = bodySize > max;
 			const slice = raw && raw.length > 0 ? raw.subarray(0, max) : void 0;
 			const contentTypeHeader = request.headers["content-type"];
@@ -942,7 +1060,7 @@ const binsCaptureRoute = (binManager) => {
 			const prefix = `/b/${id}`;
 			const url = request.url.slice(prefix.length) || "/";
 			const path = rest ? `/${rest}` : "/";
-			const captured = binManager.recordRequest(id, {
+			const captured = await bins.recordRequest(id, {
 				method: request.method,
 				url,
 				path,
@@ -955,11 +1073,11 @@ const binsCaptureRoute = (binManager) => {
 				bodyEncoding,
 				truncated
 			});
+			if (!captured) return reply.code(404).send({ error: "bin_not_found" });
 			return reply.code(200).send({
 				ok: true,
 				binId: id,
-				/* v8 ignore next -- @preserve */
-				requestId: captured?.id ?? ""
+				requestId: captured.id
 			});
 		};
 		const opts = {
@@ -1173,43 +1291,54 @@ const clearRequestsSchema = {
 	}
 };
 /**
+* Public capture URL for a new bin.
+* The last forwarded protocol wins, matching a proxy chain. An unrecognized
+* value falls back to the socket protocol, then `http`.
+*/
+function binCaptureUrl(forwardedProto, socketProtocol, host, id) {
+	const forwarded = (Array.isArray(forwardedProto) ? forwardedProto.join(",") : forwardedProto)?.split(",").at(-1)?.trim().toLowerCase();
+	let protocol = "http";
+	if (forwarded === "https" || forwarded === "http") protocol = forwarded;
+	else if (socketProtocol === "https") protocol = "https";
+	return `${protocol}://${host}/b/${id}`;
+}
+/**
 * Create a Fastify plugin that registers bin management endpoints, with the
-* provided {@link BinManager} injected.
+* provided {@link MockHttpBins} injected.
 */
-const binsManagementRoute = (binManager) => {
+const binsManagementRoute = (bins) => {
 	return (fastify) => {
 		fastify.post("/bins", { schema: createBinSchema }, async (request, _reply) => {
-			const bin = binManager.createBin();
+			const bin = await bins.createBin();
 			/* v8 ignore next -- @preserve */
 			const host = request.headers.host ?? request.hostname;
 			return {
 				...bin,
-				url: `${request.protocol}://${host}/b/${bin.id}`
+				url: binCaptureUrl(request.headers["x-mockhttp-forwarded-proto"] ?? request.headers["x-forwarded-proto"], request.protocol, host, bin.id)
 			};
 		});
-		fastify.get("/bins", { schema: listBinsSchema }, async (_request, _reply) => ({ bins: binManager.listBins() }));
+		fastify.get("/bins", { schema: listBinsSchema }, async (_request, _reply) => ({ bins: await bins.listBins() }));
 		fastify.get("/bins/:id", { schema: getBinSchema }, async (request, reply) => {
-			const bin = binManager.getBin(request.params.id);
+			const bin = await bins.getBin(request.params.id);
 			if (!bin) return reply.code(404).send({ error: "bin_not_found" });
 			return bin;
 		});
 		fastify.get("/bins/:id/requests", { schema: listRequestsSchema }, async (request, reply) => {
-			if (!binManager.getBin(request.params.id)) return reply.code(404).send({ error: "bin_not_found" });
-			return { requests: binManager.getRequests(request.params.id) };
+			if (!await bins.getBin(request.params.id)) return reply.code(404).send({ error: "bin_not_found" });
+			return { requests: await bins.getRequests(request.params.id) };
 		});
 		fastify.get("/bins/:id/requests/:reqId", { schema: getRequestSchema }, async (request, reply) => {
-			if (!binManager.getBin(request.params.id)) return reply.code(404).send({ error: "bin_not_found" });
-			const captured = binManager.getRequest(request.params.id, request.params.reqId);
+			if (!await bins.getBin(request.params.id)) return reply.code(404).send({ error: "bin_not_found" });
+			const captured = await bins.getRequest(request.params.id, request.params.reqId);
 			if (!captured) return reply.code(404).send({ error: "request_not_found" });
 			return captured;
 		});
 		fastify.delete("/bins/:id/requests", { schema: clearRequestsSchema }, async (request, reply) => {
-			if (!binManager.getBin(request.params.id)) return reply.code(404).send({ error: "bin_not_found" });
-			binManager.clearRequests(request.params.id);
+			if (!await bins.clearRequests(request.params.id)) return reply.code(404).send({ error: "bin_not_found" });
 			return reply.code(204).send();
 		});
 		fastify.delete("/bins/:id", { schema: deleteBinSchema }, async (request, reply) => {
-			if (!binManager.deleteBin(request.params.id)) return reply.code(404).send({ error: "bin_not_found" });
+			if (!await bins.deleteBin(request.params.id)) return reply.code(404).send({ error: "bin_not_found" });
 			return reply.code(204).send();
 		});
 	};
@@ -1856,6 +1985,164 @@ const uuidRoute = (fastify) => {
 	fastify.get("/uuid", { schema: uuidSchema }, async () => ({ uuid: randomUUID() }));
 };
 //#endregion
+//#region src/routes/health.ts
+/** Cheap read against the in-memory Keyv used when MongoDB is not configured. */
+async function checkMemoryBinStore(keyv) {
+	const started = Date.now();
+	try {
+		await keyv.get("__mockhttp_healthz__");
+		return {
+			status: "ok",
+			bins: {
+				store: "memory",
+				connected: true,
+				latencyMs: Math.max(0, Date.now() - started),
+				uriPresent: false
+			}
+		};
+	} catch (error) {
+		logBinStore({
+			phase: "healthz",
+			store: "memory",
+			error
+		});
+		return {
+			status: "error",
+			bins: {
+				store: "memory",
+				connected: false,
+				uriPresent: false,
+				error: redactStoreError(error)
+			}
+		};
+	}
+}
+const binHealthFields = {
+	store: {
+		type: "string",
+		enum: ["mongo", "memory"]
+	},
+	connected: { type: "boolean" },
+	latencyMs: { type: "integer" },
+	uriPresent: { type: "boolean" },
+	uri: {
+		type: "object",
+		properties: {
+			length: { type: "integer" },
+			leadingWhitespace: { type: "boolean" },
+			trailingWhitespace: { type: "boolean" },
+			newline: { type: "boolean" },
+			wrappedQuotes: { type: "boolean" },
+			atCount: { type: "integer" },
+			passwordReserved: {
+				type: "array",
+				items: { type: "string" }
+			},
+			passwordHasPercent: { type: "boolean" }
+		},
+		required: [
+			"length",
+			"leadingWhitespace",
+			"trailingWhitespace",
+			"newline",
+			"wrappedQuotes",
+			"atCount",
+			"passwordReserved",
+			"passwordHasPercent"
+		]
+	}
+};
+const healthSchema = {
+	description: "Report whether bin storage is reachable. MongoDB failures include the driver error. The scheme, the host, the username, the password, the password length, and the full URI are never returned.",
+	tags: ["Health"],
+	response: {
+		200: {
+			type: "object",
+			properties: {
+				status: {
+					type: "string",
+					enum: ["ok"]
+				},
+				bins: {
+					type: "object",
+					properties: binHealthFields,
+					required: [
+						"store",
+						"connected",
+						"latencyMs",
+						"uriPresent"
+					]
+				}
+			},
+			required: ["status", "bins"]
+		},
+		503: {
+			type: "object",
+			properties: {
+				status: {
+					type: "string",
+					enum: ["error"]
+				},
+				bins: {
+					type: "object",
+					properties: {
+						...binHealthFields,
+						error: {
+							type: "object",
+							properties: {
+								name: { type: "string" },
+								message: { type: "string" },
+								code: { type: [
+									"string",
+									"number",
+									"null"
+								] }
+							},
+							required: [
+								"name",
+								"message",
+								"code"
+							]
+						}
+					},
+					required: [
+						"store",
+						"connected",
+						"uriPresent",
+						"error"
+					]
+				}
+			},
+			required: ["status", "bins"]
+		}
+	}
+};
+const healthRoute = (check) => (fastify) => {
+	fastify.get("/healthz", { schema: healthSchema }, async (_request, reply) => {
+		try {
+			const report = await check();
+			if (report.status === "error") return reply.status(503).send(report);
+			return report;
+		} catch (error) {
+			logBinStore({
+				phase: "healthz",
+				store: "unknown",
+				error
+			});
+			const info = redactStoreError(error);
+			return reply.status(503).send({
+				status: "error",
+				bins: {
+					store: "mongo",
+					connected: false,
+					uriPresent: false,
+					error: info
+				}
+			});
+		}
+	});
+};
+//#endregion
 //#region src/routes/http-methods/delete.ts
 const deleteSchema = {
 	description: "Handles a DELETE request and returns request information",
@@ -3367,7 +3654,7 @@ A simple HTTP server that can be used to mock HTTP responses for testing purpose
 
 [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: "2.1.0"
+	version: "3.0.1"
 } } };
 const withLocalServer = (spec) => {
 	spec.servers = [{
@@ -3502,7 +3789,6 @@ var MockHttp = class extends Hookified {
 	_siteDistPath = defaultSiteDistPath;
 	_logging = true;
 	_pluginTimeout;
-	_startBins = true;
 	_httpBin = {
 		httpMethods: true,
 		redirects: true,
@@ -3528,7 +3814,8 @@ var MockHttp = class extends Hookified {
 	_httpsCredentials;
 	_server;
 	_taps = new TapManager();
-	_bins = new BinManager();
+	_bins = new MockHttpBins();
+	_binHealthCheck;
 	constructor(options) {
 		super(options?.hookOptions);
 		if (options?.port) this._port = options.port;
@@ -3545,7 +3832,6 @@ var MockHttp = class extends Hookified {
 		}
 		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) {
@@ -3679,20 +3965,6 @@ var MockHttp = class extends Hookified {
 		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.
 	*/
@@ -3798,18 +4070,30 @@ var MockHttp = class extends Hookified {
 		this._taps = taps;
 	}
 	/**
-	* The BinManager instance for managing request bins.
+	* The MockHttpBins instance for request bins.
 	*/
 	get bins() {
 		return this._bins;
 	}
 	/**
-	* The BinManager instance for managing request bins.
+	* The MockHttpBins instance for request bins.
 	*/
 	set bins(bins) {
 		this._bins = bins;
 	}
 	/**
+	* Override the bin storage probe used by `GET /healthz`.
+	* The default probe reads the in-memory Keyv.
+	*/
+	set binHealthCheck(check) {
+		this._binHealthCheck = check;
+	}
+	/** Whether bin storage can serve a read or a MongoDB ping. */
+	checkBinStore() {
+		if (this._binHealthCheck) return this._binHealthCheck();
+		return checkMemoryBinStore(this._bins.keyv);
+	}
+	/**
 	* Register plugins and routes without listening. Use `inject()` against
 	* `server`, or call `start()` to bind a port.
 	*/
@@ -3862,6 +4146,7 @@ var MockHttp = class extends Hookified {
 			} } });
 			if (this._rateLimit) await this._server.register(fastifyRateLimit, this._rateLimit);
 			if (this._apiDocs) await this.registerSwagger();
+			await this.server.register(healthRoute(() => this.checkBinStore()));
 			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();
@@ -3874,10 +4159,7 @@ var MockHttp = class extends Hookified {
 			if (auth) await this.registerAuthRoutes();
 			if (images) await this.registerImageRoutes();
 			if (dynamicData) await this.registerDynamicDataRoutes();
-			if (bins) {
-				await this.registerBinRoutes();
-				if (this._startBins) this._bins.start();
-			}
+			if (bins) await this.registerBinRoutes();
 			if (this._apiDocs) await this.registerSite();
 		} catch (error) {
 			/* v8 ignore next -- @preserve */
@@ -3908,7 +4190,6 @@ var MockHttp = class extends Hookified {
 	* Close the Fastify server.
 	*/
 	async close() {
-		this._bins.stop();
 		if (this._server) await this._server.close();
 	}
 	/**
@@ -4111,4 +4392,4 @@ const start = async () => {
 /* v8 ignore next -- @preserve */
 if (import.meta.url === `file://${process$1.argv[1]}`) await start();
 //#endregion
-export { BinManager, InMemoryBinStore, MockHttp as default, MockHttp as mockhttp, generateCertificate, generateCertificateFiles, start };
+export { MockHttpBins, MockHttp as default, MockHttp as mockhttp, generateCertificate, generateCertificateFiles, start };