-
Notifications
You must be signed in to change notification settings - Fork 0
architecture(fetch): support runtime-backed Request/Response/Headers instead of copy-first objects #8
Description
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:
- holding the underlying runtime object
- forwarding reads/writes to it
- 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/Responsestill backed by a live runtime object? - what operation detaches/materializes it?
- how should
clone()/copyWith()behave? - how much of
Headerscan 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.