Support Safari/Network.framework hybrid WebTransport negotiation and initial flow-control capsules

Version

h3-webtransport 0.1.2

Platform

macOS 26

Summary

Safari 26.4+ and Cocoa WebKit builds using Apple's Network.framework cannot establish a usable WebTransport session with an h3-webtransport server. In our macOS 26 CI, WebTransport.ready never resolves and the browser eventually reports:

TrevRpcError: DeadlineExceeded: initial connection deadline exceeded

The same browser client completes unary, client-streaming, server-streaming, and bidirectional RPCs against C, C++, JavaScript, and Kotlin WebTransport servers. All four modes fail before measurement against the Rust server using h3-webtransport.

This appears to be an interoperability gap with the hybrid WebTransport dialect exposed by Network.framework, rather than a TLS, QUIC, certificate, origin, or application-protocol problem.

Code Sample

1. Configure an h3 server with extended CONNECT, datagrams, and WebTransport enabled:

   let mut builder = h3::server::builder();
   builder
       .enable_extended_connect(true)
       .enable_datagram(true)
       .enable_webtransport(true)
       .max_webtransport_sessions(1);
   

2. Accept the extended CONNECT request with WebTransportSession::accept.

3. From Safari 26.4+ or Playwright Cocoa WebKit on macOS 26, connect with:

   const transport = new WebTransport(url, {
     serverCertificateHashes: certificateHashes,
   });
   await transport.ready;
   

4. Observe that readiness does not complete. If readiness completes with a partially compatible SETTINGS response, createBidirectionalStream() remains pending instead.

This reproduces with a loopback address, a valid short-lived certificate hash, and an exact allowed Origin. The same setup succeeds against servers implementing the Network.framework compatibility path.

Expected Behavior

Server-side support for Network.framework's hybrid WebTransport negotiation

Actual Behavior

WebTransport fails for Safari 26.4+ and Cocoa WebKit builds using Apple's Network.framework

Additional Context

The Cocoa client sends a hybrid SETTINGS set containing:

Setting	Codepoint	Value
H3_DATAGRAM	0x33	1
draft-07 WebTransport max sessions	0xc671706a	1
draft-14 WT_MAX_SESSIONS	0x14e9cd29	1
WT_INITIAL_MAX_DATA	0x2b61	8 * 1024 * 1024
WT_INITIAL_MAX_STREAMS_UNI	0x2b64	100
WT_INITIAL_MAX_STREAMS_BIDI	0x2b65	100

It does not advertise the draft-15 WT_ENABLED setting at 0x2c7cf000.

A server that interoperates with this client must select the compatible legacy behavior and grant initial session flow control on the CONNECT stream. The working implementation sends HTTP/3 DATA frames containing these capsules after the successful CONNECT response:

Capsule	Codepoint
WT_MAX_DATA	0x190b4d3d
WT_MAX_STREAMS_BIDI	0x190b4d3f
WT_MAX_STREAMS_UNI	0x190b4d40

Without those grants, Network.framework does not make the session's bidirectional streams usable.

Start at the h3 server builder options and WebTransportSession::accept path, then trace extended CONNECT negotiation and the CONNECT stream. Reproduce with Safari 26.4+ or Cocoa WebKit using the shown settings, and compare the session behavior with the listed Network.framework compatibility path. Done means the session becomes usable, including bidirectional streams, after the expected negotiation and initial flow-control grants.