Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/add-retry-backoff.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@kamsteegsoftware/fetchify": minor
---

`createFetchify` now accepts an optional `retry` (`FetchifyRetryOptions`), applied as the default retry configuration for every request made by the client, and each `FetchifyMethod` call accepts a per-request `retry` override — either a replacement `FetchifyRetryOptions` object or `false` to disable retry for that call. A failed request is retried with capped exponential backoff and full jitter (or the response's `Retry-After` header, for a `429`/`503`), re-running `beforeRequest` and getting a fresh `timeout` window per attempt. With no `retryOn` supplied, only idempotent methods (`GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`) are retried, and only for network failures, `FetchifyTimeoutError`s, and `FetchifyError`s with status `408`, `429`, `500`, `502`, `503`, or `504` — `POST`/`PATCH` are never retried by default, and a caller-triggered `AbortSignal` is never retried under any configuration. Retry never applies to a cache-served `GET`. With no `retry` configured, requests behave exactly as they did before this option existed.
55 changes: 54 additions & 1 deletion DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,21 @@ try {
await client.get("/slow", { timeout: 500 });
```

`options.retry` accepts a [`FetchifyRetryOptions`](#fetchifyretryoptions) object, applied as the default retry configuration for every request made by the client; omitting it makes every request exactly one network attempt, unchanged from before this option existed. A single call can override it via `retry` on that [`FetchifyMethod`](#fetchifymethod) call — either a different `FetchifyRetryOptions` object (replacing the client default outright, not merging with it) or `false` to disable retry for that call. With no `retryOn` supplied, only idempotent methods (`GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`) are retried, and only for network failures, a [`FetchifyTimeoutError`](#fetchifytimeouterror), or a [`FetchifyError`](#fetchifyerrort) with status `408`, `429`, `500`, `502`, `503`, or `504` — `POST`/`PATCH` are never retried by default. Each retry waits using capped exponential backoff with full jitter (or the response's `Retry-After` header, for a `429`/`503`), re-runs `beforeRequest`, and gets its own fresh `timeout` window. A caller-triggered `AbortSignal` is never retried. Retry never applies to a cache-served `GET`, since no `fetch` call is made for a cache hit.

```ts
const client = createFetchify({
baseUrl: "https://api.example.com",
retry: { retries: 3 }, // exponential backoff with jitter, 200ms base delay
});

await client.get("/flaky"); // retried on network errors, timeouts, and 408/429/5xx

// Override the client default for a single call
await client.get("/flaky", { retry: { retries: 1, retryOn: () => true } });
await client.post("/orders", { body, retry: false }); // never retried
```

## `defineOptions`

```ts
Expand Down Expand Up @@ -299,10 +314,46 @@ interface FetchifyOptions {
headers?: Record<string, string | undefined>;
hooks?: FetchifyHooks;
timeout?: number;
retry?: FetchifyRetryOptions;
}
```

Configuration accepted by `createFetchify` and `defineOptions`. `headers` (see [`defineHeaders`](#defineheaders)) are the default headers sent with every request made by the client. `hooks` (see [`FetchifyHooks`](#fetchifyhooks)) configures lifecycle hooks, currently just `beforeRequest`. `timeout` is the default number of milliseconds a request may take before it's aborted with a [`FetchifyTimeoutError`](#fetchifytimeouterror); see [`createFetchify`](#createfetchify) for the full behavior. `retry` is the default [`FetchifyRetryOptions`](#fetchifyretryoptions) applied to every request; see [`createFetchify`](#createfetchify) for the full behavior.

### `FetchifyRetryOptions`

```ts
interface FetchifyRetryOptions {
retries?: number;
delay?: number;
backoffFactor?: number;
maxDelay?: number;
jitter?: boolean;
retryOn?: (context: FetchifyRetryContext) => boolean;
}
```

Retry configuration accepted by [`FetchifyOptions.retry`](#fetchifyoptions) (client-level default) and [`FetchifyMethodOptions.retry`](#fetchifymethodoptions) (per-call override). Every field is optional; supplying `{}` enables retry with every default applied.

- `retries` — maximum number of retry attempts after the initial one. Default `3`.
- `delay` — base delay, in milliseconds, before the first retry. Default `200`.
- `backoffFactor` — multiplier applied to the delay on each subsequent retry. Default `2`.
- `maxDelay` — upper bound, in milliseconds, on any computed delay (including a `Retry-After`-derived one). Default `30000`.
- `jitter` — when `true`, the actual wait is a random value between `0` and the computed delay ("full jitter"), instead of the computed delay exactly. Default `true`.
- `retryOn` — overrides the default eligibility predicate entirely, for every method including `POST`/`PATCH`. Called with a [`FetchifyRetryContext`](#fetchifyretrycontext); returning `true` retries, `false` stops and propagates the failure. Never consulted for a caller-triggered `AbortSignal`, which is never retried.

### `FetchifyRetryContext`

```ts
interface FetchifyRetryContext {
method: string;
url: string;
attempt: number;
error: FetchifyError | FetchifyTimeoutError | Error;
}
```

Configuration accepted by `createFetchify` and `defineOptions`. `headers` (see [`defineHeaders`](#defineheaders)) are the default headers sent with every request made by the client. `hooks` (see [`FetchifyHooks`](#fetchifyhooks)) configures lifecycle hooks, currently just `beforeRequest`. `timeout` is the default number of milliseconds a request may take before it's aborted with a [`FetchifyTimeoutError`](#fetchifytimeouterror); see [`createFetchify`](#createfetchify) for the full behavior.
Passed to a custom [`FetchifyRetryOptions.retryOn`](#fetchifyretryoptions) after each failed attempt: the uppercase HTTP verb, the fully resolved request URL, the 1-based count of attempts made so far (including the one that just failed), and the error that triggered the eligibility check.

### `FetchifyHooks`

Expand Down Expand Up @@ -420,6 +471,7 @@ interface FetchifyMethodOptions {
body?: RequestInit['body'] | JsonSerializable;
init?: RequestInit;
timeout?: number;
retry?: FetchifyRetryOptions | false;
}
```

Expand All @@ -430,6 +482,7 @@ Per-request options accepted by every [`FetchifyMethod`](#fetchifymethod) call:
- `body` — the request body. Accepts either a standard `BodyInit` value (`string`, `Blob`, `ArrayBuffer`/typed array, `FormData`, `URLSearchParams`, `ReadableStream`) or any JSON-serializable value (plain object, array, number, boolean, `null`). When the resolved `Content-Type` header (see `headers` above) is `application/json`, a non-`BodyInit` body is automatically run through `JSON.stringify` before being sent; otherwise it's forwarded to `fetch` exactly as given, with no auto-serialization and no auto-setting of `Content-Type`. Standard `BodyInit` values are never re-serialized, even when `Content-Type` is `application/json`, so an already-`JSON.stringify`'d string is never double-encoded. Takes precedence over `init.body` when both are set — `init.body` is never serialized, regardless of `Content-Type`.
- `init` — the underlying `RequestInit`, for request settings not covered by `headers`/`params`/`body` (e.g. `signal`, `credentials`). Its `headers` and `body` fields, if set, are superseded by the computed `headers` and `body` above rather than merged with them.
- `timeout` — overrides the client's default `timeout` (see [`createFetchify`](#createfetchify)) for this request only; `0` explicitly disables an inherited client-level timeout.
- `retry` — overrides the client's default `retry` (see [`createFetchify`](#createfetchify)) for this request only, replacing it outright rather than merging; `false` explicitly disables an inherited client-level retry.

```ts
await client.get("/users", {
Expand Down
31 changes: 31 additions & 0 deletions GETTING-STARTED.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,37 @@ await client.get("/slow", { timeout: 0 }); // no timeout for this call

With no `timeout` configured, requests wait on the network indefinitely, same as before this option existed. See [DOCS.md](./DOCS.md#createfetchify) for how it composes with a caller-supplied `AbortSignal`.

## Retrying failed requests

Pass `retry` to automatically retry a request on a transient failure — a network error, a timeout, or a `408`/`429`/`5xx` response — using exponential backoff with jitter:

```ts
const client = createFetchify({
baseUrl: "https://api.example.com",
retry: { retries: 3 },
});

await client.get("/flaky"); // retried up to 3 times before rejecting
```

By default only idempotent methods (`GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`) are retried, so a `POST`/`PATCH` never gets retried automatically — pass your own `retryOn` if you know a specific write is safe to retry (e.g. it's protected by an idempotency key):

```ts
await client.post("/orders", {
body: { id: "already-generated-client-side" },
retry: { retries: 2, retryOn: () => true },
});
```

Override the client's default for a single call, including disabling it outright:

```ts
await client.get("/flaky", { retry: { retries: 1 } }); // replaces the client default
await client.get("/flaky", { retry: false }); // never retried for this call
```

With no `retry` configured, requests behave exactly as before this option existed — one attempt, no retry. See [DOCS.md](./DOCS.md#createfetchify) for the full default eligibility rules, backoff/jitter formula, and `Retry-After` handling.

## Using cache adapters

Pass a `CacheAdapter` as the `cache` option to `createFetchify` to cache `GET` responses. Caching only applies to `GET` requests — other verbs always hit the network. On a `GET`, fetchify checks the cache first; on a cache miss, it makes the request and, if the response is `ok`, stores it for next time.
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-08-07
48 changes: 48 additions & 0 deletions openspec/changes/archive/2026-08-07-add-retry-backoff/design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
## Context

`createFetchify`'s request path (`src/lib/create-fetchify.ts`) currently makes exactly one network attempt per call: `performRequest` runs the `beforeRequest` hook, applies the resolved timeout, calls `fetch`, and either resolves a `FetchifyResponse` or throws (`FetchifyTimeoutError` on abort, `FetchifyError` on a non-ok response, or the raw `fetch` rejection on a network failure). There is no shared retry/backoff mechanism; consumers must wrap call sites themselves.

This change adds an opt-in retry loop around that single network attempt, reusing the existing timeout and `beforeRequest` machinery per attempt rather than replacing them.

## Goals / Non-Goals

**Goals:**
- Retry a request automatically on transient failures (network errors, timeouts, and `408`/`429`/`5xx` responses), with exponential backoff and jitter.
- Make retry opt-in at the client level (`FetchifyOptions.retry`) and overridable per call (`FetchifyMethodOptions.retry`), mirroring the existing `timeout` option pattern.
- Default to only retrying idempotent methods, so enabling retry does not silently introduce duplicate-side-effect risk on `POST`/`PATCH`.
- Honor a `Retry-After` response header when present, since it is server-authoritative information about how long to wait.
- Leave cache-hit `GET`s, the `beforeRequest` hook contract, and the timeout contract behaviorally unchanged except for being re-run per attempt.

**Non-Goals:**
- No per-attempt observability hook (e.g. an `onRetry` callback) or exposing an attempt count on `FetchifyResponse`/`FetchifyError` — the existing `logger` continues to receive exactly one entry per top-level call, keyed on the final outcome, unchanged from today's contract.
- No retry budget shared across concurrent requests (e.g. a circuit breaker) — each call's retry loop is independent.
- No change to `response-error-handling` or `logger-adapter` requirements; this change touches only `http-client` and `fetchify-options`, plus the new `request-retry` capability.

## Decisions

**Retry loop location**: the loop wraps the existing "one network attempt" logic inside `performRequest` (hook invocation through building the resolved value or throwing), not the outer `request` function that owns logging/timing. This keeps `logger.log` firing exactly once per call, after the loop settles, unchanged from today.
- Alternative considered: loop in `request`, re-invoking `performRequest` wholesale. Rejected — `performRequest` already reads `cache` first; looping at that level would re-check the cache on every retry, which is wrong (a cache miss on attempt 1 will always miss on attempt 2).

**Config shape — object with named fields, not a boolean or bare number**: `FetchifyRetryOptions { retries?, delay?, backoffFactor?, maxDelay?, jitter?, retryOn? }`, all optional with defaults (`retries: 3`, `delay: 200`, `backoffFactor: 2`, `maxDelay: 30000`, `jitter: true`). Presence of `retry` (even `{}`) enables retry with defaults, matching how `cache`/`logger` are enabled by presence.
- Alternative considered: a single `retries: number` field (mirroring `timeout: number`). Rejected — unlike timeout, retry needs several independently-meaningful knobs (count, base delay, cap, predicate); collapsing them into one primitive would force a second option anyway.

**Per-call override replaces, not merges**: `FetchifyMethodOptions.retry` fully replaces the client-level `retry` config for that call (`retry: false` disables it outright). No deep-merge of individual fields.
- Alternative considered: shallow-merge per-call fields over the client default (like `headers`). Rejected for simplicity and predictability — `timeout` (the closest precedent) is also a full override, not a merge, and a retry config is small enough to restate in full when a call needs different behavior.

**Default retry eligibility — idempotency-gated, not just status-gated**: the default `retryOn` predicate is `isIdempotent(method) && isTransient(error)`, where `isIdempotent` allows `GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`, and `isTransient` is true for a raw network failure (fetch rejection not caused by the caller's own signal), a `FetchifyTimeoutError`, or a `FetchifyError` with status `408`, `429`, `500`, `502`, `503`, `504`.
- Alternative considered: retry any method on a transient error, since a slow response doesn't always mean the write landed. Rejected — retrying a `POST` by default risks duplicate side effects on the origin server; consumers who know their `POST` is safe (e.g. idempotency-key protected) can supply a custom `retryOn` to opt in explicitly.

**Caller-triggered aborts are never retried**: the loop distinguishes a timeout-driven abort (already tracked via the existing `timeoutSignal.aborted` check used to construct `FetchifyTimeoutError`) from the caller's own `init.signal` firing, and only the former is eligible for the default predicate. A caller abort always propagates immediately, matching current behavior with no retry attempted, regardless of `retryOn`.

**Backoff formula — capped exponential with full jitter**: for the Nth retry (1-indexed), `computed = min(maxDelay, delay * backoffFactor ** (N - 1))`, and when `jitter` is true (default) the actual wait is `random(0, computed)` ("full jitter", the AWS-recommended strategy for avoiding thundering-herd retries). When `jitter` is false, the wait is `computed` exactly.

**`Retry-After` overrides computed delay, still capped**: when the triggering error is a `FetchifyError` with status `429` or `503` and a parseable `Retry-After` header (integer delta-seconds or an HTTP-date), that value (converted to ms) is used as the wait instead of the backoff formula's output, but still clamped to `maxDelay` — a misbehaving upstream should not be able to stall a caller indefinitely.

**Per-attempt hook and timeout**: each retry re-runs `beforeRequest` (so a hook can refresh a stale auth token or tracing header before the next attempt) and gets a fresh timeout window sized from the same resolved `timeout` value used on attempt 1. This falls out naturally from the loop wrapping the same code path attempt 1 uses; no new requirement text is needed in `request-timeout` since "the underlying network fetch call" already means one fetch call per the existing spec, and a retry's fetch is a new one.

## Risks / Trade-offs

- **Retrying can multiply latency and load** on an already-struggling upstream. → Mitigated by capped exponential backoff with jitter, a `maxDelay` ceiling, and a default `retries` of 3 (not unbounded).
- **Retrying a non-idempotent method could duplicate a write** if a consumer overrides `retryOn` carelessly. → Default predicate excludes `POST`/`PATCH`; documentation on `retryOn` calls out the risk explicitly.
- **`Retry-After` parsing adds a small surface for malformed input** (non-numeric, invalid date). → Falls back to the computed backoff delay whenever the header is absent or unparseable, never throws.

28 changes: 28 additions & 0 deletions openspec/changes/archive/2026-08-07-add-retry-backoff/proposal.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
## Why

Every request made through `createFetchify` fails permanently on the first transient error — a dropped connection, a `FetchifyTimeoutError`, or a `5xx`/`429` response from an upstream that is momentarily overloaded. Consumers must currently hand-roll their own retry loop around every call site, with no client-wide default and no shared backoff/jitter logic. A short-lived blip in an otherwise healthy upstream should not have to surface as a hard failure to the caller.

## What Changes

- Add an optional `retry` (`FetchifyRetryOptions`) to `FetchifyOptions`, configuring the default retry behavior for every request made by the resulting client. Omitting it preserves today's no-retry behavior.
- Add an optional `retry` to `FetchifyMethodOptions`, overriding the client-level retry config for that single call — `retry: false` explicitly disables retry for that call even when the client has a default configured.
- `FetchifyRetryOptions` covers: `retries` (max retry attempts, default `3`), `delay` (base backoff delay in ms, default `200`), `backoffFactor` (multiplier applied per attempt, default `2`), `maxDelay` (cap on any computed delay, default `30000`), `jitter` (apply full jitter to each computed delay, default `true`), and `retryOn` (a predicate overriding which failures are retried).
- Default retry eligibility (when `retryOn` is not supplied): only idempotent methods (`GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`) are retried, and only for network failures, `FetchifyTimeoutError`s, and `FetchifyError`s with status `408`, `429`, `500`, `502`, `503`, or `504`. `POST`/`PATCH` are never retried by default. A caller-triggered `AbortSignal` is never retried, regardless of method.
- A `Retry-After` response header (seconds or HTTP-date) on a `429`/`503` overrides the computed backoff delay for that wait, still bounded by `maxDelay`.
- Each retry attempt re-invokes the configured `beforeRequest` hook and gets its own fresh timeout window (per the existing `request-timeout` capability); retries never apply to a cache-served `GET`.

## Capabilities

### New Capabilities
- `request-retry`: Defines the `retry` option (client-level and per-request), the default retry-eligibility predicate and idempotency restriction, the exponential-backoff-with-jitter delay calculation, `Retry-After` header handling, and how retry composes with timeouts, the `beforeRequest` hook, and caching.

### Modified Capabilities
- `http-client`: `FetchifyMethodOptions` gains a `retry` field, and request handling now retries a failed network attempt before resolving or throwing, per the `request-retry` capability.
- `fetchify-options`: `FetchifyOptions` (and `defineOptions`) gains a `retry` field.

## Impact

- `src/lib/create-fetchify.ts`: the network-attempt portion of request handling gains a retry loop (eligibility check, delay computation, re-running the hook and a fresh timeout per attempt).
- `src/lib/define-options.ts`, `src/types/fetchify-method.ts`: option shapes gain `retry`.
- New `src/types/retry.ts` (or similar) exporting `FetchifyRetryOptions` and `FetchifyRetryContext`.
- No breaking changes — `retry` is opt-in and existing no-retry behavior is unchanged.
Loading
Loading