Fix response-body failures, cancellation and retry cleanup (1.0.1)

CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.0.1
+
+- Fixed response-body transport failures (#59): timeouts and connection failures after successful
+  headers now raise `GlassnodeNetworkError` and follow the configured retry policy (subject to
+  the x402 payment safeguards below). Invalid JSON
+  and schema mismatches still raise non-retried `GlassnodeValidationError`.
+- Discarded `429`/`5xx` response bodies are cancelled before retrying, releasing their connection
+  resources. Cleanup failures or pending cancellation do not block retries (#61).
+- Caller cancellation while reading a terminal HTTP error body now raises `GlassnodeAbortError`
+  with the caller's reason, including whole-call deadlines (#60).
+- x402 with `createX402Fetch`: a successful paid response whose body fails in transit raises `GlassnodePaymentError`
+  (`paymentMayHaveSettled: true`), including timeouts and caller aborts. It is never retried, even
+  when retries are explicitly enabled. Invalid paid JSON remains a non-retried validation error.
+- x402 with a plain payment fetch: successful response-body failures are never retried, even with
+  an explicit `maxRetries`, because the payment may already have settled. They raise
+  `GlassnodeNetworkError`; only responses identified as unpaid by `createX402Fetch` can have
+  their body transfer retried in x402 mode.
+- x402 with `createX402Fetch` over a base fetch whose body is a Node stream (e.g. node-fetch v2):
+  the paid response is returned as is instead of failing after the payment was sent, which a
+  retry would have paid for again.
+- A custom `fetch` returning a Response-like object with only `json()` keeps working as in 1.0.0;
+  its failures are non-retried `GlassnodeValidationError`s.
+
 ## 1.0.0
 
 1.0.0 is the first stable release: from here on the public API follows semver, as the README's

README.md

@@ -349,7 +349,7 @@ matching needed.
 | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `GlassnodeError`           | Base class of all the errors below — catch this to handle any library failure                                                                                                                                                                       | `message`, `cause`                                                                                                                                                             |
 | `GlassnodeApiError`        | The API answered with a non-2xx HTTP status (e.g. `401`, `404`, `429`, `5xx`, or a `3xx` not followed; with x402, only before a payment was sent, or `402` after it)                                                                                | `status`, `statusText`, `detail` (server message), `isRetryable` (429 / 5xx)                                                                                                   |
-| `GlassnodeNetworkError`    | No HTTP response: connection/DNS failure (in a browser also a CORS block), or the per-attempt `timeout` firing. Retried unless `maxRetries` is `0`                                                                                                  | `timedOut` (`true` when `timeout` fired), `cause` (the original fetch error)                                                                                                   |
+| `GlassnodeNetworkError`    | Request or response-body transfer failure: connection/DNS failure (in a browser also a CORS block), or the per-attempt `timeout` firing. Retried unless `maxRetries` is `0`                                                                         | `timedOut` (`true` when `timeout` fired), `cause` (the original fetch error)                                                                                                   |
 | `GlassnodeAbortError`      | The call was cancelled through the per-call `signal` (already aborted, or aborted mid-request or during a retry wait). Never retried                                                                                                                | `cause` (the signal's `reason`, e.g. a `DOMException` named `AbortError`, or `TimeoutError` for `AbortSignal.timeout()`)                                                       |
 | `GlassnodeValidationError` | A `2xx` response was unusable: the body was not valid JSON, or did not match the expected schema (or `callMetric`'s `schema`). Never retried                                                                                                        | `endpoint` (API path, e.g. `/v1/metadata/assets`), `cause` (`ZodError` / `SyntaxError`)                                                                                        |
 | `GlassnodeConfigError`     | The options passed to `new GlassnodeAPI(...)` are invalid (e.g. empty `apiKey`, `x402` without `fetch`, an unknown hook name), or `createX402Fetch` cannot load its optional peer dependencies                                                      | `message` (lists the invalid fields), `cause` (`ZodError` / import error)                                                                                                      |
@@ -431,7 +431,9 @@ Each retry wait is the exponential delay (`retryDelay * 2^(n-1)` before retry `n
 retries across clients. When a retried `429`/`5xx` response carries a `Retry-After` header (seconds or
 an HTTP date), that value is used for the next wait instead — capped at `maxRetryDelay`, not
 jittered. A malformed `200` body is **not** retried (it isn't a transient error) — it fails
-immediately with a `GlassnodeValidationError`.
+immediately with a `GlassnodeValidationError`. A timeout or connection failure while reading a
+successful body is a transport failure instead and follows the retry policy. Discarded retry
+response bodies are cancelled to release their connections.
 
 Non-retryable errors (e.g. `401`, `404`, a caller abort, invalid input) fail immediately without
 retrying. When every attempt fails, the call rejects with the last attempt's error.
@@ -449,6 +451,12 @@ failure, timeout, `429` or `5xx` is then retried only while no payment has been
 payment has gone out, a failure — whatever the HTTP status — is **never** retried; see
 [Errors](#x402-errors) below.
 
+In x402 mode, a body-transfer failure after successful headers from a plain payment fetch raises
+`GlassnodeNetworkError` without retrying, even with an explicit `maxRetries`: the successful
+request may already have been paid. Body transfers can only be retried for responses that
+`createX402Fetch` identifies as unpaid. A plain wrapper still requires `maxRetries: 0` to avoid
+repeating payments after failures before headers or paid `429`/`5xx` responses.
+
 ## Cancellation and per-call timeouts
 
 Every method takes an optional last argument, `options: { signal?: AbortSignal; timeout?: number }`

package.json

@@ -1,6 +1,6 @@
 {
   "name": "glassnode-api",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "commonjs",
   "description": "TypeScript client for the Glassnode API (Node.js and browsers)",
   "main": "dist/index.js",

src/errors.ts

@@ -57,7 +57,7 @@ export class GlassnodeApiError extends GlassnodeError {
 }
 
 /**
- * The request never produced an HTTP response: DNS/connection failure, reset, or the per-request
+ * The request or response body failed in transit: DNS/connection failure, reset, or the per-request
  * `timeout` firing (also an abort that did not come from the caller's per-call `signal`). The
  * original error is on `.cause`. Retried when `maxRetries` > 0. A cancellation through the
  * per-call `signal` is a {@link GlassnodeAbortError} instead.

src/glassnode-api.ts

@@ -19,6 +19,7 @@ import {
   GlassnodeValidationError,
 } from './errors.js';
 import { readErrorDetail } from './error-detail.js';
+import { isGlassnodeError, isUnpaidResponse } from './response-safety.js';
 import { redactApiKey, redactSecrets } from './redact.js';
 import {
   AssetMetadataResponse,
@@ -524,6 +525,7 @@ export class GlassnodeAPI {
   private retryDelay: number;
   private maxRetryDelay: number;
   private timeout?: number;
+  private x402: boolean;
 
   /**
    * Create a new Glassnode API client
@@ -546,6 +548,7 @@ export class GlassnodeAPI {
     this.logger = validatedConfig.logger;
     this.hooks = validatedConfig.hooks;
     this.fetchFn = validatedConfig.fetch ?? globalThis.fetch;
+    this.x402 = validatedConfig.x402;
     // The default depends on `x402`, so it is applied here rather than in the schema (which stays
     // a plain object schema): a retry through a caller-supplied payment fetch could pay twice.
     this.maxRetries =
@@ -647,7 +650,7 @@ export class GlassnodeAPI {
     try {
       return finish(await this.send(url, keyInHeader, options, trace));
     } catch (error) {
-      if (error instanceof GlassnodeError) {
+      if (isGlassnodeError(error)) {
         const status = errorStatus(error);
         const durationMs = trace.lastDurationMs;
         this.emit('onError', () => ({
@@ -720,7 +723,7 @@ export class GlassnodeAPI {
             ? combineSignals(signal, AbortSignal.timeout(timeout))
             : { signal: AbortSignal.timeout(timeout), dispose: () => {} };
       try {
-        // Transport step — the only part that is retried on failure.
+        // Transport to the headers; successful response-body transfers are checked below too.
         let response: Response;
         const sentAt = performance.now();
         try {
@@ -743,7 +746,7 @@ export class GlassnodeAPI {
           // Already classified by a library-aware fetch (e.g. a GlassnodePaymentError from
           // createX402Fetch, which also covers an abort after a payment was sent): surface it
           // unchanged and never retry it.
-          if (error instanceof GlassnodeError) throw error;
+          if (isGlassnodeError(error)) throw error;
           // Cancelled by the caller: never retried, whatever the fetch rejected with.
           if (signal?.aborted) throw aborted();
           // Network/transport failure (including a timeout abort) — retryable.
@@ -781,25 +784,80 @@ export class GlassnodeAPI {
             lastError = error;
             // Honour the server's Retry-After (e.g. on 429) for the next wait, if present.
             retryAfterMs = this.parseRetryAfter(response);
+            // A discarded streaming body still owns a connection. Do not wait to drain it.
+            try {
+              void response.body?.cancel().catch(() => {});
+            } catch {
+              // Cleanup must not replace the HTTP failure that caused the retry.
+            }
             continue;
           }
           // Surface the server's error body (e.g. "Resolution 1h is not allowed") in the message,
           // with the API key masked: a server or proxy may echo the request URL or the key.
           const detail = await readErrorDetail(response, [this.apiKey]);
+          if (signal?.aborted) throw aborted();
           throw detail ? new GlassnodeApiError(response.status, statusText, detail) : error;
         }
 
-        // Success. Parsing a 200 body is NOT a transient error, so it is thrown, never retried.
+        // A minimal custom fetch may return a Response-like object with only json(), which 1.0.0
+        // accepted. Parse it there: its failures cannot be told apart, so none is retried.
+        if (typeof response.text !== 'function') {
+          try {
+            return (await response.json()) as unknown;
+          } catch (parseError) {
+            if (signal?.aborted) throw aborted();
+            throw new GlassnodeValidationError(
+              'Glassnode API error: failed to parse response body as JSON',
+              { cause: parseError, endpoint }
+            );
+          }
+        }
+
+        // Read bytes separately from parsing: polyfills can wrap invalid JSON in FetchError,
+        // so response.json() cannot reliably distinguish malformed JSON from failed transfers.
+        let readableBody = false;
+        let text: string;
         try {
-          return (await response.json()) as unknown;
+          readableBody = !!response.body && !response.bodyUsed && !response.body.locked;
+          text = await response.text();
         } catch (parseError) {
+          // A paid response stream classifies its own failures; never repeat its payment.
+          if (isGlassnodeError(parseError)) throw parseError;
           // Reading the body was cut off by the caller's abort: that is not a malformed body.
           if (signal?.aborted) throw aborted();
+          const failure = describeTransportFailure(parseError);
+          const bodyReadStarted = readableBody && response.bodyUsed;
+          const explicitAbort =
+            typeof parseError === 'object' &&
+            parseError !== null &&
+            ABORT_NAMES.has(String((parseError as { name?: unknown }).name));
+          if (failure && (bodyReadStarted || explicitAbort)) {
+            retryAfterMs = undefined;
+            lastError = new GlassnodeNetworkError(
+              `Glassnode API error: ${this.redact(failure.message)}`,
+              {
+                cause: parseError,
+                timedOut: failure.timedOut || (attemptSignal.signal?.aborted ?? false),
+              }
+            );
+            // A plain payment fetch may already have charged for this successful response.
+            // Only a response positively identified as unpaid is safe to repeat in x402 mode.
+            if (attempt < this.maxRetries && (!this.x402 || isUnpaidResponse(response))) continue;
+            throw lastError;
+          }
           throw new GlassnodeValidationError(
             'Glassnode API error: failed to parse response body as JSON',
             { cause: parseError, endpoint }
           );
         }
+        try {
+          return JSON.parse(text) as unknown;
+        } catch (cause) {
+          throw new GlassnodeValidationError(
+            'Glassnode API error: failed to parse response body as JSON',
+            { cause, endpoint }
+          );
+        }
       } finally {
         attemptSignal.dispose();
       }

src/response-safety.ts

@@ -0,0 +1,36 @@
+import type { GlassnodeError } from './errors.js';
+
+// Global symbols survive multiple installed copies and separate CJS/ESM entries.
+const SAFE_BODY_RETRY = Symbol.for('glassnode-api.x402.safe-body-retry');
+
+/** Only createX402Fetch knows that a response arrived before any payment was sent. */
+export function markUnpaidResponse(response: Response): Response {
+  Object.defineProperty(response, SAFE_BODY_RETRY, { value: true });
+  return response;
+}
+
+export function isUnpaidResponse(response: Response): boolean {
+  return (response as Response & { [SAFE_BODY_RETRY]?: boolean })[SAFE_BODY_RETRY] === true;
+}
+
+const ERROR_NAMES = new Set([
+  'GlassnodeError',
+  'GlassnodeApiError',
+  'GlassnodeNetworkError',
+  'GlassnodeAbortError',
+  'GlassnodeValidationError',
+  'GlassnodeConfigError',
+  'GlassnodeInputError',
+  'GlassnodePaymentError',
+]);
+
+/** Preserve library classifications even when an error comes from another package copy. */
+export function isGlassnodeError(error: unknown): error is GlassnodeError {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'name' in error &&
+    typeof error.name === 'string' &&
+    ERROR_NAMES.has(error.name)
+  );
+}