fix(dedupe): clone response per waiter to prevent body-already-used errors (#48)

Author: gkoos

.changeset/neat-hounds-bathe.md

@@ -0,0 +1,12 @@
+---
+'@fetchkit/ffetch': minor
+---
+
+Fixed
+
+- dedupePlugin: each deduplicated caller now receives an independent Response clone, preventing "body already used" errors when multiple concurrent callers consume the response body
+
+Documentation
+
+- deduplication: explained response cloning behaviour and auth header considerations for custom hashFn
+- advanced: clarified that timeout acts as total duration cap including retry wait periods

CHANGELOG.md

@@ -1,71 +1,24 @@
 # ffetch
 
-## 5.4.13
+## 5.4.9 – 5.4.13
 
 ### Patch Changes
 
-- 9dc55ee: Fixed: use CHANGESETS_TOKEN PAT to trigger CI on version PRs
+Internal CI/CD infrastructure releases. No functional changes.
 
-## 5.4.12
+- ci: automated publishing pipeline setup (Node 24, npm Trusted Publishing, OIDC)
+- ci: GitHub Actions pinned to commit SHAs
+- ci: CodeQL, Dependabot, OpenSSF Scorecard, SBOM generation configured
+- ci: fine-grained PAT for changeset version PRs to trigger CI
+- docs: README updated with security section and OpenSSF Scorecard badge
 
-### Patch Changes
-
-- aab0230: test: trigger release
-
-## 5.4.11
-
-### Patch Changes
-
-- 36a70ef: docs: readme updated with security section
-
-## 5.4.10
-
-### Patch Changes
-
-- b1ecd57: docs: readme updated with security section
-
-## 5.4.9
-
-### Patch Changes
-
-- a808121: Fixed: Discord announcement is inlined in publish.yml action
-
-## 5.4.8
-
-### Patch Changes
-
-- 8da944a: fix: discord announcement trigger
-
-## 5.4.7
+## 5.4.3 – 5.4.8
 
 ### Patch Changes
 
-- d084935: chore: changeset created
-
-## 5.4.6
-
-### Patch Changes
-
-- 285f68c: ci: fix action versions and registry-url placement
-
-## 5.4.5
-
-### Patch Changes
-
-- d67f74a: Trigger retry with Node24 fix
-
-## 5.4.4
-
-### Patch Changes
-
-- 5cc69e6: Retry npm publish with corrected repository url
-
-## 5.4.3
-
-### Patch Changes
+Internal CI/CD infrastructure releases. No functional changes.
 
-- f523b31: test: verify automated publishing setup
-- 70bcea4: Test automated publishing workflow
+- ci: automated publishing pipeline initial setup and stabilisation
 
 ## 5.4.2
 

docs/advanced.md

@@ -189,6 +189,8 @@ If you override retry behavior, make sure your custom logic still handles `Retry
 // ffetch will wait until that date/time before retrying
 ```
 
+> **Note**: The `timeout` option acts as a total duration cap across the entire request lifecycle, including retry wait periods. If a server responds with a large `Retry-After` value and the combined wait would exceed the configured `timeout`, the timeout fires and the request throws a `TimeoutError` — the retry wait is interrupted immediately. To allow indefinite waits, set `timeout: 0`.
+
 ## Circuit Breaker Pattern
 
 The circuit breaker pattern protects your service from repeated failures by temporarily blocking requests after a threshold of consecutive errors. This helps prevent cascading failures and allows your system to recover gracefully.

docs/deduplication.md

@@ -56,6 +56,14 @@ const client = createClient({
 - TTL eviction does not reject already in-flight request promises.
 - Stream/FormData request bodies are skipped by the default hash strategy.
 
+## Response Body Consumption
+
+Each deduplicated caller receives an independent `Response` — the first caller gets the original, and each additional concurrent caller receives a clone. This means every caller can consume the response body (`.json()`, `.text()`, `.arrayBuffer()`, etc.) independently without conflict.
+
+Note: `response.url` and `response.redirected` are not preserved on cloned responses (they are read-only on constructed `Response` objects). This is a browser/runtime constraint, not specific to ffetch. In practice, API responses rarely require these properties.
+
+If you need auth headers (e.g. `Authorization`, `Cookie`) to be part of the dedupe key, provide a custom `hashFn` that includes them — the default hash uses method, URL, and body only.
+
 ## Defaults
 
 - `hashFn`: `dedupeRequestHash`

src/plugins/dedupe.ts

@@ -4,10 +4,14 @@ import {
   type DedupeHashParams,
 } from '../dedupeRequestHash.js'
 
+type Waiter = {
+  resolve: (value: Response) => void
+  reject: (reason?: unknown) => void
+}
+
 type DedupeEntry = {
   promise: Promise<Response>
-  resolve: (value: Response | PromiseLike<Response>) => void
-  reject: (reason?: unknown) => void
+  waiters: Waiter[]
   createdAt: number
 }
 
@@ -80,51 +84,33 @@ export function dedupePlugin(options: DedupePluginOptions = {}): ClientPlugin {
 
       const existing = inFlight.get(key)
       if (existing) {
-        return existing.promise
+        return new Promise<Response>((resolve, reject) => {
+          existing.waiters.push({ resolve, reject })
+        })
       }
 
-      let settled = false
-      let resolveFn: (value: Response | PromiseLike<Response>) => void
-      let rejectFn: (reason?: unknown) => void
-
-      const placeholder = new Promise<Response>((resolve, reject) => {
-        resolveFn = (value) => {
-          if (!settled) {
-            settled = true
-            resolve(value)
-          }
-        }
-        rejectFn = (reason) => {
-          if (!settled) {
-            settled = true
-            reject(reason)
-          }
-        }
-      })
-      // Internal placeholder can reject before a consumer attaches handlers.
-      // Mark it observed to avoid unhandled-rejection noise.
-      placeholder.catch(() => undefined)
+      const waiters: Waiter[] = []
+      const actualPromise = next(ctx)
 
       inFlight.set(key, {
-        promise: placeholder,
-        resolve: resolveFn!,
-        reject: rejectFn!,
+        promise: actualPromise,
+        waiters,
         createdAt: Date.now(),
       })
       startSweeper()
 
-      const actualPromise = next(ctx)
-      const entry = inFlight.get(key)
-      if (entry) {
-        actualPromise.then(
-          (result) => entry.resolve(result),
-          (error) => entry.reject(error)
-        )
-        inFlight.set(key, {
-          ...entry,
-          promise: actualPromise,
-        })
-      }
+      actualPromise.then(
+        (result) => {
+          for (const waiter of waiters) {
+            waiter.resolve(result.clone())
+          }
+        },
+        (error) => {
+          for (const waiter of waiters) {
+            waiter.reject(error)
+          }
+        }
+      )
 
       return actualPromise.finally(() => {
         const current = inFlight.get(key)

test/plugins/dedupe.plugin.test.ts

@@ -170,6 +170,46 @@ describe('dedupe plugin parity', () => {
     expect(seenSignal).toBe(controller.signal)
   })
 
+  it('allows all deduped callers to consume the response body independently', async () => {
+    const deferred = createDeferred<Response>()
+    global.fetch = vi.fn().mockReturnValue(deferred.promise)
+
+    const client = createClient({ plugins: [dedupePlugin()] })
+
+    const p1 = client('https://example.com/body')
+    const p2 = client('https://example.com/body')
+
+    deferred.resolve(new Response(JSON.stringify({ value: 42 }), { status: 200 }))
+
+    const [r1, r2] = await Promise.all([p1, p2])
+    const [d1, d2] = await Promise.all([r1.json(), r2.json()])
+
+    expect(d1).toEqual({ value: 42 })
+    expect(d2).toEqual({ value: 42 })
+    expect(global.fetch).toHaveBeenCalledTimes(1)
+  })
+
+  it('allows three deduped callers to consume the response body independently', async () => {
+    const deferred = createDeferred<Response>()
+    global.fetch = vi.fn().mockReturnValue(deferred.promise)
+
+    const client = createClient({ plugins: [dedupePlugin()] })
+
+    const p1 = client('https://example.com/body3')
+    const p2 = client('https://example.com/body3')
+    const p3 = client('https://example.com/body3')
+
+    deferred.resolve(new Response(JSON.stringify({ value: 99 }), { status: 200 }))
+
+    const [r1, r2, r3] = await Promise.all([p1, p2, p3])
+    const [d1, d2, d3] = await Promise.all([r1.json(), r2.json(), r3.json()])
+
+    expect(d1).toEqual({ value: 99 })
+    expect(d2).toEqual({ value: 99 })
+    expect(d3).toEqual({ value: 99 })
+    expect(global.fetch).toHaveBeenCalledTimes(1)
+  })
+
   it('propagates one underlying failure to all deduped callers', async () => {
     const deferred = createDeferred<Response>()
     global.fetch = vi.fn().mockReturnValue(deferred.promise)