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
14 changes: 7 additions & 7 deletions crates/client/readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,17 @@

An endpoint-scoped HTTP client, inspired by Socketry's `Async::HTTP::Client`. It uses the `base-pool 0.5` multiplex pool with capacity one for HTTP/1 connections. The API is experimental.

`Client::new(&scheduler, Endpoint::new(address), options)` returns a request handle and an explicit `Driver`. Poll `driver.run(&lifetime_cancellation)` concurrently with calls and application body consumers. The connection retains transport directions, framing state and reusable codec buffers. The driver supervises dialing, queued calls, TLS progress and retirement. The client provides pull-body `call` and direct writable `open` operations; clones share one endpoint pool.
`Client::new(&scheduler, Endpoint::new(address), options)` returns a request handle and an explicit `Driver`. Poll `driver.run(&lifetime_cancellation)` concurrently with calls and application body consumers. The connection retains transport directions, framing state and reusable codec buffers. The driver supervises dialing, uploads that outlive their call, TLS progress and retirement. The client provides `call`, which takes a request with a body to pull from, and direct writable `open`; both run in the calling task, and clones share one endpoint pool. The client also implements `base-http`'s shared request interface, `Handler`, for a `ClientContext`, so middleware written for any context wraps it.

`call` returns as soon as final response metadata is available. Request upload continues when response consumption pauses or finishes. Incoming frames use a bounded queue. A pool use stays charged until upload finishes and the response is consumed; dropping/closing an unfinished response cancels the exchange and retires its HTTP/1 connection. Pool resource capacity remains charged through both lane retirements and exclusive socket closure. No unread response is automatically drained.
`call` writes the request body from the calling future and returns as soon as final response metadata is available; if the upload is unfinished then, the driver writes the rest, so it continues while response consumption pauses or finishes, and the request body must outlive the client's scope, as a server's request body does. The returned `StreamingResponseBody` reads directly from the connection, with no frame queue, so read it, or drop it to give the connection up. `call` makes progress only while it is polled. A pool use stays charged until upload finishes and the response is consumed; dropping/closing an unfinished response cancels the exchange and retires its HTTP/1 connection. Pool resource capacity remains charged through both lane retirements and exclusive socket closure. No unread response is automatically drained.

`begin_close` rejects new submissions and lets accepted calls finish, then retires the idle connections. Cancelling the driver's lifetime signal terminates outstanding calls and still joins cleanup. Dropping the final client handle begins graceful closure. Dropping the driver is synchronous abandonment and does not perform an asynchronous join; always await its run future. Application errors should cancel its lifetime signal before joining, especially if an upload producer is still waiting.

The existing pull-body `call` path uses statically dispatched transport operations. Heterogeneous request bodies cross its queue through one boxed producer stream per call, with dynamic polling per frame and no boxed future allocation per read. Data is normalized to `Vec<u8>`: vectors move, while borrowed slices are copied. This boundary supports one durable client accepting different body types; it is independent of the scheduler's precise I/O-handle lifetime bounds. Bodies and interim observers may borrow for the driver scope. `Client<'scope>` is therefore invariant over `'scope` and cannot outlive the scheduler borrow. To store a client for longer, keep the scheduler at the application root and make the containing type generic over `'scope`, or use a scheduler that lives for `'static`. Spawning the driver requires its captured work to be `Send + 'static`. Forwarding a transient borrowed server input through a longer-lived client needs an additional ownership design; the existing low-level proxy remains available.
`call` reads the request body and writes each chunk to the direct output path, converting it with `Chunk::into_vec`: vectors move, while borrowed slices are copied. Only an upload unfinished at the response head is boxed, once, as driver work. Bodies may borrow for the driver scope. `Client<'scope>` is therefore invariant over `'scope` and cannot outlive the scheduler borrow. To store a client for longer, keep the scheduler at the application root and make the containing type generic over `'scope`, or use a scheduler that lives for `'static`. Spawning the driver requires its captured work to be `Send + 'static`. A server's request bodies are independent values that outlive their handler, so a handler forwards one through a client in the same scope without copying.

Establishment uses `base-endpoint::AddressEndpoint` over a resolved TCP address. `Options::tcp_nodelay`, enabled by default, disables Nagle's algorithm on each new connection before any plaintext or TLS bytes are sent, so small streamed frames on long-lived duplex exchanges are not delayed by Nagle's algorithm interacting with delayed acknowledgements. It is a best-effort hint: a socket that rejects it is still used. The scheduler must provide `SocketSetOption<TcpNoDelay>`, as every Base scheduler backend does. Enable the `rustls` feature and use `Endpoint::with_tls(config, server_name)` for HTTPS with explicit trust and identity. `Options::protocols` supplies ALPN offers and selects the HTTP engine through `base-http-protocol`, before pool publication. The initial engine is HTTP/1; missing ALPN is compatible by default and can be rejected with `require_alpn`. Endpoint authority supplies missing request authority independently of the routing address and authenticated server name. DNS integration, HTTP/2/3, automatic retry, redirect and proxy policy remain follow-up work. Managed high-level client upgrades and CONNECT are rejected before dialing. `Expect: 100-continue` does not delay upload; `call_with_interim` observes informational responses without accumulating them.
Establishment uses `base-endpoint::AddressEndpoint` over a resolved TCP address. `Options::tcp_nodelay`, enabled by default, disables Nagle's algorithm on each new connection before any plaintext or TLS bytes are sent, so small streamed frames on long-lived duplex exchanges are not delayed by Nagle's algorithm interacting with delayed acknowledgements. It is a best-effort hint: a socket that rejects it is still used. The scheduler must provide `SocketSetOption<TcpNoDelay>`, as every Base scheduler backend does. Enable the `rustls` feature and use `Endpoint::with_tls(config, server_name)` for HTTPS with explicit trust and identity. `Options::protocols` supplies ALPN offers and selects the HTTP engine through `base-http-protocol`, before pool publication. The initial engine is HTTP/1; missing ALPN is compatible by default and can be rejected with `require_alpn`. Endpoint authority supplies missing request authority independently of the routing address and authenticated server name. DNS integration, HTTP/2/3, automatic retry, redirect and proxy policy remain follow-up work. Managed high-level client upgrades and CONNECT are rejected before dialing. `Expect: 100-continue` does not delay upload. Calling the client through `Handler` with a `ClientContext` relays informational responses to the context's observer as they arrive, without accumulating them; `call` discards them.

`Options` bounds pool resources/builds/waiters, total accepted calls and response queue bytes/frames. A saturated accepted-call limit returns `Error::Busy`. Queue byte capacity must accommodate one maximum parser read or trailer section. A caller cancellation signal remains associated with the exchange after `call` returns; cancelling an individual queued body read leaves that body resumable. Direct input cancellation has the stricter behavior described below.
`Options` bounds pool resources/builds/waiters and total accepted requests. A saturated accepted-request limit returns `Error::Busy`. A caller cancellation signal remains associated with the exchange after `call` returns, including an upload the driver finishes. Direct input cancellation has the stricter behavior described below.

Run the complete local example with `cargo run --example client_server`, or `cargo run --features rustls --example client_server -- --https` for HTTPS. The TLS demo trusts its explicitly generated local identity. It sends three POSTs through one pooled HTTP/1 session to an actual `base-http-server` echo handler: a buffered `call`, a sequential writable upload and an independently driven split upload/response. It then joins both peers and cleanup. Rust 1.87 is the minimum supported compiler.

Expand Down Expand Up @@ -47,11 +47,11 @@ The private sequential request sink uses pinned replacement when transferring it

`open_request_with_interim` accepts an informational-response observer; it runs when the pending response is polled. Merely opening or writing the request does not read interims or wait for 100 Continue. Output accepts ordinary data and terminal frames, including trailing fields. Synchronous `close_write(None)` hands final framing back to the supervisor; `flush` or `finish` observes its completion. Dropping unfinished output, a pending response or partial response input abandons the exchange and retires HTTP/1. A dropped pending write is not replayed. Pre-cancelled operations leave the direction usable; cancellation during a direct input read conservatively retires the exchange. Dropping a pending read future retains its pinned decoder state for a subsequent read.

Poll the driver for connection establishment, TLS progress, queued `call`, deferred synchronous `close_write` and retirement. Established plaintext `open`/write/read requests can complete repeatedly without polling it. Encrypted reads, writes and flushes also make direct progress. Incoming TLS records are processed on application reads; control output and cleanup remain supervised. Regressions freeze supervision and exercise both directions for TLS 1.2/1.3. During cancellation/shutdown, poll or drop all outstanding handles before awaiting driver completion: the supervisor cannot reclaim a codec still owned by the application. Pool uses and retiring resources remain charged until both lanes return and cleanup completes. `call` and `open` share admission, request limits, TLS/ALPN and the same pool; no automatic replay is introduced. Returning both codecs synchronously releases the pool use before the next direct request; there is no supervisor acknowledgment on the normal completion path.
Poll the driver for connection establishment, TLS progress, uploads that outlive their `call`, deferred synchronous `close_write` and retirement. Established plaintext `open`/write/read requests can complete repeatedly without polling it. Encrypted reads, writes and flushes also make direct progress. Incoming TLS records are processed on application reads; control output and cleanup remain supervised. Regressions freeze supervision and exercise both directions for TLS 1.2/1.3. During cancellation/shutdown, poll or drop all outstanding handles before awaiting driver completion: the supervisor cannot reclaim a codec still owned by the application. Pool uses and retiring resources remain charged until both lanes return and cleanup completes. `call` and `open` share admission, request limits, TLS/ALPN and the same pool; no automatic replay is introduced. Returning both codecs synchronously releases the pool use before the next direct request; there is no supervisor acknowledgment on the normal completion path.

## Connection task placement

Direct HTTP/1 exchanges execute on their application tasks, with connection-owned state and no mandatory per-request worker handoff. The current scoped prototype still polls supervised connection work together inside the client-wide driver. Queued calls and TLS progress therefore do not distribute across scheduler workers merely by spawning that one future.
HTTP/1 exchanges, through `call` or `open`, execute on their application tasks, with connection-owned state and no mandatory per-request worker handoff. The current scoped prototype still polls supervised connection work together inside the client-wide driver. Deferred uploads and TLS progress therefore do not distribute across scheduler workers merely by spawning that one future.

The scalable design separates client supervision from independently scheduled connection drivers. An HTTP/2 connection driver owns framing, control traffic and stream demultiplexing; the scheduler can distribute separate connections across workers. TLS progress belongs with its connection. The supervisor retains task handles, cancellation and pool retirement accounting and joins them at shutdown. Connections do not each need a dedicated thread, and HTTP/1 direct bodies still do not require pumping tasks.

Expand Down
120 changes: 0 additions & 120 deletions crates/client/src/body.rs

This file was deleted.

Loading