Sub-protocol negotiation + breaking API changes (#143)

* Send and receive sub protocol headers according to draft 14 of the spec

* Docstring improvements

* Polish the sub-protocol support.

* Better error handling when parsing protocols.

* Improve ConnectRequest/ConnectResponse so they're future compatibile.

* Address PR #143 feedback: fix typos and improve encapsulation.

- Fix typo "send" -> "sent" in session.rs comment
- Fix typo "Manaully" -> "Manually" in server.rs docstring
- Change Connect struct fields from pub to pub(crate)
- Remove non-existent multiproto examples from README

Co-Authored-By: Claude Opus 4.5 <[email protected]>

* Add ?protocol to the demo and actually test it.

---------

Co-authored-by: Benjamin Kampmann <[email protected]>
Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: 3 people

web-demo/client.js

@@ -11,6 +11,7 @@ const params = new URLSearchParams(window.location.search);
 
 const url = params.get("url") || "https://localhost:4443";
 const datagram = params.get("datagram") || false;
+const protocol = params.get("protocol") || null;
 
 function log(msg) {
 	const element = document.createElement("div");
@@ -21,18 +22,33 @@ function log(msg) {
 
 async function run() {
 	// Connect using the hex fingerprint in the cert folder.
-	const transport = new WebTransport(url, {
+	const options = {
 		serverCertificateHashes: [
 			{
 				algorithm: "sha-256",
 				value: new Uint8Array(fingerprint),
 			},
 		],
-	});
+	};
+
+	// Add protocols if specified via query parameter
+	if (protocol) {
+		options.protocols = [protocol];
+		log(`requesting protocol: ${protocol}`);
+	}
+
+	const transport = new WebTransport(url, options);
 	await transport.ready;
 
 	log("connected");
 
+	// Log the negotiated protocol
+	if (transport.protocol) {
+		log(`negotiated protocol: ${transport.protocol}`);
+	} else if (protocol) {
+		log("no protocol negotiated (server did not select one)");
+	}
+
 	let writer;
 	let reader;
 

web-transport-proto/Cargo.toml

@@ -15,6 +15,7 @@ categories = ["network-programming", "web-programming"]
 [dependencies]
 bytes = "1"
 http = "1"
+sfv = "0.14"
 thiserror = "2"
 
 # Just for AsyncRead and AsyncWrite traits

web-transport-proto/src/connect.rs

@@ -47,6 +47,12 @@ pub enum ConnectError {
     #[error("expected path header")]
     WrongPath,
 
+    #[error("invalid protocol header")]
+    InvalidProtocol,
+
+    #[error("structured field error: {0}")]
+    StructuredFieldError(Arc<sfv::Error>),
+
     #[error("non-200 status: {0:?}")]
     ErrorStatus(http::StatusCode),
 
@@ -60,12 +66,45 @@ impl From<std::io::Error> for ConnectError {
     }
 }
 
-#[derive(Debug)]
+impl From<sfv::Error> for ConnectError {
+    fn from(err: sfv::Error) -> Self {
+        ConnectError::StructuredFieldError(Arc::new(err))
+    }
+}
+
+/// A CONNECT request to initiate a WebTransport session.
+#[non_exhaustive]
+#[derive(Debug, Clone)]
 pub struct ConnectRequest {
+    /// The URL to connect to.
     pub url: Url,
+
+    /// The subprotocols requested (if any).
+    pub protocols: Vec<String>,
 }
 
 impl ConnectRequest {
+    pub fn new(url: impl Into<Url>) -> Self {
+        Self {
+            url: url.into(),
+            protocols: Vec::new(),
+        }
+    }
+
+    pub fn with_protocol(mut self, protocol: impl Into<String>) -> Self {
+        self.protocols.push(protocol.into());
+        self
+    }
+
+    pub fn with_protocols(
+        mut self,
+        protocols: impl IntoIterator<Item = impl Into<String>>,
+    ) -> Self {
+        self.protocols
+            .extend(protocols.into_iter().map(|p| p.into()));
+        self
+    }
+
     pub fn decode<B: Buf>(buf: &mut B) -> Result<Self, ConnectError> {
         let (typ, mut data) = Frame::read(buf).map_err(|_| ConnectError::UnexpectedEnd)?;
         if typ != Frame::HEADERS {
@@ -102,9 +141,16 @@ impl ConnectRequest {
             return Err(ConnectError::WrongProtocol(protocol.map(|s| s.to_string())));
         }
 
+        let protocols = headers
+            .get(protocol_negotiation::AVAILABLE_NAME)
+            .map(protocol_negotiation::decode_list)
+            .transpose()
+            .map_err(|_| ConnectError::InvalidProtocol)?
+            .unwrap_or_default();
+
         let url = Url::parse(&format!("{scheme}://{authority}{path_and_query}"))?;
 
-        Ok(Self { url })
+        Ok(Self { url, protocols })
     }
 
     pub async fn read<S: AsyncRead + Unpin>(stream: &mut S) -> Result<Self, ConnectError> {
@@ -123,7 +169,7 @@ impl ConnectRequest {
         }
     }
 
-    pub fn encode<B: BufMut>(&self, buf: &mut B) {
+    pub fn encode<B: BufMut>(&self, buf: &mut B) -> Result<(), ConnectError> {
         let mut headers = qpack::Headers::default();
         headers.set(":method", "CONNECT");
         headers.set(":scheme", self.url.scheme());
@@ -135,6 +181,11 @@ impl ConnectRequest {
         headers.set(":path", &path_and_query);
         headers.set(":protocol", "webtransport");
 
+        if !self.protocols.is_empty() {
+            let encoded = protocol_negotiation::encode_list(&self.protocols)?;
+            headers.set(protocol_negotiation::AVAILABLE_NAME, &encoded);
+        }
+
         // Use a temporary buffer so we can compute the size.
         let mut tmp = Vec::new();
         headers.encode(&mut tmp);
@@ -143,22 +194,51 @@ impl ConnectRequest {
         Frame::HEADERS.encode(buf);
         size.encode(buf);
         buf.put_slice(&tmp);
+
+        Ok(())
     }
 
     pub async fn write<S: AsyncWrite + Unpin>(&self, stream: &mut S) -> Result<(), ConnectError> {
         let mut buf = BytesMut::new();
-        self.encode(&mut buf);
+        self.encode(&mut buf)?;
         stream.write_all_buf(&mut buf).await?;
         Ok(())
     }
 }
 
-#[derive(Debug)]
+impl From<Url> for ConnectRequest {
+    fn from(url: Url) -> Self {
+        Self {
+            url,
+            protocols: Vec::new(),
+        }
+    }
+}
+
+/// A CONNECT response to accept or reject a WebTransport session.
+#[non_exhaustive]
+#[derive(Debug, Clone)]
 pub struct ConnectResponse {
+    /// The status code of the response.
     pub status: http::status::StatusCode,
+
+    /// The subprotocol selected by the server, if any
+    pub protocol: Option<String>,
 }
 
 impl ConnectResponse {
+    pub fn new(status: http::StatusCode) -> Self {
+        Self {
+            status,
+            protocol: None,
+        }
+    }
+
+    pub fn with_protocol(mut self, protocol: impl Into<String>) -> Self {
+        self.protocol = Some(protocol.into());
+        self
+    }
+
     pub fn decode<B: Buf>(buf: &mut B) -> Result<Self, ConnectError> {
         let (typ, mut data) = Frame::read(buf).map_err(|_| ConnectError::UnexpectedEnd)?;
         if typ != Frame::HEADERS {
@@ -178,7 +258,13 @@ impl ConnectResponse {
             o => return Err(ConnectError::WrongStatus(o)),
         };
 
-        Ok(Self { status })
+        let protocol = headers
+            .get(protocol_negotiation::SELECTED_NAME)
+            .map(protocol_negotiation::decode_item)
+            .transpose()
+            .map_err(|_| ConnectError::InvalidProtocol)?;
+
+        Ok(Self { status, protocol })
     }
 
     pub async fn read<S: AsyncRead + Unpin>(stream: &mut S) -> Result<Self, ConnectError> {
@@ -197,11 +283,16 @@ impl ConnectResponse {
         }
     }
 
-    pub fn encode<B: BufMut>(&self, buf: &mut B) {
+    pub fn encode<B: BufMut>(&self, buf: &mut B) -> Result<(), ConnectError> {
         let mut headers = qpack::Headers::default();
         headers.set(":status", self.status.as_str());
         headers.set("sec-webtransport-http3-draft", "draft02");
 
+        if let Some(protocol) = self.protocol.as_ref() {
+            let encoded = protocol_negotiation::encode_item(protocol)?;
+            headers.set(protocol_negotiation::SELECTED_NAME, &encoded);
+        }
+
         // Use a temporary buffer so we can compute the size.
         let mut tmp = Vec::new();
         headers.encode(&mut tmp);
@@ -210,12 +301,82 @@ impl ConnectResponse {
         Frame::HEADERS.encode(buf);
         size.encode(buf);
         buf.put_slice(&tmp);
+
+        Ok(())
     }
 
     pub async fn write<S: AsyncWrite + Unpin>(&self, stream: &mut S) -> Result<(), ConnectError> {
         let mut buf = BytesMut::new();
-        self.encode(&mut buf);
+        self.encode(&mut buf)?;
         stream.write_all_buf(&mut buf).await?;
         Ok(())
     }
 }
+
+impl From<http::StatusCode> for ConnectResponse {
+    fn from(status: http::StatusCode) -> Self {
+        Self {
+            status,
+            protocol: None,
+        }
+    }
+}
+
+mod protocol_negotiation {
+    //! WebTransport sub-protocol negotiation using RFC 8941 Structured Fields,
+    //!
+    //! according to [draft 14](https://www.ietf.org/archive/id/draft-ietf-webtrans-http3-14.html#section-3.3)
+
+    use sfv::{Item, ItemSerializer, List, ListEntry, ListSerializer, Parser, StringRef};
+
+    use crate::ConnectError;
+
+    /// The header name for the available protocols, sent within the WebTransport Connect request.
+    pub const AVAILABLE_NAME: &str = "wt-available-protocols";
+    /// The header name for the selected protocol, sent within the WebTransport Connect response.
+    pub const SELECTED_NAME: &str = "wt-protocol";
+
+    /// Encode a list of protocol strings as an RFC 8941 Structured Field List.
+    pub fn encode_list(protocols: &[String]) -> Result<String, ConnectError> {
+        let mut serializer = ListSerializer::new();
+        for protocol in protocols {
+            let s = StringRef::from_str(protocol)?;
+            let _ = serializer.bare_item(s);
+        }
+        serializer.finish().ok_or(ConnectError::InvalidProtocol)
+    }
+
+    /// Decode an RFC 8941 Structured Field List of strings.
+    pub fn decode_list(value: &str) -> Result<Vec<String>, ConnectError> {
+        let list = Parser::new(value).parse::<List>()?;
+
+        list.iter()
+            .map(|entry| match entry {
+                ListEntry::Item(item) => Ok(item
+                    .bare_item
+                    .as_string()
+                    .ok_or(ConnectError::InvalidProtocol)?
+                    .as_str()
+                    .to_string()),
+                _ => Err(ConnectError::InvalidProtocol),
+            })
+            .collect()
+    }
+
+    /// Encode a single string as an RFC 8941 Structured Field Item.
+    pub fn encode_item(protocol: &str) -> Result<String, ConnectError> {
+        let s = StringRef::from_str(protocol)?;
+        Ok(ItemSerializer::new().bare_item(s).finish())
+    }
+
+    /// Decode an RFC 8941 Structured Field Item (single string).
+    pub fn decode_item(value: &str) -> Result<String, ConnectError> {
+        let item = Parser::new(value).parse::<Item>()?;
+        Ok(item
+            .bare_item
+            .as_string()
+            .ok_or(ConnectError::InvalidProtocol)?
+            .as_str()
+            .to_string())
+    }
+}

web-transport-quiche/examples/echo-server.rs

@@ -71,7 +71,10 @@ async fn run_conn(request: web_transport_quiche::h3::Request) -> anyhow::Result<
     tracing::info!("received WebTransport request: {}", request.url());
 
     // Accept the session.
-    let session = request.ok().await.context("failed to accept session")?;
+    let session = request
+        .respond(http::StatusCode::OK)
+        .await
+        .context("failed to accept session")?;
     tracing::info!("accepted session");
 
     loop {

web-transport-quiche/src/h3/connect.rs

@@ -1,4 +1,4 @@
-use web_transport_proto::{ConnectRequest, ConnectResponse, VarInt};
+use crate::proto::{ConnectRequest, ConnectResponse, VarInt};
 
 use thiserror::Error;
 use url::Url;
@@ -59,8 +59,11 @@ impl Connect {
     /// Send an HTTP/3 CONNECT response to the client.
     ///
     /// This is called by the server to accept or reject the connection.
-    pub async fn respond(&mut self, status: http::StatusCode) -> Result<(), ConnectError> {
-        let response = ConnectResponse { status };
+    pub async fn respond(
+        &mut self,
+        response: impl Into<ConnectResponse>,
+    ) -> Result<(), ConnectError> {
+        let response = response.into();
         tracing::debug!(?response, "sending CONNECT");
         response.write(&mut self.send).await?;
 
@@ -70,14 +73,17 @@ impl Connect {
     /// Send an HTTP/3 CONNECT request to the server and wait for the response.
     ///
     /// This is called by the client to initiate a WebTransport session.
-    pub async fn open(conn: &ez::Connection, url: Url) -> Result<Self, ConnectError> {
+    pub async fn open(
+        conn: &ez::Connection,
+        request: impl Into<ConnectRequest>,
+    ) -> Result<Self, ConnectError> {
         tracing::debug!("opening bi");
 
         // Create a new stream that will be used to send the CONNECT frame.
         let (mut send, mut recv) = conn.open_bi().await?;
 
         // Create a new CONNECT request that we'll send using HTTP/3
-        let request = ConnectRequest { url };
+        let request = request.into();
 
         tracing::debug!(?request, "sending CONNECT");
         request.write(&mut send).await?;

web-transport-quiche/src/h3/request.rs

@@ -1,6 +1,6 @@
 use url::Url;
 
-use crate::{ez, h3, Connection, ServerError};
+use crate::{ez, h3, proto::ConnectResponse, Connection, ServerError};
 
 /// A mostly complete WebTransport handshake, just awaiting the server's decision on whether to accept or reject the session based on the URL.
 pub struct Request {
@@ -32,8 +32,11 @@ impl Request {
     }
 
     /// Accept the session, returning a 200 OK.
-    pub async fn ok(mut self) -> Result<Connection, ServerError> {
-        self.connect.respond(http::StatusCode::OK).await?;
+    pub async fn respond(
+        mut self,
+        response: impl Into<ConnectResponse>,
+    ) -> Result<Connection, ServerError> {
+        self.connect.respond(response.into()).await?;
         Ok(Connection::new(self.conn, self.settings, self.connect))
     }