@oceanmetrics/engine 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.2 (2026-10-23)
+
+- New: `patientFetch(url, init?, { tries = 6, delayMs = 300, maxDelayMs = 4000, onRetry?, retryOn? })`, the one rule for
+  asking an ERDDAP request again when the server drops it (the places page and the indicators viewer each carried a copy).
+  Retried: a network error, a 404 whose body says "Currently unknown datasetID" (the mirror answers the same url 404 and
+  200 by turns), a 429 and a 5xx, after a pause of `delayMs` x the try, capped at `maxDelayMs`. Any other answer, a 4xx
+  included, is returned at once. `init.signal` aborts it at once, between tries too; `onRetry` reports each retry (try,
+  pause, reason, status). After `tries` failed tries it throws a `PatientFetchError` (an `ErddapUnreachable`, so the message
+  names the host and the last status: "erddap.oceanmetrics.io did not answer (HTTP 503 Service Unavailable, 6 tries)"),
+  with `status` and `cause`. Also exported: `isRetryable` (the default rule, for a `retryOn` that adds to it), `UNKNOWN_DATASET`.
+  `fetchRetry` is unchanged. To get a `typeof fetch` for `lobeAxes`, `fetchTimeExtent` and `sliceSource`:
+  `(u, init) => patientFetch(u as string, init)`.
+- Differs from the two app copies on purpose: they returned the last response after the last try; this throws, and only a
+  404 that names the unknown dataset is retried (they retried every 404).
+
 ## 0.1.1 (2026-10-23)
 
 - Fix: `sliceSource().slice()` read the lobes' slabs without the `SELECT DISTINCT` that `runPreview` applies, so where two

package/README.md

@@ -30,6 +30,7 @@ From `oceanmetrics/erddap-places` on 2026-10-23 (app 0.3.12, commit 3b1868a):
 | `src/erddap.ts` | `app/src/lib/erddap.ts` | `.js` import specifiers only |
 | `src/extent.ts` | `app/src/lib/extent.ts` | `.js` import specifiers only |
 | `src/fetchRetry.ts` | `app/src/lib/fetchRetry.ts` | `.js` import specifiers only |
+| `src/patient.ts` | new (0.1.2): the retry the places page and the indicators viewer each wrote | `patientFetch(url, init?, { tries = 6, delayMs, onRetry?, retryOn? })`: asks each request again on a network error, a 404 "Currently unknown datasetID", a 429 or a 5xx; abortable through `init.signal`; throws a `PatientFetchError` (an `ErddapUnreachable` with the last `status`) after `tries` |
 | `src/cells.ts` | `app/src/lib/cells.ts` | nothing (`@oceanmetrics/map` `grid.ts` has its own port of `cellSquares`; `cellPoints` and `placeMapBounds` live here) |
 | `src/dataset.ts` | `app/src/lib/catalog.ts` | the pure functions word for word (`toDataset`, `valueExpr`, `statsTemplate`, `lobeLonSpan`, `resolveDataset` ...); `loadDatasets` (reads the gazetteer's catalog.json) and `linkMismatch` (the app's wording) stay in the app |
 | `src/chunks.ts` | `precompute/src/stats.ts` `window`, `chunks`, `chunkDaysFor`; `precompute/src/targets.ts` `MAX_CHUNK_DAYS`, `MAX_REQUEST_VALUES` | `chunks()` word for word; `chunkDaysFor()` takes the two limits as options (defaulting to 90 and 100,000); `window()` defaults to `'all'` (the precompute's `DAYS`) |

package/dist/index.d.ts

@@ -9,6 +9,8 @@ export { INFO_TIMEOUT_MS, addDays, clampWindow, day, daysBetween, defaultWindow,
 export type { ClampResult, InfoTable, TimeExtent, Window, WindowOpts } from './extent.js';
 export { ErddapUnreachable, fetchRetry, hostOf, mapFailMessage } from './fetchRetry.js';
 export type { RetryOpts } from './fetchRetry.js';
+export { PatientFetchError, UNKNOWN_DATASET, isRetryable, patientFetch } from './patient.js';
+export type { PatientOpts, PatientRetry } from './patient.js';
 export { axisSpacing, cellPoints, cellSquares, indexBounds, normalizeLon, pickCenter, placeMapBounds } from './cells.js';
 export type { CellPoints, CellProps, CellSquares, CellSquaresOptions, LonCenter, ValueCell } from './cells.js';
 export { isCategorical, lobeLonSpan, resolveDataset, statsTemplate, toDataset, toDatasetLon, toLongFormat, valueExpr, valueLabel, } from './dataset.js';

package/dist/index.js

@@ -7,6 +7,7 @@ export { placeLobes } from './lobes.js';
 export { AXIS_TIMEOUT_MS, SLICE_TIMEOUT_MS, constraint, fetchAxis, fetchJsonp, fetchSlab, griddapSliceUrl, griddapUrl, griddapUrls, isParquet, noonZ, parseCsvp, pickFormat, tableConstraint, tableToRows, tabledapPlaceConstraints, tabledapUrl, } from './erddap.js';
 export { INFO_TIMEOUT_MS, addDays, clampWindow, day, daysBetween, defaultWindow, fetchTimeExtent, parseInfoExtent, parseSpacing, spanDays, stepLabel, timeInstant, } from './extent.js';
 export { ErddapUnreachable, fetchRetry, hostOf, mapFailMessage } from './fetchRetry.js';
+export { PatientFetchError, UNKNOWN_DATASET, isRetryable, patientFetch } from './patient.js';
 export { axisSpacing, cellPoints, cellSquares, indexBounds, normalizeLon, pickCenter, placeMapBounds } from './cells.js';
 export { isCategorical, lobeLonSpan, resolveDataset, statsTemplate, toDataset, toDatasetLon, toLongFormat, valueExpr, valueLabel, } from './dataset.js';
 export { MAX_CHUNK_DAYS, MAX_REQUEST_VALUES, chunkDaysFor, chunks, window } from './chunks.js';

package/dist/patient.d.ts

@@ -0,0 +1,51 @@
+import { ErddapUnreachable } from './fetchRetry.js';
+/** the body text ERDDAP sends with a 404 when the dataset is not (yet) on the server that answered */
+export declare const UNKNOWN_DATASET = "Currently unknown datasetID";
+/** one retry about to happen: reported through `onRetry` */
+export interface PatientRetry {
+    /** the try that just failed (1 = the first) */
+    attempt: number;
+    /** tries in all */
+    tries: number;
+    /** the pause before the next try (ms) */
+    delayMs: number;
+    url: string;
+    /** why: "HTTP 503 Service Unavailable", "HTTP 404 (unknown datasetID)" or "network error: Failed to fetch" */
+    reason: string;
+    /** the status that failed the try; absent for a network error */
+    status?: number;
+}
+export interface PatientOpts {
+    /** tries in all (1 = no retry) */
+    tries?: number;
+    /** the pause before the second try (ms); before try n + 1 it is `delayMs * n`, up to `maxDelayMs`. 0 = no pause */
+    delayMs?: number;
+    /** the longest pause (ms) */
+    maxDelayMs?: number;
+    /** called before each pause */
+    onRetry?: (r: PatientRetry) => void;
+    /** whether an answer is to be asked for again; the default is `isRetryable`. It replaces the default, so a caller who
+     *  wants more can call `isRetryable(res)` itself. It reads `res.clone()` if it needs the body; the caller still gets `res` */
+    retryOn?: (res: Response) => boolean | Promise<boolean>;
+    /** for tests */
+    fetchFn?: typeof fetch;
+    wait?: (ms: number, signal?: AbortSignal) => Promise<unknown>;
+}
+/** the last failure after every try: an ErddapUnreachable that also says which status it was (absent: a network error) */
+export declare class PatientFetchError extends ErddapUnreachable {
+    readonly status?: number | undefined;
+    constructor(host: string, reason: string, attempts: number, url: string, status?: number | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * the default rule: a 429 or a 5xx, and a 404 whose body is ERDDAP's "Currently unknown datasetID". Any other 404 is a real
+ * answer (a wrong dataset id, a coordinate out of range) and is not asked for again. The body is read from a clone.
+ */
+export declare function isRetryable(res: Response): Promise<boolean>;
+/**
+ * fetch `url`, asking again when the server drops the request (see the top of this file). Returns the first answer that is
+ * not to be retried (a 2xx, or a 4xx that is the server's own); throws a PatientFetchError after `tries` failed tries.
+ * `init.signal` aborts it at once, between tries too.
+ */
+export declare function patientFetch(url: string | URL, init?: RequestInit, opts?: PatientOpts): Promise<Response>;

package/dist/patient.js

@@ -0,0 +1,97 @@
+// patientFetch: ask each ERDDAP request again, on its own, when the server drops it.
+//
+// the mirror erddap.oceanmetrics.io answers the same url 404 ("Currently unknown datasetID", one backend does not hold the
+// dataset yet) and 200 by turns under load (seen 2026-10-23), and any ERDDAP can answer 429 or a 5xx. retrying each request
+// beats retrying the whole slice: with half the answers dropped, six tries of one request fail one time in 64. this is the
+// one implementation of that rule (the places page and the indicators viewer carried a copy each). fetchRetry stays as it
+// is (a timeout per attempt, a short retry for the engine's own requests); this composes with it by naming the failure the
+// same way: the last failure is an ErddapUnreachable (a PatientFetchError, which also carries the status), so the toast
+// says "host did not answer (HTTP 503 Service Unavailable, 6 tries)" for both.
+//
+// retried: a network error (the browser's TypeError "Failed to fetch"), a 404 whose body says "Currently unknown datasetID",
+// a 429 and a 5xx. every other answer, a 4xx included, is returned at once for the caller to read. the caller's own abort
+// (`init.signal`) stops it at once, between tries too, as the AbortError it is.
+import { ErddapUnreachable, hostOf } from './fetchRetry.js';
+/** the body text ERDDAP sends with a 404 when the dataset is not (yet) on the server that answered */
+export const UNKNOWN_DATASET = 'Currently unknown datasetID';
+/** the last failure after every try: an ErddapUnreachable that also says which status it was (absent: a network error) */
+export class PatientFetchError extends ErddapUnreachable {
+    status;
+    constructor(host, reason, attempts, url, status, options) {
+        super(host, reason, attempts, url);
+        this.status = status;
+        this.name = 'PatientFetchError';
+        if (options?.cause !== undefined)
+            this.cause = options.cause;
+    }
+}
+/**
+ * the default rule: a 429 or a 5xx, and a 404 whose body is ERDDAP's "Currently unknown datasetID". Any other 404 is a real
+ * answer (a wrong dataset id, a coordinate out of range) and is not asked for again. The body is read from a clone.
+ */
+export async function isRetryable(res) {
+    if (res.status === 429 || res.status >= 500)
+        return true;
+    if (res.status !== 404)
+        return false;
+    try {
+        return (await res.clone().text()).includes(UNKNOWN_DATASET);
+    }
+    catch {
+        return false;
+    }
+}
+const abortReason = (signal) => signal.reason ?? new DOMException('aborted', 'AbortError');
+/** a pause that an abort cuts short (rejecting with the abort reason) */
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted)
+        return reject(abortReason(signal));
+    const done = () => { clearTimeout(t); signal?.removeEventListener('abort', onAbort); };
+    const onAbort = () => { done(); reject(abortReason(signal)); };
+    const t = setTimeout(() => { done(); resolve(); }, ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+});
+/**
+ * fetch `url`, asking again when the server drops the request (see the top of this file). Returns the first answer that is
+ * not to be retried (a 2xx, or a 4xx that is the server's own); throws a PatientFetchError after `tries` failed tries.
+ * `init.signal` aborts it at once, between tries too.
+ */
+export async function patientFetch(url, init, opts = {}) {
+    const { tries = 6, delayMs = 300, maxDelayMs = 4_000, onRetry, retryOn = isRetryable, fetchFn = fetch, wait = sleep } = opts;
+    const signal = init?.signal ?? undefined;
+    const href = String(url);
+    let reason = '';
+    let status;
+    let cause;
+    for (let i = 1; i <= Math.max(1, tries); i++) {
+        if (signal?.aborted)
+            throw abortReason(signal);
+        status = undefined;
+        cause = undefined;
+        try {
+            const res = await fetchFn(href, init);
+            if (!(await retryOn(res)))
+                return res;
+            status = res.status;
+            reason = `HTTP ${res.status}${res.statusText ? ` ${res.statusText}` : ''}`;
+            if (res.status === 404)
+                reason += ' (unknown datasetID)';
+            void res.body?.cancel().catch(() => { }); // free the connection of an answer we drop (not awaited: a cancel waits for a clone's reader)
+        }
+        catch (e) {
+            if (signal?.aborted)
+                throw e; // superseded: not a failure
+            if (!(e instanceof TypeError))
+                throw e; // not the network: the caller's own error
+            reason = `network error: ${e.message}`;
+            cause = e;
+        }
+        if (i < tries) {
+            const pause = Math.min(delayMs * i, maxDelayMs);
+            onRetry?.({ attempt: i, tries, delayMs: pause, url: href, reason, ...(status !== undefined ? { status } : {}) });
+            if (pause > 0)
+                await wait(pause, signal);
+        }
+    }
+    throw new PatientFetchError(hostOf(href), reason, Math.max(1, tries), href, status, { cause });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oceanmetrics/engine",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "the browser engine of Ocean Metrics: the place mask, ERDDAP requests, the SQL shared with the Python engine, DuckDB-WASM statistics and the chunked live preview",
   "keywords": [
     "ocean",

package/src/index.ts

@@ -18,6 +18,8 @@ export {
 export type { ClampResult, InfoTable, TimeExtent, Window, WindowOpts } from './extent.js'
 export { ErddapUnreachable, fetchRetry, hostOf, mapFailMessage } from './fetchRetry.js'
 export type { RetryOpts } from './fetchRetry.js'
+export { PatientFetchError, UNKNOWN_DATASET, isRetryable, patientFetch } from './patient.js'
+export type { PatientOpts, PatientRetry } from './patient.js'
 export { axisSpacing, cellPoints, cellSquares, indexBounds, normalizeLon, pickCenter, placeMapBounds } from './cells.js'
 export type { CellPoints, CellProps, CellSquares, CellSquaresOptions, LonCenter, ValueCell } from './cells.js'
 export {

package/src/patient.ts

@@ -0,0 +1,117 @@
+// patientFetch: ask each ERDDAP request again, on its own, when the server drops it.
+//
+// the mirror erddap.oceanmetrics.io answers the same url 404 ("Currently unknown datasetID", one backend does not hold the
+// dataset yet) and 200 by turns under load (seen 2026-10-23), and any ERDDAP can answer 429 or a 5xx. retrying each request
+// beats retrying the whole slice: with half the answers dropped, six tries of one request fail one time in 64. this is the
+// one implementation of that rule (the places page and the indicators viewer carried a copy each). fetchRetry stays as it
+// is (a timeout per attempt, a short retry for the engine's own requests); this composes with it by naming the failure the
+// same way: the last failure is an ErddapUnreachable (a PatientFetchError, which also carries the status), so the toast
+// says "host did not answer (HTTP 503 Service Unavailable, 6 tries)" for both.
+//
+// retried: a network error (the browser's TypeError "Failed to fetch"), a 404 whose body says "Currently unknown datasetID",
+// a 429 and a 5xx. every other answer, a 4xx included, is returned at once for the caller to read. the caller's own abort
+// (`init.signal`) stops it at once, between tries too, as the AbortError it is.
+import { ErddapUnreachable, hostOf } from './fetchRetry.js'
+
+/** the body text ERDDAP sends with a 404 when the dataset is not (yet) on the server that answered */
+export const UNKNOWN_DATASET = 'Currently unknown datasetID'
+
+/** one retry about to happen: reported through `onRetry` */
+export interface PatientRetry {
+  /** the try that just failed (1 = the first) */
+  attempt : number
+  /** tries in all */
+  tries   : number
+  /** the pause before the next try (ms) */
+  delayMs : number
+  url     : string
+  /** why: "HTTP 503 Service Unavailable", "HTTP 404 (unknown datasetID)" or "network error: Failed to fetch" */
+  reason  : string
+  /** the status that failed the try; absent for a network error */
+  status ?: number
+}
+
+export interface PatientOpts {
+  /** tries in all (1 = no retry) */
+  tries    ?: number
+  /** the pause before the second try (ms); before try n + 1 it is `delayMs * n`, up to `maxDelayMs`. 0 = no pause */
+  delayMs  ?: number
+  /** the longest pause (ms) */
+  maxDelayMs?: number
+  /** called before each pause */
+  onRetry  ?: (r: PatientRetry) => void
+  /** whether an answer is to be asked for again; the default is `isRetryable`. It replaces the default, so a caller who
+   *  wants more can call `isRetryable(res)` itself. It reads `res.clone()` if it needs the body; the caller still gets `res` */
+  retryOn  ?: (res: Response) => boolean | Promise<boolean>
+  /** for tests */
+  fetchFn  ?: typeof fetch
+  wait     ?: (ms: number, signal?: AbortSignal) => Promise<unknown>
+}
+
+/** the last failure after every try: an ErddapUnreachable that also says which status it was (absent: a network error) */
+export class PatientFetchError extends ErddapUnreachable {
+  constructor(host: string, reason: string, attempts: number, url: string, readonly status?: number, options?: { cause?: unknown }) {
+    super(host, reason, attempts, url)
+    this.name = 'PatientFetchError'
+    if (options?.cause !== undefined) this.cause = options.cause
+  }
+}
+
+/**
+ * the default rule: a 429 or a 5xx, and a 404 whose body is ERDDAP's "Currently unknown datasetID". Any other 404 is a real
+ * answer (a wrong dataset id, a coordinate out of range) and is not asked for again. The body is read from a clone.
+ */
+export async function isRetryable(res: Response): Promise<boolean> {
+  if (res.status === 429 || res.status >= 500) return true
+  if (res.status !== 404) return false
+  try { return (await res.clone().text()).includes(UNKNOWN_DATASET) } catch { return false }
+}
+
+const abortReason = (signal: AbortSignal) => signal.reason ?? new DOMException('aborted', 'AbortError')
+
+/** a pause that an abort cuts short (rejecting with the abort reason) */
+const sleep = (ms: number, signal?: AbortSignal) => new Promise<void>((resolve, reject) => {
+  if (signal?.aborted) return reject(abortReason(signal))
+  const done = () => { clearTimeout(t); signal?.removeEventListener('abort', onAbort) }
+  const onAbort = () => { done(); reject(abortReason(signal!)) }
+  const t = setTimeout(() => { done(); resolve() }, ms)
+  signal?.addEventListener('abort', onAbort, { once: true })
+})
+
+/**
+ * fetch `url`, asking again when the server drops the request (see the top of this file). Returns the first answer that is
+ * not to be retried (a 2xx, or a 4xx that is the server's own); throws a PatientFetchError after `tries` failed tries.
+ * `init.signal` aborts it at once, between tries too.
+ */
+export async function patientFetch(url: string | URL, init?: RequestInit, opts: PatientOpts = {}): Promise<Response> {
+  const { tries = 6, delayMs = 300, maxDelayMs = 4_000, onRetry, retryOn = isRetryable, fetchFn = fetch, wait = sleep } = opts
+  const signal = init?.signal ?? undefined
+  const href = String(url)
+  let reason = ''
+  let status: number | undefined
+  let cause: unknown
+  for (let i = 1; i <= Math.max(1, tries); i++) {
+    if (signal?.aborted) throw abortReason(signal)
+    status = undefined
+    cause = undefined
+    try {
+      const res = await fetchFn(href, init)
+      if (!(await retryOn(res))) return res
+      status = res.status
+      reason = `HTTP ${res.status}${res.statusText ? ` ${res.statusText}` : ''}`
+      if (res.status === 404) reason += ' (unknown datasetID)'
+      void res.body?.cancel().catch(() => {})                            // free the connection of an answer we drop (not awaited: a cancel waits for a clone's reader)
+    } catch (e) {
+      if (signal?.aborted) throw e                                       // superseded: not a failure
+      if (!(e instanceof TypeError)) throw e                             // not the network: the caller's own error
+      reason = `network error: ${e.message}`
+      cause = e
+    }
+    if (i < tries) {
+      const pause = Math.min(delayMs * i, maxDelayMs)
+      onRetry?.({ attempt: i, tries, delayMs: pause, url: href, reason, ...(status !== undefined ? { status } : {}) })
+      if (pause > 0) await wait(pause, signal)
+    }
+  }
+  throw new PatientFetchError(hostOf(href), reason, Math.max(1, tries), href, status, { cause })
+}