Skip to content

architecture(fetch): support runtime-backed Request/Response/Headers instead of copy-first objects #8

@medz

Description

@medz

Problem

ht currently behaves like a fully detached fetch-style request/response model. That is convenient and predictable, but in server runtimes it pushes implementations toward a copy-first design:

  • headers are copied into ht.Headers
  • body is materialized into BodyData
  • response metadata is copied back out later

For server hot paths, especially tiny routes, this is often the wrong default.

Proposal

Introduce a design direction where Request, Response, and Headers can be runtime-backed adapters instead of always being eagerly materialized standalone objects.

The default server-side model should prefer:

  1. holding the underlying runtime object
  2. forwarding reads/writes to it
  3. materializing only when the user explicitly needs a detached copy

This is more than a lazy optimization. It is a different ownership model:

  • today: copy first, then operate
  • proposed: hold first, forward operations, detach only when required

Examples of desired semantics

  • reading request headers should not require eagerly copying the full header set
  • mutating headers should ideally forward to the underlying storage while the object is runtime-backed
  • request body should remain unread until actually consumed
  • response headers/body should avoid clone/copy churn on the write path

Why this matters

ht is becoming the common request/response abstraction for higher-level frameworks. If the abstraction itself assumes detached ownership too early, every runtime bridge and every framework above it inherits that cost.

A runtime-backed mode would let downstream runtimes keep hot paths much thinner without giving up the unified API.

Design questions

This likely needs a clearer distinction between:

  • runtime-backed values
  • detached/materialized values

Questions that probably need explicit answers:

  • when is a Request/Response still backed by a live runtime object?
  • what operation detaches/materializes it?
  • how should clone() / copyWith() behave?
  • how much of Headers can be forwarding vs copied state?

Goal

Make ht a better fit for server runtimes by allowing request/response objects to be lightweight adapters first and independent copies second.

That should reduce hot-path overhead more fundamentally than just adding a few local fast paths.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions