@lovrozagar/flare 0.1.0

package/src/server-handler/types.ts

@@ -0,0 +1,24 @@
+import type { FlareTracer } from "../tracing/types.ts";
+
+export interface TracingConfig {
+	provider?: FlareTracer;
+	timing?: boolean;
+}
+
+export interface CspDirectives {
+	"base-uri"?: string[];
+	"connect-src"?: string[];
+	"default-src"?: string[];
+	"font-src"?: string[];
+	"form-action"?: string[];
+	"frame-ancestors"?: string[];
+	"frame-src"?: string[];
+	"img-src"?: string[];
+	"media-src"?: string[];
+	"object-src"?: string[];
+	"script-src"?: string[];
+	"style-src"?: string[];
+	"block-all-mixed-content"?: boolean;
+	"upgrade-insecure-requests"?: boolean;
+	"worker-src"?: string[];
+}

package/src/server-handler/validate-static-params.ts

@@ -0,0 +1,130 @@
+import type { ResolvedRoute } from "../loader-pipeline/index.ts";
+import type { CacheConfig } from "../route-builder/types.ts";
+
+type ParamsFn = (ctx: { params: Record<string, string | string[]> }) => unknown;
+
+/**
+ * Extract params fn from a route's cache config.
+ * Handles: `ssg: fn`, `ssg: { params: fn }`, `isr: { params: fn }`
+ */
+export function extractParamsFn(cache: CacheConfig | undefined): ParamsFn | undefined {
+	if (!cache) return undefined;
+
+	const ssg = cache.ssg;
+	if (typeof ssg === "function") return ssg as ParamsFn;
+	if (ssg && typeof ssg === "object") {
+		const params = (ssg as Record<string, unknown>).params;
+		if (typeof params === "function") return params as ParamsFn;
+	}
+
+	const isr = cache.isr;
+	if (isr && typeof isr === "object") {
+		const params = (isr as Record<string, unknown>).params;
+		if (typeof params === "function") return params as ParamsFn;
+	}
+
+	return undefined;
+}
+
+/**
+ * Determine whether a cache config requires strict param validation.
+ * - ssg with params fn → always validate
+ * - isr with params fn + dynamicParams: false → validate
+ * - everything else → skip
+ */
+function shouldValidateParams(cache: CacheConfig | undefined): boolean {
+	if (!cache) return false;
+
+	const ssg = cache.ssg;
+	if (typeof ssg === "function") return true;
+	if (ssg && typeof ssg === "object" && "params" in ssg) return true;
+
+	const isr = cache.isr;
+	if (isr && typeof isr === "object" && "params" in isr) {
+		const dynamicParams = (isr as Record<string, unknown>).dynamicParams ?? true;
+		return dynamicParams === false;
+	}
+
+	return false;
+}
+
+/*
+ * Production cache: caches params fn results per virtualPath+matchParams.
+ * Skipped in dev mode so route file edits take effect without restart —
+ * layout modules are loaded via dynamic imports that Vite invalidates on
+ * file change, but this module's state persists across those invalidations.
+ *
+ * Bounded to MAX_PARAMS_CACHE_SIZE with FIFO eviction to prevent unbounded
+ * memory growth in production with many unique URL param combinations.
+ */
+const MAX_PARAMS_CACHE_SIZE = 500;
+const paramsCache = new Map<string, Record<string, string | string[]>[]>();
+
+export function clearParamsCache(): void {
+	paramsCache.clear();
+}
+
+/**
+ * Validate that the matched URL params are within the allowed set
+ * defined by SSG/ISR params functions in the route chain.
+ *
+ * Returns `false` if any route in the chain rejects the params.
+ *
+ * In dev mode, params fn results are NOT cached so edits to route files
+ * (e.g. changing params lists) take effect immediately without restart.
+ */
+export async function validateStaticParams(
+	resolvedRoutes: ResolvedRoute[],
+	matchParams: Record<string, string | string[]>,
+	isDev?: boolean,
+): Promise<boolean> {
+	for (const route of resolvedRoutes) {
+		if (!shouldValidateParams(route.cache)) continue;
+
+		const paramsFn = extractParamsFn(route.cache);
+		if (!paramsFn) continue;
+
+		/* Cache key includes matchParams because params fns can depend on parent
+		 * params (e.g. repoSegment reads ctx.params.org to filter repos). */
+		const cacheKey = `${route.virtualPath}:${JSON.stringify(matchParams, Object.keys(matchParams).sort())}`;
+		let allowedList = isDev ? undefined : paramsCache.get(cacheKey);
+		if (!allowedList) {
+			const produced = await paramsFn({ params: matchParams });
+			allowedList = Array.isArray(produced) ? (produced as Record<string, string | string[]>[]) : [];
+			if (!isDev) {
+				if (paramsCache.size >= MAX_PARAMS_CACHE_SIZE) {
+					const oldest = paramsCache.keys().next().value;
+					if (oldest !== undefined) paramsCache.delete(oldest);
+				}
+				paramsCache.set(cacheKey, allowedList);
+			}
+		}
+
+		if (allowedList.length === 0) return false;
+
+		/* Extract which param keys this level defines */
+		const paramKeys = Object.keys(allowedList[0] ?? {});
+		if (paramKeys.length === 0) continue;
+
+		/* Check if matchParams values exist in the allowed list */
+		const matched = allowedList.some((allowed) =>
+			paramKeys.every((key) => {
+				const matchVal = matchParams[key];
+				const allowedVal = allowed[key];
+				/* Optional param [[x]] skipped — not in matchParams → skip validation */
+				if (matchVal === undefined) return true;
+				if (allowedVal === undefined) return false;
+				if (Array.isArray(matchVal) && Array.isArray(allowedVal)) {
+					if (matchVal.length !== allowedVal.length) return false;
+					return matchVal.every((v, i) => v === allowedVal[i]);
+				}
+				if (Array.isArray(matchVal) || Array.isArray(allowedVal)) return false;
+				return String(matchVal) === String(allowedVal);
+			}),
+		);
+
+		if (!matched) return false;
+	}
+
+	return true;
+}

package/src/server.ts

@@ -0,0 +1,2 @@
+/* test stub */
+export {};

package/src/service-worker/template.ts

@@ -0,0 +1,153 @@
+export interface SwTemplateConfig {
+	/** URL prefix for cache-first asset matching. Defaults to `"/assets"`. */
+	assetsBase?: string;
+	offlineFallback: string | null;
+	runtimeCacheMax: number;
+	skipWaiting: boolean;
+}
+
+export function generateSwSource(precacheManifest: string[], buildId: string, config: SwTemplateConfig): string {
+	const manifest = JSON.stringify(precacheManifest);
+	const assetsBase = config.assetsBase ?? "/assets";
+	const swConfig = JSON.stringify({
+		assetsBase,
+		offlineFallback: config.offlineFallback,
+		runtimeCacheMax: config.runtimeCacheMax,
+		skipWaiting: config.skipWaiting,
+	});
+
+	return `/* Flare Service Worker — generated at build time */
+var PRECACHE_MANIFEST = ${manifest}
+var SW_CONFIG = ${swConfig}
+var BUILD_ID = "${buildId}"
+var CACHE_NAME = "flare-assets-${buildId}"
+var RUNTIME_CACHE = "flare-runtime-v1"
+
+/* ── Install ─────────────────────────────────────────────────────── */
+
+self.addEventListener("install", function (event) {
+	event.waitUntil(
+		caches.open(CACHE_NAME).then(function (cache) {
+			var promises = [cache.addAll(PRECACHE_MANIFEST)]
+			if (SW_CONFIG.offlineFallback) {
+				promises.push(
+					caches.open(RUNTIME_CACHE).then(function (rtCache) {
+						return fetch(SW_CONFIG.offlineFallback).then(function (res) {
+							if (res.ok) return rtCache.put(SW_CONFIG.offlineFallback, res)
+						}).catch(function () {})
+					})
+				)
+			}
+			return Promise.all(promises)
+		}).then(function () {
+			if (SW_CONFIG.skipWaiting) self.skipWaiting()
+		}).catch(function (err) {
+			/* Install failed — old SW stays active. Log for debugging. */
+			console.error("[flare-sw] install failed:", err)
+		})
+	)
+})
+
+/* ── Activate ────────────────────────────────────────────────────── */
+
+self.addEventListener("activate", function (event) {
+	event.waitUntil(
+		Promise.all([
+			self.registration.navigationPreload && self.registration.navigationPreload.enable(),
+			caches.keys().then(function (names) {
+				return Promise.all(
+					names.filter(function (n) {
+						return n.startsWith("flare-assets-") && n !== CACHE_NAME
+					}).map(function (n) {
+						return caches.delete(n)
+					})
+				)
+			}),
+			self.clients.claim(),
+		])
+	)
+})
+
+/* ── Message ─────────────────────────────────────────────────────── */
+
+self.addEventListener("message", function (event) {
+	if (event.data && event.data.type === "SKIP_WAITING") {
+		self.skipWaiting()
+	}
+})
+
+/* ── Fetch ───────────────────────────────────────────────────────── */
+
+self.addEventListener("fetch", function (event) {
+	var url = new URL(event.request.url)
+
+	/* Only handle same-origin */
+	if (url.origin !== self.location.origin) return
+
+	/* Passthrough: NDJSON (x-d header), server functions, keepalive */
+	if (event.request.headers.has("x-d")) return
+	if (url.pathname.startsWith("/_fn/")) return
+	if (url.pathname === "/_flare/keepalive") return
+
+	/* Cache-first for hashed assets under the configured assetsBase */
+	if (url.pathname.startsWith(${JSON.stringify(`${assetsBase}/`)})) {
+		event.respondWith(
+			caches.match(event.request).then(function (cached) {
+				if (cached) return cached
+				return fetch(event.request).then(function (response) {
+					if (response.ok) {
+						var clone = response.clone()
+						caches.open(CACHE_NAME).then(function (cache) {
+							cache.put(event.request, clone)
+						}).catch(function () {})
+					}
+					return response
+				})
+			}).catch(function () {
+				/* Cache API error — fall through to network */
+				return fetch(event.request)
+			})
+		)
+		return
+	}
+
+	/* Network-first for navigations */
+	if (event.request.mode === "navigate") {
+		event.respondWith(
+			(function () {
+				var preload = event.preloadResponse || Promise.resolve(undefined)
+				return preload.then(function (preloaded) {
+					if (preloaded) return preloaded
+					return fetch(event.request)
+				}).then(function (response) {
+					if (response.ok) {
+						var clone = response.clone()
+						caches.open(RUNTIME_CACHE).then(function (cache) {
+							cache.put(event.request, clone).catch(function () {})
+							/* LRU eviction — batch delete to stay under limit */
+							cache.keys().then(function (keys) {
+								var i = 0
+								while (keys.length - i > SW_CONFIG.runtimeCacheMax) {
+									cache.delete(keys[i])
+									i++
+								}
+							})
+						}).catch(function () {})
+					}
+					return response
+				}).catch(function () {
+					return caches.match(event.request).then(function (cached) {
+						if (cached) return cached
+						if (SW_CONFIG.offlineFallback) {
+							return caches.match(SW_CONFIG.offlineFallback)
+						}
+						return undefined
+					})
+				})
+			})()
+		)
+		return
+	}
+})
+`;
+}

package/src/service-worker-hook/index.ts

@@ -0,0 +1,70 @@
+import { createSignal, onCleanup } from "solid-js";
+
+export interface ServiceWorkerState {
+	update: () => void;
+	updateAvailable: () => boolean;
+}
+
+export function useServiceWorker(): ServiceWorkerState {
+	const [updateAvailable, setUpdateAvailable] = createSignal(false);
+	let waitingWorker: ServiceWorker | null = null;
+
+	if ("serviceWorker" in navigator) {
+		const sw = navigator.serviceWorker;
+		const trackedListeners: Array<{
+			handler: () => void;
+			name: string;
+			target: { removeEventListener: (name: string, handler: () => void) => void };
+		}> = [];
+
+		const onControllerChange = () => {
+			window.location.reload();
+		};
+
+		sw.addEventListener("controllerchange", onControllerChange);
+
+		onCleanup(() => {
+			sw.removeEventListener("controllerchange", onControllerChange);
+			for (const entry of trackedListeners) {
+				entry.target.removeEventListener(entry.name, entry.handler);
+			}
+		});
+
+		sw.ready.then((registration) => {
+			const checkWaiting = (worker: ServiceWorker | null) => {
+				if (!worker) return;
+				if (worker.state === "installed") {
+					waitingWorker = worker;
+					setUpdateAvailable(true);
+					return;
+				}
+				const handler = () => {
+					if (worker.state === "installed") {
+						waitingWorker = worker;
+						setUpdateAvailable(true);
+					}
+				};
+				worker.addEventListener("statechange", handler);
+				trackedListeners.push({ handler, name: "statechange", target: worker });
+			};
+
+			checkWaiting(registration.waiting);
+			checkWaiting(registration.installing);
+
+			const onUpdateFound = () => {
+				checkWaiting(registration.installing);
+			};
+			registration.addEventListener("updatefound", onUpdateFound);
+			trackedListeners.push({ handler: onUpdateFound, name: "updatefound", target: registration });
+		});
+	}
+
+	return {
+		update() {
+			if (waitingWorker) {
+				waitingWorker.postMessage({ type: "SKIP_WAITING" });
+			}
+		},
+		updateAvailable,
+	};
+}

package/src/sitemap/index.ts

@@ -0,0 +1,231 @@
+import type { RouteDefinition } from "../generators/index.ts";
+
+/* ── Types ────────────────────────────────────────────────────────────── */
+
+export type ChangeFreq = "always" | "daily" | "hourly" | "monthly" | "never" | "weekly" | "yearly";
+
+export interface SitemapEntry {
+	changefreq?: ChangeFreq;
+	lastmod?: string;
+	loc: string;
+	priority?: number;
+}
+
+export interface SitemapConfig {
+	additionalEntries?: SitemapEntry[];
+	changefreq?: ChangeFreq | Record<string, ChangeFreq>;
+	exclude?: string[];
+	origin: string;
+	priority?: number | Record<string, number>;
+}
+
+export interface SitemapResult {
+	files: Array<{ content: string; path: string }>;
+	urls: string[];
+}
+
+/* ── Glob matching ────────────────────────────────────────────────────── */
+
+function globToRegex(pattern: string): RegExp {
+	let result = "^";
+	let i = 0;
+	while (i < pattern.length) {
+		if (pattern[i] === "*" && pattern[i + 1] === "*") {
+			result += ".*";
+			i += 2;
+			if (pattern[i] === "/") i++;
+		} else if (pattern[i] === "*") {
+			result += "[^/]*";
+			i++;
+		} else if (".+?^${}()|[]\\".includes(pattern[i] ?? "")) {
+			result += `\\${pattern[i]}`;
+			i++;
+		} else {
+			result += pattern[i];
+			i++;
+		}
+	}
+	result += "$";
+	return new RegExp(result);
+}
+
+/* ── URL computation (mirrors generators/index.ts computeUrlPattern) ── */
+
+function computeUrlPattern(virtualPath: string): string {
+	const parts = virtualPath.split("/");
+	const rootIdx = parts.findIndex((p) => p.startsWith("_") && p.endsWith("_") && p.length >= 3);
+	const urlParts: string[] = [];
+
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i] ?? "";
+		if (rootIdx >= 0 && i <= rootIdx) continue;
+		if (part.startsWith("(") && part.endsWith(")")) continue;
+		if (part === "") continue;
+		urlParts.push(part);
+	}
+
+	if (urlParts.length === 0) return "/";
+	return `/${urlParts.join("/")}`;
+}
+
+/* ── Dynamic param detection ──────────────────────────────────────────── */
+
+const DYNAMIC_PARAM_RE = /\[.*\]/;
+
+function hasDynamicParams(virtualPath: string): boolean {
+	return DYNAMIC_PARAM_RE.test(virtualPath);
+}
+
+/* ── Route filtering ──────────────────────────────────────────────────── */
+
+export function filterSitemapRoutes(defs: RouteDefinition[], exclude?: string[]): RouteDefinition[] {
+	const excludePatterns = exclude?.map(globToRegex) ?? [];
+
+	return defs.filter((def) => {
+		if (def.type !== "page") return false;
+		if (def.responseRoute) return false;
+		if (def.authenticateMode === true) return false;
+		if (hasDynamicParams(def.virtualPath)) return false;
+
+		const url = computeUrlPattern(def.virtualPath);
+		for (const pattern of excludePatterns) {
+			if (pattern.test(url)) return false;
+		}
+
+		return true;
+	});
+}
+
+/* ── Entry building ───────────────────────────────────────────────────── */
+
+function resolveOverride<T>(url: string, value: T | Record<string, T> | undefined): T | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "object" || value === null) return value as T;
+
+	const overrides = value as Record<string, T>;
+	let bestMatch: { key: string; value: T } | undefined;
+
+	for (const [pattern, val] of Object.entries(overrides)) {
+		const re = globToRegex(pattern);
+		if (re.test(url)) {
+			if (!bestMatch || pattern.length > bestMatch.key.length) {
+				bestMatch = { key: pattern, value: val };
+			}
+		}
+	}
+
+	return bestMatch?.value;
+}
+
+export function buildSitemapEntries(defs: RouteDefinition[], config: SitemapConfig): SitemapEntry[] {
+	const entries: SitemapEntry[] = [];
+	const origin = config.origin.replace(/\/+$/, "");
+
+	for (const def of defs) {
+		const url = computeUrlPattern(def.virtualPath);
+		const entry: SitemapEntry = { loc: `${origin}${url}` };
+
+		const freq = resolveOverride(url, config.changefreq);
+		if (freq) entry.changefreq = freq;
+
+		const prio = resolveOverride(url, config.priority);
+		if (prio !== undefined) entry.priority = prio;
+
+		entries.push(entry);
+	}
+
+	if (config.additionalEntries) {
+		entries.push(...config.additionalEntries);
+	}
+
+	return entries;
+}
+
+/* ── XML generation ───────────────────────────────────────────────────── */
+
+function escapeXml(str: string): string {
+	return str
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&apos;");
+}
+
+export function generateSitemapXml(entries: SitemapEntry[]): string {
+	const lines = [
+		'<?xml version="1.0" encoding="UTF-8"?>',
+		'<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+	];
+
+	for (const entry of entries) {
+		lines.push("  <url>");
+		lines.push(`    <loc>${escapeXml(entry.loc)}</loc>`);
+		if (entry.lastmod) lines.push(`    <lastmod>${escapeXml(entry.lastmod)}</lastmod>`);
+		if (entry.changefreq) lines.push(`    <changefreq>${escapeXml(entry.changefreq)}</changefreq>`);
+		if (entry.priority !== undefined) lines.push(`    <priority>${entry.priority}</priority>`);
+		lines.push("  </url>");
+	}
+
+	lines.push("</urlset>");
+	return lines.join("\n");
+}
+
+export function generateSitemapIndexXml(origin: string, count: number): string {
+	const lines = [
+		'<?xml version="1.0" encoding="UTF-8"?>',
+		'<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+	];
+
+	for (let i = 0; i < count; i++) {
+		lines.push("  <sitemap>");
+		lines.push(`    <loc>${escapeXml(origin)}/sitemap-${i}.xml</loc>`);
+		lines.push("  </sitemap>");
+	}
+
+	lines.push("</sitemapindex>");
+	return lines.join("\n");
+}
+
+/* ── Full pipeline ────────────────────────────────────────────────────── */
+
+const MAX_SITEMAP_ENTRIES = 50_000;
+
+export function generateSitemap(config: SitemapConfig, entries: SitemapEntry[]): SitemapResult {
+	const urls = entries.map((e) => e.loc);
+
+	if (entries.length <= MAX_SITEMAP_ENTRIES) {
+		return {
+			files: [{ content: generateSitemapXml(entries), path: "sitemap.xml" }],
+			urls,
+		};
+	}
+
+	const files: Array<{ content: string; path: string }> = [];
+	const partCount = Math.ceil(entries.length / MAX_SITEMAP_ENTRIES);
+
+	for (let i = 0; i < partCount; i++) {
+		const start = i * MAX_SITEMAP_ENTRIES;
+		const chunk = entries.slice(start, start + MAX_SITEMAP_ENTRIES);
+		files.push({ content: generateSitemapXml(chunk), path: `sitemap-${i}.xml` });
+	}
+
+	files.push({ content: generateSitemapIndexXml(config.origin, partCount), path: "sitemap.xml" });
+
+	return { files, urls };
+}
+
+/* ── robots.txt ───────────────────────────────────────────────────────── */
+
+export function generateRobotsTxt(sitemapUrl: string, rules?: string): string {
+	const base = rules ?? "User-agent: *\nAllow: /";
+	return `${base}\n\nSitemap: ${sitemapUrl}\n`;
+}
+
+/* ── Convenience: filter + build + generate ───────────────────────────── */
+
+export function buildSitemapFromDefs(defs: RouteDefinition[], config: SitemapConfig): SitemapResult {
+	const filtered = filterSitemapRoutes(defs, config.exclude);
+	const entries = buildSitemapEntries(filtered, config);
+	return generateSitemap(config, entries);
+}