@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/server/modules/server-functions/application/usecases/batch.ts

@@ -0,0 +1,135 @@
+/**
+ * Server-Function Batching
+ * Collects client calls made within the same microtask into a single
+ * POST `/_server/batch` — the SvelteKit `query.batch()` equivalent
+ *
+ *   const fn = createServerFn({ id: "users.list", batch: true })
+ *     .handler(...)
+ */
+
+import type { ServerFnErrorPayload } from "#server/types";
+import { deserialize, serialize } from "../../domain/operations/serialize";
+import { runValidator } from "./create-server-fn";
+import { getServerFn } from "./registry";
+
+export const SERVER_FN_BATCH = "/_server/batch";
+
+export const isBatchRequest = (request: Request): boolean =>
+	new URL(request.url).pathname === SERVER_FN_BATCH &&
+	request.method === "POST";
+
+interface BatchCall {
+	id: string;
+	input?: unknown;
+}
+
+export const createBatchHandler = (): ((
+	request: Request,
+) => Promise<Response>) => {
+	return async (request: Request): Promise<Response> => {
+		let calls: BatchCall[];
+		try {
+			const body = (await request.json()) as { calls?: BatchCall[] };
+			calls = body.calls ?? [];
+		} catch {
+			return Response.json(
+				{ error: { code: "BAD_REQUEST", message: "Invalid batch body" } },
+				{ status: 400 },
+			);
+		}
+
+		const results = await Promise.all(
+			calls.map(async (call) => {
+				const descriptor = getServerFn(call.id);
+				if (!descriptor) {
+					return {
+						error: {
+							code: "NOT_FOUND",
+							message: `Unknown server function: ${call.id}`,
+						} satisfies ServerFnErrorPayload,
+					};
+				}
+				try {
+					const data = runValidator(
+						descriptor.validator,
+						deserialize((call.input ?? null) as never),
+					);
+					const result = await descriptor.handler({
+						data,
+						context: { request, params: {} },
+					});
+					return { result: serialize(result) };
+				} catch (error) {
+					return {
+						error: {
+							code: "INTERNAL_ERROR",
+							message:
+								error instanceof Error ? error.message : "batch call failed",
+						} satisfies ServerFnErrorPayload,
+					};
+				}
+			}),
+		);
+
+		return Response.json({ results });
+	};
+};
+
+// ---- client-side batcher ----
+
+interface Pending {
+	id: string;
+	input: unknown;
+	resolve: (v: unknown) => void;
+	reject: (e: unknown) => void;
+}
+
+let queue: Pending[] = [];
+let flushing = false;
+
+const flush = async (baseUrl: string, fetchFn: typeof fetch): Promise<void> => {
+	const pending = queue;
+	queue = [];
+	flushing = false;
+
+	try {
+		const response = await fetchFn(`${baseUrl}${SERVER_FN_BATCH}`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				calls: pending.map((p) => ({ id: p.id, input: serialize(p.input) })),
+			}),
+		});
+		const body = (await response.json()) as {
+			results?: Array<{ result?: unknown; error?: { message?: string } }>;
+		};
+		const results = body.results ?? [];
+		pending.forEach((p, i) => {
+			const r = results[i];
+			if (r?.error) p.reject(new Error(r.error.message ?? "batch failed"));
+			else p.resolve(deserialize((r?.result ?? null) as never));
+		});
+	} catch (error) {
+		for (const p of pending) p.reject(error);
+	}
+};
+
+/** Enqueue a call — flushed into one POST at microtask end */
+export const callBatched = <T>(
+	baseUrl: string,
+	fetchFn: typeof fetch,
+	id: string,
+	input: unknown,
+): Promise<T> =>
+	new Promise<T>((resolve, reject) => {
+		queue.push({
+			id,
+			input,
+			resolve: resolve as (v: unknown) => void,
+			reject,
+		});
+		if (!flushing) {
+			flushing = true;
+			queueMicrotask(() => void flush(baseUrl, fetchFn));
+		}
+	});

package/src/server/modules/server-functions/application/usecases/create-server-fn.ts

@@ -0,0 +1,272 @@
+/**
+ * createServerFn
+ * Type-safe RPC — call server code from the client like a local function
+ *
+ * On the server the handler executes directly. On the client the call is
+ * dispatched over HTTP to `/_server/fn/<id>` and the result is deserialized.
+ */
+
+import { isServer } from "solid-js/web";
+import {
+	deserialize,
+	serialize,
+} from "#server/modules/server-functions/domain/operations/serialize";
+import {
+	NDJSON_CONTENT_TYPE,
+	readStreamResponse,
+} from "#server/modules/server-functions/domain/operations/stream";
+import { ServerFnError } from "#server/shared/errors";
+import type {
+	ServerFnContext,
+	ServerFnDescriptor,
+	ServerFnHandler,
+	ServerFnMethod,
+	ServerFnMiddleware,
+	ServerFnValidator,
+} from "#server/types";
+import { callBatched } from "./batch";
+import { registerServerFn } from "./registry";
+import { registerSchedule } from "./scheduler";
+
+export interface CreateServerFnOptions {
+	/**
+	 * Stable, unique id shared between client and server bundles.
+	 * Convention: "<domain>.<action>", e.g. "users.list".
+	 * Optional — the vite plugin injects a deterministic id when absent.
+	 */
+	id?: string;
+	method?: ServerFnMethod;
+	/**
+	 * Batch calls — calls made within the same microtask travel in a
+	 * single POST /_server/batch (the query.batch() equivalent)
+	 */
+	batch?: boolean;
+	/**
+	 * Cron schedule — registers the fn for periodic execution when
+	 * startScheduler() runs (5-field cron, minute granularity)
+	 */
+	schedule?: string;
+	/** Custom endpoint base — defaults to the framework convention */
+	baseUrl?: string;
+	fetch?: typeof fetch;
+}
+
+export interface ServerFnBuilder<TInput = undefined> {
+	validator<TNext>(validator: ServerFnValidator<TNext>): ServerFnBuilder<TNext>;
+	/**
+	 * Composable middleware — runs after validation, before the handler.
+	 * Return a Response to short-circuit, an object to merge into
+	 * `context` (auth user, db handle), or nothing.
+	 */
+	middleware(
+		mw: ServerFnMiddleware | ServerFnMiddleware[],
+	): ServerFnBuilder<TInput>;
+	/**
+	 * Client-side middleware — runs before the remote fetch. Return
+	 * `{ headers: {...} }` to merge request headers (auth tokens),
+	 * a Response to short-circuit, or other keys into context.
+	 */
+	client(
+		mw: ServerFnMiddleware | ServerFnMiddleware[],
+	): ServerFnBuilder<TInput>;
+	handler<TOutput>(
+		handler: ServerFnHandler<TInput, TOutput>,
+	): ServerFn<TInput, TOutput>;
+}
+
+export type ServerFn<TInput, TOutput> = [TInput] extends [undefined]
+	? (input?: TInput) => Promise<TOutput>
+	: (input: TInput) => Promise<TOutput>;
+
+export const SERVER_FN_BASE = "/_server/fn";
+
+export const runValidator = <TInput>(
+	validator: ServerFnValidator<TInput> | undefined,
+	input: unknown,
+): TInput => {
+	if (!validator) return input as TInput;
+
+	if (typeof validator === "function") {
+		return validator(input);
+	}
+
+	const result = validator["~standard"].validate(input) as
+		| { value?: TInput; issues?: unknown }
+		| Promise<{ value?: TInput; issues?: unknown }>;
+	if (result instanceof Promise) {
+		throw new Error(
+			"[solid-framework] async standard-schema validators are not supported in createServerFn; validate inside the handler",
+		);
+	}
+	if (result.issues) {
+		throw new ServerFnError({
+			code: "VALIDATION_ERROR",
+			message: "Invalid server function input",
+			data: result.issues,
+		});
+	}
+	return result.value as TInput;
+};
+
+/**
+ * Run a descriptor's middleware chain — returns a short-circuit
+ * Response or mutates `context` with merged middleware results
+ */
+export const runMiddleware = async (
+	middleware: ServerFnMiddleware[] | undefined,
+	data: unknown,
+	context: ServerFnContext,
+): Promise<Response | undefined> => {
+	for (const mw of middleware ?? []) {
+		const r = await mw({ data, context });
+		if (r instanceof Response) return r;
+		if (r && typeof r === "object") Object.assign(context, r);
+	}
+	return undefined;
+};
+
+const callRemote = async <TInput, TOutput>(
+	options: CreateServerFnOptions & { id: string },
+	input: TInput,
+	clientMw?: ServerFnMiddleware[],
+): Promise<TOutput> => {
+	const fetchFn = options.fetch ?? fetch;
+	const method = options.method ?? "POST";
+	const base = (options.baseUrl ?? "") + SERVER_FN_BASE;
+	const url = `${base}/${encodeURIComponent(options.id)}`;
+
+	// Client middleware — headers/auth hooks before the remote call
+	const extraHeaders: Record<string, string> = {};
+	if (clientMw?.length) {
+		const context: ServerFnContext = {
+			request: new Request(url, { method }),
+			params: {},
+		};
+		for (const mw of clientMw) {
+			const r = await mw({ data: input, context });
+			if (r instanceof Response) return r as TOutput;
+			if (r && typeof r === "object") {
+				const { headers, ...rest } = r;
+				if (headers && typeof headers === "object") {
+					Object.assign(extraHeaders, headers);
+				}
+				Object.assign(context, rest);
+			}
+		}
+	}
+
+	const response =
+		method === "GET"
+			? await fetchFn(
+					`${url}?input=${encodeURIComponent(JSON.stringify(serialize(input ?? null)))}`,
+					{ headers: extraHeaders },
+				)
+			: await fetchFn(url, {
+					method: "POST",
+					headers: {
+						"Content-Type": "application/json",
+						...extraHeaders,
+					},
+					body: JSON.stringify({ input: serialize(input ?? null) }),
+				});
+
+	// Streamed results (ReadableStream / AsyncIterable from the handler)
+	// arrive as NDJSON frames — re-materialize as an async iterable
+	const contentType = response.headers.get("Content-Type") ?? "";
+	if (contentType.includes(NDJSON_CONTENT_TYPE)) {
+		return readStreamResponse(response) as TOutput;
+	}
+	if (!response.headers.get("Content-Type")?.includes("application/json")) {
+		return response as unknown as TOutput;
+	}
+
+	const body = (await response.json()) as {
+		result?: Parameters<typeof deserialize>[0];
+		error?: { code?: string; message?: string; data?: unknown };
+	};
+
+	if (!response.ok || body.error) {
+		throw ServerFnError.fromJson(
+			body.error ?? { message: response.statusText },
+		);
+	}
+	return deserialize(body.result ?? null) as TOutput;
+};
+
+export const createServerFn = (
+	options: CreateServerFnOptions,
+): ServerFnBuilder<undefined> => {
+	let validator: ServerFnValidator<unknown> | undefined;
+	const middleware: ServerFnMiddleware[] = [];
+	const clientMw: ServerFnMiddleware[] = [];
+
+	const builder: ServerFnBuilder<never> = {
+		validator<TNext>(next: ServerFnValidator<TNext>) {
+			validator = next as ServerFnValidator<unknown>;
+			return builder as unknown as ServerFnBuilder<TNext>;
+		},
+		middleware(mw: ServerFnMiddleware | ServerFnMiddleware[]) {
+			middleware.push(...(Array.isArray(mw) ? mw : [mw]));
+			return builder;
+		},
+		client(mw: ServerFnMiddleware | ServerFnMiddleware[]) {
+			clientMw.push(...(Array.isArray(mw) ? mw : [mw]));
+			return builder;
+		},
+		handler<TOutput>(handler: ServerFnHandler<never, TOutput>) {
+			// Explicit id wins; otherwise hash the handler source so dev and
+			// prod resolve identically when the vite transform did not run
+			const resolved =
+				options.id ??
+				`fn_${String(handler).length.toString(36)}_${String(handler)
+					.split("")
+					.reduce((a, c) => (a * 31 + c.charCodeAt(0)) | 0, 7)
+					.toString(36)}`;
+			const resolvedOptions = { ...options, id: resolved };
+			const descriptor: ServerFnDescriptor<never, TOutput> = {
+				id: resolved,
+				method: options.method ?? "POST",
+				validator: validator as ServerFnValidator<never>,
+				middleware: middleware.length ? middleware : undefined,
+				handler,
+			};
+
+			if (isServer) {
+				registerServerFn(descriptor);
+				if (options.schedule) registerSchedule(resolved, options.schedule);
+				return (async (input: never) => {
+					const data = runValidator(descriptor.validator, input);
+					const context: ServerFnContext = {
+						request: new Request("http://localhost"),
+						params: {},
+					};
+					const short = await runMiddleware(
+						descriptor.middleware,
+						data,
+						context,
+					);
+					if (short) return short as TOutput;
+					return handler({ data, context });
+				}) as ServerFn<never, TOutput>;
+			}
+
+			return (async (input: never) => {
+				if (options.batch) {
+					return callBatched<TOutput>(
+						options.baseUrl ?? "",
+						options.fetch ?? fetch,
+						resolved,
+						input,
+					);
+				}
+				return callRemote<never, TOutput>(
+					resolvedOptions,
+					input,
+					clientMw.length ? clientMw : undefined,
+				);
+			}) as ServerFn<never, TOutput>;
+		},
+	};
+
+	return builder as unknown as ServerFnBuilder<undefined>;
+};

package/src/server/modules/server-functions/application/usecases/csrf.ts

@@ -0,0 +1,67 @@
+/**
+ * Same-origin guard for `/_server/fn` (and other `/_server/*` endpoints)
+ *
+ * Server functions are same-origin RPC endpoints — they must not be callable
+ * cross-site. The check mirrors TanStack Start's CSRF middleware:
+ *
+ *   1. `Sec-Fetch-Site` — allows same-origin / same-site / none, rejects
+ *      cross-site
+ *   2. `Origin` / `Referer` — compared against the request URL origin
+ *   3. No fetch metadata at all — rejected unless `allowNoFetchMetadata`
+ *      (non-browser clients like curl send none of these headers)
+ */
+
+export interface ServerFnCsrfOptions {
+	/**
+	 * Extra origins allowed to call server functions when the deployment
+	 * serves the API under a different public origin (e.g. api.example.com)
+	 */
+	origin?: string | string[];
+	/**
+	 * Allow requests without Sec-Fetch-Site / Origin / Referer headers.
+	 * Enable only when another layer guarantees same-origin calls.
+	 */
+	allowNoFetchMetadata?: boolean;
+}
+
+const SAFE_FETCH_SITES = new Set(["same-origin", "same-site", "none"]);
+
+const originOf = (value: string): string | undefined => {
+	try {
+		return new URL(value).origin;
+	} catch {
+		return undefined;
+	}
+};
+
+export const isSameOriginRequest = (
+	request: Request,
+	options: ServerFnCsrfOptions = {},
+): boolean => {
+	const requestOrigin = new URL(request.url).origin;
+	const extra = options.origin ?? [];
+	const allowed = new Set<string>([requestOrigin]);
+	for (const o of Array.isArray(extra) ? extra : [extra]) {
+		const parsed = originOf(o);
+		if (parsed) allowed.add(parsed);
+	}
+
+	const fetchSite = request.headers.get("Sec-Fetch-Site");
+	if (fetchSite !== null) {
+		return SAFE_FETCH_SITES.has(fetchSite.toLowerCase());
+	}
+
+	const origin = request.headers.get("Origin");
+	if (origin !== null) {
+		const parsed = originOf(origin);
+		return parsed !== undefined && allowed.has(parsed);
+	}
+
+	const referer = request.headers.get("Referer");
+	if (referer !== null) {
+		const parsed = originOf(referer);
+		return parsed !== undefined && allowed.has(parsed);
+	}
+
+	return options.allowNoFetchMetadata === true;
+};

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

@@ -0,0 +1,6 @@
+export * from "./batch";
+export * from "./create-server-fn";
+export * from "./csrf";
+export * from "./live";
+export * from "./registry";
+export * from "./scheduler";

package/src/server/modules/server-functions/application/usecases/live.ts

@@ -0,0 +1,172 @@
+/**
+ * Live Queries
+ * `defineLiveQuery` registers an async-iterable source served as
+ * Server-Sent Events at `/_server/live/<id>`; `useLiveQuery`
+ * subscribes on the client — the SvelteKit `query.live` equivalent
+ *
+ *   // src/fns/clock.live.ts
+ *   export const clock = defineLiveQuery({ id: "clock" })
+ *     .handler(async function* () {
+ *       while (true) { yield Date.now(); await sleep(1000); }
+ *     });
+ *
+ *   // component
+ *   const time = useLiveQuery(clock);  // accessor — latest value
+ */
+
+import { createEffect, createSignal, onCleanup } from "solid-js";
+import { isServer } from "solid-js/web";
+import {
+	defineEventStream,
+	type SseEmit,
+} from "../../../realtime/domain/operations/sse";
+import { deserialize, serialize } from "../../domain/operations/serialize";
+
+export const LIVE_ENDPOINT = "/_server/live";
+
+type LiveSource = (ctx: { request: Request }) => AsyncIterable<unknown>;
+
+const registry = new Map<string, LiveSource>();
+/** Open SSE emitters per query id — revalidateLiveQuery pushes to them */
+const emitters = new Map<string, Set<SseEmit>>();
+
+/**
+ * Replay buffers — last N data events per query id; EventSource
+ * reconnects send `Last-Event-ID`, so missed frames replay before
+ * live ones (instantdb-style resume)
+ */
+const REPLAY_LIMIT = 50;
+const replays = new Map<string, { id: number; data: unknown }[]>();
+const seq = new Map<string, number>();
+
+const bufferEvent = (id: string, data: unknown): string => {
+	const n = (seq.get(id) ?? 0) + 1;
+	seq.set(id, n);
+	const buf = replays.get(id) ?? [];
+	buf.push({ id: n, data });
+	if (buf.length > REPLAY_LIMIT) buf.shift();
+	replays.set(id, buf);
+	return String(n);
+};
+
+/**
+ * Push a "revalidate" event to every open connection of a live query —
+ * call after a mutation (action/server-fn) so subscribers re-subscribe
+ * and receive fresh data
+ */
+export const revalidateLiveQuery = (id: string): void => {
+	for (const emit of emitters.get(id) ?? []) emit({}, "revalidate");
+};
+
+export const isLiveRequest = (request: Request): boolean =>
+	new URL(request.url).pathname.startsWith(`${LIVE_ENDPOINT}/`);
+
+export const createLiveQueryHandler = (): ((request: Request) => Response) => {
+	return (request: Request): Response => {
+		const id = decodeURIComponent(
+			new URL(request.url).pathname.slice(LIVE_ENDPOINT.length + 1),
+		);
+		const source = registry.get(id);
+		if (!source) {
+			return Response.json(
+				{ error: { code: "NOT_FOUND", message: `Unknown live query: ${id}` } },
+				{ status: 404 },
+			);
+		}
+		const iterable = source({ request });
+		return defineEventStream((emit: SseEmit, req: Request) => {
+			let cancelled = false;
+			const set = emitters.get(id) ?? new Set<SseEmit>();
+			set.add(emit);
+			emitters.set(id, set);
+			// Resume — replay buffered events past the client's Last-Event-ID
+			const last = Number(req.headers.get("last-event-id") ?? 0);
+			if (last > 0) {
+				for (const e of replays.get(id) ?? []) {
+					if (e.id > last) emit(e.data, "data", String(e.id));
+				}
+			}
+			void (async () => {
+				try {
+					for await (const value of iterable) {
+						if (cancelled || req.signal.aborted) break;
+						const serialized = serialize(value);
+						const eventId = bufferEvent(id, serialized);
+						emit(serialized, "data", eventId);
+					}
+					// finite sources signal completion — consumers may close
+					if (!cancelled && !req.signal.aborted) emit({}, "done");
+				} catch (error) {
+					emit(
+						{ e: error instanceof Error ? error.message : "live query failed" },
+						"error",
+					);
+				}
+			})();
+			return () => {
+				cancelled = true;
+				set.delete(emit);
+			};
+		})(request);
+	};
+};
+
+export interface LiveQueryDescriptor<T> {
+	id: string;
+	source: LiveSource;
+	/** marker for typing */
+	readonly __type?: T;
+}
+
+export interface LiveQueryBuilder {
+	handler<T>(source: () => AsyncIterable<T>): LiveQueryDescriptor<T>;
+}
+
+export const defineLiveQuery = (options: {
+	id?: string;
+}): LiveQueryBuilder => ({
+	handler<T>(source: () => AsyncIterable<T>) {
+		const id =
+			options.id ??
+			`live_${String(source).length.toString(36)}_${String(source)
+				.split("")
+				.reduce((a, c) => (a * 31 + c.charCodeAt(0)) | 0, 7)
+				.toString(36)}`;
+		const descriptor: LiveQueryDescriptor<T> = {
+			id,
+			source: () => source(),
+		};
+		if (isServer) registry.set(id, () => source());
+		return descriptor;
+	},
+});
+
+/** Client hook — subscribe to a live query, returns latest value */
+export const useLiveQuery = <T>(
+	query: LiveQueryDescriptor<T>,
+	options: { baseUrl?: string } = {},
+): (() => T | undefined) => {
+	const [data, setData] = createSignal<T>();
+	const [epoch, setEpoch] = createSignal(0);
+
+	if (!isServer && typeof EventSource !== "undefined") {
+		// epoch bumps on "revalidate" — a fresh EventSource reconnects
+		// and the source regenerates current data
+		createEffect(() => {
+			epoch();
+			const url = `${options.baseUrl ?? ""}${LIVE_ENDPOINT}/${encodeURIComponent(query.id)}`;
+			const es = new EventSource(url);
+			es.addEventListener("data", (event) => {
+				const parsed = JSON.parse(
+					(event as MessageEvent).data as string,
+				) as never;
+				setData(() => deserialize(parsed) as T);
+			});
+			// finite sources close after "done"; live sources stay connected
+			es.addEventListener("done", () => es.close());
+			es.addEventListener("revalidate", () => setEpoch((e) => e + 1));
+			onCleanup(() => es.close());
+		});
+	}
+	return data;
+};

package/src/server/modules/server-functions/application/usecases/registry.ts

@@ -0,0 +1,22 @@
+/**
+ * Server Function Registry
+ * Server-side registry mapping function ids to descriptors
+ */
+
+import type { ServerFnDescriptor } from "#server/types";
+
+const registry = new Map<string, ServerFnDescriptor>();
+
+export const registerServerFn = <TInput, TOutput>(
+	descriptor: ServerFnDescriptor<TInput, TOutput>,
+): ServerFnDescriptor<TInput, TOutput> => {
+	registry.set(descriptor.id, descriptor as ServerFnDescriptor);
+	return descriptor;
+};
+
+export const getServerFn = (id: string): ServerFnDescriptor | undefined =>
+	registry.get(id);
+
+export const listServerFnIds = (): string[] => [...registry.keys()];
+
+export const clearServerFnRegistry = (): void => registry.clear();