HTTP server API brainstorming

[lucacasonato]

HTTP handler functions

• What is the handler signature for handling HTTP requests
  • (req: Request) => Promise<Response> | Response
  • Do we pass in the fetch Request object directly, or inside of an object (at a request key)
  • How do you get request metadata that is not on the fetch Request object itself, such as client IP address or geolocation
• Websocket upgrades
• Raw HTTP upgrades
• How do you do middlewares

  • function (req: Request, next: (req: Request) => Promise<Response>): Promise<Response>;

• How do you do routing?
• Proxying HTTP requests/responses to downstream services
• Cookie handling?
• Caching?
• Streaming request bodies / response bodies

HTTP server

• How do you start a server
  • Parallel servers across threads / processes
• Cross cutting concerns with Sockets API - can this layer on-top?
• Keepalive behaviour
• HTTP/1.1 vs HTTP/2 vs HTTP/3
• TLS + client authentication
• Automatic response body compression, and request body decompression

Prior art:

• https://github.com/nodejs/web-server-frameworks

[thescientist13]

A couple thoughts for consideration

For the signature, maybe we would want to allow for an optional ctx object (or otherwise some interplay with something like AsyncLocalStorage / AsyncContext, that I think is common in a lot of web frameworks, e.g.

function (req: Request, next: (req: Request) => Promise<Response>), ctx?: object): Promise<Response>;

Also, would it be worth surveying a handful of HTTP web framework to see what their current signatures look like as prior art? Thinking of:

• Runtimes (Node, Deno, Bun, Workerd)
• Express
• Koa
• Fastify
• Hono

[x-titan]

I would like to suggest a possible handler shape for a server API that keeps HTTP semantics separate from transport-level metadata.

The main idea is:

• the handler receives a standard WHATWG Request
• connection-specific data is provided separately via an info object
• the handler is only a possible building block for a server API, not a full framework abstraction

export type Next = () => Promise<Response | void>

export interface SocketInfo {
  localAddress: string
  remoteAddress: string
  alpn: string | null
}

export type Handler<
  TInfo = unknown
> = (
  request: Request,
  info: TInfo & SocketInfo,
  next: Next
) => MaybePromise<Response | any>