Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Typed unix socket and TLS options for `BunHttpClient` and `DenoHttpClient`

Closed
  • Is something wrong?
#9,687 0 comments 0 reactions 1 assignee View on GitHub

Maintainers usually reply within 1 day

@effect-bot is already working on this.

Since Oct 21, 2026.

  • #9704 by @tim-smart — merged

Assessment

This issue has not been assessed yet.

Description

docker-made-me-do-it enhancement platform

Problem

NodeHttpClient has typed layers for connecting over a unix socket and for custom TLS (#9158):

NodeHttpClient.layerUndiciOptions({ connect: { socketPath: "/var/run/docker.sock" } })
NodeHttpClient.layerUndiciOptions({ connect: { ca, cert, key, servername } })

Bun and Deno have nothing equivalent: BunHttpClient and DenoHttpClient only re-export FetchHttpClient. Both runtimes can do the same things, but only through fetch fields that aren't in the standard RequestInit:

  • Bun: fetch(url, { unix, tls: { ca, cert, key, rejectUnauthorized, serverName } })
  • Deno: fetch(url, { client }), where the client comes from Deno.createHttpClient({ caCerts, cert, key, proxy: { transport: "unix", path } }) and has to be closed afterwards.

You can get there by providing FetchHttpClient.RequestInit or a custom Fetch, but it isn't documented, and the types don't fit. Effect's own Kubernetes integration, which only needs to trust one CA file, does it three different ways:

  • Node: an undici Agent (packages/platform/node/src/NodeClusterSocket.ts:150-174).
  • Bun: { tls: { ca } } as any (packages/platform/bun/src/BunClusterSocket.ts:156-160).
  • Deno: a wrapped fetch that injects client with as any and closes it when the scope ends (packages/platform/deno/src/DenoClusterSocket.ts:197-201).

Anyone who needs the Docker socket on Bun, or a client certificate on Deno, has to rediscover all of this.

Proposal

One layer per runtime that takes that runtime's own options, the same way the Node layers take undici's options:

BunHttpClient.layerOptions({ unix: "/var/run/docker.sock" })
BunHttpClient.layerOptions({ tls: { ca, cert, key } })

DenoHttpClient.layerOptions({ proxy: { transport: "unix", path: "/var/run/docker.sock" } })
DenoHttpClient.layerOptions({ caCerts: [ca], cert, key })
  • Bun passes the options into every fetch call.
  • Deno creates the Deno.HttpClient in the layer's scope and closes it when the scope ends.
  • The JSDoc for each layer says what is supported. For example, Deno has no option to skip certificate verification or to set the server name.

Then switch the Bun and Deno Kubernetes layers over and remove the casts.

Why in Effect

HttpClient is meant to be portable, yet on two of the three server runtimes these settings are only reachable through untyped, undocumented fields. This is the Node change from #9158 applied to Bun and Deno, with no new concepts.

Scope

In scope:

  • layerOptions for Bun and Deno, with docs.
  • Using them in the Kubernetes layers.

Out of scope:

  • A connection or TLS type shared by all runtimes.
  • http+unix:// URLs, which have no standard scheme.
  • Per-request connection settings.
Dominant language
TypeScript
Stars
16.7k
Forks
808
Avg merge
10h 52m
Merged PRs (30d)
836

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Effect-TS/effect

All issues in Effect-TS/effect

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.