BunHttpClient unstable

When to use

Use when an Effect program should execute HttpClient requests through the platform fetch implementation, especially in browser, edge, or Node.js runtimes with globalThis.fetch.

Details

The layer uses the current Fetch reference and optional RequestInit service for each request. Request-specific method, headers, body, and abort signal are supplied by the client and override matching RequestInit fields.

Gotchas

Fetch behavior comes from the runtime's implementation, so CORS, cookies, redirects, abort handling, and streaming support can vary by platform. fetch follows redirects itself by default, so HttpClient.followRedirects has no effect unless RequestInit sets redirect: "manual". Trace propagation is on by default, and a browser preflight fails unless the target allows b3 and traceparent. Stream request bodies are sent as Web streams with duplex: "half" when the runtime supports it; see StreamBodyFallback for the unsupported case. Any content-length header is removed before calling fetch. Chrome passes the support check but rejects streaming uploads over HTTP/1.1, which surfaces as a TransportError, and browsers only deliver the response after the entire request body has been sent.

See

• Fetch for supplying the fetch implementation used by this layer
• RequestInit for default RequestInit options applied before request-specific fields
• StreamBodyFallback for opting into buffering on unsupported runtimes
• HttpClient.TracerPropagationEnabled for leaving b3 and traceparent off a browser request

declare const layer: Layer.Layer<HttpClient.HttpClient>

When to use

Use to send every request over a Unix domain socket with { unix: path }, or over TLS with a custom CA and client certificate with { tls: { ca, cert, key } }.

Details

Before each request the options are merged over the RequestInit in effect for that request: the RequestInit service in the request context, or otherwise the one provided while building this layer. An application-wide RequestInit for credentials, cache or default headers therefore still applies, and the native options win per top-level key. Method, body, abort signal and duplex mode are set per request, and request headers override the same keys in headers.

See

• Options for the accepted fields

declare function layerOptions(options: Options): Layer<HttpClient>

import { BunHttpClient } from "@effect/platform-bun"

const DockerClient = BunHttpClient.layerOptions({ unix: "/var/run/docker.sock" })

import { BunHttpClient } from "@effect/platform-bun"

declare const ca: string
declare const cert: string
declare const key: string

const MtlsClient = BunHttpClient.layerOptions({ tls: { ca, cert, key } })

Details

This is Bun's BunFetchRequestInit without the fields the client sets per request: method, body, signal and duplex. headers are merged with the request headers, with request headers taking precedence.

Bun-specific fields include unix for a Unix domain socket path, tls for ca, cert, key, rejectUnauthorized and checkServerIdentity, proxy, session for a shared connection pool, protocol, decompress, verbose and s3. Standard RequestInit fields such as credentials or redirect are accepted too.

type Options = Omit<BunFetchRequestInit, "method" | "body" | "signal" | "duplex">

Details

Defaults to globalThis.fetch.

declare const Fetch: Context.Reference<typeof globalThis.fetch>

When to use

Use to provide default credentials, cache, redirect, integrity, or other fetch options for outgoing HTTP requests.

Details

Request-specific method, headers, body, and abort signal are supplied by the client when a request is executed.

See

• HttpClient.followRedirects for following redirects in the client, which needs { redirect: "manual" } here

declare class RequestInit extends RequestInit_base {
  constructor(_: never);
}

Details

Defaults to "error", which fails with an EncodeError without sending the request. Set to "buffer" to collect the entire stream in memory and send it as a single body instead. Runtimes with streaming support always send the stream.

Gotchas

Buffering keeps the entire upload in memory and can exhaust memory for large or unbounded uploads. Support is detected once, on the first stream body sent, using the global Request implementation even when a custom Fetch is provided.

declare const StreamBodyFallback: Context.Reference<"buffer" | "error">