@usequark/quark-create-app 1.23.11

package/templates/config/src/load-config.js

@@ -0,0 +1,157 @@
+/**
+ * @techstream/quark-config - Configuration Loader
+ * Centralised configuration management that combines environment validation,
+ * environment-specific defaults, and user overrides into a single config object.
+ *
+ * Usage:
+ *   import { loadConfig } from "@techstream/quark-config";
+ *   const config = loadConfig();          // validates env + returns typed config
+ *   const config = loadConfig({ cache: { defaultTtl: 120 } }); // with overrides
+ */
+
+import { getAllowedOrigins, getAppUrl } from "./app-url.js";
+import { getEnvironmentConfig, mergeConfig } from "./environment.js";
+import { validateEnv } from "./validate-env.js";
+
+/** @type {import("./environment.js").EnvironmentConfig | null} */
+let cachedConfig = null;
+
+/**
+ * Loads the full application configuration.
+ *
+ * 1. Validates all required environment variables (throws on failure).
+ * 2. Resolves the current environment (dev/test/staging/production).
+ * 3. Merges environment-specific defaults with any user overrides.
+ * 4. Enriches with computed values (APP_URL, allowed origins, ports).
+ * 5. Caches the result - subsequent calls return the same object.
+ *
+ * @param {Record<string, unknown>} [overrides] - Optional partial overrides
+ * @param {Object} [options]
+ * @param {boolean} [options.fresh=false] - Force re-computation (bypass cache)
+ * @returns {import("./environment.js").EnvironmentConfig & { appUrl: string, allowedOrigins: string[], validated: Record<string, string> }}
+ */
+export function loadConfig(overrides = {}, options = {}) {
+	if (cachedConfig && !options.fresh) {
+		return cachedConfig;
+	}
+
+	// Step 1: Validate environment variables
+	const { validated } = validateEnv();
+
+	// Step 2: Resolve environment and get defaults
+	const envConfig = getEnvironmentConfig();
+
+	// Step 3: Apply env-var driven overrides
+	const envOverrides = buildEnvOverrides(envConfig);
+
+	// Step 4: Merge: env defaults → env-var overrides → user overrides
+	let config = mergeConfig(envConfig, envOverrides);
+	config = mergeConfig(config, overrides);
+
+	// Step 5: Attach computed values
+	config.appUrl = getAppUrl();
+	config.allowedOrigins = getAllowedOrigins();
+	config.validated = validated;
+
+	cachedConfig = config;
+	return config;
+}
+
+/**
+ * Clears the cached configuration. Useful in tests.
+ */
+export function resetConfig() {
+	cachedConfig = null;
+}
+
+/**
+ * Returns the cached configuration if already loaded, otherwise null.
+ * Does NOT trigger validation - use `loadConfig()` for that.
+ * @returns {ReturnType<typeof loadConfig> | null}
+ */
+export function getConfig() {
+	return cachedConfig;
+}
+
+/**
+ * Reads specific environment variables and converts them to config overrides.
+ * This allows env vars to take precedence over environment defaults.
+ *
+ * @param {import("./environment.js").EnvironmentConfig} envConfig
+ * @returns {Record<string, unknown>}
+ */
+function buildEnvOverrides(_envConfig) {
+	const overrides = {};
+
+	// Server
+	if (process.env.PORT) {
+		const port = Number.parseInt(process.env.PORT, 10);
+		if (!Number.isNaN(port)) overrides.server = { port };
+	}
+
+	// Rate limiting
+	if (process.env.RATE_LIMIT_MAX) {
+		const maxRequests = Number.parseInt(process.env.RATE_LIMIT_MAX, 10);
+		if (!Number.isNaN(maxRequests)) {
+			overrides.rateLimit = { ...overrides.rateLimit, maxRequests };
+		}
+	}
+	if (process.env.RATE_LIMIT_WINDOW_MS) {
+		const windowMs = Number.parseInt(process.env.RATE_LIMIT_WINDOW_MS, 10);
+		if (!Number.isNaN(windowMs)) {
+			overrides.rateLimit = { ...overrides.rateLimit, windowMs };
+		}
+	}
+
+	// Cache
+	if (process.env.CACHE_TTL) {
+		const defaultTtl = Number.parseInt(process.env.CACHE_TTL, 10);
+		if (!Number.isNaN(defaultTtl)) overrides.cache = { defaultTtl };
+	}
+
+	// Logging
+	if (process.env.LOG_LEVEL) {
+		overrides.logging = { ...overrides.logging, level: process.env.LOG_LEVEL };
+	}
+
+	// Authentication
+	if (process.env.AUTH_ALLOW_SIGNUP) {
+		const allowSignup = parseBooleanEnv(process.env.AUTH_ALLOW_SIGNUP);
+		if (allowSignup !== undefined) {
+			overrides.auth = { ...overrides.auth, allowSignup };
+		}
+	}
+
+	// Database pool
+	if (process.env.DB_POOL_MAX) {
+		const poolMax = Number.parseInt(process.env.DB_POOL_MAX, 10);
+		if (!Number.isNaN(poolMax)) {
+			overrides.db = { ...overrides.db, poolMax };
+		}
+	}
+	if (process.env.DB_POOL_IDLE_TIMEOUT) {
+		const poolIdleTimeout = Number.parseInt(
+			process.env.DB_POOL_IDLE_TIMEOUT,
+			10,
+		);
+		if (!Number.isNaN(poolIdleTimeout)) {
+			overrides.db = { ...overrides.db, poolIdleTimeout };
+		}
+	}
+
+	return overrides;
+}
+
+function parseBooleanEnv(value) {
+	const normalized = value.trim().toLowerCase();
+
+	if (["true", "1", "yes", "on"].includes(normalized)) {
+		return true;
+	}
+
+	if (["false", "0", "no", "off"].includes(normalized)) {
+		return false;
+	}
+
+	return undefined;
+}

package/templates/config/src/rate-limit.js

@@ -0,0 +1,136 @@
+/**
+ * Sliding window rate limiter using Redis sorted sets.
+ * Provides distributed rate limiting across server instances.
+ * Falls back gracefully if Redis is unavailable (fail-open).
+ */
+
+import { getSharedRedisClient } from "./redis.js";
+
+/**
+ * Sliding window rate limiter using Redis sorted sets.
+ * Each request is scored by its timestamp, and expired entries are pruned on each call.
+ * TTL on the key ensures automatic cleanup of old data.
+ *
+ * @param {string} key - Unique key for the rate limit (e.g., `chat:userId`)
+ * @param {number} limit - Max requests per window
+ * @param {number} windowMs - Window size in milliseconds (default: 60000 = 1 min)
+ * @returns {Promise<{ allowed: boolean, remaining: number, reset: number }>}
+ */
+export async function rateLimit(key, limit = 10, windowMs = 60000) {
+	const now = Date.now();
+	const windowStart = now - windowMs;
+
+	try {
+		const client = await getSharedRedisClient();
+		if (!client) {
+			// Fail open - Redis unavailable
+			return {
+				allowed: true,
+				remaining: limit,
+				reset: Math.ceil((now + windowMs) / 1000),
+			};
+		}
+
+		const redisKey = `ratelimit:${key}`;
+
+		// Pipeline: remove expired entries, count, optionally add request
+		// We use a Lua script for atomicity
+		const luaScript = `
+			local key = KEYS[1]
+			local window_start = tonumber(ARGV[1])
+			local now = tonumber(ARGV[2])
+			local limit = tonumber(ARGV[3])
+			local window_ms = tonumber(ARGV[4])
+			local window_end = now + window_ms
+
+			-- Remove entries outside the window
+			redis.call('ZREMRANGEBYSCORE', key, 0, window_start)
+
+			-- Count remaining entries in window
+			local count = redis.call('ZCARD', key)
+
+			if count >= limit then
+				-- Rate limited - return oldest entry for reset calculation
+				local oldest = redis.call('ZRANGE', key, 0, 0, 'WITHSCORES')
+				local reset_time = window_end
+				if #oldest >= 2 then
+					reset_time = tonumber(oldest[2]) + window_ms
+				end
+				return {0, 0, reset_time}
+			end
+
+			-- Add current request (score = timestamp, member = unique)
+			local member = now .. ':' .. math.random(1000000)
+			redis.call('ZADD', key, now, member)
+
+			-- Set TTL on the key for automatic cleanup
+			redis.call('PEXPIRE', key, window_ms + 1000)
+
+			local remaining = limit - count - 1
+			local reset_time = window_end
+
+			return {1, remaining, reset_time}
+		`;
+
+		const [allowed, remaining, reset] = await client.eval(
+			luaScript,
+			1,
+			redisKey,
+			windowStart,
+			now,
+			limit,
+			windowMs,
+		);
+
+		return {
+			allowed: allowed === 1,
+			remaining,
+			reset: Math.ceil(reset / 1000),
+		};
+	} catch {
+		// Fail open - Redis error
+		return {
+			allowed: true,
+			remaining: limit,
+			reset: Math.ceil((now + windowMs) / 1000),
+		};
+	}
+}
+
+/**
+ * Apply rate limiting to a Next.js API route request.
+ * Returns a 429 Response if rate limited, or null if the request is allowed.
+ * Includes rate limit headers in the returned response.
+ *
+ * @param {string} identifier - Unique identifier (userId or IP)
+ * @param {object} options - { limit, windowMs, route }
+ * @returns {Promise<Response | null>}
+ */
+export async function applyRateLimit(identifier, options = {}) {
+	const { limit = 10, windowMs = 60000, route = "default" } = options;
+	const key = `${route}:${identifier}`;
+
+	const result = await rateLimit(key, limit, windowMs);
+
+	if (!result.allowed) {
+		const retryAfter = Math.max(0, result.reset - Math.ceil(Date.now() / 1000));
+		return new Response(
+			JSON.stringify({
+				error: "Rate limit exceeded. Please try again later.",
+				retryAfter,
+			}),
+			{
+				status: 429,
+				headers: {
+					"Content-Type": "application/json",
+					"X-RateLimit-Limit": String(limit),
+					"X-RateLimit-Remaining": "0",
+					"X-RateLimit-Reset": String(result.reset),
+					"Retry-After": String(retryAfter),
+				},
+			},
+		);
+	}
+
+	return null;
+}

package/templates/config/src/redis.js

@@ -0,0 +1,43 @@
+import { resolveRedisConnection } from "@techstream/quark-core";
+
+let _redis = null;
+
+/**
+ * Get a shared Redis client. Creates and connects on first call, reuses thereafter.
+ * Returns null if Redis is unavailable (fail-open).
+ *
+ * @returns {Promise<import("ioredis").default | null>}
+ */
+export async function getSharedRedisClient() {
+	if (_redis) return _redis;
+	try {
+		const conn = resolveRedisConnection();
+		const { default: Redis } = await import("ioredis");
+		_redis = new Redis({
+			...conn,
+			lazyConnect: true,
+			maxRetriesPerRequest: 0,
+			enableReadyCheck: false,
+		});
+		_redis.on("error", () => {}); // Suppress errors
+		await _redis.connect();
+		return _redis;
+	} catch {
+		await closeSharedRedisClient();
+		return null;
+	}
+}
+
+/**
+ * Close the shared Redis client (for graceful shutdown).
+ */
+export async function closeSharedRedisClient() {
+	if (_redis) {
+		try {
+			await _redis.disconnect();
+		} catch {
+			// ignore disconnect errors
+		}
+		_redis = null;
+	}
+}