@effect/platform: HttpClientRequest emits explicit Content-Length, causing wire mismatches under undici 8.2+

[johanneskares]

Summary

@effect/platform's HttpClientRequest body helpers (bodyUrlParams, bodyUnsafeJson, bodyText, bodyUint8Array) attach an explicit content-length header to outbound requests, computed at request-build time from the encoded Uint8Array.length. The transport (fetch / undici) is supposed to compute that header itself. With undici 8.2.0+ this preempting causes real-world breakage because the value Effect snapshots no longer matches the bytes actually written to the wire.

Where it happens

In packages/platform/src/internal/httpClientRequest.ts, in setBody:

const contentLength = body.contentLength;
if (contentLength) {
  headers = Headers.set(headers, "content-length", contentLength.toString());
}

The Uint8ArrayImpl body type (created by text, uint8Array, unsafeJson, urlParams in internal/httpBody.ts) exposes contentLength from Uint8Array.length. So every request built with the form/json/text helpers carries a caller-supplied content-length header.

Why this matters

The header value Effect emits isn't malformed — it's a correct digit string at the moment Effect builds the request. The problem is that Effect is preempting work the transport owns:

• The WHATWG Fetch spec puts Content-Length on the forbidden request-header list precisely so the implementation can compute the canonical value from what it's actually going to send (after body extraction, interceptor cloning, redirect handling, stream wrapping, OTel instrumentation, etc.).
• Before undici 8.2.0, undici would always recompute its own content-length and overwrite the caller-supplied one, so any drift between Effect's snapshot and the transport's actual byte count was silently corrected.
• undici 8.2.0 (PR nodejs/undici#5060) stopped auto-overriding when the caller already set the header. Now Effect's value goes to the wire unchanged. If anything between the body.length snapshot and the bytes leaving the socket differs by even one byte, the upstream server gets a mismatched Content-Length and rejects the request.

We observed this in production against multiple unrelated third-party APIs that share only the bodyUrlParams code path. Pinning undici to 8.1.0 restored the prior lenient behavior. Note this reproduces on Node 22 even though Node ships its own bundled undici: the moment any dependency does import "undici" (e.g. @vercel/blob, @workflow/world-vercel), userland undici installs itself as the global dispatcher and the new behavior applies process-wide.

Workaround

Replace bodyUrlParams({...}) with HttpBody.raw(new URLSearchParams(...), { contentType: "application/x-www-form-urlencoded" }). HttpBody.raw doesn't expose a contentLength unless you pass it explicitly, so setBody skips emitting the header, and the transport computes it correctly.

Suggested fix

Stop emitting content-length from body.contentLength in setBody. The contentLength field is still useful internally (stream framing, server responses), but it shouldn't be reflected into outbound request headers — the transport is the only layer that can compute a value that matches what's actually sent.

export const setBody = dual(2, (self, body) => {
  let headers = self.headers;
  if (body._tag === "Empty" || body._tag === "FormData") {
    headers = Headers.remove(headers, ["Content-type", "Content-length"]);
  } else {
    const contentType = body.contentType;
    if (contentType) {
      headers = Headers.set(headers, "content-type", contentType);
    }
    // removed: explicit content-length header — let the transport compute it
  }
  return makeInternal(self.method, self.url, self.urlParams, self.hash, headers, body);
});

Reproduction

Against Node 22 + undici 8.2.x:

import { FetchHttpClient, HttpClient, HttpClientRequest } from "@effect/platform"
import { Effect } from "effect"

// Any dep that imports "undici" installs userland 8.x as global dispatcher
await import("undici")

const program = Effect.gen(function* () {
  const http = yield* HttpClient.HttpClient
  return yield* http.execute(
    HttpClientRequest.post("https://api.example.com/oauth/token").pipe(
      HttpClientRequest.bodyUrlParams({ grant_type: "refresh_token", refresh_token: "..." })
    )
  )
})

await Effect.runPromise(program.pipe(Effect.provide(FetchHttpClient.layer)))
// Upstream rejects with a Content-Length mismatch

Pinning userland undici to 8.1.0 resolves it without any Effect change.

Environment

• @effect/platform: 0.96.x
• effect: latest
• node: 22.x
• undici (userland, transitive): 8.2.0+

[truffle-dev]

Fix shape is right. One scope note.

The same body.contentLength → "content-length" emission exists at packages/platform/src/internal/httpServerResponse.ts:43-50. A "remove all body.contentLength header emission" sweep would touch it. Server semantics differ: Effect is the byte source — there's no transport between header-set and wire-write that can reframe (extract → clone → redirect → instrument → write). The value at construction time is the value sent. That one should stay.

The client-side body types whose contentLength reaches setBody are Uint8ArrayImpl (text / unsafeJson / uint8Array / urlParams), and Stream / Raw when user-supplied. The deletion proposed at httpClientRequest.ts:398-401 covers all three at the right layer.