@selvajs/solve 0.2.0-beta.0

package/dist/server.d.cts

@@ -0,0 +1,407 @@
+import { GrasshopperClient, SolveScheduler, GrasshopperComputeResponse, SolveDefinition, DataTree, InputParam } from '@selvajs/compute';
+import { SchemaInput } from '@selvajs/schemas';
+export { S as SolveInput } from './solve-input-CqYtetTA.cjs';
+
+/**
+ * Opaque identity of a compute server — construct only via `serverIdentity()`.
+ * Kept opaque so "a server is now a pool of URLs behind one id" stays additive.
+ */
+type ServerIdentity = string & {
+    readonly __brand: 'ServerIdentity';
+};
+/** Minimal resolved-server shape the cache needs (a subset of the app's `ComputeServerConfig`). */
+interface ResolvedServer {
+    id: string;
+    serverUrl: string;
+    /** Sent as `RhinoComputeKey`. */
+    apiKey?: string;
+}
+/** Derive the opaque cache identity from a resolved server. Identity is the `id`. */
+declare function serverIdentity(server: Pick<ResolvedServer, 'id'>): ServerIdentity;
+interface CachedClient {
+    client: GrasshopperClient;
+    scheduler: SolveScheduler;
+    /**
+     * Last Server-Timing decode/solve/encode, written by onServerTiming.
+     * The scheduler runs up to `maxConcurrentSolves` at once, so `last` alone
+     * can't be trusted per-request: callers snapshot `seq` before their solve
+     * and only attribute `last` to themselves if exactly one write happened
+     * since (see the guard in `runSolvePipeline`), dropping it otherwise
+     * rather than risk misattributing another request's timing.
+     */
+    rhinoTiming: {
+        last: {
+            decode: number;
+            solve: number;
+            encode: number;
+        } | null;
+        seq: number;
+    };
+    /**
+     * Same snapshot-and-attribute pattern as `rhinoTiming`, for the scheduler's
+     * onSettle cache verdict. `seq` increments on every settle (success or
+     * error); `last` is written only on success.
+     */
+    solveMeta: {
+        last: {
+            fromCache: boolean;
+            definitionReuploaded?: boolean;
+        } | null;
+        seq: number;
+    };
+}
+/** Config injected by the consuming app, so this module stays env-agnostic and testable. */
+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;
+    /**
+     * Max in-flight solves per compute server (scheduler `maxConcurrent`; excess
+     * FIFO-queues). Size to the server's `compute.geometry` child count
+     * (`ComputeLimits.computeMaxConcurrentSolves`).
+     */
+    maxConcurrentSolves: number;
+    /**
+     * Backpressure — max solves that may WAIT in the FIFO queue (excludes the
+     * in-flight `maxConcurrentSolves`). `0` = unbounded (`ComputeLimits.
+     * computeMaxQueueDepth`); a full queue sheds new solves with `QUEUE_FULL`.
+     */
+    maxQueueDepth: number;
+    /**
+     * Backpressure — max ms a solve may sit queued before executing; `0` = no
+     * deadline (`ComputeLimits.computeQueueWaitMs`). A too-long wait sheds with
+     * `QUEUE_TIMEOUT`.
+     */
+    queueWaitMs: number;
+    /**
+     * Byte budget for this client's in-process solve cache, evicted LRU alongside
+     * its entry-count cap. Applies per warm client — total worst-case heap is this
+     * × `maxCachedClients`. `0` disables the cache entirely
+     * (`ComputeLimits.computeSolveCacheBytes`, env `COMPUTE_SOLVE_CACHE_MB`).
+     */
+    responseCacheMaxBytes: number;
+    /** 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;
+}
+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.
+     */
+    getClient(server: ResolvedServer, opts?: {
+        definitionGuid?: string;
+    }): Promise<CachedClient>;
+    /** Dispose and drop the warm client for `id`, so the next request rebuilds against fresh connection details. */
+    evict(id: string | ServerIdentity): void;
+    /**
+     * Solve-cache counters summed across every warm client. `warmClients` is
+     * reported alongside since each client owns its own cache. Counters die
+     * with the client that owns them, so totals can fall over time.
+     */
+    solveCacheStats(): SolveCacheStats;
+    /** Dispose every warm client. Test seam / shutdown hook. */
+    disposeAll(): void;
+}
+/** Aggregate solve-cache counters across the warm clients (see `solveCacheStats`). */
+interface SolveCacheStats {
+    warmClients: number;
+    entries: number;
+    bytes: number;
+    hits: number;
+    misses: number;
+    /** Entries dropped under size/byte pressure (not TTL expiry or replacement). */
+    evictions: number;
+}
+declare function createClientCache(config: ClientCacheConfig): ClientCache;
+
+/**
+ * In-process cache of `.gh` definition bytes, keyed by immutable **version id**.
+ *
+ * Turns an eager `storage.get(fileKey)` on every solve request into a lazy
+ * `DefinitionRef.load()`: the scheduler calls `load()` only when an upload is
+ * unavoidable (a pointer-known re-solve never touches storage or this cache).
+ *
+ * The key MUST be the version id, never a `fileKey` — a delete-latest-then-
+ * reupload can reuse a `fileKey` for different content, which would silently
+ * serve one version's bytes for another with no diagnostic. Callers pass
+ * `version.id`, and the returned `DefinitionRef.key` is that same id, so the
+ * scheduler's own result/pointer cache keys on the same immutable identity.
+ *
+ * Eviction is LRU by total byte budget, not entry count — definitions range
+ * from tens of KB to hundreds of MB, so a count cap would either pin
+ * gigabytes or evict uselessly. `COMPUTE_DEFINITION_CACHE_MB` sets the
+ * budget (see `createDefinitionByteCache`). No TTL: version ids are
+ * immutable, so a cached entry can never go stale. An entry larger than the
+ * whole budget is served but never retained.
+ */
+/**
+ * Per-`getOrLoad` outcome, observable after the scheduler has (or hasn't)
+ * called `load()` — lets the solve pipeline emit a `def_bytes` Server-Timing
+ * verdict (`skipped` / `hit` / `miss`).
+ */
+interface ByteRefOutcome {
+    loaded: boolean;
+    /** When `loaded`, whether the bytes came from a warm cache entry. */
+    fromCache: boolean;
+}
+/** A definition reference shaped for `@selvajs/compute`'s `DefinitionRef`. */
+interface ByteCacheRef {
+    key: string;
+    load: () => Promise<Uint8Array>;
+    outcome: ByteRefOutcome;
+}
+/** Hit/miss/eviction counters for observability (Server-Timing, admin debug). */
+interface ByteCacheStats {
+    hits: number;
+    misses: number;
+    /** Entries dropped by the byte-budget LRU. */
+    evictions: number;
+    entries: number;
+    bytes: number;
+}
+interface DefinitionByteCache {
+    /**
+     * `DefinitionRef` whose `load()` serves `versionId`'s bytes from the cache
+     * when warm, otherwise calls `load` and caches the result. Cheap to build
+     * and moves no bytes until `load()` runs.
+     */
+    getOrLoad(versionId: string, load: () => Promise<Uint8Array>): ByteCacheRef;
+    stats(): ByteCacheStats;
+    /** Test seam / eviction on definition delete if ever needed. */
+    clear(): void;
+}
+/**
+ * @param maxBytes total retained-byte budget; `0` (or negative) disables caching
+ *   entirely — every `load()` calls the loader and nothing is retained.
+ */
+declare function createDefinitionByteCache(maxBytes: number): DefinitionByteCache;
+
+/**
+ * Transport-agnostic solve pipeline: given an already-resolved solve context
+ * (`.gh` bytes, input params + user values, a warm `SolveScheduler`), runs the
+ * framework-free half of a solve and returns a discriminated {@link SolveOutcome}
+ * instead of throwing for expected failures. Nothing here touches auth, the
+ * database, share tokens, rate limits, or metric sinks — those stay app policy
+ * in the route that calls this.
+ */
+
+/** Compute-response contract version. Bump (and document the change) whenever the envelope's shape changes in a way a consumer could observe. */
+declare const COMPUTE_CONTRACT_VERSION: 1;
+declare const COMPUTE_VERSION_HEADER = "X-Selva-Compute-Version";
+type PipelineInput = SchemaInput & {
+    minimum?: number;
+    maximum?: number;
+    stepSize?: number;
+};
+interface SolvePipelineArgs {
+    /**
+     * The definition to solve. Either raw `.gh` bytes, or a `DefinitionRef` (from
+     * the definition-byte cache) whose bytes the scheduler materializes ONLY when
+     * an upload is unavoidable — a pointer-known solve of a `DefinitionRef` moves
+     * zero bytes.
+     */
+    definitionSource: SolveDefinition;
+    /**
+     * When `definitionSource` is a byte-cache `DefinitionRef`, its mutable outcome
+     * so the pipeline can emit the `def_bytes` Server-Timing verdict. Omit for
+     * raw-bytes solves.
+     */
+    byteRefOutcome?: ByteRefOutcome;
+    /** Persisted input params; only those with a `paramType` are sent to the solve. */
+    inputs: PipelineInput[];
+    /**
+     * A tree the caller already built with {@link buildSolveInputTree}. When present
+     * the pipeline skips its own build and solves this exact object.
+     *
+     * Needed whenever the caller coalesces concurrent solves: a single-flight key
+     * derived from raw `{inputs, values}` would split two requests that transform
+     * to the same tree, which is the identity the scheduler actually caches on.
+     */
+    inputTree?: DataTree[];
+    /** User-chosen values keyed by input id; missing keys fall back to the schema default. */
+    values: Record<string, unknown>;
+    client: CachedClient;
+    responseMaxBytes: number;
+    /** Used only to phrase the timeout message — the scheduler enforces the deadline itself. */
+    maxSolveDurationMs: number;
+    /** Client's `Accept-Encoding`; gzip is applied only when it advertises `gzip`. */
+    acceptEncoding: string;
+    /**
+     * Request abort signal, forwarded to the scheduler so a client disconnect
+     * cancels the upstream compute call. Its `aborted` flag also disambiguates a
+     * client disconnect from the scheduler's own deadline firing.
+     */
+    signal: AbortSignal;
+    /**
+     * Wall-clock origin (`performance.now()` captured at the top of the request)
+     * so the pipeline's `load`/`total` phase timings line up with the caller's
+     * pre-solve prep.
+     */
+    loadStartMs: number;
+    /** Pre-solve "load" phase duration the caller already measured (auth + DB + fetch). */
+    defLoadMs: number;
+    /**
+     * Pre-solve prep sub-phase marks (`[label, ms]`), surfaced verbatim as `p_*`
+     * Server-Timing entries.
+     */
+    prepMarks?: [string, number][];
+}
+/** Phase timings the pipeline measured; the caller uses them for debug logging. */
+interface SolvePhaseMetrics {
+    treeBuildMs: number;
+    solveMs: number;
+    serializeMs: number;
+    gzipMs: number;
+    serverTotalMs: number;
+    serializedBytes: number;
+    /** Null when compression was skipped. */
+    compressedBytes: number | null;
+}
+/** A ready-to-send response: body + headers + the solve result + phase metrics. */
+interface SolveEnvelope {
+    /** A gzip `Uint8Array` when `encoding === 'gzip'`, else the JSON string. */
+    body: string | Uint8Array;
+    encoding?: 'gzip';
+    headers: Record<string, string>;
+    result: GrasshopperComputeResponse;
+    metrics: SolvePhaseMetrics;
+}
+/**
+ * Discriminated result. `ok` carries the envelope; every other variant names an
+ * expected failure the transport maps to a status code (the app route maps
+ * timeout→504, client_abort→499, too_large→413, shed→503+Retry-After;
+ * `compute_error` re-surfaces the original error for the generic 500/503 path).
+ * `durationMs` on the error variants is the solve wall time up to the failure,
+ * for the metric record.
+ */
+type SolveOutcome = {
+    kind: 'ok';
+    envelope: SolveEnvelope;
+    solveMs: number;
+    errorCount: number;
+    warningCount: number;
+} | {
+    kind: 'timeout';
+    durationMs: number;
+    message: string;
+} | {
+    kind: 'client_abort';
+    durationMs: number;
+} | {
+    kind: 'too_large';
+}
+/**
+ * Scheduler backpressure shed the solve before it executed — the per-server
+ * queue was full (`QUEUE_FULL`) or it sat queued past the wait deadline
+ * (`QUEUE_TIMEOUT`). Retryable: the route maps this to 503 + `Retry-After`.
+ * `retryAfterSeconds` is a suggested backoff hint for the client.
+ */
+ | {
+    kind: 'shed';
+    durationMs: number;
+    reason: 'queue_full' | 'queue_timeout';
+    retryAfterSeconds: number;
+    message: string;
+} | {
+    kind: 'compute_error';
+    durationMs: number;
+    error: unknown;
+};
+/**
+ * Build the transformed input tree — the exact object handed to the scheduler.
+ * `runSolvePipeline` calls this itself; a caller only needs it directly to see
+ * the tree before the pipeline runs (see {@link SolvePipelineArgs.inputTree}).
+ */
+declare function buildSolveInputTree(inputs: PipelineInput[], values: Record<string, unknown>): DataTree[];
+declare function runSolvePipeline(args: SolvePipelineArgs): Promise<SolveOutcome>;
+/**
+ * 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}. That
+ * envelope's wire form is baked from the FIRST caller's `Accept-Encoding`, so a
+ * later waiter with a different `Accept-Encoding` would otherwise get a body
+ * labelled with the wrong encoding (`Vary` can't help — this is one object
+ * shared across waiters, not a cache lookup). Encoding is deliberately not part
+ * 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.
+ */
+declare function adaptEnvelopeToEncoding(envelope: SolveEnvelope, acceptEncoding: string): {
+    body: string | Uint8Array;
+    headers: Record<string, string>;
+};
+
+/**
+ * Adapt a persisted `SchemaInput` into `@selvajs/compute`'s raw `InputParamSchema`
+ * and let its `processInput` produce the typed `InputParam`. `values`/`acceptedFormats`
+ * are absent on `SchemaInput` (they live on the layout item's config), so
+ * valueList/file inputs fall back to carrying the selected value with no option
+ * list — the same value that reaches Grasshopper.
+ */
+declare function transformInputParameter(input: SchemaInput & {
+    minimum?: number;
+    maximum?: number;
+    stepSize?: number;
+}, value: unknown): InputParam;
+
+/**
+ * In-process single-flight — dogpile protection for every solve.
+ *
+ * Deliberately NOT conditional on a result cache being configured: the dogpile is
+ * worst precisely when nothing else is caching (N concurrent identical solves each
+ * paying a full Rhino round trip — the scheduler has no in-flight coalescing of its
+ * own, and Rhino's `cachesolve` still costs a round trip per repeat). Gating this on
+ * cache configuration, as an earlier version did, turned it off in exactly the
+ * deployments most exposed to a cold-key stampede (hot public definition + a deploy).
+ *
+ * In-process only, sitting above `ISolveResultCache` (per app instance). A
+ * cross-instance lease (Redis `SET NX`) is a later backend capability.
+ *
+ * Correctness note: the shared promise resolves to ONE value for all waiters, so
+ * the wrapped work must return an immutable / independently-serializable result
+ * (the solve pipeline's envelope is safe to share by reference here because the
+ * app serializes it per response).
+ */
+interface SolveCacheSingleFlight {
+    /**
+     * Run `work` under `key`, coalescing concurrent identical calls: the first
+     * caller executes, overlapping callers for the same key await the same promise
+     * and result, and the key is freed as soon as it settles.
+     *
+     * `onWaiterJoined` fires on the OWNER's call each time another caller joins its
+     * flight — ownership changes what the owner's abort signal means (a solo run
+     * may cancel on its own client's disconnect, a shared one may not, or it would
+     * 499 every waiter). Never fires for a joining caller, and never after `work`
+     * settles.
+     */
+    run<T>(key: string, work: () => Promise<T>, onWaiterJoined?: () => void): Promise<T>;
+    /** Number of keys currently in flight (observability / tests). */
+    inFlight(): number;
+}
+interface SolveCacheSingleFlightOptions {
+    /**
+     * Fired when a caller joins an already-in-flight key instead of running its
+     * own work — the coalescing win this module exists for, otherwise invisible.
+     */
+    onJoin?: (key: string) => void;
+}
+declare function createSolveCacheSingleFlight(options?: SolveCacheSingleFlightOptions): SolveCacheSingleFlight;
+
+export { type ByteCacheRef, type ByteCacheStats, type ByteRefOutcome, COMPUTE_CONTRACT_VERSION, COMPUTE_VERSION_HEADER, type CachedClient, type ClientCache, type ClientCacheConfig, type DefinitionByteCache, type PipelineInput, type ResolvedServer, type ServerIdentity, type SolveCacheSingleFlight, type SolveCacheSingleFlightOptions, type SolveCacheStats, type SolveEnvelope, type SolveOutcome, type SolvePhaseMetrics, type SolvePipelineArgs, adaptEnvelopeToEncoding, buildSolveInputTree, createClientCache, createDefinitionByteCache, createSolveCacheSingleFlight, runSolvePipeline, serverIdentity, transformInputParameter };