@usequark/quark-core 2.5.4

package/src/metrics.test.js

@@ -0,0 +1,380 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import {
+	appErrorsTotal,
+	Counter,
+	createMetrics,
+	Gauge,
+	Histogram,
+	httpRequestDuration,
+	httpRequestsInFlight,
+	httpRequestsTotal,
+	jobDuration,
+	jobQueueDepth,
+	jobsProcessedTotal,
+	MetricsRegistry,
+	metrics,
+} from "./metrics.js";
+
+describe("Metrics - Counter", () => {
+	test("increments by 1 by default", () => {
+		const registry = createMetrics();
+		const counter = registry.counter({
+			name: "test_counter",
+			help: "A test counter",
+		});
+
+		counter.inc();
+		counter.inc();
+		counter.inc();
+
+		const output = counter.serialize();
+		assert.ok(output.includes("test_counter 3"));
+	});
+
+	test("increments by custom value", () => {
+		const registry = createMetrics();
+		const counter = registry.counter({
+			name: "test_counter_custom",
+			help: "A test counter",
+		});
+
+		counter.inc({}, 5);
+		counter.inc({}, 3);
+
+		const output = counter.serialize();
+		assert.ok(output.includes("test_counter_custom 8"));
+	});
+
+	test("supports labels", () => {
+		const registry = createMetrics();
+		const counter = registry.counter({
+			name: "labeled_counter",
+			help: "Counter with labels",
+			labelNames: ["method", "status"],
+		});
+
+		counter.inc({ method: "GET", status: "200" });
+		counter.inc({ method: "POST", status: "201" });
+		counter.inc({ method: "GET", status: "200" }, 2);
+
+		const output = counter.serialize();
+		assert.ok(output.includes('{method="GET",status="200"} 3'));
+		assert.ok(output.includes('{method="POST",status="201"} 1'));
+	});
+
+	test("throws on negative increment", () => {
+		const registry = createMetrics();
+		const counter = registry.counter({
+			name: "no_neg",
+			help: "No negatives",
+		});
+
+		assert.throws(() => counter.inc({}, -1), /can only be incremented/);
+	});
+
+	test("reset clears all values", () => {
+		const registry = createMetrics();
+		const counter = registry.counter({
+			name: "reset_counter",
+			help: "Resettable",
+		});
+
+		counter.inc();
+		counter.inc();
+		counter.reset();
+
+		assert.strictEqual(counter.values.size, 0);
+	});
+
+	test("serializes with HELP and TYPE headers", () => {
+		const registry = createMetrics();
+		const counter = registry.counter({
+			name: "http_total",
+			help: "Total requests",
+		});
+
+		counter.inc();
+		const output = counter.serialize();
+
+		assert.ok(output.includes("# HELP http_total Total requests"));
+		assert.ok(output.includes("# TYPE http_total counter"));
+	});
+
+	test("escapes special characters in label values", () => {
+		const registry = createMetrics();
+		const counter = registry.counter({
+			name: "escaped_counter",
+			help: "Escaping test",
+			labelNames: ["path"],
+		});
+
+		counter.inc({ path: '/api/"test"' });
+		const output = counter.serialize();
+		assert.ok(output.includes('path="/api/\\"test\\""'));
+	});
+
+	test("escapes backslashes and newlines in label values", () => {
+		const registry = createMetrics();
+		const counter = registry.counter({
+			name: "escape_bs",
+			help: "Backslash test",
+			labelNames: ["msg"],
+		});
+
+		counter.inc({ msg: "line1\nline2" });
+		const output = counter.serialize();
+		assert.ok(output.includes('msg="line1\\nline2"'));
+	});
+});
+
+describe("Metrics - Gauge", () => {
+	test("set sets a specific value", () => {
+		const registry = createMetrics();
+		const gauge = registry.gauge({
+			name: "test_gauge",
+			help: "A test gauge",
+		});
+
+		gauge.set({}, 42);
+
+		const output = gauge.serialize();
+		assert.ok(output.includes("test_gauge 42"));
+	});
+
+	test("inc and dec adjust value", () => {
+		const registry = createMetrics();
+		const gauge = registry.gauge({
+			name: "in_flight",
+			help: "In-flight requests",
+		});
+
+		gauge.inc();
+		gauge.inc();
+		gauge.dec();
+
+		const output = gauge.serialize();
+		assert.ok(output.includes("in_flight 1"));
+	});
+
+	test("supports labels", () => {
+		const registry = createMetrics();
+		const gauge = registry.gauge({
+			name: "labeled_gauge",
+			help: "Gauge with labels",
+			labelNames: ["method"],
+		});
+
+		gauge.set({ method: "GET" }, 10);
+		gauge.set({ method: "POST" }, 5);
+
+		const output = gauge.serialize();
+		assert.ok(output.includes('{method="GET"} 10'));
+		assert.ok(output.includes('{method="POST"} 5'));
+	});
+
+	test("reset clears all values", () => {
+		const registry = createMetrics();
+		const gauge = registry.gauge({
+			name: "reset_gauge",
+			help: "Resettable",
+		});
+
+		gauge.set({}, 100);
+		gauge.reset();
+
+		assert.strictEqual(gauge.values.size, 0);
+	});
+});
+
+describe("Metrics - Histogram", () => {
+	test("observe records values into buckets", () => {
+		const registry = createMetrics();
+		const hist = registry.histogram({
+			name: "request_duration",
+			help: "Duration of requests",
+			buckets: [0.01, 0.05, 0.1, 0.5, 1],
+		});
+
+		hist.observe({}, 0.03); // fits in 0.05, 0.1, 0.5, 1
+		hist.observe({}, 0.08); // fits in 0.1, 0.5, 1
+		hist.observe({}, 0.5); // fits in 0.5, 1
+
+		const output = hist.serialize();
+		assert.ok(output.includes('le="0.01"} 0'));
+		assert.ok(output.includes('le="0.05"} 1'));
+		assert.ok(output.includes('le="0.1"} 2'));
+		assert.ok(output.includes('le="0.5"} 3'));
+		assert.ok(output.includes('le="1"} 3'));
+		assert.ok(output.includes('le="+Inf"} 3'));
+		assert.ok(output.includes("_count 3"));
+	});
+
+	test("startTimer records elapsed time", async () => {
+		const registry = createMetrics();
+		const hist = registry.histogram({
+			name: "timer_test",
+			help: "Timer test",
+			buckets: [0.001, 0.01, 0.1, 1, 10],
+		});
+
+		const stop = hist.startTimer({ path: "/test" });
+		// 50ms delay ensures measurable time across all system loads
+		await new Promise((resolve) => setTimeout(resolve, 50));
+		const elapsed = stop();
+
+		assert.ok(elapsed > 0, "Elapsed time should be positive");
+		assert.ok(elapsed < 5, "Elapsed time should be less than 5 seconds");
+
+		const output = hist.serialize();
+		assert.ok(output.includes("timer_test_count"));
+		assert.ok(output.includes("timer_test_sum"));
+	});
+
+	test("supports labels on histogram", () => {
+		const registry = createMetrics();
+		const hist = registry.histogram({
+			name: "labeled_hist",
+			help: "Labeled histogram",
+			labelNames: ["method"],
+			buckets: [0.1, 1],
+		});
+
+		hist.observe({ method: "GET" }, 0.05);
+		hist.observe({ method: "POST" }, 0.5);
+
+		const output = hist.serialize();
+		assert.ok(output.includes('method="GET"'));
+		assert.ok(output.includes('method="POST"'));
+	});
+
+	test("uses default buckets when none provided", () => {
+		const registry = createMetrics();
+		const hist = registry.histogram({
+			name: "default_buckets",
+			help: "Default buckets test",
+		});
+
+		hist.observe({}, 0.05);
+		const output = hist.serialize();
+
+		// Default buckets include 0.005, 0.01, 0.025, 0.05, etc.
+		assert.ok(output.includes('le="0.005"'));
+		assert.ok(output.includes('le="10"'));
+	});
+});
+
+describe("Metrics - Registry", () => {
+	test("createMetrics returns a new registry", () => {
+		const registry = createMetrics();
+		assert.ok(registry instanceof MetricsRegistry);
+		assert.strictEqual(registry.size, 0);
+	});
+
+	test("registers and retrieves metrics", () => {
+		const registry = createMetrics();
+		const counter = registry.counter({ name: "my_counter", help: "test" });
+		const gauge = registry.gauge({ name: "my_gauge", help: "test" });
+		const hist = registry.histogram({ name: "my_hist", help: "test" });
+
+		assert.strictEqual(registry.size, 3);
+		assert.strictEqual(registry.get("my_counter"), counter);
+		assert.strictEqual(registry.get("my_gauge"), gauge);
+		assert.strictEqual(registry.get("my_hist"), hist);
+	});
+
+	test("returns existing metric if name already registered", () => {
+		const registry = createMetrics();
+		const first = registry.counter({ name: "dup", help: "first" });
+		const second = registry.counter({ name: "dup", help: "second" });
+
+		assert.strictEqual(first, second);
+		assert.strictEqual(registry.size, 1);
+	});
+
+	test("serialize outputs all metrics in Prometheus format", () => {
+		const registry = createMetrics();
+		const counter = registry.counter({ name: "req_total", help: "Total reqs" });
+		const gauge = registry.gauge({ name: "active", help: "Active conns" });
+
+		counter.inc({}, 10);
+		gauge.set({}, 5);
+
+		const output = registry.serialize();
+		assert.ok(output.includes("# HELP req_total Total reqs"));
+		assert.ok(output.includes("# TYPE req_total counter"));
+		assert.ok(output.includes("req_total 10"));
+		assert.ok(output.includes("# HELP active Active conns"));
+		assert.ok(output.includes("# TYPE active gauge"));
+		assert.ok(output.includes("active 5"));
+	});
+
+	test("resetAll clears all metric values", () => {
+		const registry = createMetrics();
+		const counter = registry.counter({ name: "c", help: "test" });
+		const gauge = registry.gauge({ name: "g", help: "test" });
+
+		counter.inc({}, 5);
+		gauge.set({}, 10);
+		registry.resetAll();
+
+		const output = registry.serialize();
+		assert.ok(!output.includes("c 5"));
+		assert.ok(!output.includes("g 10"));
+	});
+
+	test("get returns undefined for unknown metric", () => {
+		const registry = createMetrics();
+		assert.strictEqual(registry.get("nonexistent"), undefined);
+	});
+});
+
+describe("Metrics - Default instance", () => {
+	test("default metrics registry exists", () => {
+		assert.ok(metrics instanceof MetricsRegistry);
+	});
+
+	test("pre-registered HTTP metrics exist", () => {
+		assert.ok(httpRequestsTotal instanceof Counter);
+		assert.ok(httpRequestDuration instanceof Histogram);
+		assert.ok(httpRequestsInFlight instanceof Gauge);
+		assert.ok(appErrorsTotal instanceof Counter);
+	});
+
+	test("pre-registered queue metrics exist", () => {
+		assert.ok(jobQueueDepth instanceof Gauge);
+		assert.ok(jobsProcessedTotal instanceof Counter);
+		assert.ok(jobDuration instanceof Histogram);
+	});
+
+	test("pre-registered metrics are in the default registry", () => {
+		assert.strictEqual(metrics.get("http_requests_total"), httpRequestsTotal);
+		assert.strictEqual(
+			metrics.get("http_request_duration_seconds"),
+			httpRequestDuration,
+		);
+		assert.strictEqual(
+			metrics.get("http_requests_in_flight"),
+			httpRequestsInFlight,
+		);
+		assert.strictEqual(metrics.get("app_errors_total"), appErrorsTotal);
+	});
+
+	test("pre-registered queue metrics are in the default registry", () => {
+		assert.strictEqual(metrics.get("job_queue_depth"), jobQueueDepth);
+		assert.strictEqual(metrics.get("jobs_processed_total"), jobsProcessedTotal);
+		assert.strictEqual(metrics.get("job_duration_seconds"), jobDuration);
+	});
+
+	test("queue metrics have correct label names", () => {
+		assert.deepStrictEqual(jobQueueDepth.labelNames, ["queue"]);
+		assert.deepStrictEqual(jobsProcessedTotal.labelNames, ["queue", "status"]);
+		assert.deepStrictEqual(jobDuration.labelNames, ["queue", "name"]);
+	});
+
+	test("jobDuration uses job-appropriate buckets", () => {
+		// Buckets should cover sub-second to 5-minute range
+		assert.ok(jobDuration.buckets.includes(0.1));
+		assert.ok(jobDuration.buckets.includes(300));
+	});
+});

package/src/multipart.js

@@ -0,0 +1,144 @@
+/**
+ * @techstream/quark-core - Multipart Parser
+ *
+ * Stream-based multipart/form-data parsing with early limit enforcement.
+ * Works with Next.js App Router Request objects.
+ */
+
+import { Readable } from "node:stream";
+
+/**
+ * @typedef {Object} ParsedFile
+ * @property {string} fieldName - Form field name
+ * @property {string} filename - Original filename
+ * @property {string} mimeType - MIME type from Content-Type header
+ * @property {Buffer} buffer - Complete file content
+ * @property {number} size - File size in bytes
+ */
+
+/**
+ * @typedef {Object} ParseMultipartOptions
+ * @property {number} [maxFileSize=10485760] - Max file size in bytes (default: 10MB)
+ * @property {number} [maxFiles=5] - Max number of files per request
+ * @property {number} [maxFields=20] - Max number of non-file fields
+ */
+
+/**
+ * @typedef {Object} ParseMultipartResult
+ * @property {ParsedFile[]} files - Parsed file uploads
+ * @property {Record<string, string>} fields - Non-file form fields
+ */
+
+/**
+ * Parse a multipart/form-data request into files and fields.
+ *
+ * @param {Request} request - Web API Request (Next.js App Router)
+ * @param {ParseMultipartOptions} [options]
+ * @returns {Promise<ParseMultipartResult>}
+ */
+export async function parseMultipart(request, options = {}) {
+	const {
+		maxFileSize = 10 * 1024 * 1024,
+		maxFiles = 5,
+		maxFields = 20,
+	} = options;
+
+	const contentType = request.headers.get("content-type");
+	if (!contentType?.includes("multipart/form-data")) {
+		throw new Error("Request is not multipart/form-data");
+	}
+
+	if (!request.body) {
+		throw new Error("Request body is empty");
+	}
+
+	const { default: Busboy } = await import("busboy");
+
+	return new Promise((resolve, reject) => {
+		const files = [];
+		const fields = {};
+		let settled = false;
+
+		function resolveOnce(result) {
+			if (settled) return;
+			settled = true;
+			resolve(result);
+		}
+
+		function rejectOnce(error) {
+			if (settled) return;
+			settled = true;
+			reject(error);
+		}
+
+		const busboy = Busboy({
+			headers: { "content-type": contentType },
+			limits: {
+				fileSize: maxFileSize,
+				files: maxFiles,
+				fields: maxFields,
+			},
+		});
+
+		busboy.on("file", (fieldName, stream, info) => {
+			const { filename, mimeType } = info;
+			const chunks = [];
+			let size = 0;
+			let truncated = false;
+
+			stream.on("data", (chunk) => {
+				size += chunk.length;
+				chunks.push(chunk);
+			});
+
+			stream.on("limit", () => {
+				truncated = true;
+				stream.resume();
+			});
+
+			stream.on("error", rejectOnce);
+
+			stream.on("end", () => {
+				if (truncated) {
+					rejectOnce(
+						new Error(
+							`File "${filename}" exceeds maximum size of ${(maxFileSize / (1024 * 1024)).toFixed(1)} MB`,
+						),
+					);
+					return;
+				}
+
+				files.push({
+					fieldName,
+					filename: filename || "unknown",
+					mimeType: mimeType || "application/octet-stream",
+					buffer: Buffer.concat(chunks),
+					size,
+				});
+			});
+		});
+
+		busboy.on("field", (name, value) => {
+			fields[name] = value;
+		});
+
+		busboy.on("filesLimit", () => {
+			rejectOnce(
+				new Error(`Request exceeds maximum file count of ${maxFiles}`),
+			);
+		});
+
+		busboy.on("fieldsLimit", () => {
+			rejectOnce(
+				new Error(`Request exceeds maximum field count of ${maxFields}`),
+			);
+		});
+
+		busboy.on("error", rejectOnce);
+		busboy.on("close", () => resolveOnce({ files, fields }));
+
+		const nodeStream = Readable.fromWeb(request.body);
+		nodeStream.on("error", rejectOnce);
+		nodeStream.pipe(busboy);
+	});
+}

package/src/multipart.test.js

@@ -0,0 +1,188 @@
+import assert from "node:assert";
+import { test } from "node:test";
+import { parseMultipart } from "../src/multipart.js";
+
+// ---------------------------------------------------------------------------
+// Helper: build a multipart/form-data body from parts
+// ---------------------------------------------------------------------------
+
+function buildMultipartBody(boundary, parts) {
+	const lines = [];
+	for (const part of parts) {
+		lines.push(`--${boundary}`);
+		if (part.filename) {
+			lines.push(
+				`Content-Disposition: form-data; name="${part.name}"; filename="${part.filename}"`,
+			);
+			lines.push(
+				`Content-Type: ${part.contentType || "application/octet-stream"}`,
+			);
+		} else {
+			lines.push(`Content-Disposition: form-data; name="${part.name}"`);
+		}
+		lines.push("");
+		lines.push(part.value);
+	}
+	lines.push(`--${boundary}--`);
+	return lines.join("\r\n");
+}
+
+function createMultipartRequest(parts, boundary = "----TestBoundary") {
+	const body = buildMultipartBody(boundary, parts);
+	return new Request("http://localhost/upload", {
+		method: "POST",
+		headers: {
+			"content-type": `multipart/form-data; boundary=${boundary}`,
+		},
+		body,
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+test("Multipart - parses single file upload", async () => {
+	const request = createMultipartRequest([
+		{
+			name: "file",
+			filename: "test.txt",
+			contentType: "text/plain",
+			value: "hello world",
+		},
+	]);
+
+	const result = await parseMultipart(request);
+	assert.strictEqual(result.files.length, 1);
+	assert.strictEqual(result.files[0].filename, "test.txt");
+	assert.strictEqual(result.files[0].mimeType, "text/plain");
+	assert.strictEqual(result.files[0].buffer.toString(), "hello world");
+	assert.strictEqual(result.files[0].size, 11);
+	assert.strictEqual(result.files[0].fieldName, "file");
+});
+
+test("Multipart - parses text fields", async () => {
+	const request = createMultipartRequest([
+		{ name: "title", value: "My Upload" },
+		{ name: "description", value: "A test file" },
+	]);
+
+	const result = await parseMultipart(request);
+	assert.strictEqual(result.files.length, 0);
+	assert.strictEqual(result.fields.title, "My Upload");
+	assert.strictEqual(result.fields.description, "A test file");
+});
+
+test("Multipart - parses mixed files and fields", async () => {
+	const request = createMultipartRequest([
+		{ name: "title", value: "Photo" },
+		{
+			name: "file",
+			filename: "photo.jpg",
+			contentType: "image/jpeg",
+			value: "jpeg-data",
+		},
+	]);
+
+	const result = await parseMultipart(request);
+	assert.strictEqual(result.files.length, 1);
+	assert.strictEqual(result.files[0].filename, "photo.jpg");
+	assert.strictEqual(result.fields.title, "Photo");
+});
+
+test("Multipart - parses multiple files", async () => {
+	const request = createMultipartRequest([
+		{
+			name: "files",
+			filename: "a.txt",
+			contentType: "text/plain",
+			value: "aaa",
+		},
+		{
+			name: "files",
+			filename: "b.txt",
+			contentType: "text/plain",
+			value: "bbb",
+		},
+	]);
+
+	const result = await parseMultipart(request);
+	assert.strictEqual(result.files.length, 2);
+	assert.strictEqual(result.files[0].filename, "a.txt");
+	assert.strictEqual(result.files[1].filename, "b.txt");
+});
+
+test("Multipart - rejects non-multipart request", async () => {
+	const request = new Request("http://localhost/upload", {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: "{}",
+	});
+
+	await assert.rejects(
+		() => parseMultipart(request),
+		/not multipart\/form-data/,
+	);
+});
+
+test("Multipart - rejects request with no body", async () => {
+	const request = new Request("http://localhost/upload", {
+		method: "POST",
+		headers: {
+			"content-type": "multipart/form-data; boundary=test",
+		},
+	});
+
+	await assert.rejects(() => parseMultipart(request), /body is empty/);
+});
+
+test("Multipart - rejects file exceeding maxFileSize", async () => {
+	const largeContent = "x".repeat(1024);
+	const request = createMultipartRequest([
+		{
+			name: "file",
+			filename: "big.txt",
+			contentType: "text/plain",
+			value: largeContent,
+		},
+	]);
+
+	await assert.rejects(
+		() => parseMultipart(request, { maxFileSize: 100 }),
+		/exceeds maximum size/,
+	);
+});
+
+test("Multipart - rejects request exceeding maxFiles", async () => {
+	const request = createMultipartRequest([
+		{
+			name: "files",
+			filename: "a.txt",
+			contentType: "text/plain",
+			value: "aaa",
+		},
+		{
+			name: "files",
+			filename: "b.txt",
+			contentType: "text/plain",
+			value: "bbb",
+		},
+	]);
+
+	await assert.rejects(
+		() => parseMultipart(request, { maxFiles: 1 }),
+		/maximum file count/,
+	);
+});
+
+test("Multipart - rejects request exceeding maxFields", async () => {
+	const request = createMultipartRequest([
+		{ name: "title", value: "My Upload" },
+		{ name: "description", value: "A test file" },
+	]);
+
+	await assert.rejects(
+		() => parseMultipart(request, { maxFields: 1 }),
+		/maximum field count/,
+	);
+});