@pyreon/zero 0.12.2 → 0.12.4

package/lib/og-image.js

@@ -0,0 +1,233 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+//#region src/og-image.ts
+/**
+* OG Image generation plugin.
+*
+* Generates Open Graph images at build time from templates with
+* text overlays. Supports locale-specific text for i18n apps.
+* Uses sharp for image processing (same optional dep as favicon/image plugins).
+*
+* @example
+* ```ts
+* // vite.config.ts
+* import { ogImagePlugin } from "@pyreon/zero/og-image"
+*
+* export default {
+*   plugins: [
+*     ogImagePlugin({
+*       locales: ["en", "de", "cs"],
+*       templates: [{
+*         name: "default",
+*         background: "./src/assets/og-bg.jpg",
+*         layers: [{
+*           text: { en: "Build faster", de: "Schneller bauen", cs: "Stavte rychleji" },
+*           y: "40%",
+*           fontSize: 72,
+*         }],
+*       }],
+*     }),
+*   ],
+* }
+* ```
+*/
+let sharpWarned = false;
+function warnSharpMissing() {
+	if (sharpWarned) return;
+	sharpWarned = true;
+	console.warn("\n[zero:og-image] sharp not installed — OG images will not be generated. Install for full support: bun add -D sharp\n");
+}
+function resolvePosition(value, dimension, fallback = "50%") {
+	if (value === void 0) value = fallback;
+	if (typeof value === "number") return value;
+	if (value.endsWith("%")) return Math.round(Number.parseFloat(value) / 100 * dimension);
+	return Number.parseInt(value, 10) || 0;
+}
+function resolveLayerText(layer, locale) {
+	if (typeof layer.text === "string") return layer.text;
+	if (typeof layer.text === "function") return layer.text(locale);
+	return layer.text[locale] ?? layer.text[Object.keys(layer.text)[0] ?? ""] ?? "";
+}
+function escapeXml(str) {
+	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+/**
+* Build an SVG overlay with text layers.
+* @internal Exported for testing.
+*/
+function buildTextOverlaySvg(layers, width, height, locale) {
+	return `<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">${layers.map((layer) => {
+		const text = resolveLayerText(layer, locale);
+		const x = resolvePosition(layer.x, width, "50%");
+		const y = resolvePosition(layer.y, height, "50%");
+		const fontSize = layer.fontSize ?? 64;
+		const fontFamily = layer.fontFamily ?? "sans-serif";
+		const fontWeight = layer.fontWeight ?? "bold";
+		const color = layer.color ?? "#ffffff";
+		const anchor = layer.textAnchor ?? "middle";
+		const maxWidth = layer.maxWidth ?? Math.round(width * .8);
+		const words = text.split(" ");
+		const lines = [];
+		let currentLine = "";
+		const estimateWidth = (s) => {
+			let width = 0;
+			for (let i = 0; i < s.length; i++) {
+				const code = s.charCodeAt(i);
+				if (code >= 12288 && code <= 40959) width += fontSize * 1;
+				else if (code <= 126 && "iljft!|:;.,'".includes(s[i])) width += fontSize * .35;
+				else width += fontSize * .55;
+			}
+			return width;
+		};
+		for (const word of words) {
+			const testLine = currentLine ? `${currentLine} ${word}` : word;
+			if (estimateWidth(testLine) > maxWidth && currentLine) {
+				lines.push(currentLine);
+				currentLine = word;
+			} else currentLine = testLine;
+		}
+		if (currentLine) lines.push(currentLine);
+		const tspans = lines.map((line, i) => {
+			return `<tspan x="${x}" dy="${i === 0 ? "0" : `${fontSize * 1.2}`}">${escapeXml(line)}</tspan>`;
+		}).join("");
+		return `<text x="${x}" y="${y}" font-size="${fontSize}" font-family="${escapeXml(fontFamily)}" font-weight="${fontWeight}" fill="${color}" text-anchor="${anchor}" dominant-baseline="middle">${tspans}</text>`;
+	}).join("")}</svg>`;
+}
+/**
+* Render an OG image from a template for a specific locale.
+* @internal Exported for testing.
+*/
+async function renderOgImage(template, locale, rootDir) {
+	try {
+		const sharp = await import("sharp").then((m) => m.default ?? m);
+		const width = template.width ?? 1200;
+		const height = template.height ?? 630;
+		let pipeline;
+		if (typeof template.background === "string") pipeline = sharp(join(rootDir, template.background)).resize(width, height, { fit: "cover" });
+		else pipeline = sharp({ create: {
+			width,
+			height,
+			channels: 4,
+			background: template.background.color
+		} });
+		if (template.layers && template.layers.length > 0) {
+			const svgOverlay = buildTextOverlaySvg(template.layers, width, height, locale);
+			pipeline = pipeline.composite([{
+				input: Buffer.from(svgOverlay),
+				top: 0,
+				left: 0
+			}]);
+		}
+		if (template.format === "jpeg") return await pipeline.jpeg({ quality: template.quality ?? 90 }).toBuffer();
+		return await pipeline.png().toBuffer();
+	} catch {
+		warnSharpMissing();
+		return null;
+	}
+}
+/**
+* Compute the OG image path for a template and locale.
+*
+* @example
+* ```ts
+* ogImagePath("default", "de")      // → "/og/default-de.png"
+* ogImagePath("default")            // → "/og/default.png"
+* ogImagePath("hero", "en", "images") // → "/images/hero-en.png"
+* ```
+*/
+function ogImagePath(templateName, locale, outDir = "og", format = "png") {
+	const ext = format === "jpeg" ? "jpg" : "png";
+	return `/${outDir}/${templateName}${locale ? `-${locale}` : ""}.${ext}`;
+}
+/**
+* OG image generation Vite plugin.
+*
+* Generates Open Graph images at build time. In dev, generates on-demand.
+* Requires `sharp` as an optional dependency.
+*
+* @example
+* ```ts
+* // vite.config.ts
+* import { ogImagePlugin } from "@pyreon/zero/og-image"
+*
+* export default {
+*   plugins: [
+*     ogImagePlugin({
+*       locales: ["en", "de"],
+*       templates: [{
+*         name: "default",
+*         background: { color: "#0066ff" },
+*         layers: [{ text: { en: "Hello", de: "Hallo" }, fontSize: 72 }],
+*       }],
+*     }),
+*   ],
+* }
+* ```
+*/
+function ogImagePlugin(config) {
+	const outDir = config.outDir ?? "og";
+	let root = "";
+	let isBuild = false;
+	return {
+		name: "pyreon-zero-og-image",
+		enforce: "pre",
+		configResolved(resolvedConfig) {
+			root = resolvedConfig.root;
+			isBuild = resolvedConfig.command === "build";
+		},
+		configureServer(server) {
+			const devCache = /* @__PURE__ */ new Map();
+			server.middlewares.use(async (req, res, next) => {
+				const url = req.url ?? "";
+				if (!url.startsWith(`/${outDir}/`)) return next();
+				const match = url.slice(outDir.length + 2).match(/^(.+?)(?:-([a-z]{2,5}))?\.(png|jpe?g)$/);
+				if (!match) return next();
+				const [, templateName, locale, ext] = match;
+				const template = config.templates.find((t) => t.name === templateName);
+				if (!template) return next();
+				const resolvedLocale = locale ?? config.locales?.[0] ?? "en";
+				const cacheKey = `${templateName}:${resolvedLocale}`;
+				let buffer = devCache.get(cacheKey);
+				if (!buffer) {
+					const result = await renderOgImage(template, resolvedLocale, root);
+					if (!result) return next();
+					buffer = result;
+					devCache.set(cacheKey, result);
+				}
+				const contentType = ext === "jpg" || ext === "jpeg" ? "image/jpeg" : "image/png";
+				res.setHeader("Content-Type", contentType);
+				res.setHeader("Cache-Control", "no-cache");
+				res.end(Buffer.from(buffer));
+			});
+		},
+		async generateBundle() {
+			if (!isBuild) return;
+			for (const template of config.templates) {
+				const locales = config.locales ?? [void 0];
+				const ext = (template.format ?? "png") === "jpeg" ? "jpg" : "png";
+				for (const locale of locales) {
+					if (typeof template.background === "string") {
+						const bgPath = join(root, template.background);
+						if (!existsSync(bgPath)) {
+							console.warn(`[zero:og-image] Background not found: ${bgPath}`);
+							continue;
+						}
+					}
+					const buffer = await renderOgImage(template, locale ?? "en", root);
+					if (!buffer) continue;
+					const suffix = locale ? `-${locale}` : "";
+					this.emitFile({
+						type: "asset",
+						fileName: `${outDir}/${template.name}${suffix}.${ext}`,
+						source: buffer
+					});
+				}
+			}
+		}
+	};
+}
+
+//#endregion
+export { buildTextOverlaySvg, ogImagePath, ogImagePlugin, renderOgImage };
+//# sourceMappingURL=og-image.js.map

package/lib/og-image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"og-image.js","names":[],"sources":["../src/og-image.ts"],"sourcesContent":["/**\n * OG Image generation plugin.\n *\n * Generates Open Graph images at build time from templates with\n * text overlays. Supports locale-specific text for i18n apps.\n * Uses sharp for image processing (same optional dep as favicon/image plugins).\n *\n * @example\n * ```ts\n * // vite.config.ts\n * import { ogImagePlugin } from \"@pyreon/zero/og-image\"\n *\n * export default {\n *   plugins: [\n *     ogImagePlugin({\n *       locales: [\"en\", \"de\", \"cs\"],\n *       templates: [{\n *         name: \"default\",\n *         background: \"./src/assets/og-bg.jpg\",\n *         layers: [{\n *           text: { en: \"Build faster\", de: \"Schneller bauen\", cs: \"Stavte rychleji\" },\n *           y: \"40%\",\n *           fontSize: 72,\n *         }],\n *       }],\n *     }),\n *   ],\n * }\n * ```\n */\nimport { existsSync } from 'node:fs'\nimport { join } from 'node:path'\nimport type { Plugin } from 'vite'\n\nlet sharpWarned = false\nfunction warnSharpMissing() {\n  if (sharpWarned) return\n  sharpWarned = true\n  // oxlint-disable-next-line no-console\n  console.warn(\n    '\\n[zero:og-image] sharp not installed — OG images will not be generated. Install for full support: bun add -D sharp\\n',\n  )\n}\n\n// ─── Types ──────────────────────────────────────────────────────────────────\n\nexport interface OgImageLayer {\n  /**\n   * Text content. Can be:\n   * - A string (same for all locales)\n   * - A record mapping locale → text\n   * - A function receiving locale and returning text\n   */\n  text: string | Record<string, string> | ((locale: string) => string)\n  /** X position — number (px) or string with % (e.g. \"50%\"). Default: \"50%\" */\n  x?: number | string\n  /** Y position — number (px) or string with % (e.g. \"40%\"). Default: \"50%\" */\n  y?: number | string\n  /** Font size in px. Default: 64 */\n  fontSize?: number\n  /** Font family. Default: \"sans-serif\" */\n  fontFamily?: string\n  /** Font weight. Default: \"bold\" */\n  fontWeight?: string\n  /** Text color. Default: \"#ffffff\" */\n  color?: string\n  /** Text anchor (alignment). Default: \"middle\" */\n  textAnchor?: 'start' | 'middle' | 'end'\n  /** Max width in px before wrapping. Default: 80% of image width. */\n  maxWidth?: number\n}\n\nexport interface OgImageTemplate {\n  /** Template name — used for output file naming. */\n  name: string\n  /**\n   * Background: path to an image file, or a solid color config.\n   *\n   * @example \"./src/assets/og-bg.jpg\"\n   * @example { color: \"#0066ff\", width: 1200, height: 630 }\n   */\n  background: string | { color: string; width?: number; height?: number }\n  /** Output width. Default: 1200 */\n  width?: number\n  /** Output height. Default: 630 */\n  height?: number\n  /** Output format. Default: \"png\" */\n  format?: 'png' | 'jpeg'\n  /** JPEG quality (1-100). Default: 90 */\n  quality?: number\n  /** Text layers to overlay on the background. */\n  layers?: OgImageLayer[]\n}\n\nexport interface OgImagePluginConfig {\n  /** Templates to generate. */\n  templates: OgImageTemplate[]\n  /** Locales to generate for. When omitted, generates a single image per template. */\n  locales?: string[]\n  /** Output directory prefix. Default: \"og\" */\n  outDir?: string\n}\n\n// ─── Helpers ────────────────────────────────────────────────────────────────\n\nfunction resolvePosition(value: number | string | undefined, dimension: number, fallback = '50%'): number {\n  if (value === undefined) value = fallback\n  if (typeof value === 'number') return value\n  if (value.endsWith('%')) return Math.round((Number.parseFloat(value) / 100) * dimension)\n  return Number.parseInt(value, 10) || 0\n}\n\nfunction resolveLayerText(layer: OgImageLayer, locale: string): string {\n  if (typeof layer.text === 'string') return layer.text\n  if (typeof layer.text === 'function') return layer.text(locale)\n  return layer.text[locale] ?? layer.text[Object.keys(layer.text)[0] ?? ''] ?? ''\n}\n\nfunction escapeXml(str: string): string {\n  return str\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;')\n    .replace(/'/g, '&apos;')\n}\n\n/**\n * Build an SVG overlay with text layers.\n * @internal Exported for testing.\n */\nexport function buildTextOverlaySvg(\n  layers: OgImageLayer[],\n  width: number,\n  height: number,\n  locale: string,\n): string {\n  const textElements = layers.map((layer) => {\n    const text = resolveLayerText(layer, locale)\n    const x = resolvePosition(layer.x, width, '50%')\n    const y = resolvePosition(layer.y, height, '50%')\n    const fontSize = layer.fontSize ?? 64\n    const fontFamily = layer.fontFamily ?? 'sans-serif'\n    const fontWeight = layer.fontWeight ?? 'bold'\n    const color = layer.color ?? '#ffffff'\n    const anchor = layer.textAnchor ?? 'middle'\n    const maxWidth = layer.maxWidth ?? Math.round(width * 0.8)\n\n    // Word wrapping via tspan elements.\n    // Width estimation: Latin chars ~0.55em, CJK chars ~1.0em, narrow chars ~0.35em.\n    const words = text.split(' ')\n    const lines: string[] = []\n    let currentLine = ''\n\n    const estimateWidth = (s: string): number => {\n      let width = 0\n      for (let i = 0; i < s.length; i++) {\n        const code = s.charCodeAt(i)\n        if (code >= 0x3000 && code <= 0x9FFF) {\n          // CJK characters — full width\n          width += fontSize * 1.0\n        } else if (code <= 0x7E && 'iljft!|:;.,\\''.includes(s[i]!)) {\n          // Narrow Latin characters\n          width += fontSize * 0.35\n        } else {\n          // Regular Latin characters\n          width += fontSize * 0.55\n        }\n      }\n      return width\n    }\n\n    for (const word of words) {\n      const testLine = currentLine ? `${currentLine} ${word}` : word\n      if (estimateWidth(testLine) > maxWidth && currentLine) {\n        lines.push(currentLine)\n        currentLine = word\n      } else {\n        currentLine = testLine\n      }\n    }\n    if (currentLine) lines.push(currentLine)\n\n    const tspans = lines\n      .map((line, i) => {\n        const dy = i === 0 ? '0' : `${fontSize * 1.2}`\n        return `<tspan x=\"${x}\" dy=\"${dy}\">${escapeXml(line)}</tspan>`\n      })\n      .join('')\n\n    return `<text x=\"${x}\" y=\"${y}\" font-size=\"${fontSize}\" font-family=\"${escapeXml(fontFamily)}\" font-weight=\"${fontWeight}\" fill=\"${color}\" text-anchor=\"${anchor}\" dominant-baseline=\"middle\">${tspans}</text>`\n  })\n\n  return `<svg width=\"${width}\" height=\"${height}\" xmlns=\"http://www.w3.org/2000/svg\">${textElements.join('')}</svg>`\n}\n\n/**\n * Render an OG image from a template for a specific locale.\n * @internal Exported for testing.\n */\nexport async function renderOgImage(\n  template: OgImageTemplate,\n  locale: string,\n  rootDir: string,\n): Promise<Uint8Array | null> {\n  try {\n    const sharp = await import('sharp').then((m) => m.default ?? m)\n    const width = template.width ?? 1200\n    const height = template.height ?? 630\n\n    let pipeline: any\n    if (typeof template.background === 'string') {\n      const bgPath = join(rootDir, template.background)\n      pipeline = sharp(bgPath).resize(width, height, { fit: 'cover' })\n    } else {\n      pipeline = (sharp as any)({\n        create: {\n          width,\n          height,\n          channels: 4,\n          background: template.background.color,\n        },\n      })\n    }\n\n    // Overlay text layers if any\n    if (template.layers && template.layers.length > 0) {\n      const svgOverlay = buildTextOverlaySvg(template.layers, width, height, locale)\n      pipeline = pipeline.composite([{\n        input: Buffer.from(svgOverlay),\n        top: 0,\n        left: 0,\n      }])\n    }\n\n    if (template.format === 'jpeg') {\n      return await pipeline.jpeg({ quality: template.quality ?? 90 }).toBuffer()\n    }\n    return await pipeline.png().toBuffer()\n  } catch {\n    warnSharpMissing()\n    return null\n  }\n}\n\n// ─── Path utility ───────────────────────────────────────────────────────────\n\n/**\n * Compute the OG image path for a template and locale.\n *\n * @example\n * ```ts\n * ogImagePath(\"default\", \"de\")      // → \"/og/default-de.png\"\n * ogImagePath(\"default\")            // → \"/og/default.png\"\n * ogImagePath(\"hero\", \"en\", \"images\") // → \"/images/hero-en.png\"\n * ```\n */\nexport function ogImagePath(\n  templateName: string,\n  locale?: string,\n  outDir = 'og',\n  format: 'png' | 'jpeg' = 'png',\n): string {\n  const ext = format === 'jpeg' ? 'jpg' : 'png'\n  const suffix = locale ? `-${locale}` : ''\n  return `/${outDir}/${templateName}${suffix}.${ext}`\n}\n\n// ─── Vite plugin ────────────────────────────────────────────────────────────\n\n/**\n * OG image generation Vite plugin.\n *\n * Generates Open Graph images at build time. In dev, generates on-demand.\n * Requires `sharp` as an optional dependency.\n *\n * @example\n * ```ts\n * // vite.config.ts\n * import { ogImagePlugin } from \"@pyreon/zero/og-image\"\n *\n * export default {\n *   plugins: [\n *     ogImagePlugin({\n *       locales: [\"en\", \"de\"],\n *       templates: [{\n *         name: \"default\",\n *         background: { color: \"#0066ff\" },\n *         layers: [{ text: { en: \"Hello\", de: \"Hallo\" }, fontSize: 72 }],\n *       }],\n *     }),\n *   ],\n * }\n * ```\n */\nexport function ogImagePlugin(config: OgImagePluginConfig): Plugin {\n  const outDir = config.outDir ?? 'og'\n  let root = ''\n  let isBuild = false\n\n  return {\n    name: 'pyreon-zero-og-image',\n    enforce: 'pre',\n\n    configResolved(resolvedConfig) {\n      root = resolvedConfig.root\n      isBuild = resolvedConfig.command === 'build'\n    },\n\n    // Dev: generate on-demand\n    configureServer(server) {\n      const devCache = new Map<string, Uint8Array>()\n\n      server.middlewares.use(async (req, res, next) => {\n        const url = req.url ?? ''\n        if (!url.startsWith(`/${outDir}/`)) return next()\n\n        // Parse: /og/default-en.png → template=default, locale=en\n        const fileName = url.slice(outDir.length + 2) // strip /{outDir}/\n        const match = fileName.match(/^(.+?)(?:-([a-z]{2,5}))?\\.(png|jpe?g)$/)\n        if (!match) return next()\n\n        const [, templateName, locale, ext] = match\n        const template = config.templates.find((t) => t.name === templateName)\n        if (!template) return next()\n\n        const resolvedLocale = locale ?? config.locales?.[0] ?? 'en'\n        const cacheKey = `${templateName}:${resolvedLocale}`\n\n        let buffer = devCache.get(cacheKey)\n        if (!buffer) {\n          const result = await renderOgImage(template, resolvedLocale, root)\n          if (!result) return next()\n          buffer = result\n          devCache.set(cacheKey, result)\n        }\n\n        const contentType = ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg' : 'image/png'\n        res.setHeader('Content-Type', contentType)\n        res.setHeader('Cache-Control', 'no-cache')\n        res.end(Buffer.from(buffer))\n      })\n    },\n\n    // Build: generate all variants\n    async generateBundle() {\n      if (!isBuild) return\n\n      for (const template of config.templates) {\n        const locales = config.locales ?? [undefined]\n        const format = template.format ?? 'png'\n        const ext = format === 'jpeg' ? 'jpg' : 'png'\n\n        for (const locale of locales) {\n          // Validate background exists if it's a file path\n          if (typeof template.background === 'string') {\n            const bgPath = join(root, template.background)\n            if (!existsSync(bgPath)) {\n              // oxlint-disable-next-line no-console\n              console.warn(`[zero:og-image] Background not found: ${bgPath}`)\n              continue\n            }\n          }\n\n          const buffer = await renderOgImage(template, locale ?? 'en', root)\n          if (!buffer) continue\n\n          const suffix = locale ? `-${locale}` : ''\n          this.emitFile({\n            type: 'asset',\n            fileName: `${outDir}/${template.name}${suffix}.${ext}`,\n            source: buffer,\n          })\n        }\n      }\n    },\n  }\n}\n"],"mappings":"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"}

package/lib/rate-limit.js

@@ -0,0 +1,76 @@
+//#region src/rate-limit.ts
+/**
+* Rate limiting middleware — limits requests per client within a time window.
+* Uses an in-memory store (suitable for single-instance deployments).
+*
+* @example
+* import { rateLimitMiddleware } from "@pyreon/zero/rate-limit"
+*
+* // 100 requests per minute (default)
+* rateLimitMiddleware()
+*
+* // Strict API rate limiting
+* rateLimitMiddleware({
+*   max: 20,
+*   window: 60,
+*   include: ["/api/*"],
+* })
+*/
+function rateLimitMiddleware(config = {}) {
+	const { max = 100, window: windowSec = 60, keyFn = defaultKeyFn, onLimit, include, exclude } = config;
+	const windowMs = windowSec * 1e3;
+	const store = /* @__PURE__ */ new Map();
+	const MAX_STORE_SIZE = 1e4;
+	let lastCleanup = Date.now();
+	function cleanupIfNeeded(now) {
+		if (store.size < MAX_STORE_SIZE / 2 && now - lastCleanup < windowMs) return;
+		lastCleanup = now;
+		for (const [key, entry] of store) if (entry.resetAt <= now) store.delete(key);
+	}
+	return (ctx) => {
+		if (include && !include.some((p) => matchSimpleGlob(p, ctx.path))) return;
+		if (exclude?.some((p) => matchSimpleGlob(p, ctx.path))) return;
+		const key = keyFn(ctx);
+		const now = Date.now();
+		cleanupIfNeeded(now);
+		let entry = store.get(key);
+		if (!entry || entry.resetAt <= now) {
+			entry = {
+				count: 0,
+				resetAt: now + windowMs
+			};
+			store.set(key, entry);
+		}
+		entry.count++;
+		const remaining = Math.max(0, max - entry.count);
+		const resetSeconds = Math.ceil((entry.resetAt - now) / 1e3);
+		ctx.headers.set("X-RateLimit-Limit", String(max));
+		ctx.headers.set("X-RateLimit-Remaining", String(remaining));
+		ctx.headers.set("X-RateLimit-Reset", String(resetSeconds));
+		if (entry.count > max) {
+			if (onLimit) return onLimit(ctx);
+			return new Response(JSON.stringify({ error: "Too many requests" }), {
+				status: 429,
+				headers: {
+					"Content-Type": "application/json",
+					"Retry-After": String(resetSeconds),
+					"X-RateLimit-Limit": String(max),
+					"X-RateLimit-Remaining": "0",
+					"X-RateLimit-Reset": String(resetSeconds)
+				}
+			});
+		}
+	};
+}
+function defaultKeyFn(ctx) {
+	return ctx.req.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? ctx.req.headers.get("x-real-ip") ?? "unknown";
+}
+/** Simple glob matching for path patterns. Supports trailing `*`. */
+function matchSimpleGlob(pattern, path) {
+	if (pattern.endsWith("/*")) return path.startsWith(pattern.slice(0, -1));
+	return pattern === path;
+}
+
+//#endregion
+export { rateLimitMiddleware };
+//# sourceMappingURL=rate-limit.js.map

package/lib/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","names":[],"sources":["../src/rate-limit.ts"],"sourcesContent":["import type { Middleware, MiddlewareContext } from '@pyreon/server'\n\n// ─── Rate limiting middleware ───────────────────────────────────────────────\n\nexport interface RateLimitConfig {\n  /** Maximum requests per window. Default: `100` */\n  max?: number\n  /** Time window in seconds. Default: `60` */\n  window?: number\n  /** Function to extract the client identifier. Default: IP from headers. */\n  keyFn?: (ctx: MiddlewareContext) => string\n  /** Custom response when rate limited. */\n  onLimit?: (ctx: MiddlewareContext) => Response\n  /** URL patterns to rate limit (glob-style). Default: all paths. */\n  include?: string[]\n  /** URL patterns to exclude from rate limiting. */\n  exclude?: string[]\n}\n\ninterface RateLimitEntry {\n  count: number\n  resetAt: number\n}\n\n/**\n * Rate limiting middleware — limits requests per client within a time window.\n * Uses an in-memory store (suitable for single-instance deployments).\n *\n * @example\n * import { rateLimitMiddleware } from \"@pyreon/zero/rate-limit\"\n *\n * // 100 requests per minute (default)\n * rateLimitMiddleware()\n *\n * // Strict API rate limiting\n * rateLimitMiddleware({\n *   max: 20,\n *   window: 60,\n *   include: [\"/api/*\"],\n * })\n */\nexport function rateLimitMiddleware(config: RateLimitConfig = {}): Middleware {\n  const {\n    max = 100,\n    window: windowSec = 60,\n    keyFn = defaultKeyFn,\n    onLimit,\n    include,\n    exclude,\n  } = config\n\n  const windowMs = windowSec * 1000\n  const store = new Map<string, RateLimitEntry>()\n  const MAX_STORE_SIZE = 10000\n  let lastCleanup = Date.now()\n\n  // Inline cleanup — runs during request processing, no setInterval needed.\n  // Evicts expired entries when store exceeds half capacity or on window boundary.\n  function cleanupIfNeeded(now: number) {\n    if (store.size < MAX_STORE_SIZE / 2 && now - lastCleanup < windowMs) return\n    lastCleanup = now\n    for (const [key, entry] of store) {\n      if (entry.resetAt <= now) store.delete(key)\n    }\n  }\n\n  return (ctx: MiddlewareContext) => {\n    // Check include/exclude patterns\n    if (include && !include.some((p) => matchSimpleGlob(p, ctx.path))) return\n    if (exclude?.some((p) => matchSimpleGlob(p, ctx.path))) return\n\n    const key = keyFn(ctx)\n    const now = Date.now()\n\n    cleanupIfNeeded(now)\n\n    let entry = store.get(key)\n\n    if (!entry || entry.resetAt <= now) {\n      entry = { count: 0, resetAt: now + windowMs }\n      store.set(key, entry)\n    }\n\n    entry.count++\n    const remaining = Math.max(0, max - entry.count)\n    const resetSeconds = Math.ceil((entry.resetAt - now) / 1000)\n\n    // Set rate limit headers on all responses\n    ctx.headers.set('X-RateLimit-Limit', String(max))\n    ctx.headers.set('X-RateLimit-Remaining', String(remaining))\n    ctx.headers.set('X-RateLimit-Reset', String(resetSeconds))\n\n    if (entry.count > max) {\n      if (onLimit) return onLimit(ctx)\n\n      return new Response(JSON.stringify({ error: 'Too many requests' }), {\n        status: 429,\n        headers: {\n          'Content-Type': 'application/json',\n          'Retry-After': String(resetSeconds),\n          'X-RateLimit-Limit': String(max),\n          'X-RateLimit-Remaining': '0',\n          'X-RateLimit-Reset': String(resetSeconds),\n        },\n      })\n    }\n  }\n}\n\nfunction defaultKeyFn(ctx: MiddlewareContext): string {\n  return (\n    ctx.req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ??\n    ctx.req.headers.get('x-real-ip') ??\n    'unknown'\n  )\n}\n\n/** Simple glob matching for path patterns. Supports trailing `*`. */\nfunction matchSimpleGlob(pattern: string, path: string): boolean {\n  if (pattern.endsWith('/*')) {\n    return path.startsWith(pattern.slice(0, -1))\n  }\n  return pattern === path\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAyCA,SAAgB,oBAAoB,SAA0B,EAAE,EAAc;CAC5E,MAAM,EACJ,MAAM,KACN,QAAQ,YAAY,IACpB,QAAQ,cACR,SACA,SACA,YACE;CAEJ,MAAM,WAAW,YAAY;CAC7B,MAAM,wBAAQ,IAAI,KAA6B;CAC/C,MAAM,iBAAiB;CACvB,IAAI,cAAc,KAAK,KAAK;CAI5B,SAAS,gBAAgB,KAAa;AACpC,MAAI,MAAM,OAAO,iBAAiB,KAAK,MAAM,cAAc,SAAU;AACrE,gBAAc;AACd,OAAK,MAAM,CAAC,KAAK,UAAU,MACzB,KAAI,MAAM,WAAW,IAAK,OAAM,OAAO,IAAI;;AAI/C,SAAQ,QAA2B;AAEjC,MAAI,WAAW,CAAC,QAAQ,MAAM,MAAM,gBAAgB,GAAG,IAAI,KAAK,CAAC,CAAE;AACnE,MAAI,SAAS,MAAM,MAAM,gBAAgB,GAAG,IAAI,KAAK,CAAC,CAAE;EAExD,MAAM,MAAM,MAAM,IAAI;EACtB,MAAM,MAAM,KAAK,KAAK;AAEtB,kBAAgB,IAAI;EAEpB,IAAI,QAAQ,MAAM,IAAI,IAAI;AAE1B,MAAI,CAAC,SAAS,MAAM,WAAW,KAAK;AAClC,WAAQ;IAAE,OAAO;IAAG,SAAS,MAAM;IAAU;AAC7C,SAAM,IAAI,KAAK,MAAM;;AAGvB,QAAM;EACN,MAAM,YAAY,KAAK,IAAI,GAAG,MAAM,MAAM,MAAM;EAChD,MAAM,eAAe,KAAK,MAAM,MAAM,UAAU,OAAO,IAAK;AAG5D,MAAI,QAAQ,IAAI,qBAAqB,OAAO,IAAI,CAAC;AACjD,MAAI,QAAQ,IAAI,yBAAyB,OAAO,UAAU,CAAC;AAC3D,MAAI,QAAQ,IAAI,qBAAqB,OAAO,aAAa,CAAC;AAE1D,MAAI,MAAM,QAAQ,KAAK;AACrB,OAAI,QAAS,QAAO,QAAQ,IAAI;AAEhC,UAAO,IAAI,SAAS,KAAK,UAAU,EAAE,OAAO,qBAAqB,CAAC,EAAE;IAClE,QAAQ;IACR,SAAS;KACP,gBAAgB;KAChB,eAAe,OAAO,aAAa;KACnC,qBAAqB,OAAO,IAAI;KAChC,yBAAyB;KACzB,qBAAqB,OAAO,aAAa;KAC1C;IACF,CAAC;;;;AAKR,SAAS,aAAa,KAAgC;AACpD,QACE,IAAI,IAAI,QAAQ,IAAI,kBAAkB,EAAE,MAAM,IAAI,CAAC,IAAI,MAAM,IAC7D,IAAI,IAAI,QAAQ,IAAI,YAAY,IAChC;;;AAKJ,SAAS,gBAAgB,SAAiB,MAAuB;AAC/D,KAAI,QAAQ,SAAS,KAAK,CACxB,QAAO,KAAK,WAAW,QAAQ,MAAM,GAAG,GAAG,CAAC;AAE9C,QAAO,YAAY"}