@usequark/quark-core 2.5.4

package/src/rate-limiter.test.js

@@ -0,0 +1,130 @@
+import assert from "node:assert";
+import { test } from "node:test";
+import {
+	createRateLimiter,
+	createRateLimitMiddleware,
+	RATE_LIMIT_PRESETS,
+} from "../src/rate-limiter.js";
+
+test("Rate Limiter Module", async (t) => {
+	await t.test("createRateLimiter creates memory limiter by default", () => {
+		const limiter = createRateLimiter();
+		assert(limiter !== null);
+	});
+
+	await t.test(
+		"createRateLimiter throws error for Redis without client",
+		() => {
+			assert.throws(
+				() => createRateLimiter({ type: "redis" }),
+				/Redis client is required/,
+			);
+		},
+	);
+
+	await t.test("Memory rate limiter allows requests under limit", async () => {
+		const limiter = createRateLimiter({ type: "memory" });
+		const result = await limiter.checkLimit("test-key", 5, 60000);
+
+		assert.strictEqual(result.limited, false);
+		assert.strictEqual(result.remaining, 4);
+		assert(result.resetTime > Date.now());
+	});
+
+	await t.test("Memory rate limiter blocks requests over limit", async () => {
+		const limiter = createRateLimiter({ type: "memory" });
+
+		// Make 5 requests (limit is 5)
+		for (let i = 0; i < 5; i++) {
+			await limiter.checkLimit("test-key-2", 5, 60000);
+		}
+
+		// 6th request should be blocked
+		const result = await limiter.checkLimit("test-key-2", 5, 60000);
+		assert.strictEqual(result.limited, true);
+		assert.strictEqual(result.remaining, 0);
+	});
+
+	await t.test("Memory rate limiter resets after window", async () => {
+		const limiter = createRateLimiter({ type: "memory" });
+
+		// Make a request with very short window
+		const result1 = await limiter.checkLimit("test-key-3", 1, 10);
+		assert.strictEqual(result1.limited, false);
+
+		// Second request should be blocked
+		const result2 = await limiter.checkLimit("test-key-3", 1, 10);
+		assert.strictEqual(result2.limited, true);
+
+		// Wait for window to expire
+		await new Promise((resolve) => setTimeout(resolve, 20));
+
+		// Should be allowed again
+		const result3 = await limiter.checkLimit("test-key-3", 1, 10);
+		assert.strictEqual(result3.limited, false);
+	});
+
+	await t.test("Memory rate limiter can reset a key", async () => {
+		const limiter = createRateLimiter({ type: "memory" });
+
+		await limiter.checkLimit("test-key-4", 1, 60000);
+		await limiter.reset("test-key-4");
+
+		const result = await limiter.checkLimit("test-key-4", 1, 60000);
+		assert.strictEqual(result.limited, false);
+	});
+
+	await t.test("Memory rate limiter can clear all keys", async () => {
+		const limiter = createRateLimiter({ type: "memory" });
+
+		await limiter.checkLimit("key-1", 1, 60000);
+		await limiter.checkLimit("key-2", 1, 60000);
+		await limiter.clear();
+
+		const result1 = await limiter.checkLimit("key-1", 1, 60000);
+		const result2 = await limiter.checkLimit("key-2", 1, 60000);
+
+		assert.strictEqual(result1.limited, false);
+		assert.strictEqual(result2.limited, false);
+	});
+
+	await t.test("RATE_LIMIT_PRESETS have correct structure", () => {
+		assert(RATE_LIMIT_PRESETS.strict);
+		assert(RATE_LIMIT_PRESETS.moderate);
+		assert(RATE_LIMIT_PRESETS.relaxed);
+		assert(RATE_LIMIT_PRESETS.auth);
+		assert(RATE_LIMIT_PRESETS.api);
+
+		assert.strictEqual(RATE_LIMIT_PRESETS.auth.maxRequests, 5);
+		assert.strictEqual(RATE_LIMIT_PRESETS.api.maxRequests, 100);
+	});
+
+	await t.test("createRateLimitMiddleware returns a function", () => {
+		const limiter = createRateLimiter({ type: "memory" });
+		const middleware = createRateLimitMiddleware(limiter);
+
+		assert.strictEqual(typeof middleware, "function");
+	});
+
+	await t.test("createRateLimitMiddleware works with API preset", async () => {
+		const limiter = createRateLimiter({ type: "memory" });
+		const middleware = createRateLimitMiddleware(
+			limiter,
+			RATE_LIMIT_PRESETS.api,
+		);
+
+		const result = await middleware("192.168.1.1", "/api/posts");
+
+		assert.strictEqual(result.limited, false);
+		assert(result.remaining > 0);
+	});
+
+	await t.test("Cleanup interval is started for memory limiter", () => {
+		const limiter = createRateLimiter({ type: "memory" });
+		assert(limiter.cleanupInterval !== null);
+
+		// Clean up
+		limiter.stopCleanup();
+		assert(limiter.cleanupInterval === null);
+	});
+});

package/src/redis.js

@@ -0,0 +1,154 @@
+/**
+ * Builds REDIS_URL from individual environment variables if not explicitly provided.
+ * Allows configuration via individual REDIS_* vars instead of a single REDIS_URL.
+ */
+function getRedisUrl() {
+	if (process.env.REDIS_URL) {
+		return process.env.REDIS_URL;
+	}
+
+	const host = process.env.REDIS_HOST || "localhost";
+	const port = process.env.REDIS_PORT || "6379";
+
+	return `redis://${host}:${port}`;
+}
+
+/**
+ * Creates a Redis configuration object from environment variables.
+ * Returns the URL and any additional options - does not create an actual connection.
+ * Pass the URL to your Redis library of choice (e.g., ioredis).
+ *
+ * @deprecated Use `resolveRedisConnection` for ioredis/BullMQ configs, or `getRedisUrl` for URL strings.
+ */
+export const createRedisConfig = (options = {}) => {
+	const redisUrl = getRedisUrl();
+
+	return {
+		url: redisUrl,
+		...options,
+	};
+};
+
+/**
+ * @deprecated Use `resolveRedisConnection` instead.
+ */
+export const createRedisClient = createRedisConfig;
+
+/**
+ * Pings Redis to verify connectivity.
+ * Dynamically imports ioredis so it doesn't fail at load time if the package is not installed.
+ * Creates a temporary connection, sends PING, expects PONG, then disconnects.
+ *
+ * @param {object} [options]
+ * @param {number} [options.timeout=3000] - Connection/ping timeout in milliseconds.
+ * @returns {Promise<{ status: "ok", latencyMs: number } | { status: "error", message: string }>}
+ */
+export async function pingRedis({ timeout = 3000 } = {}) {
+	/** @type {import("ioredis").default | null} */
+	let client = null;
+
+	try {
+		const { default: Redis } = await import("ioredis");
+
+		const conn = resolveRedisConnection();
+
+		client = new Redis({
+			...conn,
+			lazyConnect: true,
+			connectTimeout: timeout,
+			maxRetriesPerRequest: 0,
+			enableReadyCheck: false,
+		});
+
+		// Suppress the "Unhandled error event" stderr noise that ioredis emits
+		// when a connection attempt fails. The error is still caught by the
+		// try/catch below - this listener just prevents Node from treating it
+		// as an unhandled EventEmitter error.
+		client.on("error", () => {});
+
+		await client.connect();
+
+		const start = performance.now();
+		const result = await new Promise((resolve, reject) => {
+			const timer = setTimeout(
+				() => reject(new Error("PING timed out")),
+				timeout,
+			);
+			client.ping().then(
+				(val) => {
+					clearTimeout(timer);
+					resolve(val);
+				},
+				(err) => {
+					clearTimeout(timer);
+					reject(err);
+				},
+			);
+		});
+
+		const latencyMs = Math.round(performance.now() - start);
+
+		if (result !== "PONG") {
+			return {
+				status: "error",
+				message: `Unexpected PING response: ${result}`,
+			};
+		}
+
+		return { status: "ok", latencyMs };
+	} catch (/** @type {any} */ error) {
+		let message;
+		if (
+			error?.code === "MODULE_NOT_FOUND" ||
+			error?.code === "ERR_MODULE_NOT_FOUND"
+		) {
+			message = "ioredis is not installed";
+		} else if (
+			error?.code === "ECONNREFUSED" ||
+			/connection is closed|ECONNREFUSED/i.test(error?.message ?? "")
+		) {
+			message = `Redis unreachable at ${getRedisUrl()}`;
+		} else {
+			message = error?.message ?? String(error);
+		}
+		return { status: "error", message };
+	} finally {
+		try {
+			await client?.disconnect();
+		} catch {
+			// ignore disconnect errors
+		}
+	}
+}
+
+/**
+ * Resolves Redis connection config as an ioredis-compatible options object.
+ * Precedence: explicit override > REDIS_URL > REDIS_HOST/REDIS_PORT > localhost defaults.
+ *
+ * @param {object} [override] - if provided, returned as-is (pass-through for caller-supplied config)
+ * @returns {{ host: string, port: number, password?: string, tls?: object }}
+ */
+export function resolveRedisConnection(override) {
+	if (override) return override;
+
+	if (process.env.REDIS_URL) {
+		try {
+			const u = new URL(process.env.REDIS_URL);
+			return {
+				host: u.hostname,
+				port: parseInt(u.port || "6379", 10),
+				...(u.password && { password: decodeURIComponent(u.password) }),
+				...(u.protocol === "rediss:" && { tls: {} }),
+			};
+		} catch {
+			// Malformed REDIS_URL - fall through to host/port env vars
+		}
+	}
+
+	return {
+		host: process.env.REDIS_HOST || "localhost",
+		port: parseInt(process.env.REDIS_PORT || "6379", 10),
+	};
+}
+
+export { getRedisUrl };

package/src/redis.test.js

@@ -0,0 +1,150 @@
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import { getRedisUrl, resolveRedisConnection } from "./redis.js";
+
+describe("getRedisUrl", () => {
+	let originalEnv;
+
+	beforeEach(() => {
+		originalEnv = { ...process.env };
+	});
+
+	afterEach(() => {
+		process.env = originalEnv;
+	});
+
+	it("returns REDIS_URL when set", () => {
+		process.env.REDIS_URL = "redis://custom:6380";
+		delete process.env.REDIS_HOST;
+		delete process.env.REDIS_PORT;
+
+		assert.equal(getRedisUrl(), "redis://custom:6380");
+	});
+
+	it("builds URL from REDIS_HOST and REDIS_PORT", () => {
+		delete process.env.REDIS_URL;
+		process.env.REDIS_HOST = "myhost";
+		process.env.REDIS_PORT = "6381";
+
+		assert.equal(getRedisUrl(), "redis://myhost:6381");
+	});
+
+	it("defaults to localhost:6379", () => {
+		delete process.env.REDIS_URL;
+		delete process.env.REDIS_HOST;
+		delete process.env.REDIS_PORT;
+
+		assert.equal(getRedisUrl(), "redis://localhost:6379");
+	});
+
+	it("REDIS_URL takes precedence over REDIS_HOST/REDIS_PORT", () => {
+		process.env.REDIS_URL = "redis://from-url:9999";
+		process.env.REDIS_HOST = "from-host";
+		process.env.REDIS_PORT = "1111";
+
+		assert.equal(getRedisUrl(), "redis://from-url:9999");
+	});
+});
+
+describe("resolveRedisConnection", () => {
+	let originalEnv;
+
+	beforeEach(() => {
+		originalEnv = { ...process.env };
+	});
+
+	afterEach(() => {
+		process.env = originalEnv;
+	});
+
+	it("returns override as-is when provided", () => {
+		const override = { host: "custom", port: 1234 };
+		assert.deepEqual(resolveRedisConnection(override), override);
+	});
+
+	it("parses REDIS_URL into host/port", () => {
+		process.env.REDIS_URL = "redis://myredis:6380";
+		delete process.env.REDIS_HOST;
+		delete process.env.REDIS_PORT;
+
+		const result = resolveRedisConnection();
+		assert.equal(result.host, "myredis");
+		assert.equal(result.port, 6380);
+	});
+
+	it("parses password from REDIS_URL", () => {
+		process.env.REDIS_URL = "redis://:s3cret@myredis:6380";
+		delete process.env.REDIS_HOST;
+
+		const result = resolveRedisConnection();
+		assert.equal(result.host, "myredis");
+		assert.equal(result.port, 6380);
+		assert.equal(result.password, "s3cret");
+	});
+
+	it("decodes URL-encoded password", () => {
+		process.env.REDIS_URL = "redis://:p%40ss%3Aword@myredis:6380";
+		delete process.env.REDIS_HOST;
+
+		const result = resolveRedisConnection();
+		assert.equal(result.password, "p@ss:word");
+	});
+
+	it("sets tls for rediss:// protocol", () => {
+		process.env.REDIS_URL = "rediss://secure-host:6380";
+		delete process.env.REDIS_HOST;
+
+		const result = resolveRedisConnection();
+		assert.equal(result.host, "secure-host");
+		assert.deepEqual(result.tls, {});
+	});
+
+	it("defaults port to 6379 when REDIS_URL omits port", () => {
+		process.env.REDIS_URL = "redis://myredis";
+		delete process.env.REDIS_HOST;
+
+		const result = resolveRedisConnection();
+		assert.equal(result.port, 6379);
+	});
+
+	it("falls back to REDIS_HOST/REDIS_PORT when REDIS_URL is absent", () => {
+		delete process.env.REDIS_URL;
+		process.env.REDIS_HOST = "fallback-host";
+		process.env.REDIS_PORT = "7777";
+
+		const result = resolveRedisConnection();
+		assert.equal(result.host, "fallback-host");
+		assert.equal(result.port, 7777);
+		assert.equal(result.password, undefined);
+	});
+
+	it("defaults to localhost:6379 when no env vars are set", () => {
+		delete process.env.REDIS_URL;
+		delete process.env.REDIS_HOST;
+		delete process.env.REDIS_PORT;
+
+		const result = resolveRedisConnection();
+		assert.equal(result.host, "localhost");
+		assert.equal(result.port, 6379);
+	});
+
+	it("REDIS_URL takes precedence over REDIS_HOST/REDIS_PORT", () => {
+		process.env.REDIS_URL = "redis://url-host:8888";
+		process.env.REDIS_HOST = "host-var";
+		process.env.REDIS_PORT = "9999";
+
+		const result = resolveRedisConnection();
+		assert.equal(result.host, "url-host");
+		assert.equal(result.port, 8888);
+	});
+
+	it("falls back to REDIS_HOST/REDIS_PORT when REDIS_URL is malformed", () => {
+		process.env.REDIS_URL = "not-a-valid-url";
+		process.env.REDIS_HOST = "fallback-host";
+		process.env.REDIS_PORT = "6382";
+
+		const result = resolveRedisConnection();
+		assert.equal(result.host, "fallback-host");
+		assert.equal(result.port, 6382);
+	});
+});

package/src/request-logger.js

@@ -0,0 +1,211 @@
+/**
+ * Request/Response Logging Middleware
+ *
+ * Logs HTTP request and response details for debugging and auditing.
+ * Sanitizes sensitive data (passwords, tokens) from request bodies.
+ * Logs response bodies only for errors (4xx/5xx status codes).
+ */
+
+import { logger } from "./logger.js";
+
+/**
+ * Fields to sanitize from request bodies (replace with "[REDACTED]")
+ */
+const SENSITIVE_FIELDS = [
+	"password",
+	"token",
+	"secret",
+	"apiKey",
+	"api_key",
+	"authorization",
+	"passwordConfirmation",
+	"oldPassword",
+	"newPassword",
+	"currentPassword",
+];
+
+/**
+ * Recursively sanitize sensitive fields in an object
+ * @param {any} obj - Object to sanitize
+ * @param {string[]} fields - List of sensitive field names
+ * @returns {any} Sanitized object
+ */
+function sanitizeObject(obj, fields = SENSITIVE_FIELDS) {
+	if (!obj || typeof obj !== "object") {
+		return obj;
+	}
+
+	if (Array.isArray(obj)) {
+		return obj.map((item) => sanitizeObject(item, fields));
+	}
+
+	const sanitized = {};
+	for (const [key, value] of Object.entries(obj)) {
+		const keyLower = key.toLowerCase();
+		if (fields.some((field) => keyLower.includes(field.toLowerCase()))) {
+			sanitized[key] = "[REDACTED]";
+		} else if (typeof value === "object" && value !== null) {
+			sanitized[key] = sanitizeObject(value, fields);
+		} else {
+			sanitized[key] = value;
+		}
+	}
+	return sanitized;
+}
+
+/**
+ * Create request logger options
+ * @typedef {Object} RequestLoggerOptions
+ * @property {boolean} [logRequestBody=true] - Log request body
+ * @property {boolean} [logResponseBody=false] - Log response body for all requests
+ * @property {boolean} [logErrorResponseBody=true] - Log response body only for errors
+ * @property {string[]} [sensitiveFields] - Custom sensitive field names to sanitize
+ * @property {number} [maxBodyLength=1000] - Max characters to log from body (prevents massive logs)
+ */
+
+/**
+ * Create a request logger middleware for Next.js API routes
+ *
+ * @param {RequestLoggerOptions} [options={}] - Logging options
+ * @returns {Function} Middleware function
+ *
+ * @example
+ * import { createRequestLogger } from "@techstream/quark-core";
+ *
+ * const logRequest = createRequestLogger({
+ *   logRequestBody: true,
+ *   logErrorResponseBody: true,
+ * });
+ *
+ * export async function GET(request) {
+ *   return logRequest(request, async () => {
+ *     // Your handler logic
+ *     return NextResponse.json({ data: "..." });
+ *   });
+ * }
+ */
+export function createRequestLogger(options = {}) {
+	const {
+		logRequestBody = true,
+		logResponseBody = false,
+		logErrorResponseBody = true,
+		sensitiveFields = SENSITIVE_FIELDS,
+		maxBodyLength = 1000,
+	} = options;
+
+	return async (request, handler) => {
+		const startTime = Date.now();
+		const { method, url } = request;
+		const { pathname, searchParams } = new URL(url);
+
+		// Build log context
+		const logContext = {
+			method,
+			path: pathname,
+			query: Object.fromEntries(searchParams),
+			headers: {
+				"user-agent": request.headers.get("user-agent"),
+				"content-type": request.headers.get("content-type"),
+			},
+		};
+
+		// Log request body for non-GET requests
+		if (logRequestBody && method !== "GET" && method !== "HEAD") {
+			try {
+				// Clone request to read body without consuming it
+				const clonedRequest = request.clone();
+				const contentType = request.headers.get("content-type") || "";
+
+				if (contentType.includes("application/json")) {
+					const body = await clonedRequest.json();
+					const sanitized = sanitizeObject(body, sensitiveFields);
+					const bodyStr = JSON.stringify(sanitized);
+					logContext.body =
+						bodyStr.length > maxBodyLength
+							? `${bodyStr.substring(0, maxBodyLength)}... [truncated]`
+							: bodyStr;
+				} else if (contentType.includes("application/x-www-form-urlencoded")) {
+					const text = await clonedRequest.text();
+					const params = new URLSearchParams(text);
+					const paramsObj = Object.fromEntries(params);
+					const sanitized = sanitizeObject(paramsObj, sensitiveFields);
+					logContext.body = sanitized;
+				} else {
+					logContext.body = `[${contentType || "unknown content-type"}]`;
+				}
+			} catch (error) {
+				logContext.bodyError = error.message;
+			}
+		}
+
+		logger.info("Incoming request", logContext);
+
+		let response;
+		let responseError = null;
+
+		try {
+			// Execute the handler
+			response = await handler(request);
+		} catch (error) {
+			responseError = error;
+			throw error; // Re-throw to maintain error flow
+		} finally {
+			const duration = Date.now() - startTime;
+
+			const responseLog = {
+				method,
+				path: pathname,
+				duration: `${duration}ms`,
+			};
+
+			if (response) {
+				responseLog.status = response.status;
+
+				// Log response body for errors or if explicitly enabled
+				const isError = response.status >= 400;
+				const shouldLogBody =
+					logResponseBody || (logErrorResponseBody && isError);
+
+				if (shouldLogBody) {
+					try {
+						const clonedResponse = response.clone();
+						const contentType = response.headers.get("content-type") || "";
+
+						if (contentType.includes("application/json")) {
+							const body = await clonedResponse.json();
+							const bodyStr = JSON.stringify(body);
+							responseLog.body =
+								bodyStr.length > maxBodyLength
+									? `${bodyStr.substring(0, maxBodyLength)}... [truncated]`
+									: bodyStr;
+						}
+					} catch (error) {
+						responseLog.bodyError = error.message;
+					}
+				}
+
+				if (isError) {
+					logger.error("Request completed with error", responseLog);
+				} else {
+					logger.info("Request completed", responseLog);
+				}
+			} else if (responseError) {
+				responseLog.error = responseError.message;
+				responseLog.stack = responseError.stack;
+				logger.error("Request failed", responseLog);
+			}
+		}
+
+		return response;
+	};
+}
+
+/**
+ * Default request logger instance
+ */
+export const logRequest = createRequestLogger();
+
+/**
+ * Export sanitization utility for standalone use
+ */
+export { sanitizeObject };