Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion design/client-connection.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ The [client example](../crates/client/examples/client_server.rs) demonstrates bu

Do not make a single client driver the scheduling unit for all connections. A `FuturesUnordered` inside one task permits interleaving but all child polls execute on whichever worker is polling that task. A thousand HTTP/2 connections need independently schedulable connection drivers, each owning its framer/demultiplexer and any TLS progress. Stream queues are a protocol-specific boundary; the connection receive loop must not wait for a slow application writer. The client supervisor owns connection task handles, pool admission and lifecycle cancellation, then joins connection cleanup. This permits distribution across workers without creating one OS thread per connection or one mandatory task per body.

The present borrowed-scope prototype still collects its supervised connection work within one driver; ordinary direct HTTP/1 operations run in their calling tasks. The user decided on 2026-11-20 that this scoped mode stays, with borrowed handlers and bodies and no `Spawn`, and that M6 of the [roadmap](roadmap.md) adds an opt-in spawned mode, chosen per client or server, in which each connection is its own task. The guidance above therefore applies to the spawned mode, which provides the multiworker contract; the scoped mode interleaves its connections within one task by design. The spawned mode is not implemented yet. The scheduler's `Spawn` requires `Send + 'static` captures. A runtime-owned client execution mode must supply owned scheduler/transport state and retain all task handles, or use a separately specified scoped executor. Borrowed bodies cannot be silently extended to static lifetimes. Direct imperative writes can keep borrowed producers in application scope because only owned frame data crosses into the active handle. Resolve this scheduling/ownership boundary before implementing the high-scale HTTP/2 client.
The present borrowed-scope prototype still collects its supervised connection work within one driver; ordinary direct HTTP/1 operations run in their calling tasks. The user decided on 2026-11-20 that this scoped mode stays, with borrowed handlers and bodies and no `Spawn`, and that M6 of the [roadmap](roadmap.md) adds an opt-in spawned mode, chosen per client or server, in which each connection is its own task. The guidance above therefore applies to the spawned mode, which provides the multiworker contract; the scoped mode interleaves its connections within one task by design. The spawned mode is not implemented yet. The scheduler's `Spawn` requires `Send + 'static` captures, and borrowed bodies cannot be silently extended to static lifetimes. The user decided on 2026-11-21 that the spawned mode uses a scoped spawn instead, proposed for `base-scheduler` 0.6 in its scoped spawning requirement: the application runs its program inside a blocking scope, whose tasks run on the scheduler's workers and may borrow anything that outlives the scope, and which returns only after every task has been destroyed. A spawned connection task therefore has the scoped mode's lifetimes: handlers are `Handler<'scope, …>`, request bodies outlive the scope, and a spawned server can forward a body through a spawned client in the same scope. This was chosen over requiring a scheduler borrowed for `'static`, which an application would have to leak, and over reader and writer handles that own their scheduler, which every backend's I/O factories, `base-endpoint`'s TLS streams and the protocols above them would have to adopt. Direct imperative writes can keep borrowed producers in application scope because only owned frame data crosses into the active handle. Resolve this scheduling/ownership boundary before implementing the high-scale HTTP/2 client.

## Storage reuse within a connection

Expand Down
2 changes: 1 addition & 1 deletion design/roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ The initial path uses optional rustls in `base-endpoint::tls` for configuration,

Replace the `base-http-protocol` factories' HTTP/1 codec pairs with selected connections, a closed enum over the engines compiled in, and extend `HttpProtocols` with the enabled engines in preference order and a plaintext policy, as [HTTP/2](http2.md#connection-contract-and-protocol-selection) requires. Make the server and client error and option types version-neutral. Initially HTTP/1 is the only variant; the change lands before HTTP/2 so that its effect on the HTTP/1 path can be measured alone.

Resolve the [task placement](client-connection.md#writable-http1-experiment-and-task-placement) question as decided on 2026-11-20. The scoped mode stays: connection drivers are supervised within the client's or server's own operation, with borrowed handlers, bodies that need only outlive the scope and no scheduler `Spawn`. An opt-in spawned mode, chosen per client or server, makes each connection its own task. It requires the scheduler's `Spawn` and `Send + 'static` handlers and bodies. In both modes, client-wide and server-wide supervision keep owning admission, cancellation and joined retirement, and the direct HTTP/1 client path keeps running in its calling tasks.
Resolve the [task placement](client-connection.md#writable-http1-experiment-and-task-placement) question as decided on 2026-11-20. The scoped mode stays: connection drivers are supervised within the client's or server's own operation, with borrowed handlers, bodies that need only outlive the scope and no scheduler `Spawn`. An opt-in spawned mode, chosen per client or server, makes each connection its own task. It uses the scoped spawn proposed for `base-scheduler` 0.6, decided on 2026-11-21, as [clients and connections](client-connection.md#writable-http1-experiment-and-task-placement) records, so its connection tasks may borrow the scheduler for the program's scope and its handlers and bodies have the scoped mode's lifetimes; it waits for that release. In both modes, client-wide and server-wide supervision keep owning admission, cancellation and joined retirement, and the direct HTTP/1 client path keeps running in its calling tasks.

Move the server's `Handler` into `base-http` as the [shared request interface](middleware.md#shared-request-interface), `Handler<C>` with `ServerContext` carrying the downstream [`Peer`](load-balancer.md#connection-information-and-the-proxy-protocol), in this milestone, decided on 2026-11-20, since both it and the version-neutral errors change the handler interface, so applications adapt once. HTTP/3's early-data flag (M9) and the load balancer (M11) depend on it. The client implements the interface as [middleware](middleware.md#shared-request-interface) records, decided on 2026-11-21: server request bodies become owned, the interface carries the scope lifetime they outlive, `ReadableBody`'s data implements `Chunk`, converting into `Vec<u8>`, and the server's entry points declare `Send` futures. The client's `call` is replaced, as decided on 2026-11-21, by one on the direct path that moves an upload unfinished at the response head to the driver and returns a streaming response body, which the spike measured at the direct writer's per-request cost; it relays interim responses, and `open_request` stays; until the client implements the interface, it keeps its existing `call`.

Expand Down