@lde/distribution-probe 0.1.9 → 0.1.11

package/README.md

@@ -32,4 +32,6 @@ Sends `HEAD` with `Accept: <distribution.mimeType>` and `Accept-Encoding: identi
 
 ### Network errors
 
-Any thrown exception from `fetch` (DNS, connection refused, TLS, timeout after the configured `timeout` – default 5 000 ms) is caught and returned as a `NetworkError` with the original message.
+A thrown exception from `fetch` (DNS failure, connection refused, socket reset, TLS error, timeout after the configured `timeoutMs` – default 5 000 ms) is a connection-level failure. The probe retries these up to `retries` times (default 2) with a short backoff before giving up and returning a `NetworkError`. This turns a transient transport blip into a reliable single measurement without looking backward across checks. A genuine outage still resolves to a `NetworkError` on the current check – every attempt fails – but note each attempt gets its own `timeoutMs`, so an endpoint that fails only by timing out takes up to `(retries + 1) × timeoutMs` (plus backoff) to be reported down. HTTP error responses (4xx/5xx) and content-validation failures are real ‘down’ states and are **never** retried.
+
+`NetworkError.message` includes the underlying `error.cause` (e.g. `ECONNRESET`, `UND_ERR_SOCKET “other side closed”`) when Node wraps one, so observations record what actually failed rather than a bare ‘fetch failed’.

package/dist/probe.d.ts

@@ -17,6 +17,17 @@ export interface ProbeOptions {
      * distributions. Defaults to `SELECT * { ?s ?p ?o } LIMIT 1`.
      */
     sparqlQuery?: string;
+    /**
+     * How many times to retry a connection-level failure (DNS, connection
+     * refused, socket reset, TLS error, timeout) before returning a
+     * {@link NetworkError}. Only transport errors are retried within the same
+     * check, so a transient blip does not flip an otherwise healthy distribution
+     * to ‘unavailable’; HTTP error responses and content-validation failures are
+     * genuine ‘down’ states and are never retried. Set to `0` to disable.
+     * Defaults to `2`. A non-integer or otherwise invalid value falls back to
+     * the default; negative values are clamped to `0`.
+     */
+    retries?: number;
 }
 /**
  * Result of a network error during probing.

package/dist/probe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../src/probe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,YAAY,EAAE,MAAM,cAAc,CAAC;AAInE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAKD;;GAEG;AACH,qBAAa,YAAY;aAEL,GAAG,EAAE,MAAM;aACX,OAAO,EAAE,MAAM;aACf,cAAc,EAAE,MAAM;gBAFtB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM;CAEzC;AAED;;GAEG;AACH,uBAAe,WAAW;aAUN,GAAG,EAAE,MAAM;IAT7B,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,YAAY,EAAE,IAAI,GAAG,IAAI,CAAQ;IACjD,SAAgB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,SAAgB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,SAAgB,QAAQ,EAAE,MAAM,EAAE,CAAM;IACxC,SAAgB,cAAc,EAAE,MAAM,CAAC;gBAGrB,GAAG,EAAE,MAAM,EAC3B,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,MAAM,EACtB,aAAa,GAAE,MAAM,GAAG,IAAW;IAa9B,SAAS,IAAI,OAAO;CAO5B;AAMD;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;IAChD;;;;;OAKG;IACH,SAAgB,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;gBAGtD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,MAAM,EACtB,oBAAoB,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EAChD,aAAa,GAAE,MAAM,GAAG,IAAW;IAS5B,SAAS,IAAI,OAAO;CAQ9B;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;IAClD,SAAgB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAQ;gBAGhD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,MAAM,EACtB,aAAa,GAAE,MAAM,GAAG,IAAW;CAQtC;AAED,MAAM,MAAM,eAAe,GACvB,iBAAiB,GACjB,mBAAmB,GACnB,YAAY,CAAC;AAIjB;;;;;;;;GAQG;AACH,wBAAsB,KAAK,CACzB,YAAY,EAAE,YAAY,EAC1B,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,eAAe,CAAC,CAkC1B"}
+{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../src/probe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,YAAY,EAAE,MAAM,cAAc,CAAC;AAInE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AASD;;GAEG;AACH,qBAAa,YAAY;aAEL,GAAG,EAAE,MAAM;aACX,OAAO,EAAE,MAAM;aACf,cAAc,EAAE,MAAM;gBAFtB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM;CAEzC;AAED;;GAEG;AACH,uBAAe,WAAW;aAUN,GAAG,EAAE,MAAM;IAT7B,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,YAAY,EAAE,IAAI,GAAG,IAAI,CAAQ;IACjD,SAAgB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,SAAgB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,SAAgB,QAAQ,EAAE,MAAM,EAAE,CAAM;IACxC,SAAgB,cAAc,EAAE,MAAM,CAAC;gBAGrB,GAAG,EAAE,MAAM,EAC3B,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,MAAM,EACtB,aAAa,GAAE,MAAM,GAAG,IAAW;IAa9B,SAAS,IAAI,OAAO;CAO5B;AAMD;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;IAChD;;;;;OAKG;IACH,SAAgB,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;gBAGtD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,MAAM,EACtB,oBAAoB,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EAChD,aAAa,GAAE,MAAM,GAAG,IAAW;IAS5B,SAAS,IAAI,OAAO;CAQ9B;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;IAClD,SAAgB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAQ;gBAGhD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,MAAM,EACtB,aAAa,GAAE,MAAM,GAAG,IAAW;CAQtC;AAED,MAAM,MAAM,eAAe,GACvB,iBAAiB,GACjB,mBAAmB,GACnB,YAAY,CAAC;AAIjB;;;;;;;;GAQG;AACH,wBAAsB,KAAK,CACzB,YAAY,EAAE,YAAY,EAC1B,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,eAAe,CAAC,CAqD1B"}

package/dist/probe.js

@@ -3,6 +3,9 @@ import { rdfParser } from 'rdf-parse';
 import { Readable } from 'node:stream';
 const DEFAULT_SPARQL_QUERY = 'SELECT * { ?s ?p ?o } LIMIT 1';
 const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_RETRIES = 2;
+/** Base backoff between retries; the nth retry waits `n × base`. */
+const RETRY_BACKOFF_MS = 250;
 /**
  * Result of a network error during probing.
  */
@@ -100,23 +103,75 @@ export async function probe(distribution, options) {
     const [authUrl, authHeaders] = distribution.accessUrl !== undefined
         ? extractUrlCredentials(distribution.accessUrl, resolved.headers)
         : [new URL(url), new Headers(resolved.headers)];
-    const start = performance.now();
-    try {
-        if (distribution.isSparql()) {
-            return await probeSparqlEndpoint(authUrl.toString(), distribution, resolved, authHeaders, start);
+    // Retry only connection-level failures (a thrown `fetch`): HTTP error
+    // responses and content-validation failures are returned as result objects,
+    // never thrown, so they exit the loop on the first attempt and are not
+    // retried. A genuine outage still resolves to a NetworkError – every attempt
+    // fails – but note each attempt gets its own `timeoutMs`, so an endpoint that
+    // fails only by timing out takes up to (retries + 1) × timeoutMs (plus
+    // backoff) to be reported down.
+    const overallStart = performance.now();
+    let lastError;
+    for (let attempt = 0; attempt <= resolved.retries; attempt++) {
+        if (attempt > 0) {
+            await delay(RETRY_BACKOFF_MS * attempt);
+        }
+        const start = performance.now();
+        try {
+            if (distribution.isSparql()) {
+                return await probeSparqlEndpoint(authUrl.toString(), distribution, resolved, authHeaders, start);
+            }
+            return await probeDataDump(authUrl.toString(), distribution, resolved, authHeaders, start);
+        }
+        catch (error) {
+            lastError = error;
         }
-        return await probeDataDump(authUrl.toString(), distribution, resolved, authHeaders, start);
     }
-    catch (e) {
-        const responseTimeMs = Math.round(performance.now() - start);
-        return new NetworkError(url, e instanceof Error ? e.message : String(e), responseTimeMs);
+    // A successful probe reports its own attempt's latency (computed inside the
+    // probe functions); a NetworkError reports the total time spent failing,
+    // across every attempt and backoff, so observations do not understate the
+    // real cost of a down endpoint.
+    return new NetworkError(url, describeNetworkError(lastError), Math.round(performance.now() - overallStart));
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+/**
+ * Describe a thrown fetch error for a {@link NetworkError} message. undici wraps
+ * * the real reason (`ECONNRESET`, `UND_ERR_SOCKET “other side closed”`, TLS
+ * errors, …) in `error.cause`, while `error.message` is usually a bare
+ * ‘fetch failed’. Including the cause’s code and message preserves the
+ * diagnostic detail that would otherwise be discarded.
+ */
+function describeNetworkError(error) {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    const { cause } = error;
+    if (cause === undefined || cause === null) {
+        return error.message;
     }
+    const detail = cause instanceof Error
+        ? [cause.code, cause.message]
+            .filter(Boolean)
+            .join(': ')
+        : String(cause);
+    return detail && detail !== error.message
+        ? `${error.message} (${detail})`
+        : error.message;
 }
 function resolveOptions(options) {
+    const retries = options?.retries;
     return {
         timeoutMs: options?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
         headers: options?.headers ?? new Headers(),
         sparqlQuery: options?.sparqlQuery ?? DEFAULT_SPARQL_QUERY,
+        // Guard the loop bound: a non-integer (NaN, Infinity, fractional) would
+        // otherwise either skip the loop entirely or never terminate. Negatives
+        // clamp to 0 (retries disabled).
+        retries: retries === undefined || !Number.isInteger(retries)
+            ? DEFAULT_RETRIES
+            : Math.max(0, retries),
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/distribution-probe",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
     "directory": "packages/distribution-probe"
@@ -24,7 +24,7 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@lde/dataset": "0.7.6",
+    "@lde/dataset": "0.7.7",
     "rdf-parse": "^5.0.0",
     "tslib": "^2.3.0"
   }