@jaredwray/mockhttp 3.0.0 → 3.0.1

package/dist/index.d.mts

@@ -2,6 +2,43 @@ import { RateLimitPluginOptions } from "@fastify/rate-limit";
 import { FastifyInstance, FastifyRequest } from "fastify";
 import { Hookified, HookifiedOptions } from "hookified";
 import Keyv from "keyv";
+//#region src/bin-store-diagnostics.d.ts
+type BinStoreErrorInfo = {
+  name: string;
+  message: string;
+  code: string | number | null;
+};
+type BinHealth = {
+  status: "ok";
+  bins: {
+    store: "mongo" | "memory";
+    connected: true;
+    latencyMs: number;
+    uriPresent: boolean;
+    uri?: UriDiagnostics;
+  };
+} | {
+  status: "error";
+  bins: {
+    store: "mongo" | "memory";
+    connected: false;
+    uriPresent: boolean;
+    uri?: UriDiagnostics;
+    error: BinStoreErrorInfo;
+  };
+};
+/** Redacted URI facts for `GET /healthz`. No password and no full URI. */
+type UriDiagnostics = {
+  length: number;
+  leadingWhitespace: boolean;
+  trailingWhitespace: boolean;
+  newline: boolean;
+  wrappedQuotes: boolean;
+  atCount: number;
+  passwordReserved: string[];
+  passwordHasPercent: boolean;
+};
+//#endregion
 //#region src/certificate.d.ts
 type CertificateOptions = {
   /**
@@ -455,6 +492,7 @@ declare class MockHttp extends Hookified {
   private _server;
   private _taps;
   private _bins;
+  private _binHealthCheck?;
   constructor(options?: MockHttpOptions);
   /**
    * The port to listen on. If not provided, defaults to 3000 and detects the next available port if in use.
@@ -624,6 +662,13 @@ declare class MockHttp extends Hookified {
    * The MockHttpBins instance for request bins.
    */
   set bins(bins: MockHttpBins);
+  /**
+   * Override the bin storage probe used by `GET /healthz`.
+   * The default probe reads the in-memory Keyv.
+   */
+  set binHealthCheck(check: () => Promise<BinHealth>);
+  /** Whether bin storage can serve a read or a MongoDB ping. */
+  checkBinStore(): Promise<BinHealth>;
   /**
    * Register plugins and routes without listening. Use `inject()` against
    * `server`, or call `start()` to bind a port.

package/dist/index.mjs

@@ -293,6 +293,134 @@ 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;
@@ -439,6 +567,7 @@ var MockHttpBins = class {
 		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);
@@ -1162,6 +1291,18 @@ 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 MockHttpBins} injected.
 */
@@ -1173,7 +1314,7 @@ const binsManagementRoute = (bins) => {
 			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: await bins.listBins() }));
@@ -1844,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",
@@ -3355,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: "3.0.0"
+	version: "3.0.1"
 } } };
 const withLocalServer = (spec) => {
 	spec.servers = [{
@@ -3516,6 +3815,7 @@ var MockHttp = class extends Hookified {
 	_server;
 	_taps = new TapManager();
 	_bins = new MockHttpBins();
+	_binHealthCheck;
 	constructor(options) {
 		super(options?.hookOptions);
 		if (options?.port) this._port = options.port;
@@ -3782,6 +4082,18 @@ var MockHttp = class extends Hookified {
 		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.
 	*/
@@ -3834,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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaredwray/mockhttp",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Mock Http - Easy way to mock http with httpbin replacement",
   "type": "module",
   "main": "dist/index.mjs",
@@ -49,7 +49,8 @@
     "tsx": "^4.23.15",
     "typescript": "7.0.2",
     "vite": "^8.3.4",
-    "vitest": "^5.0.3"
+    "vitest": "^5.0.3",
+    "wrangler": "4.127.0"
   },
   "dependencies": {
     "@fastify/cookie": "^11.1.3",
@@ -63,6 +64,7 @@
     "hookified": "^3.0.4",
     "html-escaper": "^3.0.3",
     "keyv": "^6.1.0",
+    "mongodb": "7.7.0",
     "pino": "^10.4.0",
     "pino-pretty": "^13.2.0"
   },
@@ -70,7 +72,7 @@
     "dist",
     "public",
     "site/dist",
-    "LICENCE"
+    "LICENSE"
   ],
   "scripts": {
     "lint": "biome check --write --error-on-warnings",