@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/server/modules/http/domain/operations/session-store.ts

@@ -0,0 +1,98 @@
+/**
+ * Server-side Session Stores — the cookie carries only an opaque
+ * session id; data lives in a backend. Same `Session<T>` interface
+ * as the signed-cookie store so `createAuth` accepts either:
+ *
+ *   createAuth({ secret, store: kvSessionStore(env.KV) })
+ *   createAuth({ secret, store: memorySessionStore() })  // dev
+ */
+
+import type { CookieOptions, Session } from "./cookies";
+import { deleteCookie, getCookie, setCookie } from "./cookies";
+
+/** Minimal KV contract — works with edge KV, Redis clients, Map */
+export interface SessionBackend {
+	get(key: string): Promise<string | null>;
+	set(key: string, value: string, ttlSeconds?: number): Promise<unknown>;
+	delete(key: string): Promise<unknown>;
+}
+
+const newId = (): string =>
+	`${crypto.randomUUID()}.${crypto.randomUUID().slice(0, 8)}`;
+
+/** Wrap any backend in the Session<T> interface */
+export const serverSessionStore = <T = Record<string, unknown>>(
+	backend: SessionBackend,
+	options: {
+		name?: string;
+		cookie?: CookieOptions;
+		/** Session TTL in seconds — default 7 days */
+		ttl?: number;
+	} = {},
+): Session<T> => {
+	const name = options.name ?? "sf_session";
+	const ttl = options.ttl ?? 60 * 60 * 24 * 7;
+	return {
+		async get(request) {
+			const id = getCookie(request, name);
+			if (!id) return null;
+			const raw = await backend.get(`sf:session:${id}`);
+			if (raw === null) return null;
+			try {
+				return JSON.parse(raw) as T;
+			} catch {
+				return null;
+			}
+		},
+		async set(headers, data) {
+			const id = newId();
+			await backend.set(`sf:session:${id}`, JSON.stringify(data), ttl);
+			setCookie(headers, name, id, {
+				httpOnly: true,
+				sameSite: "lax",
+				maxAge: ttl,
+				...options.cookie,
+			});
+		},
+		destroy(headers) {
+			deleteCookie(headers, name, { path: options.cookie?.path });
+		},
+	};
+};
+
+/** In-memory session backend — dev/testing; not multi-instance safe */
+export const memorySessionStore = <T = Record<string, unknown>>(options?: {
+	name?: string;
+	cookie?: CookieOptions;
+	ttl?: number;
+}): Session<T> => {
+	const map = new Map<string, string>();
+	return serverSessionStore<T>(
+		{
+			get: async (k) => map.get(k) ?? null,
+			set: async (k, v) => void map.set(k, v),
+			delete: async (k) => void map.delete(k),
+		},
+		options,
+	);
+};
+
+/** Edge KV / Redis-style client adapter — `{get,set,del|delete}` */
+export const kvSessionStore = <T = Record<string, unknown>>(
+	kv: {
+		get(key: string): Promise<string | null>;
+		set(key: string, value: string, opts?: { ex?: number }): Promise<unknown>;
+		del?(key: string): Promise<unknown>;
+		delete?(key: string): Promise<unknown>;
+	},
+	options?: { name?: string; cookie?: CookieOptions; ttl?: number },
+): Session<T> =>
+	serverSessionStore<T>(
+		{
+			get: (k) => kv.get(k),
+			set: (k, v, ttl) => kv.set(k, v, ttl ? { ex: ttl } : undefined),
+			delete: (k) =>
+				kv.del ? kv.del(k) : (kv.delete?.(k) ?? Promise.resolve()),
+		},
+		options,
+	);

package/src/server/modules/http/index.ts

@@ -0,0 +1,15 @@
+export * from "./domain/operations/cookies";
+export {
+	httpMetrics,
+	metrics,
+	renderMetrics,
+	resetMetrics,
+} from "./domain/operations/metrics";
+export {
+	getRequest,
+	type RequestEvent,
+	runWithRequest,
+	useRequestEvent,
+	useRequestState,
+} from "./domain/operations/request-context";
+export * from "./domain/operations/session-store";

package/src/server/modules/loaders/application/index.ts

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

package/src/server/modules/loaders/application/usecases/create-route-loader.ts

@@ -0,0 +1,88 @@
+/**
+ * Route Loader
+ * Route-level data loading with SSR dehydration — the useFetch/loaders equivalent
+ *
+ * Server: execute() runs during SSR and stores the result in the hydration
+ * payload. Client: read() returns the hydrated value without refetching.
+ */
+
+import { isServer } from "solid-js/web";
+import { readHydrationPayload } from "#render/modules/render/domain";
+import type { HydrationPayload } from "#render/types";
+import type { LoaderContext, RouteLoader } from "#server/types";
+
+export interface RouteLoaderOptions<TOutput> {
+	/** Stable key used in the hydration payload */
+	key: string;
+	/** Fallback when no hydrated value exists on the client */
+	fallback?: () => Promise<TOutput>;
+}
+
+const pending = new Map<string, Promise<unknown>>();
+
+export const createRouteLoader = <TOutput>(
+	options: RouteLoaderOptions<TOutput>,
+	load: (context: LoaderContext) => Promise<TOutput>,
+): RouteLoader<TOutput> => {
+	let cached: TOutput | undefined;
+	let hydrated = false;
+
+	const loader: RouteLoader<TOutput> = {
+		key: options.key,
+
+		async execute(context: LoaderContext): Promise<TOutput> {
+			const result = await load(context);
+			cached = result;
+			hydrated = true;
+			return result;
+		},
+
+		read(): TOutput | undefined {
+			if (hydrated) return cached;
+
+			if (!isServer) {
+				const payload = readHydrationPayload();
+				if (options.key in payload.loaders) {
+					cached = payload.loaders[options.key] as TOutput;
+					hydrated = true;
+					return cached;
+				}
+				if (options.fallback && !pending.has(options.key)) {
+					pending.set(
+						options.key,
+						options.fallback().then((value) => {
+							cached = value;
+							hydrated = true;
+							return value;
+						}),
+					);
+				}
+			}
+
+			return cached;
+		},
+
+		invalidate(): void {
+			cached = undefined;
+			hydrated = false;
+			pending.delete(options.key);
+		},
+	};
+
+	return loader;
+};
+
+/**
+ * Execute loaders during SSR and write results into the hydration payload
+ */
+export const runLoaders = async (
+	context: LoaderContext,
+	payload: HydrationPayload,
+	loaders: RouteLoader<unknown>[],
+): Promise<void> => {
+	await Promise.all(
+		loaders.map(async (loader) => {
+			payload.loaders[loader.key] = await loader.execute(context);
+		}),
+	);
+};

package/src/server/modules/loaders/application/usecases/dehydrate.ts

@@ -0,0 +1,21 @@
+/**
+ * Dehydrate
+ * Serialize framework state (stores, query cache) into the hydration payload
+ */
+
+import type { HydrationPayload } from "#render/types";
+import { dehydrateStore } from "#stores/modules/store/domain/operations/hydration";
+import type { Store } from "#stores/modules/store/types";
+
+/**
+ * Write named stores into the hydration payload under `stores`
+ */
+export const dehydrateStores = (
+	payload: HydrationPayload,
+	stores: Record<string, Store<unknown>>,
+): HydrationPayload => {
+	for (const [key, store] of Object.entries(stores)) {
+		payload.stores[key] = JSON.parse(dehydrateStore(store)) as unknown;
+	}
+	return payload;
+};

package/src/server/modules/loaders/application/usecases/index.ts

@@ -0,0 +1,2 @@
+export * from "./create-route-loader";
+export * from "./dehydrate";

package/src/server/modules/loaders/index.ts

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

package/src/server/modules/realtime/domain/operations/channels.ts

@@ -0,0 +1,241 @@
+/**
+ * WebSocket Channels
+ * `defineChannel` registers a bidirectional channel at `/_ws/<id>`;
+ * `useChannel` subscribes on the client with a signal — the
+ * counterpart to SSE live queries for push/pull messaging:
+ *
+ *   export const chat = defineChannel<{ text: string }>({ id: "chat" })
+ *     .handler({
+ *       onConnect(socket) { socket.send({ hello: true }); },
+ *       onMessage(socket, msg) { socket.broadcast(msg); },
+ *     });
+ *
+ *   const { messages, send } = useChannel(chat);
+ */
+
+import { createSignal, onCleanup } from "solid-js";
+import { isServer } from "solid-js/web";
+import {
+	deserialize,
+	serialize,
+} from "../../../server-functions/domain/operations/serialize";
+
+export const WS_ENDPOINT = "/_ws";
+
+export const isChannelRequest = (request: Request): boolean =>
+	new URL(request.url).pathname.startsWith(`${WS_ENDPOINT}/`);
+
+/** Minimal socket surface across runtimes (Bun/Workers ws) */
+export interface ChannelSocket {
+	send: (data: unknown) => void;
+	close: (code?: number, reason?: string) => void;
+	/** Publish to every other open socket on the channel */
+	broadcast: (data: unknown) => void;
+	/** Join a named room — broadcastTo targets only members */
+	join: (room: string) => void;
+	leave: (room: string) => void;
+	/** Publish to every other open socket inside a room */
+	broadcastTo: (room: string, data: unknown) => void;
+	/** Rooms this socket belongs to */
+	rooms: () => string[];
+}
+
+export interface ChannelHandlers {
+	onConnect?: (socket: ChannelSocket, request: Request) => void;
+	onMessage?: (socket: ChannelSocket, message: unknown) => void;
+	onClose?: (socket: ChannelSocket) => void;
+}
+
+/** Presence frame key — broadcast to every socket on join/leave */
+export const PRESENCE_KEY = "__presence";
+
+const broadcastPresence = (id: string): void => {
+	const set = sockets.get(id);
+	if (!set) return;
+	const frame = JSON.stringify(
+		serialize({ [PRESENCE_KEY]: { count: set.size } }),
+	);
+	for (const peer of set) peer.send(frame);
+};
+
+export interface ChannelDescriptor<T = unknown> {
+	id: string;
+	handlers: ChannelHandlers;
+	readonly __type?: T;
+}
+
+const registry = new Map<string, ChannelHandlers>();
+/** Open raw sockets per channel — used by broadcast */
+const sockets = new Map<string, Set<{ send: (d: string) => void }>>();
+/** Room membership — channelId → room → raw sockets */
+const rooms = new Map<
+	string,
+	Map<string, Set<{ send: (d: string) => void }>>
+>();
+
+export const defineChannel = <T = unknown>(options: {
+	id: string;
+}): { handler: (h: ChannelHandlers) => ChannelDescriptor<T> } => ({
+	handler(handlers) {
+		const descriptor: ChannelDescriptor<T> = {
+			id: options.id,
+			handlers,
+		};
+		if (isServer) registry.set(options.id, handlers);
+		return descriptor;
+	},
+});
+
+export const getChannel = (id: string): ChannelHandlers | undefined =>
+	registry.get(id);
+
+/**
+ * Adapt a runtime WebSocket into the channel contract — call from the
+ * server's upgrade hook (e.g. Bun.serve websocket handlers)
+ */
+export const bindChannelSocket = (
+	id: string,
+	raw: { send: (d: string) => void; close: (c?: number, r?: string) => void },
+	request: Request,
+): { message: (data: string) => void; close: () => void } | null => {
+	const handlers = registry.get(id);
+	if (!handlers) return null;
+
+	const set = sockets.get(id) ?? new Set<typeof raw>();
+	set.add(raw);
+	sockets.set(id, set);
+
+	const joined = new Set<string>();
+	const socket: ChannelSocket = {
+		send: (data) => raw.send(JSON.stringify(serialize(data))),
+		broadcast: (data) => {
+			const frame = JSON.stringify(serialize(data));
+			for (const peer of sockets.get(id) ?? []) {
+				if (peer !== raw) peer.send(frame);
+			}
+		},
+		join: (room) => {
+			const byRoom = rooms.get(id) ?? new Map();
+			const members = byRoom.get(room) ?? new Set();
+			members.add(raw);
+			byRoom.set(room, members);
+			rooms.set(id, byRoom);
+			joined.add(room);
+		},
+		leave: (room) => {
+			rooms.get(id)?.get(room)?.delete(raw);
+			joined.delete(room);
+		},
+		broadcastTo: (room, data) => {
+			const frame = JSON.stringify(serialize(data));
+			for (const peer of rooms.get(id)?.get(room) ?? []) {
+				if (peer !== raw) peer.send(frame);
+			}
+		},
+		rooms: () => [...joined],
+		close: (code, reason) => raw.close(code, reason),
+	};
+	handlers.onConnect?.(socket, request);
+	broadcastPresence(id);
+
+	return {
+		message: (data) => {
+			try {
+				handlers.onMessage?.(socket, deserialize(JSON.parse(data) as never));
+			} catch {
+				socket.send({ error: "invalid frame" });
+			}
+		},
+		close: () => {
+			set.delete(raw);
+			for (const room of joined) rooms.get(id)?.get(room)?.delete(raw);
+			handlers.onClose?.(socket);
+			broadcastPresence(id);
+		},
+	};
+};
+
+export interface UseChannel<T> {
+	messages: () => T[];
+	send: (data: unknown) => void;
+	open: () => boolean;
+	/** Connected socket count — updates on join/leave frames */
+	presence: () => number | undefined;
+}
+
+export interface UseChannelOptions {
+	baseUrl?: string;
+	/** Reconnect on close with exponential backoff — default true */
+	reconnect?: boolean;
+	/** Backoff ceiling in ms — default 30000 */
+	maxDelay?: number;
+}
+
+/** Client hook — subscribe to a channel, accumulate messages */
+export const useChannel = <T = unknown>(
+	channel: ChannelDescriptor<T>,
+	options: UseChannelOptions = {},
+): UseChannel<T> => {
+	const [messages, setMessages] = createSignal<T[]>([]);
+	const [open, setOpen] = createSignal(false);
+	const [presence, setPresence] = createSignal<number>();
+	let ws: WebSocket | undefined;
+	let disposed = false;
+	let attempts = 0;
+
+	const connect = () => {
+		if (disposed || isServer || typeof WebSocket === "undefined") return;
+		const base =
+			options.baseUrl ??
+			`${location.protocol === "https:" ? "wss" : "ws"}://${location.host}`;
+		ws = new WebSocket(
+			`${base}${WS_ENDPOINT}/${encodeURIComponent(channel.id)}`,
+		);
+		ws.onopen = () => {
+			attempts = 0;
+			setOpen(true);
+		};
+		ws.onclose = () => {
+			setOpen(false);
+			if (disposed || options.reconnect === false) return;
+			// Exponential backoff — 1s, 2s, 4s … capped at maxDelay
+			const delay = Math.min(1000 * 2 ** attempts, options.maxDelay ?? 30_000);
+			attempts += 1;
+			setTimeout(connect, delay);
+		};
+		ws.onmessage = (event) => {
+			try {
+				const value = deserialize(JSON.parse(String(event.data)) as never) as
+					| T
+					| { [PRESENCE_KEY]: { count: number } };
+				if (
+					typeof value === "object" &&
+					value !== null &&
+					PRESENCE_KEY in value
+				) {
+					setPresence(
+						(value as { [PRESENCE_KEY]: { count: number } })[PRESENCE_KEY]
+							.count,
+					);
+					return;
+				}
+				setMessages((list) => [...list, value as T]);
+			} catch {
+				// ignore malformed frames
+			}
+		};
+	};
+
+	connect();
+	onCleanup(() => {
+		disposed = true;
+		ws?.close();
+	});
+
+	return {
+		messages,
+		open,
+		presence,
+		send: (data) => ws?.send(JSON.stringify(serialize(data))),
+	};
+};

package/src/server/modules/realtime/domain/operations/sse.ts

@@ -0,0 +1,63 @@
+/**
+ * Server-Sent Events
+ * `defineEventStream` wraps an emit function into a text/event-stream
+ * Response — web-standard, runs on every runtime
+ *
+ *   export const GET = defineEventStream((emit) => {
+ *     const t = setInterval(() => emit({ tick: Date.now() }), 1000);
+ *     return () => clearInterval(t); // cleanup on disconnect
+ *   });
+ */
+
+export type SseEmit = (event: unknown, name?: string, id?: string) => void;
+
+export type EventStreamSetup = (
+	emit: SseEmit,
+	request: Request,
+) => undefined | (() => void);
+
+const format = (event: unknown, name?: string, id?: string): string => {
+	const data = typeof event === "string" ? event : JSON.stringify(event);
+	return `${id ? `id: ${id}\n` : ""}${name ? `event: ${name}\n` : ""}data: ${data}\n\n`;
+};
+
+export const defineEventStream = (
+	setup: EventStreamSetup,
+): ((request: Request) => Response) => {
+	return (request: Request): Response => {
+		const encoder = new TextEncoder();
+		const stream = new ReadableStream<Uint8Array>({
+			start(controller) {
+				const emit: SseEmit = (event, name, id) => {
+					try {
+						controller.enqueue(encoder.encode(format(event, name, id)));
+					} catch {
+						/* stream closed */
+					}
+				};
+				const cleanup = setup(emit, request);
+				// Heartbeat keeps proxies from buffering-closing the stream
+				const heartbeat = setInterval(
+					() => emit({ ts: Date.now() }, "ping"),
+					15000,
+				);
+				request.signal.addEventListener("abort", () => {
+					clearInterval(heartbeat);
+					cleanup?.();
+					try {
+						controller.close();
+					} catch {
+						/* already closed */
+					}
+				});
+			},
+		});
+		return new Response(stream, {
+			headers: {
+				"Content-Type": "text/event-stream",
+				"Cache-Control": "no-cache",
+				Connection: "keep-alive",
+			},
+		});
+	};
+};

package/src/server/modules/realtime/index.ts

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

package/src/server/modules/server-functions/adapters/http/handler.ts

@@ -0,0 +1,128 @@
+/**
+ * Server Function HTTP Handler
+ * Dispatches `/_server/fn/<id>` requests to registered descriptors
+ */
+
+import type { ServerFnErrorPayload } from "#server/types";
+import {
+	runMiddleware,
+	runValidator,
+	SERVER_FN_BASE,
+} from "../../application/usecases/create-server-fn";
+import {
+	isSameOriginRequest,
+	type ServerFnCsrfOptions,
+} from "../../application/usecases/csrf";
+import { getServerFn } from "../../application/usecases/registry";
+import {
+	deserialize,
+	isAsyncIterable,
+	isReadableStream,
+	serialize,
+} from "../../domain/operations/serialize";
+import { streamResponse } from "../../domain/operations/stream";
+
+const jsonError = (status: number, payload: ServerFnErrorPayload): Response =>
+	new Response(JSON.stringify({ error: payload }), {
+		status,
+		headers: { "Content-Type": "application/json" },
+	});
+
+export const isServerFnRequest = (request: Request): boolean =>
+	new URL(request.url).pathname.startsWith(`${SERVER_FN_BASE}/`);
+
+const readInput = async (request: Request): Promise<unknown> => {
+	const url = new URL(request.url);
+	if (request.method === "GET") {
+		const raw = url.searchParams.get("input");
+		return raw === null
+			? null
+			: deserialize(JSON.parse(raw) as Parameters<typeof deserialize>[0]);
+	}
+	if (request.method === "POST") {
+		const contentType = request.headers.get("Content-Type") ?? "";
+		if (contentType.includes("application/json")) {
+			const body = (await request.json()) as { input?: unknown };
+			return deserialize(
+				(body.input ?? null) as Parameters<typeof deserialize>[0],
+			);
+		}
+		return Object.fromEntries(await request.formData());
+	}
+	return null;
+};
+
+export interface ServerFnHandlerOptions {
+	/**
+	 * Same-origin guard — enabled by default. Pass `false` to disable or an
+	 * options object to allow extra origins / no fetch metadata.
+	 */
+	csrf?: ServerFnCsrfOptions | false;
+}
+
+export const createServerFnHandler = (
+	options: ServerFnHandlerOptions = {},
+): ((request: Request) => Promise<Response>) => {
+	const csrf = options.csrf ?? {};
+
+	return async (request: Request): Promise<Response> => {
+		if (csrf !== false && !isSameOriginRequest(request, csrf)) {
+			return jsonError(403, {
+				code: "FORBIDDEN",
+				message: "Server functions must be called from the same origin",
+			});
+		}
+
+		const url = new URL(request.url);
+		const id = decodeURIComponent(
+			url.pathname.slice(SERVER_FN_BASE.length + 1),
+		);
+
+		const descriptor = getServerFn(id);
+		if (!descriptor) {
+			return jsonError(404, {
+				code: "NOT_FOUND",
+				message: `Unknown server function: ${id}`,
+			});
+		}
+
+		if (descriptor.method !== request.method && request.method !== "GET") {
+			return jsonError(405, {
+				code: "METHOD_NOT_ALLOWED",
+				message: `Server function ${id} expects ${descriptor.method}`,
+			});
+		}
+
+		try {
+			const rawInput = await readInput(request);
+			const data = runValidator(descriptor.validator, rawInput);
+			const context = { request, params: {} };
+			const short = await runMiddleware(descriptor.middleware, data, context);
+			if (short) return short;
+			const result = await descriptor.handler({ data, context });
+			// Advanced serialization — streams and async iterables travel as
+			// an NDJSON body the client re-materializes as an async iterable;
+			// Response returns pass through untouched
+			if (result instanceof Response) return result;
+			if (isAsyncIterable(result) || isReadableStream(result)) {
+				return streamResponse(result);
+			}
+			return new Response(JSON.stringify({ result: serialize(result) }), {
+				headers: { "Content-Type": "application/json" },
+			});
+		} catch (error) {
+			const payload: ServerFnErrorPayload =
+				error instanceof Error
+					? {
+							code: "code" in error ? String(error.code) : "INTERNAL_ERROR",
+							message: error.message,
+							data: (error as { data?: unknown }).data,
+						}
+					: { code: "INTERNAL_ERROR", message: "Server function failed" };
+			return jsonError(
+				payload.code === "VALIDATION_ERROR" ? 400 : 500,
+				payload,
+			);
+		}
+	};
+};

package/src/server/modules/server-functions/application/index.ts

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