@selvajs/solve 1.3.0-beta.3 → 2.0.0-beta.11

package/dist/server.js

@@ -1,2 +1,750 @@
-import{GrasshopperClient as e,TreeBuilder as t,isDefinitionRef as n,processInput as r,stableStringify as i}from"@selvajs/compute/grasshopper";import{ComputeError as a,ErrorCodes as o,enableDebugLogging as s,isDefinitionRef as c}from"@selvajs/compute/core";import{gunzipSync as l,gzip as u}from"node:zlib";import{promisify as d}from"node:util";import{NoopLogger as f}from"@selvajs/platform";function p(e,t){let n={id:e.id,name:e.nickname,nickname:e.nickname||null,description:e.description||``,paramType:e.paramType===`dynamicValueList`?`valueList`:e.paramType,treeAccess:e.inputStructure===`tree`,minimum:e.minimum??null,maximum:e.maximum??null,atLeast:1,atMost:1,stepSize:e.stepSize,default:t??e.default},i=r(n),a=t??e.default;return i.default==null&&a!=null&&(Array.isArray(a)||i.paramType===`ValueList`&&typeof a!=`object`)&&(i.default=a),i}const m=d(u),h=1,g=`X-Selva-Compute-Version`;function _(e,n){return t.fromInputParams(e.filter(e=>e.paramType).map(e=>p(e,n[e.id])))}async function v(e){let{client:t,signal:n}=e,r=performance.now(),i=e.inputTree??_(e.inputs,e.values),s=performance.now()-r,c=t.solveMeta.seq,l=t.rhinoTiming.seq,u,d=performance.now();try{u=await t.scheduler.solve(e.definitionSource,i,{signal:n,selvaevents:e.selvaEvents})}catch(t){let r=performance.now()-d,i=t instanceof Error&&t.name===`AbortError`||t instanceof a&&t.code===o.ABORTED,s=t instanceof a&&t.code===o.TIMEOUT_ERROR;if(i||s)return i&&n.aborted?{kind:`client_abort`,durationMs:r}:{kind:`timeout`,durationMs:r,message:`Solve exceeded the ${Math.round(e.solveDeadlineMs/1e3)}s deadline.`};if(t instanceof a){if(t.code===o.QUEUE_FULL)return{kind:`shed`,durationMs:r,reason:`queue_full`,retryAfterSeconds:1,message:`Compute server is at capacity. Retry shortly.`};if(t.code===o.QUEUE_TIMEOUT)return{kind:`shed`,durationMs:r,reason:`queue_timeout`,retryAfterSeconds:1,message:`Compute request waited too long in the queue. Retry shortly.`}}return{kind:`compute_error`,durationMs:r,error:t}}let f=performance.now()-d,p=performance.now(),h;try{h=JSON.stringify(u)}catch(e){if(e instanceof RangeError)return{kind:`too_large`};throw e}if(h.length>e.responseMaxBytes)return{kind:`too_large`};let v=performance.now()-p,y=/\bgzip\b/i.test(e.acceptEncoding)&&h.length>1024,x=null,S=0;if(y){let e=performance.now();x=await m(Buffer.from(h)),S=performance.now()-e}let C=performance.now()-e.loadStartMs,w=t.solveMeta.seq===c+1?t.solveMeta.last:null,T=w&&!w.fromCache&&t.rhinoTiming.seq===l+1?t.rhinoTiming.last:null,E={"Content-Type":`application/json`,"Server-Timing":b({defLoadMs:e.defLoadMs,treeBuildMs:s,solveMs:f,serializeMs:v,gzipMs:S,serverTotalMs:C,rhino:T,settle:w,byteRefOutcome:e.byteRefOutcome,prepMarks:e.prepMarks??[]}),[g]:`1`,Vary:`Accept-Encoding`},D={treeBuildMs:s,solveMs:f,serializeMs:v,gzipMs:S,serverTotalMs:C,serializedBytes:h.length,compressedBytes:x?.byteLength??null},O;return x?(E[`Content-Encoding`]=`gzip`,E[`Content-Length`]=String(x.byteLength),O={body:new Uint8Array(x),encoding:`gzip`,headers:E,result:u,metrics:D}):(E[`Content-Length`]=String(Buffer.byteLength(h)),O={body:h,headers:E,result:u,metrics:D}),{kind:`ok`,envelope:O,solveMs:f,errorCount:u.errors?.length??0,warningCount:u.warnings?.length??0}}function y(e,t){let n=/\bgzip\b/i.test(t);if(e.encoding===`gzip`&&!n){let t=l(e.body instanceof Uint8Array?e.body:Buffer.from(e.body)).toString(`utf8`),n={...e.headers};return delete n[`Content-Encoding`],n[`Content-Length`]=String(Buffer.byteLength(t)),{body:t,headers:n}}return{body:e.body,headers:e.headers}}function b(e){let t=`load;dur=${e.defLoadMs.toFixed(1)}, tree;dur=${e.treeBuildMs.toFixed(1)}, solve;dur=${e.solveMs.toFixed(1)}, serialize;dur=${e.serializeMs.toFixed(1)}, gzip;dur=${e.gzipMs.toFixed(1)}, total;dur=${e.serverTotalMs.toFixed(1)}`,n=e.rhino;if(n){let r=n.decode+n.solve+n.encode,i=Math.max(0,e.solveMs-r);t+=`, rhino_decode;dur=${n.decode.toFixed(1)}, rhino_solve;dur=${n.solve.toFixed(1)}, rhino_encode;dur=${n.encode.toFixed(1)}, compute_link;dur=${i.toFixed(1)}`}for(let[n,r]of e.prepMarks)t+=`, p_${n};dur=${r.toFixed(1)}`;let r=e.settle;r&&(t+=`, selva_cache;dur=${+!!r.fromCache}`,r.definitionReuploaded!==void 0&&(t+=`, def_reupload;dur=${+!!r.definitionReuploaded}`));let i=e.byteRefOutcome;if(i){let e=i.loaded?i.fromCache?`hit`:`miss`:`skipped`;t+=`, def_bytes;desc=${e}`}return t}function x(e){return e.id}const S=5e3;function C(t){let n=t.maxWarmComputeServers??16,r=new Map,i=new Map,a=new Map;t.debug===`verbose`&&s();let o=e=>{t.debug&&t.onDebugLog?.(e)};async function c(n,r){let i={last:null,seq:0},a={last:null,seq:0},s=t.debug===`verbose`,c={serverUrl:n.serverUrl,apiKey:n.apiKey,debug:s,cachesolve:t.cachesolve,cacheerroredsolves:t.cacheerroredsolves,onServerTiming:e=>{let n=e.decode??0,r=e.solve??0,a=e.encode??0;if(i.seq+=1,i.last={decode:n,solve:r,encode:a},!t.debug)return;let s=n<=1?`HIT (definition reused, no re-upload/parse)`:`miss (full parse)`,c=t.cachesolve&&r<=1?`HIT (cached result, solve skipped)`:t.cachesolve?`miss (solved fresh)`:`off`;o(`[Compute/rhino-cache] decode=${n}ms solve=${r}ms encode=${a}ms | definition-cache: ${s} | solve-cache (cachesolve): ${c}`)}};r&&(c.headers={"X-Selva-Definition":r});let l=await e.create(c),u=1,d=0,f=!1;async function p(e){if(!f){f=!0;try{let t=await Promise.resolve(l.serverStats?.getActiveChildren({initialize:!1})).catch(()=>null);d=Date.now();let n=!t||t<=0?1:t;if(n===u)return;o(`[Compute/client-cache] concurrency ${u} → ${n} (server child count)`),u=n,e?.setMaxConcurrent(n)}finally{f=!1}}}await p();let m=l.createScheduler({mode:`queue`,maxConcurrent:u,maxQueueDepth:t.maxQueueDepth||void 0,queueWaitMs:t.queueWaitMs||void 0,timeoutMs:t.solveDeadlineMs,cache:t.responseCacheMaxBytes>0&&{maxBytes:t.responseCacheMaxBytes},reuseServerDefinitionCache:t.reuseServerDefinitionCache,onSettle:(e,n)=>{if(a.seq+=1,n.status===`success`&&(n.fromCache!==!0&&Date.now()-d>=3e5&&p(m),a.last={fromCache:n.fromCache===!0,definitionReuploaded:n.definitionReuploaded},t.debug&&(o(`[Compute/selva-cache] ${n.fromCache?`HIT  — served from cache (no compute call)`:`miss — went to Rhino.Compute`} (${Math.round(n.durationMs)}ms)`),n.fromCache||o(n.definitionReuploaded===!0?`[Compute/def-cache] miss — definition RE-UPLOADED (pointer was cold/stale)`:n.definitionReuploaded===!1?`[Compute/def-cache] HIT  — definition reused from server cache (no upload)`:`[Compute/def-cache] n/a — reuse disabled or non-reusable definition`),!n.fromCache))){let e=n.response?.errors,r=Array.isArray(e)?e.length:0;if(r>0){let n=t.cacheerroredsolves?`cached (cacheerroredsolves on)`:`not cached (cacheerroredsolves off) — re-run until fixed`;o(`[Compute/rhino-cache] ${r} GH error(s); ${n}. First: ${JSON.stringify(e[0])}`)}}}});return{client:l,scheduler:m,rhinoTiming:i,solveMeta:a}}return{async getClient(e,t){let s=e.id,l=r.get(s);if(l)return r.delete(s),r.set(s,l),l;let u=i.get(s);if(u)return u;let d=a.get(s);if(d){if(Date.now()-d.at<S)throw o(`[Compute/client-cache] server ${s} failed to build <${S}ms ago — replaying error`),d.error;a.delete(s)}o(`[Compute/client-cache] miss — building warm client for server ${s}`);let f=(async()=>{let i;try{i=await c(e,t?.definitionGuid)}catch(e){throw a.set(s,{error:e,at:Date.now()}),e}if(r.size>=n){let e=r.keys().next().value;e!==void 0&&(o(`[Compute/client-cache] LRU evicted warm client for server ${e} (cap ${n})`),r.get(e)?.scheduler.dispose(),r.delete(e))}return r.set(s,i),i})().finally(()=>i.delete(s));return i.set(s,f),f},evict(e){let t=e;a.delete(t);let n=r.get(t);n&&(o(`[Compute/client-cache] evicted warm client for server ${t} (config change)`),n.scheduler.dispose(),r.delete(t))},solveCacheStats(){let e={warmClients:r.size,entries:0,bytes:0,hits:0,misses:0,evictions:0};for(let t of r.values()){let n=t.scheduler.cacheStats();e.entries+=n.entries,e.bytes+=n.bytes,e.hits+=n.hits,e.misses+=n.misses,e.evictions+=n.evictions}return e},clearSolveCaches(){o(`[Compute/client-cache] cleared solve caches on ${r.size} warm client(s)`);for(let e of r.values())e.scheduler.clearCache()},disposeAll(){o(`[Compute/client-cache] disposing all ${r.size} warm client(s)`);for(let e of r.values())e.scheduler.dispose();r.clear(),a.clear()}}}function w(e){let t=Math.max(0,Math.floor(e)),n=new Map,r=0,i={hits:0,misses:0,evictions:0};function a(e,t){n.delete(e),n.set(e,t)}function o(){for(;r>t&&n.size>0;){let e=n.keys().next().value,t=n.get(e);n.delete(e),r-=t.bytes.byteLength,i.evictions+=1}}function s(e,i){if(t===0||i.byteLength>t)return;let a=n.get(e);a&&(r-=a.bytes.byteLength),n.set(e,{bytes:i}),r+=i.byteLength,o()}return{getOrLoad(e,t){let r={loaded:!1,fromCache:!1};return{key:e,outcome:r,load:async()=>{let o=n.get(e);if(o)return a(e,o),i.hits+=1,r.loaded=!0,r.fromCache=!0,o.bytes;i.misses+=1,r.loaded=!0,r.fromCache=!1;let c=await t();return s(e,c),c}}},stats(){return{hits:i.hits,misses:i.misses,evictions:i.evictions,entries:n.size,bytes:r}},clear(){n.clear(),r=0}}}function T(e={}){let t=new Map;return{run(n,r,i){let a=t.get(n);if(a)return e.onJoin?.(n),a.notifyOwner?.(),a.promise;let o={notifyOwner:i,promise:void 0},s=(async()=>r())().finally(()=>{o.notifyOwner=void 0,t.get(n)===o&&t.delete(n)});return o.promise=s,t.set(n,o),s},inFlight(){return t.size}}}function E(e){return typeof e==`object`&&!!e&&!(e instanceof Uint8Array)&&`outcome`in e}function D(e){return typeof e==`object`&&!!e&&!(e instanceof Uint8Array)&&!(`outcome`in e)&&!(`key`in e)&&`versionId`in e}var O=class{limits;clientCache;byteCache;singleFlight;constructor(e){this.limits=e.limits;let t=e.logger??new f;this.clientCache=C({solveDeadlineMs:this.limits.solveDeadlineMs,cachesolve:this.limits.computeServerCachesolve,cacheerroredsolves:this.limits.computeCacheErroredSolves,reuseServerDefinitionCache:this.limits.computeReuseDefinitionCache,maxQueueDepth:this.limits.computeMaxQueueDepth,queueWaitMs:this.limits.computeQueueWaitMs,responseCacheMaxBytes:this.limits.computeSolveCacheBytes,debug:e.debug??!1,maxWarmComputeServers:e.maxWarmComputeServers,onDebugLog:e.onDebugLog??(e=>t.debug(e,{component:`Compute/client-cache`}))}),this.byteCache=w(this.limits.computeDefinitionCacheBytes),this.singleFlight=T({onJoin:e.onSolveCoalesced})}getClient(e,t){return this.clientCache.getClient(e,t)}definitionRef(e,t){return this.byteCache.getOrLoad(e,t)}evictServer(e){this.clientCache.evict(e)}clearSolveCaches(){this.clientCache.clearSolveCaches()}clearDefinitionCache(){this.byteCache.clear()}stats(){return{client:this.clientCache.solveCacheStats(),definitionBytes:this.byteCache.stats(),coalescing:{inFlight:this.singleFlight.inFlight()}}}async solve(e){let{definitionSource:t,byteRefOutcome:n,identity:r}=this.resolveDefinitionSource(e),a=await this.clientCache.getClient(e.server,{definitionGuid:e.definitionGuid}),o=_(e.inputs,e.values),s=`${r}:${e.server.id}:${i(o)}`,c=new AbortController,l=!1,u=()=>{l||c.abort()};e.signal.addEventListener(`abort`,u,{once:!0});let d=e.acceptEncoding??``,f;try{f=await this.singleFlight.run(s,()=>v({definitionSource:t,byteRefOutcome:n,inputs:e.inputs,values:e.values,inputTree:o,client:a,responseMaxBytes:this.limits.computeResponseMaxBytes,solveDeadlineMs:this.limits.solveDeadlineMs,acceptEncoding:d,selvaEvents:e.selvaEvents,signal:c.signal,loadStartMs:e.loadStartMs??performance.now(),defLoadMs:e.defLoadMs??0,prepMarks:e.prepMarks}),()=>{l=!0})}finally{e.signal.removeEventListener(`abort`,u)}if(f.kind!==`ok`)return f;let p=y(f.envelope,d);return{...f,envelope:{...f.envelope,body:p.body,headers:p.headers}}}toResponse(e,t){let n=(e,n)=>{t?.onError&&t.onError(e,n);let r={"Content-Type":`application/json`};return n.retryAfter!==void 0&&(r[`Retry-After`]=String(n.retryAfter)),{status:e,headers:r,body:JSON.stringify(n)}};switch(e.kind){case`ok`:return{status:200,headers:e.envelope.headers,body:e.envelope.body};case`timeout`:return n(504,{message:e.message});case`client_abort`:return n(499,{message:`Client closed request`});case`too_large`:return n(413,{message:`Solve result is too large to return. This usually means a file output exceeds the supported size.`});case`shed`:return n(503,{message:e.message,retryAfter:e.retryAfterSeconds});case`compute_error`:throw e.error}}toWebResponse(e){let t=this.toResponse(e);return new Response(typeof t.body==`string`?t.body:new Uint8Array(t.body),{status:t.status,headers:t.headers})}resolveDefinitionSource(e){let t=e.definitionSource;if(D(t)){let e=this.byteCache.getOrLoad(t.versionId,t.load);return{definitionSource:e,byteRefOutcome:e.outcome,identity:e.key}}if(E(t))return{definitionSource:t,byteRefOutcome:t.outcome,identity:t.key};if(n(t))return{definitionSource:t,identity:t.key};if(!e.definitionKey)throw Error(`SolveEngine.solve(): definitionKey is required when definitionSource is raw bytes or a string.`);return{definitionSource:t,identity:e.definitionKey}}};export{h as COMPUTE_CONTRACT_VERSION,g as COMPUTE_VERSION_HEADER,O as SolveEngine,y as adaptEnvelopeToEncoding,_ as buildSolveInputTree,C as createClientCache,w as createDefinitionByteCache,T as createSolveCacheSingleFlight,c as isDefinitionRef,v as runSolvePipeline,x as serverIdentity,p as transformInputParameter};
+import { GrasshopperClient, TreeBuilder, stableStringify } from "@selvajs/compute/grasshopper";
+import { ComputeError, ErrorCodes, enableDebugLogging, isDefinitionRef, isDefinitionRef as isDefinitionRef$1 } from "@selvajs/compute/core";
+import { gunzipSync, gzip } from "node:zlib";
+import { promisify } from "node:util";
+import { Agent, fetch } from "undici";
+import { NoopLogger } from "@selvajs/platform";
+// src/server/transform-input.ts
+/** The input tree a solve sends: each input's value, or its schema default when it has none. */
+function buildSolveInputTree(inputs, values) {
+	return TreeBuilder.fromValues(inputs.filter((input) => input.paramType).map((input) => ({
+		paramName: input.nickname,
+		paramType: input.paramType,
+		value: values[input.id] ?? input.default,
+		minimum: input.minimum,
+		maximum: input.maximum
+	})));
+}
+// src/server/solve-pipeline.ts
+/**
+* Transport-agnostic solve pipeline: given an already-resolved solve context
+* (`.gh` bytes, input params + user values, a warm `SolveScheduler`), runs the
+* solve and returns a discriminated {@link SolveOutcome} instead of throwing
+* for expected failures. Auth, the database, share tokens, rate limits, and
+* metric sinks are the calling route's job, not this file's.
+*/
+const gzipAsync = promisify(gzip);
+/**
+* Display output is base64 of already-deflated bytes, where higher levels find nothing more:
+* level 1 lands within 1% of the default's size, in up to a fifth of the time.
+*/
+const GZIP_LEVEL = 1;
+/**
+* A scheduler cache hit returns the same response object, so a repeat solve reuses its bytes rather
+* than paying to serialize and compress them again. Entries live exactly as long as the response.
+* Only the gzip form is kept: browsers always take it, and the JSON string would double the memory.
+*/
+const gzippedBodies = /* @__PURE__ */ new WeakMap();
+/** Compute-response contract version. Bump (and document the change) whenever the envelope's shape changes in a way a consumer could observe. */
+const COMPUTE_CONTRACT_VERSION = 1;
+const COMPUTE_VERSION_HEADER = "X-Selva-Compute-Version";
+async function runSolvePipeline(args) {
+	const { client, signal } = args;
+	const treeBuildStart = performance.now();
+	const inputTree = args.inputTree ?? buildSolveInputTree(args.inputs, args.values);
+	const treeBuildMs = performance.now() - treeBuildStart;
+	let rhino = null;
+	let result;
+	let settle;
+	const solveStart = performance.now();
+	try {
+		const detail = await client.scheduler.solveDetailed(args.definitionSource, inputTree, {
+			signal,
+			selvaevents: args.selvaEvents,
+			onServerTiming: (t) => {
+				rhino = t;
+			}
+		});
+		result = detail.response;
+		settle = {
+			fromCache: detail.fromCache,
+			definitionReuploaded: detail.definitionReuploaded
+		};
+	} catch (err) {
+		const durationMs = performance.now() - solveStart;
+		const isAbort = err instanceof Error && err.name === "AbortError" || err instanceof ComputeError && err.code === ErrorCodes.ABORTED;
+		const isDeadline = err instanceof ComputeError && err.code === ErrorCodes.TIMEOUT_ERROR;
+		if (isAbort || isDeadline) {
+			if (isAbort && signal.aborted) return {
+				kind: "client_abort",
+				durationMs
+			};
+			return {
+				kind: "timeout",
+				durationMs,
+				message: `Solve exceeded the ${Math.round(args.solveDeadlineMs / 1e3)}s deadline.`
+			};
+		}
+		if (err instanceof ComputeError) {
+			if (err.code === ErrorCodes.RESPONSE_TOO_LARGE) return { kind: "too_large" };
+			if (err.code === ErrorCodes.QUEUE_FULL) return {
+				kind: "shed",
+				durationMs,
+				reason: "queue_full",
+				retryAfterSeconds: 1,
+				message: "Compute server is at capacity. Retry shortly."
+			};
+			if (err.code === ErrorCodes.QUEUE_TIMEOUT) return {
+				kind: "shed",
+				durationMs,
+				reason: "queue_timeout",
+				retryAfterSeconds: 1,
+				message: "Compute request waited too long in the queue. Retry shortly."
+			};
+		}
+		return {
+			kind: "compute_error",
+			durationMs,
+			error: err
+		};
+	}
+	const solveMs = performance.now() - solveStart;
+	const clientWantsGzip = /\bgzip\b/i.test(args.acceptEncoding);
+	const remembered = clientWantsGzip ? gzippedBodies.get(result) : void 0;
+	let compressed = remembered?.body ?? null;
+	let serializedBytes = remembered?.serializedBytes ?? 0;
+	let serialized = "";
+	let serializeMs = 0;
+	let gzipMs = 0;
+	if (!remembered) {
+		const serializeStart = performance.now();
+		try {
+			serialized = JSON.stringify(result);
+		} catch (err) {
+			if (err instanceof RangeError) return { kind: "too_large" };
+			throw err;
+		}
+		if (serialized.length > args.responseMaxBytes) return { kind: "too_large" };
+		serializeMs = performance.now() - serializeStart;
+		serializedBytes = serialized.length;
+		if (clientWantsGzip && serialized.length > 1024) {
+			const gzipStart = performance.now();
+			compressed = new Uint8Array(await gzipAsync(Buffer.from(serialized), { level: GZIP_LEVEL }));
+			gzipMs = performance.now() - gzipStart;
+			gzippedBodies.set(result, {
+				body: compressed,
+				serializedBytes
+			});
+		}
+	}
+	const serverTotalMs = performance.now() - args.loadStartMs;
+	const headers = {
+		"Content-Type": "application/json",
+		"Server-Timing": buildServerTiming({
+			defLoadMs: args.defLoadMs,
+			treeBuildMs,
+			solveMs,
+			serializeMs,
+			gzipMs,
+			serverTotalMs,
+			rhino,
+			settle,
+			byteRefOutcome: args.byteRefOutcome,
+			prepMarks: args.prepMarks ?? []
+		}),
+		[COMPUTE_VERSION_HEADER]: String(1),
+		Vary: "Accept-Encoding"
+	};
+	const metrics = {
+		treeBuildMs,
+		solveMs,
+		serializeMs,
+		gzipMs,
+		serverTotalMs,
+		serializedBytes,
+		compressedBytes: compressed?.byteLength ?? null
+	};
+	let envelope;
+	if (compressed) {
+		headers["Content-Encoding"] = "gzip";
+		headers["Content-Length"] = String(compressed.byteLength);
+		envelope = {
+			body: compressed,
+			encoding: "gzip",
+			headers,
+			result,
+			metrics
+		};
+	} else {
+		headers["Content-Length"] = String(Buffer.byteLength(serialized));
+		envelope = {
+			body: serialized,
+			headers,
+			result,
+			metrics
+		};
+	}
+	return {
+		kind: "ok",
+		envelope,
+		solveMs,
+		errorCount: result.errors?.length ?? 0,
+		warningCount: result.warnings?.length ?? 0
+	};
+}
+/**
+* Re-key a coalesced envelope to a single waiter's `Accept-Encoding`.
+*
+* The single-flight coalescer runs ONE pipeline execution for N identical
+* concurrent solves and hands every waiter the same {@link SolveEnvelope},
+* baked from the FIRST caller's `Accept-Encoding`. A later waiter with a
+* different `Accept-Encoding` would otherwise get a body labelled with the
+* wrong encoding — `Vary` can't help here, since it's one shared object, not a
+* cache lookup. Encoding is deliberately left out of the coalesce key so mixed
+* clients still coalesce; this adapts the shared result to each waiter instead.
+*
+* Only the correctness-critical direction is adapted: a gzip envelope served to
+* a non-gzip waiter is gunzipped back to JSON. The reverse (plain JSON to a
+* gzip-capable waiter) is left uncompressed — correct, just not maximally small.
+*/
+function adaptEnvelopeToEncoding(envelope, acceptEncoding) {
+	const waiterWantsGzip = /\bgzip\b/i.test(acceptEncoding);
+	if (envelope.encoding === "gzip" && !waiterWantsGzip) {
+		const json = gunzipSync(envelope.body instanceof Uint8Array ? envelope.body : Buffer.from(envelope.body)).toString("utf8");
+		const headers = { ...envelope.headers };
+		delete headers["Content-Encoding"];
+		headers["Content-Length"] = String(Buffer.byteLength(json));
+		return {
+			body: json,
+			headers
+		};
+	}
+	return {
+		body: envelope.body,
+		headers: envelope.headers
+	};
+}
+/**
+* `total` is the server's headers-to-out wall time, so browser `ttfb − total`
+* ≈ network+send latency. When the compute server reports its own timing
+* (VektorNode fork), `rhino_*` is time on the compute server and `compute_link`
+* is everything between it (network + queue wait). `rhino_cache` is 1 when the
+* compute server answered from its own result cache.
+*/
+function buildServerTiming(parts) {
+	let header = `load;dur=${parts.defLoadMs.toFixed(1)}, tree;dur=${parts.treeBuildMs.toFixed(1)}, solve;dur=${parts.solveMs.toFixed(1)}, serialize;dur=${parts.serializeMs.toFixed(1)}, gzip;dur=${parts.gzipMs.toFixed(1)}, total;dur=${parts.serverTotalMs.toFixed(1)}`;
+	const rhino = parts.rhino;
+	if (rhino) {
+		const decode = rhino.decode ?? 0;
+		const solve = rhino.solve ?? 0;
+		const encode = rhino.encode ?? 0;
+		const computeLinkMs = Math.max(0, parts.solveMs - decode - solve - encode);
+		header += `, rhino_decode;dur=${decode.toFixed(1)}, rhino_solve;dur=${solve.toFixed(1)}, rhino_encode;dur=${encode.toFixed(1)}, compute_link;dur=${computeLinkMs.toFixed(1)}, rhino_cache;dur=${rhino.cacheHit ? 1 : 0}`;
+		if (rhino.gh !== void 0) header += `, rhino_gh;dur=${rhino.gh.toFixed(1)}`;
+		if (rhino.recomputed) header += `, rhino_recomputed;desc="${rhino.recomputed.ran}/${rhino.recomputed.total}"`;
+	}
+	for (const [label, ms] of parts.prepMarks) header += `, p_${label};dur=${ms.toFixed(1)}`;
+	const settle = parts.settle;
+	header += `, selva_cache;dur=${settle.fromCache ? 1 : 0}`;
+	if (settle.definitionReuploaded !== void 0) header += `, def_reupload;dur=${settle.definitionReuploaded ? 1 : 0}`;
+	const byteRef = parts.byteRefOutcome;
+	if (byteRef) {
+		const verdict = !byteRef.loaded ? "skipped" : byteRef.fromCache ? "hit" : "miss";
+		header += `, def_bytes;desc=${verdict}`;
+	}
+	return header;
+}
+// src/server/long-fetch.ts
+/** undici's default `headersTimeout` and `bodyTimeout`, which `timeoutMs` can't extend. */
+const UNDICI_DEFAULT_LIMIT_MS = 3e5;
+/** Both off, not raised: the scheduler's `timeoutMs` stays the one deadline on a solve. */
+const unlimited = new Agent({
+	headersTimeout: 0,
+	bodyTimeout: 0
+});
+const unlimitedFetch = ((input, init) => fetch(input, {
+	...init,
+	dispatcher: unlimited
+}));
+/** The fetch for a solve deadline: `undefined` means the global one reaches it. */
+function fetchForDeadline(deadlineMs) {
+	return deadlineMs >= UNDICI_DEFAULT_LIMIT_MS ? unlimitedFetch : void 0;
+}
+// src/server/client-cache.ts
+function serverIdentity(server) {
+	return server.id;
+}
+const DEFAULT_MAX_WARM_COMPUTE_SERVERS = 16;
+/**
+* Fallback concurrency while the first probe is still in flight, and the value
+* kept whenever a probe fails or reports 0 — never send more than a single
+* solve to a server whose real capacity is unknown.
+*/
+const FALLBACK_CONCURRENCY = 1;
+/**
+* How stale the compute server's child count may get before a solve triggers a
+* re-read. Short enough that a resized pool is picked up within a few solves,
+* long enough that a busy server is probed rarely — the probe rides on solve
+* completion, so an idle server is never polled at all.
+*/
+const CONCURRENCY_PROBE_INTERVAL_MS = 3e5;
+/**
+* How long a failed build is remembered before the next `getClient` retries the
+* handshake. Without this, every solve against a down server pays the full probe
+* ladder again, so a user clicking Solve twice waits twice.
+*
+* Short on purpose: this is a convenience for the rapid-retry case, not a
+* circuit breaker. An operator who starts the compute VM should not have to wait
+* out a long penalty window before the app notices.
+*/
+const FAILED_BUILD_TTL_MS = 5e3;
+function createClientCache(config) {
+	const maxWarmComputeServers = config.maxWarmComputeServers ?? DEFAULT_MAX_WARM_COMPUTE_SERVERS;
+	const cache = /* @__PURE__ */ new Map();
+	const pending = /* @__PURE__ */ new Map();
+	const failed = /* @__PURE__ */ new Map();
+	if (config.debug === "verbose") enableDebugLogging();
+	const debugLog = (message) => {
+		if (config.debug) config.onDebugLog?.(message);
+	};
+	async function build(server, definitionGuid) {
+		const debugVerbose = config.debug === "verbose";
+		const longFetch = fetchForDeadline(config.solveDeadlineMs);
+		const clientConfig = {
+			serverUrl: server.serverUrl,
+			apiKey: server.apiKey,
+			debug: debugVerbose,
+			cachesolve: config.cachesolve,
+			maxResponseBytes: config.maxResponseBytes,
+			...longFetch && { fetch: longFetch }
+		};
+		if (config.debug) clientConfig.onServerTiming = (t) => {
+			if (t.cacheHit) {
+				debugLog("[Compute/rhino-cache] solve-cache (cachesolve): HIT (cached result, solve skipped)");
+				return;
+			}
+			const decode = t.decode ?? 0;
+			const solve = t.solve ?? 0;
+			const encode = t.encode ?? 0;
+			const defCache = decode <= 1 ? "HIT (definition reused, no re-upload/parse)" : "miss (full parse)";
+			const solveCache = config.cachesolve ? "miss (solved fresh)" : "off";
+			const ran = t.recomputed ? ` | ran ${t.recomputed.ran}/${t.recomputed.total} objects` : "";
+			debugLog(`[Compute/rhino-cache] decode=${decode}ms solve=${solve}ms encode=${encode}ms | definition-cache: ${defCache} | solve-cache (cachesolve): ${solveCache}${ran}`);
+		};
+		if (definitionGuid) clientConfig.headers = { "X-Selva-Definition": definitionGuid };
+		const client = await GrasshopperClient.create(clientConfig);
+		let maxConcurrent = FALLBACK_CONCURRENCY;
+		let lastProbeAt = 0;
+		let probing = false;
+		/**
+		* Best-effort re-read of the server's child count. Never awaited by a caller:
+		* a probe must not add a round-trip to the solve path, so a changed count takes
+		* effect on the NEXT solve rather than the one that triggered the probe.
+		*
+		* `initialize: false` keeps this from spawning children on an idle server —
+		* which also means a cold server honestly reports 0. Both a failed probe and a
+		* 0 result fall back to `FALLBACK_CONCURRENCY` (1): an unknown-capacity server
+		* is safer under-used than oversent.
+		*/
+		async function refreshConcurrency(scheduler) {
+			if (probing) return;
+			probing = true;
+			try {
+				const children = await Promise.resolve(client.serverStats?.getActiveChildren({ initialize: false })).catch(() => null);
+				lastProbeAt = Date.now();
+				const next = !children || children <= 0 ? FALLBACK_CONCURRENCY : children;
+				if (next === maxConcurrent) return;
+				debugLog(`[Compute/client-cache] concurrency ${maxConcurrent} → ${next} (server child count)`);
+				maxConcurrent = next;
+				scheduler?.setMaxConcurrent(next);
+			} finally {
+				probing = false;
+			}
+		}
+		await refreshConcurrency();
+		const scheduler = client.createScheduler({
+			mode: "queue",
+			maxConcurrent,
+			maxQueueDepth: config.maxQueueDepth || void 0,
+			queueWaitMs: config.queueWaitMs || void 0,
+			timeoutMs: config.solveDeadlineMs,
+			cache: config.responseCacheMaxBytes > 0 ? { maxBytes: config.responseCacheMaxBytes } : false,
+			reuseServerDefinitionCache: config.reuseServerDefinitionCache,
+			onSettle: (_ctx, result) => {
+				if (result.status !== "success") return;
+				if (result.fromCache !== true && Date.now() - lastProbeAt >= CONCURRENCY_PROBE_INTERVAL_MS) refreshConcurrency(scheduler);
+				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)`);
+				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");
+				if (!result.fromCache) {
+					const errs = result.response?.errors;
+					const errCount = Array.isArray(errs) ? errs.length : 0;
+					if (errCount > 0) debugLog(`[Compute/rhino-cache] ${errCount} GH error(s); not cached by Rhino.Compute. First: ${JSON.stringify(errs[0])}`);
+				}
+			}
+		});
+		return {
+			client,
+			scheduler
+		};
+	}
+	return {
+		async getClient(server, opts) {
+			const key = server.id;
+			const existing = cache.get(key);
+			if (existing) {
+				cache.delete(key);
+				cache.set(key, existing);
+				return existing;
+			}
+			const inFlight = pending.get(key);
+			if (inFlight) return inFlight;
+			const recentFailure = failed.get(key);
+			if (recentFailure) {
+				if (Date.now() - recentFailure.at < FAILED_BUILD_TTL_MS) {
+					debugLog(`[Compute/client-cache] server ${key} failed to build <${FAILED_BUILD_TTL_MS}ms ago — replaying error`);
+					throw recentFailure.error;
+				}
+				failed.delete(key);
+			}
+			debugLog(`[Compute/client-cache] miss — building warm client for server ${key}`);
+			const buildPromise = (async () => {
+				let entry;
+				try {
+					entry = await build(server, opts?.definitionGuid);
+				} catch (err) {
+					failed.set(key, {
+						error: err,
+						at: Date.now()
+					});
+					throw err;
+				}
+				if (cache.size >= maxWarmComputeServers) {
+					const oldestKey = cache.keys().next().value;
+					if (oldestKey !== void 0) {
+						debugLog(`[Compute/client-cache] LRU evicted warm client for server ${oldestKey} (cap ${maxWarmComputeServers})`);
+						cache.get(oldestKey)?.scheduler.dispose();
+						cache.delete(oldestKey);
+					}
+				}
+				cache.set(key, entry);
+				return entry;
+			})().finally(() => pending.delete(key));
+			pending.set(key, buildPromise);
+			return buildPromise;
+		},
+		evict(id) {
+			const key = id;
+			failed.delete(key);
+			const entry = cache.get(key);
+			if (entry) {
+				debugLog(`[Compute/client-cache] evicted warm client for server ${key} (config change)`);
+				entry.scheduler.dispose();
+				cache.delete(key);
+			}
+		},
+		solveCacheStats() {
+			const total = {
+				warmClients: cache.size,
+				entries: 0,
+				bytes: 0,
+				hits: 0,
+				misses: 0,
+				evictions: 0
+			};
+			for (const entry of cache.values()) {
+				const s = entry.scheduler.cacheStats();
+				total.entries += s.entries;
+				total.bytes += s.bytes;
+				total.hits += s.hits;
+				total.misses += s.misses;
+				total.evictions += s.evictions;
+			}
+			return total;
+		},
+		clearSolveCaches() {
+			debugLog(`[Compute/client-cache] cleared solve caches on ${cache.size} warm client(s)`);
+			for (const entry of cache.values()) entry.scheduler.clearCache();
+		},
+		disposeAll() {
+			debugLog(`[Compute/client-cache] disposing all ${cache.size} warm client(s)`);
+			for (const entry of cache.values()) entry.scheduler.dispose();
+			cache.clear();
+			failed.clear();
+		}
+	};
+}
+// src/server/definition-byte-cache.ts
+/**
+* @param maxBytes total retained-byte budget; `0` (or negative) disables caching
+*   entirely — every `load()` calls the loader and nothing is retained.
+*/
+function createDefinitionByteCache(maxBytes) {
+	const budget = Math.max(0, Math.floor(maxBytes));
+	const cache = /* @__PURE__ */ new Map();
+	let retainedBytes = 0;
+	const stats = {
+		hits: 0,
+		misses: 0,
+		evictions: 0
+	};
+	function touch(key, entry) {
+		cache.delete(key);
+		cache.set(key, entry);
+	}
+	function evictToFit() {
+		while (retainedBytes > budget && cache.size > 0) {
+			const oldestKey = cache.keys().next().value;
+			const oldest = cache.get(oldestKey);
+			cache.delete(oldestKey);
+			retainedBytes -= oldest.bytes.byteLength;
+			stats.evictions += 1;
+		}
+	}
+	function store(key, bytes) {
+		if (budget === 0) return;
+		if (bytes.byteLength > budget) return;
+		const existing = cache.get(key);
+		if (existing) retainedBytes -= existing.bytes.byteLength;
+		cache.set(key, { bytes });
+		retainedBytes += bytes.byteLength;
+		evictToFit();
+	}
+	return {
+		getOrLoad(versionId, load) {
+			const outcome = {
+				loaded: false,
+				fromCache: false
+			};
+			return {
+				key: versionId,
+				outcome,
+				load: async () => {
+					const hit = cache.get(versionId);
+					if (hit) {
+						touch(versionId, hit);
+						stats.hits += 1;
+						outcome.loaded = true;
+						outcome.fromCache = true;
+						return hit.bytes;
+					}
+					stats.misses += 1;
+					outcome.loaded = true;
+					outcome.fromCache = false;
+					const bytes = await load();
+					store(versionId, bytes);
+					return bytes;
+				}
+			};
+		},
+		stats() {
+			return {
+				hits: stats.hits,
+				misses: stats.misses,
+				evictions: stats.evictions,
+				entries: cache.size,
+				bytes: retainedBytes
+			};
+		},
+		clear() {
+			cache.clear();
+			retainedBytes = 0;
+		}
+	};
+}
+// src/server/solve-cache-single-flight.ts
+function createSolveCacheSingleFlight(options = {}) {
+	const inflight = /* @__PURE__ */ new Map();
+	return {
+		run(key, work, onWaiterJoined) {
+			const existing = inflight.get(key);
+			if (existing) {
+				options.onJoin?.(key);
+				existing.notifyOwner?.();
+				return existing.promise;
+			}
+			const flight = {
+				notifyOwner: onWaiterJoined,
+				promise: void 0
+			};
+			const p = (async () => work())().finally(() => {
+				flight.notifyOwner = void 0;
+				if (inflight.get(key) === flight) inflight.delete(key);
+			});
+			flight.promise = p;
+			inflight.set(key, flight);
+			return p;
+		},
+		inFlight() {
+			return inflight.size;
+		}
+	};
+}
+// src/server/solve-engine.ts
+/**
+* Facade over the warm-client cache, definition-byte cache, single-flight
+* coalescing, and the solve pipeline — the primitives an app route would
+* otherwise wire up by hand.
+*
+* Doesn't read env itself: `@selvajs/server` owns `resolveComputeLimits` and
+* depends on `@selvajs/solve`, so calling it from here would be a circular
+* import. Callers resolve their own limits and pass in the fields below.
+*
+* Stays out of auth, DB reads, share tokens, rate limiting, metrics, and
+* compute-server selection — all app policy, supplied per-call via
+* `SolveEngineSolveArgs.server`.
+*/
+function isByteCacheRef(source) {
+	return typeof source === "object" && source !== null && !(source instanceof Uint8Array) && "outcome" in source;
+}
+function isVersionLoadPair(source) {
+	return typeof source === "object" && source !== null && !(source instanceof Uint8Array) && !("outcome" in source) && !("key" in source) && "versionId" in source;
+}
+var SolveEngine = class {
+	limits;
+	clientCache;
+	byteCache;
+	singleFlight;
+	constructor(options) {
+		this.limits = options.limits;
+		const logger = options.logger ?? new NoopLogger();
+		this.clientCache = createClientCache({
+			solveDeadlineMs: this.limits.solveDeadlineMs,
+			cachesolve: this.limits.computeServerCachesolve,
+			reuseServerDefinitionCache: this.limits.computeReuseDefinitionCache,
+			maxQueueDepth: this.limits.computeMaxQueueDepth,
+			queueWaitMs: this.limits.computeQueueWaitMs,
+			responseCacheMaxBytes: this.limits.computeSolveCacheBytes,
+			maxResponseBytes: this.limits.computeResponseMaxBytes,
+			debug: options.debug ?? false,
+			maxWarmComputeServers: options.maxWarmComputeServers,
+			onDebugLog: options.onDebugLog ?? ((message) => logger.debug(message, { component: "Compute/client-cache" }))
+		});
+		this.byteCache = createDefinitionByteCache(this.limits.computeDefinitionCacheBytes);
+		this.singleFlight = createSolveCacheSingleFlight({ onJoin: options.onSolveCoalesced });
+	}
+	getClient(server, opts) {
+		return this.clientCache.getClient(server, opts);
+	}
+	definitionRef(versionId, load) {
+		return this.byteCache.getOrLoad(versionId, load);
+	}
+	evictServer(id) {
+		this.clientCache.evict(id);
+	}
+	clearSolveCaches() {
+		this.clientCache.clearSolveCaches();
+	}
+	/**
+	* Drop every retained `.gh` byte entry. Safe at any time: entries key on an
+	* immutable version id, so clearing costs a storage re-read and nothing else.
+	*/
+	clearDefinitionCache() {
+		this.byteCache.clear();
+	}
+	stats() {
+		return {
+			client: this.clientCache.solveCacheStats(),
+			definitionBytes: this.byteCache.stats(),
+			coalescing: { inFlight: this.singleFlight.inFlight() }
+		};
+	}
+	async solve(args) {
+		const { definitionSource: resolvedSource, byteRefOutcome, identity } = this.resolveDefinitionSource(args);
+		const client = await this.clientCache.getClient(args.server, { definitionGuid: args.definitionGuid });
+		const inputTree = buildSolveInputTree(args.inputs, args.values);
+		const coalesceKey = `${identity}:${args.server.id}:${stableStringify(inputTree)}`;
+		const abortController = new AbortController();
+		let hasWaiters = false;
+		const onCallerAbort = () => {
+			if (!hasWaiters) abortController.abort();
+		};
+		args.signal.addEventListener("abort", onCallerAbort, { once: true });
+		const acceptEncoding = args.acceptEncoding ?? "";
+		let outcome;
+		try {
+			outcome = await this.singleFlight.run(coalesceKey, () => runSolvePipeline({
+				definitionSource: resolvedSource,
+				byteRefOutcome,
+				inputs: args.inputs,
+				values: args.values,
+				inputTree,
+				client,
+				responseMaxBytes: this.limits.computeResponseMaxBytes,
+				solveDeadlineMs: this.limits.solveDeadlineMs,
+				acceptEncoding,
+				selvaEvents: args.selvaEvents,
+				signal: abortController.signal,
+				loadStartMs: args.loadStartMs ?? performance.now(),
+				defLoadMs: args.defLoadMs ?? 0,
+				prepMarks: args.prepMarks
+			}), () => {
+				hasWaiters = true;
+			});
+		} finally {
+			args.signal.removeEventListener("abort", onCallerAbort);
+		}
+		if (outcome.kind !== "ok") return outcome;
+		const wire = adaptEnvelopeToEncoding(outcome.envelope, acceptEncoding);
+		return {
+			...outcome,
+			envelope: {
+				...outcome.envelope,
+				body: wire.body,
+				headers: wire.headers
+			}
+		};
+	}
+	toResponse(outcome, opts) {
+		const fail = (status, body) => {
+			if (opts?.onError) opts.onError(status, body);
+			const headers = { "Content-Type": "application/json" };
+			if (body.retryAfter !== void 0) headers["Retry-After"] = String(body.retryAfter);
+			return {
+				status,
+				headers,
+				body: JSON.stringify(body)
+			};
+		};
+		switch (outcome.kind) {
+			case "ok": return {
+				status: 200,
+				headers: outcome.envelope.headers,
+				body: outcome.envelope.body
+			};
+			case "timeout": return fail(504, { message: outcome.message });
+			case "client_abort": return fail(499, { message: "Client closed request" });
+			case "too_large": return fail(413, { message: "Solve result is too large to return. This usually means a file output exceeds the supported size." });
+			case "shed": return fail(503, {
+				message: outcome.message,
+				retryAfter: outcome.retryAfterSeconds
+			});
+			case "compute_error": throw outcome.error;
+		}
+	}
+	toWebResponse(outcome) {
+		const r = this.toResponse(outcome);
+		return new Response(typeof r.body === "string" ? r.body : new Uint8Array(r.body), {
+			status: r.status,
+			headers: r.headers
+		});
+	}
+	resolveDefinitionSource(args) {
+		const source = args.definitionSource;
+		if (isVersionLoadPair(source)) {
+			const ref = this.byteCache.getOrLoad(source.versionId, source.load);
+			return {
+				definitionSource: ref,
+				byteRefOutcome: ref.outcome,
+				identity: ref.key
+			};
+		}
+		if (isByteCacheRef(source)) return {
+			definitionSource: source,
+			byteRefOutcome: source.outcome,
+			identity: source.key
+		};
+		if (isDefinitionRef$1(source)) return {
+			definitionSource: source,
+			identity: source.key
+		};
+		if (!args.definitionKey) throw new Error("SolveEngine.solve(): definitionKey is required when definitionSource is raw bytes or a string.");
+		return {
+			definitionSource: source,
+			identity: args.definitionKey
+		};
+	}
+};
+export { COMPUTE_CONTRACT_VERSION, COMPUTE_VERSION_HEADER, SolveEngine, adaptEnvelopeToEncoding, buildSolveInputTree, createClientCache, createDefinitionByteCache, createSolveCacheSingleFlight, isDefinitionRef, runSolvePipeline, serverIdentity };
+
 //# sourceMappingURL=server.js.map