@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/server/adapters/platforms.ts

@@ -0,0 +1,79 @@
+/**
+ * Platform Adapters — wrap a FrameworkFetchHandler for non-web-server
+ * runtimes:
+ *
+ *   const handler = createAppServer({ app: App });
+ *   export default toFetchAdapter(handler);          // deno/vercel/bun
+ *   export const onRequest = cloudflareAdapter(handler); // workers/pages
+ *   nodeAdapter(handler).listen(3000);                // plain node
+ */
+
+import type { FrameworkFetchHandler } from "./web-server";
+
+/** Generic fetch adapter — `export default` in Deno/Vercel/Bun entries */
+export const toFetchAdapter = (
+	handler: FrameworkFetchHandler,
+): { fetch: FrameworkFetchHandler } => ({ fetch: handler });
+
+/** Cloudflare Workers/Pages — event handler signature */
+export const cloudflareAdapter =
+	(
+		handler: FrameworkFetchHandler,
+	): ((request: Request, env?: unknown, ctx?: unknown) => Promise<Response>) =>
+	async (request) =>
+		handler(request);
+
+/** Deno.serve / generic — identity with a serve() convenience */
+export const denoAdapter = (handler: FrameworkFetchHandler) => ({
+	fetch: handler,
+	serve: (options?: { port?: number }) =>
+		// deno global — not typed here
+		(
+			globalThis as { Deno?: { serve: (o: object, h: unknown) => void } }
+		).Deno?.serve({ port: options?.port ?? 8000 }, handler),
+});
+
+/**
+ * Node http(s) adapter — converts IncomingMessage ↔ web Request;
+ * no deps beyond node:http
+ */
+export const nodeAdapter = (handler: FrameworkFetchHandler) => ({
+	fetch: handler,
+	listen: async (port = 3000, host = "0.0.0.0") => {
+		const { createServer } = await import("node:http");
+		const server = createServer(async (req, res) => {
+			const url = `http://${req.headers.host ?? "localhost"}${req.url ?? "/"}`;
+			const body =
+				req.method === "GET" || req.method === "HEAD"
+					? undefined
+					: new ReadableStream({
+							start(c) {
+								req.on("data", (chunk) => c.enqueue(chunk));
+								req.on("end", () => c.close());
+								req.on("error", (e) => c.error(e));
+							},
+						});
+			const response = await handler(
+				new Request(url, {
+					method: req.method,
+					headers: req.headers as Record<string, string>,
+					body,
+					...({ duplex: "half" } as object),
+				}),
+			);
+			res.statusCode = response.status;
+			for (const [k, v] of response.headers) res.setHeader(k, v);
+			if (response.body) {
+				const reader = response.body.getReader();
+				for (;;) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					res.write(value);
+				}
+			}
+			res.end();
+		});
+		server.listen(port, host);
+		return server;
+	},
+});

package/src/server/adapters/web-server/index.ts

@@ -0,0 +1,281 @@
+/**
+ * Web Server Adapter
+ * Composes the framework request pipeline on top of @wrikka/web-server-toolkit:
+ *
+ *   /_server/fn/*     → server function dispatch
+ *   /_server/action/* → progressive-enhancement form actions
+ *   api prefixes      → web-server routes, then optional apiHandler fallback
+ *   everything else   → SSR render handler
+ */
+
+import type { Route } from "@wrikka/web-server-toolkit";
+import { runWithRequest, useRequestEvent } from "#server/modules/http";
+import {
+	createBatchHandler,
+	createLiveQueryHandler,
+	createServerFnHandler,
+	isBatchRequest,
+	isLiveRequest,
+	isSameOriginRequest,
+	isServerFnRequest,
+	type ServerFnCsrfOptions,
+} from "#server/modules/server-functions";
+
+export interface FrameworkServerOptions {
+	/**
+	 * API routes handled by @wrikka/web-server-toolkit — created with its
+	 * routing/file-system-routing modules and middleware engine
+	 */
+	routes?: Route[];
+	/**
+	 * Fetch-based API fallback (Elysia `.fetch`, Hono, custom web-server
+	 * handler) — tried when no web-server route matches
+	 */
+	apiHandler?: (request: Request) => Promise<Response>;
+	/**
+	 * Fallback handler for page requests — typically createServerEntry()
+	 * from #render or a custom render pipeline
+	 */
+	render: (request: Request) => Promise<Response>;
+	/**
+	 * Handler for `/_server/action/*` — pass createActionHandler() from
+	 * #actions to enable progressive-enhancement form actions
+	 */
+	actionHandler?: (request: Request) => Promise<Response>;
+	/**
+	 * Handler for the image optimization endpoint — serves `/_image`
+	 * requests (default endpoint path)
+	 */
+	imageHandler?: (request: Request) => Promise<Response>;
+	/** Image endpoint path — defaults to "/_image" */
+	imageEndpoint?: string;
+	/** Additional prefix routed to web-server — defaults to ["/api"] */
+	apiPrefixes?: string[];
+	/**
+	 * Same-origin guard for `/_server/*` endpoints (server functions and
+	 * form actions) — enabled by default; pass `false` to disable
+	 */
+	serverFnCsrf?: ServerFnCsrfOptions | false;
+	/**
+	 * File-based API routes (`*.api.ts` in routesDir) — built with
+	 * createApiRouteHandler(manifest, routeModules); tried before the
+	 * render fallback, returns null when no api route matches
+	 */
+	fileApiHandler?: (request: Request) => Promise<Response | null>;
+	/**
+	 * Loader data endpoint — serves `/_server/loader?path=...` for
+	 * client-side navigation re-fetching of route `loader` exports
+	 */
+	loaderHandler?: (request: Request) => Promise<Response>;
+	/**
+	 * Static file handler (production asset serving) — tried after API
+	 * and framework endpoints, before the render fallback
+	 */
+	staticHandler?: (request: Request) => Promise<Response | null>;
+	/** sitemap.xml / robots.txt — null lets the render pipeline handle it */
+	seoHandler?: (request: Request) => Response | null;
+	/** `/_og` OpenGraph card endpoint */
+	ogHandler?: (request: Request) => Response | null;
+	/** `/_docs/openapi.json` generated spec endpoint */
+	docsHandler?: (request: Request) => Promise<Response | null>;
+	/** `/_island/<name>` remote island HTML endpoint */
+	islandHandler?: (request: Request) => Promise<Response | null>;
+	/** `/llms.txt` + `/_server/mcp` — AI-facing surface */
+	aiHandler?: (request: Request) => Promise<Response | null>;
+	/** `/_health` + `/_ready` probes — readiness fn may return false */
+	opsHandler?: (request: Request) => Promise<Response | null>;
+	/** Multi-zone proxy — [{prefix, target}] strips prefix and forwards */
+	zoneHandler?: (request: Request) => Promise<Response | null>;
+	/** `/_devtools` — standalone diagnostics page (dev only) */
+	devtoolsHandler?: (request: Request) => Response | null;
+	/**
+	 * Route-rules rate limit check — runs first for every request
+	 * (covers api routes and render paths); built by createAppServer
+	 * from config.routeRules via matchRouteRuleWithPattern + checkRateLimit
+	 */
+	rateLimitCheck?: (request: Request) => Response | undefined;
+}
+
+export type FrameworkFetchHandler = (request: Request) => Promise<Response>;
+
+const isApiRequest = (request: Request, prefixes: string[]): boolean => {
+	const { pathname } = new URL(request.url);
+	return prefixes.some(
+		(prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`),
+	);
+};
+
+type RequestHandler = (request: Request) => Promise<Response>;
+
+export const createFrameworkServerHandler = (
+	options: FrameworkServerOptions,
+): FrameworkFetchHandler => {
+	const serverFnHandler = createServerFnHandler({
+		csrf: options.serverFnCsrf,
+	});
+	const batchHandler = createBatchHandler();
+	const liveHandler = createLiveQueryHandler();
+	const apiPrefixes = options.apiPrefixes ?? ["/api"];
+
+	// @wrikka/web-server-toolkit is lazily imported so client bundles and runtimes
+	// without web-server installed never load it
+	let apiHandler: RequestHandler | undefined;
+	let apiHandlerReady = false;
+	const getApiHandler = async (): Promise<RequestHandler | undefined> => {
+		if (apiHandlerReady) return apiHandler;
+		if (options.routes?.length) {
+			const { createRequestHandler } = await import(
+				"@wrikka/web-server-toolkit"
+			);
+			apiHandler = createRequestHandler(options.routes);
+		}
+		apiHandlerReady = true;
+		return apiHandler;
+	};
+
+	const dispatch = async (request: Request): Promise<Response> => {
+		// Multi-zone — prefix proxy runs first (the zone owns those paths)
+		if (options.zoneHandler) {
+			const response = await options.zoneHandler(request);
+			if (response) return response;
+		}
+
+		// `/_devtools` — standalone diagnostics page
+		if (options.devtoolsHandler) {
+			const response = options.devtoolsHandler(request);
+			if (response) return response;
+		}
+
+		// Rate limiting — first gate; covers api routes, endpoints, render
+		const limited = options.rateLimitCheck?.(request);
+		if (limited) return limited;
+
+		if (isServerFnRequest(request)) {
+			return serverFnHandler(request);
+		}
+
+		if (isBatchRequest(request)) {
+			const csrf = options.serverFnCsrf;
+			if (csrf !== false && !isSameOriginRequest(request, csrf ?? {})) {
+				return new Response(
+					JSON.stringify({
+						error: {
+							code: "FORBIDDEN",
+							message: "Batch calls must be same-origin",
+						},
+					}),
+					{ status: 403, headers: { "Content-Type": "application/json" } },
+				);
+			}
+			return batchHandler(request);
+		}
+
+		if (isLiveRequest(request)) {
+			return liveHandler(request);
+		}
+
+		if (
+			options.actionHandler &&
+			new URL(request.url).pathname.startsWith("/_server/action/")
+		) {
+			const csrf = options.serverFnCsrf;
+			if (csrf !== false && !isSameOriginRequest(request, csrf ?? {})) {
+				return new Response(
+					JSON.stringify({
+						error: {
+							code: "FORBIDDEN",
+							message: "Actions must be called from the same origin",
+						},
+					}),
+					{ status: 403, headers: { "Content-Type": "application/json" } },
+				);
+			}
+			return options.actionHandler(request);
+		}
+
+		if (
+			options.loaderHandler &&
+			new URL(request.url).pathname === "/_server/loader"
+		) {
+			return options.loaderHandler(request);
+		}
+
+		if (
+			options.imageHandler &&
+			new URL(request.url).pathname === (options.imageEndpoint ?? "/_image")
+		) {
+			return options.imageHandler(request);
+		}
+
+		if (isApiRequest(request, apiPrefixes)) {
+			const handler = await getApiHandler();
+			if (handler) {
+				const response = await handler(request);
+				if (response.status !== 404) return response;
+			}
+			if (options.apiHandler) {
+				const response = await options.apiHandler(request);
+				if (response.status !== 404) return response;
+			}
+		}
+
+		// File API routes (*.api.ts) — colocated with pages in routesDir
+		if (options.fileApiHandler) {
+			const response = await options.fileApiHandler(request);
+			if (response) return response;
+		}
+
+		// Static files — production asset/public serving
+		if (options.staticHandler) {
+			const response = await options.staticHandler(request);
+			if (response) return response;
+		}
+
+		// sitemap.xml / robots.txt
+		if (options.seoHandler) {
+			const response = options.seoHandler(request);
+			if (response) return response;
+		}
+
+		// /_og OpenGraph cards + /_docs/openapi.json
+		if (options.ogHandler) {
+			const response = options.ogHandler(request);
+			if (response) return response;
+		}
+		if (options.docsHandler) {
+			const response = await options.docsHandler(request);
+			if (response) return response;
+		}
+		if (options.islandHandler) {
+			const response = await options.islandHandler(request);
+			if (response) return response;
+		}
+		if (options.aiHandler) {
+			const response = await options.aiHandler(request);
+			if (response) return response;
+		}
+		if (options.opsHandler) {
+			const response = await options.opsHandler(request);
+			if (response) return response;
+		}
+
+		return options.render(request);
+	};
+
+	// Every request runs inside an AsyncLocalStorage scope so loaders,
+	// server functions and middleware can call useRequestEvent()
+	return (request: Request): Promise<Response> =>
+		runWithRequest({ request, state: {} }, async () => {
+			const response = await dispatch(request);
+			// Echo the request-id middleware wrote (x-request-id correlation)
+			const id = useRequestEvent()?.state.requestId;
+			if (typeof id === "string" && !response.headers.has("x-request-id")) {
+				try {
+					response.headers.set("x-request-id", id);
+				} catch {
+					// immutable headers (e.g. redirects) — skip
+				}
+			}
+			return response;
+		});
+};

package/src/server/index.ts

@@ -0,0 +1,13 @@
+// Public API - @wrikka/solid-framework/server
+// NOTE: this module is isomorphic — *.fn.ts files import it from the
+// client bundle too, so nothing here may touch node builtins. Node-only
+// helpers live under dedicated subpaths (@wrikka/solid-framework/server/*)
+
+export * from "./adapters";
+export * from "./modules/http";
+export * from "./modules/loaders";
+export * from "./modules/realtime";
+export * from "./modules/server-functions";
+export * from "./modules/server-only";
+export * from "./shared";
+export * from "./types";

package/src/server/modules/http/domain/operations/cookies.ts

@@ -0,0 +1,151 @@
+/**
+ * Cookies & Sessions
+ * Web-standard helpers usable inside loaders, actions and middleware —
+ * signing uses WebCrypto HMAC so it runs on Bun/Node/Workers alike
+ */
+
+export interface CookieOptions {
+	path?: string;
+	domain?: string;
+	maxAge?: number;
+	expires?: Date;
+	httpOnly?: boolean;
+	secure?: boolean;
+	sameSite?: "strict" | "lax" | "none";
+}
+
+export const parseCookies = (request: Request): Record<string, string> => {
+	const header = request.headers.get("cookie") ?? "";
+	const out: Record<string, string> = {};
+	for (const pair of header.split(";")) {
+		const eq = pair.indexOf("=");
+		if (eq === -1) continue;
+		const key = pair.slice(0, eq).trim();
+		if (key) out[key] = decodeURIComponent(pair.slice(eq + 1).trim());
+	}
+	return out;
+};
+
+export const getCookie = (request: Request, name: string): string | undefined =>
+	parseCookies(request)[name];
+
+export const serializeCookie = (
+	name: string,
+	value: string,
+	options: CookieOptions = {},
+): string => {
+	const parts = [
+		`${name}=${encodeURIComponent(value)}`,
+		`Path=${options.path ?? "/"}`,
+	];
+	if (options.domain) parts.push(`Domain=${options.domain}`);
+	if (options.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`);
+	if (options.expires) parts.push(`Expires=${options.expires.toUTCString()}`);
+	if (options.httpOnly !== false) parts.push("HttpOnly");
+	if (options.secure !== false) parts.push("Secure");
+	parts.push(`SameSite=${options.sameSite ?? "Lax"}`);
+	return parts.join("; ");
+};
+
+export const setCookie = (
+	headers: Headers,
+	name: string,
+	value: string,
+	options: CookieOptions = {},
+): void => {
+	headers.append("Set-Cookie", serializeCookie(name, value, options));
+};
+
+export const deleteCookie = (
+	headers: Headers,
+	name: string,
+	options: Pick<CookieOptions, "path" | "domain"> = {},
+): void => {
+	setCookie(headers, name, "", { ...options, maxAge: 0 });
+};
+
+// ---- signed sessions ----
+
+const hmacKey = (secret: string): Promise<CryptoKey> =>
+	crypto.subtle.importKey(
+		"raw",
+		new TextEncoder().encode(secret),
+		{ name: "HMAC", hash: "SHA-256" },
+		false,
+		["sign", "verify"],
+	);
+
+const toB64 = (buf: ArrayBuffer): string =>
+	btoa(String.fromCharCode(...new Uint8Array(buf)))
+		.replaceAll("+", "-")
+		.replaceAll("/", "_")
+		.replaceAll("=", "");
+
+const fromB64 = (b64: string): Uint8Array =>
+	Uint8Array.from(atob(b64.replaceAll("-", "+").replaceAll("_", "/")), (c) =>
+		c.charCodeAt(0),
+	);
+
+export interface Session<T = Record<string, unknown>> {
+	/** Signed session data from the request cookie — null when absent/forged */
+	get(request: Request): Promise<T | null>;
+	/** Write the session cookie onto response headers */
+	set(headers: Headers, data: T): Promise<void>;
+	destroy(headers: Headers): void;
+}
+
+/**
+ * Signed-cookie session — data is JSON + HMAC-SHA256 signature,
+ * tamper-evident without server-side storage
+ */
+export const createSession = <T = Record<string, unknown>>(
+	secret: string,
+	options: { name?: string; cookie?: CookieOptions } = {},
+): Session<T> => {
+	const name = options.name ?? "sf_session";
+	const sign = async (payload: string): Promise<string> => {
+		const key = await hmacKey(secret);
+		const sig = await crypto.subtle.sign(
+			"HMAC",
+			key,
+			new TextEncoder().encode(payload),
+		);
+		return toB64(sig);
+	};
+
+	return {
+		async get(request) {
+			const raw = getCookie(request, name);
+			if (!raw) return null;
+			const dot = raw.lastIndexOf(".");
+			if (dot === -1) return null;
+			const payload = raw.slice(0, dot);
+			const signature = raw.slice(dot + 1);
+			const key = await hmacKey(secret);
+			const ok = await crypto.subtle.verify(
+				"HMAC",
+				key,
+				fromB64(signature).buffer as ArrayBuffer,
+				new TextEncoder().encode(payload),
+			);
+			if (!ok) return null;
+			try {
+				return JSON.parse(atob(payload)) as T;
+			} catch {
+				return null;
+			}
+		},
+		async set(headers, data) {
+			const payload = btoa(JSON.stringify(data));
+			const value = `${payload}.${await sign(payload)}`;
+			setCookie(headers, name, value, {
+				httpOnly: true,
+				sameSite: "lax",
+				...options.cookie,
+			});
+		},
+		destroy(headers) {
+			deleteCookie(headers, name, { path: options.cookie?.path });
+		},
+	};
+};

package/src/server/modules/http/domain/operations/metrics.ts

@@ -0,0 +1,103 @@
+/**
+ * Metrics — minimal Prometheus-text exporter wired to the ops surface.
+ * Counters/gauges are shared-process singletons:
+ *
+ *   metrics.counter("http_requests_total").inc();
+ *   // createAppServer({ ops: { metrics: true } }) → GET /_metrics
+ */
+
+interface Counter {
+	inc(by?: number): void;
+	value(): number;
+}
+interface Gauge extends Counter {
+	dec(by?: number): void;
+	set(v: number): void;
+}
+interface Histogram {
+	observe(ms: number): void;
+	buckets(): { le: number; count: number }[];
+}
+
+const counters = new Map<string, { v: number; labels?: string }>();
+const gauges = new Map<string, { v: number; labels?: string }>();
+const histograms = new Map<
+	string,
+	{ le: number; count: number; labels?: string }[]
+>();
+
+const HISTO_BOUNDS = [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000];
+
+export const metrics = {
+	counter: (name: string, labels?: string): Counter => ({
+		inc(by = 1) {
+			const e = counters.get(name) ?? { v: 0, labels };
+			e.v += by;
+			counters.set(name, e);
+		},
+		value: () => counters.get(name)?.v ?? 0,
+	}),
+	gauge: (name: string, labels?: string): Gauge => ({
+		inc(by = 1) {
+			const e = gauges.get(name) ?? { v: 0, labels };
+			e.v += by;
+			gauges.set(name, e);
+		},
+		dec(by = 1) {
+			this.inc(-by);
+		},
+		set(v) {
+			gauges.set(name, { v, labels });
+		},
+		value: () => gauges.get(name)?.v ?? 0,
+	}),
+	histogram: (name: string, labels?: string): Histogram => ({
+		observe(ms) {
+			const buckets =
+				histograms.get(name) ??
+				HISTO_BOUNDS.map((le) => ({ le, count: 0, labels }));
+			for (const b of buckets) if (ms <= b.le) b.count++;
+			histograms.set(name, buckets);
+		},
+		buckets: () => histograms.get(name) ?? [],
+	}),
+};
+
+/** Render the registry as Prometheus exposition text */
+export const renderMetrics = (): string => {
+	const lines: string[] = [];
+	for (const [name, e] of counters) {
+		lines.push(`# TYPE ${name} counter`, `${name} ${e.v}`);
+	}
+	for (const [name, e] of gauges) {
+		lines.push(`# TYPE ${name} gauge`, `${name} ${e.v}`);
+	}
+	for (const [name, buckets] of histograms) {
+		lines.push(`# TYPE ${name} histogram`);
+		let cumulative = 0;
+		for (const b of buckets) {
+			cumulative += b.count;
+			lines.push(`${name}_bucket{le="${b.le}"} ${cumulative}`);
+		}
+		lines.push(`${name}_bucket{le="+Inf"} ${cumulative}`);
+	}
+	return `${lines.join("\n")}\n`;
+};
+
+/** Request counter + duration histogram — wire via middleware or ops */
+export const httpMetrics = (
+	method: string,
+	path: string,
+	status: number,
+	ms: number,
+): void => {
+	metrics.counter("http_requests_total", `${method} ${status}`).inc();
+	metrics.histogram("http_request_duration_ms", path).observe(ms);
+};
+
+/** Test hook */
+export const resetMetrics = (): void => {
+	counters.clear();
+	gauges.clear();
+	histograms.clear();
+};

package/src/server/modules/http/domain/operations/request-context.ts

@@ -0,0 +1,36 @@
+/**
+ * Request-scoped Context
+ * `runWithRequest` binds the current RequestEvent to an async scope —
+ * loaders, server functions and middleware read it via
+ * `useRequestEvent()` without prop drilling:
+ *
+ *   export const loader = () => {
+ *     const { request } = useRequestEvent()!;
+ *     return { ua: request.headers.get("user-agent") };
+ *   };
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export interface RequestEvent {
+	request: Request;
+	/** Middleware-scoped state bag (auth user, db handle, …) */
+	state: Record<string, unknown>;
+}
+
+const storage = new AsyncLocalStorage<RequestEvent>();
+
+export const runWithRequest = <T>(event: RequestEvent, fn: () => T): T =>
+	storage.run(event, fn);
+
+/** Current request event — undefined outside a request scope */
+export const useRequestEvent = (): RequestEvent | undefined =>
+	storage.getStore();
+
+/** Current request — shorthand for useRequestEvent()?.request */
+export const getRequest = (): Request | undefined =>
+	storage.getStore()?.request;
+
+/** Read a value from request-scoped middleware state */
+export const useRequestState = <T = unknown>(key: string): T | undefined =>
+	storage.getStore()?.state[key] as T | undefined;