@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/app/modules/i18n/domain/operations/locale.ts

@@ -0,0 +1,39 @@
+/**
+ * i18n Routing
+ * Locale-prefixed paths — `/en/about` matches `/about` routes while
+ * the locale is exposed via useLocale(). Strategy:
+ *   "prefix"               → every locale is prefixed
+ *   "prefix_except_default"→ default locale stays unprefixed
+ */
+
+export interface I18nConfig {
+	locales: string[];
+	defaultLocale: string;
+	strategy?: "prefix" | "prefix_except_default";
+}
+
+/** Strip the locale prefix — returns [locale, pathWithoutPrefix] */
+export const stripLocale = (
+	pathname: string,
+	config: I18nConfig,
+): { locale: string; path: string } => {
+	const seg = pathname.split("/")[1];
+	if (seg && config.locales.includes(seg)) {
+		const rest = pathname.slice(seg.length + 1) || "/";
+		return { locale: seg, path: rest };
+	}
+	return { locale: config.defaultLocale, path: pathname };
+};
+
+/** Build a localized path for the given locale */
+export const localizedPath = (
+	path: string,
+	locale: string,
+	config: I18nConfig,
+): string => {
+	const unprefixed = stripLocale(path, config).path;
+	const skip = config.strategy !== "prefix" && locale === config.defaultLocale;
+	return skip
+		? unprefixed
+		: `/${locale}${unprefixed === "/" ? "" : unprefixed}`;
+};

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

@@ -0,0 +1,3 @@
+export * from "./domain/operations/i18n-middleware";
+export * from "./domain/operations/locale";
+export * from "./presentation/use-locale";

package/src/app/modules/i18n/presentation/use-locale.ts

@@ -0,0 +1,16 @@
+/**
+ * useLocale — current locale resolved by <FileRoutes> when
+ * config.i18n is set (LocaleContext defaults to config.defaultLocale)
+ */
+
+import { createContext, useContext } from "solid-js";
+
+export const LocaleContext = createContext<string>();
+
+export const useLocale = (): string => {
+	const locale = useContext(LocaleContext);
+	if (!locale) {
+		throw new Error("[solid-framework] useLocale requires config.i18n");
+	}
+	return locale;
+};

package/src/app/modules/middleware/domain/operations/request-id.ts

@@ -0,0 +1,33 @@
+/**
+ * Request ID + Request Logging
+ * `requestId()` honors an inbound `x-request-id` or mints a UUID into
+ * state.requestId — the adapter echoes it on the response; logs,
+ * loaders and error reports correlate by id. `logRequest()` emits a
+ * one-line method/path/id log per request:
+ *
+ *   middleware: [requestId(), logRequest()]
+ */
+
+import type { AppMiddleware } from "#app/types";
+
+export const REQUEST_ID_STATE = "requestId";
+export const REQUEST_ID_HEADER = "x-request-id";
+
+export const requestId = (header = REQUEST_ID_HEADER): AppMiddleware => {
+	return async (ctx) => {
+		ctx.state[REQUEST_ID_STATE] =
+			ctx.request.headers.get(header) ?? crypto.randomUUID();
+		return undefined;
+	};
+};
+
+export const logRequest = (
+	log: (line: string) => void = console.log,
+): AppMiddleware => {
+	return async (ctx) => {
+		const { pathname } = new URL(ctx.request.url);
+		const id = ctx.state[REQUEST_ID_STATE];
+		log(`${ctx.request.method} ${pathname}${id ? ` id=${String(id)}` : ""}`);
+		return undefined;
+	};
+};

package/src/app/modules/middleware/domain/operations/run.ts

@@ -0,0 +1,29 @@
+/**
+ * Middleware Chain
+ * Runs AppMiddleware list in order — first Response wins
+ * (redirect/auth deny); state bag flows into the render context
+ */
+
+import type { AppMiddleware, MiddlewareContext } from "#app/types";
+
+export const runMiddleware = async (
+	middleware: AppMiddleware[] | undefined,
+	ctx: MiddlewareContext,
+): Promise<Response | undefined> => {
+	// `order` field sorts execution — stable for equal order
+	const sorted = [...(middleware ?? [])].sort(
+		(a, b) => (a.order ?? 0) - (b.order ?? 0),
+	);
+	for (const fn of sorted) {
+		const response = await fn(ctx);
+		if (response instanceof Response) return response;
+	}
+	return undefined;
+};
+
+/** Redirect helper for middleware authors */
+export const redirect = (to: string, status = 302): Response =>
+	new Response(null, {
+		status,
+		headers: { Location: to },
+	});

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

@@ -0,0 +1,7 @@
+export {
+	logRequest,
+	REQUEST_ID_HEADER,
+	REQUEST_ID_STATE,
+	requestId,
+} from "./domain/operations/request-id";
+export { redirect, runMiddleware } from "./domain/operations/run";

package/src/app/modules/route-rules/domain/index.ts

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

package/src/app/modules/route-rules/domain/operations/ab-variant.ts

@@ -0,0 +1,58 @@
+/**
+ * A/B Variant Resolution
+ * `routeRules: { "/path": { variant: { route, weight } } }` — sticky
+ * `__ab_<pattern>` cookie buckets clients into "a"/"b"; bucket "b"
+ * rewrites the request to the variant route at the same URL
+ */
+
+import type { RouteRule } from "#app/types";
+
+export interface AbVariantResolution {
+	/** Original request, or rewritten to the variant route (bucket "b") */
+	request: Request;
+	/** Pathname to render — variant route when bucketed "b" */
+	pathname: string;
+	/** Append the sticky bucket cookie to a render-path response */
+	applyCookie: (res: Response) => Response;
+}
+
+export const resolveAbVariant = (
+	rule: RouteRule | undefined,
+	pattern: string,
+	request: Request,
+	pathname: string,
+): AbVariantResolution => {
+	let routedRequest = request;
+	let routePathname = pathname;
+	let abCookie: string | undefined;
+	if (rule?.variant) {
+		const key = `__ab_${pattern.replace(/[^a-z0-9]+/gi, "_")}`;
+		const seen = request.headers
+			.get("cookie")
+			?.match(new RegExp(`(?:^|;\\s*)${key}=(a|b)`))?.[1];
+		const bucket = seen ?? (Math.random() < rule.variant.weight ? "b" : "a");
+		if (!seen) {
+			abCookie = `${key}=${bucket}; Path=/; HttpOnly; SameSite=Lax; Max-Age=31536000`;
+		}
+		if (bucket === "b") {
+			routePathname = rule.variant.route;
+			const u = new URL(request.url);
+			u.pathname = routePathname;
+			routedRequest = new Request(u, request);
+		}
+	}
+	return {
+		request: routedRequest,
+		pathname: routePathname,
+		applyCookie: (res) => {
+			if (abCookie) {
+				try {
+					res.headers.append("Set-Cookie", abCookie);
+				} catch {
+					// immutable headers — skip
+				}
+			}
+			return res;
+		},
+	};
+};

package/src/app/modules/route-rules/domain/operations/index.ts

@@ -0,0 +1,4 @@
+export * from "./ab-variant";
+export * from "./match";
+export * from "./rate-limit";
+export * from "./security";

package/src/app/modules/route-rules/domain/operations/match.ts

@@ -0,0 +1,51 @@
+/**
+ * Route Rules Matcher
+ * Pattern matching for per-route rendering rules — `*` one segment, `**` any depth
+ */
+
+import type { RouteRule, RouteRules } from "#app/types";
+
+const DEEP = "__WILDCARD_DEEP__";
+
+const patternToRegex = (pattern: string): RegExp => {
+	const escaped = pattern
+		.replace(/[.+^${}()|[\]\\]/g, "\\$&")
+		.replace(/\*\*/g, DEEP)
+		.replace(/\*/g, "[^/]*")
+		.replace(/__WILDCARD_DEEP__/g, ".*");
+	return new RegExp(`^${escaped}$`);
+};
+
+/**
+ * Most specific match wins (longest pattern); earlier keys break ties
+ */
+export const matchRouteRule = (
+	path: string,
+	rules: RouteRules,
+): RouteRule | undefined => {
+	let best: { pattern: string; rule: RouteRule } | undefined;
+
+	for (const [pattern, rule] of Object.entries(rules)) {
+		if (!patternToRegex(pattern).test(path)) continue;
+		if (!best || pattern.length > best.pattern.length) {
+			best = { pattern, rule };
+		}
+	}
+
+	return best?.rule;
+};
+
+/** Match + pattern — rate limiting keys buckets by the pattern */
+export const matchRouteRuleWithPattern = (
+	path: string,
+	rules: RouteRules,
+): { pattern: string; rule: RouteRule } | undefined => {
+	let best: { pattern: string; rule: RouteRule } | undefined;
+	for (const [pattern, rule] of Object.entries(rules)) {
+		if (!patternToRegex(pattern).test(path)) continue;
+		if (!best || pattern.length > best.pattern.length) {
+			best = { pattern, rule };
+		}
+	}
+	return best;
+};

package/src/app/modules/route-rules/domain/operations/rate-limit.ts

@@ -0,0 +1,63 @@
+/**
+ * Rate Limiting
+ * Per-route-rule token buckets — `routeRules: { "/api/**": { rateLimit:
+ * { rpm: 60 } } }` throttles matching requests with a fixed-window
+ * counter; keys default to client ip + rule pattern so buckets never
+ * mix across rules. Exceeding the limit returns 429 + Retry-After
+ */
+
+import type { RouteRule } from "#app/types";
+
+interface Bucket {
+	count: number;
+	resetAt: number;
+}
+
+const buckets = new Map<string, Bucket>();
+
+const clientKey = (request: Request, ruleKey: string): string => {
+	const ip =
+		request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ??
+		request.headers.get("x-real-ip") ??
+		"anon";
+	return `${ruleKey}:${ip}`;
+};
+
+/**
+ * Check the rule's rate limit for this request — returns a 429
+ * Response when exceeded, undefined otherwise
+ */
+export const checkRateLimit = (
+	rule: RouteRule,
+	ruleKey: string,
+	request: Request,
+): Response | undefined => {
+	const limit = rule.rateLimit;
+	if (!limit) return undefined;
+	const rpm = limit.rpm ?? 60;
+	const key = limit.key ? limit.key({ request }) : clientKey(request, ruleKey);
+	const now = Date.now();
+	const window = limit.window ?? 60_000;
+	let bucket = buckets.get(key);
+	if (!bucket || now >= bucket.resetAt) {
+		bucket = { count: 0, resetAt: now + window };
+		buckets.set(key, bucket);
+	}
+	bucket.count += 1;
+	if (bucket.count <= rpm) return undefined;
+	const retry = Math.ceil((bucket.resetAt - now) / 1000);
+	return Response.json(
+		{ error: { code: "RATE_LIMITED", message: "Too many requests" } },
+		{
+			status: 429,
+			headers: {
+				"Retry-After": String(retry),
+				"X-RateLimit-Limit": String(rpm),
+				"X-RateLimit-Remaining": "0",
+			},
+		},
+	);
+};
+
+/** Test/hot-reload helper — clears every bucket */
+export const resetRateLimits = (): void => buckets.clear();

package/src/app/modules/route-rules/domain/operations/security.ts

@@ -0,0 +1,67 @@
+/**
+ * Security Headers
+ * Route-rule-driven security header set — `security: true` applies
+ * the safe defaults; `security.csp` adds a nonce-scoped
+ * Content-Security-Policy
+ */
+
+import type { SecurityHeaders } from "#app/types";
+
+// WebCrypto — works on both server and client runtimes (no node:crypto)
+export const generateNonce = (): string => {
+	const bytes = new Uint8Array(16);
+	globalThis.crypto.getRandomValues(bytes);
+	return btoa(String.fromCharCode(...bytes));
+};
+
+const renderCsp = (
+	csp: string | Record<string, string[]>,
+	nonce: string,
+): string => {
+	const directives =
+		typeof csp === "string"
+			? csp
+			: Object.entries(csp)
+					.map(([k, v]) => `${k} ${v.join(" ")}`)
+					.join("; ");
+	return directives.replaceAll("{nonce}", `'nonce-${nonce}'`);
+};
+
+const DEFAULT_CSP: Record<string, string[]> = {
+	"default-src": ["'self'"],
+	"script-src": ["'self'", "{nonce}"],
+	"style-src": ["'self'", "'unsafe-inline'"],
+	"img-src": ["'self'", "data:", "blob:"],
+	"font-src": ["'self'", "data:"],
+	"connect-src": ["'self'"],
+	"frame-ancestors": ["'none'"],
+};
+
+/**
+ * Build the header map for a route rule — returns the headers and the
+ * CSP nonce (when a csp is configured) so the render pass can mark
+ * inline scripts
+ */
+export const buildSecurityHeaders = (
+	security: SecurityHeaders | boolean | undefined,
+): { headers: Record<string, string>; nonce?: string } => {
+	if (!security) return { headers: {} };
+	const opts: SecurityHeaders = security === true ? {} : security;
+	const headers: Record<string, string> = {};
+	let nonce: string | undefined;
+
+	if (opts.csp) {
+		nonce = generateNonce();
+		headers["Content-Security-Policy"] = renderCsp(opts.csp, nonce);
+	}
+	if (opts.noSniff !== false) headers["X-Content-Type-Options"] = "nosniff";
+	headers["X-Frame-Options"] = opts.frameOptions ?? "DENY";
+	headers["Referrer-Policy"] =
+		opts.referrerPolicy ?? "strict-origin-when-cross-origin";
+	headers["Strict-Transport-Security"] =
+		opts.hsts ?? "max-age=31536000; includeSubDomains";
+
+	return { headers, nonce };
+};
+
+export { DEFAULT_CSP };

package/src/app/modules/route-rules/index.ts

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

package/src/app/modules/runtime-config/application/index.ts

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

package/src/app/modules/runtime-config/application/usecases/index.ts

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

package/src/app/modules/runtime-config/application/usecases/runtime-config.ts

@@ -0,0 +1,42 @@
+/**
+ * Runtime Config
+ * App-level env/config access — the useRuntimeConfig equivalent.
+ * Server sees all env vars; client sees only public-prefixed vars.
+ */
+
+import { isServer } from "solid-js/web";
+
+export type RuntimeConfig = Record<string, string | undefined>;
+
+let active: RuntimeConfig = {};
+
+const readEnv = (prefixes: string[]): RuntimeConfig => {
+	const source: Record<string, string | undefined> =
+		typeof process !== "undefined"
+			? (process.env as Record<string, string | undefined>)
+			: ((import.meta as { env?: Record<string, string | undefined> }).env ??
+				{});
+
+	if (isServer) return source;
+
+	const publicConfig: RuntimeConfig = {};
+	for (const [key, value] of Object.entries(source)) {
+		if (prefixes.some((prefix) => key.startsWith(prefix))) {
+			publicConfig[key] = value;
+		}
+	}
+	return publicConfig;
+};
+
+export const createRuntimeConfig = (
+	publicEnvPrefixes: string[] = ["PUBLIC_"],
+	overrides: RuntimeConfig = {},
+): RuntimeConfig => {
+	active = { ...readEnv(publicEnvPrefixes), ...overrides };
+	return active;
+};
+
+/**
+ * Read the active runtime config — server returns all env, client only public
+ */
+export const useRuntimeConfig = (): RuntimeConfig => active;

package/src/app/modules/runtime-config/index.ts

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

package/src/app/modules/seo/domain/operations/og.ts

@@ -0,0 +1,66 @@
+/**
+ * OG Image Endpoint
+ * `/_og?title=...&subtitle=...` renders an OpenGraph card as SVG —
+ * portable across runtimes with zero native deps. For PNG output
+ * front the endpoint with resvg/sharp or a screenshot service
+ */
+
+export const OG_ENDPOINT = "/_og";
+
+export interface OgParams {
+	title?: string;
+	subtitle?: string;
+	site?: string;
+	/** "dark" (default) or "light" */
+	theme?: "dark" | "light";
+}
+
+const esc = (s: string) =>
+	s
+		.replaceAll("&", "&")
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;")
+		.replaceAll('"', "&quot;");
+
+export const renderOgSvg = (params: OgParams): string => {
+	const dark = params.theme !== "light";
+	const bg = dark ? "#0f172a" : "#f8fafc";
+	const fg = dark ? "#f1f5f9" : "#0f172a";
+	const muted = dark ? "#94a3b8" : "#475569";
+	const accent = "#38bdf8";
+	return [
+		`<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630">`,
+		`<rect width="1200" height="630" fill="${bg}"/>`,
+		`<rect x="0" y="0" width="1200" height="8" fill="${accent}"/>`,
+		params.site
+			? `<text x="80" y="120" font-family="system-ui,sans-serif" font-size="32" fill="${accent}">${esc(params.site)}</text>`
+			: "",
+		`<text x="80" y="330" font-family="system-ui,sans-serif" font-size="64" font-weight="700" fill="${fg}">${esc(params.title ?? "")}</text>`,
+		params.subtitle
+			? `<text x="80" y="420" font-family="system-ui,sans-serif" font-size="36" fill="${muted}">${esc(params.subtitle)}</text>`
+			: "",
+		`</svg>`,
+	].join("");
+};
+
+export const createOgHandler = (
+	defaults: OgParams = {},
+): ((request: Request) => Response | null) => {
+	return (request: Request): Response | null => {
+		const url = new URL(request.url);
+		if (url.pathname !== OG_ENDPOINT) return null;
+		const svg = renderOgSvg({
+			...defaults,
+			title: url.searchParams.get("title") ?? defaults.title,
+			subtitle: url.searchParams.get("subtitle") ?? defaults.subtitle,
+			theme:
+				(url.searchParams.get("theme") as OgParams["theme"]) ?? defaults.theme,
+		});
+		return new Response(svg, {
+			headers: {
+				"Content-Type": "image/svg+xml",
+				"Cache-Control": "public, max-age=3600",
+			},
+		});
+	};
+};

package/src/app/modules/seo/domain/operations/site.ts

@@ -0,0 +1,106 @@
+/**
+ * Sitemap & Robots
+ * Generate /sitemap.xml and /robots.txt from the route manifest —
+ * param routes need generateStaticParams expansion or are skipped
+ * (Nuxt sitemap / Next metadata routes equivalent)
+ */
+
+import type { RouteManifest } from "#app/modules/file-routes/domain/models";
+import { matchRouteRule } from "#app/modules/route-rules";
+import type { RouteRules } from "#app/types";
+
+export interface SitemapEntry {
+	path: string;
+	lastmod?: string;
+	changefreq?: string;
+	priority?: number;
+}
+
+const xmlEscape = (s: string) =>
+	s
+		.replaceAll("&", "&")
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;")
+		.replaceAll('"', "&quot;");
+
+export const sitemapPaths = (manifest: RouteManifest): string[] =>
+	manifest
+		.filter((r) => r.kind !== "api")
+		.map((r) => r.path)
+		.filter((p) => !p.includes(":") && !p.includes("*"))
+		.sort();
+
+export const generateSitemapXml = (
+	origin: string,
+	entries: (string | SitemapEntry)[],
+): string => {
+	const urls = entries
+		.map((e) => {
+			const entry = typeof e === "string" ? { path: e } : e;
+			const extra = [
+				entry.lastmod ? `<lastmod>${entry.lastmod}</lastmod>` : "",
+				entry.changefreq ? `<changefreq>${entry.changefreq}</changefreq>` : "",
+				entry.priority !== undefined
+					? `<priority>${entry.priority}</priority>`
+					: "",
+			].join("");
+			return `<url><loc>${xmlEscape(origin)}${xmlEscape(entry.path)}</loc>${extra}</url>`;
+		})
+		.join("");
+	return `<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${urls}</urlset>`;
+};
+
+export interface RobotsConfig {
+	/** Disallow paths — default ["/api", "/_server"] */
+	disallow?: string[];
+	/** Additional sitemap URLs */
+	sitemaps?: string[];
+	/** Block all crawlers */
+	disallowAll?: boolean;
+}
+
+export const generateRobotsTxt = (
+	origin: string,
+	config: RobotsConfig = {},
+): string => {
+	const lines = ["User-agent: *"];
+	if (config.disallowAll) {
+		lines.push("Disallow: /");
+	} else {
+		for (const path of config.disallow ?? ["/api", "/_server"]) {
+			lines.push(`Disallow: ${path}`);
+		}
+	}
+	for (const sitemap of config.sitemaps ?? [`${origin}/sitemap.xml`]) {
+		lines.push("", `Sitemap: ${sitemap}`);
+	}
+	return lines.join("\n");
+};
+
+/** Combined handler — /sitemap.xml + /robots.txt, null otherwise */
+export const createSeoHandler = (
+	manifest: RouteManifest,
+	options: { origin?: string; robots?: RobotsConfig } = {},
+	rules?: RouteRules,
+): ((request: Request) => Response | null) => {
+	return (request: Request): Response | null => {
+		const { pathname, origin } = new URL(request.url);
+		const base = options.origin ?? origin;
+		if (pathname === "/sitemap.xml") {
+			// routeRules.*.sitemap merges priority/changefreq/lastmod
+			const entries = sitemapPaths(manifest).map((path) => {
+				const rule = rules ? matchRouteRule(path, rules) : undefined;
+				return rule?.sitemap ? { path, ...rule.sitemap } : path;
+			});
+			return new Response(generateSitemapXml(base, entries), {
+				headers: { "Content-Type": "application/xml" },
+			});
+		}
+		if (pathname === "/robots.txt") {
+			return new Response(generateRobotsTxt(base, options.robots), {
+				headers: { "Content-Type": "text/plain" },
+			});
+		}
+		return null;
+	};
+};

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

@@ -0,0 +1,2 @@
+export * from "./domain/operations/og";
+export * from "./domain/operations/site";

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

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