@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/app/modules/server-entry/application/usecases/routed-entry.ts

@@ -0,0 +1,194 @@
+/**
+ * Routed Server Entry
+ * Per-request render-mode resolution via routeRules — SSR, streaming,
+ * CSR shell, or cached prerender (runtime ISR equivalent)
+ */
+
+import type { RouteManifest } from "#app/modules/file-routes/domain";
+import { matchFileRoute } from "#app/modules/file-routes/domain/operations/match";
+import { runMiddleware } from "#app/modules/middleware";
+import {
+	matchRouteRuleWithPattern,
+	resolveAbVariant,
+} from "#app/modules/route-rules";
+import { checkRateLimit } from "#app/modules/route-rules/domain/operations/rate-limit";
+import { buildSecurityHeaders } from "#app/modules/route-rules/domain/operations/security";
+import type { AppMiddleware, SolidFrameworkConfig } from "#app/types";
+import type { Renderable } from "#render/types";
+import { useRequestEvent as requestEvent } from "#server/modules/http";
+import { type PrerenderCache, sharedPrerenderCache } from "./prerender-cache";
+import { createRouteRenderer } from "./route-render";
+
+export interface RoutedEntryOptions {
+	title?: string;
+	lang?: string;
+	/** Client entry script url used by csr shells — default "/src/entry-client.tsx" */
+	clientEntry?: string;
+	/**
+	 * Prerender store — defaults to the shared instance so
+	 * revalidateTag()/revalidatePath() reach served entries
+	 */
+	cache?: PrerenderCache;
+	/**
+	 * Islands-mode entry — replaces clientEntry for `mode: "islands"`
+	 * routes; should call hydrateIslands() instead of hydrating the app
+	 */
+	islandsEntry?: string;
+	/**
+	 * File routes — preloaded per request so SSR renders resolved
+	 * modules synchronously (client hydration must match component depth)
+	 */
+	fileRoutes?: {
+		manifest: RouteManifest;
+		modules: Record<string, unknown>;
+	};
+}
+
+/** middleware.ts convention files along the matched route's ancestor chain */
+const loadRouteMiddleware = async (
+	fileRoutes: { manifest: RouteManifest; modules: Record<string, unknown> },
+	pathname: string,
+): Promise<AppMiddleware[]> => {
+	const matched = matchFileRoute(pathname, fileRoutes.manifest);
+	const files = matched?.route.middleware ?? [];
+	const fns: AppMiddleware[] = [];
+	for (const file of files) {
+		const entry = fileRoutes.modules[file];
+		if (!entry) continue;
+		const mod = (await Promise.resolve(
+			typeof entry === "function" ? entry() : entry,
+		)) as {
+			default?: AppMiddleware;
+			middleware?: AppMiddleware;
+		};
+		const fn = mod.middleware ?? mod.default;
+		if (fn) fns.push(fn);
+	}
+	return fns;
+};
+
+/**
+ * Create a fetch handler that picks the render mode per request using
+ * the configured routeRules — the routeRules → render pipeline binding.
+ * Runs config.middleware first; prerender modes are ISR-cached.
+ */
+export const createRoutedServerEntry = (
+	renderable: Renderable,
+	config: SolidFrameworkConfig,
+	options: RoutedEntryOptions = {},
+): ((request: Request) => Promise<Response>) => {
+	const renderer = createRouteRenderer({
+		renderable,
+		config,
+		options,
+		prerender: options.cache ?? sharedPrerenderCache,
+	});
+	// instrumentation.ts convention — register() once at boot
+	void config.instrumentation?.register?.();
+
+	const handle = async (request: Request): Promise<Response> => {
+		const url = new URL(request.url);
+		const pathname = url.pathname;
+		const ruleMatch = matchRouteRuleWithPattern(pathname, config.rules);
+		const rule = ruleMatch?.rule;
+		const mode = rule?.mode ?? config.renderMode;
+
+		// Middleware chain — first Response short-circuits the pipeline.
+		// Reuse the request-event state bag when running inside the ALS
+		// scope so useRequestState() sees middleware writes
+		const state: Record<string, unknown> = requestEvent()?.state ?? {};
+		const early = await runMiddleware(config.middleware, {
+			request,
+			url,
+			state,
+		});
+		if (early) return early;
+
+		// Directory middleware — every middleware.ts convention file
+		// along the matched route's ancestor chain runs
+		// outermost → innermost (default or `middleware` export)
+		if (options.fileRoutes) {
+			const fns = await loadRouteMiddleware(options.fileRoutes, pathname);
+			if (fns.length) {
+				const blocked = await runMiddleware(fns, { request, url, state });
+				if (blocked) return blocked;
+			}
+		}
+
+		// Per-route middleware — rule.middleware runs only when the rule
+		// matched this pathname (route-level guards, e.g. "/admin/**")
+		if (rule?.middleware?.length) {
+			const scoped = await runMiddleware(rule.middleware, {
+				request,
+				url,
+				state,
+			});
+			if (scoped) return scoped;
+		}
+
+		// Rate limiting — fixed-window bucket keyed by pattern + client
+		if (ruleMatch) {
+			const limited = checkRateLimit(
+				ruleMatch.rule,
+				ruleMatch.pattern,
+				request,
+			);
+			if (limited) return limited;
+		}
+
+		// A/B split — sticky `__ab_*` cookie buckets clients; bucket "b"
+		// renders the variant route at the same URL (no redirect)
+		const ab = ruleMatch
+			? resolveAbVariant(rule, ruleMatch.pattern, request, pathname)
+			: { request, pathname, applyCookie: (res: Response) => res };
+
+		// Security headers + CSP nonce — nonce is generated before the
+		// render so the hydration script carries it
+		const security = buildSecurityHeaders(rule?.security);
+		if (security.nonce) state.cspNonce = security.nonce;
+
+		return ab.applyCookie(
+			await renderer.serve({
+				request: ab.request,
+				pathname: ab.pathname,
+				state,
+				rule,
+				mode,
+				security,
+			}),
+		);
+	};
+
+	// instrumentation.ts onRequest/onError — span around every response
+	const onRequest = config.instrumentation?.onRequest;
+	const onError = config.instrumentation?.onError;
+	if (!onRequest && !onError) return handle;
+	return async (request: Request): Promise<Response> => {
+		const t0 = performance.now();
+		const path = new URL(request.url).pathname;
+		try {
+			const response = await handle(request);
+			try {
+				onRequest?.({
+					method: request.method,
+					path,
+					status: response.status,
+					ms: performance.now() - t0,
+				});
+			} catch {
+				// observability hooks must never break the request
+			}
+			return response;
+		} catch (error) {
+			try {
+				onError?.({ method: request.method, path, error });
+			} catch {
+				// ignore hook errors
+			}
+			return Response.json(
+				{ error: { code: "INTERNAL", message: "Internal Server Error" } },
+				{ status: 500 },
+			);
+		}
+	};
+};

package/src/app/modules/server-entry/application/usecases/static-handler.ts

@@ -0,0 +1,20 @@
+/**
+ * Static Handler (lazy)
+ * Lazy-import wrapper — node:path must never enter the client bundle
+ * graph (app/index is isomorphic)
+ */
+
+export const lazyStaticHandler = (opts: {
+	dirs: string[];
+	immutablePrefix?: string;
+}): ((request: Request) => Promise<Response | null>) => {
+	let inner:
+		| Promise<(request: Request) => Promise<Response | null>>
+		| undefined;
+	return async (request) => {
+		inner ??= import("#app/modules/static").then((m) =>
+			m.createStaticHandler(opts),
+		);
+		return (await inner)(request);
+	};
+};

package/src/app/modules/server-entry/application/usecases/zone-handler.ts

@@ -0,0 +1,37 @@
+/**
+ * Zone Handler
+ * Multi-zone prefix proxy (config.zones) — requests under a zone's
+ * `prefix` are rewritten and forwarded to its `target` origin
+ */
+
+export interface ZoneConfig {
+	prefix: string;
+	target: string;
+}
+
+export const createZoneHandler = (
+	zones: ZoneConfig[],
+): ((request: Request) => Promise<Response | null>) => {
+	return async (request) => {
+		const { pathname } = new URL(request.url);
+		const zone = zones.find(
+			(z) => pathname === z.prefix || pathname.startsWith(`${z.prefix}/`),
+		);
+		if (!zone) return null;
+		const url = new URL(request.url);
+		url.pathname = pathname.slice(zone.prefix.length) || "/";
+		const target = new URL(url.pathname + url.search, zone.target);
+		return fetch(
+			new Request(target, {
+				method: request.method,
+				headers: request.headers,
+				body:
+					request.method === "GET" || request.method === "HEAD"
+						? undefined
+						: request.body,
+				// duplex required for streaming bodies in undici
+				...({ duplex: "half" } as object),
+			}),
+		);
+	};
+};

package/src/app/modules/server-entry/index.ts

@@ -0,0 +1 @@
+export * from "./application";

package/src/app/modules/session/index.ts

@@ -0,0 +1,77 @@
+/**
+ * Sessions — cookie-id + server-side store
+ *
+ *   const s = session(request);
+ *   s.get("user"); s.set("cart", [...]); s.destroy();
+ *   // respond with `s.setCookie` as Set-Cookie on first use
+ */
+
+export interface Session {
+	id: string;
+	get: <T>(key: string) => T | undefined;
+	set: (key: string, value: unknown) => void;
+	delete: (key: string) => void;
+	/** Rotate the session id (post-login) */
+	regenerate: () => void;
+	/** Drop the whole session */
+	destroy: () => void;
+	/** Set-Cookie header value for the session id (empty when existing) */
+	setCookie: string;
+}
+
+const COOKIE = "sf_sess";
+const store = new Map<string, Map<string, unknown>>();
+
+const parseCookies = (request: Request): Record<string, string> =>
+	Object.fromEntries(
+		(request.headers.get("cookie") ?? "")
+			.split(";")
+			.map((c) => c.trim().split("="))
+			.filter(([k]) => k),
+	);
+
+const newId = (): string =>
+	`${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+
+export const session = (
+	request: Request,
+	options: { cookie?: string; maxAge?: number } = {},
+): Session => {
+	const name = options.cookie ?? COOKIE;
+	let id = parseCookies(request)[name];
+	let setCookie = "";
+	if (!id || !store.has(id)) {
+		id = newId();
+		store.set(id, new Map());
+		setCookie = `${name}=${id}; Path=/; HttpOnly; SameSite=Lax${
+			options.maxAge ? `; Max-Age=${options.maxAge}` : ""
+		}`;
+	}
+	return {
+		get id() {
+			return id;
+		},
+		get: (key) => store.get(id)?.get(key) as never,
+		set: (key, value) => {
+			store.get(id)?.set(key, value);
+		},
+		delete: (key) => {
+			store.get(id)?.delete(key);
+		},
+		regenerate: () => {
+			const next = newId();
+			store.set(next, store.get(id) ?? new Map());
+			store.delete(id);
+			id = next;
+		},
+		destroy: () => {
+			store.delete(id);
+		},
+		get setCookie() {
+			return setCookie;
+		},
+	};
+};
+
+/** Test hook — drop all sessions */
+export const clearSessions = (): void => store.clear();

package/src/app/modules/static/domain/operations/serve.ts

@@ -0,0 +1,88 @@
+/**
+ * Static File Serving
+ * Serves built client assets and public/ files in production —
+ * `solid start` works without a CDN in front. Directories are tried
+ * in order; hashed build assets get immutable cache headers
+ */
+
+import { join, normalize, resolve, sep } from "node:path";
+
+export interface StaticFilesConfig {
+	/** Directories tried in order — e.g. ["dist", "public"] */
+	dirs: string[];
+	/** Path prefix that gets immutable caching — default "/assets/" */
+	immutablePrefix?: string;
+}
+
+const MIME: Record<string, string> = {
+	html: "text/html; charset=utf-8",
+	js: "text/javascript; charset=utf-8",
+	mjs: "text/javascript; charset=utf-8",
+	css: "text/css; charset=utf-8",
+	json: "application/json",
+	map: "application/json",
+	svg: "image/svg+xml",
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	gif: "image/gif",
+	webp: "image/webp",
+	avif: "image/avif",
+	ico: "image/x-icon",
+	woff: "font/woff",
+	woff2: "font/woff2",
+	ttf: "font/ttf",
+	txt: "text/plain; charset=utf-8",
+	xml: "application/xml",
+	pdf: "application/pdf",
+	wasm: "application/wasm",
+};
+
+const mimeOf = (path: string): string =>
+	MIME[path.split(".").pop()?.toLowerCase() ?? ""] ??
+	"application/octet-stream";
+
+/** Resolve pathname inside dir — null when it escapes (traversal) */
+const safeJoin = (dir: string, pathname: string): string | null => {
+	const root = resolve(dir);
+	const target = normalize(join(root, decodeURIComponent(pathname)));
+	return target.startsWith(root + sep) || target === root ? target : null;
+};
+
+/**
+ * Returns a handler serving static files — null when nothing matches
+ * so the caller can fall through to SSR
+ */
+export const createStaticHandler = (
+	config: StaticFilesConfig,
+): ((request: Request) => Promise<Response | null>) => {
+	const dirs = config.dirs.map((d) => resolve(d));
+	const immutable = config.immutablePrefix ?? "/assets/";
+
+	return async (request: Request): Promise<Response | null> => {
+		if (request.method !== "GET" && request.method !== "HEAD") return null;
+		const { pathname } = new URL(request.url);
+		if (pathname === "/" || pathname.endsWith("/")) return null;
+		if (pathname.includes("..")) return null;
+
+		const { readFile } = await import("node:fs/promises");
+		for (const dir of dirs) {
+			const file = safeJoin(dir, pathname);
+			if (!file) continue;
+			try {
+				const content = await readFile(file);
+				const headers: Record<string, string> = {
+					"Content-Type": mimeOf(file),
+				};
+				headers["Cache-Control"] = pathname.startsWith(immutable)
+					? "public, max-age=31536000, immutable"
+					: "public, max-age=3600";
+				return new Response(
+					request.method === "HEAD" ? null : (content as unknown as BodyInit),
+					{ headers },
+				);
+			} catch {}
+		}
+		return null;
+	};
+};

package/src/app/modules/static/index.ts

@@ -0,0 +1 @@
+export * from "./domain/operations/serve";

package/src/app/presentation/App.tsx

@@ -0,0 +1,34 @@
+/**
+ * App Component
+ * Framework root — wires head management and suspense around the app tree
+ */
+
+import type { JSX } from "solid-js";
+import { Suspense } from "solid-js";
+import {
+	createRuntimeConfig,
+	type RuntimeConfig,
+} from "#app/modules/runtime-config";
+import type { SolidFrameworkConfig } from "#app/types";
+import type { HeadSink } from "#head/modules/head/ports";
+import { HeadProvider } from "#head/presentation/HeadProvider";
+
+export interface AppProps {
+	config?: Partial<SolidFrameworkConfig>;
+	runtimeConfig?: RuntimeConfig;
+	headSink?: HeadSink;
+	children?: JSX.Element;
+}
+
+export const App = (props: AppProps): JSX.Element => {
+	createRuntimeConfig(
+		props.config?.publicEnvPrefixes ?? ["PUBLIC_"],
+		props.runtimeConfig,
+	);
+
+	return (
+		<HeadProvider sink={props.headSink}>
+			<Suspense>{props.children}</Suspense>
+		</HeadProvider>
+	);
+};

package/src/app/presentation/define-config.ts

@@ -0,0 +1,11 @@
+/**
+ * defineConfig
+ * Identity helper for solid.config.ts with full typing
+ */
+
+import { resolveConfig } from "#app/modules/config";
+import type { SolidFrameworkConfig } from "#app/types";
+
+export const defineConfig = (
+	config: Partial<SolidFrameworkConfig>,
+): SolidFrameworkConfig => resolveConfig(config);

package/src/app/presentation/index.ts

@@ -0,0 +1,3 @@
+export * from "./App";
+export * from "./define-config";
+export * from "./providers";

package/src/app/presentation/providers.ts

@@ -0,0 +1,80 @@
+/**
+ * App Providers
+ * The provider stack wrapped around the app renderable — MUST be
+ * identical on server and client so hydration keys (data-hk depth)
+ * line up: Head → Request → RouteStatus → Hydration → app
+ */
+
+import { createComponent } from "solid-js";
+import { isServer } from "solid-js/web";
+import { HydrationContext } from "#app/modules/file-routes/presentation/loader-data";
+import {
+	RequestContext,
+	RouteStateContext,
+} from "#app/modules/file-routes/presentation/location";
+import {
+	type RouteStatus,
+	RouteStatusContext,
+} from "#app/modules/file-routes/presentation/status";
+import {
+	createDomHeadSink,
+	createHeadManager,
+} from "#head/modules/head/application/usecases";
+import type { HeadSink } from "#head/modules/head/ports";
+import { HeadContext } from "#head/presentation/head-context";
+import { readHydrationPayload } from "#render/modules/render/domain";
+import type { HydrationPayload, Renderable } from "#render/types";
+
+export interface AppProvidersOptions {
+	head?: HeadSink;
+	request?: Request;
+	status?: RouteStatus;
+	hydration?: HydrationPayload;
+	/** Middleware-written request state — exposed via useRouteState */
+	state?: Record<string, unknown>;
+}
+
+/**
+ * Wrap the app in the framework provider stack — call sites:
+ *   server (routed-entry): live Request, head manager, status, payload
+ *   client (entry-client): synthesized Request, DOM head sink, payload
+ */
+export const wrapAppProviders = (
+	renderable: Renderable,
+	options: AppProvidersOptions = {},
+): Renderable => {
+	const head =
+		options.head ?? (isServer ? createHeadManager() : createDomHeadSink());
+	const status = options.status ?? { status: 200 };
+	// Client: middleware state arrives via the hydration payload so
+	// useRouteState() reads the same values after hydration
+	const state =
+		options.state ?? (isServer ? {} : (readHydrationPayload().stores ?? {}));
+	return () =>
+		createComponent(HeadContext.Provider, {
+			value: head,
+			get children() {
+				return createComponent(RequestContext.Provider, {
+					value: options.request,
+					get children() {
+						return createComponent(RouteStatusContext.Provider, {
+							value: status,
+							get children() {
+								return createComponent(RouteStateContext.Provider, {
+									value: state,
+									get children() {
+										return createComponent(HydrationContext.Provider, {
+											value: options.hydration,
+											get children() {
+												return renderable();
+											},
+										});
+									},
+								});
+							},
+						});
+					},
+				});
+			},
+		});
+};