/x/socket_fetch

What?

A remake of some fetch() functionality in pure TypeScript, with a set of pluggable Dialer implementations to customize how network connections are established.

Support for:

• http: over TCP
• https: over TCP + TLS (with custom server name)
• http+unix: over stream-type Unix Domain Sockets (UDS)

Note that this module can & should be deprecated once Deno's HTTP builtins provide comparable networking functionality.

Why?

Deno's fetch() APIs are relatively limited for a server-side runtime. Numerous advanced network features have been lacking:

• HTTP over UNIX domain sockets: denoland/deno#8821
• HTTPS/TLS to IP addresses: denoland/deno#7660
  • Added in Deno v1.34 :)
• HTTPS with TLS client auth: denoland/deno#11721
  • Added in Deno v1.14 :)
• HTTP with weird server behaviors that fail Deno's sanity checks

Unfortunately, HTTP over UNIX domain sockets and HTTPS to IP addresses are both really useful in modern/containerized cloud architecture. For example, the Docker Engine listens only at /var/run/docker.sock by default, and Google Kubernetes Engine HTTPS APIs are only externally reachable via IP address.

In order to support connecting to these endpoints from various modules, I've opted to leverage Deno's TCP primitives directly in a new module.

When?

Consider this library if you:

• Need to send basic HTTP requests to a daemon that listens on a Unix socket
  • Docker Engine, tailscaled, Podman, snapd, etc
• Need to communicate with an HTTPS endpoint that doesn't have a proper DNS name
  • Google Kubernetes Engine API, Kubernetes nodes/pods, IoT devices on your LAN
  • You just need to provide any DNS name that is on the server's certificate
• Need to use a service which has a different DNS name and TLS name
  • I have no examples of this, and I hope you don't either.

Implemented features

• Protocols:
  • http:
  • https:
  • http+unix:
• HTTP/1.1 Requests:
  • Headers
  • Buffered bodies
  • Streaming bodies
  • Connection keep-alive
• HTTP/1.1 Responses:
  • Headers
  • Buffered bodies
  • Streaming bodies

Remaining work

• Rewrite with /std/io/buffer.ts (added in Deno v1.8.3)
• Enable/test connection reuse
• Implement error handling
• Offer easy API for HTTP/1.1 upgrades, useful for Kubernetes SPDY
• Support HTTP/2 when available (using /x/spdy_transport) for improved efficiency and accuracy

What about WebSocket?

In addition to the fetch() limitations listed above, Deno's WebSocket API is even further behind:

• WebSocket doesn't accept Deno.HttpClient: denoland/deno#11846
  • Would enable custom Certificate Authorities
  • Would enable TLS client certificate auth
  • Should enable WebSocket over UNIX domain sockets, once fetch() has it
• WebSocket doesn't allow custom HTTP request headers: denoland/deno#11847

A similar reimplementation effort already exists for WebSocket and so far it addresses custom request headers.