@lovrozagar/flare 0.1.0

package/src/middleware/builtins/markdown-negotiation.ts

@@ -0,0 +1,141 @@
+/**
+ * Markdown content negotiation — opt-in builtin. Converts the HTML response to
+ * Markdown when the request carries `Accept: text/markdown`. Subpath export,
+ * tree-shaken when unused.
+ *
+ * Pattern cribbed from `@markdown-for-agents/web` + Vercel's content-negotiation
+ * guide:
+ *   - always advertise `Vary: Accept` so caches keep HTML + Markdown variants
+ *     separate under the same URL
+ *   - convert 2xx `text/html` responses only; everything else passes through
+ *   - set `Content-Type: text/markdown; charset=utf-8`, drop stale
+ *     `Content-Length`, attach an optional `x-markdown-tokens` rough estimate
+ *
+ * Default converter is lazily imported `node-html-markdown` (pure JS, no DOM,
+ * CF Worker safe). Pass a custom `convert` to swap engines and keep the peer
+ * dep out of your bundle entirely.
+ */
+
+import type { FlareMiddleware } from "..";
+
+type Convert = (html: string) => string | Promise<string>;
+
+export interface MarkdownNegotiationOptions {
+	/** Custom HTML → Markdown converter. Omit to use lazy `node-html-markdown`. */
+	convert?: Convert;
+	/** Opt-in token header (GPT/Claude-style ~4 chars/token estimate). Default `true`. */
+	emitTokenHeader?: boolean;
+	/** Upper bound on HTML body size in bytes — larger responses pass through. Default 2 MiB. */
+	maxBytes?: number;
+	/** Per-request gate. Return `false` to skip conversion (e.g. interactive routes). */
+	when?: (input: { request: Request; url: URL }) => boolean;
+}
+
+const DEFAULT_MAX_BYTES = 2 * 1024 * 1024;
+
+function acceptsMarkdown(request: Request): boolean {
+	const accept = request.headers.get("accept");
+	if (!accept) return false;
+	/* Substring match — RFC 7231 q-value parse is overkill here.
+	   `text/html, text/markdown;q=0.9` matches; `text/html` does not. */
+	return accept.includes("text/markdown");
+}
+
+async function defaultConvert(html: string): Promise<string> {
+	/* Dynamic import so the peer dep is only loaded by consumers who import
+	   this middleware. Bundlers (Vite / esbuild) pre-bundle it as a separate
+	   chunk — required for CF Workers which have no runtime module loader. */
+	const { NodeHtmlMarkdown } = await import("node-html-markdown");
+	return NodeHtmlMarkdown.translate(html);
+}
+
+function estimateTokens(text: string): number {
+	return Math.ceil(text.length / 4);
+}
+
+export function markdownNegotiation<TEnv = unknown>(options: MarkdownNegotiationOptions = {}): FlareMiddleware<TEnv> {
+	const convert = options.convert ?? defaultConvert;
+	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+	const emitTokenHeader = options.emitTokenHeader ?? true;
+
+	return (ctx) => {
+		/* Always advertise Accept-based variance so shared caches don't serve
+		   the wrong representation. Added even on requests that won't convert
+		   — the HTML response still has an MD counterpart under the same URL. */
+		ctx.onResponse((response) => {
+			response.headers.append("vary", "Accept");
+			return response;
+		});
+
+		if (!acceptsMarkdown(ctx.request)) return ctx.next();
+		if (options.when && !options.when({ request: ctx.request, url: ctx.url })) {
+			return ctx.next();
+		}
+
+		ctx.onResponse(async (response) => {
+			if (!response.ok) return response;
+
+			const contentType = response.headers.get("content-type") ?? "";
+			if (!contentType.startsWith("text/html")) return response;
+
+			/* Status codes that forbid a body (Response constructor throws if we
+			   try to give them one). Pass through unconverted. */
+			if (response.status === 204 || response.status === 205 || response.status === 304) {
+				return response;
+			}
+
+			/* Pre-flight size check using Content-Length when present — avoids
+			   buffering multi-MB responses just to reject them. */
+			const declaredLength = Number(response.headers.get("content-length") ?? 0);
+			if (declaredLength > 0 && declaredLength > maxBytes) return response;
+
+			let html: string;
+			try {
+				html = await response.text();
+			} catch {
+				/* Body read failure — upstream closed stream or similar. Nothing
+				   we can do; return original response (stream may already be dead,
+				   but caller must handle that case regardless). */
+				return response;
+			}
+
+			if (html.length > maxBytes) {
+				/* Rebuild from captured body so the stream isn't consumed downstream. */
+				return new Response(html, {
+					headers: response.headers,
+					status: response.status,
+					statusText: response.statusText,
+				});
+			}
+
+			let markdown: string;
+			try {
+				markdown = await convert(html);
+			} catch {
+				/* Conversion failure must not break the page — return the HTML we
+				   already buffered so the client gets a working response. */
+				return new Response(html, {
+					headers: response.headers,
+					status: response.status,
+					statusText: response.statusText,
+				});
+			}
+
+			const headers = new Headers(response.headers);
+			headers.set("content-type", "text/markdown; charset=utf-8");
+			/* Length changes; drop the stale header so downstream recomputes. */
+			headers.delete("content-length");
+			if (emitTokenHeader) {
+				headers.set("x-markdown-tokens", String(estimateTokens(markdown)));
+			}
+
+			return new Response(markdown, {
+				headers,
+				status: response.status,
+				statusText: response.statusText,
+			});
+		});
+
+		return ctx.next();
+	};
+}

package/src/middleware/builtins/static-assets.ts

@@ -0,0 +1,32 @@
+import type { FlareMiddleware } from "..";
+
+interface StaticAssetsConfig {
+	paths: string[];
+}
+
+export function staticAssets(config: StaticAssetsConfig): FlareMiddleware {
+	const exactPaths = new Set<string>();
+	const prefixPaths: string[] = [];
+
+	for (const path of config.paths) {
+		if (path.endsWith("/")) {
+			prefixPaths.push(path);
+		} else {
+			exactPaths.add(path);
+		}
+	}
+
+	return async (ctx) => {
+		const pathname = ctx.url.pathname;
+
+		const matched = exactPaths.has(pathname) || prefixPaths.some((prefix) => pathname.startsWith(prefix));
+
+		if (!matched) return ctx.next();
+
+		const env = ctx.env as Record<string, { fetch: (req: Request) => Promise<Response> }>;
+		if (!env.ASSETS) return ctx.next();
+
+		const response = await env.ASSETS.fetch(ctx.request);
+		return ctx.bypass(response);
+	};
+}

package/src/middleware/index.ts

@@ -0,0 +1,223 @@
+import type { FlareTracer } from "../tracing/types.ts";
+
+export type ResponseHandler = (response: Response) => Response | Promise<Response>;
+
+export type MiddlewareResult =
+	| { response: Response; type: "bypass" }
+	| { response: Response; type: "respond" }
+	| { type: "next" };
+
+export type MiddlewareRunResult =
+	| { response: Response; type: "bypass" }
+	| { response: Response; type: "respond" }
+	| { type: "next" };
+
+export type RequestType = "internal" | "mount" | "page" | "server-fn";
+
+export interface MiddlewareContext<TEnv = unknown> {
+	bypass: (response: Response) => MiddlewareResult;
+	env: TEnv;
+	error: (...args: unknown[]) => void;
+	locale?: import("../locale").LocaleConfig;
+	log: (...args: unknown[]) => void;
+	next: () => Promise<MiddlewareResult>;
+	nonce: string;
+	onResponse: (handler: ResponseHandler) => void;
+	request: Request;
+	requestType: RequestType;
+	respond: (response: Response) => MiddlewareResult;
+	/** Present on live requests. Used by i18n to keep `/en/...` when the unprefixed path is not a route. */
+	routeTree?: import("../router-primitives/types.ts").TreeNode;
+	serverContext: Record<string, unknown>;
+	url: URL;
+	warn: (...args: unknown[]) => void;
+}
+
+export type FlareMiddleware<TEnv = unknown> = (ctx: MiddlewareContext<TEnv>) => Promise<MiddlewareResult>;
+
+export interface MiddlewareRunOutput {
+	responseHandlers: ResponseHandler[];
+	result: MiddlewareRunResult;
+}
+
+const NEXT_RESULT: MiddlewareResult = Object.freeze({ type: "next" as const });
+
+function bypassResult(response: Response): MiddlewareResult {
+	return Object.freeze({ response, type: "bypass" as const });
+}
+
+function respondResult(response: Response): MiddlewareResult {
+	return Object.freeze({ response, type: "respond" as const });
+}
+
+export async function runMiddlewares<TEnv = unknown>(
+	middlewares: FlareMiddleware<TEnv>[],
+	ctx: Omit<MiddlewareContext<TEnv>, "bypass" | "next" | "respond"> &
+		Partial<Pick<MiddlewareContext<TEnv>, "bypass" | "next" | "respond">>,
+	tracer?: FlareTracer,
+): Promise<MiddlewareRunOutput> {
+	const responseHandlers: ResponseHandler[] = [];
+
+	/* override onResponse to collect handlers, preserving ctx identity */
+	ctx.onResponse = (handler) => {
+		responseHandlers.push(handler);
+	};
+
+	ctx.bypass = bypassResult;
+	ctx.respond = respondResult;
+
+	/* After assigning flow-control methods, ctx satisfies the full interface */
+	const fullCtx = ctx as MiddlewareContext<TEnv>;
+
+	if (middlewares.length === 0) {
+		return { responseHandlers, result: { type: "next" } };
+	}
+
+	function buildChain(index: number): () => Promise<MiddlewareResult> {
+		if (index >= middlewares.length) {
+			return () => Promise.resolve(NEXT_RESULT);
+		}
+		let result: Promise<MiddlewareResult> | undefined;
+		return () => {
+			if (result) return result;
+			const mw = middlewares[index];
+			if (!mw) return Promise.resolve(NEXT_RESULT);
+			fullCtx.next = buildChain(index + 1);
+			if (tracer) {
+				const span = tracer.startSpan(`flare.middleware.${index}`);
+				span.setAttribute("index", index);
+				result = mw(fullCtx).then(
+					(r) => {
+						span.end();
+						return r;
+					},
+					(e: unknown) => {
+						span.setStatus("error");
+						span.end();
+						throw e;
+					},
+				);
+			} else {
+				result = mw(fullCtx);
+			}
+			return result;
+		};
+	}
+
+	const result = await buildChain(0)();
+
+	return { responseHandlers, result };
+}
+
+/* ── Path matching ────────────────────────────────────────────────────── */
+
+export function compilePattern(pattern: string): (path: string) => boolean {
+	if (pattern.endsWith("/*")) {
+		const prefix = pattern.slice(0, -2);
+		return (p) => p === prefix || p.startsWith(`${prefix}/`);
+	}
+	return (p) => p === pattern;
+}
+
+/* ── Virtual path matching ─────────────────────────────────────────── */
+
+const MATCHER_BRAND = Symbol.for("flare/matcher");
+
+export interface PathMatcher {
+	(path: string): boolean;
+	[MATCHER_BRAND]: true;
+}
+
+export function isPathMatcher(value: unknown): value is PathMatcher {
+	return typeof value === "function" && MATCHER_BRAND in (value as object);
+}
+
+type SegmentMatcher =
+	| { type: "catch"; min: number }
+	| { type: "literal"; value: string }
+	| { type: "optional" }
+	| { type: "param" };
+
+function parseSegments(pattern: string): SegmentMatcher[] {
+	const raw = pattern.split("/").filter(Boolean);
+	return raw.map((seg): SegmentMatcher => {
+		if (seg.startsWith("[[...") && seg.endsWith("]]")) return { min: 0, type: "catch" };
+		if (seg.startsWith("[...") && seg.endsWith("]")) return { min: 1, type: "catch" };
+		if (seg.startsWith("[[") && seg.endsWith("]]")) return { type: "optional" };
+		if (seg.startsWith("[") && seg.endsWith("]")) return { type: "param" };
+		return { type: "literal", value: seg };
+	});
+}
+
+/**
+ * Compile a virtual path pattern into a branded URL matcher.
+ * Supports `[param]`, `[[optional]]`, `[...catch]`, `[[...optional-catch]]`.
+ */
+export function virtualPath(pattern: string): PathMatcher {
+	const matchers = parseSegments(pattern);
+
+	const fn = ((path: string): boolean => {
+		const segments = path.split("/").filter(Boolean);
+
+		function walk(mi: number, si: number): boolean {
+			if (mi === matchers.length) return si === segments.length;
+
+			const m = matchers[mi];
+			if (!m) return false;
+
+			if (m.type === "literal") {
+				return si < segments.length && segments[si] === m.value && walk(mi + 1, si + 1);
+			}
+			if (m.type === "param") {
+				return si < segments.length && walk(mi + 1, si + 1);
+			}
+			if (m.type === "optional") {
+				return walk(mi + 1, si) || (si < segments.length && walk(mi + 1, si + 1));
+			}
+			if (m.type === "catch") {
+				const remaining = segments.length - si;
+				for (let take = remaining; take >= m.min; take--) {
+					if (walk(mi + 1, si + take)) return true;
+				}
+				return false;
+			}
+			return false;
+		}
+
+		return walk(0, 0);
+	}) as PathMatcher;
+	fn[MATCHER_BRAND] = true;
+	return fn;
+}
+
+/* ── Request-type filter helpers ──────────────────────────────────────── */
+
+export function onPage<TEnv = unknown>(mw: FlareMiddleware<TEnv>): FlareMiddleware<TEnv> {
+	return (ctx) => (ctx.requestType === "page" ? mw(ctx) : ctx.next());
+}
+
+export function onServerFn<TEnv = unknown>(mw: FlareMiddleware<TEnv>): FlareMiddleware<TEnv> {
+	return (ctx) => (ctx.requestType === "server-fn" ? mw(ctx) : ctx.next());
+}
+
+/* ── Middleware entry (used by server builder) ────────────────────────── */
+
+export interface MiddlewareEntry<TEnv = unknown> {
+	matchers?: Array<(path: string) => boolean>;
+	middlewares: FlareMiddleware<TEnv>[];
+}
+
+export function resolveMiddlewareEntries<TEnv = unknown>(
+	entries: MiddlewareEntry<TEnv>[],
+	pathname: string,
+): FlareMiddleware<TEnv>[] {
+	const result: FlareMiddleware<TEnv>[] = [];
+	for (const entry of entries) {
+		if (!entry.matchers || entry.matchers.some((m) => m(pathname))) {
+			for (const mw of entry.middlewares) {
+				result.push(mw);
+			}
+		}
+	}
+	return result;
+}

package/src/module-graph/index.ts

@@ -0,0 +1,181 @@
+/**
+ * Vite manifest walker for module preloading.
+ *
+ * Walks the Vite client build manifest to collect the full transitive
+ * dependency graph (JS + CSS) for a given entry point or set of route
+ * modules. Used to emit `<link rel="modulepreload">` tags in SSR HTML,
+ * eliminating the sequential module discovery waterfall.
+ */
+
+export interface ModulePreloads {
+	css: string[];
+	js: string[];
+}
+
+export interface ViteManifestEntry {
+	css?: string[];
+	dynamicImports?: string[];
+	file: string;
+	imports?: string[];
+	isDynamicEntry?: boolean;
+	isEntry?: boolean;
+	name?: string;
+	src?: string;
+}
+
+export type ViteManifest = Record<string, ViteManifestEntry>;
+
+/**
+ * Walk Vite manifest from an entry key, collecting all transitive
+ * static imports (JS files) and CSS files.
+ *
+ * Only follows `imports` (static), not `dynamicImports` (lazy routes).
+ * Returns deduplicated, ordered arrays of asset paths.
+ */
+function ensureLeadingSlash(path: string): string {
+	return path.startsWith("/") ? path : `/${path}`;
+}
+
+export function resolveModulePreloads(manifest: ViteManifest, entryKey: string): ModulePreloads {
+	const js: string[] = [];
+	const css: string[] = [];
+	const visited = new Set<string>();
+	const cssVisited = new Set<string>();
+
+	function walk(key: string) {
+		if (visited.has(key)) return;
+		visited.add(key);
+
+		const entry = manifest[key];
+		if (!entry) return;
+
+		js.push(ensureLeadingSlash(entry.file));
+
+		if (entry.css) {
+			for (const href of entry.css) {
+				const path = ensureLeadingSlash(href);
+				if (!cssVisited.has(path)) {
+					cssVisited.add(path);
+					css.push(path);
+				}
+			}
+		}
+
+		if (entry.imports) {
+			for (const dep of entry.imports) {
+				walk(dep);
+			}
+		}
+	}
+
+	walk(entryKey);
+
+	/* Hydrate is a dynamic import from createClient — not a route chunk.
+	   Preload that one hop so Lighthouse does not chain client.js → hydrate.js.
+	   Never follow src/routes/* dynamicImports (those stay lazy). */
+	const root = manifest[entryKey];
+	if (root?.dynamicImports) {
+		for (const dep of root.dynamicImports) {
+			if (/[/\\]hydrate[/\\]index\.[cm]?[tj]sx?$/.test(dep)) {
+				walk(dep);
+			}
+		}
+	}
+
+	return { css, js };
+}
+
+/**
+ * Resolve route-specific chunk preloads from manifest.
+ *
+ * Given a set of matched route module IDs (source paths like
+ * `src/routes/index.tsx`), collects all their chunks + transitive
+ * static imports, excluding any chunks already covered by the entry.
+ *
+ * Returns only the NEW chunks the route needs beyond the entry graph.
+ */
+export function resolveRoutePreloads(
+	manifest: ViteManifest,
+	routeModuleIds: string[],
+	entryPreloads?: ModulePreloads,
+): ModulePreloads {
+	const entryJs = new Set(entryPreloads?.js);
+	const entryCss = new Set(entryPreloads?.css);
+
+	const js: string[] = [];
+	const css: string[] = [];
+	const visited = new Set<string>();
+	const cssVisited = new Set(entryCss);
+
+	function walk(key: string) {
+		if (visited.has(key)) return;
+		visited.add(key);
+
+		const entry = manifest[key];
+		if (!entry) return;
+
+		const file = ensureLeadingSlash(entry.file);
+		if (!entryJs.has(file)) {
+			js.push(file);
+		}
+
+		if (entry.css) {
+			for (const href of entry.css) {
+				const cssFile = ensureLeadingSlash(href);
+				if (!cssVisited.has(cssFile)) {
+					cssVisited.add(cssFile);
+					css.push(cssFile);
+				}
+			}
+		}
+
+		if (entry.imports) {
+			for (const dep of entry.imports) {
+				walk(dep);
+			}
+		}
+	}
+
+	for (const moduleId of routeModuleIds) {
+		walk(moduleId);
+	}
+
+	return { css, js };
+}
+
+/**
+ * Find the entry key in a Vite manifest (the chunk with isEntry: true).
+ */
+export function findEntryKey(manifest: ViteManifest): string | undefined {
+	for (const [key, entry] of Object.entries(manifest)) {
+		if (entry.isEntry) return key;
+	}
+	return undefined;
+}
+
+/**
+ * Merge two ModulePreloads, deduplicating.
+ */
+export function mergePreloads(a: ModulePreloads, b: ModulePreloads): ModulePreloads {
+	const jsSet = new Set(a.js);
+	const cssSet = new Set(a.css);
+
+	const js = [...a.js];
+	const css = [...a.css];
+
+	for (const href of b.js) {
+		if (!jsSet.has(href)) {
+			js.push(href);
+			jsSet.add(href);
+		}
+	}
+
+	for (const href of b.css) {
+		if (!cssSet.has(href)) {
+			css.push(href);
+			cssSet.add(href);
+		}
+	}
+
+	return { css, js };
+}