@lovrozagar/flare 0.1.0

package/src/server/index.ts

@@ -0,0 +1,286 @@
+import {
+	compilePattern,
+	type FlareMiddleware,
+	isPathMatcher,
+	type MiddlewareEntry,
+	type PathMatcher,
+} from "../middleware/index.ts";
+import type { MountConfig } from "../mount/index.ts";
+import type { MarkedRouterConfig } from "../router-config/index.ts";
+import type { SecurityConfig } from "../security/index.ts";
+import type {
+	HandlerCacheConfig,
+	ServerHandler,
+	ServerHandlerConfig,
+	SitemapSubmitConfig,
+	StaticParamsMap,
+	TracingConfig,
+} from "../server-handler/index.ts";
+
+export type { SecurityConfig } from "../security/index.ts";
+export { background } from "@lovrozagar/flare/server-context";
+export type { CdnPurgeAdapter, HandlerCacheConfig } from "../server-handler/index.ts";
+
+/* ── Types ─────────────────────────────────────────────────────────────── */
+
+export interface KeepaliveConfig {
+	handler?: (ctx: import("../middleware").MiddlewareContext) => Promise<void> | void;
+	interval: number;
+}
+
+export type MountTarget =
+	| {
+			fetch: (
+				request: Request,
+				env: unknown,
+				ctx: { waitUntil(p: Promise<unknown>): void },
+			) => Response | Promise<Response>;
+	  }
+	| ((request: Request, env: unknown, ctx: { waitUntil(p: Promise<unknown>): void }) => Response | Promise<Response>);
+
+export interface ServerBuilder<TExcluded extends string = never> {
+	authenticateFn: "authenticateFn" extends TExcluded
+		? never
+		: <TAuth>(
+				fn: (ctx: {
+					callerData?: unknown[];
+					env: unknown;
+					request: Request;
+					serverContext: Record<string, unknown>;
+					url: URL;
+				}) => TAuth | null | Promise<TAuth | null>,
+			) => ServerBuilder<TExcluded | "authenticateFn">;
+	cache: "cache" extends TExcluded ? never : (config: HandlerCacheConfig) => ServerBuilder<TExcluded | "cache">;
+	fetch(request: Request, env?: unknown, ctx?: { waitUntil?: (p: Promise<unknown>) => void }): Promise<Response>;
+	getStaticParams(): Promise<StaticParamsMap>;
+	keepalive: "keepalive" extends TExcluded
+		? never
+		: (config: KeepaliveConfig) => ServerBuilder<TExcluded | "keepalive">;
+	mount(prefix: string, target: MountTarget): ServerBuilder<TExcluded>;
+	security: "security" extends TExcluded
+		? never
+		: (
+				config:
+					| SecurityConfig
+					| ((ctx: {
+							env: unknown;
+							nonce: string;
+							request: Request;
+							serverContext: Record<string, unknown>;
+					  }) => SecurityConfig),
+			) => ServerBuilder<TExcluded | "security">;
+	serverContext: "serverContext" extends TExcluded
+		? never
+		: <T extends Record<string, unknown>>(
+				fn: (ctx: { env: unknown; request: Request }) => T | Promise<T>,
+			) => ServerBuilder<TExcluded | "serverContext">;
+	sitemap: "sitemap" extends TExcluded ? never : (config: SitemapSubmitConfig) => ServerBuilder<TExcluded | "sitemap">;
+	tracing: "tracing" extends TExcluded ? never : (config: TracingConfig) => ServerBuilder<TExcluded | "tracing">;
+	use(...args: (FlareMiddleware | PathMatcher | string)[]): ServerBuilder<TExcluded>;
+}
+
+/* Internal implementation type — no exclusion tracking */
+interface ServerBuilderImpl {
+	authenticateFn(fn: ServerHandlerConfig["authenticateFn"]): ServerBuilderImpl;
+	cache(config: HandlerCacheConfig): ServerBuilderImpl;
+	fetch(request: Request, env?: unknown, ctx?: { waitUntil?: (p: Promise<unknown>) => void }): Promise<Response>;
+	getStaticParams(): Promise<StaticParamsMap>;
+	keepalive(config: KeepaliveConfig): ServerBuilderImpl;
+	mount(prefix: string, target: MountTarget): ServerBuilderImpl;
+	security(
+		config:
+			| SecurityConfig
+			| ((ctx: {
+					env: unknown;
+					nonce: string;
+					request: Request;
+					serverContext: Record<string, unknown>;
+			  }) => SecurityConfig),
+	): ServerBuilderImpl;
+	serverContext(
+		fn: (ctx: { env: unknown; request: Request }) => Record<string, unknown> | Promise<Record<string, unknown>>,
+	): ServerBuilderImpl;
+	sitemap(config: SitemapSubmitConfig): ServerBuilderImpl;
+	tracing(config: TracingConfig): ServerBuilderImpl;
+	use(...args: (FlareMiddleware | PathMatcher | string)[]): ServerBuilderImpl;
+}
+
+/* ── Builder ───────────────────────────────────────────────────────────── */
+
+const KEEPALIVE_PATH = "/_flare/keepalive";
+
+/*
+ * server-handler/index.ts imports virtual modules (virtual:flare-client-entry, etc.)
+ * that only exist inside Vite's module graph. Lazy-importing it in fetch() keeps the
+ * builder module free of those dependencies at evaluation time — this is the correct
+ * boundary: config collection is static, handler creation is runtime.
+ */
+let resolvedCreateServerHandler: typeof import("../server-handler").createServerHandler | undefined;
+
+async function getCreateServerHandler() {
+	if (!resolvedCreateServerHandler) {
+		const mod = await import("../server-handler");
+		resolvedCreateServerHandler = mod.createServerHandler;
+	}
+	return resolvedCreateServerHandler;
+}
+
+function normalizeMountTarget(target: MountTarget): MountConfig["fetch"] {
+	if (typeof target === "function") return target;
+	return (req, env, ctx) => target.fetch(req, env, ctx);
+}
+
+/**
+ * Cloudflare ExecutionContext.waitUntil must be invoked as a method.
+ * Passing the extracted function loses `this` and throws Illegal invocation,
+ * which previously turned a finished SSR into a 500.
+ */
+function bindWaitUntil(ctx?: {
+	waitUntil?: (p: Promise<unknown>) => void;
+}): ((p: Promise<unknown>) => void) | undefined {
+	if (!ctx?.waitUntil) return undefined;
+	return (p) => {
+		ctx.waitUntil!(p);
+	};
+}
+
+export function createServer(router: MarkedRouterConfig): ServerBuilder {
+	const middlewareEntries: MiddlewareEntry[] = [];
+	const mountConfigs: MountConfig[] = [];
+	let authenticateFn: ServerHandlerConfig["authenticateFn"];
+	let serverContextFn: ServerHandlerConfig["serverContext"];
+	let cacheConfig: HandlerCacheConfig | undefined;
+	let keepaliveConfig: KeepaliveConfig | undefined;
+	let securityCfg: ServerHandlerConfig["securityConfig"];
+	let sitemapConfig: SitemapSubmitConfig | undefined;
+	let tracingConfig: TracingConfig | undefined;
+
+	type ResolvedHandler = ServerHandler & {
+		getStaticParams(): Promise<StaticParamsMap>;
+	};
+
+	let cachedHandler: ResolvedHandler | undefined;
+	let handlerConfig: ServerHandlerConfig | undefined;
+
+	async function getHandler(waitUntil?: (p: Promise<unknown>) => void): Promise<ResolvedHandler> {
+		if (cachedHandler && handlerConfig) {
+			handlerConfig.waitUntil = waitUntil;
+			return cachedHandler;
+		}
+
+		const allEntries = [...middlewareEntries];
+
+		if (keepaliveConfig) {
+			const { handler: keepaliveHandler } = keepaliveConfig;
+			const keepaliveMw: FlareMiddleware = async (ctx) => {
+				if (ctx.url.pathname !== KEEPALIVE_PATH || ctx.request.method !== "GET") {
+					return ctx.next();
+				}
+				if (keepaliveHandler) {
+					try {
+						await keepaliveHandler(ctx);
+					} catch {
+						/* swallow keepalive handler errors */
+					}
+				}
+				return ctx.bypass(new Response(null, { status: 204 }));
+			};
+			allEntries.unshift({ middlewares: [keepaliveMw] });
+		}
+
+		/* Inject keepalive interval into router so it serializes to client via FlareState */
+		const routerWithKeepalive = keepaliveConfig
+			? Object.assign({}, router, { keepalive: keepaliveConfig.interval })
+			: router;
+
+		const config: ServerHandlerConfig = {
+			authenticateFn,
+			cache: cacheConfig,
+			middlewareEntries: allEntries,
+			mount: mountConfigs.length > 0 ? mountConfigs : undefined,
+			router: routerWithKeepalive,
+			securityConfig: securityCfg,
+			serverContext: serverContextFn,
+			sitemap: sitemapConfig,
+			tracing: tracingConfig,
+			waitUntil,
+		};
+
+		const create = await getCreateServerHandler();
+		handlerConfig = config;
+		cachedHandler = create(config);
+		return cachedHandler;
+	}
+
+	const builder: ServerBuilderImpl = {
+		authenticateFn(fn) {
+			authenticateFn = fn;
+			return builder;
+		},
+		cache(config) {
+			cacheConfig = config;
+			return builder;
+		},
+		async fetch(request, env, ctx) {
+			const h = await getHandler(bindWaitUntil(ctx));
+			return h.fetch(request, env);
+		},
+		async getStaticParams() {
+			const h = await getHandler();
+			return h.getStaticParams();
+		},
+		keepalive(config) {
+			keepaliveConfig = config;
+			return builder;
+		},
+		mount(prefix, target) {
+			mountConfigs.push({
+				fetch: normalizeMountTarget(target),
+				prefix,
+			});
+			return builder;
+		},
+		security(config) {
+			securityCfg = config;
+			return builder;
+		},
+		serverContext(fn) {
+			serverContextFn = fn;
+			return builder;
+		},
+		sitemap(config) {
+			sitemapConfig = config;
+			return builder;
+		},
+		tracing(config) {
+			tracingConfig = config;
+			return builder;
+		},
+		use(...args) {
+			const matchers: Array<(path: string) => boolean> = [];
+			const middlewares: FlareMiddleware[] = [];
+
+			for (const arg of args) {
+				if (typeof arg === "string") {
+					matchers.push(compilePattern(arg));
+				} else if (isPathMatcher(arg)) {
+					matchers.push(arg);
+				} else {
+					middlewares.push(arg);
+				}
+			}
+
+			if (middlewares.length > 0) {
+				const entry: MiddlewareEntry = { middlewares };
+				if (matchers.length > 0) {
+					entry.matchers = matchers;
+				}
+				middlewareEntries.push(entry);
+			}
+
+			return builder;
+		},
+	};
+
+	return builder as ServerBuilder;
+}

package/src/server-context/browser.ts

@@ -0,0 +1,113 @@
+/**
+ * Browser stub for `flare/server-context`. Resolved via package.json `exports.browser`
+ * condition. Server-context wraps `node:async_hooks` AsyncLocalStorage — Node-only API. Vite's
+ * browser shim throws on `node:*` import access, so the real module cannot load on the client
+ * even when its functions are unreachable. This stub exposes the same surface with throwing
+ * implementations + no Node imports, keeping `node:async_hooks` out of the client bundle entirely.
+ *
+ * If any of these functions actually run in the browser, that is a real bug in the consumer —
+ * they should be guarded by `import.meta.env.SSR` or live inside a stripped server-fn handler.
+ */
+
+import type { CdnPurgeAdapter } from "../revalidation/index.ts";
+import type { FlareStore } from "../store/index.ts";
+
+export interface ServerLogEntry {
+	a: unknown[];
+	l: "error" | "log" | "warn";
+	s?: string;
+}
+
+export interface ServerRequestContextStore {
+	get<T>(key: string): T | undefined;
+	set<K extends string, V>(key: K, value: V): void;
+}
+
+export interface RunWithServerContextOptions {
+	cdnPurgeAdapter?: CdnPurgeAdapter;
+	isDev?: boolean;
+	nonce: string;
+	request: Request;
+	serverContext?: Record<string, unknown>;
+	store?: FlareStore;
+	waitUntil?: (promise: Promise<unknown>) => void;
+}
+
+const ERR =
+	"Flare server-context API called in the browser. Move call into a server-fn handler or guard with import.meta.env.SSR.";
+
+function unreachable(): never {
+	throw new Error(ERR);
+}
+
+export function generateNonce(): string {
+	const bytes = crypto.getRandomValues(new Uint8Array(16));
+	let hex = "";
+	for (const b of bytes) {
+		hex += b.toString(16).padStart(2, "0");
+	}
+	return hex;
+}
+
+export function runWithServerContext<T>(_opts: RunWithServerContextOptions, _cb: () => T): T {
+	return unreachable();
+}
+
+export function getServerNonce(): string {
+	return "";
+}
+
+export function setServerNonce(_nonce: string): void {
+	unreachable();
+}
+
+export function getServerRequest(): Request {
+	return unreachable();
+}
+
+export function getServerRequestContext(): ServerRequestContextStore {
+	return unreachable();
+}
+
+export function getServerContext<T extends Record<string, unknown> = Record<string, unknown>>(): T {
+	return unreachable() as T;
+}
+
+export function getRevalidationContext(): {
+	cdnPurgeAdapter?: CdnPurgeAdapter;
+	store?: FlareStore;
+} {
+	return {};
+}
+
+export function addRevalidatedTags(_tags: string[]): void {
+	/* no-op on browser — revalidation is server-only */
+}
+
+export function getRevalidatedTags(): string[] {
+	return [];
+}
+
+export function serverLog(_level: "error" | "log" | "warn", ..._args: unknown[]): void {
+	/* no-op on browser */
+}
+
+export function getServerLogs(): ServerLogEntry[] {
+	return [];
+}
+
+export function background(_promise: Promise<unknown>): void {
+	/* no-op on browser */
+}
+
+export interface FormActionContext {
+	[key: string]: unknown;
+}
+
+export function setFormActionContext(_fnId: string, _ctx: FormActionContext): void {
+	unreachable();
+}
+
+export function getFormActionContext(_fnId: string): FormActionContext | undefined {
+	return undefined;
+}

package/src/server-context/index.ts

@@ -0,0 +1,217 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { CdnPurgeAdapter } from "../revalidation/index.ts";
+import type { FlareStore } from "../store/index.ts";
+
+export interface ServerLogEntry {
+	a: unknown[];
+	l: "error" | "log" | "warn";
+	/** Server-side source location (dev only) */
+	s?: string;
+}
+
+interface ServerContextValue {
+	cdnPurgeAdapter?: CdnPurgeAdapter;
+	isDev?: boolean;
+	nonce: string;
+	request: Request;
+	requestStore: Map<string, unknown>;
+	serverContext: Record<string, unknown>;
+	store?: FlareStore;
+	waitUntil?: (promise: Promise<unknown>) => void;
+}
+
+export interface ServerRequestContextStore {
+	get<T>(key: string): T | undefined;
+	set<K extends string, V>(key: K, value: V): void;
+}
+
+let storage: AsyncLocalStorage<ServerContextValue> | undefined;
+
+function getStorage(): AsyncLocalStorage<ServerContextValue> {
+	if (!storage) {
+		storage = new AsyncLocalStorage<ServerContextValue>();
+	}
+	return storage;
+}
+
+function getContext(): ServerContextValue {
+	const ctx = getStorage().getStore();
+	if (!ctx) {
+		throw new Error(
+			"getServerContext() called outside request context. Must be called during request handling (route handler, middleware, or server function).",
+		);
+	}
+	return ctx;
+}
+
+export function generateNonce(): string {
+	const bytes = crypto.getRandomValues(new Uint8Array(16));
+	let hex = "";
+	for (const b of bytes) {
+		hex += b.toString(16).padStart(2, "0");
+	}
+	return hex;
+}
+
+export interface RunWithServerContextOptions {
+	cdnPurgeAdapter?: CdnPurgeAdapter;
+	isDev?: boolean;
+	nonce: string;
+	request: Request;
+	serverContext?: Record<string, unknown>;
+	store?: FlareStore;
+	waitUntil?: (promise: Promise<unknown>) => void;
+}
+
+export function runWithServerContext<T>(options: RunWithServerContextOptions, callback: () => T): T {
+	const value: ServerContextValue = {
+		cdnPurgeAdapter: options.cdnPurgeAdapter,
+		isDev: options.isDev,
+		nonce: options.nonce,
+		request: options.request,
+		requestStore: new Map(),
+		serverContext: options.serverContext ?? {},
+		store: options.store,
+		waitUntil: options.waitUntil,
+	};
+	return getStorage().run(value, callback);
+}
+
+export function getServerNonce(): string {
+	return getContext().nonce;
+}
+
+export function setServerNonce(nonce: string): void {
+	getContext().nonce = nonce;
+}
+
+export function getServerRequest(): Request {
+	return getContext().request;
+}
+
+export function getServerRequestContext(): ServerRequestContextStore {
+	const ctx = getContext();
+	return {
+		get<T>(key: string): T | undefined {
+			return ctx.requestStore.get(key) as T | undefined;
+		},
+		set<K extends string, V>(key: K, value: V): void {
+			ctx.requestStore.set(key, value);
+		},
+	};
+}
+
+const EMPTY_CONTEXT: Record<string, unknown> = Object.freeze(Object.create(null));
+
+export function getServerContext<T extends Record<string, unknown> = Record<string, unknown>>(): T {
+	const ctx = getStorage().getStore();
+	if (!ctx) return EMPTY_CONTEXT as T;
+	return ctx.serverContext as T;
+}
+
+export function getRevalidationContext(): {
+	cdnPurgeAdapter?: CdnPurgeAdapter;
+	store?: FlareStore;
+} {
+	const ctx = getStorage().getStore();
+	if (!ctx) return {};
+	return {
+		cdnPurgeAdapter: ctx.cdnPurgeAdapter,
+		store: ctx.store,
+	};
+}
+
+const REVALIDATED_TAGS_KEY = "__flare_revalidated_tags";
+
+export function addRevalidatedTags(tags: string[]): void {
+	const ctx = getStorage().getStore();
+	if (!ctx) return;
+	const existing = (ctx.requestStore.get(REVALIDATED_TAGS_KEY) as string[] | undefined) ?? [];
+	const merged = new Set(existing);
+	for (const tag of tags) {
+		merged.add(tag);
+	}
+	ctx.requestStore.set(REVALIDATED_TAGS_KEY, [...merged]);
+}
+
+export function getRevalidatedTags(): string[] {
+	const ctx = getStorage().getStore();
+	if (!ctx) return [];
+	return (ctx.requestStore.get(REVALIDATED_TAGS_KEY) as string[] | undefined) ?? [];
+}
+
+const SERVER_LOGS_KEY = "__flare_server_logs";
+const MAX_SERVER_LOGS = 1000;
+
+const CALLER_RE = /\((.+):(\d+):\d+\)|at\s+(.+):(\d+):\d+/;
+
+function parseCallerLocation(): string | undefined {
+	const stack = new Error().stack;
+	if (!stack) return undefined;
+	/* Frame 0 = Error, 1 = parseCallerLocation, 2 = serverLog, 3 = ctx.log/warn/error wrapper, 4 = user code */
+	const frame = stack.split("\n")[4];
+	if (!frame) return undefined;
+	const m = CALLER_RE.exec(frame);
+	if (!m) return undefined;
+	const file = m[1] ?? m[3] ?? "";
+	const line = m[2] ?? m[4] ?? "";
+	/* Strip to relative path from src/ or routes/ */
+	const srcIdx = file.lastIndexOf("/src/");
+	const short = srcIdx >= 0 ? file.slice(srcIdx + 1) : file.split("/").slice(-2).join("/");
+	return `${short}:${line}`;
+}
+
+export function serverLog(level: "error" | "log" | "warn", ...args: unknown[]): void {
+	const ctx = getStorage().getStore();
+	if (!ctx) return;
+	const logs = (ctx.requestStore.get(SERVER_LOGS_KEY) as ServerLogEntry[] | undefined) ?? [];
+	if (logs.length >= MAX_SERVER_LOGS) return;
+	const entry: ServerLogEntry = { a: args, l: level };
+	if (ctx.isDev) {
+		const loc = parseCallerLocation();
+		if (loc) entry.s = loc;
+	}
+	logs.push(entry);
+	ctx.requestStore.set(SERVER_LOGS_KEY, logs);
+}
+
+export function getServerLogs(): ServerLogEntry[] {
+	const ctx = getStorage().getStore();
+	if (!ctx) return [];
+	return (ctx.requestStore.get(SERVER_LOGS_KEY) as ServerLogEntry[] | undefined) ?? [];
+}
+
+/* ── Form action context (PE POST error re-render) ─────────────────── */
+
+export interface FormActionContext {
+	fieldErrors: Record<string, string[]>;
+	formErrors: string[];
+	message: string;
+	values: Record<string, unknown>;
+}
+
+export function setFormActionContext(fnId: string, ctx: FormActionContext): void {
+	const store = getStorage().getStore();
+	if (!store) return;
+	store.requestStore.set(`__flare_form:${fnId}`, ctx);
+}
+
+export function getFormActionContext(fnId: string): FormActionContext | undefined {
+	const store = getStorage().getStore();
+	if (!store) return undefined;
+	return store.requestStore.get(`__flare_form:${fnId}`) as FormActionContext | undefined;
+}
+
+export function background(promise: Promise<unknown>): void {
+	const ctx = getContext();
+	if (ctx.waitUntil) {
+		try {
+			ctx.waitUntil(promise);
+			return;
+		} catch {
+			/* Cloudflare's waitUntil is a method. An extracted unbound fn throws
+			   Illegal invocation — never fail the request for bookkeeping. */
+		}
+	}
+	promise.catch(() => {});
+}