@lovrozagar/flare 0.1.0

package/src/locale/index.tsx

@@ -0,0 +1,137 @@
+import {
+	createContext,
+	createEffect,
+	createSignal,
+	type JSX,
+	on,
+	onCleanup,
+	onMount,
+	sharedConfig,
+	useContext,
+} from "solid-js";
+import { BroadcastCtx } from "../broadcast/context.ts";
+import { escapeJsString } from "../theme/index.tsx";
+
+/* ── Types ─────────────────────────────────────────────────────────── */
+
+export interface LocaleConfig {
+	broadcast?: boolean;
+	cookieName?: string;
+	defaultLocale: string;
+	locales: readonly string[];
+	paramName?: string;
+	skip?: readonly string[];
+	syncDirection?: boolean;
+}
+
+export interface LocaleContextValue {
+	defaultLocale: string;
+	locale: () => string;
+	locales: readonly string[];
+	setLocale: (locale: string) => void;
+}
+
+/* ── getLocaleScript ───────────────────────────────────────────────── */
+
+export function getLocaleScript(opts: LocaleConfig): string {
+	const defaultLocale = escapeJsString(opts.defaultLocale);
+	return `(d=>{var e=document.documentElement;e.setAttribute("lang",e.getAttribute("lang")||d)})("${defaultLocale}")`;
+}
+
+/* ── Context ───────────────────────────────────────────────────────── */
+
+const LocaleCtx = createContext<LocaleContextValue>();
+
+export function LocaleProvider(props: { children: JSX.Element; config: LocaleConfig; initial?: string }): JSX.Element {
+	if (sharedConfig.context) {
+		return props.children;
+	}
+
+	const cfg = props.config;
+	const defaultLocale = cfg.defaultLocale;
+	const cookieName = cfg.cookieName ?? "flare.locale";
+
+	/* Capture context at component setup level (not inside onMount) */
+	const channel = cfg.broadcast ? useContext(BroadcastCtx) : undefined;
+
+	/* URL is truth: initial comes from server (URL params), not localStorage */
+	const initial = props.initial ?? defaultLocale;
+	const [locale, setLocaleSignal] = createSignal(initial);
+
+	/* Cross-tab sync: BroadcastChannel for locale (opt-in) */
+	onMount(() => {
+		if (!channel) return;
+
+		const unsubscribe = channel.onMessage((msg) => {
+			if (msg.type === "locale" && typeof msg.value === "string" && cfg.locales.includes(msg.value)) {
+				setLocaleSignal(msg.value);
+			}
+		});
+
+		createEffect(
+			on(
+				locale,
+				(l) => {
+					channel.broadcast({ type: "locale", value: l });
+				},
+				{ defer: true },
+			),
+		);
+
+		onCleanup(unsubscribe);
+	});
+
+	createEffect(() => {
+		const l = locale();
+		if (typeof document === "undefined") return;
+		document.documentElement.setAttribute("lang", l);
+		document.cookie = `${cookieName}=${l}; path=/; max-age=31536000; samesite=lax`;
+	});
+
+	const setLocale = (l: string): void => {
+		if (!cfg.locales.includes(l)) return;
+		setLocaleSignal(l);
+	};
+
+	const value: LocaleContextValue = {
+		defaultLocale,
+		locale,
+		locales: cfg.locales,
+		setLocale,
+	};
+
+	return <LocaleCtx.Provider value={value}>{props.children}</LocaleCtx.Provider>;
+}
+
+export function useLocale(): LocaleContextValue {
+	const ctx = useContext(LocaleCtx);
+	if (!ctx)
+		throw new Error(
+			"useLocale() called outside LocaleProvider. Ensure <LocaleProvider> wraps components using locale hooks.",
+		);
+	return ctx;
+}
+
+/* ── buildHreflangLinks ────────────────────────────────────────────── */
+
+export function buildHreflangLinks(opts: {
+	baseUrl: string;
+	config: LocaleConfig;
+	pathname: string;
+}): Record<string, string> {
+	const base = opts.baseUrl.replace(/\/$/, "");
+	const links: Record<string, string> = {};
+
+	for (const locale of opts.config.locales) {
+		if (locale === opts.config.defaultLocale) {
+			links[locale] = `${base}${opts.pathname}`;
+		} else {
+			const path = opts.pathname === "/" ? "" : opts.pathname;
+			links[locale] = `${base}/${locale}${path}`;
+		}
+	}
+
+	links["x-default"] = links[opts.config.defaultLocale] ?? `${base}${opts.pathname}`;
+
+	return links;
+}

package/src/locale.ts

@@ -0,0 +1,3 @@
+export { LocaleScript } from "./components/locale-script.tsx";
+export type { LocaleConfig, LocaleContextValue } from "./locale/index.tsx";
+export { buildHreflangLinks, getLocaleScript, LocaleProvider, useLocale } from "./locale/index.tsx";

package/src/logger.ts

@@ -0,0 +1,22 @@
+import defaultLevel from "virtual:flare-log-level";
+
+export type LogLevel = "error" | "silent" | "verbose" | "warn";
+
+const PRIORITY: Record<LogLevel, number> = { error: 1, silent: 0, verbose: 3, warn: 2 };
+
+const level: LogLevel = defaultLevel;
+
+export function warn(tag: string, msg: string, data?: unknown): void {
+	if (PRIORITY[level] < 2) return;
+	console.warn(`[flare:${tag}]`, msg, ...(data !== undefined ? [data] : []));
+}
+
+export function error(tag: string, msg: string, data?: unknown): void {
+	if (PRIORITY[level] < 1) return;
+	console.error(`[flare:${tag}]`, msg, ...(data !== undefined ? [data] : []));
+}
+
+export function verbose(tag: string, msg: string, data?: unknown): void {
+	if (PRIORITY[level] < 3) return;
+	console.log(`[flare:${tag}]`, msg, ...(data !== undefined ? [data] : []));
+}

package/src/middleware/builtins/api-proxy.ts

@@ -0,0 +1,64 @@
+import type { FlareMiddleware, MiddlewareContext } from "..";
+
+interface ServiceBinding {
+	fetch: (request: Request) => Promise<Response>;
+}
+
+interface ApiProxyConfig<TEnv = unknown> {
+	enabled?: boolean | ((ctx: { env: TEnv }) => boolean);
+	headers?: (ctx: { env: TEnv; request: Request }) => Record<string, string>;
+	pathPrefix: string;
+	rewrite?: (path: string) => string;
+	target: (ctx: { env: TEnv }) => ServiceBinding;
+}
+
+export function apiProxy<TEnv = unknown>(config: ApiProxyConfig<TEnv>): FlareMiddleware<TEnv> {
+	return async (ctx: MiddlewareContext<TEnv>) => {
+		/* check enabled */
+		if (config.enabled !== undefined) {
+			const enabled = typeof config.enabled === "function" ? config.enabled({ env: ctx.env }) : config.enabled;
+			if (!enabled) return ctx.next();
+		}
+
+		/* check path match */
+		const pathname = ctx.url.pathname;
+		if (pathname !== config.pathPrefix && !pathname.startsWith(`${config.pathPrefix}/`)) {
+			return ctx.next();
+		}
+
+		try {
+			/* rewrite path */
+			let targetPath = pathname;
+			if (config.rewrite) {
+				targetPath = config.rewrite(pathname);
+			} else {
+				targetPath = pathname.slice(config.pathPrefix.length) || "/";
+			}
+
+			/* build proxied request */
+			const targetUrl = new URL(targetPath, ctx.url.origin);
+			targetUrl.search = ctx.url.search;
+			const headers = new Headers(ctx.request.headers);
+
+			if (config.headers) {
+				const extra = config.headers({ env: ctx.env, request: ctx.request });
+				for (const [k, v] of Object.entries(extra)) {
+					headers.set(k, v);
+				}
+			}
+
+			const proxyRequest = new Request(targetUrl.toString(), {
+				body: ctx.request.body,
+				duplex: "half",
+				headers,
+				method: ctx.request.method,
+			} as RequestInit);
+
+			const service = config.target({ env: ctx.env });
+			const response = await service.fetch(proxyRequest);
+			return ctx.bypass(response);
+		} catch {
+			return ctx.bypass(new Response("Bad Gateway", { status: 502 }));
+		}
+	};
+}

package/src/middleware/builtins/cdn-proxy.ts

@@ -0,0 +1,58 @@
+import type { FlareMiddleware, MiddlewareContext } from "..";
+
+interface R2Object {
+	body: ReadableStream;
+	etag: string;
+	httpMetadata?: { contentType?: string };
+	size: number;
+}
+
+interface R2BucketBinding {
+	get: (key: string) => Promise<R2Object | null>;
+}
+
+interface CdnProxyConfig<TEnv = unknown> {
+	bucket: (ctx: { env: TEnv }) => R2BucketBinding;
+	cacheControl?: string;
+	edgeCache?: boolean;
+	pathPrefix: string;
+}
+
+export function cdnProxy<TEnv = unknown>(config: CdnProxyConfig<TEnv>): FlareMiddleware<TEnv> {
+	const defaultCacheControl = config.cacheControl ?? "public, max-age=31536000, immutable";
+
+	return async (ctx: MiddlewareContext<TEnv>) => {
+		const pathname = ctx.url.pathname;
+		if (!pathname.startsWith(`${config.pathPrefix}/`)) return ctx.next();
+
+		const rawKey = pathname.slice(config.pathPrefix.length + 1);
+		let key: string;
+		try {
+			key = decodeURIComponent(rawKey);
+		} catch {
+			return ctx.bypass(new Response("Bad Request", { status: 400 }));
+		}
+		/* Reject path traversal, null bytes, backslashes, and CRLF */
+		if (key.includes("..") || key.includes("\0") || key.includes("\\") || key.includes("\r") || key.includes("\n")) {
+			return ctx.bypass(new Response("Bad Request", { status: 400 }));
+		}
+		const bucket = config.bucket({ env: ctx.env });
+		const object = await bucket.get(key);
+
+		if (!object) {
+			return ctx.bypass(new Response("Not Found", { status: 404 }));
+		}
+
+		const headers: Record<string, string> = {
+			"Cache-Control": defaultCacheControl,
+			"Content-Length": String(object.size),
+			ETag: object.etag,
+		};
+
+		if (object.httpMetadata?.contentType) {
+			headers["Content-Type"] = object.httpMetadata.contentType;
+		}
+
+		return ctx.bypass(new Response(object.body, { headers }));
+	};
+}

package/src/middleware/builtins/i18n.ts

@@ -0,0 +1,256 @@
+import { match as cldrMatch } from "@formatjs/intl-localematcher";
+import { isbot } from "isbot";
+import Negotiator from "negotiator";
+import type { FlareMiddleware } from "..";
+import { matchRoute, toLocaleMatch } from "../../router-primitives/tree.ts";
+
+/**
+ * Matches BCP-47-like path segments with 2-letter primary subtag:
+ * xx, xx-YY, xx-Yyyy, xx-Yyyy-ZZ
+ * Covers: en, en-us, zh-hans, zh-hant-tw, sr-latn, pt-br
+ * Uses 2-letter primary only to avoid false positives on route
+ * segments like isr-test, env-fn-test, api-data.
+ */
+const LOCALE_LIKE_RE = /^[a-z]{2}(-[a-z]{2,4}){0,2}$/i;
+
+export interface I18nMiddlewareOptions {
+	botDetection?: boolean;
+	cookie?: {
+		maxAge?: number;
+		secure?: boolean;
+	};
+	cookieName?: string;
+	skip?: readonly string[];
+}
+
+function getLocaleFromPath(pathname: string, localeSet: Set<string>): string | null {
+	const slashIdx = pathname.indexOf("/", 1);
+	const segment = (slashIdx === -1 ? pathname.slice(1) : pathname.slice(1, slashIdx)).toLowerCase();
+	return localeSet.has(segment) ? segment : null;
+}
+
+function getLocaleFromCookie(request: Request, cookieName: string, localeSet: Set<string>): string | null {
+	const cookieHeader = request.headers.get("cookie");
+	if (!cookieHeader) return null;
+	for (const pair of cookieHeader.split(";")) {
+		const eqIdx = pair.indexOf("=");
+		if (eqIdx === -1) continue;
+		const name = pair.slice(0, eqIdx).trim();
+		if (name !== cookieName) continue;
+		const locale = pair
+			.slice(eqIdx + 1)
+			.trim()
+			.toLowerCase();
+		return localeSet.has(locale) ? locale : null;
+	}
+	return null;
+}
+
+function getLocaleFromAcceptLanguage(request: Request, locales: readonly string[], defaultLocale: string): string {
+	const acceptLanguage = request.headers.get("accept-language");
+	if (!acceptLanguage) return defaultLocale;
+
+	const negotiator = new Negotiator({ headers: { "accept-language": acceptLanguage } });
+	const requested = negotiator.languages();
+	if (requested.length === 0) return defaultLocale;
+
+	for (const req of requested) {
+		try {
+			const result = cldrMatch([req], locales as string[], "");
+			if (result && result !== "") {
+				return result.toLowerCase();
+			}
+		} catch {
+			/* no match, try next */
+		}
+	}
+
+	return defaultLocale;
+}
+
+function buildCookieHeader(
+	locale: string,
+	cookieName: string,
+	maxAge: number,
+	isHttps: boolean,
+	secure?: boolean,
+): string {
+	/* Defense-in-depth: strip chars that could enable header/cookie injection.
+	 * Primary gate is localeSet.has() before any call site, but this guards
+	 * against future code paths that might bypass that check. */
+	const safe = locale.replace(/[\r\n;\0]/g, "");
+	const secureFlag = (secure ?? isHttps) ? "; Secure" : "";
+	return `${cookieName}=${safe}; Path=/; Max-Age=${maxAge}; SameSite=Lax${secureFlag}`;
+}
+
+export function i18n(options?: I18nMiddlewareOptions): FlareMiddleware {
+	let cachedLocales: readonly string[] | null = null;
+	let cachedLocaleSet: Set<string> = new Set();
+	let cachedSkipPaths: string[] = [];
+	let cachedCookieName = "";
+	let cachedMaxAge = 0;
+	return async (ctx) => {
+		if (!ctx.locale) {
+			throw new Error(
+				'i18n() middleware requires locale config on the router. Use router.locale({ locales: [...], defaultLocale: "..." }).',
+			);
+		}
+		const { defaultLocale, locales } = ctx.locale;
+		if (cachedLocales !== locales) {
+			cachedLocales = locales;
+			cachedLocaleSet = new Set(locales.map((l) => l.toLowerCase()));
+			cachedCookieName = options?.cookieName ?? ctx.locale.cookieName ?? "flare.locale";
+			cachedMaxAge = options?.cookie?.maxAge ?? 31536000;
+			const skip = options?.skip ?? ctx.locale.skip ?? [];
+			cachedSkipPaths = ["/_fn/", ...skip];
+		}
+
+		const { pathname } = ctx.url;
+		const isHttps = ctx.url.protocol === "https:";
+
+		/* Prerender snapshots the exact expanded URL — do not locale-redirect. */
+		if (ctx.request.headers.get("x-flare-prerender") === "1") {
+			const prerenderLocale = getLocaleFromPath(pathname, cachedLocaleSet);
+			ctx.serverContext.locale = prerenderLocale ?? defaultLocale;
+			return ctx.next();
+		}
+
+		/* Bots get default locale for consistent SEO */
+		if (options?.botDetection !== false) {
+			const userAgent = ctx.request.headers.get("user-agent") ?? "";
+			if (isbot(userAgent)) {
+				ctx.serverContext.locale = defaultLocale;
+				return ctx.next();
+			}
+		}
+
+		/* Skip configured paths */
+		for (const skipPath of cachedSkipPaths) {
+			if (pathname.startsWith(skipPath)) {
+				ctx.serverContext.locale = defaultLocale;
+				return ctx.next();
+			}
+		}
+
+		/* Skip files with extensions */
+		const lastDot = pathname.lastIndexOf(".");
+		if (lastDot > pathname.lastIndexOf("/")) {
+			ctx.serverContext.locale = defaultLocale;
+			return ctx.next();
+		}
+
+		/* Normalize locale case (EN-US -> en-us) */
+		const slashIdx = pathname.indexOf("/", 1);
+		const firstSegment = slashIdx === -1 ? pathname.slice(1) : pathname.slice(1, slashIdx);
+
+		if (firstSegment && LOCALE_LIKE_RE.test(firstSegment)) {
+			const lowerSegment = firstSegment.toLowerCase();
+			if (firstSegment !== lowerSegment) {
+				const newUrl = new URL(ctx.url);
+				newUrl.pathname = pathname.replace(firstSegment, lowerSegment);
+				const headers = new Headers({ Location: newUrl.href });
+				if (cachedLocaleSet.has(lowerSegment)) {
+					headers.set(
+						"Set-Cookie",
+						buildCookieHeader(lowerSegment, cachedCookieName, cachedMaxAge, isHttps, options?.cookie?.secure),
+					);
+				}
+				return ctx.bypass(new Response(null, { headers, status: 302 }));
+			}
+		}
+
+		const pathLocale = getLocaleFromPath(pathname, cachedLocaleSet);
+		const cookieLocale = getLocaleFromCookie(ctx.request, cachedCookieName, cachedLocaleSet);
+		const hasInvalidLocale = !pathLocale && firstSegment !== "" && LOCALE_LIKE_RE.test(firstSegment);
+
+		/* Invalid/unsupported locale-like segment in path → strip it */
+		if (hasInvalidLocale) {
+			const newUrl = new URL(ctx.url);
+			newUrl.pathname = pathname.replace(`/${firstSegment}`, "") || "/";
+			const headers = new Headers({ Location: newUrl.href });
+			headers.set(
+				"Set-Cookie",
+				buildCookieHeader(defaultLocale, cachedCookieName, cachedMaxAge, isHttps, options?.cookie?.secure),
+			);
+			return ctx.bypass(new Response(null, { headers, status: 302 }));
+		}
+
+		/* Default locale in URL → strip prefix when the unprefixed path is a real route.
+		   Required `[locale]/ssg-about` has no `/ssg-about` twin — keep `/en/ssg-about`. */
+		if (pathLocale === defaultLocale) {
+			const strippedPath = pathname.replace(`/${defaultLocale}`, "") || "/";
+			const canStrip =
+				!ctx.routeTree || matchRoute(ctx.routeTree, strippedPath, false, toLocaleMatch(ctx.locale)) !== null;
+			if (canStrip) {
+				const newUrl = new URL(ctx.url);
+				newUrl.pathname = strippedPath;
+				const headers = new Headers({ Location: newUrl.href });
+				headers.set(
+					"Set-Cookie",
+					buildCookieHeader(defaultLocale, cachedCookieName, cachedMaxAge, isHttps, options?.cookie?.secure),
+				);
+				return ctx.bypass(new Response(null, { headers, status: 302 }));
+			}
+		}
+
+		/*
+		 * First visit to root — Accept-Language redirect.
+		 * Only when no cookie exists (truly first visit).
+		 */
+		if (!pathLocale && pathname === "/" && !cookieLocale) {
+			const acceptLocale = getLocaleFromAcceptLanguage(ctx.request, locales, defaultLocale);
+			if (acceptLocale !== defaultLocale) {
+				const newUrl = new URL(ctx.url);
+				newUrl.pathname = `/${acceptLocale}`;
+				const headers = new Headers({ Location: newUrl.href });
+				headers.set(
+					"Set-Cookie",
+					buildCookieHeader(acceptLocale, cachedCookieName, cachedMaxAge, isHttps, options?.cookie?.secure),
+				);
+				return ctx.bypass(new Response(null, { headers, status: 302 }));
+			}
+		}
+
+		/*
+		 * Cookie-respect redirect: unprefixed SSR path + cookie has non-default locale.
+		 * Only for full page loads (not NDJSON/prefetch — SPA router handles those).
+		 * e.g. /about with cookie=fr → 302 → /fr/about
+		 */
+		const isDataRequest = ctx.request.headers.get("x-d") === "1";
+		if (!pathLocale && cookieLocale && cookieLocale !== defaultLocale && !isDataRequest) {
+			const newUrl = new URL(ctx.url);
+			newUrl.pathname = `/${cookieLocale}${pathname}`;
+			return ctx.bypass(
+				new Response(null, {
+					headers: new Headers({ Location: newUrl.href }),
+					status: 302,
+				}),
+			);
+		}
+
+		/* URL is truth: locale comes from path, or default if no prefix */
+		const currentLocale = pathLocale ?? defaultLocale;
+		ctx.serverContext.locale = currentLocale;
+
+		/* Prefetch requests must not set cookies — SPA prefetches multiple
+		 * locale URLs after hydration, and the last one to complete would
+		 * overwrite the correct cookie from the actual page load. */
+		const isPrefetch = ctx.request.headers.get("x-p") === "1";
+		const needsCookie = !isPrefetch && currentLocale !== cookieLocale;
+		if (needsCookie) {
+			const setCookieHeader = buildCookieHeader(
+				currentLocale,
+				cachedCookieName,
+				cachedMaxAge,
+				isHttps,
+				options?.cookie?.secure,
+			);
+			ctx.onResponse((response) => {
+				response.headers.append("Set-Cookie", setCookieHeader);
+				return response;
+			});
+		}
+
+		return ctx.next();
+	};
+}

package/src/middleware/builtins/keepalive.ts

@@ -0,0 +1,24 @@
+import { error } from "../../logger.ts";
+import type { FlareMiddleware, MiddlewareContext } from "..";
+
+const PING_PATH = "/_flare/keepalive";
+
+interface KeepaliveConfig<TEnv = unknown> {
+	handler?: (ctx: MiddlewareContext<TEnv>) => Promise<void> | void;
+}
+
+export function keepalive<TEnv = unknown>(config?: KeepaliveConfig<TEnv>): FlareMiddleware<TEnv> {
+	return async (ctx: MiddlewareContext<TEnv>) => {
+		if (ctx.url.pathname !== PING_PATH || ctx.request.method !== "GET") return ctx.next();
+
+		if (config?.handler) {
+			try {
+				await config.handler(ctx);
+			} catch (e: unknown) {
+				error("keepalive", "handler error", e);
+			}
+		}
+
+		return ctx.bypass(new Response(null, { status: 204 }));
+	};
+}