diff --git a/crates/client/readme.md b/crates/client/readme.md index b1fd29bc..2c7851d2 100644 --- a/crates/client/readme.md +++ b/crates/client/readme.md @@ -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`: 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`, 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`, 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. @@ -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. diff --git a/crates/client/src/body.rs b/crates/client/src/body.rs deleted file mode 100644 index 19db9e46..00000000 --- a/crates/client/src/body.rs +++ /dev/null @@ -1,120 +0,0 @@ -// Released under the MIT License. -// Copyright, 2026, by Samuel Williams. - -use crate::{Error, driver::lock}; -use base_http::body::{BodyError, BodyFrame, BodyReader, ReadableBody}; -use base_scheduler::Cancellation; -use event_listener::Event; -use std::sync::{Arc, Mutex}; - -#[derive(Clone, Copy, PartialEq, Eq)] -enum State { - Reading, - Complete, - Abandoned, -} - -pub(crate) struct Consumption { - state: Mutex, - changed: Event, - cancellation: Cancellation, -} -impl Consumption { - pub fn new(cancellation: Cancellation) -> Arc { - Arc::new(Self { - state: Mutex::new(State::Reading), - changed: Event::new(), - cancellation, - }) - } - pub(crate) fn complete(&self) { - let mut state = lock(&self.state); - if *state == State::Reading { - *state = State::Complete; - } - drop(state); - self.changed.notify(usize::MAX); - } - fn abandon(&self) { - let mut state = lock(&self.state); - if *state != State::Reading { - return; - } - *state = State::Abandoned; - drop(state); - self.cancellation.cancel(); - self.changed.notify(usize::MAX); - } - pub async fn wait(&self) -> Result<(), Error> { - loop { - event_listener::listener!(self.changed => listener); - match *lock(&self.state) { - State::Complete => return Ok(()), - State::Abandoned => return Err(Error::Abandoned), - State::Reading => {} - } - listener.await; - } - } -} - -/// Incoming response frames. Completion or abandonment is reported to the -/// client driver; response reads do not drive request upload or socket I/O. -/// -/// A pending read can be dropped without losing a frame, so reads can race other futures such as a command channel or timer. See [polling reads alongside other I/O](base_http::body#polling-reads-alongside-other-io). -pub struct ResponseBody { - pub(crate) reader: BodyReader, - pub(crate) consumption: Arc, - pub(crate) length: Option, - pub(crate) trailers: bool, -} -impl ReadableBody for ResponseBody { - type Data = Vec; - type Error = BodyError; - fn is_ready(&self) -> bool { - self.reader.is_ready() - } - fn is_empty(&self) -> bool { - self.reader.is_empty() - } - fn length(&self) -> Option { - self.length - } - fn may_have_trailers(&self) -> bool { - self.trailers - } - fn close(&mut self, error: Option) { - self.consumption.abandon(); - self.reader.close(error); - } - async fn read(&mut self, cancellation: &Cancellation) -> Result>, BodyError> { - let frame = self.reader.read(cancellation).await?; - if frame.is_end() { - self.consumption.complete(); - } - Ok(frame) - } -} -impl Drop for ResponseBody { - fn drop(&mut self) { - self.consumption.abandon(); - } -} - -#[cfg(test)] -mod tests { - use super::*; - use futures_lite::future::block_on; - - #[test] - fn abandonment_is_final_and_cancels_the_exchange() { - let cancellation = Cancellation::new(); - let consumption = Consumption::new(cancellation.clone()); - consumption.abandon(); - assert!(cancellation.is_cancelled()); - // A late end of input cannot turn an abandoned body into a reusable exchange. - consumption.complete(); - let error = block_on(consumption.wait()).unwrap_err(); - assert_eq!(error.to_string(), "HTTP client response abandoned"); - } -} diff --git a/crates/client/src/call.rs b/crates/client/src/call.rs new file mode 100644 index 00000000..f52a385a --- /dev/null +++ b/crates/client/src/call.rs @@ -0,0 +1,223 @@ +// Released under the MIT License. +// Copyright, 2026, by Samuel Williams. + +//! Requests with a body to send: the calling future writes the body until the +//! response head arrives, then the client's driver writes any remainder. +use crate::{ + Client, Error, RequestBodyWriter, StreamingResponseBody, WritableRequest, driver::checked, +}; +use base_http::{ + ClientContext, Handler, HandlerContext, InterimHandler, InterimRelay, Request, RequestMetadata, + Response, ResponseMetadata, + body::{Chunk, ReadableBody}, +}; +use base_scheduler::Cancellation; +use futures_util::future::{Either, select}; +use std::{ + convert::Infallible, + future::{Future, poll_fn}, + pin::pin, + task::Poll, +}; + +/// A request body being written to its exchange's output. +struct Upload<'scope, B> { + source: B, + sink: RequestBodyWriter<'scope>, + cancellation: Cancellation, +} + +impl Upload<'_, B> { + /// Write the rest of the body. Dropping this future loses nothing: the sink + /// retains a write in progress, and a pending read consumes nothing. + async fn run(&mut self) -> Result<(), Error> { + loop { + poll_fn(|cx| self.sink.poll_writable(cx, &self.cancellation)).await?; + if self.sink.is_ended() { + return Ok(()); + } + // A read waiting for the source stops when the exchange ends + // early, such as when its response is dropped unfinished. + let read = async { + self.source + .read(&self.cancellation) + .await + .map_err(Error::body) + }; + let frame = checked(read, self.sink.exchange_cancellation()).await?; + self.sink + .start_frame(frame.map_data(Chunk::into_vec), &self.cancellation); + } + } + + /// Stop writing after a failure, abandoning the exchange's output. + fn abort(mut self) { + self.sink.abort(); + self.source.close(None); + } +} + +/// Poll `work` while writing `upload`. Returns `work`'s result and whether the +/// upload finished; an upload failure is returned in place of `work`'s result. +async fn alongside( + upload: &mut Upload<'_, B>, + work: impl Future>, +) -> (Result, bool) { + let mut work = pin!(work); + let mut finished = false; + let mut run = pin!(upload.run()); + let result = poll_fn(|cx| { + if !finished && let Poll::Ready(result) = run.as_mut().poll(cx) { + result?; + finished = true; + } + work.as_mut().poll(cx) + }) + .await; + (result, finished) +} + +/// Split `request`, declaring its body's known length so the request is +/// framed by its body, as a server's response is: a body of known length is +/// sent with `Content-Length`, which a contradicting declaration cannot change. +fn framed(request: Request) -> (RequestMetadata, B) { + let (mut metadata, source) = request.into_parts(); + if let Some(length) = source.length() { + metadata.content_length = Some(length); + } + (metadata, source) +} + +fn ignore(_: ResponseMetadata) -> std::future::Ready> { + std::future::ready(Ok(())) +} + +impl<'scope> Client<'scope> { + /// Send `request` and return its response once the head arrives. + /// + /// This future writes the request body until then; any remainder is + /// written by the client's driver, so the body must outlive the client's + /// scope, as a server's request body does. The response body reads directly + /// from the connection as it is read, so read it, or drop it to give the + /// connection up. Interim responses are discarded; call the client through + /// [`Handler`] with a [`ClientContext`] to observe them. A reused idle + /// connection is checked before any request bytes are sent, and one the + /// server closed is replaced. No automatic retries occur. + pub async fn call( + &self, + request: Request, + cancellation: &Cancellation, + ) -> Result>, Error> { + let (metadata, mut source) = framed(request); + let opened = match self + .open_request_with_interim(metadata, ignore, cancellation) + .await + { + Ok(opened) => opened, + Err(error) => { + source.close(None); + return Err(error); + } + }; + self.send(source, opened, |pending| pending, cancellation) + .await + } + + /// As [`call`](Self::call), relaying interim responses to `context`'s + /// observer as they arrive. + async fn call_with_context( + &self, + request: Request, + context: &mut ClientContext, + cancellation: &Cancellation, + ) -> Result>, Error> { + let (metadata, mut source) = framed(request); + // The exchange retains its observer for the client's scope, longer + // than this borrow of the context, so it hands each interim response + // to this call, which relays it while waiting for the final head. + let relay = InterimRelay::new(); + let opened = match self + .open_request_with_interim(metadata, relay.sender(), cancellation) + .await + { + Ok(opened) => opened, + Err(error) => { + source.close(None); + return Err(error); + } + }; + let relay = &relay; + self.send( + source, + opened, + |mut pending| async move { + loop { + let interim = match select(&mut pending, pin!(relay.next())).await { + Either::Left((response, _)) => return response, + Either::Right((interim, _)) => interim, + }; + let observed = context + .interim() + .send_interim_response(interim, cancellation) + .await; + relay.complete(observed); + } + }, + cancellation, + ) + .await + } + + async fn send( + &self, + source: B, + opened: WritableRequest<'scope>, + head: F, + cancellation: &Cancellation, + ) -> Result>, Error> + where + B: ReadableBody + 'scope, + F: FnOnce(crate::PendingResponse<'scope>) -> Head, + Head: Future>, Error>>, + { + let (sink, pending) = opened.split(); + let mut upload = Upload { + source, + sink, + cancellation: cancellation.clone(), + }; + let (response, finished) = alongside(&mut upload, head(pending)).await; + let response = match response { + Ok(response) => response, + Err(error) => { + upload.abort(); + return Err(error); + } + }; + if !finished { + // A closed queue drops this work, whose sink abandons the exchange. + let _ = self.queue.push_work(Box::pin(async move { + if upload.run().await.is_err() { + upload.abort(); + } + })); + } + Ok(response) + } +} + +/// A client is the upstream end of the shared request interface: middleware +/// written for any context, or for [`ClientContext`], wraps it. +impl<'scope, I: InterimHandler> Handler<'scope, ClientContext> for Client<'scope> { + type Error = Error; + type Body = StreamingResponseBody<'scope>; + + fn call( + &self, + request: Request, + context: &mut ClientContext, + cancellation: &Cancellation, + ) -> impl Future>, Error>> + Send { + self.call_with_context(request, context, cancellation) + } +} diff --git a/crates/client/src/connection.rs b/crates/client/src/connection.rs index 8f26f505..95b3e86d 100644 --- a/crates/client/src/connection.rs +++ b/crates/client/src/connection.rs @@ -2,10 +2,8 @@ // Copyright, 2026, by Samuel Williams. use crate::{ - Endpoint, Error, Options, ResponseBody, - body::Consumption, - driver::{Assigned, Operation, Queue, checked, linked, lock}, - outgoing::Interim, + Endpoint, Error, Options, + driver::{Queue, checked, lock}, writable::{ COMPLETE, ExchangeCompletion, FINALIZE, Open, OpenFactory, Opening, Return, ReturnTo, }, @@ -14,10 +12,6 @@ use base_endpoint::{ AddressEndpoint, ConnectEndpoint, stream::{ReadableStream, WritableStream}, }; -use base_http::{ - InterimResponses, Response, - body::{BodyError, BodyReader, ReadableBody}, -}; use base_http1::{RequestWriter, ResponseReader}; use base_pool::{Admission, MultiplexBuildPermit, MultiplexResource}; use base_scheduler::{ @@ -26,14 +20,12 @@ use base_scheduler::{ }; use event_listener::Event; use futures_channel::oneshot; -use futures_util::future::join; use std::sync::{ Arc, Mutex, Weak, atomic::{AtomicBool, Ordering}, }; struct Inner<'scope> { - assigned: Mutex>>, direct: Mutex + 'scope>>>, changed: Event, stop: Cancellation, @@ -41,8 +33,8 @@ struct Inner<'scope> { } /// An established HTTP/1 session retaining its transport and codec buffers. -/// Direct requests take and return its directions in the calling task; -/// supervised work handles construction, queued calls and retirement. +/// Requests take and return its directions in the calling task; supervised +/// work handles construction and retirement. #[derive(Clone)] pub struct Connection<'scope> { inner: Arc>, @@ -51,7 +43,6 @@ impl<'scope> Connection<'scope> { fn new() -> Self { Self { inner: Arc::new(Inner { - assigned: Mutex::new(None), direct: Mutex::new(None), changed: Event::new(), stop: Cancellation::new(), @@ -62,13 +53,6 @@ impl<'scope> Connection<'scope> { pub(crate) fn clone_handle(&self) -> Self { self.clone() } - pub(crate) fn submit(&self, assigned: Assigned<'scope>) { - let mut slot = lock(&self.inner.assigned); - assert!(slot.is_none(), "HTTP/1 admits one exchange at a time"); - *slot = Some(assigned); - drop(slot); - self.inner.changed.notify(usize::MAX); - } pub(crate) fn open(&self, opening: Open<'scope>) -> Opening<'scope> { // Admission is published only after the session installs its direct state, which it never removes. let direct = lock(&self.inner.direct) @@ -85,28 +69,16 @@ impl<'scope> Connection<'scope> { .expect("an admitted connection has direct state"); direct.probe() } - async fn next(&self, lifetime: &Cancellation) -> Option> { - loop { - event_listener::listener!(self.inner.changed => listener); - if let Some(assigned) = lock(&self.inner.assigned).take() { - return Some(assigned); - } - if checked( - checked( - async { - listener.await; - Ok(()) - }, - &self.inner.stop, - ), - lifetime, - ) - .await - .is_err() - { - return None; - } - } + /// Wait until the connection is stopped or its lifetime ends. + async fn stopped(&self, lifetime: &Cancellation) { + let _ = checked( + checked( + std::future::pending::>(), + &self.inner.stop, + ), + lifetime, + ) + .await; } pub(crate) fn stop(&self) { self.inner.stop.cancel(); @@ -139,8 +111,6 @@ impl Drop for Owner<'_> { if let Some(registration) = &self.registration { registration.retire(); } - let abandoned = lock(&self.connection.inner.assigned).take(); - drop(abandoned); self.connection.finish(Err(Error::Closed)); } } @@ -204,7 +174,6 @@ pub(crate) async fn run<'scope, S>( &mut owner, &mut build, &mut ready, - &options, &cancellation, &lifetime, queue.clone(), @@ -243,7 +212,6 @@ pub(crate) async fn run<'scope, S>( &mut owner, &mut build, &mut ready, - &options, &cancellation, &lifetime, queue.clone(), @@ -478,7 +446,6 @@ async fn session<'scope, R, W>( owner: &mut Owner<'scope>, build: &mut Option>>, ready: &mut Option>>, - options: &Options, cancellation: &Cancellation, lifetime: &Cancellation, queue: Weak>, @@ -494,20 +461,14 @@ where } // Set the direct interface before publication; no admitted caller can see // a connection without its codec storage. - let Ok(registration) = build + // The pool closes only once the driver's cancellation, which construction + // inherits from its waiting request, has been cancelled, and that was + // checked above with no wait since, so the pool is still open. + let registration = build .take() .unwrap() .commit(owner.connection.clone(), Admission::concurrent(0)) - else { - // Commit fails only once shutdown has closed the pool, which queues this connection for retirement. Its waiter sees the closed client, and only a failed close is a driver failure. - let ready = ready.take().expect("a session reports readiness once"); - let _ = ready.send(Err(Error::Closed)); - let input = input.close().await; - let output = output.close().await; - input?; - output?; - return Ok(()); - }; + .expect("the pool closes only after construction is cancelled"); owner.registration = Some(registration.clone()); let state = Arc::new(Http1Connection { codecs: Mutex::new(Codecs { @@ -526,161 +487,17 @@ where // Construction runs one session, and reports readiness itself only if the session never does. let ready = ready.take().expect("a session reports readiness once"); let _ = ready.send(Ok(())); - // Only queued pull-body calls run here. Imperative open/write/read acquires the retained state directly on the calling task. - while let Some(Assigned { - mut operation, - active, - }) = owner.connection.next(lifetime).await - { - // Direct exchanges restore both directions before releasing their use, and closing begins only after this loop. - let (mut input, mut output) = state - .take() - .expect("an admitted exchange finds both codec directions"); - let local = operation.cancellation.clone(); - let caller = operation.lifetime.clone(); - let outcome = linked( - exchange(&mut input, &mut output, &mut operation, options), - &local, - &caller, - lifetime, - ) - .await; - operation.request.body.close(None); - if let Some(reply) = operation.reply.take() { - let _ = reply.send(Err(outcome - .as_ref() - .err() - .cloned() - .unwrap_or(Error::Closed))); - } - let reusable = matches!(outcome, Ok(true)); - if !reusable { - state.registration.retire(); - } - { - let mut codecs = lock(&state.codecs); - codecs.input = Some(input); - codecs.output = Some(output); - } - drop(operation); - active.complete(); - if !reusable { - break; - } - } + // Requests acquire the retained state directly on their calling tasks; + // the session only keeps the connection until it is stopped. + owner.connection.stopped(lifetime).await; state.registration.retire(); state.close().await } -async fn exchange( - input: &mut ResponseReader, - output: &mut RequestWriter, - operation: &mut Operation<'_>, - options: &Options, -) -> Result { - let Operation { - request, - interim, - reply, - cancellation, - .. - } = operation; - let metadata = request.metadata.clone(); - let headers = AtomicBool::new(false); - let send = async { - let result = checked( - async { - output - .write_request(request, cancellation) - .await - .map_err(Error::from) - }, - cancellation, - ) - .await; - // Preserve a readable final response when the peer refuses further - // upload. The connection is retired even if that response succeeds. - if result.is_err() && !headers.load(Ordering::Acquire) { - cancellation.cancel(); - } - result - }; - let receive = async { - let mut writer = None; - let result = checked( - async { - let mut observer = InterimResponses::new(Interim(interim.as_mut())); - let mut response = input - .read_response(&metadata, &mut observer, cancellation) - .await?; - let consumption = Consumption::new(cancellation.clone()); - let empty = response.body.is_empty(); - let (reader, mut producer) = BodyReader::bounded( - options.response_buffer_bytes, - options.response_buffer_frames, - ); - // Publish known-empty input as completed before handing it to - // another task. Its consumer may drop it immediately, without - // racing a redundant End write or retiring a healthy session. - if empty { - consumption.complete(); - producer.close_write(None); - } - let body = ResponseBody { - reader, - consumption: consumption.clone(), - length: response.body.length(), - trailers: response.body.may_have_trailers(), - }; - writer = Some(producer); - let returned = Response::from_parts(response.metadata, body); - if reply.take().unwrap().send(Ok(returned)).is_err() { - return Err(Error::Abandoned); - } - headers.store(true, Ordering::Release); - if !empty { - loop { - let frame = response.body.read(cancellation).await?; - let end = frame.is_end(); - writer - .as_mut() - .unwrap() - .write_frame(frame, cancellation) - .await?; - if end { - break; - } - } - } - consumption.wait().await - }, - cancellation, - ) - .await; - if let Err(error) = &result { - if let Some(writer) = &mut writer { - writer.close_write(Some(match error { - Error::Body(error) => error.clone(), - error => BodyError::new(error.clone()), - })); - } - cancellation.cancel(); - } - result - }; - let (sent, received) = join(send, receive).await; - match (sent, received) { - (Ok(persistent), Ok(())) => Ok(persistent && input.is_reusable()), - (Err(_), Ok(())) => Ok(false), - (Err(error), Err(Error::Cancelled)) if !matches!(error, Error::Cancelled) => Err(error), - (_, Err(error)) => Err(error), - } -} - #[cfg(test)] mod tests { use super::*; - use crate::{Client, driver::Pending, outgoing::tests::ignore}; + use crate::{Client, driver::Pending, observer::tests::ignore}; use base_http::{Method, RequestMetadata}; use base_scheduler_native::NativeScheduler; use futures_lite::future::{block_on, yield_now, zip}; diff --git a/crates/client/src/driver.rs b/crates/client/src/driver.rs index 957f5359..c147ad5b 100644 --- a/crates/client/src/driver.rs +++ b/crates/client/src/driver.rs @@ -1,11 +1,7 @@ // Released under the MIT License. // Copyright, 2026, by Samuel Williams. -use crate::{ - Connection, Endpoint, Error, Options, ResponseBody, connection, - outgoing::{Observer, OutgoingBody}, -}; -use base_http::{Request, Response, body::ReadableBody}; +use crate::{Connection, Endpoint, Error, Options, connection}; use base_pool::{Acquisition, MultiplexBuildPermit, MultiplexPool, MultiplexUse}; use base_scheduler::{ Cancellation, SocketClose, SocketConnect, SocketOpen, SocketSetOption, SocketStreamReading, @@ -36,22 +32,7 @@ type Factory<'scope> = Box< + Sync + 'scope, >; -pub(crate) type Reply = oneshot::Sender, Error>>; - -pub(crate) struct Operation<'scope> { - pub request: Request>, - pub interim: Box, - pub reply: Option, - pub cancellation: Cancellation, - pub lifetime: Cancellation, - pub _pending: Option>, -} -pub(crate) struct Assigned<'scope> { - pub operation: Operation<'scope>, - pub active: MultiplexUse>, -} struct State<'scope> { - requests: VecDeque>, work: VecDeque>, pending: usize, closed: bool, @@ -64,16 +45,6 @@ pub(crate) struct Queue<'scope> { limit: usize, } impl<'scope> Queue<'scope> { - pub fn push(&self, operation: Operation<'scope>) -> Result<(), Error> { - let mut state = lock(&self.state); - if state.closed { - return Err(Error::Closed); - } - state.requests.push_back(operation); - drop(state); - self.changed.notify(usize::MAX); - Ok(()) - } pub(crate) fn push_work(&self, work: Work<'scope, ()>) -> Result<(), Error> { let mut state = lock(&self.state); if state.abandoned { @@ -86,6 +57,10 @@ impl<'scope> Queue<'scope> { self.changed.notify(usize::MAX); Ok(()) } + /// Whether the driver was dropped, abandoning its work. + pub(crate) fn is_abandoned(&self) -> bool { + lock(&self.state).abandoned + } pub fn begin_close(&self) { lock(&self.state).closed = true; self.changed.notify(usize::MAX); @@ -95,10 +70,7 @@ impl<'scope> Queue<'scope> { let mut state = lock(&self.state); state.closed = true; state.abandoned = true; - ( - std::mem::take(&mut state.requests), - std::mem::take(&mut state.work), - ) + std::mem::take(&mut state.work) }; self.changed.notify(usize::MAX); drop(discarded); @@ -244,7 +216,6 @@ where MultiplexPool::new(options.pool.clone()).expect("Client::new validated the pool options"); let queue = Arc::new(Queue { state: Mutex::new(State { - requests: VecDeque::new(), work: VecDeque::new(), pending: 0, closed: false, @@ -261,7 +232,7 @@ where let options = options.clone(); let endpoint = endpoint.clone(); let lifetime = connection_lifetime.clone(); - // Acquirers hold the queue: the driver's assignment jobs and client handles both retain it. + // Acquirers hold the queue: every request retains it through its client handle. let queue = weak_queue.upgrade().expect("an acquirer retains the queue"); Box::pin(async move { let (ready, established) = oneshot::channel(); @@ -302,24 +273,6 @@ where } } -async fn assign<'scope>(mut operation: Operation<'scope>, context: Arc>) { - let result = context.acquire(&operation.cancellation).await; - match result { - Ok(active) => { - let connection = active.clone_handle(); - connection.submit(Assigned { operation, active }); - } - Err(error) => { - operation.request.body.close(None); - let reply = operation - .reply - .take() - .expect("an unassigned operation retains its reply"); - let _ = reply.send(Err(error)); - } - } -} - async fn run<'scope>( queue: Arc>, context: Arc>, @@ -332,22 +285,7 @@ async fn run<'scope>( let mut cleaned = None; loop { event_listener::listener!(queue.changed => listener); - let (requests, work) = { - let mut state = lock(&queue.state); - ( - std::mem::take(&mut state.requests), - std::mem::take(&mut state.work), - ) - }; - for operation in requests { - let context = context.clone(); - jobs.push(Box::pin(async move { - let local = operation.cancellation.clone(); - let lifetime = operation.lifetime.clone(); - let driver = context.cancellation.clone(); - linked(assign(operation, context), &local, &lifetime, &driver).await; - })); - } + let work = std::mem::take(&mut lock(&queue.state).work); jobs.extend(work); let close = { let state = lock(&queue.state); @@ -432,26 +370,6 @@ pub(crate) fn checked( cancellation, } } -// Propagate lifetime cancellation without dropping owned construction/cleanup. -pub(crate) async fn linked( - work: impl Future, - cancellation: &Cancellation, - lifetime: &Cancellation, - driver: &Cancellation, -) -> T { - let mut work = pin!(work); - let mut a = pin!(lifetime.cancelled()); - let mut b = pin!(driver.cancelled()); - poll_fn(|cx| { - if !cancellation.is_cancelled() - && (a.as_mut().poll(cx).is_ready() || b.as_mut().poll(cx).is_ready()) - { - cancellation.cancel(); - } - work.as_mut().poll(cx) - }) - .await -} pub(crate) struct CancelOnDrop(pub Cancellation, pub bool); impl Drop for CancelOnDrop { fn drop(&mut self) { @@ -465,7 +383,7 @@ impl Drop for CancelOnDrop { mod tests { use super::*; use crate::{Endpoint, Options}; - use base_http::{Method, body::EmptyBody}; + use base_scheduler_native::NativeScheduler; use std::{ sync::atomic::Ordering, @@ -539,7 +457,6 @@ mod tests { fn pending_completion_wakes_supervisor_only_when_closed_and_drained() { let queue = Arc::new(Queue { state: Mutex::new(State { - requests: VecDeque::new(), work: VecDeque::new(), pending: 0, closed: false, @@ -586,25 +503,14 @@ mod tests { } #[test] - fn requests_pushed_after_close_are_rejected() { + fn acquiring_from_a_closed_pool_fails() { let scheduler = NativeScheduler::new().unwrap(); let parts = parts(&scheduler); - parts.queue.begin_close(); - let operation = Operation { - request: Request::new( - Method::GET, - "/", - OutgoingBody::new(EmptyBody, Cancellation::never()), - ), - interim: Box::new(crate::outgoing::tests::ignore), - reply: None, - cancellation: Cancellation::new(), - lifetime: Cancellation::never(), - _pending: None, - }; - let error = parts.queue.push(operation).unwrap_err(); + parts.pool.begin_close(); + let error = futures_lite::future::block_on(parts.context.acquire(&Cancellation::never())) + .err() + .unwrap(); assert_eq!(error.to_string(), Error::Closed.to_string()); - assert!(lock(&parts.queue.state).requests.is_empty()); } #[test] diff --git a/crates/client/src/lib.rs b/crates/client/src/lib.rs index 8759be83..e107b710 100644 --- a/crates/client/src/lib.rs +++ b/crates/client/src/lib.rs @@ -5,30 +5,28 @@ #![doc = include_str!("../readme.md")] #![forbid(unsafe_code)] -mod body; +mod call; mod connection; mod driver; mod error; -mod outgoing; +mod observer; mod reuse; mod sink; mod writable; pub use writable::{PendingResponse, RequestBodyWriter, StreamingResponseBody, WritableRequest}; -pub use body::ResponseBody; pub use connection::Connection; pub use driver::Driver; pub use error::Error; -use base_http::{Authority, InterimHandler, Method, Request, Response, Scheme, body::ReadableBody}; +use base_http::{Authority, Scheme}; use base_pool::MultiplexPool; use base_scheduler::{ - Cancellation, SocketClose, SocketConnect, SocketOpen, SocketSetOption, SocketStreamReading, + SocketClose, SocketConnect, SocketOpen, SocketSetOption, SocketStreamReading, SocketStreamWriting, TcpNoDelay, }; -use driver::{CancelOnDrop, Operation, Pending, Queue, checked}; +use driver::Queue; use std::{ - convert::Infallible, net::SocketAddr, sync::{Arc, atomic::Ordering}, }; @@ -94,10 +92,9 @@ pub struct Options { pub http1: base_http1::Options, /// HTTP engine selection, shared by plain and encrypted establishment. pub protocols: base_http_protocol::HttpProtocols, - /// Bound accepted calls, including queued, uploading and unread responses. + /// Bound accepted requests, including those still uploading and unread + /// responses. pub max_requests: usize, - pub response_buffer_bytes: usize, - pub response_buffer_frames: usize, /// Disable Nagle's algorithm on each TCP connection, so small writes such /// as streamed frames are not held back waiting for acknowledgement. This /// is a best-effort latency hint: a socket that rejects it remains usable. @@ -110,8 +107,6 @@ impl Default for Options { http1: base_http1::Options::default(), protocols: base_http_protocol::HttpProtocols::default(), max_requests: 1024, - response_buffer_bytes: 64 * 1024, - response_buffer_frames: 16, tcp_nodelay: true, } } @@ -120,10 +115,7 @@ impl Options { pub fn validate(&self) -> Result<(), Error> { self.pool.validate()?; self.http1.validate()?; - if self.max_requests == 0 - || self.response_buffer_frames == 0 - || self.response_buffer_bytes < self.http1.read_size.max(self.http1.max_head_bytes) - { + if self.max_requests == 0 { return Err(Error::InvalidOptions); } Ok(()) @@ -131,7 +123,9 @@ impl Options { } /// Durable remote-server interface. Clones share connection admission and -/// supervision. `call` submits pull bodies; `open` lends direct HTTP/1 directions. +/// supervision. `call` sends a request with a body to pull from; `open` lends +/// direct HTTP/1 directions for writing one imperatively. Both run in the +/// calling task. /// Neither operation chooses a process-global scheduler. /// /// `'scope` is the scheduler borrow, and it also bounds the request bodies and interim observers that calls queue for the driver. The client and its driver share that queue, so neither can outlive the scheduler. The type is invariant over `'scope`: shortening it would let a call queue a body that borrows shorter-lived data for a driver that keeps running after the data is gone. @@ -190,92 +184,6 @@ impl<'scope> Client<'scope> { pub fn begin_close(&self) { self.queue.begin_close(); } - - /// Return final response metadata promptly. The driver continues upload - /// independently of response consumption. A reused idle connection is - /// checked before any request bytes are sent, and one the server closed is - /// replaced. No automatic retries occur. - pub async fn call( - &self, - request: Request, - cancellation: &Cancellation, - ) -> Result, Error> - where - B: ReadableBody + 'scope, - { - self.call_with_interim( - request, - |_: base_http::ResponseMetadata| async { Ok::<_, Infallible>(()) }, - cancellation, - ) - .await - } - /// Observe informational responses in order, without accumulating a log. - pub async fn call_with_interim( - &self, - mut request: Request, - interim: I, - cancellation: &Cancellation, - ) -> Result, Error> - where - B: ReadableBody + 'scope, - I: InterimHandler + 'scope, - { - if cancellation.is_cancelled() { - request.body.close(None); - return Err(Error::Cancelled); - } - if request.method == Method::CONNECT - || request.protocol.is_some() - || request.fields.contains("upgrade") - { - request.body.close(None); - return Err(Error::Unsupported("managed client tunnels and upgrades")); - } - if request - .scheme - .as_deref() - .is_some_and(|scheme| scheme != self.endpoint.scheme()) - { - request.body.close(None); - return Err(Error::Unsupported( - "request scheme does not match the endpoint", - )); - } - request - .scheme - .get_or_insert_with(|| self.endpoint.request_scheme()); - request - .authority - .get_or_insert_with(|| self.endpoint.authority.clone()); - let local = Cancellation::new(); - let mut guard = CancelOnDrop(local.clone(), true); - let (reply, response) = futures_channel::oneshot::channel(); - let pending = match Pending::new(self.queue.clone()) { - Ok(pending) => pending, - Err(error) => { - request.body.close(None); - return Err(error); - } - }; - let operation = Operation { - request: request.map_body(|body| outgoing::OutgoingBody::new(body, local.clone())), - interim: Box::new(interim), - reply: Some(reply), - cancellation: local, - lifetime: cancellation.clone(), - _pending: Some(pending), - }; - // A queue closed since admission drops the operation and its reply sender, so the response reports `Closed`, as for calls queued when the driver stops. - let _ = self.queue.push(operation); - let response = checked( - async { response.await.map_err(|_| Error::Closed)? }, - cancellation, - ) - .await?; - guard.1 = false; - Ok(response) - } } impl Clone for Client<'_> { fn clone(&self) -> Self { diff --git a/crates/client/src/observer.rs b/crates/client/src/observer.rs new file mode 100644 index 00000000..3341706f --- /dev/null +++ b/crates/client/src/observer.rs @@ -0,0 +1,61 @@ +// Released under the MIT License. +// Copyright, 2026, by Samuel Williams. + +use crate::{Error, driver::Work}; +use base_http::{InterimHandler, ResponseMetadata}; +use base_scheduler::Cancellation; + +/// A type-erased interim-response observer, retained by an exchange's response +/// reader for the client's scope. +pub(crate) trait Observer: Send { + fn response<'a>( + &'a mut self, + metadata: ResponseMetadata, + cancellation: &'a Cancellation, + ) -> Work<'a, Result<(), Error>>; +} +impl Observer for I { + fn response<'a>( + &'a mut self, + metadata: ResponseMetadata, + cancellation: &'a Cancellation, + ) -> Work<'a, Result<(), Error>> { + Box::pin(async move { + self.on_interim_response(metadata, cancellation) + .await + .map_err(Error::body) + }) + } +} +pub(crate) struct Interim<'a>(pub &'a mut dyn Observer); +impl InterimHandler for Interim<'_> { + type Error = Error; + async fn on_interim_response( + &mut self, + metadata: ResponseMetadata, + cancellation: &Cancellation, + ) -> Result<(), Error> { + self.0.response(metadata, cancellation).await + } +} + +#[cfg(test)] +pub(crate) mod tests { + use super::*; + use base_http::Status; + use futures_lite::future::block_on; + use std::convert::Infallible; + + // An interim handler which ignores informational responses. + pub(crate) fn ignore(_: ResponseMetadata) -> std::future::Ready> { + std::future::ready(Ok(())) + } + + #[test] + fn interim_forwarding_reaches_the_observer() { + let mut observer = ignore; + let mut interim = Interim(&mut observer); + let metadata = ResponseMetadata::new(Status::CONTINUE); + block_on(interim.on_interim_response(metadata, &Cancellation::never())).unwrap(); + } +} diff --git a/crates/client/src/outgoing.rs b/crates/client/src/outgoing.rs deleted file mode 100644 index dda30ec7..00000000 --- a/crates/client/src/outgoing.rs +++ /dev/null @@ -1,179 +0,0 @@ -// Released under the MIT License. -// Copyright, 2026, by Samuel Williams. - -use crate::{Error, driver::Work}; -use base_http::{ - InterimHandler, ResponseMetadata, - body::{BodyFrame, Chunk, ReadableBody}, -}; -use base_scheduler::Cancellation; -use futures_util::{ - StreamExt, - stream::{Stream, try_unfold}, -}; -use std::pin::Pin; - -struct Guard(B); -impl Drop for Guard { - fn drop(&mut self) { - self.0.close(None); - } -} - -// One allocation stores the monomorphized producer and its in-flight read -// state. Polling this stream does not allocate a boxed future per body frame. -type Producer<'scope> = - Pin>, Error>> + Send + 'scope>>; -pub(crate) struct OutgoingBody<'scope> { - stream: Option>, - length: Option, - trailers: bool, - empty: bool, -} -impl<'scope> OutgoingBody<'scope> { - pub fn new(body: B, cancellation: Cancellation) -> Self - where - B: ReadableBody + 'scope, - { - let length = body.length(); - let trailers = body.may_have_trailers(); - let empty = body.is_empty(); - let stream = try_unfold( - (Guard(body), cancellation, false), - |(mut body, cancellation, end)| async move { - if end { - return Ok(None); - } - let frame = body.0.read(&cancellation).await.map_err(Error::body)?; - let end = frame.is_end(); - Ok(Some(( - frame.map_data(Chunk::into_vec), - (body, cancellation, end), - ))) - }, - ); - Self { - stream: Some(Box::pin(stream)), - length, - trailers, - empty, - } - } -} -impl ReadableBody for OutgoingBody<'_> { - type Data = Vec; - type Error = Error; - fn length(&self) -> Option { - self.length - } - fn may_have_trailers(&self) -> bool { - self.trailers - } - fn is_empty(&self) -> bool { - self.empty - } - fn close(&mut self, _: Option) { - self.stream = None; - self.empty = true; - } - async fn read(&mut self, cancellation: &Cancellation) -> Result>, Error> { - if cancellation.is_cancelled() { - return Err(Error::Cancelled); - } - let frame = match &mut self.stream { - Some(stream) => stream.next().await.transpose()?.unwrap_or(BodyFrame::End), - None => BodyFrame::End, - }; - self.empty = frame.is_end(); - Ok(frame) - } -} - -pub(crate) trait Observer: Send { - fn response<'a>( - &'a mut self, - metadata: ResponseMetadata, - cancellation: &'a Cancellation, - ) -> Work<'a, Result<(), Error>>; -} -impl Observer for I { - fn response<'a>( - &'a mut self, - metadata: ResponseMetadata, - cancellation: &'a Cancellation, - ) -> Work<'a, Result<(), Error>> { - Box::pin(async move { - self.on_interim_response(metadata, cancellation) - .await - .map_err(Error::body) - }) - } -} -pub(crate) struct Interim<'a>(pub &'a mut dyn Observer); -impl InterimHandler for Interim<'_> { - type Error = Error; - async fn on_interim_response( - &mut self, - metadata: ResponseMetadata, - cancellation: &Cancellation, - ) -> Result<(), Error> { - self.0.response(metadata, cancellation).await - } -} - -#[cfg(test)] -pub(crate) mod tests { - use super::*; - use base_http::{ - Status, - body::{BufferedBody, EmptyBody}, - }; - use futures_lite::future::block_on; - use std::convert::Infallible; - - // An interim handler which ignores informational responses. - pub(crate) fn ignore(_: ResponseMetadata) -> std::future::Ready> { - std::future::ready(Ok(())) - } - - #[test] - fn interim_forwarding_reaches_the_observer() { - let mut observer = ignore; - let mut interim = Interim(&mut observer); - let metadata = ResponseMetadata::new(Status::CONTINUE); - block_on(interim.on_interim_response(metadata, &Cancellation::never())).unwrap(); - } - - #[test] - fn reads_after_completion_or_close_report_the_end() { - let never = Cancellation::never(); - let mut body = OutgoingBody::new(BufferedBody::new([b"hello".to_vec()]), never.clone()); - assert_eq!(body.length(), Some(5)); - // The wrapped body's trailer hint passes through unchanged. - assert!(!body.may_have_trailers()); - let (reader, _writer) = base_http::body::BodyReader::>::bounded(1, 1); - assert!(OutgoingBody::new(reader, never.clone()).may_have_trailers()); - assert!(!body.is_empty()); - let frame = block_on(body.read(&never)).unwrap(); - let expected = BodyFrame::Data { - data: b"hello".to_vec(), - end: true, - }; - assert_eq!(format!("{frame:?}"), format!("{expected:?}")); - assert!(body.is_empty()); - // The producer already finished; another read reports the end again. - assert_eq!(format!("{:?}", block_on(body.read(&never)).unwrap()), "End"); - body.close(None); - assert_eq!(format!("{:?}", block_on(body.read(&never)).unwrap()), "End"); - } - - #[test] - fn cancelled_reads_fail_before_reading_the_body() { - let cancellation = Cancellation::new(); - let mut body = OutgoingBody::new(EmptyBody, cancellation.clone()); - assert!(body.is_empty()); - cancellation.cancel(); - let error = block_on(body.read(&cancellation)).unwrap_err(); - assert_eq!(error.to_string(), Error::Cancelled.to_string()); - } -} diff --git a/crates/client/src/writable.rs b/crates/client/src/writable.rs index c3b5c922..3e483cbe 100644 --- a/crates/client/src/writable.rs +++ b/crates/client/src/writable.rs @@ -5,7 +5,7 @@ use crate::{ Client, Error, driver::{CancelOnDrop, Pending, checked, lock}, - outgoing::{Interim, Observer}, + observer::{Interim, Observer}, reuse::{Cache, Recycle, Reused}, sink::owned_sink, }; @@ -130,7 +130,14 @@ impl<'scope> Client<'scope> { checked(self.context.acquire(&local), &self.context.cancellation), cancellation, ) - .await?; + .await + .map_err(|error| match error { + // A dropped driver closed the client; a cancelled one reports cancellation. + Error::Cancelled if self.queue.is_abandoned() && !cancellation.is_cancelled() => { + Error::Closed + } + error => error, + })?; let connection = active.clone_handle(); let opening = Open { metadata, @@ -319,6 +326,51 @@ impl RequestBodyWriter<'_> { self.sink.take(); self.ended = true; } + /// Poll until the previous frame is written, for callers that interleave + /// output with other work. The write in progress stays in the sink, so a + /// dropped poll loses nothing. After the final frame, the sink is released + /// once it is written. + pub(crate) fn poll_writable( + &mut self, + cx: &mut Context<'_>, + cancellation: &Cancellation, + ) -> Poll> { + if cancellation.is_cancelled() || self.exchange.cancellation.is_cancelled() { + return Poll::Ready(Err(Error::Cancelled)); + } + let sink = self + .sink + .as_mut() + .expect("output retains its sink until its final frame is written"); + if let Err(error) = std::task::ready!(sink.poll_ready_unpin(cx)) { + self.abort(); + return Poll::Ready(Err(error)); + } + if self.ended { + self.sink.take(); + self.completion = Some(Ok(())); + } + Poll::Ready(Ok(())) + } + /// Cancelled when the exchange ends early, such as when its response is + /// dropped unfinished. + pub(crate) fn exchange_cancellation(&self) -> &Cancellation { + &self.exchange.cancellation + } + /// Whether the final frame has been started. + pub(crate) fn is_ended(&self) -> bool { + self.ended + } + /// Start writing `frame` once [`poll_writable`](Self::poll_writable) is + /// ready, before the final frame. + pub(crate) fn start_frame(&mut self, frame: BodyFrame>, cancellation: &Cancellation) { + self.ended = frame.is_end(); + self.sink + .as_mut() + .expect("output retains its sink until its final frame is written") + .start_send_unpin((frame, cancellation.clone())) + .expect("a ready sink accepts a write"); + } } impl WritableBody for RequestBodyWriter<'_> { type Data = Vec; @@ -382,6 +434,7 @@ impl<'scope> Future for PendingResponse<'scope> { length, trailers, empty, + failure: None, }, ))) } @@ -416,6 +469,8 @@ pub struct StreamingResponseBody<'scope> { length: Option, trailers: bool, empty: bool, + /// The failure reported by a close, which later reads return. + failure: Option, } impl ReadableBody for StreamingResponseBody<'_> { type Data = Vec; @@ -429,14 +484,24 @@ impl ReadableBody for StreamingResponseBody<'_> { fn is_empty(&self) -> bool { self.empty } - fn close(&mut self, _: Option) { + /// A body known to be empty, or read to its end, is ready. + fn is_ready(&self) -> bool { + self.empty + } + /// Abandon the rest of the response, which retires its connection unless + /// the body had ended. Later reads report `error`, or the end without one. + fn close(&mut self, error: Option) { self.stream.take(); self.empty = true; + self.failure = error; } async fn read(&mut self, cancellation: &Cancellation) -> Result>, Error> { if cancellation.is_cancelled() { return Err(Error::Cancelled); } + if let Some(failure) = &self.failure { + return Err(failure.clone()); + } if self.empty { return Ok(BodyFrame::End); } diff --git a/crates/client/tests/client/call.rs b/crates/client/tests/client/call.rs index 6ae74374..cb587985 100644 --- a/crates/client/tests/client/call.rs +++ b/crates/client/tests/client/call.rs @@ -4,7 +4,7 @@ use super::{Tracked, accept, chain, head, payload, peer, remainder, run_endpoint, unconnected}; use base_http::{ Method, Protocol, Request, Scheme, - body::{BodyError, EmptyBody, ReadableBody}, + body::{EmptyBody, ReadableBody}, }; use base_http_client::{Endpoint, Error, Options}; use base_scheduler::Cancellation; @@ -50,6 +50,18 @@ fn rejected_calls_close_their_bodies_without_dialing() { ["unsupported HTTP client operation: request scheme does not match the endpoint"] ); assert_eq!(closed.load(Ordering::Relaxed), 5); + + // Calls through the request interface are rejected the same way. + let mut context = base_http::ClientContext::new(|_: base_http::ResponseMetadata| async { + Ok::<_, std::convert::Infallible>(()) + }); + let connect = Request::new(Method::CONNECT, "/", Tracked(closed.clone())); + let error = base_http::Handler::call(&client, connect, &mut context, &never) + .await + .err() + .unwrap(); + assert!(matches!(error, Error::Unsupported(_))); + assert_eq!(closed.load(Ordering::Relaxed), 6); assert_eq!(client.pool_stats().total(), 0); }); } @@ -122,7 +134,7 @@ fn closing_a_response_body_abandons_its_connection() { .call(Request::new(Method::GET, "/", EmptyBody), &never) .await .unwrap(); - response.body.close(Some(BodyError::Abandoned)); + response.body.close(Some(Error::Abandoned)); assert!(response.body.read(&never).await.is_err()); let mut response = client .call(Request::new(Method::GET, "/next", EmptyBody), &never) @@ -157,12 +169,8 @@ fn truncated_response_bodies_report_the_protocol_failure() { Err(error) => break error, } }; - assert_eq!(chain(&error), ["body failed", "truncated HTTP/1 message"]); - let source = std::error::Error::source(&error).unwrap(); - assert!(matches!( - source.downcast_ref::(), - Some(Error::Protocol(_)) - )); + assert_eq!(chain(&error), ["truncated HTTP/1 message"]); + assert!(matches!(error, Error::Protocol(_)), "{error:?}"); client.begin_close(); }); peer.join().unwrap(); diff --git a/crates/client/tests/client/connection.rs b/crates/client/tests/client/connection.rs index 92ce485b..029078bb 100644 --- a/crates/client/tests/client/connection.rs +++ b/crates/client/tests/client/connection.rs @@ -2,10 +2,10 @@ // Copyright, 2026, by Samuel Williams. //! Connection construction, cleanup and exchange failures, using a scheduler with injected faults where the real one cannot fail on demand. -use super::{Stalled, accept, chain, head, peer, remainder, run_endpoint}; +use super::{Stalled, accept, chain, drive_until, head, peer, remainder, run_endpoint}; use base_http::{ Method, Request, - body::{BodyFrame, EmptyBody, ReadableBody}, + body::{BodyFrame, BufferedBody, EmptyBody, ReadableBody}, }; use base_http_client::{Client, Endpoint, Error, Options}; use base_scheduler::{ @@ -32,6 +32,16 @@ use std::{ time::Duration, }; +/// The client closed this connection without sending anything more. Closing +/// with unread response bytes resets the connection instead of ending it. +fn closed_unused(stream: &mut impl std::io::Read) { + let mut rest = Vec::new(); + match stream.read_to_end(&mut rest) { + Ok(_) => assert!(rest.is_empty(), "{rest:?}"), + Err(error) => assert_eq!(error.kind(), io::ErrorKind::ConnectionReset), + } +} + fn respond_no_content(listener: &TcpListener) { let mut stream = accept(listener); assert!(head(&mut stream).starts_with("GET /next HTTP/1.1\r\n")); @@ -143,7 +153,6 @@ struct Plan { // Pause the next connect until released, before or after the TCP handshake. connect: Mutex>, // Block the polling thread after the next nonempty read until another thread proceeds. - read: Mutex, mpsc::Receiver<()>)>>, } impl Plan { fn gate(&self, after: bool) -> (oneshot::Receiver<()>, oneshot::Sender<()>) { @@ -156,12 +165,6 @@ impl Plan { }); (reached_wait, release) } - fn pause_read(&self) -> (mpsc::Receiver<()>, mpsc::Sender<()>) { - let (reached, reached_wait) = mpsc::channel(); - let (proceed, proceed_wait) = mpsc::channel(); - *self.read.lock().unwrap() = Some((reached, proceed_wait)); - (reached_wait, proceed) - } } struct Faults<'a> { inner: &'a NativeScheduler, @@ -343,16 +346,7 @@ impl SocketStreamReader for FaultReader { buffer: &mut [u8], cancellation: &Cancellation, ) -> OperationResult { - let length = self.inner.read_into(buffer, cancellation).await?; - if length > 0 { - let pause = self.plan.read.lock().unwrap().take(); - if let Some((reached, proceed)) = pause { - // Hold this poll after data arrived but before the codec observes it. - reached.send(()).unwrap(); - proceed.recv().unwrap(); - } - } - Ok(length) + self.inner.read_into(buffer, cancellation).await } fn try_read_into(&mut self, buffer: &mut [u8]) -> io::Result { self.inner.try_read_into(buffer) @@ -595,8 +589,12 @@ fn driver_cancellation_during_tcp_connect_waits_for_construction_to_stop() { } #[test] -fn driver_shutdown_during_establishment_retires_a_late_connection() { - // A clean close of the late connection is not a driver failure; its close errors still are. +fn driver_shutdown_during_establishment_closes_the_late_connection() { + // Shutdown cancels construction, which closes both directions even when + // one fails; a close failure during cancelled construction reports the + // cancellation, so the driver does not fail. Failures closing a connection + // retired after establishment are reported by + // `cleanup_failures_are_reported_by_the_driver_after_closing_everything`. for fault in [None, Some("reader close"), Some("writer close")] { let (address, peer) = peer(|listener| { assert!(remainder(&mut accept(&listener)).is_empty()); @@ -625,19 +623,13 @@ fn driver_shutdown_during_establishment_retires_a_late_connection() { let mut call = pin!(client.call(Request::new(Method::GET, "/", EmptyBody), &never)); assert!(poll_once(call.as_mut()).await.is_none()); reached.await.unwrap(); - // Construction resumes in the same supervisor poll that closes the pool, before the waiting call observes shutdown. release.send(()).unwrap(); lifetime.cancel(); + // Cancelling the driver's lifetime cancels the waiting call. let error = call.await.err().unwrap(); - assert!(matches!(error, Error::Closed), "{error:?}"); + assert!(matches!(error, Error::Cancelled), "{error:?}"); }); - match fault { - Some(fault) => { - let error = result.unwrap_err(); - assert_eq!(chain(&error)[1], format!("injected {fault} failure")); - } - None => result.unwrap(), - } + result.unwrap(); // Both directions are closed even when one fails. assert_eq!(plan.reader_closes.load(Ordering::SeqCst), 1); assert_eq!(plan.writer_closes.load(Ordering::SeqCst), 1); @@ -755,6 +747,36 @@ fn request_body_failure_before_a_response_fails_the_call_with_that_error() { peer.join().unwrap(); } +#[test] +fn a_failed_upload_write_fails_the_call_and_retires_the_connection() { + let (address, peer) = peer(|listener| { + let mut stream = accept(&listener); + head(&mut stream); + // Closing with the upload unread resets the connection, so the + // client's later writes fail. + drop(stream); + respond_no_content(&listener); + }); + run_endpoint(Endpoint::new(address), Options::default(), async |client| { + let upload = BufferedBody::from(vec![b'u'; 64 * 1024 * 1024]); + let error = client + .call( + Request::new(Method::POST, "/", upload), + &Cancellation::never(), + ) + .await + .err() + .unwrap(); + assert!( + matches!(error, Error::Io(_) | Error::Protocol(_)), + "{error:?}" + ); + next_call(&client).await; + client.begin_close(); + }); + peer.join().unwrap(); +} + #[test] fn cancelling_during_upload_and_response_wait_retires_the_connection() { let (sent, request) = oneshot::channel(); @@ -768,8 +790,7 @@ fn cancelling_during_upload_and_response_wait_retires_the_connection() { run_endpoint(Endpoint::new(address), Options::default(), async |client| { let cancel = Cancellation::new(); let mut call = pin!(client.call(Request::new(Method::POST, "/", Stalled), &cancel)); - assert!(poll_once(call.as_mut()).await.is_none()); - request.await.unwrap(); + drive_until(&mut call, request).await.unwrap(); cancel.cancel(); assert!(matches!(call.await, Err(Error::Cancelled))); next_call(&client).await; @@ -829,7 +850,7 @@ fn truncated_response_body_reports_an_error_to_its_reader() { Err(error) => break error, } }; - assert_eq!(chain(&error), ["body failed", "truncated HTTP/1 message"]); + assert_eq!(chain(&error), ["truncated HTTP/1 message"]); drop(response); next_call(&client).await; client.begin_close(); @@ -837,57 +858,42 @@ fn truncated_response_body_reports_an_error_to_its_reader() { peer.join().unwrap(); } -// Run the driver on another thread, so the application can act while a driver poll is held inside a read. -fn drive_threaded( - faults: &Faults<'_>, - address: SocketAddr, - application: impl for<'scope> FnOnce(&Client<'scope>), -) { - let (client, driver) = Client::new(faults, Endpoint::new(address), Options::default()).unwrap(); - let lifetime = Cancellation::new(); - thread::scope(|scope| { - let driving = scope.spawn(|| block_on(driver.run(&lifetime))); - application(&client); - client.begin_close(); - driving.join().unwrap().unwrap(); - }); - assert_eq!(client.pool_stats().total(), 0); -} - #[test] fn call_dropped_as_its_response_arrives_retires_the_connection() { - let (address, peer) = peer(|listener| { + let (received, request) = oneshot::channel(); + let (respond, go) = mpsc::channel::<()>(); + let (responded, arrived) = oneshot::channel(); + let (address, peer) = peer(move |listener| { let mut stream = accept(&listener); head(&mut stream); + received.send(()).unwrap(); + go.recv().unwrap(); stream .get_mut() .write_all(b"HTTP/1.1 200 OK\r\nContent-Length: 5\r\n\r\nhello") .unwrap(); - assert!(remainder(&mut stream).is_empty()); + responded.send(()).unwrap(); + closed_unused(&mut stream); respond_no_content(&listener); }); - let scheduler = NativeScheduler::new().unwrap(); - let faults = Faults::new(&scheduler); - let (reached, proceed) = faults.plan.pause_read(); - drive_threaded(&faults, address, |client| { - block_on(async { - let never = Cancellation::never(); - let mut call = Box::pin(client.call(Request::new(Method::GET, "/", EmptyBody), &never)); - assert!(poll_once(call.as_mut()).await.is_none()); - // The driver holds the response head; abandon the call before it is delivered. - reached.recv().unwrap(); - drop(call); - proceed.send(()).unwrap(); - next_call(client).await; - }); + run_endpoint(Endpoint::new(address), Options::default(), async |client| { + let never = Cancellation::never(); + let mut call = Box::pin(client.call(Request::new(Method::GET, "/", EmptyBody), &never)); + drive_until(&mut call, request).await.unwrap(); + // The response arrives while the call is not polled; abandon it unread. + respond.send(()).unwrap(); + arrived.await.unwrap(); + drop(call); + next_call(&client).await; + client.begin_close(); }); peer.join().unwrap(); - block_on(scheduler.shutdown()); } #[test] fn response_dropped_while_its_body_arrives_retires_the_connection() { let (send_body, body_requested) = mpsc::channel::<()>(); + let (sent_body, body_sent) = oneshot::channel(); let (address, peer) = peer(move |listener| { let mut stream = accept(&listener); head(&mut stream); @@ -897,32 +903,26 @@ fn response_dropped_while_its_body_arrives_retires_the_connection() { .unwrap(); body_requested.recv().unwrap(); stream.get_mut().write_all(b"hello").unwrap(); - assert!(remainder(&mut stream).is_empty()); + sent_body.send(()).unwrap(); + closed_unused(&mut stream); respond_no_content(&listener); }); - let scheduler = NativeScheduler::new().unwrap(); - let faults = Faults::new(&scheduler); - let plan = faults.plan.clone(); - drive_threaded(&faults, address, |client| { - block_on(async { - let response = client - .call( - Request::new(Method::GET, "/", EmptyBody), - &Cancellation::never(), - ) - .await - .unwrap(); - let (reached, proceed) = plan.pause_read(); - send_body.send(()).unwrap(); - // The driver holds body bytes; abandon the response before they are forwarded. - reached.recv().unwrap(); - drop(response); - proceed.send(()).unwrap(); - next_call(client).await; - }); + run_endpoint(Endpoint::new(address), Options::default(), async |client| { + let response = client + .call( + Request::new(Method::GET, "/", EmptyBody), + &Cancellation::never(), + ) + .await + .unwrap(); + send_body.send(()).unwrap(); + // The body is on its way; abandon the response before reading it. + body_sent.await.unwrap(); + drop(response); + next_call(&client).await; + client.begin_close(); }); peer.join().unwrap(); - block_on(scheduler.shutdown()); } #[cfg(feature = "rustls")] diff --git a/crates/client/tests/client/main.rs b/crates/client/tests/client/main.rs index 55347b6f..9b9859d1 100644 --- a/crates/client/tests/client/main.rs +++ b/crates/client/tests/client/main.rs @@ -23,7 +23,7 @@ use std::{ thread, time::Duration, }; -use support::{chain, head, payload, peer, remainder, run_endpoint, unconnected}; +use support::{chain, drive_until, head, payload, peer, remainder, run_endpoint, unconnected}; fn accept(listener: &TcpListener) -> BufReader { listener.set_nonblocking(true).unwrap(); @@ -185,6 +185,10 @@ fn response_finishes_before_upload_and_use_remains_charged() { .await .unwrap(); producer.close_write(None); + // The driver finishes the upload, which then releases the use. + while client.pool_stats().uses != 0 { + futures_lite::future::yield_now().await; + } let mut response = client .call( Request::new(Method::GET, "/next", EmptyBody), @@ -260,17 +264,19 @@ fn interim_responses_and_trailers_preserve_order() { run(&scheduler, address, Options::default(), async |client| { let observed = std::sync::Arc::new(std::sync::Mutex::new(Vec::new())); let observer = observed.clone(); - let mut response = client - .call_with_interim( - Request::new(Method::GET, "/", EmptyBody), - move |metadata: base_http::ResponseMetadata| { - observer.lock().unwrap().push(metadata.status); - async { Ok::<_, std::convert::Infallible>(()) } - }, - &Cancellation::never(), - ) - .await - .unwrap(); + let mut context = + base_http::ClientContext::new(move |metadata: base_http::ResponseMetadata| { + observer.lock().unwrap().push(metadata.status); + async { Ok::<_, std::convert::Infallible>(()) } + }); + let mut response = base_http::Handler::call( + &client, + Request::new(Method::GET, "/", EmptyBody), + &mut context, + &Cancellation::never(), + ) + .await + .unwrap(); assert_eq!( observed.lock().unwrap().as_slice(), &[base_http::Status::CONTINUE, base_http::Status::EARLY_HINTS] @@ -307,9 +313,11 @@ fn interim_responses_and_trailers_preserve_order() { #[test] fn cancelling_a_waiting_call_disconnects_and_allows_replacement() { + let (sent, request) = futures_channel::oneshot::channel(); let (address, peer) = peer(|listener| { let mut stream = accept(&listener); head(&mut stream); + sent.send(()).unwrap(); let mut eof = [0]; assert_eq!(stream.read(&mut eof).unwrap(), 0); let mut next = accept(&listener); @@ -320,19 +328,11 @@ fn cancelling_a_waiting_call_disconnects_and_allows_replacement() { }); let scheduler = NativeScheduler::new().unwrap(); run(&scheduler, address, Options::default(), async |client| { - // Keep the call pending while the driver establishes its connection. + // The call sends its request, then waits for the response. let cancelled = Cancellation::new(); let work = client.call(Request::new(Method::GET, "/waiting", EmptyBody), &cancelled); let mut work = std::pin::pin!(work); - assert!( - futures_lite::future::poll_once(work.as_mut()) - .await - .is_none() - ); - // Let the driver establish the connection before cancellation. - while client.pool_stats().uses == 0 { - futures_lite::future::yield_now().await; - } + drive_until(&mut work, request).await.unwrap(); cancelled.cancel(); assert!(matches!( work.await, @@ -489,11 +489,7 @@ fn upload_keeps_progressing_while_response_queue_is_full() { sending.join().unwrap(); }); let scheduler = NativeScheduler::new().unwrap(); - let options = Options { - response_buffer_frames: 1, - ..Options::default() - }; - run(&scheduler, address, options, async |client| { + run(&scheduler, address, Options::default(), async |client| { let (body, mut producer) = base_http::body::BodyReader::bounded(16 * 1024, 1); let mut response = client .call( @@ -633,12 +629,7 @@ fn dropped_call_retires_an_exchange_waiting_for_final_metadata() { let never = Cancellation::never(); let mut call = Box::pin(client.call(Request::new(Method::GET, "/dropped", EmptyBody), &never)); - assert!( - futures_lite::future::poll_once(call.as_mut()) - .await - .is_none() - ); - started.await.unwrap(); + drive_until(&mut call, started).await.unwrap(); drop(call); let mut response = client .call(Request::new(Method::GET, "/replacement", EmptyBody), &never) diff --git a/crates/client/tests/client/options.rs b/crates/client/tests/client/options.rs index da2b77c6..6bb394af 100644 --- a/crates/client/tests/client/options.rs +++ b/crates/client/tests/client/options.rs @@ -38,21 +38,10 @@ fn invalid_limits_are_reported_by_the_layer_that_owns_them() { ["invalid HTTP/1 message: invalid HTTP/1 limits"] ); let defaults = Options::default(); - let client = [ - Options { - max_requests: 0, - ..defaults.clone() - }, - Options { - response_buffer_frames: 0, - ..defaults.clone() - }, - // The response buffer must hold a complete head. - Options { - response_buffer_bytes: defaults.http1.max_head_bytes - 1, - ..defaults.clone() - }, - ]; + let client = [Options { + max_requests: 0, + ..defaults.clone() + }]; for options in client { assert!(matches!(options.validate(), Err(Error::InvalidOptions))); } diff --git a/crates/client/tests/https.rs b/crates/client/tests/https.rs index 2a94140b..33b19a73 100644 --- a/crates/client/tests/https.rs +++ b/crates/client/tests/https.rs @@ -282,12 +282,8 @@ fn https_upload_progresses_while_response_consumption_is_paused() { scheduler .timeout(Duration::from_secs(15), async { let endpoint = Endpoint::new(address).with_tls(client_config, "localhost"); - let options = Options { - response_buffer_bytes: 32768, - response_buffer_frames: 1, - ..Options::default() - }; - let (client, driver) = Client::new(&scheduler, endpoint, options).unwrap(); + let (client, driver) = + Client::new(&scheduler, endpoint, Options::default()).unwrap(); let application = async { let request = Request::new( Method::POST, diff --git a/crates/client/tests/support/mod.rs b/crates/client/tests/support/mod.rs index 74d18da3..f66d3cb2 100644 --- a/crates/client/tests/support/mod.rs +++ b/crates/client/tests/support/mod.rs @@ -46,6 +46,24 @@ pub fn remainder(stream: &mut impl Read) -> Vec { pub use base_http_fixtures::{body::payload, error_chain as chain}; +/// Keep polling `work`, such as a call, which makes progress only while it is +/// polled, until `point` is reached, such as the peer receiving its request. +/// Panics if `work` finishes first. +#[allow(dead_code)] // The writable suite does not use it. +pub async fn drive_until(work: &mut W, point: impl std::future::Future) -> T +where + W: std::future::Future + Unpin, +{ + let mut point = std::pin::pin!(point); + std::future::poll_fn(|cx| { + if std::pin::Pin::new(&mut *work).poll(cx).is_ready() { + panic!("the work finished before the point was reached"); + } + point.as_mut().poll(cx) + }) + .await +} + /// Run a client with a single pooled connection beside its driver, then require that every connection was retired. pub fn run_endpoint( endpoint: Endpoint, diff --git a/crates/fixtures/src/protocol.rs b/crates/fixtures/src/protocol.rs index 81ca4461..d0248bb2 100644 --- a/crates/fixtures/src/protocol.rs +++ b/crates/fixtures/src/protocol.rs @@ -6,7 +6,7 @@ //! One application, [`App`], serves every case on its own route, so a runner only chooses how to serve and connect: the HTTP version, options and transport. Each case is a standalone `pub async fn` taking the running [`Context`], so a partial implementation can call a subset. The cases address the application through `H: Borrow`, so a test can wrap it to change its behaviour. use crate::{Context, Latch, Scheduler, body}; use base_http::{ - Fields, Method, Request, Response, ResponseMetadata, Status, Version, + ClientContext, Fields, Method, Request, Response, ResponseMetadata, Status, Version, body::{BodyError, BodyFrame, BodyReader, BufferedBody, ReadableBody}, }; use base_http_server::{Handler, HandlerContext, ServerContext}; @@ -559,19 +559,20 @@ pub async fn request_length>(context: &Context<'_, pub async fn interim_response>(context: &Context<'_, S, H>) { let observed = Arc::new(Mutex::new(Vec::new())); let observer = observed.clone(); - let mut response = context - .client() - .call_with_interim( - context.request(Method::GET, "/interim", BufferedBody::>::default()), - move |metadata: ResponseMetadata| { - let link = metadata.fields.values("link").next().map(<[u8]>::to_vec); - observer.lock().unwrap().push((metadata.status, link)); - async { Ok::<_, Infallible>(()) } - }, - &never(), - ) - .await - .expect("GET /interim"); + let mut client_context = ClientContext::new(move |metadata: ResponseMetadata| { + let link = metadata.fields.values("link").next().map(<[u8]>::to_vec); + observer.lock().unwrap().push((metadata.status, link)); + async { Ok::<_, Infallible>(()) } + }); + // The client implements the shared request interface for a client context. + let mut response = Handler::call( + context.client(), + context.request(Method::GET, "/interim", BufferedBody::>::default()), + &mut client_context, + &never(), + ) + .await + .expect("GET /interim"); assert_eq!(response.status, Status::OK); assert_eq!(body::payload(&mut response.body).await, b"Hello World"); let expected = match context.version() { @@ -654,10 +655,7 @@ pub async fn incorrect_length>(context: &Context<'_ .find(|(known, _)| *known == scheme) .expect("a known scheme"); let cause = chain.last().expect("an error message").contains(expected); - assert!( - chain[0] == "body failed" && cause, - "unexpected failure: {chain:?}" - ); + assert!(cause, "unexpected failure: {chain:?}"); } /// A request trailer sent after the server has received the request head reaches the handler over HTTP/1.1. HTTP/1.0 cannot frame trailers, so the client sends the data with its length and the handler receives no trailer. diff --git a/crates/fixtures/tests/context.rs b/crates/fixtures/tests/context.rs index 3113df15..ed8b115f 100644 --- a/crates/fixtures/tests/context.rs +++ b/crates/fixtures/tests/context.rs @@ -2,13 +2,16 @@ // Copyright, 2026, by Samuel Williams. //! A server context serves, connects, bounds and tears down a test, and reports each way it can fail. -use base_http::{Method, Status, body::EmptyBody}; +use base_http::{ + Method, Status, + body::{BodyFrame, EmptyBody, ReadableBody}, +}; use base_http_fixtures::{ ClientFixture, Hello, Latch, RawServer, ServerFixture, TEARDOWN_TIMEOUT, TEST_TIMEOUT, body::payload, native, }; use base_scheduler::Cancellation; -use std::time::Duration; +use std::{convert::Infallible, time::Duration}; #[test] fn the_default_context_serves_hello_to_its_client_and_a_raw_peer() { @@ -62,21 +65,35 @@ fn a_test_exceeding_its_timeout_fails() { }); } -// A test which returns an unfinished response body keeps its connection busy, so teardown cannot complete. +/// A request body that never produces a frame. +struct Stalled; +impl ReadableBody for Stalled { + type Data = Vec; + type Error = Infallible; + async fn read(&mut self, _: &Cancellation) -> Result>, Infallible> { + std::future::pending().await + } + fn close(&mut self, _: Option) {} +} + +// The server answers in full without reading the request body, so after the +// test reads the whole response the client's driver still waits to upload a +// body that never yields, and only a forced teardown stops it. #[test] #[should_panic(expected = "teardown exceeded")] fn a_teardown_exceeding_its_timeout_is_forced_and_fails() { ServerFixture::new() .teardown_timeout(Duration::from_millis(50)) .run(async |context| { - context + let mut response = context .client() .call( - context.request(Method::GET, "/", EmptyBody), + context.request(Method::POST, "/", Stalled), &Cancellation::never(), ) .await - .unwrap() + .unwrap(); + assert_eq!(payload(&mut response.body).await, b"Hello World!"); }); } diff --git a/crates/fixtures/tests/raw.rs b/crates/fixtures/tests/raw.rs index fa263b9e..42bfb332 100644 --- a/crates/fixtures/tests/raw.rs +++ b/crates/fixtures/tests/raw.rs @@ -122,10 +122,7 @@ fn a_truncated_body_fails_the_client_read() { let error = body::collect(&mut response.body, &Cancellation::never()) .await .unwrap_err(); - assert_eq!( - error_chain(&error), - ["body failed", "truncated HTTP/1 message"] - ); + assert_eq!(error_chain(&error), ["truncated HTTP/1 message"]); }); server.join(); } diff --git a/design/client-connection.md b/design/client-connection.md index 4e70f2a9..c1fc72b6 100644 --- a/design/client-connection.md +++ b/design/client-connection.md @@ -103,7 +103,7 @@ This first managed client rejects CONNECT and Upgrade before dialing. Bodies mus ## Writable HTTP/1 experiment and task placement -The HTTP/1 client now also provides `open` / `open_request` returning an active `WritableRequest`, alongside the existing semantic pull-body `call`. `open` acquires pool admission in the caller and hands connection-bound encoder/decoder directions to the application. `write` directly drives output; `finish` completes output and reads response metadata. `split` separates the request writer from the pending response so applications can poll upload and download independently. Response bodies decode on read, without an HTTP frame queue. The connection retains its transport directions and reusable codec buffers. Short locks transfer those directions to/from direct request handles; normal completion returns them synchronously and releases admission without waiting on the supervisor. Pool and client-accounting notifications can still wake lifecycle work. Established plaintext requests require no driver polls or worker handoff; construction, queued calls, deferred synchronous closure and retirement remain supervised. Encrypted reads, writes and flushes directly poll retained I/O futures below those codecs, with stable wake routing for application and supervised pollers. The input future returns available authenticated plaintext before reading more ciphertext; control output and directional retirement remain supervised. Neither a per-write producer queue nor a per-write future allocation is required. +The HTTP/1 client now also provides `open` / `open_request` returning an active `WritableRequest`, alongside the semantic pull-body `call`, which since 2026-11-21 runs on the same direct path, writing its body from the calling future until the response head. `open` acquires pool admission in the caller and hands connection-bound encoder/decoder directions to the application. `write` directly drives output; `finish` completes output and reads response metadata. `split` separates the request writer from the pending response so applications can poll upload and download independently. Response bodies decode on read, without an HTTP frame queue. The connection retains its transport directions and reusable codec buffers. Short locks transfer those directions to/from direct request handles; normal completion returns them synchronously and releases admission without waiting on the supervisor. Pool and client-accounting notifications can still wake lifecycle work. Established plaintext requests require no driver polls or worker handoff; construction, queued calls, deferred synchronous closure and retirement remain supervised. Encrypted reads, writes and flushes directly poll retained I/O futures below those codecs, with stable wake routing for application and supervised pollers. The input future returns available authenticated plaintext before reading more ciphertext; control output and directional retirement remain supervised. Neither a per-write producer queue nor a per-write future allocation is required. The [client example](../crates/client/examples/client_server.rs) demonstrates buffered, sequential writable and split duplex requests. [Writable integration tests](../crates/client/tests/writable/main.rs) exercise independent peers, interim responses, trailers, fixed-length failures, cancellation, abandonment, pool waiters, and large HTTP/TLS 1.2/1.3 duplex echo. [Three-party proxy tests](../crates/client/tests/proxy.rs) also forward transient borrowed downstream input through direct upstream handles under response backpressure and early response completion. Proxy forwarding must drive both directions by default. Existing `call` still uses its queued implementation; this experiment does not claim a performance result or implement HTTP/2. diff --git a/design/implementation.md b/design/implementation.md index fd0050a8..358a7ed8 100644 --- a/design/implementation.md +++ b/design/implementation.md @@ -111,17 +111,17 @@ The release allocation probe still reports 2 allocations and 15 allocated bytes ## Pooled client implementation -`base-http-client::Client::new` returns a cloneable endpoint handle and an explicit `Driver`. The scheduler constructs I/O capabilities; polling the driver supervises dialing, queued call assignments/upload/download, TLS progress and cleanup. No task is detached. A connection holds its socket and concrete reader/writer codecs together under the corrected scheduler factory contract. Direct HTTP/1 `open`/write/read takes the retained codecs in the calling task and returns them synchronously before releasing pool admission. There is no per-request driver submission or codec-recovery channel on that path. A regression establishes one plaintext connection, stops polling the driver, and completes four further requests on it. Queued `call`, TLS control output, synchronous deferred `close_write` and asynchronous retirement still require supervised progress. TLS reads, writes and flushes now directly poll retained I/O futures; input processes incoming control records as it reads. +`base-http-client::Client::new` returns a cloneable endpoint handle and an explicit `Driver`. The scheduler constructs I/O capabilities; polling the driver supervises dialing, uploads that outlive their `call`, TLS progress and cleanup. No task is detached. A connection holds its socket and concrete reader/writer codecs together under the corrected scheduler factory contract. Direct HTTP/1 `open`/write/read takes the retained codecs in the calling task and returns them synchronously before releasing pool admission. There is no per-request driver submission or codec-recovery channel on that path. A regression establishes one plaintext connection, stops polling the driver, and completes four further requests on it. Deferred uploads, TLS control output, synchronous deferred `close_write` and asynchronous retirement still require supervised progress. TLS reads, writes and flushes now directly poll retained I/O futures; input processes incoming control records as it reads. Each connection publishes `Admission::concurrent(1)` through `base-pool::MultiplexPool`. The active use remains charged until upload completes and the application consumes the response's final frame. Network read-ahead alone does not release admission. Abandoning a partial response cancels the exchange and retires HTTP/1 without draining unread bytes; retirement capacity remains charged through lane cleanup and socket closure. Graceful closure finishes accepted calls; driver lifetime cancellation terminates them and joins cleanup. Driver drop is synchronous abandonment, without an async join. An idle connection is probed before reuse, following the [Async::HTTP viability probe](https://github.com/socketry/async-http/commit/3c8bec5246063c6a833c99af992827cac8959737). After activating an existing use of a connection that has completed an exchange, and before any request bytes are written, `Context::acquire` calls `Connection::probe`, which takes the connection's codecs and calls `ResponseReader::probe_viable`. The probe requires reusable input with no read-ahead, then attempts one immediate read into the input buffer with `ReadableStream::try_read_into`, which reaches the transport rather than any readiness the scheduler has cached; `WouldBlock` means the connection is idle. Data, EOF or an error, including a TLS close notification or truncation, means the peer sent or closed outside an exchange: the probe poisons the input, the registration is retired, the use completes, and acquisition continues with another or a new connection. This serves direct `open` and queued `call` alike. A connection that has not yet completed an exchange is not read, as in Async::Pool, which returns newly created resources without a viability check: otherwise a peer that writes or closes on accept would have each replacement retired, without bound. Each failed probe therefore retires a previously used connection, bounding the loop by the pool size. The immediate read leaves no pending operation behind, and the TLS reader processes control records such as key updates and session tickets without yielding plaintext, so those connections remain usable. The probe performs I/O outside the codec lock and adds no task, timer, waker or idle registration. Every backend attempts the receive, so detection does not depend on readiness the scheduler has or has not yet observed, but only on what the operating system has received: a close still in flight on loopback or the network reads as idle. The tests run on the Native scheduler. The cost is one nonblocking receive per reused exchange, which has not been measured against the [storage reuse baseline](../benchmarks/client/exchange-reuse-20261029.md). It narrows, but cannot close, the window in which the server closes a connection the client is about to use: a close the transport has not yet observed, or one arriving during the exchange, still fails that exchange, and requests are not replayed. Dead idle connections also remain until their next acquisition or retirement; an idle-timeout maintenance future would release them earlier. -One boxed producer stream per call accepts heterogeneous bodies, with dynamic polling per frame and no boxed future allocation per body read. Vectors move; borrowed slices are copied into queued vectors. Transport dispatch remains static. Request bodies and interim observers may borrow for the driver's scope, which permits borrowed application data but does not yet accept shorter-lived server input through a long-lived client. This boundary is an explicit client ownership decision, not a consequence of a temporary socket borrow. +Since 2026-11-21, `call` runs on the direct path, as [middleware](middleware.md#shared-request-interface) records: it opens the request with the body's known length, writes the body from the calling future while waiting for the response head, and returns the direct path's `StreamingResponseBody`. An upload unfinished at the head moves to the driver as one boxed work item; a read of the request body waiting there stops when the exchange is cancelled, such as by dropping the response unfinished. Chunks are converted with `Chunk::into_vec`, so vectors move and borrowed slices are copied. The buffered `call`, its driver queue of operations, its boxed producer stream and `ResponseBody` are removed, with `Options::response_buffer_bytes` and `response_buffer_frames`. `Client` implements `Handler<'scope, ClientContext>`: interim responses reach the exchange's observer for the client's scope, so a context call hands them through an `InterimRelay` to the context's borrowed observer while waiting for the head. Request bodies may borrow for the driver's scope, and a server's request bodies, which outlive their handler, can be forwarded through a client in the same scope. Waiting calls report `Closed` when the driver is dropped and `Cancelled` when its lifetime is cancelled; connection construction inherits the waiting call's cancellation, so a driver shutdown cancels construction in progress rather than retiring a late connection. TCP integration tests cover borrowed POST then GET reuse, early final response with delayed upload, full response-queue backpressure with independent 1 MiB upload, interim responses and trailers, partial-response abandonment and replacement, call cancellation/drop, cancelled pool waiters, construction-failure cleanup, known-empty response reuse, request limits, rejected-body closure, uncooperative upload shutdown and driver abandonment. Idle-probe tests close, or send unsolicited bytes on, an idle plaintext connection and require both `call` and `open` to succeed on a fresh one, and a server that responds and closes on accept is used through one connection; an HTTPS test does the same for a close notification and an abrupt close, and requires a key update to keep the connection. The single-file pooled client/server example uses the actual application server and sends two echoed POSTs over one session. Managed CONNECT/upgrades, DNS integration, retries and additional protocols remain outside this first path. -The registry-backed dependency graph uses `base-scheduler 0.5.0`, `base-pool 0.5.0` and `base-endpoint 0.3.0`, without local overrides, and `cargo tree -d` finds one version of each Base crate in the workspace and in each benchmark. CI runs `cargo test --locked --workspace --all-features` with them on Linux, with the current stable Rust and with Rust 1.87. The workspace previously used `base-scheduler 0.4.0`, `base-pool 0.4.0` and `base-endpoint 0.2.0`. With the earlier `base-scheduler 0.3.0`, `base-pool 0.3.0` and `base-endpoint 0.1.0`, the workspace tests passed on macOS with Rust 1.87 and on Linux (hana) with Rust 1.99.1, and the pooled client/server example ran on Linux. With the earlier 0.2.0 releases, Rust 1.87 passed 63 semantic, 55 codec, 27 server/proxy and 13 client integration tests on macOS. The 13 client tests and pooled client/server example also passed on Linux via `aiko.local`. +The registry-backed dependency graph uses `base-scheduler 0.5.0`, `base-pool 0.5.0` and `base-endpoint 0.3.0`, without local overrides, and `cargo tree -d` finds one version of each Base crate in the workspace and in each benchmark. CI runs `cargo test --locked --workspace --all-features` with them on Linux, with the current stable Rust and with Rust 1.92, the declared minimum since 2026-11-21. The workspace previously used `base-scheduler 0.4.0`, `base-pool 0.4.0` and `base-endpoint 0.2.0`. With the earlier `base-scheduler 0.3.0`, `base-pool 0.3.0` and `base-endpoint 0.1.0`, the workspace tests passed on macOS with Rust 1.87 and on Linux (hana) with Rust 1.99.1, and the pooled client/server example ran on Linux. With the earlier 0.2.0 releases, Rust 1.87 passed 63 semantic, 55 codec, 27 server/proxy and 13 client integration tests on macOS. The 13 client tests and pooled client/server example also passed on Linux via `aiko.local`. ## HTTP/1 HTTPS integration diff --git a/design/middleware.md b/design/middleware.md index 966f241d..c43090f3 100644 --- a/design/middleware.md +++ b/design/middleware.md @@ -36,7 +36,20 @@ A spike on 2026-11-20 and 2026-11-21, kept on the local branch `client-handler-b Owning a body costs nothing measurable. The 11 further allocations per request are in the client's existing `call`, which queues each request to the driver and buffers the response. The spike's replacement removes them: a handler calling it through the server measured 7.04 allocations and 2,600 bytes per request, and 38.8 ms against the first row's 39.8 ms in the same seven runs. It opens the request on the direct path and writes the body from the calling future until the response head arrives; only an upload unfinished by then moves to the client's driver, at one allocation. It returns the direct path's streaming response body, which borrows the client's scope and which the caller's reads drive, rather than the buffered one. It does not yet relay interim responses, which M6 adds. -The user decided on 2026-11-21 that the client keeps one such call: `call` takes this design and replaces the buffered one, so the client implements the interface without a response copy or a queue per request, and its response body streams from the connection as Async::HTTP's does. A caller that wants the response read ahead of its own reads wraps the body in a buffering body. `open_request` stays, for a caller writing a request body itself rather than passing one. Before the buffered `call` is removed, M6 relays interim responses through the new one and checks that no test or example depends on the buffered response. Per-exchange data added later goes into the relevant context, without changing the interface's signature. +The user decided on 2026-11-21 that the client keeps one such call: `call` takes this design and replaces the buffered one, so the client implements the interface without a response copy or a queue per request, and its response body streams from the connection as Async::HTTP's does. A caller that wants the response read ahead of its own reads wraps the body in a buffering body. `open_request` stays, for a caller writing a request body itself rather than passing one. Before the buffered `call` is removed, M6 relays interim responses through the new one and checks that no test or example depends on the buffered response. + +Implemented on 2026-11-21. The client benchmark, over plain HTTP on hana with three 3-second samples per case and allocation counting, measured the new `call` (`base-call`) at the direct writer's (`base-open`) cost: + +| Path | In flight | Requests per second | Client CPU per request | Allocations per request | Bytes allocated per request | +| --- | --- | --- | --- | --- | --- | +| Buffered `call`, before | 1 | 127,168 | 5.41 µs | 18.00 | 5,577 | +| Direct-path `call` | 1 | 157,439 | 3.82 µs | 7.00 | 593 | +| `open` | 1 | 155,591 | 3.92 µs | 7.00 | 593 | +| Buffered `call`, before | 32 | 225,170 | 3.90 µs | 17.06 | 5,112 | +| Direct-path `call` | 32 | 290,643 | 2.78 µs | 7.00 | 600 | +| `open` | 32 | 303,567 | 2.70 µs | 7.00 | 600 | + +These requests have no body and pass no context. A call through `Handler` with a `ClientContext` also allocates its relay and the observer's box, and an upload unfinished at the response head one driver work item. Per-exchange data added later goes into the relevant context, without changing the interface's signature. A middleware is an implementation of the interface that holds a delegate implementing it, for the same context, and calls through to it, transforming the request on the way in and the response on the way out, or answering without calling its delegate. Middleware compose by wrapping, with static dispatch: a stack is a nested type, and no layer requires boxing, a `'static` bound or a task. Request and response bodies stay generic, so a layer passes bodies through without copying, and a returned body may borrow the request body, as the server's handler contract allows now. A middleware that only transforms requests and responses is generic over the context type, so the same layer wraps a server application or a client. A middleware that needs one side's data, such as the `Peer` or the client's request options, is written for that side's context, so placing it on the other side is a compile-time error. A small trait implemented by both contexts gives generic middleware access to the interim hook where it needs one. diff --git a/performance.md b/performance.md index 7fe5ea54..ec0b4273 100644 --- a/performance.md +++ b/performance.md @@ -23,9 +23,9 @@ The established client path has these layers: For imperative `Client::open_request`, acquisition is followed by direct connection use. The exchange independently owns request output and response input. Writes drive output; response body reads drive input. Both codec directions return before the active pool use completes. Receiving response metadata, or reaching response EOF, does not finish an active upload. -The explicit client driver handles establishment, queued calls, deferred closure and retirement, plus supervised connection/TLS work. Ordinary established direct requests require no per-request supervisor acknowledgment. Direct TLS reads/writes also make progress in application futures. Connection supervision is currently scoped under one client driver; this prototype does not establish independently scheduled multiworker connection drivers. +The explicit client driver handles establishment, uploads that outlive their `call`, deferred closure and retirement, plus supervised connection/TLS work. Ordinary established direct requests require no per-request supervisor acknowledgment. Direct TLS reads/writes also make progress in application futures. Connection supervision is currently scoped under one client driver; this prototype does not establish independently scheduled multiworker connection drivers. -The latest pooled benchmark measures the imperative **`base-open` path**. The queued pull-body **`base-call` path** is a separate implementation and is not included in the latest comparison. Erasure occurs at the client adapter boundary; transport operations remain statically dispatched. There is no body-data queue or new boxed future per frame on the direct path. +The latest pooled benchmark measures the imperative **`base-open` path**. The pull-body **`base-call` path** used a separate queued implementation until 2026-11-21 and is not included in the latest comparison; it now runs on the same direct path, writing its body from the calling future. Erasure occurs at the client adapter boundary; transport operations remain statically dispatched. There is no body-data queue or new boxed future per frame on the direct path. See [client/connection taxonomy](design/client-connection.md), [transport layering](design/transport.md), [duplex ownership](design/duplex.md) and the [client implementation notes](crates/client/readme.md).