@selvajs/server 0.2.0-beta.1

package/src/compute/client-cache.ts

@@ -0,0 +1,278 @@
+import {
+	GrasshopperClient,
+	enableDebugLogging,
+	type GrasshopperComputeConfig,
+	type SolveScheduler
+} from '@selvajs/compute';
+
+// ============================================================================
+// Shared compute client cache
+// ============================================================================
+//
+// One warm `GrasshopperClient` (+ its `SolveScheduler`) per distinct compute
+// server, keyed by the server's **`id`** (ADR 0004 — a server's identity is its
+// `id`, never its URL). Definitions can pin different servers (the app's
+// `resolveServerForOrg` honors a per-definition pin → org default → global
+// default), so this is deliberately a per-server LRU, NOT a single shared
+// client — two definitions on two servers keep two warm clients; a churn of
+// one-off servers is bounded by `maxCachedClients`.
+//
+// Both hot paths share this cache:
+//   - the solve endpoint uses the entry's `scheduler`;
+//   - the definition-viewer render path uses the entry's `client` for `getIO`.
+// Sharing means a definition that was just solved renders from the same warm
+// client (and vice-versa) instead of re-handshaking Rhino.Compute per page load.
+//
+// Staleness: keyed on `id`, a rotated URL/apiKey keeps the SAME key with stale
+// connection details — so the config-write path MUST call `evict(id)` when a
+// server's config changes (ADR 0004 Consequences). That replaces the old
+// implicit "new key → LRU age-out" staleness the URL-keyed cache relied on.
+
+/**
+ * Opaque identity of a compute server. Callers never construct the branded
+ * string directly — they pass a resolved server config to `serverIdentity()`.
+ * Keeping this opaque from day one (ADR 0004 D1) means "a server is now a pool
+ * of URLs behind one id" stays an additive, non-breaking change.
+ */
+export type ServerIdentity = string & { readonly __brand: 'ServerIdentity' };
+
+/** Minimal resolved-server shape the cache needs (a subset of the app's `ComputeServerConfig`). */
+export interface ResolvedServer {
+	/** Stable identity — the cache key. */
+	id: string;
+	/** Base URL of the Rhino.Compute instance (a resolution detail of `id`). */
+	serverUrl: string;
+	/** Sent as `RhinoComputeKey`. */
+	apiKey?: string;
+}
+
+/** Derive the opaque cache identity from a resolved server. Identity is the `id`. */
+export function serverIdentity(server: Pick<ResolvedServer, 'id'>): ServerIdentity {
+	return server.id as ServerIdentity;
+}
+
+/**
+ * Per-request telemetry holders read by the caller right after a solve resolves
+ * to build a Server-Timing header. Populated by the client/scheduler callbacks.
+ */
+export interface CachedClient {
+	client: GrasshopperClient;
+	scheduler: SolveScheduler;
+	/**
+	 * Last decode/solve/encode reported by the compute server (Server-Timing).
+	 * Written by onServerTiming, read right after scheduler.solve resolves to split
+	 * the solve wall time into on-compute-server work vs. the compute↔web-server
+	 * link. Queue-mode schedulers serialize solves, so this correlates with the
+	 * request that just resolved; a Selva-cache hit leaves it null (no compute
+	 * call). Debug aid — a concurrent burst may misattribute one request's timing.
+	 */
+	rhinoTiming: { last: { decode: number; solve: number; encode: number } | null };
+	/**
+	 * Last solve's cache verdicts from the scheduler's onSettle: whether the
+	 * in-process response cache served it (no compute call) and whether the
+	 * definition had to be re-uploaded. Same read-after-solve pattern and
+	 * concurrency caveat as rhinoTiming.
+	 */
+	solveMeta: { last: { fromCache: boolean; definitionReuploaded?: boolean } | null };
+}
+
+/**
+ * Config injected by the consuming app. Everything that used to be read from
+ * `$env` / `computeLimits` in the app module is passed in, so this module stays
+ * env-agnostic and testable.
+ */
+export interface ClientCacheConfig {
+	/** Per-solve timeout forwarded to the scheduler (`ComputeLimits.maxSolveDurationMs`). */
+	maxSolveDurationMs: number;
+	/** Ask Rhino.Compute to cache solve results and return them on identical repeats. */
+	cachesolve: boolean;
+	/** Also cache solves that reported GH errors (only meaningful with `cachesolve`). */
+	cacheerroredsolves: boolean;
+	/** Reference large definitions by server cache key (pointer) instead of re-uploading. */
+	reuseServerDefinitionCache: boolean;
+	/** Concise cache/timing logs. When false, `onDebugLog` is never invoked. */
+	debug: boolean;
+	/** VERBOSE lib-level logging (full solve request/response incl. geometry). */
+	debugVerbose: boolean;
+	/** Max distinct warm clients before the LRU evicts the oldest. Default 16. */
+	maxCachedClients?: number;
+	/** Sink for the concise debug lines (the app wires `console.log`). */
+	onDebugLog?: (message: string) => void;
+}
+
+export interface ClientCache {
+	/**
+	 * Get (or create) the warm client + scheduler for a resolved compute server,
+	 * keyed by its `id`. `definitionGuid`, when present, is stamped as the
+	 * `X-Selva-Definition` header on this client's outbound solve/IO requests —
+	 * inert routing/telemetry metadata until a pool router exists (ADR 0004 D2).
+	 */
+	getClient(server: ResolvedServer, opts?: { definitionGuid?: string }): Promise<CachedClient>;
+	/**
+	 * Dispose and drop the warm client for `id` (or a `ServerIdentity`). Called by
+	 * the config-write path when a server's URL/key rotates so the next request
+	 * rebuilds against fresh connection details (ADR 0004 Consequences).
+	 */
+	evict(id: string | ServerIdentity): void;
+	/** Dispose every warm client. Test seam / shutdown hook. */
+	disposeAll(): void;
+}
+
+const DEFAULT_MAX_CACHED_CLIENTS = 16;
+
+/**
+ * Build a per-server warm-client cache. Each cache owns its own LRU `Map` keyed
+ * on server `id`.
+ */
+export function createClientCache(config: ClientCacheConfig): ClientCache {
+	const maxCachedClients = config.maxCachedClients ?? DEFAULT_MAX_CACHED_CLIENTS;
+	const cache = new Map<string, CachedClient>();
+
+	if (config.debugVerbose) enableDebugLogging();
+
+	const debugLog = (message: string) => {
+		if (config.debug) config.onDebugLog?.(message);
+	};
+
+	async function build(server: ResolvedServer, definitionGuid?: string): Promise<CachedClient> {
+		// Holders for per-request results from the client/scheduler callbacks; the
+		// caller reads them right after each solve resolves to build Server-Timing.
+		const rhinoTiming: CachedClient['rhinoTiming'] = { last: null };
+		const solveMeta: CachedClient['solveMeta'] = { last: null };
+
+		const clientConfig: GrasshopperComputeConfig = {
+			serverUrl: server.serverUrl,
+			apiKey: server.apiKey,
+			// Lib-level debug is the verbose one (full payload logs); keep it on the
+			// verbose flag so the concise cache logs can run without the noise.
+			debug: config.debugVerbose,
+			// Ask Rhino.Compute to cache solve results and return them on identical
+			// repeats (same definition + inputs), skipping the solve.
+			cachesolve: config.cachesolve,
+			// Opt-in: also cache solves that reported GH errors.
+			cacheerroredsolves: config.cacheerroredsolves,
+			// DEBUG: the server's per-request timing breakdown, which exposes the two
+			// SERVER-side caches at once — definition cache (pointer reuse) via
+			// `decode`, solve cache (cachesolve) via `solve`. Flagged below so the
+			// contrast is obvious in the logs.
+			onServerTiming: (t) => {
+				const decode = t.decode ?? 0;
+				const solve = t.solve ?? 0;
+				const encode = t.encode ?? 0;
+				// Always recorded (cheap): the caller reads this after scheduler.solve.
+				rhinoTiming.last = { decode, solve, encode };
+				if (!config.debug) return;
+				// Heuristic thresholds: a genuine parse/solve is many ms; a cache hit
+				// is sub-millisecond. Only meaningful relative to the first (cold) solve.
+				const defCache =
+					decode <= 1 ? 'HIT (definition reused, no re-upload/parse)' : 'miss (full parse)';
+				const solveCache =
+					config.cachesolve && solve <= 1
+						? 'HIT (cached result, solve skipped)'
+						: config.cachesolve
+							? 'miss (solved fresh)'
+							: 'off';
+				debugLog(
+					`[Compute/rhino-cache] decode=${decode}ms solve=${solve}ms encode=${encode}ms ` +
+						`| definition-cache: ${defCache} | solve-cache (cachesolve): ${solveCache}`
+				);
+			}
+		};
+
+		// `X-Selva-Definition` on the wire (ADR 0004 D2). Baked at client-create
+		// time because the scheduler has no per-request header hook — inert for a
+		// single-member "pool", useful in compute-side access logs immediately.
+		if (definitionGuid) {
+			clientConfig.headers = { 'X-Selva-Definition': definitionGuid };
+		}
+
+		const client = await GrasshopperClient.create(clientConfig);
+		const scheduler = client.createScheduler({
+			mode: 'queue',
+			timeoutMs: config.maxSolveDurationMs,
+			cache: { maxEntries: 20, ttlMs: 5 * 60_000 },
+			// Solve large definitions by server cache-key (pointer) instead of
+			// re-uploading the full binary every solve. On a stale-pointer miss the
+			// client transparently re-uploads.
+			reuseServerDefinitionCache: config.reuseServerDefinitionCache,
+			// DEBUG: observe the in-process response cache. `fromCache === true` means
+			// this solve was served from the app's own cache — Rhino.Compute was never
+			// called. `false` means it went to the compute server.
+			onSettle: (_ctx, result) => {
+				if (result.status !== 'success') return;
+				// Always recorded (cheap): the caller surfaces these on Server-Timing.
+				solveMeta.last = {
+					fromCache: result.fromCache === true,
+					definitionReuploaded: result.definitionReuploaded
+				};
+				if (!config.debug) return;
+				debugLog(
+					`[Compute/selva-cache] ${result.fromCache ? 'HIT  — served from cache (no compute call)' : 'miss — went to Rhino.Compute'} (${Math.round(result.durationMs)}ms)`
+				);
+				// Definition-cache verdict for a real compute call (not a cache HIT).
+				if (!result.fromCache) {
+					debugLog(
+						result.definitionReuploaded === true
+							? '[Compute/def-cache] miss — definition RE-UPLOADED (pointer was cold/stale)'
+							: result.definitionReuploaded === false
+								? '[Compute/def-cache] HIT  — definition reused from server cache (no upload)'
+								: '[Compute/def-cache] n/a — reuse disabled or non-reusable definition'
+					);
+				}
+				// Surface real GH errors when present. An errored solve is NEVER cached
+				// server-side (cachesolve only stores error-free solves).
+				if (!result.fromCache) {
+					const errs = (result.response as { errors?: unknown[] })?.errors;
+					const errCount = Array.isArray(errs) ? errs.length : 0;
+					if (errCount > 0) {
+						debugLog(
+							`[Compute/rhino-cache] ${errCount} GH error(s); not cacheable until fixed. First: ${JSON.stringify((errs as unknown[])[0])}`
+						);
+					}
+				}
+			}
+		});
+		return { client, scheduler, rhinoTiming, solveMeta };
+	}
+
+	return {
+		async getClient(server, opts): Promise<CachedClient> {
+			const key = server.id;
+			const existing = cache.get(key);
+			if (existing) {
+				// Refresh LRU position.
+				cache.delete(key);
+				cache.set(key, existing);
+				return existing;
+			}
+
+			const entry = await build(server, opts?.definitionGuid);
+
+			// Evict the least-recently-used entry before inserting when at capacity.
+			if (cache.size >= maxCachedClients) {
+				const oldestKey = cache.keys().next().value;
+				if (oldestKey !== undefined) {
+					cache.get(oldestKey)?.scheduler.dispose();
+					cache.delete(oldestKey);
+				}
+			}
+
+			cache.set(key, entry);
+			return entry;
+		},
+
+		evict(id): void {
+			const key = id as string;
+			const entry = cache.get(key);
+			if (entry) {
+				entry.scheduler.dispose();
+				cache.delete(key);
+			}
+		},
+
+		disposeAll(): void {
+			for (const entry of cache.values()) entry.scheduler.dispose();
+			cache.clear();
+		}
+	};
+}

package/src/compute/index.ts

@@ -0,0 +1,48 @@
+// Compute/solve server building blocks — transport-agnostic, env-injected.
+
+export {
+	resolveComputeLimits,
+	readPositiveInt,
+	readBool,
+	type ComputeLimits,
+	type EnvRecord
+} from './limits.js';
+
+export {
+	createComputeRateLimiter,
+	type ComputeRateLimiter,
+	type ComputeRateLimiterConfig,
+	type RateLimitResult
+} from './rate-limit.js';
+
+export { isSafeRemoteDefinitionUrl, assertSafeRemoteDefinitionUrl } from './safe-url.js';
+
+export { transformInputParameter } from './transform-input.js';
+
+export {
+	createClientCache,
+	serverIdentity,
+	type ClientCache,
+	type ClientCacheConfig,
+	type CachedClient,
+	type ResolvedServer,
+	type ServerIdentity
+} from './client-cache.js';
+
+export {
+	createRemoteDefinitionFetcher,
+	readBodyWithCap,
+	type RemoteDefinitionFetcher,
+	type RemoteDefinitionConfig
+} from './remote-definition.js';
+
+export {
+	runSolvePipeline,
+	COMPUTE_CONTRACT_VERSION,
+	COMPUTE_VERSION_HEADER,
+	type SolvePipelineArgs,
+	type SolveOutcome,
+	type SolveEnvelope,
+	type SolvePhaseMetrics,
+	type PipelineInput
+} from './solve-pipeline.js';

package/src/compute/limits.ts

@@ -0,0 +1,147 @@
+/**
+ * Compute/solve server limits, resolved from an injected env map.
+ *
+ * This is the transport- and framework-agnostic core: it takes a plain
+ * `Record<string, string | undefined>` (the caller passes SvelteKit's
+ * `$env/dynamic/private`, `process.env`, or any config source) and returns a
+ * fully-resolved `ComputeLimits` object. No ambient `$env` / `process.env`
+ * read happens here, so the module is importable from any runtime and testable
+ * without env plumbing.
+ *
+ * Every knob is env-overridable so deployments can tune without code changes;
+ * the defaults are sized for typical interactive use (sliders + small uploads).
+ * Centralizing them surfaces the tradeoffs (raise the rate cap → also consider
+ * the body cap) at one glance.
+ *
+ * Client-side counterparts (the in-flight compute throttle and slider debounce)
+ * live in `@selvajs/ui` and are bundled into the client, so they can't read
+ * env — they carry their own defaults.
+ */
+
+const MB = 1024 * 1024;
+
+/** Env source: any string→string map. `$env/dynamic/private` satisfies this. */
+export type EnvRecord = Record<string, string | undefined>;
+
+/**
+ * Parse a positive integer env value. Returns `fallback` when absent, and warns
+ * + falls back when present but not a finite positive number.
+ */
+export function readPositiveInt(env: EnvRecord, name: string, fallback: number): number {
+	const raw = env[name];
+	if (!raw) return fallback;
+	const parsed = Number(raw);
+	if (!Number.isFinite(parsed) || parsed <= 0) {
+		console.warn(`[selva] Invalid ${name}=${raw}, falling back to ${fallback}`);
+		return fallback;
+	}
+	return Math.floor(parsed);
+}
+
+/**
+ * Parse a boolean env flag. Accepts `true/1/yes/on` (case-insensitive) as true
+ * and `false/0/no/off` as false; any other / absent value falls back.
+ */
+export function readBool(env: EnvRecord, name: string, fallback: boolean): boolean {
+	const raw = env[name];
+	if (raw == null || raw === '') return fallback;
+	const v = raw.trim().toLowerCase();
+	if (v === 'true' || v === '1' || v === 'yes' || v === 'on') return true;
+	if (v === 'false' || v === '0' || v === 'no' || v === 'off') return false;
+	console.warn(`[selva] Invalid ${name}=${raw}, falling back to ${fallback}`);
+	return fallback;
+}
+
+/** Fully-resolved server-side compute limits. */
+export interface ComputeLimits {
+	/**
+	 * Longest the app waits for one solve. Enforced by the SolveScheduler
+	 * (`@selvajs/compute`), which propagates AbortSignal into the upstream
+	 * Compute call — a timeout actually cancels the work. Forwarded to the
+	 * client to drive the in-browser AbortController.
+	 *
+	 * Caveat: bounds only the parts of the stack we own. A reverse proxy or
+	 * serverless platform cap may shoot the request sooner; bumping past those
+	 * caps produces 502s, not longer solves.
+	 */
+	maxSolveDurationMs: number;
+	/** Fixed-window cap on /api/compute: window length + max requests per window. */
+	rateLimitWindowMs: number;
+	rateLimitMaxRequests: number;
+	/**
+	 * Largest .gh definition accepted on upload AND the largest remote definition
+	 * fetched for compute — kept in lockstep so a remote URL can't smuggle a file
+	 * past the upload cap.
+	 */
+	maxGhFileSize: number;
+	maxImageFileSize: number;
+	/**
+	 * /api/compute JSON *request* body cap (inputs + values, not the .gh). A
+	 * `file`-widget input embeds geometry as base64 in `values`; must stay <=
+	 * the adapter-node global BODY_SIZE_LIMIT or the global backstop rejects first.
+	 */
+	computeRequestMaxBytes: number;
+	/**
+	 * /api/compute JSON *response* cap. A `file`-typed output is base64-embedded
+	 * in the response; guards V8's ~512 MB single-string wall (a `JSON.stringify`
+	 * `RangeError`) and browser-tab OOM. Defensive backstop → clear 413 instead of
+	 * an opaque crash (real fix is out-of-band streaming, ADR 0003).
+	 */
+	computeResponseMaxBytes: number;
+	/** Hard cap on fetching a remote definition — tracks `maxGhFileSize`. */
+	remoteDefinitionMaxBytes: number;
+	/** Deadline on fetching a remote definition (slow-loris protection). */
+	remoteDefinitionFetchTimeoutMs: number;
+	/** In-process cache TTL for remote-fetched .gh bytes. */
+	definitionCacheTtlMs: number;
+	/**
+	 * Reuse the server's cached definition via a pointer instead of re-uploading
+	 * the binary each solve. SAFE only on a compute server that signals a
+	 * stale-pointer miss (VektorNode fork / a fork that throws) — a server that
+	 * returns an empty 200 would silently yield EMPTY geometry. Off for unknown
+	 * / standard rhino.compute.
+	 */
+	computeReuseDefinitionCache: boolean;
+	/**
+	 * Ask Rhino.Compute to cache solve RESULTS keyed on the full request and
+	 * return a cached result on an identical repeat. Server-wide (survives Selva
+	 * restarts, spans instances). Only helps IDENTICAL re-solves.
+	 */
+	computeServerCachesolve: boolean;
+	/**
+	 * Also cache solves that reported Grasshopper errors — correct for
+	 * error-by-design definitions (guarded Python, pruned branches) that still
+	 * produce valid geometry. Requires `computeServerCachesolve` and a server
+	 * honoring the flag. Conservative default off.
+	 */
+	computeCacheErroredSolves: boolean;
+}
+
+/**
+ * Resolve every server-side compute limit from an env map. Pure: the same env
+ * always yields the same limits, and nothing is read ambiently. The app calls
+ * this once at its composition root with `$env/dynamic/private`.
+ */
+export function resolveComputeLimits(env: EnvRecord): ComputeLimits {
+	const maxGhFileSize = readPositiveInt(env, 'MAX_GH_FILE_SIZE_BYTES', 300 * MB);
+	return {
+		maxSolveDurationMs: readPositiveInt(env, 'MAX_SOLVE_DURATION_MS', 100_000),
+		rateLimitWindowMs: readPositiveInt(env, 'COMPUTE_RATE_LIMIT_WINDOW_MS', 100_000),
+		rateLimitMaxRequests: readPositiveInt(env, 'COMPUTE_RATE_LIMIT_MAX', 120),
+		maxGhFileSize,
+		maxImageFileSize: readPositiveInt(env, 'MAX_IMAGE_FILE_SIZE_BYTES', 10 * MB),
+		computeRequestMaxBytes: readPositiveInt(env, 'COMPUTE_REQUEST_MAX_BYTES', 300 * MB),
+		computeResponseMaxBytes: readPositiveInt(env, 'COMPUTE_RESPONSE_MAX_BYTES', 300 * MB),
+		// Tracks the upload cap so a remote URL can't smuggle a larger file.
+		remoteDefinitionMaxBytes: maxGhFileSize,
+		remoteDefinitionFetchTimeoutMs: readPositiveInt(
+			env,
+			'REMOTE_DEFINITION_FETCH_TIMEOUT_MS',
+			30_000
+		),
+		definitionCacheTtlMs: readPositiveInt(env, 'DEFINITION_CACHE_TTL_MS', 5 * 60 * 1000),
+		computeReuseDefinitionCache: readBool(env, 'COMPUTE_REUSE_DEFINITION_CACHE', true),
+		computeServerCachesolve: readBool(env, 'COMPUTE_SERVER_CACHESOLVE', true),
+		computeCacheErroredSolves: readBool(env, 'COMPUTE_CACHE_ERRORED_SOLVES', false)
+	};
+}

package/src/compute/rate-limit.ts

@@ -0,0 +1,83 @@
+/**
+ * Per-key fixed-window rate limiter for the compute-solve endpoint. Compute
+ * solves are the one expensive endpoint in a Selva-engine app — without a cap a
+ * single authenticated user (or share-link consumer) can burn through compute
+ * budget far faster than any other surface allows.
+ *
+ * Design:
+ *  - Process-local `Map`. Multi-instance deployments see N× the per-key rate —
+ *    acceptable as a first line; a distributed limiter is a follow-up. The state
+ *    lives behind this factory so a shared-store implementation can slot in
+ *    later without changing the call sites.
+ *  - Fixed window (vs sliding) — simpler, no per-request bookkeeping; the
+ *    "burst at window edges" mode is fine here (share-link `maxSolves` and
+ *    per-user auth already prevent unbounded abuse — this flattens short spikes).
+ *  - Keyed by caller — the app passes `user:{userId}` for authenticated solves,
+ *    `share:{linkId}` for share-token solves, so anonymous consumers of one link
+ *    don't share a bucket with the link's owner.
+ *
+ * The window + cap are injected (they live in `ComputeLimits`), so this module
+ * reads no env of its own.
+ */
+
+export interface RateLimitResult {
+	allowed: boolean;
+	/** Seconds until the bucket resets, when not allowed. */
+	retryAfter?: number;
+}
+
+export interface ComputeRateLimiterConfig {
+	/** Fixed-window length in ms. */
+	windowMs: number;
+	/** Max requests admitted per key per window. */
+	maxPerWindow: number;
+}
+
+export interface ComputeRateLimiter {
+	/**
+	 * Check + record one request against `key`. Increments the counter on allow.
+	 * Returns `{ allowed: false, retryAfter }` once the bucket is full.
+	 */
+	check(key: string): RateLimitResult;
+	/** Test seam — wipes in-memory state. Production code never calls this. */
+	reset(): void;
+	/** The resolved config, exposed for time-based test assertions. */
+	readonly config: Readonly<ComputeRateLimiterConfig>;
+}
+
+interface BucketEntry {
+	count: number;
+	resetAt: number;
+}
+
+/**
+ * Build a process-local fixed-window rate limiter. Each limiter owns its own
+ * bucket `Map`, so distinct endpoints/keys-spaces don't collide.
+ */
+export function createComputeRateLimiter(config: ComputeRateLimiterConfig): ComputeRateLimiter {
+	const { windowMs, maxPerWindow } = config;
+	const buckets = new Map<string, BucketEntry>();
+
+	return {
+		config,
+		check(key: string): RateLimitResult {
+			const now = Date.now();
+			const entry = buckets.get(key);
+
+			if (!entry || now > entry.resetAt) {
+				buckets.set(key, { count: 1, resetAt: now + windowMs });
+				return { allowed: true };
+			}
+
+			if (entry.count >= maxPerWindow) {
+				return { allowed: false, retryAfter: Math.ceil((entry.resetAt - now) / 1000) };
+			}
+
+			entry.count += 1;
+			return { allowed: true };
+		},
+		reset(): void {
+			buckets.clear();
+		}
+	};
+}