@wmind/site-core 0.1.0 → 0.1.1

package/README.md

@@ -4,8 +4,8 @@ The product-independent core of the site SDK: an HTTP transport, request-driven
 cache model, an atomic-swap snapshot, webhooks and status. Product modules (`@wmind/site-entitycms`,
 `@wmind/site-legal`) build on it; a site normally installs a module, not this package alone.
 
-- **Status:** MIT, final name. Version `0.0.0`, `private` and unpublished until the publishing plan
-  (changesets, the `wmind` npm organisation, a manual publish workflow).
+- **Status:** MIT, final name, public on npm. Version `0.1.1`: the two known limits of `0.1.0`
+  fixed, one option added (`storeTimeoutMs`), nothing removed or changed in shape.
 - **Runs on:** Node 22, browsers and edge runtimes (Cloudflare Workers, Vercel, Netlify). Web
   platform APIs only (`fetch`, `Request`, `Response`, `crypto.subtle`, `AbortController`); zero
   runtime dependencies.
@@ -18,8 +18,11 @@ cache model, an atomic-swap snapshot, webhooks and status. Product modules (`@wm
 1. **Requests drive refreshes.** No timer ever starts a refresh or an HTTP call. A copy past its
    freshness is refreshed when a request asks for it; the flight is shared by every concurrent
    request for the key (one per key and process) and is never cancelled. A flight that has not
-   settled after `refreshMaxMs` (60 s) is abandoned by the next request, which starts a new one;
-   the abandoned one writes nothing when it settles.
+   settled after `refreshMaxMs` (60 s) is abandoned by the next request, which starts a new one.
+   The abandoned one records no error when it settles, and its value is stored only when no newer
+   flight of the key has landed and the stored copy is older than its start: a loader slower than
+   `refreshMaxMs` still lands, and never over a newer copy or a copy a 404 deleted. Set
+   `refreshMaxMs` above the loader's worst case anyway, or a slow loader runs twice at a time.
 2. **Budgets, not waits.** A request with a copy waits for the refresh at most `refreshBudgetMs`
    (default 0: it answers with the copy at once); a request without one waits at most
    `coldBudgetMs` (10 s), then gets `Unavailable` `refresh_budget_exceeded`. The refresh goes on and
@@ -48,16 +51,16 @@ cache model, an atomic-swap snapshot, webhooks and status. Product modules (`@wm
 
 ## Known limits
 
-- **A loader slower than `refreshMaxMs` never lands.** Each request past `refreshMaxMs` (60 s)
-  abandons the running flight and starts another, and an abandoned flight writes nothing, so a
-  loader that always takes longer keeps restarting and its copy never moves. `httpResource` is
-  bounded by the transport's 30 s deadline and is not affected; a loader making several calls in a
-  row is. Set `refreshMaxMs` above the loader's worst case. A later version may let an abandoned
-  flight still write when the stored copy is older than its start.
-- **A store call that never settles blocks its key.** Writes to one key are queued in process, so a
-  `CacheStore` (or `KvBackend`) call that never settles leaves that key's later refresh writes and
-  `invalidate()` waiting for good; other keys are unaffected. Give the backend its own timeout. A
-  later version may bound store calls with a budget.
+- **Fixed in 0.1.1.** A loader slower than `refreshMaxMs` no longer restarts forever without
+  landing (rule 1), and a store call that never settles no longer blocks its key: every
+  `CacheStore` call (`get`, `set`, `delete`) is bounded by `storeTimeoutMs` (5 s), after which it
+  fails as `store_unavailable` (`details.reason: 'timeout'`) and the key's write queue moves on.
+- **A store call cannot be cancelled.** A write that takes longer than `storeTimeoutMs` and then
+  completes can land after a later write of the same key: until the next refresh (at most
+  `fullEveryMs` later) it can leave an older value in place, bring back a copy a 404 had deleted, or
+  undo an invalidation. Keep `storeTimeoutMs` well above the store's normal latency (it is capped at
+  2,147,483,647 ms, the largest delay a platform timer honours).
+- **Instances sharing a KV store are not serialised** (rule 7).
 
 ## Quick start
 
@@ -153,8 +156,8 @@ Codes this package mints:
 | `network_error`, `timeout` | `Unavailable` | no HTTP answer (status 0) |
 | `unexpected_response` | by status (`Unavailable` for a 404) | an answer that is not the JSON error envelope, a 2xx that is not JSON, a 304 to a request without `If-None-Match` |
 | `refresh_budget_exceeded` | `Unavailable` | no servable copy within the budget; `details.reason` `cold`, `max_stale` or `preview` |
-| `store_unavailable` | `Unavailable` | the cache store failed |
-| `refresh_abandoned` | `Unavailable` (status only) | a flight older than `refreshMaxMs` was replaced |
+| `store_unavailable` | `Unavailable` | the cache store failed, or a call did not settle within `storeTimeoutMs` (`details.reason: 'timeout'`) |
+| `refresh_abandoned` | `Unavailable` (status only) | a flight older than `refreshMaxMs` was replaced (its late value may still land) |
 | `store_unserialisable` | `SiteSdkError` | a value a KV store cannot hold as JSON |
 | `unexpected_not_modified` | `SiteSdkError` (304) | a loader answered `not_modified` with no copy |
 | `preview_unsupported` | `SiteSdkError` | a preview of an `httpResource` with no `preview` |

package/dist/site.d.ts

@@ -4,6 +4,7 @@ import { type CacheRecord, type CacheStore } from './store.js';
 export declare const DEFAULT_COLD_BUDGET_MS = 10000;
 export declare const DEFAULT_REFRESH_MAX_MS = 60000;
 export declare const DEFAULT_MAX_ERROR_PAUSE_MS = 600000;
+export declare const DEFAULT_STORE_TIMEOUT_MS = 5000;
 export interface SiteCacheOptions {
     tenant: string;
     /** Default `new MemoryCacheStore()`. */
@@ -29,6 +30,12 @@ export interface SiteCacheOptions {
      * cannot freeze it. `errorPauseMs` itself is never cut.
      */
     maxErrorPauseMs?: number;
+    /**
+     * How long one store call (`get`, `set`, `delete`) may take (5_000). A call that has not settled
+     * by then fails as `Unavailable` `store_unavailable` (`details.reason: 'timeout'`) and the key's
+     * write queue moves on; the call itself cannot be cancelled and runs on.
+     */
+    storeTimeoutMs?: number;
     /** A product prefix for every store key (`legal`, `cms`), so modules can share a store. */
     namespace?: string;
 }

package/dist/site.js

@@ -7,14 +7,19 @@
  *
  * A flight never rejects: it resolves to `{ ok, value | error }`, and its failure goes to
  * `status()` and starts the error pause. A flight older than `refreshMaxMs` is abandoned by the
- * next request (review I1): it writes nothing and records nothing when it settles.
+ * next request (review I1): it records nothing when it settles, and its success is written only
+ * when no newer flight of the key has landed and the stored copy is older than its start
+ * (re-review M-a, 0.1.1), so a loader slower than `refreshMaxMs` still lands and never overwrites
+ * a newer copy.
  *
  * Writes to one key are queued in process (review I3): a refresh's re-read and write, an
  * invalidation's read and write and a NotFound's delete never interleave, so an invalidation is
  * never lost and a deleted copy is never written back. An invalidation is also kept in process
- * from the moment `invalidate()` is called. Instances sharing a KV store are not serialised: the
- * store has no compare-and-set, so an invalidation written by one instance can be overwritten by a
- * refresh of another that re-read before it; the periodic full refresh bounds that (§3.2).
+ * from the moment `invalidate()` is called. Every store call is bounded by `storeTimeoutMs`
+ * (re-review M-d, 0.1.1): one that has not settled by then fails as `store_unavailable` and the
+ * queue moves on. Instances sharing a KV store are not serialised: the store has no
+ * compare-and-set, so an invalidation written by one instance can be overwritten by a refresh of
+ * another that re-read before it; the periodic full refresh bounds that (§3.2).
  */
 import { freshForMs, isStorable, parseCacheControl } from './cache-control.js';
 import { NotFound, SiteSdkError, Unavailable } from './errors.js';
@@ -25,6 +30,12 @@ import { MemoryCacheStore, storeKey } from './store.js';
 export const DEFAULT_COLD_BUDGET_MS = 10_000;
 export const DEFAULT_REFRESH_MAX_MS = 60_000;
 export const DEFAULT_MAX_ERROR_PAUSE_MS = 600_000;
+export const DEFAULT_STORE_TIMEOUT_MS = 5_000;
+/** A store call that did not settle within `storeTimeoutMs` (re-review M-d); never leaves the module. */
+class StoreTimeout extends Error {
+}
+/** The start of the refresh that last produced or confirmed the record, full or partial. */
+const lastRefreshOf = (record) => Math.max(record.lastFullAt, record.lastPartialAt ?? record.lastFullAt);
 /** A positive finite number, else a TypeError naming the option. */
 function positiveMs(name, value) {
     if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
@@ -32,6 +43,16 @@ function positiveMs(name, value) {
     }
     return value;
 }
+/** The largest delay a platform timer honours: above it Node fires after 1 ms. */
+const MAX_TIMER_MS = 2_147_483_647;
+/** A duration that backs a timer: positive, finite and at most `MAX_TIMER_MS`. */
+function timerMs(name, value) {
+    const ms = positiveMs(name, value);
+    if (ms > MAX_TIMER_MS) {
+        throw new TypeError(`createSiteCache: ${name} must be at most ${MAX_TIMER_MS} milliseconds`);
+    }
+    return ms;
+}
 export function createSiteCache(options) {
     const { tenant } = options;
     if (typeof tenant !== 'string' || tenant === '') {
@@ -44,6 +65,7 @@ export function createSiteCache(options) {
     const maxStaleMs = options.maxStaleMs;
     const refreshMaxMs = positiveMs('refreshMaxMs', options.refreshMaxMs ?? DEFAULT_REFRESH_MAX_MS);
     const maxErrorPauseMs = positiveMs('maxErrorPauseMs', options.maxErrorPauseMs ?? DEFAULT_MAX_ERROR_PAUSE_MS);
+    const storeTimeoutMs = timerMs('storeTimeoutMs', options.storeTimeoutMs ?? DEFAULT_STORE_TIMEOUT_MS);
     const { namespace } = options;
     if (namespace !== undefined && (typeof namespace !== 'string' || namespace === '')) {
         throw new TypeError('createSiteCache: namespace must be a non-empty string when set');
@@ -100,13 +122,32 @@ export function createSiteCache(options) {
         entry.error = { at, error };
         noteError(entry, error, at);
     };
-    const storeUnavailable = (entry, operation) => 
+    /**
+     * One store call, bounded by `storeTimeoutMs` (re-review M-d): a call that has not settled by
+     * then throws `StoreTimeout`, so the key's queue moves on. A synchronous throw is a rejection.
+     */
+    const storeCall = async (call) => {
+        const settled = await within(new Promise((resolve) => resolve(call())), storeTimeoutMs);
+        if (settled === null)
+            throw new StoreTimeout();
+        if (settled.status === 'rejected')
+            throw settled.reason;
+        return settled.value;
+    };
+    const storeUnavailable = (entry, operation, cause) => 
     // The backend's own message is left out: it can name a host or a credential of the store.
-    new Unavailable({
-        code: 'store_unavailable',
-        status: 0,
-        message: `${entry.key}: the cache store could not be ${operation}`,
-    });
+    cause instanceof StoreTimeout
+        ? new Unavailable({
+            code: 'store_unavailable',
+            status: 0,
+            message: `${entry.key}: the cache store could not be ${operation} within ${storeTimeoutMs} ms`,
+            details: { reason: 'timeout', storeTimeoutMs },
+        })
+        : new Unavailable({
+            code: 'store_unavailable',
+            status: 0,
+            message: `${entry.key}: the cache store could not be ${operation}`,
+        });
     const budgetExceeded = (entry, reason, budgetMs) => new Unavailable({
         code: 'refresh_budget_exceeded',
         status: 0,
@@ -139,14 +180,20 @@ export function createSiteCache(options) {
         const freshFor = cacheControl ? freshForMs(cacheControl) : (previous?.freshForMs ?? null);
         const storable = !cacheControl || isStorable(cacheControl);
         await locked(entry, async () => {
-            // An abandoned flight (review I1) hands its value to the requests that joined it and
-            // writes nothing: a newer flight owns the key.
-            if (entry.flight !== flight)
+            // The flight that owns the key writes its answer. An abandoned one (review I1) hands its
+            // value to the requests that joined it, records nothing, and writes only when no newer
+            // flight has landed and the stored copy is older than its start (re-review M-a): a loader
+            // slower than `refreshMaxMs` still lands, never over a newer copy or a NotFound's delete.
+            const owner = entry.flight === flight;
+            if (!owner && flight.gen <= entry.landedGen)
                 return;
             const t = now();
             /** An invalidation counts when it came at or after this flight's start, and not from the future. */
             const counts = (at) => typeof at === 'number' && at >= flight.startedAt && at <= t;
             if (!storable) {
+                if (!owner)
+                    return;
+                entry.landedGen = flight.gen;
                 entry.error = null;
                 absorbInvalidation(entry, flight.startedAt, t);
                 return;
@@ -155,11 +202,16 @@ export function createSiteCache(options) {
             // survives it (R6, review I3).
             let current = null;
             try {
-                current = await store.get(entry.storeKey);
+                current = await storeCall(() => store.get(entry.storeKey));
             }
             catch {
+                // The owner writes anyway; an abandoned flight cannot tell whether the copy is newer.
+                if (!owner)
+                    return;
                 current = null;
             }
+            if (!owner && current !== null && lastRefreshOf(current) >= flight.startedAt)
+                return;
             const marks = [current?.invalidatedAt, entry.pendingInvalidationAt].filter(counts);
             const record = {
                 value,
@@ -169,16 +221,23 @@ export function createSiteCache(options) {
                 invalidatedAt: marks.length > 0 ? Math.max(...marks) : null,
                 freshForMs: freshFor,
             };
+            // Before the write: a write that fails or times out may still land, and no older flight
+            // may follow it.
+            entry.landedGen = flight.gen;
             try {
-                await store.set(entry.storeKey, record);
+                await storeCall(() => store.set(entry.storeKey, record));
             }
             catch (error) {
-                // The waiting requests still get the value; the failure pauses like any other. An error
-                // the SDK minted (store_unserialisable) is kept; a backend's own error is never shown.
-                refreshFailed(entry, error instanceof SiteSdkError ? error : storeUnavailable(entry, 'written'), now());
+                // The waiting requests still get the value; the owner's failure pauses like any other. An
+                // error the SDK minted (store_unserialisable) is kept; a backend's own error is never shown.
+                if (owner) {
+                    refreshFailed(entry, error instanceof SiteSdkError ? error : storeUnavailable(entry, 'written', error), now());
+                }
                 return;
             }
-            entry.error = null;
+            // A late landing clears only an error older than its start: a newer flight's pause stays.
+            if (owner || (entry.error !== null && entry.error.at < flight.startedAt))
+                entry.error = null;
             absorbInvalidation(entry, flight.startedAt, t);
             mirror(entry, record);
         });
@@ -194,7 +253,13 @@ export function createSiteCache(options) {
             entry.pendingInvalidationAt = null;
     };
     const startFlight = (entry, kind, previous, startedAt, ctx) => {
-        const flight = { kind, startedAt, promise: Promise.resolve({ ok: true, value: null }) };
+        entry.flights += 1;
+        const flight = {
+            kind,
+            startedAt,
+            gen: entry.flights,
+            promise: Promise.resolve({ ok: true, value: null }),
+        };
         const { definition } = entry;
         const load = () => {
             if (kind === 'partial') {
@@ -219,10 +284,12 @@ export function createSiteCache(options) {
                         // The source says the resource is gone: a withdrawn text must not stay online (R5).
                         // Every other error keeps the copy.
                         if (kind === 'full' && error instanceof NotFound) {
+                            // The answer landed even if the delete fails: no older flight writes after it.
+                            entry.landedGen = flight.gen;
                             await locked(entry, async () => {
                                 if (entry.flight !== flight)
                                     return;
-                                await store.delete(entry.storeKey);
+                                await storeCall(() => store.delete(entry.storeKey));
                                 entry.pendingInvalidationAt = null;
                                 mirror(entry, null);
                             }).catch(() => {
@@ -287,18 +354,17 @@ export function createSiteCache(options) {
     const servable = (record, t) => {
         if (maxStaleMs === undefined)
             return true;
-        const last = Math.max(record.lastFullAt, record.lastPartialAt ?? record.lastFullAt);
-        return Math.max(0, t - last) <= maxStaleMs;
+        return Math.max(0, t - lastRefreshOf(record)) <= maxStaleMs;
     };
     const get = async (entry, ctx = {}) => {
         if (ctx.preview !== undefined)
             return previewGet(entry, ctx.preview?.token);
         let record;
         try {
-            record = await store.get(entry.storeKey);
+            record = await storeCall(() => store.get(entry.storeKey));
         }
-        catch {
-            const error = storeUnavailable(entry, 'read');
+        catch (cause) {
+            const error = storeUnavailable(entry, 'read', cause);
             noteError(entry, error, now());
             throw error;
         }
@@ -382,10 +448,10 @@ export function createSiteCache(options) {
         await locked(entry, async () => {
             let record;
             try {
-                record = await store.get(entry.storeKey);
+                record = await storeCall(() => store.get(entry.storeKey));
             }
-            catch {
-                const error = storeUnavailable(entry, 'read');
+            catch (cause) {
+                const error = storeUnavailable(entry, 'read', cause);
                 noteError(entry, error, now());
                 throw error;
             }
@@ -396,10 +462,10 @@ export function createSiteCache(options) {
                 invalidatedAt: Math.max(record.invalidatedAt ?? at, at),
             };
             try {
-                await store.set(entry.storeKey, marked);
+                await storeCall(() => store.set(entry.storeKey, marked));
             }
-            catch {
-                const error = storeUnavailable(entry, 'written');
+            catch (cause) {
+                const error = storeUnavailable(entry, 'written', cause);
                 noteError(entry, error, now());
                 throw error;
             }
@@ -438,6 +504,8 @@ export function createSiteCache(options) {
                 storeKey: k,
                 definition: definition,
                 flight: null,
+                flights: 0,
+                landedGen: 0,
                 error: null,
                 chain: Promise.resolve(),
                 pendingInvalidationAt: null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wmind/site-core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Site SDK core: HTTP transport, request-driven refresh, snapshot store, webhooks, status",
   "license": "MIT",
   "repository": {