@jaredwray/mockhttp 1.6.0 → 1.8.0

package/dist/index.mjs

@@ -16,6 +16,192 @@ 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
+* 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 = 1440 * 60 * 1e3;
+const DEFAULT_MAX_REQUESTS = 100;
+const DEFAULT_MAX_BODY_SIZE = 1024 * 1024;
+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]);
@@ -249,7 +435,9 @@ async function generateCertificateFiles(options) {
 function isSpecificMatch(route) {
 	if (!route) return false;
 	const params = route.params;
-	return params === void 0 || params["*"] === void 0;
+	if (!params) return true;
+	const keys = Object.keys(params);
+	return keys.length === 0 || keys.some((k) => k !== "*");
 }
 function rewriteUrl(req) {
 	const originalUrl = req.url ?? "/";
@@ -359,6 +547,7 @@ const anythingRoute = (fastify) => {
 	};
 	const noValidation = {
 		schema: anythingSchema,
+		/* v8 ignore next -- @preserve */
 		validatorCompiler: () => () => true
 	};
 	fastify.get("/anything", noValidation, handler);
@@ -451,7 +640,7 @@ const basicAuthRoute = (fastify) => {
 const parseBearer = (header) => {
 	if (!header) return;
 	const [scheme, token] = header.split(" ");
-	if (!scheme || scheme.toLowerCase() !== "bearer" || !token) return;
+	if (scheme?.toLowerCase() !== "bearer" || !token) return;
 	return token;
 };
 const bearerAuthSchema = {
@@ -525,7 +714,7 @@ const parseDigest = (header) => {
 	if (spaceIndex === -1) return;
 	const scheme = header.slice(0, spaceIndex);
 	const rest = header.slice(spaceIndex + 1);
-	if (!scheme || scheme.toLowerCase() !== "digest" || !rest) return;
+	if (scheme?.toLowerCase() !== "digest" || !rest) return;
 	const out = {};
 	const parts = [];
 	let current = "";
@@ -633,7 +822,7 @@ const digestAuthRoute = (fastify) => {
 const parseBasic = (header) => {
 	if (!header) return;
 	const [scheme, value] = header.split(" ");
-	if (!scheme || scheme.toLowerCase() !== "basic" || !value) return;
+	if (scheme?.toLowerCase() !== "basic" || !value) return;
 	try {
 		const decoded = Buffer$1.from(value, "base64").toString("utf8");
 		const idx = decoded.indexOf(":");
@@ -675,6 +864,356 @@ const hiddenBasicAuthRoute = (fastify) => {
 	});
 };
 //#endregion
+//#region src/routes/bins/capture.ts
+const captureSchema = {
+	description: "Capture any HTTP request sent to a bin. Stores method, headers, body, query, and metadata.",
+	tags: ["Bins"],
+	params: {
+		type: "object",
+		properties: {
+			id: {
+				type: "string",
+				description: "Bin identifier"
+			},
+			"*": {
+				type: "string",
+				description: "Sub-path captured with the request"
+			}
+		},
+		required: ["id"]
+	},
+	response: {
+		200: {
+			type: "object",
+			properties: {
+				ok: { type: "boolean" },
+				binId: { type: "string" },
+				requestId: { type: "string" }
+			},
+			required: [
+				"ok",
+				"binId",
+				"requestId"
+			]
+		},
+		404: {
+			type: "object",
+			properties: { error: { type: "string" } },
+			required: ["error"]
+		}
+	}
+};
+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.
+*/
+const binsCaptureRoute = (binManager) => {
+	return (fastify) => {
+		fastify.removeAllContentTypeParsers();
+		fastify.addContentTypeParser("*", { parseAs: "buffer" }, (_request, body, done) => {
+			done(null, body);
+		});
+		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 truncated = bodySize > max;
+			const slice = raw && raw.length > 0 ? raw.subarray(0, max) : void 0;
+			const contentTypeHeader = request.headers["content-type"];
+			const contentType = typeof contentTypeHeader === "string" ? contentTypeHeader : void 0;
+			const isText = contentType ? TEXT_CONTENT_TYPE_REGEX.test(contentType) : false;
+			let bodyEncoding;
+			let body;
+			if (!slice) {
+				bodyEncoding = "none";
+				body = null;
+			} else if (isText) {
+				bodyEncoding = "utf8";
+				body = slice.toString("utf8");
+			} else {
+				bodyEncoding = "base64";
+				body = slice.toString("base64");
+			}
+			const prefix = `/b/${id}`;
+			const url = request.url.slice(prefix.length) || "/";
+			const path = rest ? `/${rest}` : "/";
+			const captured = binManager.recordRequest(id, {
+				method: request.method,
+				url,
+				path,
+				query: request.query,
+				headers: request.headers,
+				remoteAddress: request.ip,
+				contentType,
+				bodySize,
+				body,
+				bodyEncoding,
+				truncated
+			});
+			return reply.code(200).send({
+				ok: true,
+				binId: id,
+				/* v8 ignore next -- @preserve */
+				requestId: captured?.id ?? ""
+			});
+		};
+		const opts = {
+			schema: captureSchema,
+			/* v8 ignore next -- @preserve */
+			validatorCompiler: () => () => true
+		};
+		for (const m of [
+			"get",
+			"post",
+			"put",
+			"patch",
+			"delete",
+			"options"
+		]) {
+			fastify[m]("/b/:id", opts, handler);
+			fastify[m]("/b/:id/*", opts, handler);
+		}
+	};
+};
+//#endregion
+//#region src/routes/bins/management.ts
+const binSchema = {
+	type: "object",
+	properties: {
+		id: { type: "string" },
+		createdAt: { type: "string" },
+		expiresAt: { type: "string" },
+		requestCount: { type: "integer" }
+	},
+	required: [
+		"id",
+		"createdAt",
+		"expiresAt",
+		"requestCount"
+	]
+};
+const capturedRequestSchema = {
+	type: "object",
+	properties: {
+		id: { type: "string" },
+		binId: { type: "string" },
+		method: { type: "string" },
+		url: { type: "string" },
+		path: { type: "string" },
+		query: {
+			type: "object",
+			additionalProperties: true
+		},
+		headers: {
+			type: "object",
+			additionalProperties: true
+		},
+		remoteAddress: { type: "string" },
+		contentType: { type: "string" },
+		bodySize: { type: "integer" },
+		body: { type: ["string", "null"] },
+		bodyEncoding: {
+			type: "string",
+			enum: [
+				"utf8",
+				"base64",
+				"none"
+			]
+		},
+		truncated: { type: "boolean" },
+		capturedAt: { type: "string" }
+	},
+	required: [
+		"id",
+		"binId",
+		"method",
+		"url",
+		"path",
+		"query",
+		"headers",
+		"remoteAddress",
+		"bodySize",
+		"body",
+		"bodyEncoding",
+		"truncated",
+		"capturedAt"
+	]
+};
+const createBinSchema = {
+	description: "Create a new request bin",
+	tags: ["Bins"],
+	response: { 200: {
+		type: "object",
+		properties: {
+			id: { type: "string" },
+			url: { type: "string" },
+			createdAt: { type: "string" },
+			expiresAt: { type: "string" },
+			requestCount: { type: "integer" }
+		},
+		required: [
+			"id",
+			"url",
+			"createdAt",
+			"expiresAt",
+			"requestCount"
+		]
+	} }
+};
+const listBinsSchema = {
+	description: "List all active bins",
+	tags: ["Bins"],
+	response: { 200: {
+		type: "object",
+		properties: { bins: {
+			type: "array",
+			items: binSchema
+		} },
+		required: ["bins"]
+	} }
+};
+const getBinSchema = {
+	description: "Get metadata for a single bin",
+	tags: ["Bins"],
+	params: {
+		type: "object",
+		properties: { id: { type: "string" } },
+		required: ["id"]
+	},
+	response: {
+		200: binSchema,
+		404: {
+			type: "object",
+			properties: { error: { type: "string" } },
+			required: ["error"]
+		}
+	}
+};
+const listRequestsSchema = {
+	description: "List captured requests for a bin (newest first)",
+	tags: ["Bins"],
+	params: {
+		type: "object",
+		properties: { id: { type: "string" } },
+		required: ["id"]
+	},
+	response: {
+		200: {
+			type: "object",
+			properties: { requests: {
+				type: "array",
+				items: capturedRequestSchema
+			} },
+			required: ["requests"]
+		},
+		404: {
+			type: "object",
+			properties: { error: { type: "string" } },
+			required: ["error"]
+		}
+	}
+};
+const getRequestSchema = {
+	description: "Get a single captured request by id",
+	tags: ["Bins"],
+	params: {
+		type: "object",
+		properties: {
+			id: { type: "string" },
+			reqId: { type: "string" }
+		},
+		required: ["id", "reqId"]
+	},
+	response: {
+		200: capturedRequestSchema,
+		404: {
+			type: "object",
+			properties: { error: { type: "string" } },
+			required: ["error"]
+		}
+	}
+};
+const deleteBinSchema = {
+	description: "Delete a bin and all its captured requests",
+	tags: ["Bins"],
+	params: {
+		type: "object",
+		properties: { id: { type: "string" } },
+		required: ["id"]
+	},
+	response: {
+		204: { type: "null" },
+		404: {
+			type: "object",
+			properties: { error: { type: "string" } },
+			required: ["error"]
+		}
+	}
+};
+const clearRequestsSchema = {
+	description: "Clear all captured requests for a bin",
+	tags: ["Bins"],
+	params: {
+		type: "object",
+		properties: { id: { type: "string" } },
+		required: ["id"]
+	},
+	response: {
+		204: { type: "null" },
+		404: {
+			type: "object",
+			properties: { error: { type: "string" } },
+			required: ["error"]
+		}
+	}
+};
+/**
+* Create a Fastify plugin that registers bin management endpoints, with the
+* provided {@link BinManager} injected.
+*/
+const binsManagementRoute = (binManager) => {
+	return (fastify) => {
+		fastify.post("/bins", { schema: createBinSchema }, async (request, _reply) => {
+			const bin = binManager.createBin();
+			/* v8 ignore next -- @preserve */
+			const host = request.headers.host ?? request.hostname;
+			return {
+				...bin,
+				url: `${request.protocol}://${host}/b/${bin.id}`
+			};
+		});
+		fastify.get("/bins", { schema: listBinsSchema }, async (_request, _reply) => ({ bins: binManager.listBins() }));
+		fastify.get("/bins/:id", { schema: getBinSchema }, async (request, reply) => {
+			const bin = binManager.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) };
+		});
+		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 (!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);
+			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" });
+			return reply.code(204).send();
+		});
+	};
+};
+//#endregion
 //#region src/routes/cookies/delete.ts
 const cookiesDeleteSchema = {
 	description: "Delete a cookie",
@@ -900,6 +1439,7 @@ const delayRoute = (fastify) => {
 		/* v8 ignore next -- @preserve */
 		const host = request.headers.host || "localhost";
 		return {
+			/* v8 ignore next -- @preserve */
 			args: request.query || {},
 			data: "",
 			files: {},
@@ -1207,6 +1747,7 @@ const streamRoute = (fastify) => {
 		for (let i = 0; i < lines; i++) {
 			const data = {
 				id: i,
+				/* v8 ignore next -- @preserve */
 				args: request.query || {},
 				headers: request.headers,
 				origin: request.ip,
@@ -2908,7 +3449,7 @@ A simple HTTP server that can be used to mock HTTP responses for testing purpose
 
 [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.
 `,
-		version: "1.6.0"
+		version: "1.8.0"
 	},
 	consumes: ["application/json"],
 	produces: ["application/json"]
@@ -2921,14 +3462,17 @@ const registerSwaggerUi = async (fastify) => {
 			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
 	});
@@ -3052,7 +3596,8 @@ var MockHttp = class extends Hookified {
 		anything: true,
 		auth: true,
 		images: true,
-		dynamicData: true
+		dynamicData: true,
+		bins: true
 	};
 	_rateLimit = {
 		max: 1e3,
@@ -3065,6 +3610,7 @@ var MockHttp = class extends Hookified {
 	_httpsCredentials;
 	_server = Fastify();
 	_taps = new TapManager();
+	_bins = new BinManager();
 	constructor(options) {
 		super(options?.hookOptions);
 		if (options?.port) this._port = options.port;
@@ -3270,6 +3816,18 @@ var MockHttp = class extends Hookified {
 		this._taps = taps;
 	}
 	/**
+	* The BinManager instance for managing request bins.
+	*/
+	get bins() {
+		return this._bins;
+	}
+	/**
+	* The BinManager instance for managing request bins.
+	*/
+	set bins(bins) {
+		this._bins = bins;
+	}
+	/**
 	* Start the Fastify server. If the server is already running, it will be closed and restarted.
 	*/
 	async start() {
@@ -3328,7 +3886,7 @@ var MockHttp = class extends Hookified {
 			} } });
 			if (this._rateLimit) await this._server.register(fastifyRateLimit, this._rateLimit);
 			if (this._apiDocs) await this.registerApiDocs();
-			const { httpMethods, redirects, requestInspection, responseInspection, responseFormats, statusCodes, cookies, anything, auth, images, dynamicData } = this._httpBin;
+			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();
 			if (requestInspection) await this.registerRequestInspectionRoutes();
@@ -3340,6 +3898,10 @@ 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();
+				this._bins.start();
+			}
 			if (this._autoDetectPort) {
 				const originalPort = this._port;
 				this._port = await this.detectPort();
@@ -3358,6 +3920,7 @@ var MockHttp = class extends Hookified {
 	* Close the Fastify server.
 	*/
 	async close() {
+		this._bins.stop();
 		await this._server.close();
 	}
 	/**
@@ -3482,6 +4045,15 @@ var MockHttp = class extends Hookified {
 		await fastify.register(dripRoute);
 		await fastify.register(linksRoute);
 	}
+	/**
+	* Register the request bin routes (management at /bins and capture at /b/:id).
+	* @param fastifyInstance - the server instance to register the routes on.
+	*/
+	async registerBinRoutes(fastifyInstance) {
+		const fastify = fastifyInstance ?? this._server;
+		await fastify.register(binsManagementRoute(this._bins));
+		await fastify.register(binsCaptureRoute(this._bins));
+	}
 	async resolveHttpsCredentials(options) {
 		if (options.cert && options.key) return {
 			cert: await this.loadPemValue(options.cert),
@@ -3520,4 +4092,4 @@ const start = async () => {
 /* v8 ignore next -- @preserve */
 if (import.meta.url === `file://${process$1.argv[1]}`) await start();
 //#endregion
-export { MockHttp as default, MockHttp as mockhttp, generateCertificate, generateCertificateFiles, start };
+export { BinManager, InMemoryBinStore, MockHttp as default, MockHttp as mockhttp, generateCertificate, generateCertificateFiles, start };