@selvajs/server 1.0.0-beta.1 → 1.0.0-beta.2

package/dist/compute/idempotency.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Idempotency store for the solve endpoint: a repeat of the same request within
+ * the TTL replays the first response instead of re-solving.
+ *
+ * **This absorbs client retries; it is not a result cache.** The TTL is short
+ * and the store is process-local, so a retry that lands on another instance
+ * (or after the TTL) re-solves. That is acceptable — a duplicate solve costs
+ * compute, not correctness. What it must never do is return one caller's result
+ * to another, hence the caller identity in the key.
+ *
+ * Concurrency matters more than the hit rate. A client that retries on timeout
+ * usually retries *while the first solve is still running*, so the store holds a
+ * **promise**, reserved before the work starts: the second request awaits the
+ * first rather than starting a second solve. A reservation that rejects is
+ * dropped, so a failed solve is retryable rather than a cached error.
+ *
+ * Bounded the same way as the rate limiter: amortized sweep plus a hard cap, both
+ * driven by `run` rather than a timer — a timer would keep the event loop alive
+ * and give this module a lifecycle its callers don't have.
+ */
+export interface IdempotencyStoreConfig {
+    /** How long a completed response stays replayable, in ms. */
+    ttlMs: number;
+    /**
+     * Max retained entries. Once live entries exceed this, the ones nearest
+     * expiry are evicted. Evicting only costs a re-solve on a retry, so size this
+     * above the plausible number of in-flight + recent keys.
+     */
+    maxKeys?: number;
+    /**
+     * How often (ms) to sweep expired entries, amortized onto `run`. Defaults to
+     * `ttlMs`. `0` disables the sweep, leaving only the cap (test seam).
+     */
+    sweepIntervalMs?: number;
+}
+/** Default {@link IdempotencyStoreConfig.maxKeys}. */
+export declare const DEFAULT_IDEMPOTENCY_MAX_KEYS = 10000;
+export interface IdempotencyOutcome<T> {
+    value: T;
+    /** True when this call awaited an existing entry rather than running `fn`. */
+    replayed: boolean;
+}
+export interface IdempotencyStore<T> {
+    /**
+     * Run `fn` under `key`, or join/replay the entry already stored there.
+     *
+     * The entry is reserved before `fn` starts, so a concurrent retry awaits the
+     * first run instead of starting its own. A rejection drops the reservation.
+     */
+    run(key: string, fn: () => Promise<T>): Promise<IdempotencyOutcome<T>>;
+    /** Test seam — wipes in-memory state. Production code never calls this. */
+    reset(): void;
+    /** Retained entry count, including any not yet swept. For tests/observability. */
+    size(): number;
+    readonly config: Readonly<IdempotencyStoreConfig>;
+}
+/**
+ * Build a process-local idempotency store. `T` is whatever the caller replays;
+ * the solve route stores a serialized response snapshot rather than a `Response`,
+ * because a `Response` body can only be read once.
+ */
+export declare function createIdempotencyStore<T>(config: IdempotencyStoreConfig): IdempotencyStore<T>;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/compute/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../src/compute/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,sBAAsB;IACtC,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,sDAAsD;AACtD,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACpC,KAAK,EAAE,CAAC,CAAC;IACT,8EAA8E;IAC9E,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC;IAClC;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;IACvE,2EAA2E;IAC3E,KAAK,IAAI,IAAI,CAAC;IACd,kFAAkF;IAClF,IAAI,IAAI,MAAM,CAAC;IACf,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,sBAAsB,CAAC,CAAC;CAClD;AAYD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,MAAM,EAAE,sBAAsB,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAwE7F"}

package/dist/compute/idempotency.js

@@ -0,0 +1,97 @@
+/**
+ * Idempotency store for the solve endpoint: a repeat of the same request within
+ * the TTL replays the first response instead of re-solving.
+ *
+ * **This absorbs client retries; it is not a result cache.** The TTL is short
+ * and the store is process-local, so a retry that lands on another instance
+ * (or after the TTL) re-solves. That is acceptable — a duplicate solve costs
+ * compute, not correctness. What it must never do is return one caller's result
+ * to another, hence the caller identity in the key.
+ *
+ * Concurrency matters more than the hit rate. A client that retries on timeout
+ * usually retries *while the first solve is still running*, so the store holds a
+ * **promise**, reserved before the work starts: the second request awaits the
+ * first rather than starting a second solve. A reservation that rejects is
+ * dropped, so a failed solve is retryable rather than a cached error.
+ *
+ * Bounded the same way as the rate limiter: amortized sweep plus a hard cap, both
+ * driven by `run` rather than a timer — a timer would keep the event loop alive
+ * and give this module a lifecycle its callers don't have.
+ */
+/** Default {@link IdempotencyStoreConfig.maxKeys}. */
+export const DEFAULT_IDEMPOTENCY_MAX_KEYS = 10_000;
+/**
+ * Build a process-local idempotency store. `T` is whatever the caller replays;
+ * the solve route stores a serialized response snapshot rather than a `Response`,
+ * because a `Response` body can only be read once.
+ */
+export function createIdempotencyStore(config) {
+    const ttlMs = Math.max(0, Math.floor(config.ttlMs));
+    const maxKeys = Math.max(1, Math.floor(config.maxKeys ?? DEFAULT_IDEMPOTENCY_MAX_KEYS));
+    const sweepIntervalMs = Math.max(0, Math.floor(config.sweepIntervalMs ?? ttlMs));
+    const resolvedConfig = Object.freeze({
+        ...config,
+        ttlMs,
+        maxKeys,
+        sweepIntervalMs
+    });
+    const entries = new Map();
+    let nextSweepAt = Number.POSITIVE_INFINITY;
+    function maybeSweep(now, headroom = 0) {
+        const budget = Math.max(0, maxKeys - headroom);
+        const dueForSweep = sweepIntervalMs > 0 && now >= nextSweepAt;
+        if (!dueForSweep && entries.size <= budget)
+            return;
+        for (const [key, entry] of entries) {
+            if (entry.expiresAt !== null && now > entry.expiresAt)
+                entries.delete(key);
+        }
+        if (sweepIntervalMs > 0)
+            nextSweepAt = now + sweepIntervalMs;
+        if (entries.size > budget) {
+            // In-flight entries sort last: evicting one would orphan the retries
+            // awaiting it, so they are given up only when nothing else is left.
+            const byExpiryAsc = [...entries.entries()].sort((a, b) => (a[1].expiresAt ?? Infinity) - (b[1].expiresAt ?? Infinity));
+            for (let i = 0; i < byExpiryAsc.length - budget; i++)
+                entries.delete(byExpiryAsc[i][0]);
+        }
+    }
+    return {
+        config: resolvedConfig,
+        async run(key, fn) {
+            const now = Date.now();
+            const existing = entries.get(key);
+            if (existing && (existing.expiresAt === null || now <= existing.expiresAt)) {
+                return { value: await existing.promise, replayed: true };
+            }
+            maybeSweep(now, entries.has(key) ? 0 : 1);
+            const promise = fn();
+            const entry = { promise, expiresAt: null };
+            entries.set(key, entry);
+            if (sweepIntervalMs > 0 && nextSweepAt === Number.POSITIVE_INFINITY) {
+                nextSweepAt = now + sweepIntervalMs;
+            }
+            try {
+                const value = await promise;
+                entry.expiresAt = Date.now() + ttlMs;
+                return { value, replayed: false };
+            }
+            catch (err) {
+                // A failed solve is retryable — drop the reservation rather than
+                // replaying the error to every retry for the whole TTL. Only drop our
+                // own entry: a later `run` may already have replaced it.
+                if (entries.get(key) === entry)
+                    entries.delete(key);
+                throw err;
+            }
+        },
+        reset() {
+            entries.clear();
+            nextSweepAt = Number.POSITIVE_INFINITY;
+        },
+        size() {
+            return entries.size;
+        }
+    };
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/compute/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../../src/compute/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAkBH,sDAAsD;AACtD,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAC;AAiCnD;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAI,MAA8B;IACvE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACpD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,IAAI,4BAA4B,CAAC,CAAC,CAAC;IACxF,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,eAAe,IAAI,KAAK,CAAC,CAAC,CAAC;IACjF,MAAM,cAAc,GAAqC,MAAM,CAAC,MAAM,CAAC;QACtE,GAAG,MAAM;QACT,KAAK;QACL,OAAO;QACP,eAAe;KACf,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC5C,IAAI,WAAW,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAE3C,SAAS,UAAU,CAAC,GAAW,EAAE,QAAQ,GAAG,CAAC;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC,CAAC;QAC/C,MAAM,WAAW,GAAG,eAAe,GAAG,CAAC,IAAI,GAAG,IAAI,WAAW,CAAC;QAC9D,IAAI,CAAC,WAAW,IAAI,OAAO,CAAC,IAAI,IAAI,MAAM;YAAE,OAAO;QAEnD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;YACpC,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS;gBAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5E,CAAC;QACD,IAAI,eAAe,GAAG,CAAC;YAAE,WAAW,GAAG,GAAG,GAAG,eAAe,CAAC;QAE7D,IAAI,OAAO,CAAC,IAAI,GAAG,MAAM,EAAE,CAAC;YAC3B,qEAAqE;YACrE,oEAAoE;YACpE,MAAM,WAAW,GAAG,CAAC,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAC9C,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,QAAQ,CAAC,CACrE,CAAC;YACF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE;gBAAE,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACzF,CAAC;IACF,CAAC;IAED,OAAO;QACN,MAAM,EAAE,cAAc;QACtB,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,EAAoB;YAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACvB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,QAAQ,IAAI,CAAC,QAAQ,CAAC,SAAS,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC5E,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;YAC1D,CAAC;YAED,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAE1C,MAAM,OAAO,GAAG,EAAE,EAAE,CAAC;YACrB,MAAM,KAAK,GAAa,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;YACrD,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACxB,IAAI,eAAe,GAAG,CAAC,IAAI,WAAW,KAAK,MAAM,CAAC,iBAAiB,EAAE,CAAC;gBACrE,WAAW,GAAG,GAAG,GAAG,eAAe,CAAC;YACrC,CAAC;YAED,IAAI,CAAC;gBACJ,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC;gBAC5B,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;gBACrC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;YACnC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACd,iEAAiE;gBACjE,sEAAsE;gBACtE,yDAAyD;gBACzD,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK;oBAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACpD,MAAM,GAAG,CAAC;YACX,CAAC;QACF,CAAC;QACD,KAAK;YACJ,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,WAAW,GAAG,MAAM,CAAC,iBAAiB,CAAC;QACxC,CAAC;QACD,IAAI;YACH,OAAO,OAAO,CAAC,IAAI,CAAC;QACrB,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/compute/index.d.ts

@@ -1,5 +1,6 @@
 export { resolveComputeLimits, readPositiveInt, readNonNegativeInt, readBool, type ComputeLimits, type EnvRecord } from './limits.js';
 export { createComputeRateLimiter, DEFAULT_MAX_KEYS, type ComputeRateLimiter, type ComputeRateLimiterConfig, type RateLimitResult } from './rate-limit.js';
+export { createIdempotencyStore, DEFAULT_IDEMPOTENCY_MAX_KEYS, type IdempotencyStore, type IdempotencyStoreConfig, type IdempotencyOutcome } from './idempotency.js';
 export { isSafeRemoteDefinitionUrl, assertSafeRemoteDefinitionUrl } from './safe-url.js';
 export { createRemoteDefinitionFetcher, readBodyWithCap, type RemoteDefinitionFetcher, type RemoteDefinitionConfig } from './remote-definition.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/compute/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/compute/index.ts"],"names":[],"mappings":"AAaA,OAAO,EACN,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,QAAQ,EACR,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,wBAAwB,EACxB,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,yBAAyB,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AAEzF,OAAO,EACN,6BAA6B,EAC7B,eAAe,EACf,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/compute/index.ts"],"names":[],"mappings":"AAaA,OAAO,EACN,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,QAAQ,EACR,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,wBAAwB,EACxB,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACN,sBAAsB,EACtB,4BAA4B,EAC5B,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,yBAAyB,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AAEzF,OAAO,EACN,6BAA6B,EAC7B,eAAe,EACf,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,MAAM,wBAAwB,CAAC"}

package/dist/compute/index.js

@@ -12,6 +12,7 @@
 // depend on `@selvajs/solve`.
 export { resolveComputeLimits, readPositiveInt, readNonNegativeInt, readBool } from './limits.js';
 export { createComputeRateLimiter, DEFAULT_MAX_KEYS } from './rate-limit.js';
+export { createIdempotencyStore, DEFAULT_IDEMPOTENCY_MAX_KEYS } from './idempotency.js';
 export { isSafeRemoteDefinitionUrl, assertSafeRemoteDefinitionUrl } from './safe-url.js';
 export { createRemoteDefinitionFetcher, readBodyWithCap } from './remote-definition.js';
 //# sourceMappingURL=index.js.map

package/dist/compute/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/compute/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,kGAAkG;AAClG,mGAAmG;AACnG,oBAAoB;AACpB,EAAE;AACF,6FAA6F;AAC7F,qGAAqG;AACrG,mGAAmG;AACnG,oGAAoG;AACpG,kGAAkG;AAClG,8BAA8B;AAE9B,OAAO,EACN,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,QAAQ,EAGR,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,wBAAwB,EACxB,gBAAgB,EAIhB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,yBAAyB,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AAEzF,OAAO,EACN,6BAA6B,EAC7B,eAAe,EAGf,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/compute/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,kGAAkG;AAClG,mGAAmG;AACnG,oBAAoB;AACpB,EAAE;AACF,6FAA6F;AAC7F,qGAAqG;AACrG,mGAAmG;AACnG,oGAAoG;AACpG,kGAAkG;AAClG,8BAA8B;AAE9B,OAAO,EACN,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,QAAQ,EAGR,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,wBAAwB,EACxB,gBAAgB,EAIhB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACN,sBAAsB,EACtB,4BAA4B,EAI5B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,yBAAyB,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AAEzF,OAAO,EACN,6BAA6B,EAC7B,eAAe,EAGf,MAAM,wBAAwB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selvajs/server",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "description": "Transport-agnostic server building blocks for apps built on the Selva engine (limits, rate limiting, SSRF guard, remote-definition fetch, definition service + render loader); the solve core lives in @selvajs/solve/server",
   "license": "MIT",
   "author": "VektorNode",