From 04f6865be6dd957ef9545b187a39db1de593c66e Mon Sep 17 00:00:00 2001 From: Samuel Williams Date: Sat, 21 Nov 2026 11:25:18 +1300 Subject: [PATCH 1/4] Select version-neutral connections from an ordered engine list, and name the engine in protocol errors. --- benchmarks/hello/src/main.rs | 2 +- crates/client/src/connection.rs | 37 ++-- crates/client/src/error.rs | 14 +- crates/client/tests/client/options.rs | 30 ++++ crates/client/tests/https.rs | 6 +- crates/protocol/readme.md | 4 +- crates/protocol/src/lib.rs | 216 ++++++++++++++++++++---- crates/server/readme.md | 2 +- crates/server/src/lib.rs | 105 +++++++----- crates/server/tests/end_to_end.rs | 4 +- crates/server/tests/support/mod.rs | 5 +- crates/server/tests/tls.rs | 23 ++- crates/server/tests/transport_faults.rs | 50 +++++- design/http2.md | 2 + 14 files changed, 386 insertions(+), 114 deletions(-) diff --git a/benchmarks/hello/src/main.rs b/benchmarks/hello/src/main.rs index 095f149d..fdfba0f9 100644 --- a/benchmarks/hello/src/main.rs +++ b/benchmarks/hello/src/main.rs @@ -86,7 +86,7 @@ where ready(&listener)?; let listener = scheduler.register_listener(listener)?; let cancellation = Cancellation::never(); - let options = base_http1::Options::default(); + let options = base_http_server::Options::default(); let mut connections = FuturesUnordered::new(); loop { if connections.len() == MAX_CONNECTIONS { diff --git a/crates/client/src/connection.rs b/crates/client/src/connection.rs index 95b3e86d..2b40efe3 100644 --- a/crates/client/src/connection.rs +++ b/crates/client/src/connection.rs @@ -12,6 +12,7 @@ use base_endpoint::{ AddressEndpoint, ConnectEndpoint, stream::{ReadableStream, WritableStream}, }; +use base_http_protocol::ClientConnection; use base_http1::{RequestWriter, ResponseReader}; use base_pool::{Admission, MultiplexBuildPermit, MultiplexResource}; use base_scheduler::{ @@ -165,23 +166,29 @@ pub(crate) async fn run<'scope, S>( return transport .with_duplex(scheduler, &lifetime, |reader, writer| async { let protocol = options.protocols.negotiated(selected.as_deref())?; - let (input, output) = protocol + let connection = protocol .client(reader, writer, options.http1.clone()) .expect("Client::new validated the HTTP/1 options"); - session( - input, - output, - &mut owner, - &mut build, - &mut ready, - &cancellation, - &lifetime, - queue.clone(), - ) - .await + match connection { + ClientConnection::Http1(input, output) => { + session( + input, + output, + &mut owner, + &mut build, + &mut ready, + &cancellation, + &lifetime, + queue.clone(), + ) + .await + } + } }) .await; } + // A plain TCP connection negotiates nothing, so select its engine before connecting. + let protocol = options.protocols.plaintext()?; let socket = endpoint_transport .connect(scheduler, &cancellation) .await @@ -196,16 +203,14 @@ pub(crate) async fn run<'scope, S>( } }; Ok::<_, Error>( - options - .protocols - .plaintext() + protocol .client(reader, writer, options.http1.clone()) .expect("Client::new validated the HTTP/1 options"), ) } .await; let result = match initialized { - Ok((input, output)) => { + Ok(ClientConnection::Http1(input, output)) => { session( input, output, diff --git a/crates/client/src/error.rs b/crates/client/src/error.rs index 47eca60f..9de71d05 100644 --- a/crates/client/src/error.rs +++ b/crates/client/src/error.rs @@ -21,7 +21,8 @@ pub enum Error { InvalidOptions, Unsupported(&'static str), Pool(base_pool::Error), - Protocol(Arc), + /// The connection's engine failed, such as on a malformed response. + Protocol(Arc), Io(Arc), Body(base_http::body::BodyError), } @@ -91,6 +92,11 @@ impl From for Error { } } } +impl Error { + fn protocol(error: base_http1::Error) -> Self { + Self::Protocol(Arc::new(error.into())) + } +} impl From for Error { fn from(error: base_http1::Error) -> Self { match error { @@ -101,12 +107,12 @@ impl From for Error { Err(error) => match error.downcast::>() { Ok(error) => match *error { base_http::InterimError::Handler(error) => error, - error => Self::Protocol(Arc::new(base_http1::Error::Body(Box::new(error)))), + error => Self::protocol(base_http1::Error::Body(Box::new(error))), }, - Err(error) => Self::Protocol(Arc::new(base_http1::Error::Body(error))), + Err(error) => Self::protocol(base_http1::Error::Body(error)), }, }, - error => Self::Protocol(Arc::new(error)), + error => Self::protocol(error), } } } diff --git a/crates/client/tests/client/options.rs b/crates/client/tests/client/options.rs index 6bb394af..978025aa 100644 --- a/crates/client/tests/client/options.rs +++ b/crates/client/tests/client/options.rs @@ -70,3 +70,33 @@ fn clients_report_their_endpoint() { assert_eq!(endpoint.scheme(), "http"); }); } + +#[test] +fn a_disabled_plaintext_engine_fails_calls_before_connecting() { + let scheduler = NativeScheduler::new().unwrap(); + let options = Options { + protocols: base_http_protocol::HttpProtocols { + enabled: Vec::new(), + ..Default::default() + }, + ..Default::default() + }; + // Nothing listens on port 1, so connecting would fail; selection fails first. + let endpoint = Endpoint::new("127.0.0.1:1".parse().unwrap()); + let (client, driver) = Client::new(&scheduler, endpoint, options).unwrap(); + let never = base_scheduler::Cancellation::never(); + let (driven, ()) = + futures_lite::future::block_on(futures_lite::future::zip(driver.run(&never), async { + let request = + base_http::Request::new(base_http::Method::GET, "/", base_http::body::EmptyBody); + let error = client.call(request, &never).await.err().unwrap(); + assert!(matches!(error, Error::Negotiation(_)), "{error:?}"); + assert_eq!( + chain(&error), + ["HTTP application protocol \"http/1.1\" is not enabled"] + ); + client.begin_close(); + })); + driven.unwrap(); + futures_lite::future::block_on(scheduler.shutdown()); +} diff --git a/crates/client/tests/https.rs b/crates/client/tests/https.rs index 33b19a73..466506d9 100644 --- a/crates/client/tests/https.rs +++ b/crates/client/tests/https.rs @@ -93,7 +93,10 @@ fn https_echo_reuses_connections_and_accepts_during_another_handshake() { let endpoint = Endpoint::new(address).with_tls(client_config, "localhost"); assert_eq!(endpoint.scheme(), "https"); let options = Options { - protocols: base_http_protocol::HttpProtocols { require_alpn: true }, + protocols: base_http_protocol::HttpProtocols { + require_alpn: true, + ..Default::default() + }, ..Options::default() }; let (client, driver) = Client::new(&scheduler, endpoint, options).unwrap(); @@ -198,6 +201,7 @@ fn https_client_applies_missing_alpn_policy_before_pool_publication() { let options = Options { protocols: base_http_protocol::HttpProtocols { require_alpn: required, + ..Default::default() }, ..Options::default() }; diff --git a/crates/protocol/readme.md b/crates/protocol/readme.md index fed4d051..7d5f3eec 100644 --- a/crates/protocol/readme.md +++ b/crates/protocol/readme.md @@ -1,7 +1,7 @@ # Base HTTP Protocol -Experimental protocol selection shared by the application client and server, following Async::HTTP's protocol factories. `HttpProtocols` supplies application-protocol offers and selects an enabled engine from explicit plaintext policy or an opaque negotiated identifier. `HttpProtocol` constructs the corresponding client/server codec pair. +Experimental protocol selection shared by the application client and server, following Async::HTTP's protocol factories. `HttpProtocols` lists the enabled engines in preference order, from which it supplies application-protocol offers, and selects an enabled engine from its `Plaintext` policy or an opaque negotiated identifier, so offers and selection always agree. `HttpProtocol` constructs the selected connection, a `ClientConnection` or `ServerConnection`, closed enums with one variant for each engine compiled in, on which the client and server dispatch. `ProtocolError` reports an engine's failure and names the engine. -The initial engine is HTTP/1, advertising `http/1.1`. Missing ALPN is accepted for older HTTPS peers unless `require_alpn` is enabled. An unknown negotiated identifier is always rejected. TLS configuration, handshakes, encryption and transport ownership remain outside this crate. `base-http1` only consumes plaintext stream capabilities. +The initial engine is HTTP/1, advertising `http/1.1`. Missing ALPN is accepted for older HTTPS peers unless `require_alpn` is enabled, and only when HTTP/1 is enabled. An unknown or disabled negotiated identifier is always rejected, and a plaintext policy whose engine is disabled refuses the connection. TLS configuration, handshakes, encryption and transport ownership remain outside this crate. `base-http1` only consumes plaintext stream capabilities. HTTP/2 and QUIC/HTTP/3 are future engines. TCP and QUIC require distinct establishment paths; advertising `h3` over a TLS/TCP connection cannot select QUIC. The existing semantic `base_http::Protocol` describes application upgrades and is unrelated to this configuration. diff --git a/crates/protocol/src/lib.rs b/crates/protocol/src/lib.rs index aedbac8b..d4abec20 100644 --- a/crates/protocol/src/lib.rs +++ b/crates/protocol/src/lib.rs @@ -8,70 +8,167 @@ use base_endpoint::stream::{ReadableStream, WritableStream}; use base_http1::{RequestReader, RequestWriter, ResponseReader, ResponseWriter}; use std::fmt; -/// Enabled HTTP implementations and their establishment policy. -#[derive(Clone, Copy, Debug, Default)] +/// Enabled HTTP engines and their establishment policy, shared by plain and +/// encrypted establishment, so the identifiers offered and those accepted +/// always agree. +#[derive(Clone, Debug, PartialEq, Eq)] pub struct HttpProtocols { + /// The enabled engines, most preferred first. Application-protocol offers + /// follow this order, and only these engines are negotiated. + pub enabled: Vec, + /// The engine used on a plain TCP connection, which has no negotiation. + pub plaintext: Plaintext, /// Reject an encrypted peer that did not negotiate an application protocol. - /// Unknown negotiated protocols are rejected regardless of this setting. + /// Otherwise such a peer uses HTTP/1, when it is enabled. Unknown or + /// disabled negotiated protocols are rejected regardless of this setting. pub require_alpn: bool, } +impl Default for HttpProtocols { + fn default() -> Self { + Self { + enabled: vec![HttpProtocol::Http1], + plaintext: Plaintext::Http1, + require_alpn: false, + } + } +} impl HttpProtocols { - /// Opaque application-protocol names supplied to the security provider. + /// Opaque application-protocol names supplied to the security provider, in + /// preference order. pub fn alpn_protocols(&self) -> Vec> { - vec![b"http/1.1".to_vec()] + self.enabled + .iter() + .map(|protocol| protocol.alpn().to_vec()) + .collect() } - /// The initial explicit policy for a plain TCP stream. - pub fn plaintext(&self) -> HttpProtocol { - HttpProtocol::Http1 + /// Select the engine for a plain TCP connection. + pub fn plaintext(&self) -> Result { + let protocol = match self.plaintext { + Plaintext::Http1 => HttpProtocol::Http1, + }; + self.enabled(protocol) } /// Select the engine after an authenticated transport reports negotiation. pub fn negotiated(&self, selected: Option<&[u8]>) -> Result { match selected { - Some(b"http/1.1") => Ok(HttpProtocol::Http1), - None if !self.require_alpn => Ok(HttpProtocol::Http1), + Some(name) => self + .enabled + .iter() + .copied() + .find(|protocol| protocol.alpn() == name) + .ok_or_else(|| NegotiationError::Unsupported(name.to_vec())), + None if !self.require_alpn => self.enabled(HttpProtocol::Http1), None => Err(NegotiationError::Missing), - Some(name) => Err(NegotiationError::Unsupported(name.to_vec())), + } + } + fn enabled(&self, protocol: HttpProtocol) -> Result { + if self.enabled.contains(&protocol) { + Ok(protocol) + } else { + Err(NegotiationError::Disabled(protocol)) } } } -/// An enabled wire engine selected before exchange admission. -#[derive(Clone, Copy, Debug, PartialEq, Eq)] +/// How a plain TCP connection, which negotiates nothing, chooses its engine. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub enum Plaintext { + /// Use HTTP/1. + #[default] + Http1, +} + +/// An HTTP engine: a wire protocol implementation selected per connection. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] pub enum HttpProtocol { /// HTTP/1 framing over a reliable plaintext byte stream. Http1, } impl HttpProtocol { - /// Construct matching client codec directions over an established stream. + /// The engine's application-protocol identifier. + pub fn alpn(self) -> &'static [u8] { + match self { + Self::Http1 => b"http/1.1", + } + } + /// Construct a client connection of this engine over an established + /// stream. pub fn client( self, reader: R, writer: W, - options: base_http1::Options, - ) -> Result<(ResponseReader, RequestWriter), base_http1::Error> { + http1: base_http1::Options, + ) -> Result, ProtocolError> { match self { - Self::Http1 => Ok(( - ResponseReader::new(reader, options)?, + Self::Http1 => Ok(ClientConnection::Http1( + ResponseReader::new(reader, http1)?, RequestWriter::new(writer), )), } } - /// Construct matching server codec directions over an established stream. + /// Construct a server connection of this engine over an established + /// stream. pub fn server( self, reader: R, writer: W, - options: base_http1::Options, - ) -> Result<(RequestReader, ResponseWriter), base_http1::Error> { + http1: base_http1::Options, + ) -> Result, ProtocolError> { match self { - Self::Http1 => Ok(( - RequestReader::new(reader, options)?, + Self::Http1 => Ok(ServerConnection::Http1( + RequestReader::new(reader, http1)?, ResponseWriter::new(writer), )), } } } +/// A selected client connection, one variant for each engine compiled in. The +/// client dispatches on it, so adding an engine adds a variant. +pub enum ClientConnection { + Http1(ResponseReader, RequestWriter), +} + +/// A selected server connection, one variant for each engine compiled in. The +/// server dispatches on it, so adding an engine adds a variant. +pub enum ServerConnection { + Http1(RequestReader, ResponseWriter), +} + +/// A failure of an engine, naming the engine that produced it. Transparent: it +/// displays the engine's error and reports that error's source. +#[derive(Debug)] +pub enum ProtocolError { + Http1(base_http1::Error), +} +impl ProtocolError { + /// The engine that failed. + pub fn protocol(&self) -> HttpProtocol { + match self { + Self::Http1(_) => HttpProtocol::Http1, + } + } +} +impl From for ProtocolError { + fn from(error: base_http1::Error) -> Self { + Self::Http1(error) + } +} +impl fmt::Display for ProtocolError { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::Http1(error) => error.fmt(formatter), + } + } +} +impl std::error::Error for ProtocolError { + fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { + match self { + Self::Http1(error) => error.source(), + } + } +} + /// Negotiated evidence did not select an enabled HTTP engine. #[derive(Clone, Debug, PartialEq, Eq)] pub enum NegotiationError { @@ -79,11 +176,20 @@ pub enum NegotiationError { Missing, /// The peer selected an unsupported identifier. Retain its opaque bytes. Unsupported(Vec), + /// The engine the connection requires is not enabled. + Disabled(HttpProtocol), } impl fmt::Display for NegotiationError { fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { match self { Self::Missing => formatter.write_str("HTTP application protocol was not negotiated"), + Self::Disabled(protocol) => { + let name = protocol.alpn().escape_ascii(); + write!( + formatter, + "HTTP application protocol \"{name}\" is not enabled" + ) + } Self::Unsupported(name) => { let name = name.escape_ascii(); write!( @@ -100,11 +206,28 @@ impl std::error::Error for NegotiationError {} mod tests { use super::*; + fn http1_disabled() -> HttpProtocols { + HttpProtocols { + enabled: Vec::new(), + ..HttpProtocols::default() + } + } + + #[test] + fn offers_follow_the_enabled_engines_in_order() { + assert_eq!( + HttpProtocols::default().alpn_protocols(), + vec![b"http/1.1".to_vec()] + ); + assert!(http1_disabled().alpn_protocols().is_empty()); + } + #[test] - fn unsupported_identifiers_never_fall_back_to_http1() { + fn unknown_or_disabled_identifiers_are_rejected() { for required in [false, true] { let protocols = HttpProtocols { require_alpn: required, + ..HttpProtocols::default() }; for name in [b"h2".as_slice(), b"h3", b"http/1.1\0", b"\xff"] { assert_eq!( @@ -116,17 +239,34 @@ mod tests { protocols.negotiated(Some(b"http/1.1")), Ok(HttpProtocol::Http1) ); - assert_eq!(protocols.plaintext(), HttpProtocol::Http1); + assert_eq!(protocols.plaintext(), Ok(HttpProtocol::Http1)); } + let disabled = http1_disabled(); + assert_eq!( + disabled.negotiated(Some(b"http/1.1")), + Err(NegotiationError::Unsupported(b"http/1.1".to_vec())) + ); + assert_eq!( + disabled.plaintext(), + Err(NegotiationError::Disabled(HttpProtocol::Http1)) + ); } #[test] - fn http1_is_advertised_and_absent_negotiation_follows_policy() { - let optional = HttpProtocols::default(); - assert_eq!(optional.alpn_protocols(), vec![b"http/1.1".to_vec()]); - assert_eq!(optional.negotiated(None), Ok(HttpProtocol::Http1)); - let required = HttpProtocols { require_alpn: true }; + fn a_missing_identifier_selects_http1_only_when_allowed_and_enabled() { + assert_eq!( + HttpProtocols::default().negotiated(None), + Ok(HttpProtocol::Http1) + ); + let required = HttpProtocols { + require_alpn: true, + ..HttpProtocols::default() + }; assert_eq!(required.negotiated(None), Err(NegotiationError::Missing)); + assert_eq!( + http1_disabled().negotiated(None), + Err(NegotiationError::Disabled(HttpProtocol::Http1)) + ); } #[test] @@ -143,5 +283,21 @@ mod tests { NegotiationError::Unsupported(b"\xff\"".to_vec()).to_string(), r#"unsupported HTTP application protocol: "\xff\"""# ); + assert_eq!( + NegotiationError::Disabled(HttpProtocol::Http1).to_string(), + "HTTP application protocol \"http/1.1\" is not enabled" + ); + } + + #[test] + fn protocol_errors_name_their_engine_and_are_transparent() { + let io = std::io::Error::other("reset"); + let error = ProtocolError::from(base_http1::Error::Io(io)); + assert_eq!(error.protocol(), HttpProtocol::Http1); + assert_eq!(error.to_string(), "HTTP/1 connection I/O failed"); + assert_eq!( + std::error::Error::source(&error).unwrap().to_string(), + "reset" + ); } } diff --git a/crates/server/readme.md b/crates/server/readme.md index 84be2dac..97941319 100644 --- a/crates/server/readme.md +++ b/crates/server/readme.md @@ -30,7 +30,7 @@ A request body is an independent value: a handler can pass it to work that outli Static handlers can use `BufferedBody`; imperative producers can return `BodyReader` and supervise their `BodyWriter` producer explicitly. There is one pull-body model. A handler may send interim heads while processing input. Returning a readable body that owns input also supports managed CONNECT and upgrade exchanges. -`serve_connection` consumes one accepted socket. `serve` consumes an already-bound listener and enforces `Options::max_connections`. `serve` and `serve_tls` disable Nagle's algorithm on each accepted socket unless `Options::tcp_nodelay` is false, so small streamed frames are not delayed waiting for acknowledgements. This is a best-effort hint: a socket that rejects it is still served. `serve_connection` leaves the options of a socket the caller accepted unchanged. Both retain the scheduler until reader/writer retirement and exclusive socket closure complete. For shutdown, cancel the supplied signal and await the serving future. Listener shutdown closes the listener, then terminates active work and joins cleanup; timed draining is future policy. Transient accept failures do not stop a listener: per-peer failures such as `ECONNABORTED` are retried, backing off after repeated failures, and resource exhaustion such as `EMFILE` pauses acceptance for 100 ms on the scheduler's `Clock`. They are counted in `Statistics::accept_errors`. Other accept failures, including scheduler closure, end serving with an error. +`serve_connection` consumes one accepted socket and serves it with `Options::protocols`'s plaintext engine. `serve` consumes an already-bound listener and enforces `Options::max_connections`. `serve` and `serve_tls` disable Nagle's algorithm on each accepted socket unless `Options::tcp_nodelay` is false, so small streamed frames are not delayed waiting for acknowledgements. This is a best-effort hint: a socket that rejects it is still served. `serve_connection` leaves the options of a socket the caller accepted unchanged. Both retain the scheduler until reader/writer retirement and exclusive socket closure complete. For shutdown, cancel the supplied signal and await the serving future. Listener shutdown closes the listener, then terminates active work and joins cleanup; timed draining is future policy. Transient accept failures do not stop a listener: per-peer failures such as `ECONNABORTED` are retried, backing off after repeated failures, and resource exhaustion such as `EMFILE` pauses acceptance for 100 ms on the scheduler's `Clock`. They are counted in `Statistics::accept_errors`. Other accept failures, including scheduler closure, end serving with an error. Run `cargo run --example hello`, then `curl -v http://127.0.0.1:8080/`. Use `-- --once` to serve one connection and exit; `BASE_HTTP_ADDRESS` overrides the bind address. The example uses the released Native scheduler as a development dependency. Real TCP tests use an independent raw HTTP peer and cover streaming, persistence, interim responses, trailers, managed duplex bodies, cancellation, errors and listener limits. diff --git a/crates/server/src/lib.rs b/crates/server/src/lib.rs index 39d97446..da858bfc 100644 --- a/crates/server/src/lib.rs +++ b/crates/server/src/lib.rs @@ -8,6 +8,7 @@ use base_endpoint::stream::{ReadableStream, WritableStream}; use base_http::{InterimHandler, InterimRelay, Scheme, Status}; +use base_http_protocol::{ProtocolError, ServerConnection}; use base_http1::{LentInput, RequestReader, ResponseWriter}; use base_scheduler::{ Cancellation, Clock, OperationError, SocketAccept, SocketClose, SocketLocalAddress, @@ -57,10 +58,11 @@ impl Default for Options { /// A server failure. Protocol and negotiation errors are transparent; other wrapping variants describe this layer and report their cause as the source, so a cause chain never repeats a message. #[derive(Debug)] pub enum Error { - Protocol(base_http1::Error), + /// The connection's engine failed, such as on a malformed request. + Protocol(ProtocolError), Handler(Box), /// A handler returned a final response which the protocol writer refused before writing any of it, such as an informational status or conflicting framing. - Response(base_http1::Error), + Response(ProtocolError), Io(std::io::Error), Cancelled, Negotiation(base_http_protocol::NegotiationError), @@ -91,9 +93,14 @@ impl std::error::Error for Error { } impl From for Error { fn from(e: base_http1::Error) -> Self { - match e { - base_http1::Error::Cancelled => Self::Cancelled, - e => Self::Protocol(e), + ProtocolError::from(e).into() + } +} +impl From for Error { + fn from(error: ProtocolError) -> Self { + match error { + ProtocolError::Http1(base_http1::Error::Cancelled) => Self::Cancelled, + error => Self::Protocol(error), } } } @@ -128,13 +135,14 @@ async fn cancellable( } /// Own one accepted socket through request admission, handler execution, output, -/// uncancellable lane retirement, and finally exclusive socket closure. Await -/// completion after cooperative cancellation; dropping this future is not a join. +/// uncancellable lane retirement, and finally exclusive socket closure. The +/// engine is `options.protocols`'s plaintext selection. Await completion after +/// cooperative cancellation; dropping this future is not a join. pub fn serve_connection<'scope, S, H>( scheduler: &'scope S, socket: S::Socket, handler: &H, - options: &base_http1::Options, + options: &Options, cancellation: &Cancellation, ) -> impl Future> + Send where @@ -157,7 +165,7 @@ async fn serve_connection_inner<'scope, S, H>( scheduler: &'scope S, socket: S::Socket, handler: &H, - options: &base_http1::Options, + options: &Options, cancellation: &Cancellation, ) -> Result where @@ -182,7 +190,7 @@ async fn connection_outcome<'scope, S, H>( scheduler: &'scope S, socket: S::Socket, handler: &H, - options: &base_http1::Options, + options: &Options, cancellation: &Cancellation, ) -> Outcome where @@ -197,7 +205,8 @@ where let mut requests = 0; // The outer owner closes the socket even when capability construction fails. let result = async { - options.validate()?; + options.http1.validate()?; + let protocol = options.protocols.plaintext()?; let mut reader = scheduler.socket_stream_reader(&socket)?; let writer = match scheduler.socket_stream_writer(&socket) { Ok(writer) => writer, @@ -212,21 +221,24 @@ where scheduler.socket_peer_address(&socket).ok(), scheduler.socket_local_address(&socket).ok(), )); - // The plaintext engine is HTTP/1, whose codecs fail to construct only when `options.validate` above fails. - let (input, output) = base_http_protocol::HttpProtocols::default() - .plaintext() - .server(reader, writer, options.clone()) - .expect("validated HTTP/1 options construct server codecs"); - serve_codecs( - input, - output, - handler, - &peer, - cancellation, - &mut requests, - &Scheme::HTTP, - ) - .await + // Codecs fail to construct only when the options validated above are invalid. + let connection = protocol + .server(reader, writer, options.http1.clone()) + .expect("validated options construct server codecs"); + match connection { + ServerConnection::Http1(input, output) => { + serve_codecs( + input, + output, + handler, + &peer, + cancellation, + &mut requests, + &Scheme::HTTP, + ) + .await + } + } } .await; let closed = scheduler.socket_close(socket).await; @@ -366,7 +378,7 @@ where let _ = output .reject(Status::INTERNAL_SERVER_ERROR, cancellation) .await; - return Err(Error::Response(error)); + return Err(Error::Response(error.into())); } Err(error) => return Err(error.into()), }; @@ -566,7 +578,7 @@ where options, cancellation, |socket, cancellation| async move { - connection_outcome(scheduler, socket, handler, &options.http1, &cancellation).await + connection_outcome(scheduler, socket, handler, options, &cancellation).await }, ) .await @@ -592,9 +604,7 @@ where let result = async { options.http1.validate()?; if options.max_connections == 0 { - return Err(Error::Protocol(base_http1::Error::Invalid( - "zero connection limit", - ))); + return Err(base_http1::Error::Invalid("zero connection limit").into()); } loop { if connections.len() == options.max_connections { @@ -751,17 +761,20 @@ where let result = connection .with_duplex(scheduler, cancellation, |reader, writer| async { let protocol = options.protocols.negotiated(selected.as_deref())?; - let (input, output) = protocol.server(reader, writer, options.http1.clone())?; - serve_codecs( - input, - output, - handler, - &peer, - cancellation, - &mut requests, - &Scheme::HTTPS, - ) - .await + match protocol.server(reader, writer, options.http1.clone())? { + ServerConnection::Http1(input, output) => { + serve_codecs( + input, + output, + handler, + &peer, + cancellation, + &mut requests, + &Scheme::HTTPS, + ) + .await + } + } }) .await; Outcome { requests, result } @@ -885,7 +898,7 @@ mod tests { #[test] fn invalid_responses_report_the_refusal_as_the_source() { - let error = Error::Response(base_http1::Error::Invalid("final response required")); + let error = Error::Response(base_http1::Error::Invalid("final response required").into()); assert_eq!( error.to_string(), "request handler returned an invalid response" @@ -908,9 +921,9 @@ mod tests { let error = Error::from(base_scheduler::OperationError::from(io::Error::from( io::ErrorKind::ConnectionReset, ))); - let expected = Error::Protocol(base_http1::Error::Io(io::Error::from( - io::ErrorKind::ConnectionReset, - ))); + let expected = Error::Protocol( + base_http1::Error::Io(io::Error::from(io::ErrorKind::ConnectionReset)).into(), + ); assert_eq!(format!("{error:?}"), format!("{expected:?}")); assert_eq!(error.source().unwrap().to_string(), "connection reset"); } diff --git a/crates/server/tests/end_to_end.rs b/crates/server/tests/end_to_end.rs index 8e158789..d4572b2f 100644 --- a/crates/server/tests/end_to_end.rs +++ b/crates/server/tests/end_to_end.rs @@ -666,7 +666,9 @@ fn limits_are_enforced_before_handler_admission() { ); assert!(matches!( served, - Err(Error::Protocol(base_http1::Error::Limit(_))) + Err(Error::Protocol(base_http_protocol::ProtocolError::Http1( + base_http1::Error::Limit(_) + ))) )); } diff --git a/crates/server/tests/support/mod.rs b/crates/server/tests/support/mod.rs index c4d7798e..1e96b2b8 100644 --- a/crates/server/tests/support/mod.rs +++ b/crates/server/tests/support/mod.rs @@ -89,7 +89,10 @@ pub fn connection_options Handler<'h, ServerContext>, T: Send + 'stat &scheduler, socket, &handler, - &options, + &base_http_server::Options { + http1: options.clone(), + ..Default::default() + }, &cancellation, ) .await; diff --git a/crates/server/tests/tls.rs b/crates/server/tests/tls.rs index 7c2deab8..3382aca3 100644 --- a/crates/server/tests/tls.rs +++ b/crates/server/tests/tls.rs @@ -152,9 +152,12 @@ impl<'h> Handler<'h, ServerContext> for Hello { #[test] fn negotiated_http1_serves_https_requests_on_an_accepted_connection() { - let protocols = HttpProtocols { require_alpn: true }; + let protocols = HttpProtocols { + require_alpn: true, + ..Default::default() + }; let options = Options { - protocols, + protocols: protocols.clone(), ..Default::default() }; let (served, (negotiated, response)) = tls_connection( @@ -185,9 +188,12 @@ fn negotiated_http1_serves_https_requests_on_an_accepted_connection() { #[test] fn missing_alpn_is_rejected_when_negotiation_is_required() { - let protocols = HttpProtocols { require_alpn: true }; + let protocols = HttpProtocols { + require_alpn: true, + ..Default::default() + }; let options = Options { - protocols, + protocols: protocols.clone(), ..Default::default() }; let (served, ()) = tls_connection( @@ -243,7 +249,9 @@ fn invalid_http1_options_reject_a_negotiated_connection() { ); assert!(matches!( served, - Err(Error::Protocol(base_http1::Error::Invalid(_))) + Err(Error::Protocol(base_http_protocol::ProtocolError::Http1( + base_http1::Error::Invalid(_) + ))) )); } @@ -269,7 +277,10 @@ fn listener_counts_a_connection_without_required_alpn_as_failed() { result }); let options = Options { - protocols: HttpProtocols { require_alpn: true }, + protocols: HttpProtocols { + require_alpn: true, + ..Default::default() + }, ..Default::default() }; // The listener replaces any configured ALPN list with the enabled protocols. diff --git a/crates/server/tests/transport_faults.rs b/crates/server/tests/transport_faults.rs index a3f8a16e..825191b8 100644 --- a/crates/server/tests/transport_faults.rs +++ b/crates/server/tests/transport_faults.rs @@ -393,11 +393,15 @@ fn serve( options: &base_http1::Options, cancellation: &Cancellation, ) -> Result { + let options = base_http_server::Options { + http1: options.clone(), + ..Default::default() + }; block_on(base_http_server::serve_connection( memory, (), handler, - options, + &options, cancellation, )) } @@ -418,6 +422,34 @@ fn never_cancelled_connection_serves_and_retires_every_capability() { assert_eq!(memory.closes(), (1, 1, 1)); } +#[test] +fn a_disabled_plaintext_engine_closes_the_socket_without_constructing_streams() { + let memory = Memory::new(REQUEST); + let handler = Hello::default(); + let options = base_http_server::Options { + protocols: base_http_protocol::HttpProtocols { + enabled: Vec::new(), + ..Default::default() + }, + ..Default::default() + }; + let served = block_on(base_http_server::serve_connection( + &memory, + (), + &handler, + &options, + &Cancellation::new(), + )); + let error = served.unwrap_err(); + assert!(matches!(error, Error::Negotiation(_)), "{error:?}"); + assert_eq!( + error.to_string(), + "HTTP application protocol \"http/1.1\" is not enabled" + ); + assert!(!handler.called.load(Ordering::SeqCst)); + assert_eq!(memory.closes(), (0, 0, 1)); +} + #[test] fn invalid_options_close_the_socket_without_constructing_streams() { let memory = Memory::new(REQUEST); @@ -429,7 +461,9 @@ fn invalid_options_close_the_socket_without_constructing_streams() { let served = serve(&memory, &handler, &options, &Cancellation::new()); assert!(matches!( served, - Err(Error::Protocol(base_http1::Error::Invalid(_))) + Err(Error::Protocol(base_http_protocol::ProtocolError::Http1( + base_http1::Error::Invalid(_) + ))) )); assert!(!handler.called.load(Ordering::SeqCst)); assert_eq!(memory.output(), ""); @@ -606,18 +640,24 @@ fn protocol_codecs_reject_invalid_limits_at_construction() { max_fields: 0, ..Default::default() }; - let protocol = base_http_protocol::HttpProtocols::default().plaintext(); + let protocol = base_http_protocol::HttpProtocols::default() + .plaintext() + .unwrap(); let reader = memory.socket_stream_reader(&()).unwrap(); let writer = memory.socket_stream_writer(&()).unwrap(); assert!(matches!( protocol.server(reader, writer, options.clone()), - Err(base_http1::Error::Invalid(_)) + Err(base_http_protocol::ProtocolError::Http1( + base_http1::Error::Invalid(_) + )) )); let reader = memory.socket_stream_reader(&()).unwrap(); let writer = memory.socket_stream_writer(&()).unwrap(); assert!(matches!( protocol.client(reader, writer, options), - Err(base_http1::Error::Invalid(_)) + Err(base_http_protocol::ProtocolError::Http1( + base_http1::Error::Invalid(_) + )) )); } diff --git a/design/http2.md b/design/http2.md index 6a160575..04e76fbf 100644 --- a/design/http2.md +++ b/design/http2.md @@ -46,6 +46,8 @@ Errors in `base-http-server` and `base-http-client` must not name a single engin M6 delivers the enum, the engine list, the plaintext policy types and the version-neutral errors and options, with HTTP/1 as the only engine. Client prior knowledge and server preface detection take effect when the `http2` engine is added in M7. +Implemented on 2026-11-21: `HttpProtocol::client` and `server` return `ClientConnection` and `ServerConnection`, with an `Http1` variant; `HttpProtocols` has `enabled`, in preference order, a `Plaintext` policy with an `Http1` variant, and `require_alpn`, and a disabled engine is reported as `NegotiationError::Disabled`; the server's `Protocol` and `Response` errors and the client's `Protocol` error carry a `ProtocolError`, whose `Http1` variant names the engine. `serve_connection` takes the server's `Options`, as `serve_tls_connection` does, and so uses its configured plaintext engine instead of the default; plain TCP selects its engine before streams are constructed or, on the client, before connecting. + ### Rationale Fixing the connection contract first, as its own milestone before HTTP/2, with a closed enum, an engine list in preference order, a bounded plaintext policy, no h2c Upgrade and version-neutral errors, was decided on 2026-11-20. Async::HTTP defines [one connection contract](https://github.com/socketry/async-http/blob/b7029c722791711588354016891297df21264272/lib/async/http/protocol.rb#L13-L28) for every engine: a client connection answers `concurrency`, `viable?`, `reusable?` and `call`; a server connection runs `each`. Its plaintext [`Protocol::HTTP`](https://github.com/socketry/async-http/blob/b7029c722791711588354016891297df21264272/lib/async/http/protocol/http.rb#L39-L56) peeks for the preface without consuming it. The current `HttpProtocol::client` and `server` return HTTP/1 reader/writer pairs (`crates/protocol/src/lib.rs`), which HTTP/2's single connection driver cannot satisfy. Async::HTTP's [`Protocol::HTTPS`](https://github.com/socketry/async-http/blob/b7029c722791711588354016891297df21264272/lib/async/http/protocol/https.rb#L49-L60) dispatches through the global `HANDLERS` table rather than the instance's, so configured and advertised protocols can disagree; one enabled set for both offers and selection prevents that. A closed enum keeps dispatch static, as the [taxonomy](client-connection.md#one-http-client-pool-contract) records. From 71df1be02425e4cfc527137ef20be6aaea8a563e Mon Sep 17 00:00:00 2001 From: Samuel Williams Date: Sat, 21 Nov 2026 12:56:59 +1300 Subject: [PATCH 2/4] Build each side's selected connection where its behaviour lives, as Async::HTTP's protocol client and server connections. --- Cargo.lock | 1 - benchmarks/client/Cargo.lock | 1 - benchmarks/hello/Cargo.lock | 1 - crates/client/src/connection.rs | 93 +++++++---- crates/protocol/Cargo.toml | 1 - crates/protocol/readme.md | 2 +- crates/protocol/src/lib.rs | 44 ----- crates/server/src/connection.rs | 206 ++++++++++++++++++++++++ crates/server/src/lib.rs | 200 ++--------------------- crates/server/tests/transport_faults.rs | 28 ---- design/client-connection.md | 2 +- design/http2.md | 4 +- design/roadmap.md | 2 +- 13 files changed, 286 insertions(+), 299 deletions(-) create mode 100644 crates/server/src/connection.rs diff --git a/Cargo.lock b/Cargo.lock index 3b4e280e..3a0fe9bb 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -348,7 +348,6 @@ dependencies = [ name = "base-http-protocol" version = "0.4.0" dependencies = [ - "base-endpoint", "base-http1", ] diff --git a/benchmarks/client/Cargo.lock b/benchmarks/client/Cargo.lock index 1153f11f..0bda09d5 100644 --- a/benchmarks/client/Cargo.lock +++ b/benchmarks/client/Cargo.lock @@ -186,7 +186,6 @@ dependencies = [ name = "base-http-protocol" version = "0.4.0" dependencies = [ - "base-endpoint", "base-http1", ] diff --git a/benchmarks/hello/Cargo.lock b/benchmarks/hello/Cargo.lock index 1e3229f3..bef026a8 100644 --- a/benchmarks/hello/Cargo.lock +++ b/benchmarks/hello/Cargo.lock @@ -95,7 +95,6 @@ dependencies = [ name = "base-http-protocol" version = "0.4.0" dependencies = [ - "base-endpoint", "base-http1", ] diff --git a/crates/client/src/connection.rs b/crates/client/src/connection.rs index 2b40efe3..7495467f 100644 --- a/crates/client/src/connection.rs +++ b/crates/client/src/connection.rs @@ -12,7 +12,7 @@ use base_endpoint::{ AddressEndpoint, ConnectEndpoint, stream::{ReadableStream, WritableStream}, }; -use base_http_protocol::ClientConnection; +use base_http_protocol::HttpProtocol; use base_http1::{RequestWriter, ResponseReader}; use base_pool::{Admission, MultiplexBuildPermit, MultiplexResource}; use base_scheduler::{ @@ -27,15 +27,15 @@ use std::sync::{ }; struct Inner<'scope> { - direct: Mutex + 'scope>>>, + selected: Mutex>>, changed: Event, stop: Cancellation, result: Mutex>>, } -/// An established HTTP/1 session retaining its transport and codec buffers. -/// Requests take and return its directions in the calling task; supervised -/// work handles construction and retirement. +/// An endpoint pool's entry for one established connection, holding the +/// connection the selected protocol constructed. Requests use it in the +/// calling task; supervised work handles construction and retirement. #[derive(Clone)] pub struct Connection<'scope> { inner: Arc>, @@ -44,7 +44,7 @@ impl<'scope> Connection<'scope> { fn new() -> Self { Self { inner: Arc::new(Inner { - direct: Mutex::new(None), + selected: Mutex::new(None), changed: Event::new(), stop: Cancellation::new(), result: Mutex::new(None), @@ -54,21 +54,21 @@ impl<'scope> Connection<'scope> { pub(crate) fn clone_handle(&self) -> Self { self.clone() } - 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) + /// The selected connection. Admission is published only after the session + /// installs it, which it never removes. + fn selected(&self) -> ClientConnection<'scope> { + lock(&self.inner.selected) .clone() - .expect("an admitted connection has direct state"); - direct.open(opening) + .expect("an admitted connection has a selected protocol connection") + } + pub(crate) fn open(&self, opening: Open<'scope>) -> Opening<'scope> { + self.selected().open(opening) } /// Check an admitted idle connection before its exchange begins. A failed /// probe retires the registration; the caller completes its use and /// acquires again, since no request bytes have been sent. pub(crate) fn probe(&self) -> bool { - let direct = lock(&self.inner.direct) - .clone() - .expect("an admitted connection has direct state"); - direct.probe() + self.selected().probe() } /// Wait until the connection is stopped or its lifetime ends. async fn stopped(&self, lifetime: &Cancellation) { @@ -166,14 +166,13 @@ pub(crate) async fn run<'scope, S>( return transport .with_duplex(scheduler, &lifetime, |reader, writer| async { let protocol = options.protocols.negotiated(selected.as_deref())?; - let connection = protocol - .client(reader, writer, options.http1.clone()) - .expect("Client::new validated the HTTP/1 options"); - match connection { - ClientConnection::Http1(input, output) => { + match protocol { + HttpProtocol::Http1 => { + let input = ResponseReader::new(reader, options.http1.clone()) + .expect("Client::new validated the HTTP/1 options"); session( input, - output, + RequestWriter::new(writer), &mut owner, &mut build, &mut ready, @@ -202,15 +201,17 @@ pub(crate) async fn run<'scope, S>( return Err(Error::from(error)); } }; - Ok::<_, Error>( - protocol - .client(reader, writer, options.http1.clone()) - .expect("Client::new validated the HTTP/1 options"), - ) + Ok::<_, Error>(match protocol { + HttpProtocol::Http1 => ( + ResponseReader::new(reader, options.http1.clone()) + .expect("Client::new validated the HTTP/1 options"), + RequestWriter::new(writer), + ), + }) } .await; let result = match initialized { - Ok(ClientConnection::Http1(input, output)) => { + Ok((input, output)) => { session( input, output, @@ -271,9 +272,33 @@ where } } -// A connection retains its typed HTTP buffers and transport directions. Only -// an admitted exchange may take them; short locks protect transfer, never I/O. -trait DirectConnection<'scope>: Send + Sync { +/// One outbound connection speaking the selected protocol, as Async::HTTP's +/// `Protocol::HTTP1::Client` is: it opens each exchange on the connection and +/// checks an idle connection before reuse, and its admission bounds the pool's +/// concurrent uses. There is one variant for each engine compiled in, on which +/// the client dispatches. Each variant erases its transport's types, which +/// depend on the scheduler and on whether the connection is encrypted. +#[derive(Clone)] +enum ClientConnection<'scope> { + Http1(Arc + 'scope>), +} +impl<'scope> ClientConnection<'scope> { + fn open(self, opening: Open<'scope>) -> Opening<'scope> { + match self { + Self::Http1(connection) => connection.open(opening), + } + } + fn probe(&self) -> bool { + match self { + Self::Http1(connection) => connection.probe(), + } + } +} + +// An HTTP/1 connection retains its typed buffers and transport directions. +// Only an admitted exchange may take them; short locks protect transfer, never +// I/O. +trait Http1Exchanges<'scope>: Send + Sync { fn open(self: Arc, opening: Open<'scope>) -> Opening<'scope>; fn probe(&self) -> bool; } @@ -329,7 +354,7 @@ impl Http1Connection<'_, R, W> { Ok(()) } } -impl<'scope, R: ReadableStream + 'scope, W: WritableStream + 'scope> DirectConnection<'scope> +impl<'scope, R: ReadableStream + 'scope, W: WritableStream + 'scope> Http1Exchanges<'scope> for Http1Connection<'scope, R, W> { fn open(self: Arc, opening: Open<'scope>) -> Opening<'scope> { @@ -464,8 +489,8 @@ where let _ = output.close().await; return Err(Error::Cancelled); } - // Set the direct interface before publication; no admitted caller can see - // a connection without its codec storage. + // Install the selected connection before publication; no admitted caller + // can see a connection without its codec storage. // 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. @@ -486,7 +511,7 @@ where queue, open: crate::writable::factory(), }); - *lock(&owner.connection.inner.direct) = Some(state.clone()); + *lock(&owner.connection.inner.selected) = Some(ClientConnection::Http1(state.clone())); // A registration that is already draining publishes no admission; its retirement stops the session below. state.registration.update(Admission::concurrent(1)); // Construction runs one session, and reports readiness itself only if the session never does. diff --git a/crates/protocol/Cargo.toml b/crates/protocol/Cargo.toml index cb77c6d4..d31bcf9b 100644 --- a/crates/protocol/Cargo.toml +++ b/crates/protocol/Cargo.toml @@ -10,4 +10,3 @@ readme = "readme.md" [dependencies] base-http1 = { version = "0.4.0", path = "../http1" } -base-endpoint = "0.3.0" diff --git a/crates/protocol/readme.md b/crates/protocol/readme.md index 7d5f3eec..e8044fc4 100644 --- a/crates/protocol/readme.md +++ b/crates/protocol/readme.md @@ -1,6 +1,6 @@ # Base HTTP Protocol -Experimental protocol selection shared by the application client and server, following Async::HTTP's protocol factories. `HttpProtocols` lists the enabled engines in preference order, from which it supplies application-protocol offers, and selects an enabled engine from its `Plaintext` policy or an opaque negotiated identifier, so offers and selection always agree. `HttpProtocol` constructs the selected connection, a `ClientConnection` or `ServerConnection`, closed enums with one variant for each engine compiled in, on which the client and server dispatch. `ProtocolError` reports an engine's failure and names the engine. +Experimental protocol selection shared by the application client and server, following Async::HTTP's protocol factories. `HttpProtocols` lists the enabled engines in preference order, from which it supplies application-protocol offers, and selects an enabled engine from its `Plaintext` policy or an opaque negotiated identifier, so offers and selection always agree. `HttpProtocol` names the selected engine; the client and server each construct their connection for it, as Async::HTTP's `Protocol::HTTP1::Client` and `Server`, and dispatch on a closed enum with one variant for each engine compiled in. `ProtocolError` reports an engine's failure and names the engine. The initial engine is HTTP/1, advertising `http/1.1`. Missing ALPN is accepted for older HTTPS peers unless `require_alpn` is enabled, and only when HTTP/1 is enabled. An unknown or disabled negotiated identifier is always rejected, and a plaintext policy whose engine is disabled refuses the connection. TLS configuration, handshakes, encryption and transport ownership remain outside this crate. `base-http1` only consumes plaintext stream capabilities. diff --git a/crates/protocol/src/lib.rs b/crates/protocol/src/lib.rs index d4abec20..607c8fc7 100644 --- a/crates/protocol/src/lib.rs +++ b/crates/protocol/src/lib.rs @@ -4,8 +4,6 @@ #![doc = include_str!("../readme.md")] #![forbid(unsafe_code)] -use base_endpoint::stream::{ReadableStream, WritableStream}; -use base_http1::{RequestReader, RequestWriter, ResponseReader, ResponseWriter}; use std::fmt; /// Enabled HTTP engines and their establishment policy, shared by plain and @@ -91,48 +89,6 @@ impl HttpProtocol { Self::Http1 => b"http/1.1", } } - /// Construct a client connection of this engine over an established - /// stream. - pub fn client( - self, - reader: R, - writer: W, - http1: base_http1::Options, - ) -> Result, ProtocolError> { - match self { - Self::Http1 => Ok(ClientConnection::Http1( - ResponseReader::new(reader, http1)?, - RequestWriter::new(writer), - )), - } - } - /// Construct a server connection of this engine over an established - /// stream. - pub fn server( - self, - reader: R, - writer: W, - http1: base_http1::Options, - ) -> Result, ProtocolError> { - match self { - Self::Http1 => Ok(ServerConnection::Http1( - RequestReader::new(reader, http1)?, - ResponseWriter::new(writer), - )), - } - } -} - -/// A selected client connection, one variant for each engine compiled in. The -/// client dispatches on it, so adding an engine adds a variant. -pub enum ClientConnection { - Http1(ResponseReader, RequestWriter), -} - -/// A selected server connection, one variant for each engine compiled in. The -/// server dispatches on it, so adding an engine adds a variant. -pub enum ServerConnection { - Http1(RequestReader, ResponseWriter), } /// A failure of an engine, naming the engine that produced it. Transparent: it diff --git a/crates/server/src/connection.rs b/crates/server/src/connection.rs new file mode 100644 index 00000000..dc0770b9 --- /dev/null +++ b/crates/server/src/connection.rs @@ -0,0 +1,206 @@ +// Released under the MIT License. +// Copyright, 2026, by Samuel Williams. + +//! Inbound connections speaking the selected protocol. +use crate::{Error, Handler, Options, Peer, ServerContext, cancellable}; +use base_endpoint::stream::{ReadableStream, WritableStream}; +use base_http::{InterimHandler, InterimRelay, Scheme, Status}; +use base_http_protocol::HttpProtocol; +use base_http1::{LentInput, RequestReader, ResponseWriter}; +use base_scheduler::Cancellation; +use futures_util::future::{Either, select}; +use std::{pin::pin, sync::Arc}; + +/// One inbound connection speaking the selected protocol, as Async::HTTP's +/// `Protocol::HTTP1::Server` is: it reads each request, calls the handler with +/// it and writes the response, until the connection ends. There is one variant +/// for each engine compiled in, on which the server dispatches. +pub(crate) enum ServerConnection { + Http1(Http1Connection), +} + +impl ServerConnection { + /// Construct a connection of `protocol` over an established stream. + pub(crate) fn new( + protocol: HttpProtocol, + reader: R, + writer: W, + options: &Options, + ) -> Result { + match protocol { + HttpProtocol::Http1 => Ok(Self::Http1(Http1Connection { + input: LentInput::new(RequestReader::new(reader, options.http1.clone())?), + output: ResponseWriter::new(writer), + })), + } + } + + /// Serve requests with `handler` until the connection ends, counting them + /// in `count`, then retire the connection's directions. The caller closes + /// the transport. + pub(crate) async fn serve<'scope, H>( + self, + handler: &H, + peer: &Arc, + cancellation: &Cancellation, + count: &mut u64, + scheme: &Scheme, + ) -> Result<(), Error> + where + R: 'scope, + H: Handler<'scope, ServerContext>, + { + match self { + Self::Http1(connection) => { + connection + .serve(handler, peer, cancellation, count, scheme) + .await + } + } + } +} + +/// An HTTP/1 connection: its request input, lent to each request body, and its +/// response output. +pub(crate) struct Http1Connection { + input: LentInput, + output: ResponseWriter, +} + +impl Http1Connection { + /// Serve requests until the connection ends, then retire both directions. + async fn serve<'scope, H>( + mut self, + handler: &H, + peer: &Arc, + cancellation: &Cancellation, + count: &mut u64, + scheme: &Scheme, + ) -> Result<(), Error> + where + R: 'scope, + H: Handler<'scope, ServerContext>, + { + let Self { input, output } = &mut self; + let result = exchanges(input, output, handler, peer, cancellation, count, scheme).await; + // After a normal end, wait for the last request body before retiring input, + // so work still reading it, such as a forwarded upload, can finish. + // Cancellation, or any failure, takes the input back from the body at once. + if result.is_ok() { + let _ = input.returned(cancellation).await; + } + // Both cleanups run regardless of the exchange or the other cleanup result. + let input_closed = input.close().await; + let output_closed = output.close().await; + result?; + input_closed?; + output_closed?; + Ok(()) + } +} + +async fn exchanges<'scope, R, W, H>( + input: &mut LentInput, + output: &mut ResponseWriter, + handler: &H, + peer: &Arc, + cancellation: &Cancellation, + count: &mut u64, + scheme: &Scheme, +) -> Result<(), Error> +where + R: ReadableStream + Send + 'scope, + W: WritableStream, + H: Handler<'scope, ServerContext>, +{ + let relay = InterimRelay::new(); + loop { + let (mut request, exchange) = match input.read_request(cancellation).await { + Ok(Some(pair)) => pair, + Ok(None) => return Ok(()), + Err(error) => { + if !matches!(error, base_http1::Error::Cancelled) { + let status = if matches!(error, base_http1::Error::Limit(_)) { + Status::new(431).unwrap() + } else { + Status::BAD_REQUEST + }; + // A bad request cannot be reused even if rejection succeeds. + let _ = output.reject(status, cancellation).await; + } + return Err(error.into()); + } + }; + request.scheme.get_or_insert_with(|| scheme.clone()); + let result = { + let mut context = ServerContext::new(peer.clone(), relay.sender()); + let mut called = pin!(handler.call(request, &mut context, cancellation)); + // Write each interim response the handler hands over while still + // polling the handler, which waits for it. + let handled = async { + loop { + let response = match select(called.as_mut(), pin!(relay.next())).await { + Either::Left((result, _)) => break result, + Either::Right((response, _)) => response, + }; + let mut writer = output.interim(exchange.version()); + let written = pin!(writer.on_interim_response(response, cancellation)); + match select(written, called.as_mut()).await { + Either::Left((written, _)) => relay.complete(written), + // The handler abandoned its send; dropping the write + // poisons output if it had started. + Either::Right((result, _)) => break result, + } + } + }; + let result = cancellable(handled, cancellation).await; + relay.finish(); + result? + }; + // The response can borrow the input lane, which a failure inspects, so only a successful result leaves this block. + let mut response = 'handled: { + let error = match result.map_err(|error| Error::Handler(Box::new(error))) { + Ok(response) => break 'handled response, + Err(error) => error, + }; + // Cancellation can arrive between polling the outer signal and polling a handler which propagates a cancelled body operation. + if cancellation.is_cancelled() { + return Err(Error::Cancelled); + } + // No final head has been written, so the peer can still learn of the failure: failed request input means the request was bad, and anything else is a server error. The input position may be unknown and unread input may remain, so the connection always closes afterwards; output already out of sync refuses the response and just closes. The input is taken back from a request body that outlived the handler, whose later reads fail. + input.reclaim().await; + let status = if input.input().is_some_and(RequestReader::is_poisoned) { + Status::BAD_REQUEST + } else { + Status::INTERNAL_SERVER_ERROR + }; + let _ = output.reject(status, cancellation).await; + return Err(error); + }; + let written = output + .write_response(&exchange, &mut response, cancellation) + .await; + drop(response); + let persistent = match written { + Ok(persistent) => persistent, + // Usable output means the writer refused the response before writing any of it, so the peer can still learn of the failure; the request may be unfinished, so the connection closes afterwards. + Err(error) if output.is_usable() && !matches!(error, base_http1::Error::Cancelled) => { + let _ = output + .reject(Status::INTERNAL_SERVER_ERROR, cancellation) + .await; + return Err(Error::Response(error.into())); + } + Err(error) => return Err(error.into()), + }; + *count += 1; + if !persistent { + return Ok(()); + } + // The request body may outlive its handler, such as one a client is + // still forwarding; the next request waits until it ends or is dropped. + input.returned(cancellation).await?; + if !input.is_reusable() { + return Ok(()); + } + } +} diff --git a/crates/server/src/lib.rs b/crates/server/src/lib.rs index da858bfc..69df3b0c 100644 --- a/crates/server/src/lib.rs +++ b/crates/server/src/lib.rs @@ -6,14 +6,16 @@ #![doc = include_str!("../readme.md")] #![forbid(unsafe_code)] -use base_endpoint::stream::{ReadableStream, WritableStream}; -use base_http::{InterimHandler, InterimRelay, Scheme, Status}; -use base_http_protocol::{ProtocolError, ServerConnection}; -use base_http1::{LentInput, RequestReader, ResponseWriter}; +use base_endpoint::stream::ReadableStream; +use base_http::Scheme; +use base_http_protocol::ProtocolError; + +mod connection; use base_scheduler::{ Cancellation, Clock, OperationError, SocketAccept, SocketClose, SocketLocalAddress, SocketPeerAddress, SocketSetOption, SocketStreamReading, SocketStreamWriting, TcpNoDelay, }; +use connection::ServerConnection; use futures_util::{ future::{Either, select}, stream::{FuturesUnordered, StreamExt}, @@ -115,7 +117,7 @@ impl From for Error { } } -async fn cancellable( +pub(crate) async fn cancellable( future: F, cancellation: &Cancellation, ) -> Result { @@ -221,24 +223,12 @@ where scheduler.socket_peer_address(&socket).ok(), scheduler.socket_local_address(&socket).ok(), )); - // Codecs fail to construct only when the options validated above are invalid. - let connection = protocol - .server(reader, writer, options.http1.clone()) - .expect("validated options construct server codecs"); - match connection { - ServerConnection::Http1(input, output) => { - serve_codecs( - input, - output, - handler, - &peer, - cancellation, - &mut requests, - &Scheme::HTTP, - ) - .await - } - } + // A connection fails to construct only when the options validated above are invalid. + let connection = ServerConnection::new(protocol, reader, writer, options) + .expect("validated options construct server connections"); + connection + .serve(handler, &peer, cancellation, &mut requests, &Scheme::HTTP) + .await } .await; let closed = scheduler.socket_close(socket).await; @@ -248,153 +238,6 @@ where } } -/// Serve exchanges over established codecs, then retire both directions. -async fn serve_codecs<'scope, R, W, H>( - input: RequestReader, - mut output: ResponseWriter, - handler: &H, - peer: &Arc, - cancellation: &Cancellation, - count: &mut u64, - scheme: &Scheme, -) -> Result<(), Error> -where - R: ReadableStream + Send + 'scope, - W: WritableStream, - H: Handler<'scope, ServerContext>, -{ - let mut input = LentInput::new(input); - let result = exchanges( - &mut input, - &mut output, - handler, - peer, - cancellation, - count, - scheme, - ) - .await; - // After a normal end, wait for the last request body before retiring input, - // so work still reading it, such as a forwarded upload, can finish. - // Cancellation, or any failure, takes the input back from the body at once. - if result.is_ok() { - let _ = input.returned(cancellation).await; - } - // Both cleanups run regardless of the exchange or the other cleanup result. - let input_closed = input.close().await; - let output_closed = output.close().await; - result?; - input_closed?; - output_closed?; - Ok(()) -} - -async fn exchanges<'scope, R, W, H>( - input: &mut LentInput, - output: &mut ResponseWriter, - handler: &H, - peer: &Arc, - cancellation: &Cancellation, - count: &mut u64, - scheme: &Scheme, -) -> Result<(), Error> -where - R: ReadableStream + Send + 'scope, - W: WritableStream, - H: Handler<'scope, ServerContext>, -{ - let relay = InterimRelay::new(); - loop { - let (mut request, exchange) = match input.read_request(cancellation).await { - Ok(Some(pair)) => pair, - Ok(None) => return Ok(()), - Err(error) => { - if !matches!(error, base_http1::Error::Cancelled) { - let status = if matches!(error, base_http1::Error::Limit(_)) { - Status::new(431).unwrap() - } else { - Status::BAD_REQUEST - }; - // A bad request cannot be reused even if rejection succeeds. - let _ = output.reject(status, cancellation).await; - } - return Err(error.into()); - } - }; - request.scheme.get_or_insert_with(|| scheme.clone()); - let result = { - let mut context = ServerContext::new(peer.clone(), relay.sender()); - let mut called = pin!(handler.call(request, &mut context, cancellation)); - // Write each interim response the handler hands over while still - // polling the handler, which waits for it. - let handled = async { - loop { - let response = match select(called.as_mut(), pin!(relay.next())).await { - Either::Left((result, _)) => break result, - Either::Right((response, _)) => response, - }; - let mut writer = output.interim(exchange.version()); - let written = pin!(writer.on_interim_response(response, cancellation)); - match select(written, called.as_mut()).await { - Either::Left((written, _)) => relay.complete(written), - // The handler abandoned its send; dropping the write - // poisons output if it had started. - Either::Right((result, _)) => break result, - } - } - }; - let result = cancellable(handled, cancellation).await; - relay.finish(); - result? - }; - // The response can borrow the input lane, which a failure inspects, so only a successful result leaves this block. - let mut response = 'handled: { - let error = match result.map_err(|error| Error::Handler(Box::new(error))) { - Ok(response) => break 'handled response, - Err(error) => error, - }; - // Cancellation can arrive between polling the outer signal and polling a handler which propagates a cancelled body operation. - if cancellation.is_cancelled() { - return Err(Error::Cancelled); - } - // No final head has been written, so the peer can still learn of the failure: failed request input means the request was bad, and anything else is a server error. The input position may be unknown and unread input may remain, so the connection always closes afterwards; output already out of sync refuses the response and just closes. The input is taken back from a request body that outlived the handler, whose later reads fail. - input.reclaim().await; - let status = if input.input().is_some_and(RequestReader::is_poisoned) { - Status::BAD_REQUEST - } else { - Status::INTERNAL_SERVER_ERROR - }; - let _ = output.reject(status, cancellation).await; - return Err(error); - }; - let written = output - .write_response(&exchange, &mut response, cancellation) - .await; - drop(response); - let persistent = match written { - Ok(persistent) => persistent, - // Usable output means the writer refused the response before writing any of it, so the peer can still learn of the failure; the request may be unfinished, so the connection closes afterwards. - Err(error) if output.is_usable() && !matches!(error, base_http1::Error::Cancelled) => { - let _ = output - .reject(Status::INTERNAL_SERVER_ERROR, cancellation) - .await; - return Err(Error::Response(error.into())); - } - Err(error) => return Err(error.into()), - }; - *count += 1; - if !persistent { - return Ok(()); - } - // The request body may outlive its handler, such as one a client is - // still forwarding; the next request waits until it ends or is dropped. - input.returned(cancellation).await?; - if !input.is_reusable() { - return Ok(()); - } - } -} - #[derive(Default, Debug)] pub struct Statistics { pub connections: u64, @@ -761,20 +604,9 @@ where let result = connection .with_duplex(scheduler, cancellation, |reader, writer| async { let protocol = options.protocols.negotiated(selected.as_deref())?; - match protocol.server(reader, writer, options.http1.clone())? { - ServerConnection::Http1(input, output) => { - serve_codecs( - input, - output, - handler, - &peer, - cancellation, - &mut requests, - &Scheme::HTTPS, - ) - .await - } - } + ServerConnection::new(protocol, reader, writer, options)? + .serve(handler, &peer, cancellation, &mut requests, &Scheme::HTTPS) + .await }) .await; Outcome { requests, result } diff --git a/crates/server/tests/transport_faults.rs b/crates/server/tests/transport_faults.rs index 825191b8..ddc6e085 100644 --- a/crates/server/tests/transport_faults.rs +++ b/crates/server/tests/transport_faults.rs @@ -633,34 +633,6 @@ fn listener_close_failure_is_reported_after_cancelled_acceptance() { assert_eq!(memory.closes(), (0, 0, 1)); } -#[test] -fn protocol_codecs_reject_invalid_limits_at_construction() { - let memory = Memory::default(); - let options = base_http1::Options { - max_fields: 0, - ..Default::default() - }; - let protocol = base_http_protocol::HttpProtocols::default() - .plaintext() - .unwrap(); - let reader = memory.socket_stream_reader(&()).unwrap(); - let writer = memory.socket_stream_writer(&()).unwrap(); - assert!(matches!( - protocol.server(reader, writer, options.clone()), - Err(base_http_protocol::ProtocolError::Http1( - base_http1::Error::Invalid(_) - )) - )); - let reader = memory.socket_stream_reader(&()).unwrap(); - let writer = memory.socket_stream_writer(&()).unwrap(); - assert!(matches!( - protocol.client(reader, writer, options), - Err(base_http_protocol::ProtocolError::Http1( - base_http1::Error::Invalid(_) - )) - )); -} - #[test] fn a_listener_serves_connections_that_reject_nodelay() { for tcp_nodelay in [true, false] { diff --git a/design/client-connection.md b/design/client-connection.md index c1fc72b6..d2c23f6d 100644 --- a/design/client-connection.md +++ b/design/client-connection.md @@ -64,7 +64,7 @@ Use `base-pool::MultiplexPool` conceptually for an endpoint's | HTTP/2 | Concurrent-stream capacity constrained by peer settings and local policy; updates as settings or draining state change. | | HTTP/3 | Concurrent-use bounds plus actual QUIC request-stream opening credit. Finishing one stream does not itself replenish peer-granted opening credit. | -A client can receive HTTP/1 on one connection and HTTP/2 on another. Both belong to the same pool contract when compatible with that client's policy. The client does not need to choose a pool type before connecting or move an unclassified connection between typed pools. The [HTTP/2 connection contract](http2.md#connection-contract-and-protocol-selection) makes this a closed enum over the engines compiled in, dispatched statically, with no trait object or second selection path. Until it is implemented in M6, the factories return HTTP/1 codec pairs. +A client can receive HTTP/1 on one connection and HTTP/2 on another. Both belong to the same pool contract when compatible with that client's policy. The client does not need to choose a pool type before connecting or move an unclassified connection between typed pools. The [HTTP/2 connection contract](http2.md#connection-contract-and-protocol-selection) makes this a closed enum over the engines compiled in, dispatched statically, with no trait object or second selection path. Since 2026-11-21 the pool's entries hold a `ClientConnection`, with an `Http1` variant, as Async::HTTP's pool holds `Protocol::HTTP1::Client` connections. Reserve construction capacity before dialing or handshaking. Retain that reservation through selection and driver setup, then commit the selected connection with its admission. Register the progress owner before making the handle usable. A connection that still awaits protocol readiness can initially publish zero admission. Failed/cancelled construction retains its charge until pending I/O and transport cleanup finish. Building, live and retiring connections count against the stated resource bound. diff --git a/design/http2.md b/design/http2.md index 04e76fbf..5d31a84c 100644 --- a/design/http2.md +++ b/design/http2.md @@ -33,7 +33,7 @@ The following must not carry over. Each is addressed by a requirement below, whe ### Requirement -`base-http-protocol` factories must construct a selected *connection*, not a pair of HTTP/1 codec directions. Selection returns a closed enum over the engines compiled in, for example `ServerConnection` with `Http1` and `Http2` variants, and the client equivalent. The client and server dispatch on that enum; adding an engine adds a variant and a feature, not a trait object or a second selection path. +`base-http-protocol` selects the engine, and each side constructs a selected *connection* of that engine, not a pair of HTTP/1 codec directions: a closed enum over the engines compiled in, `ServerConnection` in `base-http-server` and `ClientConnection` in `base-http-client`, each with `Http1` and `Http2` variants. As Async::HTTP's `Protocol::HTTP1::Server` and `Protocol::HTTP1::Client` are, a `ServerConnection` serves its requests, and a `ClientConnection`, the connection an endpoint client's pool holds, opens each exchange, checks an idle connection before reuse and supplies the pool's admission. The client and server dispatch on that enum; adding an engine adds a variant and a feature, not a trait object or a second selection path. The connections live with the client and server because their behaviour depends on each side's supervision, pool and error types, decided on 2026-11-21 in place of factories in `base-http-protocol`. `HttpProtocols` must describe the enabled engines in preference order and the plaintext policy, in addition to the existing `require_alpn`: @@ -46,7 +46,7 @@ Errors in `base-http-server` and `base-http-client` must not name a single engin M6 delivers the enum, the engine list, the plaintext policy types and the version-neutral errors and options, with HTTP/1 as the only engine. Client prior knowledge and server preface detection take effect when the `http2` engine is added in M7. -Implemented on 2026-11-21: `HttpProtocol::client` and `server` return `ClientConnection` and `ServerConnection`, with an `Http1` variant; `HttpProtocols` has `enabled`, in preference order, a `Plaintext` policy with an `Http1` variant, and `require_alpn`, and a disabled engine is reported as `NegotiationError::Disabled`; the server's `Protocol` and `Response` errors and the client's `Protocol` error carry a `ProtocolError`, whose `Http1` variant names the engine. `serve_connection` takes the server's `Options`, as `serve_tls_connection` does, and so uses its configured plaintext engine instead of the default; plain TCP selects its engine before streams are constructed or, on the client, before connecting. +Implemented on 2026-11-21: `base-http-server`'s `ServerConnection` and `base-http-client`'s `ClientConnection` have an `Http1` variant, which the server's request loop and the client's exchange opening and idle probe dispatch through. The HTTP/1 client variant erases its transport's types, which depend on the scheduler and on encryption, behind one trait object; engine dispatch has none. `HttpProtocol` names an engine and its ALPN identifier, and constructs nothing; `HttpProtocols` has `enabled`, in preference order, a `Plaintext` policy with an `Http1` variant, and `require_alpn`, and a disabled engine is reported as `NegotiationError::Disabled`; the server's `Protocol` and `Response` errors and the client's `Protocol` error carry a `ProtocolError`, whose `Http1` variant names the engine. `serve_connection` takes the server's `Options`, as `serve_tls_connection` does, and so uses its configured plaintext engine instead of the default; plain TCP selects its engine before streams are constructed or, on the client, before connecting. ### Rationale diff --git a/design/roadmap.md b/design/roadmap.md index c0297c22..504e83c5 100644 --- a/design/roadmap.md +++ b/design/roadmap.md @@ -19,7 +19,7 @@ The planned package boundaries are: - `base-http-client` and `base-http-server` compose the enabled protocols into application APIs. The client also uses `base-pool`. - `base-pool` implements distinct `SingleplexPool` and `MultiplexPool` contracts with a common admission interface. The HTTP client uses `MultiplexPool` with capacity one for HTTP/1 and negotiated stream capacity for HTTP/2/3. The HTTP/1 client exercises this integration; additional protocol consumers and measurements remain required before API stabilization. - `base-http-hpack` and `base-http-qpack` own compression interfaces. Each is a native implementation behind its Base-owned interface, decided on 2026-11-20: `base-http-hpack` ports `protocol-hpack`, and an independent codec is only a development dependency, as a test oracle. Upstream types do not become public aliases or re-exports in the codec API. No pluggable backend framework is required. -- `base-http-protocol` owns shared HTTP engine selection and client/server connection factories. The current factories return HTTP/1 codec pairs; M6 replaces them with selected connections, as [HTTP/2](http2.md#connection-contract-and-protocol-selection) requires. +- `base-http-protocol` owns shared HTTP engine selection. The client and server construct and dispatch selected connections of the chosen engine, as [HTTP/2](http2.md#connection-contract-and-protocol-selection) requires. - TLS currently lives in `base-endpoint::tls`, including optional rustls and supervised duplex I/O. Extraction into `base-tls` remains optional. Native `base-quic` uses rustls's separate QUIC handshake/key API; `base-http3` uses QUIC connections. - `base-quic-wire` and `base-quic-router` are sub-crates of the `base-quic` workspace (`crates/wire`, `crates/router`). `base-quic-wire` owns QUIC's version-independent header parsing and the connection-identifier format shared by `base-quic` and `base-quic-router`, without TLS, scheduler or HTTP dependencies. `base-quic-router` forwards QUIC datagrams to endpoints by connection identifier without terminating TLS; see [stateless QUIC routing](quic-routing.md). - `base-http-proxy`, a sub-crate of this workspace at `crates/proxy`, provides the proxy forwarding handler over the client and server. The load balancer application lives in its own repository, `base-load-balancer` as a working name, composing it with the router; see the [load balancer](load-balancer.md). From f9a270cb97c16d50f1fca09a8785d8ca17549a88 Mon Sep 17 00:00:00 2001 From: Samuel Williams Date: Sat, 21 Nov 2026 13:02:47 +1300 Subject: [PATCH 3/4] Validate options before constructing a server connection on either transport. --- crates/server/src/connection.rs | 19 +++++++++---------- crates/server/src/lib.rs | 8 +++----- 2 files changed, 12 insertions(+), 15 deletions(-) diff --git a/crates/server/src/connection.rs b/crates/server/src/connection.rs index dc0770b9..cca98be5 100644 --- a/crates/server/src/connection.rs +++ b/crates/server/src/connection.rs @@ -20,18 +20,17 @@ pub(crate) enum ServerConnection { } impl ServerConnection { - /// Construct a connection of `protocol` over an established stream. - pub(crate) fn new( - protocol: HttpProtocol, - reader: R, - writer: W, - options: &Options, - ) -> Result { + /// Construct a connection of `protocol` over an established stream, with + /// options the caller has validated. + pub(crate) fn new(protocol: HttpProtocol, reader: R, writer: W, options: &Options) -> Self { match protocol { - HttpProtocol::Http1 => Ok(Self::Http1(Http1Connection { - input: LentInput::new(RequestReader::new(reader, options.http1.clone())?), + HttpProtocol::Http1 => Self::Http1(Http1Connection { + input: LentInput::new( + RequestReader::new(reader, options.http1.clone()) + .expect("validated options construct server codecs"), + ), output: ResponseWriter::new(writer), - })), + }), } } diff --git a/crates/server/src/lib.rs b/crates/server/src/lib.rs index 69df3b0c..643dc3c6 100644 --- a/crates/server/src/lib.rs +++ b/crates/server/src/lib.rs @@ -223,10 +223,7 @@ where scheduler.socket_peer_address(&socket).ok(), scheduler.socket_local_address(&socket).ok(), )); - // A connection fails to construct only when the options validated above are invalid. - let connection = ServerConnection::new(protocol, reader, writer, options) - .expect("validated options construct server connections"); - connection + ServerConnection::new(protocol, reader, writer, options) .serve(handler, &peer, cancellation, &mut requests, &Scheme::HTTP) .await } @@ -603,8 +600,9 @@ where let mut requests = 0; let result = connection .with_duplex(scheduler, cancellation, |reader, writer| async { + options.http1.validate()?; let protocol = options.protocols.negotiated(selected.as_deref())?; - ServerConnection::new(protocol, reader, writer, options)? + ServerConnection::new(protocol, reader, writer, options) .serve(handler, &peer, cancellation, &mut requests, &Scheme::HTTPS) .await }) From e14c75f27f805239a0bbf024e66558b46717b636 Mon Sep 17 00:00:00 2001 From: Samuel Williams Date: Sat, 21 Nov 2026 13:16:41 +1300 Subject: [PATCH 4/4] Keep the client's pool entry private, and describe where each connection's admission is published. --- crates/client/src/connection.rs | 7 ++++--- crates/client/src/lib.rs | 2 +- design/client-connection.md | 2 +- design/http2.md | 2 +- design/implementation.md | 2 +- 5 files changed, 8 insertions(+), 7 deletions(-) diff --git a/crates/client/src/connection.rs b/crates/client/src/connection.rs index 7495467f..146795a1 100644 --- a/crates/client/src/connection.rs +++ b/crates/client/src/connection.rs @@ -37,7 +37,7 @@ struct Inner<'scope> { /// connection the selected protocol constructed. Requests use it in the /// calling task; supervised work handles construction and retirement. #[derive(Clone)] -pub struct Connection<'scope> { +pub(crate) struct Connection<'scope> { inner: Arc>, } impl<'scope> Connection<'scope> { @@ -274,8 +274,9 @@ where /// One outbound connection speaking the selected protocol, as Async::HTTP's /// `Protocol::HTTP1::Client` is: it opens each exchange on the connection and -/// checks an idle connection before reuse, and its admission bounds the pool's -/// concurrent uses. There is one variant for each engine compiled in, on which +/// checks an idle connection before reuse. HTTP/1's session publishes its fixed +/// admission of one exchange on the pool registration; an engine whose +/// admission changes, such as HTTP/2's stream limits, will publish it here. There is one variant for each engine compiled in, on which /// the client dispatches. Each variant erases its transport's types, which /// depend on the scheduler and on whether the connection is encrypted. #[derive(Clone)] diff --git a/crates/client/src/lib.rs b/crates/client/src/lib.rs index e107b710..f9b7dc56 100644 --- a/crates/client/src/lib.rs +++ b/crates/client/src/lib.rs @@ -15,7 +15,7 @@ mod sink; mod writable; pub use writable::{PendingResponse, RequestBodyWriter, StreamingResponseBody, WritableRequest}; -pub use connection::Connection; +use connection::Connection; pub use driver::Driver; pub use error::Error; diff --git a/design/client-connection.md b/design/client-connection.md index d2c23f6d..e7539954 100644 --- a/design/client-connection.md +++ b/design/client-connection.md @@ -15,7 +15,7 @@ Updated 2026-10-28. This records the taxonomy and orchestration boundary for the | Exchange | One request and its informational/final response sequence, with both body directions. | Remains active until both directions and associated work finish or are terminated. In HTTP/2 and HTTP/3 it normally occupies one request stream. | | Server | The application-facing accept/serve capability. | Establishes accepted transports, selects the protocol, owns connection drivers and dispatches requests to handlers. | -`Client` names the durable remote-server interface. `Connection` names the actual selected session, whether selected by negotiation or explicit configuration. An HTTP/2 connection is not one request stream; an HTTP/3 connection contains QUIC streams and is not a TCP-shaped byte stream. +`Client` names the durable remote-server interface. A connection names the actual selected session, whether selected by negotiation or explicit configuration: `ClientConnection` on the client, which the client's pool holds, and `ServerConnection` on the server, as Async::HTTP's `Protocol::HTTP1::Client` and `Server`. An HTTP/2 connection is not one request stream; an HTTP/3 connection contains QUIC streams and is not a TCP-shaped byte stream. These terms define responsibilities, not a new public trait hierarchy. `base-http` retains shared message/body semantics; `base-http-client` and `base-http-server` compose protocol-specific connection APIs. The existing semantic `Protocol` type expresses upgrade/tunnel intent, not the set of enabled HTTP engines or an ALPN selector. diff --git a/design/http2.md b/design/http2.md index 5d31a84c..4531cc8d 100644 --- a/design/http2.md +++ b/design/http2.md @@ -33,7 +33,7 @@ The following must not carry over. Each is addressed by a requirement below, whe ### Requirement -`base-http-protocol` selects the engine, and each side constructs a selected *connection* of that engine, not a pair of HTTP/1 codec directions: a closed enum over the engines compiled in, `ServerConnection` in `base-http-server` and `ClientConnection` in `base-http-client`, each with `Http1` and `Http2` variants. As Async::HTTP's `Protocol::HTTP1::Server` and `Protocol::HTTP1::Client` are, a `ServerConnection` serves its requests, and a `ClientConnection`, the connection an endpoint client's pool holds, opens each exchange, checks an idle connection before reuse and supplies the pool's admission. The client and server dispatch on that enum; adding an engine adds a variant and a feature, not a trait object or a second selection path. The connections live with the client and server because their behaviour depends on each side's supervision, pool and error types, decided on 2026-11-21 in place of factories in `base-http-protocol`. +`base-http-protocol` selects the engine, and each side constructs a selected *connection* of that engine, not a pair of HTTP/1 codec directions: a closed enum over the engines compiled in, `ServerConnection` in `base-http-server` and `ClientConnection` in `base-http-client`, each with `Http1` and `Http2` variants. As Async::HTTP's `Protocol::HTTP1::Server` and `Protocol::HTTP1::Client` are, a `ServerConnection` serves its requests, and a `ClientConnection`, the connection an endpoint client's pool entries hold, opens each exchange and checks an idle connection before reuse. A pool entry, which the client reserves before dialing, holds the `ClientConnection` once the engine is selected and is private to the client. HTTP/1's fixed admission of one exchange is published by its session on the pool registration; an `Http2` variant publishes its changing admission, from the peer's stream limits, through `ClientConnection`, in M7. The client and server dispatch on that enum; adding an engine adds a variant and a feature, not a trait object or a second selection path. The connections live with the client and server because their behaviour depends on each side's supervision, pool and error types, decided on 2026-11-21 in place of factories in `base-http-protocol`. `HttpProtocols` must describe the enabled engines in preference order and the plaintext policy, in addition to the existing `require_alpn`: diff --git a/design/implementation.md b/design/implementation.md index 358a7ed8..7b754acd 100644 --- a/design/implementation.md +++ b/design/implementation.md @@ -13,7 +13,7 @@ Updated 2026-11-09. The initial semantic core, pull bodies, native HTTP/1 client The HTTP packages are members of this repository's Cargo workspace and depend on each other by version and path, so their published manifests use the registry releases. Scheduler dependencies use `base-scheduler 0.5` and require Rust 1.87. Precise lifetime captures allow connections to move their sockets and concrete directional handles together without self references. No parent Cargo workspace is introduced over unrelated projects. `base-http1` parses request heads, response heads and trailers with its own parser (`design/http1-parser.md`). The server uses `FuturesUnordered` for supervised connection futures; it does not spawn or detach tasks. No `http`, `http-body`, Hyper or Tokio runtime is a production dependency. -Orchestration follows [clients, connections and protocol negotiation](client-connection.md): `Client` is the durable remote-server interface; `Connection` is an established transport with its selected HTTP session. The initial engine is HTTP/1 over resolved plain TCP or rustls TLS. The client uses the released multiplex pool with capacity one per HTTP/1 connection; ALPN is supplied and interpreted by the shared protocol layer; additional HTTP engines remain absent. Low-level HTTP/1 callers can still supply connected lanes and own progress, reuse and closure themselves. +Orchestration follows [clients, connections and protocol negotiation](client-connection.md): `Client` is the durable remote-server interface; a `ClientConnection`, which its pool holds, is an established transport with its selected HTTP session, and a `ServerConnection` is an accepted one. The initial engine is HTTP/1 over resolved plain TCP or rustls TLS. The client uses the released multiplex pool with capacity one per HTTP/1 connection; ALPN is supplied and interpreted by the shared protocol layer; additional HTTP engines remain absent. Low-level HTTP/1 callers can still supply connected lanes and own progress, reuse and closure themselves. ## Semantic core