@lovrozagar/flare 0.7.0 → 0.8.0

package/README.md

@@ -426,6 +426,24 @@ Pipeline: authenticate → authorize → preloaders (parent → child) → loade
 
 `<Await>` also accepts `error` and `onError`. Missing deferred data must not throw in `.then` — the component treats a missing promise as pending.
 
+### Fetch dedupe
+
+During a server request, identical `GET` / `HEAD` fetches share one upstream call: concurrent callers wait on it, and later callers in the same request reuse it. The key is method, URL, headers (minus `traceparent`, `tracestate`, `x-request-id`, `x-correlation-id`), and the request's mode fields such as `redirect`. `globalThis.fetch` is covered automatically.
+
+A fetch you pass around yourself, such as an SDK over a Workers service binding, opts in with `withFetchDedupe`. Pass the binding itself, not an arrow around it. Wrappers over the same target share one cache, so building the SDK per request still dedupes.
+
+```ts
+import { withFetchDedupe } from "@lovrozagar/flare/fetch-dedupe";
+
+const sdk = new ApiClient({ fetch: withFetchDedupe(env.API) });
+```
+
+- Each caller gets its own `Response` with the upstream status, headers, `url`, and `redirected`.
+- A caller's `AbortSignal` cancels only that caller. The upstream fetch is aborted once every caller has aborted.
+- Any other method passes through and clears the request's memoized responses.
+- Bodies over `maxBytes` (default 1 MiB, `withFetchDedupe(target, { maxBytes })`) and `text/event-stream` responses still stream but are not reused by later callers.
+- Outside a request (browser, module scope, queue consumers) it is a plain passthrough.
+
 ## Hooks
 
 From `@lovrozagar/flare` (route-builder barrel) / the same names on the provider:
@@ -1124,6 +1142,7 @@ Import features from their path.
 | `@lovrozagar/flare/lazy`                | `lazy`, `clientLazy`                    |
 | `@lovrozagar/flare/server`              | `createServer`                          |
 | `@lovrozagar/flare/server-context`      | ALS, `background`                       |
+| `@lovrozagar/flare/fetch-dedupe`        | `withFetchDedupe`                       |
 | `@lovrozagar/flare/server-only`         | `createServerOnlyFn`                    |
 | `@lovrozagar/flare/client-only`         | `createClientOnlyFn`                    |
 | `@lovrozagar/flare/isomorphic`          | `createIsomorphicFn`                    |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lovrozagar/flare",
-	"version": "0.7.0",
+	"version": "0.8.0",
 	"description": "Solid meta-framework. Server-driven, NDJSON streaming, renderToStream.",
 	"keywords": [
 		"flare",
@@ -34,6 +34,7 @@
 		"./codegen": "./src/codegen/index.ts",
 		"./direction": "./src/direction.ts",
 		"./errors": "./src/errors/index.ts",
+		"./fetch-dedupe": "./src/fetch-dedupe.ts",
 		"./fonts": "./src/fonts/index.ts",
 		"./fonts/*": "./src/fonts/*.ts",
 		"./form": "./src/form/index.tsx",

package/src/dedupe/fetch.ts

@@ -0,0 +1,404 @@
+import { getServerRequestContext } from "@lovrozagar/flare/server-context";
+
+export type FetchFn = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+const FETCH_CACHE_KEY = "__flare_fetch_dedupe";
+/** Bodies above this are streamed to their caller but never memoized. */
+export const DEFAULT_MAX_BYTES = 1024 * 1024;
+
+const SHAREABLE_METHODS = new Set(["GET", "HEAD"]);
+const NULL_BODY_STATUSES = new Set([204, 205, 304]);
+const EXCLUDED_HEADERS = new Set(["traceparent", "tracestate", "x-correlation-id", "x-request-id"]);
+
+function isRequest(input: RequestInfo | URL): input is Request {
+	return typeof input === "object" && !(input instanceof URL) && "method" in input && "url" in input;
+}
+
+function methodOf(input: RequestInfo | URL, init: RequestInit | undefined): string {
+	return (init?.method ?? (isRequest(input) ? input.method : "GET")).toUpperCase();
+}
+
+/* `new Request` normalizes the URL and header names the same way the runtime's fetch will. */
+function keyOf(scope: string, request: Request): string {
+	const headers: Array<[string, string]> = [];
+	request.headers.forEach((value, name) => {
+		if (!EXCLUDED_HEADERS.has(name)) headers.push([name, value]);
+	});
+	headers.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+	return JSON.stringify([
+		scope,
+		request.method,
+		request.url,
+		headers,
+		request.redirect,
+		request.cache,
+		request.credentials,
+		request.integrity,
+		request.mode,
+		request.referrer,
+		request.referrerPolicy,
+	]);
+}
+
+function requestCache(): Map<string, SharedFetch> | undefined {
+	try {
+		const ctx = getServerRequestContext();
+		let cache = ctx.get<Map<string, SharedFetch>>(FETCH_CACHE_KEY);
+		if (!cache) {
+			cache = new Map();
+			ctx.set(FETCH_CACHE_KEY, cache);
+		}
+		return cache;
+	} catch {
+		return undefined;
+	}
+}
+
+function isShareable(response: Response, maxBytes: number): boolean {
+	if (response.status < 200 || response.status > 599) return false;
+	const type = response.headers.get("content-type");
+	if (type && type.trim().toLowerCase().startsWith("text/event-stream")) return false;
+	const length = Number(response.headers.get("content-length") ?? Number.NaN);
+	return !(length > maxBytes);
+}
+
+interface Head {
+	headers: Headers;
+	redirected: boolean;
+	status: number;
+	statusText: string;
+	url: string;
+}
+
+function build(head: Head, body: ReadableStream<Uint8Array> | null): Response {
+	const response = new Response(body, { headers: head.headers, status: head.status, statusText: head.statusText });
+	/* Constructed responses have no url / redirected; keep the upstream values callers rely on. */
+	if (head.url) Object.defineProperty(response, "url", { value: head.url });
+	if (head.redirected) Object.defineProperty(response, "redirected", { value: true });
+	return response;
+}
+
+/** Errors the caller's body with its abort reason, as a native fetch body would. */
+function abortable(body: ReadableStream<Uint8Array>, signal: AbortSignal | undefined): ReadableStream<Uint8Array> {
+	if (!signal) return body;
+	const reader = body.getReader();
+	let finished = false;
+	let onAbort: (() => void) | undefined;
+	const finish = () => {
+		finished = true;
+		if (onAbort) signal.removeEventListener("abort", onAbort);
+	};
+	return new ReadableStream<Uint8Array>(
+		{
+			cancel(reason) {
+				finish();
+				return reader.cancel(reason);
+			},
+			async pull(controller) {
+				const { done, value } = await reader.read();
+				if (finished) return;
+				if (done) {
+					finish();
+					controller.close();
+					return;
+				}
+				controller.enqueue(value);
+			},
+			start(controller) {
+				onAbort = () => {
+					if (finished) return;
+					finish();
+					controller.error(signal.reason);
+					reader.cancel(signal.reason).catch(() => {});
+				};
+				signal.addEventListener("abort", onAbort, { once: true });
+			},
+		},
+		{ highWaterMark: 0 },
+	);
+}
+
+/**
+ * Reads one tee branch eagerly and replays it to every later caller. Past `maxBytes` the entry is
+ * evicted and, once no replay reader needs the rest, the branch is canceled so the first caller's
+ * branch keeps native backpressure. No branch is ever left unread.
+ */
+class Replay {
+	private chunks: Uint8Array[] = [];
+	private bytes = 0;
+	private done = false;
+	private failed = false;
+	private error: unknown;
+	private overflowed = false;
+	private readers = 0;
+	private wakers: Array<() => void> = [];
+
+	constructor(
+		source: ReadableStream<Uint8Array>,
+		private readonly maxBytes: number,
+		private readonly evict: () => void,
+	) {
+		void this.pump(source.getReader());
+	}
+
+	private notify(): void {
+		const wakers = this.wakers;
+		this.wakers = [];
+		for (const wake of wakers) wake();
+	}
+
+	private async pump(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<void> {
+		try {
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				this.bytes += value.byteLength;
+				if (this.bytes > this.maxBytes && !this.overflowed) {
+					this.overflowed = true;
+					this.evict();
+				}
+				if (this.overflowed && this.readers === 0) {
+					this.chunks = [];
+					await reader.cancel();
+					return;
+				}
+				this.chunks.push(value);
+				this.notify();
+			}
+			this.done = true;
+		} catch (e: unknown) {
+			this.failed = true;
+			this.error = e;
+			this.evict();
+		}
+		this.notify();
+	}
+
+	stream(signal: AbortSignal | undefined): ReadableStream<Uint8Array> {
+		this.readers++;
+		let index = 0;
+		let finished = false;
+		let onAbort: (() => void) | undefined;
+		const finish = () => {
+			if (finished) return;
+			finished = true;
+			this.readers--;
+			if (onAbort) signal?.removeEventListener("abort", onAbort);
+		};
+		return new ReadableStream<Uint8Array>(
+			{
+				cancel: finish,
+				pull: async (controller) => {
+					for (;;) {
+						if (finished) return;
+						const chunk = this.chunks[index];
+						if (chunk) {
+							index++;
+							/* Each caller owns its bytes; a consumer that detaches a buffer cannot corrupt another. */
+							controller.enqueue(new Uint8Array(chunk));
+							return;
+						}
+						if (this.failed) {
+							finish();
+							controller.error(this.error);
+							return;
+						}
+						if (this.done) {
+							finish();
+							controller.close();
+							return;
+						}
+						await new Promise<void>((resolve) => this.wakers.push(resolve));
+					}
+				},
+				start: (controller) => {
+					if (!signal) return;
+					onAbort = () => {
+						if (finished) return;
+						finish();
+						controller.error(signal.reason);
+						this.notify();
+					};
+					signal.addEventListener("abort", onAbort, { once: true });
+				},
+			},
+			{ highWaterMark: 0 },
+		);
+	}
+}
+
+interface Waiter {
+	reject: (reason: unknown) => void;
+	resolve: (response: Response | Promise<Response>) => void;
+	signal: AbortSignal | undefined;
+}
+
+/** One upstream fetch shared by every caller in the request with the same key. */
+class SharedFetch {
+	private readonly upstream = new AbortController();
+	private waiters: Waiter[] = [];
+	/** A caller without a signal can never abort, so the upstream fetch must run to completion. */
+	private pinned = false;
+	private head: Head | undefined;
+	private body: Replay | null | undefined;
+
+	constructor(
+		private readonly cache: Map<string, SharedFetch>,
+		private readonly key: string,
+		private readonly call: FetchFn,
+		private readonly input: RequestInfo | URL,
+		private readonly init: RequestInit | undefined,
+		private readonly maxBytes: number,
+	) {
+		Promise.resolve()
+			.then(() => call(input, { ...init, signal: this.upstream.signal }))
+			.then(
+				(response) => this.settle(response),
+				(error: unknown) => this.fail(error),
+			);
+	}
+
+	private evict(): void {
+		if (this.cache.get(this.key) === this) this.cache.delete(this.key);
+	}
+
+	join(signal: AbortSignal | undefined): Promise<Response> {
+		const head = this.head;
+		if (head) return Promise.resolve(build(head, this.body ? this.body.stream(signal) : null));
+		return new Promise<Response>((resolve, reject) => {
+			const waiter: Waiter = { reject, resolve, signal };
+			this.waiters.push(waiter);
+			if (!signal) {
+				this.pinned = true;
+				return;
+			}
+			signal.addEventListener(
+				"abort",
+				() => {
+					const index = this.waiters.indexOf(waiter);
+					if (index === -1) return;
+					this.waiters.splice(index, 1);
+					reject(signal.reason);
+					if (!this.pinned && this.waiters.length === 0) {
+						this.evict();
+						this.upstream.abort(signal.reason);
+					}
+				},
+				{ once: true },
+			);
+		});
+	}
+
+	private fail(error: unknown): void {
+		this.evict();
+		const waiters = this.waiters;
+		this.waiters = [];
+		for (const waiter of waiters) waiter.reject(error);
+	}
+
+	private settle(response: Response): void {
+		const waiters = this.waiters;
+		this.waiters = [];
+		const [first, ...rest] = waiters;
+		if (!first) {
+			this.evict();
+			response.body?.cancel().catch(() => {});
+			return;
+		}
+
+		if (!isShareable(response, this.maxBytes)) {
+			this.evict();
+			const signal = first.signal;
+			if (signal) signal.addEventListener("abort", () => this.upstream.abort(signal.reason), { once: true });
+			first.resolve(response);
+			for (const waiter of rest) {
+				waiter.resolve(this.call(this.input, { ...this.init, signal: waiter.signal }));
+			}
+			return;
+		}
+
+		const head: Head = {
+			headers: new Headers(response.headers),
+			redirected: response.redirected,
+			status: response.status,
+			statusText: response.statusText,
+			url: response.url,
+		};
+		const source = NULL_BODY_STATUSES.has(response.status) ? null : response.body;
+		if (!source) {
+			if (response.body) response.body.cancel().catch(() => {});
+			this.body = null;
+			this.head = head;
+			for (const waiter of waiters) waiter.resolve(build(head, null));
+			return;
+		}
+
+		const [own, shared] = source.tee();
+		this.body = new Replay(shared, this.maxBytes, () => this.evict());
+		this.head = head;
+		first.resolve(build(head, abortable(own, first.signal)));
+		for (const waiter of rest) waiter.resolve(build(head, this.body.stream(waiter.signal)));
+	}
+}
+
+/**
+ * Wraps `call` so GET and HEAD requests with the same key share one upstream fetch for the
+ * rest of the current server request. Other methods pass through and drop every memoized
+ * response. Outside a request (browser, module scope, background jobs) it is a plain passthrough.
+ */
+export function createDedupedFetch(call: FetchFn, scope: string, maxBytes = DEFAULT_MAX_BYTES): FetchFn {
+	return (input, init) => {
+		const cache = requestCache();
+		if (!cache) return call(input, init);
+		const method = methodOf(input, init);
+		if (!SHAREABLE_METHODS.has(method)) {
+			cache.clear();
+			return call(input, init);
+		}
+		const signal = init && "signal" in init ? (init.signal ?? undefined) : isRequest(input) ? input.signal : undefined;
+		if (signal?.aborted) return Promise.reject(signal.reason);
+
+		let key: string;
+		try {
+			key = keyOf(scope, new Request(input, init));
+		} catch {
+			/* Let the runtime's fetch report an invalid request the way it normally does. */
+			return call(input, init);
+		}
+		let entry = cache.get(key);
+		if (!entry) {
+			entry = new SharedFetch(cache, key, call, input, init, maxBytes);
+			cache.set(key, entry);
+		}
+		return entry.join(signal);
+	};
+}
+
+let originalFetch: typeof globalThis.fetch | undefined;
+let enableCount = 0;
+
+/**
+ * Reference-counted enable/disable to avoid race conditions
+ * when concurrent requests share the same isolate.
+ */
+export function enableFetchDedupe(): void {
+	enableCount++;
+	if (enableCount === 1) {
+		const base = globalThis.fetch;
+		originalFetch = base;
+		globalThis.fetch = createDedupedFetch((input, init) => base(input, init), "global") as typeof globalThis.fetch;
+	}
+}
+
+export function disableFetchDedupe(): void {
+	enableCount--;
+	if (enableCount <= 0) {
+		if (originalFetch) globalThis.fetch = originalFetch;
+		originalFetch = undefined;
+		enableCount = 0;
+	}
+}
+
+export function isFetchDedupeEnabled(): boolean {
+	return enableCount > 0;
+}

package/src/dedupe/index.ts

@@ -1,8 +1,6 @@
-import { warn } from "../logger.ts";
 import { getServerRequestContext } from "@lovrozagar/flare/server-context";
 
 const DEDUPE_CACHE_KEY = "__flare_dedupe";
-const FETCH_CACHE_KEY = "__flare_fetch_dedupe";
 
 let fnCounter = 0;
 
@@ -16,20 +14,6 @@ function getDedupeCache(): Map<string, Promise<unknown>> {
 	return cache;
 }
 
-function getFetchCache(): Map<string, Promise<Response>> | undefined {
-	try {
-		const ctx = getServerRequestContext();
-		let cache = ctx.get<Map<string, Promise<Response>>>(FETCH_CACHE_KEY);
-		if (!cache) {
-			cache = new Map();
-			ctx.set(FETCH_CACHE_KEY, cache);
-		}
-		return cache;
-	} catch {
-		return undefined;
-	}
-}
-
 export function dedupe<TArgs extends unknown[], TResult>(
 	fn: (...args: TArgs) => Promise<TResult>,
 ): (...args: TArgs) => Promise<TResult> {
@@ -47,105 +31,4 @@ export function dedupe<TArgs extends unknown[], TResult>(
 	};
 }
 
-const EXCLUDED_HEADERS = new Set(["traceparent", "tracestate", "x-request-id", "x-correlation-id"]);
-
-function getFetchCacheKey(input: RequestInfo | URL, init?: RequestInit): string | undefined {
-	let method = "GET";
-	let url: string;
-
-	if (input instanceof Request) {
-		method = input.method.toUpperCase();
-		url = input.url;
-	} else if (input instanceof URL) {
-		url = input.toString();
-	} else {
-		url = input;
-	}
-
-	if (init?.method) {
-		method = init.method.toUpperCase();
-	}
-
-	if (method !== "GET" && method !== "HEAD") {
-		return undefined;
-	}
-
-	let headersKey = "";
-	const headers = init?.headers ?? (input instanceof Request ? input.headers : undefined);
-	if (headers) {
-		const entries: Array<[string, string]> = [];
-		if (headers instanceof Headers) {
-			headers.forEach((v, k) => {
-				if (!EXCLUDED_HEADERS.has(k.toLowerCase())) {
-					entries.push([k.toLowerCase(), v]);
-				}
-			});
-		} else if (Array.isArray(headers)) {
-			for (const [k, v] of headers) {
-				if (!EXCLUDED_HEADERS.has(k.toLowerCase())) {
-					entries.push([k.toLowerCase(), v]);
-				}
-			}
-		} else {
-			for (const k of Object.keys(headers)) {
-				if (!EXCLUDED_HEADERS.has(k.toLowerCase())) {
-					entries.push([k.toLowerCase(), headers[k] as string]);
-				}
-			}
-		}
-		entries.sort((a, b) => a[0].localeCompare(b[0]));
-		headersKey = JSON.stringify(entries);
-	}
-
-	return `fetch:${method}:${url}:${headersKey}`;
-}
-
-let originalFetch: typeof globalThis.fetch | undefined;
-let enableCount = 0;
-
-function createDedupedFetch(baseFetch: typeof globalThis.fetch): typeof globalThis.fetch {
-	return async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
-		const key = getFetchCacheKey(input, init);
-		if (!key) return baseFetch(input, init);
-
-		const cache = getFetchCache();
-		if (!cache) return baseFetch(input, init);
-
-		const existing = cache.get(key);
-		if (existing) return (await existing).clone();
-
-		const promise = baseFetch(input, init);
-		cache.set(key, promise);
-		/* Clean up cache on rejection so retries within same request can succeed */
-		promise.catch((e: unknown) => {
-			warn("dedupe", "fetch failed, clearing cache", e);
-			cache.delete(key);
-		});
-		return (await promise).clone();
-	};
-}
-
-/**
- * Reference-counted enable/disable to avoid race conditions
- * when concurrent requests share the same isolate.
- */
-export function enableFetchDedupe(): void {
-	enableCount++;
-	if (enableCount === 1) {
-		originalFetch = globalThis.fetch;
-		globalThis.fetch = createDedupedFetch(originalFetch);
-	}
-}
-
-export function disableFetchDedupe(): void {
-	enableCount--;
-	if (enableCount <= 0) {
-		if (originalFetch) globalThis.fetch = originalFetch;
-		originalFetch = undefined;
-		enableCount = 0;
-	}
-}
-
-export function isFetchDedupeEnabled(): boolean {
-	return enableCount > 0;
-}
+export { disableFetchDedupe, enableFetchDedupe, isFetchDedupeEnabled } from "./fetch.ts";

package/src/fetch-dedupe.ts

@@ -0,0 +1,36 @@
+import { createDedupedFetch, DEFAULT_MAX_BYTES, type FetchFn } from "./dedupe/fetch.ts";
+
+/** A fetch function, or anything with a `fetch` method such as a Workers service binding. */
+export type FetchTarget = FetchFn | { fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> };
+
+export interface FetchDedupeOptions {
+	/** Largest body that is memoized for later callers. Larger bodies still stream. Default 1 MiB. */
+	maxBytes?: number;
+}
+
+const scopes = new WeakMap<object, string>();
+let scopeCounter = 0;
+
+function scopeOf(target: object): string {
+	let scope = scopes.get(target);
+	if (!scope) {
+		scopeCounter++;
+		scope = `target:${scopeCounter}`;
+		scopes.set(target, scope);
+	}
+	return scope;
+}
+
+/**
+ * Request-scoped GET / HEAD dedupe for a fetch that is not `globalThis.fetch`, such as an SDK
+ * over a service binding. Flare already dedupes `globalThis.fetch` during a request.
+ *
+ * Wrappers over the same target share one cache, so build the SDK per request and pass the
+ * binding itself (`withFetchDedupe(env.API)`), not a new arrow around it. Bindings are called
+ * as methods, so `this` stays intact.
+ */
+export function withFetchDedupe(target: FetchTarget, options?: FetchDedupeOptions): FetchFn {
+	const call: FetchFn =
+		typeof target === "function" ? (input, init) => target(input, init) : (input, init) => target.fetch(input, init);
+	return createDedupedFetch(call, scopeOf(target), options?.maxBytes ?? DEFAULT_MAX_BYTES);
+}

package/src/server/index.ts

@@ -54,7 +54,7 @@ export interface ServerBuilder<
 					callerData?: unknown[];
 					env: TEnv;
 					request: Request;
-					serverContext: Record<string, unknown>;
+					serverContext: TServerContext;
 					url: URL;
 				}) => TNewAuth | null | Promise<TNewAuth | null>,
 			) => ServerBuilder<TExcluded | "authenticateFn", TNewAuth, TServerContext, TEnv>;
@@ -72,12 +72,7 @@ export interface ServerBuilder<
 		: (
 				config:
 					| SecurityConfig
-					| ((ctx: {
-							env: TEnv;
-							nonce: string;
-							request: Request;
-							serverContext: Record<string, unknown>;
-					  }) => SecurityConfig),
+					| ((ctx: { env: TEnv; nonce: string; request: Request; serverContext: TServerContext }) => SecurityConfig),
 			) => ServerBuilder<TExcluded | "security", TAuth, TServerContext, TEnv>;
 	serverContext: "serverContext" extends TExcluded
 		? never

package/src/server-fn/index.ts

@@ -1,3 +1,4 @@
+import type { ResolvedAuth, ResolvedEnv, ResolvedServerContext } from "../route-builder/register.ts";
 import { FORM_FN_FIELD, parseServerFnPathname, serverFnPath } from "../protocol.ts";
 import { callServerFnOverHttp } from "./rpc.ts";
 import {
@@ -39,7 +40,8 @@ export interface PiggybackedQuery {
 	key: unknown[];
 }
 
-export interface HandlerContext<TAuth, TInput, TEnv = unknown> {
+/* TEnv defaults to the app's registered env (`createServer<Env>()`) */
+export interface HandlerContext<TAuth, TInput, TEnv = ResolvedEnv> {
 	auth: TAuth;
 	env: TEnv;
 	input: TInput;
@@ -56,15 +58,17 @@ export interface HandlerContext<TAuth, TInput, TEnv = unknown> {
 	piggyback: (key: unknown[], data: unknown) => void;
 	request: Request;
 	revalidate: RevalidateFn;
-	serverContext: Record<string, unknown>;
+	/* the app's `.serverContext()` result, typed through FlareRegister */
+	serverContext: ResolvedServerContext;
 }
 
-export interface StreamContext<TAuth, TInput, TEnv = unknown> {
+export interface StreamContext<TAuth, TInput, TEnv = ResolvedEnv> {
 	auth: TAuth;
 	env: TEnv;
 	input: TInput;
 	request: Request;
-	serverContext: Record<string, unknown>;
+	/* the app's `.serverContext()` result, typed through FlareRegister */
+	serverContext: ResolvedServerContext;
 	signal: AbortSignal;
 }
 
@@ -78,12 +82,12 @@ export interface ServerFnRegistrationBase {
 }
 
 export interface ServerFnHandlerRegistration extends ServerFnRegistrationBase {
-	fn: (ctx: HandlerContext<unknown, unknown>) => unknown | Promise<unknown>;
+	fn: (ctx: HandlerContext<unknown, unknown, unknown>) => unknown | Promise<unknown>;
 	stream?: false;
 }
 
 export interface ServerFnStreamRegistration extends ServerFnRegistrationBase {
-	fn: (ctx: StreamContext<unknown, unknown>) => AsyncGenerator<unknown>;
+	fn: (ctx: StreamContext<unknown, unknown, unknown>) => AsyncGenerator<unknown>;
 	stream: true;
 }
 
@@ -99,22 +103,24 @@ interface BuilderState {
 	name: string;
 }
 
-interface ServerFnBuilderTerminal<TAuth, TInput, TOutput> {
-	handler(fn: (ctx: HandlerContext<TAuth, TInput>) => TOutput | Promise<TOutput>): ServerFn<TInput, TOutput>;
-	input<T>(validator: Validator<T>): ServerFnBuilderTerminal<TAuth, T, TOutput>;
+interface ServerFnBuilderTerminal<TAuth, TInput> {
+	/* the output type is the handler's: callers get it without restating it */
+	handler<TOutput>(fn: (ctx: HandlerContext<TAuth, TInput>) => TOutput | Promise<TOutput>): ServerFn<TInput, TOutput>;
+	input<T>(validator: Validator<T>): ServerFnBuilderTerminal<TAuth, T>;
 	stream<TChunk>(fn: (ctx: StreamContext<TAuth, TInput>) => AsyncGenerator<TChunk>): StreamFn<TInput, TChunk>;
 }
 
-interface ServerFnBuilderAfterAuth<TAuth, TInput, TOutput> extends ServerFnBuilderTerminal<TAuth, TInput, TOutput> {
+interface ServerFnBuilderAfterAuth<TAuth, TInput> extends ServerFnBuilderTerminal<TAuth, TInput> {
 	authorize(
 		fn: (ctx: { auth: TAuth; input: TInput }) => boolean | Promise<boolean>,
-	): ServerFnBuilderTerminal<TAuth, TInput, TOutput>;
-	input<T>(validator: Validator<T>): ServerFnBuilderAfterAuth<TAuth, T, TOutput>;
+	): ServerFnBuilderTerminal<TAuth, TInput>;
+	input<T>(validator: Validator<T>): ServerFnBuilderAfterAuth<TAuth, T>;
 }
 
-interface ServerFnBuilder<TAuth, TInput, TOutput> extends ServerFnBuilderAfterAuth<TAuth, TInput, TOutput> {
-	authenticate(): ServerFnBuilderAfterAuth<unknown, TInput, TOutput>;
-	input<T>(validator: Validator<T>): ServerFnBuilder<TAuth, T, TOutput>;
+interface ServerFnBuilder<TAuth, TInput> extends ServerFnBuilderAfterAuth<TAuth, TInput> {
+	/* the app's `authenticateFn` result, typed through FlareRegister */
+	authenticate(): ServerFnBuilderAfterAuth<ResolvedAuth<true>, TInput>;
+	input<T>(validator: Validator<T>): ServerFnBuilder<TAuth, T>;
 }
 
 export type ServerFn<_TInput, TOutput> = ((_input: _TInput) => Promise<TOutput>) & {
@@ -128,15 +134,13 @@ export type StreamFn<_TInput, TChunk> = ((
 	_registration?: ServerFnRegistration;
 };
 
-function createBuilderTerminal<TAuth, TInput, TOutput>(
-	state: BuilderState,
-): ServerFnBuilderTerminal<TAuth, TInput, TOutput> {
+function createBuilderTerminal<TAuth, TInput>(state: BuilderState): ServerFnBuilderTerminal<TAuth, TInput> {
 	return {
-		handler(fn) {
+		handler<TOutput>(fn: (ctx: HandlerContext<TAuth, TInput>) => TOutput | Promise<TOutput>) {
 			const registration: ServerFnHandlerRegistration = {
 				authenticate: state.authenticate,
 				authorizeFn: state.authorizeFn,
-				fn: fn as (ctx: HandlerContext<unknown, unknown>) => unknown | Promise<unknown>,
+				fn: fn as (ctx: HandlerContext<unknown, unknown, unknown>) => unknown | Promise<unknown>,
 				id: state.__id && state.__id.length > 0 ? state.__id : state.name,
 				input: state.input,
 				method: state.method,
@@ -168,7 +172,8 @@ function createBuilderTerminal<TAuth, TInput, TOutput>(
 				};
 				return await fn({
 					auth: null as TAuth,
-					env: {},
+					/* direct server-side invocation runs outside a request: there are no bindings */
+					env: {} as ResolvedEnv,
 					input: validated,
 					piggyback: () => {},
 					request: new Request("http://localhost"),
@@ -180,7 +185,7 @@ function createBuilderTerminal<TAuth, TInput, TOutput>(
 			return serverFn;
 		},
 		input<T>(validator: Validator<T>) {
-			return createBuilderTerminal<TAuth, T, TOutput>({
+			return createBuilderTerminal<TAuth, T>({
 				...state,
 				input: validator as Validator<unknown>,
 			});
@@ -189,7 +194,7 @@ function createBuilderTerminal<TAuth, TInput, TOutput>(
 			const registration: ServerFnStreamRegistration = {
 				authenticate: state.authenticate,
 				authorizeFn: state.authorizeFn,
-				fn: fn as (ctx: StreamContext<unknown, unknown>) => AsyncGenerator<unknown>,
+				fn: fn as (ctx: StreamContext<unknown, unknown, unknown>) => AsyncGenerator<unknown>,
 				id: state.__id && state.__id.length > 0 ? state.__id : state.name,
 				input: state.input,
 				method: state.method,
@@ -218,7 +223,7 @@ function createBuilderTerminal<TAuth, TInput, TOutput>(
 									const validated = (await validatedPromise) as TInput;
 									generator = fn({
 										auth: null as TAuth,
-										env: {} as unknown,
+										env: {} as ResolvedEnv,
 										input: validated,
 										request: new Request("http://localhost"),
 										serverContext: getServerContext(),
@@ -243,19 +248,17 @@ function createBuilderTerminal<TAuth, TInput, TOutput>(
 	};
 }
 
-function createBuilderAfterAuth<TAuth, TInput, TOutput>(
-	state: BuilderState,
-): ServerFnBuilderAfterAuth<TAuth, TInput, TOutput> {
+function createBuilderAfterAuth<TAuth, TInput>(state: BuilderState): ServerFnBuilderAfterAuth<TAuth, TInput> {
 	return {
-		...createBuilderTerminal<TAuth, TInput, TOutput>(state),
+		...createBuilderTerminal<TAuth, TInput>(state),
 		authorize(fn) {
-			return createBuilderTerminal<TAuth, TInput, TOutput>({
+			return createBuilderTerminal<TAuth, TInput>({
 				...state,
 				authorizeFn: fn as (ctx: { auth: unknown; input: unknown }) => boolean | Promise<boolean>,
 			});
 		},
 		input<T>(validator: Validator<T>) {
-			return createBuilderAfterAuth<TAuth, T, TOutput>({
+			return createBuilderAfterAuth<TAuth, T>({
 				...state,
 				input: validator as Validator<unknown>,
 			});
@@ -263,17 +266,17 @@ function createBuilderAfterAuth<TAuth, TInput, TOutput>(
 	};
 }
 
-function createBuilder<TAuth, TInput, TOutput>(state: BuilderState): ServerFnBuilder<TAuth, TInput, TOutput> {
+function createBuilder<TAuth, TInput>(state: BuilderState): ServerFnBuilder<TAuth, TInput> {
 	return {
-		...createBuilderAfterAuth<TAuth, TInput, TOutput>(state),
+		...createBuilderAfterAuth<TAuth, TInput>(state),
 		authenticate() {
-			return createBuilderAfterAuth<unknown, TInput, TOutput>({
+			return createBuilderAfterAuth<ResolvedAuth<true>, TInput>({
 				...state,
 				authenticate: true,
 			});
 		},
 		input<T>(validator: Validator<T>) {
-			return createBuilder<TAuth, T, TOutput>({
+			return createBuilder<TAuth, T>({
 				...state,
 				input: validator as Validator<unknown>,
 			});
@@ -281,8 +284,8 @@ function createBuilder<TAuth, TInput, TOutput>(state: BuilderState): ServerFnBui
 	};
 }
 
-export function createServerFn(config: ServerFnConfig): ServerFnBuilder<null, void, unknown> {
-	return createBuilder<null, void, unknown>({
+export function createServerFn(config: ServerFnConfig): ServerFnBuilder<null, void> {
+	return createBuilder<null, void>({
 		__client: config.__client,
 		__id: config.__id,
 		authenticate: false,