rwebtransport 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -43,11 +43,25 @@ const SERVER_FIRST_WT_UNI_ID: u64 = 15;
43
43
  /// hostile peer advertising a huge length).
44
44
  const MAX_CONTROL_FRAME: usize = 1 << 20;
45
45
 
46
+ /// Per-session flow-control credit we grant the peer once established. Large,
47
+ /// because QUIC's connection flow control is the real limit (one session per
48
+ /// connection); this only keeps a strict peer from stalling on our advertised
49
+ /// per-session limits while QUIC does the actual enforcement.
50
+ const WT_GRANT_MAX_DATA: u64 = 1 << 34;
51
+ const WT_GRANT_MAX_STREAMS: u64 = 1 << 20;
52
+
46
53
  /// Events the session emits for the driver to forward to JS.
47
54
  #[derive(Debug)]
48
55
  pub enum Ev {
49
56
  /// The WebTransport session is established (client role: CONNECT got a 2xx).
50
- Ready,
57
+ /// Carries the negotiated subprotocol (if any) and the response headers.
58
+ Ready {
59
+ protocol: Option<String>,
60
+ headers: Vec<(String, String)>,
61
+ },
62
+ /// The peer sent DRAIN_WEBTRANSPORT_SESSION: it intends to close soon, but
63
+ /// the session and its streams stay usable until an actual close.
64
+ Draining,
51
65
  /// A server-role session was established: a valid Extended CONNECT arrived
52
66
  /// and we answered 200. Carries the request details for the application.
53
67
  ServerReady {
@@ -55,6 +69,10 @@ pub enum Ev {
55
69
  path: String,
56
70
  origin: Option<String>,
57
71
  headers: Vec<(String, String)>,
72
+ /// The subprotocols the client offered (in `wt-available-protocols`).
73
+ requested_protocols: Vec<String>,
74
+ /// The subprotocol the server selected (echoed in `wt-protocol`), if any.
75
+ protocol: Option<String>,
58
76
  /// The client's remote IP (as a string) at session establishment.
59
77
  remote_addr: String,
60
78
  /// The client's remote UDP port at session establishment.
@@ -86,6 +104,68 @@ pub enum Ev {
86
104
  WriteAck { request_id: u64 },
87
105
  /// A datagram send request was processed (sent or intentionally dropped).
88
106
  DatagramAck { request_id: u64, sent: bool },
107
+ /// Result of a getStats() request.
108
+ Stats {
109
+ request_id: u64,
110
+ bytes_sent: u64,
111
+ bytes_received: u64,
112
+ packets_sent: u64,
113
+ packets_received: u64,
114
+ packets_lost: u64,
115
+ smoothed_rtt_ms: f64,
116
+ rtt_variation_ms: f64,
117
+ min_rtt_ms: f64,
118
+ },
119
+ /// Result of an exportKeyingMaterial() request: the exported bytes, or
120
+ /// `None` if the TLS export failed (for example, before the handshake).
121
+ KeyingMaterial {
122
+ request_id: u64,
123
+ data: Option<Vec<u8>>,
124
+ },
125
+ }
126
+
127
+ /// Snapshot a quiche connection's stats into a [`Ev::Stats`] for `request_id`.
128
+ pub fn build_stats(conn: &quiche::Connection, request_id: u64) -> Ev {
129
+ let s = conn.stats();
130
+ let to_ms = |d: std::time::Duration| d.as_secs_f64() * 1000.0;
131
+ let (rtt, min_rtt, rttvar) = match conn.path_stats().next() {
132
+ Some(p) => (p.rtt, p.min_rtt.unwrap_or(p.rtt), p.rttvar),
133
+ None => (
134
+ std::time::Duration::ZERO,
135
+ std::time::Duration::ZERO,
136
+ std::time::Duration::ZERO,
137
+ ),
138
+ };
139
+ Ev::Stats {
140
+ request_id,
141
+ bytes_sent: s.sent_bytes,
142
+ bytes_received: s.recv_bytes,
143
+ packets_sent: s.sent as u64,
144
+ packets_received: s.recv as u64,
145
+ packets_lost: s.lost as u64,
146
+ smoothed_rtt_ms: to_ms(rtt),
147
+ rtt_variation_ms: to_ms(rttvar),
148
+ min_rtt_ms: to_ms(min_rtt),
149
+ }
150
+ }
151
+
152
+ /// Export `length` bytes of TLS keying material (RFC 5705) into a
153
+ /// [`Ev::KeyingMaterial`] for `request_id`. `data` is `None` if the export
154
+ /// failed. WebTransport always supplies a context, so it is passed through even
155
+ /// when empty (an empty context differs from no context per RFC 5705).
156
+ pub fn build_keying_material(
157
+ conn: &mut quiche::Connection,
158
+ request_id: u64,
159
+ label: &[u8],
160
+ context: &[u8],
161
+ length: u32,
162
+ ) -> Ev {
163
+ let mut out = vec![0u8; length as usize];
164
+ let data = match conn.export_keying_material(&mut out, label, Some(context)) {
165
+ Ok(()) => Some(out),
166
+ Err(_) => None,
167
+ };
168
+ Ev::KeyingMaterial { request_id, data }
89
169
  }
90
170
 
91
171
  /// One queued outbound chunk on a stream.
@@ -211,6 +291,16 @@ pub struct WtSession {
211
291
  path: String,
212
292
  origin: Option<String>,
213
293
  extra_headers: Vec<(String, String)>,
294
+ /// Client role: WebTransport subprotocols we offer (preference order).
295
+ protocols: Vec<String>,
296
+ /// Server role: subprotocols we support (preference order); the first that
297
+ /// the client also offers is selected. Empty means no negotiation.
298
+ supported_protocols: Vec<String>,
299
+ /// Server role: if `Some`, only Extended CONNECTs whose `origin` is in this
300
+ /// list are accepted (others are rejected with 403). `None` allows any.
301
+ allowed_origins: Option<Vec<String>>,
302
+ /// Server role: extra headers to add to the 200 CONNECT response.
303
+ response_headers: Vec<(String, String)>,
214
304
 
215
305
  next_bidi: u64,
216
306
  next_uni: u64,
@@ -218,6 +308,35 @@ pub struct WtSession {
218
308
  setup_sent: bool,
219
309
  ready: bool,
220
310
  closed: bool,
311
+ /// Client role only: the Extended CONNECT is built but deferred until the
312
+ /// server's SETTINGS confirm WebTransport support (see parse_control_frames).
313
+ connect_pending: bool,
314
+ /// Set once a DRAIN_WEBTRANSPORT_SESSION capsule has been surfaced, so the
315
+ /// `Draining` event is emitted at most once.
316
+ drain_emitted: bool,
317
+ /// Set once we have queued an outbound DRAIN capsule, so we send at most one.
318
+ drain_sent: bool,
319
+ /// Set once we granted the peer per-session flow-control credit.
320
+ fc_credit_granted: bool,
321
+ /// Peer's send-side session limits (from SETTINGS_WT_INITIAL_* and WT_MAX_*
322
+ /// capsules). QUIC performs the actual send enforcement under the
323
+ /// one-session-per-connection model; these drive only the WT_*_BLOCKED
324
+ /// signaling below.
325
+ fc_max_data_remote: u64,
326
+ fc_max_streams_bidi_remote: u64,
327
+ fc_max_streams_uni_remote: u64,
328
+ /// Cumulative WebTransport stream payload bytes handed to quiche, compared
329
+ /// against `fc_max_data_remote` to detect a WT_DATA_BLOCKED condition.
330
+ fc_data_sent: u64,
331
+ /// The WT_MAX_DATA / WT_MAX_STREAMS_* limit value we last announced as blocked
332
+ /// at (0 = none), so a BLOCKED capsule is re-sent only when the limit changes.
333
+ data_blocked_at: u64,
334
+ streams_bidi_blocked_at: u64,
335
+ streams_uni_blocked_at: u64,
336
+ /// Reassembly buffer for capsules on the session (CONNECT) stream: RFC 9297
337
+ /// lets a capsule span multiple HTTP/3 DATA frames, so bytes are accumulated
338
+ /// here and only whole capsules are consumed.
339
+ capsule_buf: Vec<u8>,
221
340
 
222
341
  peer_settings: Option<h3::PeerSettings>,
223
342
 
@@ -226,6 +345,12 @@ pub struct WtSession {
226
345
  close_req: Option<CloseReq>,
227
346
  /// Set once the QUIC connection should be closed (after connect FIN flush).
228
347
  want_quic_close: Option<(u32, Vec<u8>)>,
348
+ /// True once the QUIC close has been deferred one flush pass, so the queued
349
+ /// CLOSE_WEBTRANSPORT_SESSION capsule + FIN are serialized to the wire before
350
+ /// the CONNECTION_CLOSE frame supersedes all stream frames.
351
+ close_deferred_once: bool,
352
+ /// True once we have issued the graceful QUIC close, so it happens once.
353
+ quic_close_issued: bool,
229
354
  /// Server role only: the client's remote address, captured when the
230
355
  /// connection was accepted and surfaced on the `serverReady` event.
231
356
  remote_addr: Option<std::net::SocketAddr>,
@@ -238,6 +363,7 @@ impl WtSession {
238
363
  path: String,
239
364
  origin: Option<String>,
240
365
  extra_headers: Vec<(String, String)>,
366
+ protocols: Vec<String>,
241
367
  ) -> Self {
242
368
  Self {
243
369
  is_server: false,
@@ -245,15 +371,33 @@ impl WtSession {
245
371
  path,
246
372
  origin,
247
373
  extra_headers,
374
+ protocols,
375
+ supported_protocols: Vec::new(),
376
+ allowed_origins: None,
377
+ response_headers: Vec::new(),
248
378
  next_bidi: CLIENT_FIRST_WT_BIDI_ID,
249
379
  next_uni: CLIENT_FIRST_WT_UNI_ID,
250
380
  setup_sent: false,
251
381
  ready: false,
252
382
  closed: false,
383
+ connect_pending: false,
384
+ drain_emitted: false,
385
+ drain_sent: false,
386
+ fc_credit_granted: false,
387
+ fc_max_data_remote: 0,
388
+ fc_max_streams_bidi_remote: 0,
389
+ fc_max_streams_uni_remote: 0,
390
+ fc_data_sent: 0,
391
+ data_blocked_at: 0,
392
+ streams_bidi_blocked_at: 0,
393
+ streams_uni_blocked_at: 0,
394
+ capsule_buf: Vec::new(),
253
395
  peer_settings: None,
254
396
  streams: HashMap::new(),
255
397
  close_req: None,
256
398
  want_quic_close: None,
399
+ close_deferred_once: false,
400
+ quic_close_issued: false,
257
401
  remote_addr: None,
258
402
  }
259
403
  }
@@ -261,22 +405,45 @@ impl WtSession {
261
405
  /// A server-role session that will accept an incoming Extended CONNECT.
262
406
  /// `remote` is the client's address, surfaced to the application via the
263
407
  /// `serverReady` event.
264
- pub fn new_server(remote: std::net::SocketAddr) -> Self {
408
+ pub fn new_server(
409
+ remote: std::net::SocketAddr,
410
+ supported_protocols: Vec<String>,
411
+ allowed_origins: Option<Vec<String>>,
412
+ response_headers: Vec<(String, String)>,
413
+ ) -> Self {
265
414
  Self {
266
415
  is_server: true,
267
416
  authority: String::new(),
268
417
  path: String::new(),
269
418
  origin: None,
270
419
  extra_headers: Vec::new(),
420
+ protocols: Vec::new(),
421
+ supported_protocols,
422
+ allowed_origins,
423
+ response_headers,
271
424
  next_bidi: SERVER_FIRST_WT_BIDI_ID,
272
425
  next_uni: SERVER_FIRST_WT_UNI_ID,
273
426
  setup_sent: false,
274
427
  ready: false,
275
428
  closed: false,
429
+ connect_pending: false,
430
+ drain_emitted: false,
431
+ drain_sent: false,
432
+ fc_credit_granted: false,
433
+ fc_max_data_remote: 0,
434
+ fc_max_streams_bidi_remote: 0,
435
+ fc_max_streams_uni_remote: 0,
436
+ fc_data_sent: 0,
437
+ data_blocked_at: 0,
438
+ streams_bidi_blocked_at: 0,
439
+ streams_uni_blocked_at: 0,
440
+ capsule_buf: Vec::new(),
276
441
  peer_settings: None,
277
442
  streams: HashMap::new(),
278
443
  close_req: None,
279
444
  want_quic_close: None,
445
+ close_deferred_once: false,
446
+ quic_close_issued: false,
280
447
  remote_addr: Some(remote),
281
448
  }
282
449
  }
@@ -289,7 +456,7 @@ impl WtSession {
289
456
  /// control-plane streams and advertise SETTINGS. A client also sends the
290
457
  /// Extended CONNECT immediately; a server waits for the client's CONNECT on
291
458
  /// bidi stream 0.
292
- pub fn on_established(&mut self, ev: &mut Vec<Ev>) {
459
+ pub fn on_established(&mut self) {
293
460
  if self.setup_sent {
294
461
  return;
295
462
  }
@@ -321,20 +488,10 @@ impl WtSession {
321
488
  );
322
489
 
323
490
  if !self.is_server {
324
- // CONNECT request on the session (bidi 0) stream.
325
- let headers = h3::connect_headers(
326
- &self.authority,
327
- &self.path,
328
- self.origin.as_deref(),
329
- &self.extra_headers,
330
- );
331
- match h3::encode_headers_frame(&headers) {
332
- Ok(frame) => {
333
- self.streams
334
- .insert(CONNECT_ID, Stream::with_prefix(Role::Connect, frame));
335
- }
336
- Err(e) => ev.push(Ev::Error(format!("failed to encode CONNECT: {e}"))),
337
- }
491
+ // Per draft-ietf-webtrans-http3 §3.1 the client MUST NOT send the
492
+ // Extended CONNECT until it has received the server's SETTINGS and
493
+ // confirmed WebTransport support. Defer it to parse_control_frames.
494
+ self.connect_pending = true;
338
495
  }
339
496
  if dbg_on() {
340
497
  eprintln!(
@@ -410,7 +567,12 @@ impl WtSession {
410
567
  st.recv_dead = true;
411
568
  }
412
569
  match role {
413
- Some(Role::WtData { .. }) => ev.push(Ev::StreamReset { id, code }),
570
+ Some(Role::WtData { .. }) => {
571
+ // Map the HTTP/3 reset code back to the WebTransport
572
+ // application code; pass unmapped codes through unchanged.
573
+ let app = h3::http_code_to_webtransport_code(code).unwrap_or(code);
574
+ ev.push(Ev::StreamReset { id, code: app })
575
+ }
414
576
  Some(Role::Connect) if !self.closed => {
415
577
  // A reset of the session (CONNECT) stream ends the session;
416
578
  // if we swallowed it, ready/closed would hang forever.
@@ -466,7 +628,7 @@ impl WtSession {
466
628
  if let Some(st) = self.streams.get_mut(&id) {
467
629
  st.frames.push(&chunk);
468
630
  }
469
- self.parse_control_frames(id);
631
+ self.parse_control_frames(id, ev);
470
632
  // A malformed control stream is a fatal H3 error; stop reading it
471
633
  // so a hostile server cannot keep us draining (and re-crediting)
472
634
  // an oversized frame into an unbounded buffer.
@@ -518,7 +680,7 @@ impl WtSession {
518
680
  }
519
681
  }
520
682
 
521
- fn parse_control_frames(&mut self, id: u64) {
683
+ fn parse_control_frames(&mut self, id: u64, ev: &mut Vec<Ev>) {
522
684
  loop {
523
685
  let frame = self
524
686
  .streams
@@ -526,8 +688,52 @@ impl WtSession {
526
688
  .and_then(|s| s.frames.next_frame());
527
689
  let Some((ty, payload)) = frame else { break };
528
690
  if ty == h3::FRAME_SETTINGS {
529
- self.peer_settings = Some(h3::parse_settings(&payload));
691
+ let settings = h3::parse_settings(&payload);
692
+ self.peer_settings = Some(settings);
693
+ // Seed the peer's per-session flow-control limits from its SETTINGS.
694
+ self.fc_max_data_remote = settings.wt_initial_max_data;
695
+ self.fc_max_streams_bidi_remote = settings.wt_initial_max_streams_bidi;
696
+ self.fc_max_streams_uni_remote = settings.wt_initial_max_streams_uni;
697
+ // The client deferred its Extended CONNECT until it saw the
698
+ // server's SETTINGS: now send it if WebTransport is supported,
699
+ // otherwise reject the session.
700
+ if self.connect_pending {
701
+ self.connect_pending = false;
702
+ if settings.webtransport_ok() {
703
+ self.queue_connect(ev);
704
+ } else {
705
+ ev.push(Ev::Error(
706
+ "server does not advertise WebTransport support".to_string(),
707
+ ));
708
+ self.mark_closed(ev, 0, b"webtransport not supported".to_vec(), false);
709
+ }
710
+ }
711
+ } else if ty == h3::FRAME_GOAWAY && !self.drain_emitted && !self.closed {
712
+ // The peer is gracefully shutting down the HTTP/3 connection.
713
+ // Exactly one WebTransport session rides it, so surface GOAWAY as
714
+ // the session draining (going away soon, still usable).
715
+ self.drain_emitted = true;
716
+ ev.push(Ev::Draining);
717
+ }
718
+ }
719
+ }
720
+
721
+ /// Build and queue the client's Extended CONNECT on the session (bidi 0)
722
+ /// stream. Called once the server's SETTINGS have confirmed WebTransport.
723
+ fn queue_connect(&mut self, ev: &mut Vec<Ev>) {
724
+ let headers = h3::connect_headers(
725
+ &self.authority,
726
+ &self.path,
727
+ self.origin.as_deref(),
728
+ &self.extra_headers,
729
+ &self.protocols,
730
+ );
731
+ match h3::encode_headers_frame(&headers) {
732
+ Ok(frame) => {
733
+ self.streams
734
+ .insert(CONNECT_ID, Stream::with_prefix(Role::Connect, frame));
530
735
  }
736
+ Err(e) => ev.push(Ev::Error(format!("failed to encode CONNECT: {e}"))),
531
737
  }
532
738
  }
533
739
 
@@ -557,7 +763,12 @@ impl WtSession {
557
763
  if (200..300).contains(&status) {
558
764
  if !self.ready {
559
765
  self.ready = true;
560
- ev.push(Ev::Ready);
766
+ let protocol = h3::wt_protocol_of(&headers);
767
+ let resp_headers = h3::response_headers(&headers);
768
+ ev.push(Ev::Ready {
769
+ protocol,
770
+ headers: resp_headers,
771
+ });
561
772
  }
562
773
  } else {
563
774
  ev.push(Ev::Error(format!(
@@ -578,32 +789,58 @@ impl WtSession {
578
789
  }
579
790
  }
580
791
 
581
- fn scan_capsules(&mut self, mut buf: &[u8], ev: &mut Vec<Ev>) {
582
- while !buf.is_empty() {
583
- let Some((ty, n1)) = h3::read_varint(buf) else {
584
- break;
585
- };
586
- let Some((len, n2)) = h3::read_varint(&buf[n1..]) else {
587
- break;
792
+ fn scan_capsules(&mut self, payload: &[u8], ev: &mut Vec<Ev>) {
793
+ // A capsule may span multiple HTTP/3 DATA frames (RFC 9297), so append
794
+ // this frame's payload and consume only whole capsules from the buffer.
795
+ self.capsule_buf.extend_from_slice(payload);
796
+ loop {
797
+ let (ty, start, len) = {
798
+ let buf = &self.capsule_buf;
799
+ let Some((ty, n1)) = h3::read_varint(buf) else {
800
+ break;
801
+ };
802
+ let Some((len, n2)) = h3::read_varint(&buf[n1..]) else {
803
+ break;
804
+ };
805
+ (ty, n1 + n2, len as usize)
588
806
  };
589
- let len = len as usize;
590
- let start = n1 + n2;
591
- if buf.len() < start + len {
807
+ // Guard against a hostile/oversized declared length.
808
+ if len > MAX_CONTROL_FRAME {
809
+ self.capsule_buf.clear();
592
810
  break;
593
811
  }
594
- let value = &buf[start..start + len];
812
+ if self.capsule_buf.len() < start + len {
813
+ break; // capsule not fully arrived; wait for the next DATA frame
814
+ }
815
+ let value: Vec<u8> = self.capsule_buf[start..start + len].to_vec();
816
+ self.capsule_buf.drain(..start + len);
817
+
595
818
  if ty == h3::WT_CLOSE_SESSION_CAPSULE && !self.closed {
596
819
  let (code, reason) = if value.len() >= 4 {
597
820
  (
598
821
  u32::from_be_bytes([value[0], value[1], value[2], value[3]]),
599
- value[4..].to_vec(),
822
+ h3::truncate_close_reason(value[4..].to_vec()),
600
823
  )
601
824
  } else {
602
825
  (0, Vec::new())
603
826
  };
604
827
  self.mark_closed(ev, code, reason, true);
828
+ } else if ty == h3::WT_DRAIN_SESSION_CAPSULE && !self.drain_emitted && !self.closed {
829
+ self.drain_emitted = true;
830
+ ev.push(Ev::Draining);
831
+ } else if ty == h3::WT_MAX_DATA_CAPSULE {
832
+ if let Some((v, _)) = h3::read_varint(&value) {
833
+ self.fc_max_data_remote = self.fc_max_data_remote.max(v);
834
+ }
835
+ } else if ty == h3::WT_MAX_STREAMS_BIDI_CAPSULE {
836
+ if let Some((v, _)) = h3::read_varint(&value) {
837
+ self.fc_max_streams_bidi_remote = self.fc_max_streams_bidi_remote.max(v);
838
+ }
839
+ } else if ty == h3::WT_MAX_STREAMS_UNI_CAPSULE {
840
+ if let Some((v, _)) = h3::read_varint(&value) {
841
+ self.fc_max_streams_uni_remote = self.fc_max_streams_uni_remote.max(v);
842
+ }
605
843
  }
606
- buf = &buf[start + len..];
607
844
  }
608
845
  }
609
846
 
@@ -654,6 +891,7 @@ impl WtSession {
654
891
  let mut authority = String::new();
655
892
  let mut path = String::from("/");
656
893
  let mut origin: Option<String> = None;
894
+ let mut requested_protocols: Vec<String> = Vec::new();
657
895
  let mut extra: Vec<(String, String)> = Vec::new();
658
896
  for h in headers {
659
897
  let name = h.name();
@@ -664,6 +902,9 @@ impl WtSession {
664
902
  b":authority" => authority = String::from_utf8_lossy(value).into_owned(),
665
903
  b":path" => path = String::from_utf8_lossy(value).into_owned(),
666
904
  b"origin" => origin = Some(String::from_utf8_lossy(value).into_owned()),
905
+ _ if name == h3::WT_AVAILABLE_PROTOCOLS => {
906
+ requested_protocols = h3::parse_sf_string_list(&String::from_utf8_lossy(value));
907
+ }
667
908
  _ if name.starts_with(b":") => {} // other pseudo-headers
668
909
  _ => extra.push((
669
910
  String::from_utf8_lossy(name).into_owned(),
@@ -678,8 +919,41 @@ impl WtSession {
678
919
  return;
679
920
  }
680
921
 
681
- let resp = vec![quiche::h3::Header::new(b":status", b"200")];
682
- match h3::encode_headers_frame(&resp) {
922
+ // Origin verification (draft-ietf-webtrans-http3 3.3): if an allowlist is
923
+ // configured, the request's origin must be present in it.
924
+ if let Some(allowed) = &self.allowed_origins {
925
+ let permitted = origin
926
+ .as_deref()
927
+ .map(|o| allowed.iter().any(|a| a == o))
928
+ .unwrap_or(false);
929
+ if !permitted {
930
+ self.reject_connect(conn, id, 403, ev);
931
+ return;
932
+ }
933
+ }
934
+
935
+ // Select the first supported subprotocol that the client also offered.
936
+ let selected: Option<String> = self
937
+ .supported_protocols
938
+ .iter()
939
+ .find(|p| requested_protocols.iter().any(|r| r == *p))
940
+ .cloned();
941
+
942
+ // Build the 200 response: :status, the selected wt-protocol (if any), and
943
+ // any configured static response headers. Scoped so the borrows of
944
+ // `self.response_headers` and `selected` end before the stream mutation.
945
+ let selected_ser = selected.as_ref().map(|p| h3::serialize_sf_string(p));
946
+ let encoded = {
947
+ let mut resp = vec![quiche::h3::Header::new(b":status", b"200")];
948
+ if let Some(val) = &selected_ser {
949
+ resp.push(quiche::h3::Header::new(h3::WT_PROTOCOL, val.as_bytes()));
950
+ }
951
+ for (k, v) in &self.response_headers {
952
+ resp.push(quiche::h3::Header::new(k.as_bytes(), v.as_bytes()));
953
+ }
954
+ h3::encode_headers_frame(&resp)
955
+ };
956
+ match encoded {
683
957
  Ok(frame) => {
684
958
  if let Some(st) = self.streams.get_mut(&id) {
685
959
  st.out.push_back(OutChunk {
@@ -698,6 +972,8 @@ impl WtSession {
698
972
  path,
699
973
  origin,
700
974
  headers: extra,
975
+ requested_protocols,
976
+ protocol: selected,
701
977
  remote_addr,
702
978
  remote_port,
703
979
  });
@@ -748,6 +1024,11 @@ impl WtSession {
748
1024
  st.class_buf.clone()
749
1025
  };
750
1026
  let Some((ty, n)) = h3::read_varint(&buf) else {
1027
+ // Peer FIN'd before we could classify: no more bytes will ever
1028
+ // arrive, so drop the entry rather than leak a Pending stream.
1029
+ if fin {
1030
+ self.streams.remove(&id);
1031
+ }
751
1032
  return; // need more bytes for the type varint
752
1033
  };
753
1034
  match ty {
@@ -759,7 +1040,7 @@ impl WtSession {
759
1040
  st.role = Role::PeerControl;
760
1041
  st.class_buf.clear();
761
1042
  st.frames.push(&rest);
762
- self.parse_control_frames(id);
1043
+ self.parse_control_frames(id, ev);
763
1044
  }
764
1045
  t if t == h3::QPACK_ENCODER_STREAM_TYPE || t == h3::QPACK_DECODER_STREAM_TYPE => {
765
1046
  let Some(st) = self.streams.get_mut(&id) else {
@@ -770,6 +1051,10 @@ impl WtSession {
770
1051
  }
771
1052
  t if t == h3::WT_UNI_STREAM_TYPE => {
772
1053
  let Some((session, n2)) = h3::read_varint(&buf[n..]) else {
1054
+ // Peer FIN'd mid-header: reclaim the entry instead of leaking.
1055
+ if fin {
1056
+ self.streams.remove(&id);
1057
+ }
773
1058
  return; // need session id
774
1059
  };
775
1060
  if session != CONNECT_ID {
@@ -826,6 +1111,10 @@ impl WtSession {
826
1111
  st.class_buf.clone()
827
1112
  };
828
1113
  let Some((signal, n)) = h3::read_varint(&buf) else {
1114
+ // Peer FIN'd before we could classify: reclaim the entry.
1115
+ if fin {
1116
+ self.streams.remove(&id);
1117
+ }
829
1118
  return;
830
1119
  };
831
1120
  if signal != h3::WT_BIDI_FRAME_TYPE {
@@ -838,6 +1127,10 @@ impl WtSession {
838
1127
  return;
839
1128
  }
840
1129
  let Some((session, n2)) = h3::read_varint(&buf[n..]) else {
1130
+ // Peer FIN'd mid-header: reclaim the entry instead of leaking.
1131
+ if fin {
1132
+ self.streams.remove(&id);
1133
+ }
841
1134
  return;
842
1135
  };
843
1136
  if session != CONNECT_ID {
@@ -949,7 +1242,10 @@ impl WtSession {
949
1242
 
950
1243
  pub fn stream_reset(&mut self, conn: &mut quiche::Connection, id: u64, code: u64) {
951
1244
  if self.streams.contains_key(&id) {
952
- let _ = conn.stream_shutdown(id, quiche::Shutdown::Write, code);
1245
+ // The QUIC RESET_STREAM code must be the WebTransport application code
1246
+ // mapped into the HTTP/3 error space.
1247
+ let h = h3::webtransport_code_to_http_code(code);
1248
+ let _ = conn.stream_shutdown(id, quiche::Shutdown::Write, h);
953
1249
  if let Some(st) = self.streams.get_mut(&id) {
954
1250
  st.out.clear();
955
1251
  st.fin_sent = true;
@@ -959,7 +1255,8 @@ impl WtSession {
959
1255
 
960
1256
  pub fn stream_stop_sending(&mut self, conn: &mut quiche::Connection, id: u64, code: u64) {
961
1257
  if self.streams.contains_key(&id) {
962
- let _ = conn.stream_shutdown(id, quiche::Shutdown::Read, code);
1258
+ let h = h3::webtransport_code_to_http_code(code);
1259
+ let _ = conn.stream_shutdown(id, quiche::Shutdown::Read, h);
963
1260
  if let Some(st) = self.streams.get_mut(&id) {
964
1261
  st.recv_dead = true;
965
1262
  }
@@ -976,16 +1273,69 @@ impl WtSession {
976
1273
  if self.close_req.is_none() {
977
1274
  self.close_req = Some(CloseReq {
978
1275
  code,
979
- reason,
1276
+ reason: h3::truncate_close_reason(reason),
980
1277
  capsule_queued: false,
981
1278
  });
982
1279
  }
983
1280
  }
984
1281
 
1282
+ /// Queue a DRAIN_WEBTRANSPORT_SESSION capsule on the session stream, telling
1283
+ /// the peer we intend to close soon. The session stays usable; this is not a
1284
+ /// close. Emitted at most once and only while the session is open.
1285
+ pub fn send_drain(&mut self) {
1286
+ if self.closed || self.drain_sent {
1287
+ return;
1288
+ }
1289
+ let mut capsule = Vec::new();
1290
+ h3::put_varint(h3::WT_DRAIN_SESSION_CAPSULE, &mut capsule);
1291
+ h3::put_varint(0, &mut capsule); // DRAIN carries no content
1292
+ let body = h3::frame(h3::FRAME_DATA, &capsule);
1293
+ // Only mark it sent once the CONNECT stream actually exists and we have
1294
+ // queued the capsule; a drain() issued before establishment retries later.
1295
+ if let Some(st) = self.streams.get_mut(&CONNECT_ID) {
1296
+ st.out.push_back(OutChunk {
1297
+ data: body,
1298
+ off: 0,
1299
+ request_id: None,
1300
+ });
1301
+ self.drain_sent = true;
1302
+ }
1303
+ }
1304
+
1305
+ /// Queue a single-varint-valued capsule (WT_MAX_DATA / WT_MAX_STREAMS_*) on
1306
+ /// the session stream.
1307
+ fn queue_session_capsule(&mut self, ty: u64, value: u64) {
1308
+ let mut val = Vec::new();
1309
+ h3::put_varint(value, &mut val);
1310
+ let mut capsule = Vec::new();
1311
+ h3::put_varint(ty, &mut capsule);
1312
+ h3::put_varint(val.len() as u64, &mut capsule);
1313
+ capsule.extend_from_slice(&val);
1314
+ let body = h3::frame(h3::FRAME_DATA, &capsule);
1315
+ if let Some(st) = self.streams.get_mut(&CONNECT_ID) {
1316
+ st.out.push_back(OutChunk {
1317
+ data: body,
1318
+ off: 0,
1319
+ request_id: None,
1320
+ });
1321
+ }
1322
+ }
1323
+
985
1324
  /// Flush pending outbound stream data and drive the graceful-close sequence.
986
1325
  /// Returns an optional `(code, reason)` if the QUIC connection should now be
987
1326
  /// closed.
988
1327
  pub fn flush(&mut self, conn: &mut quiche::Connection, ev: &mut Vec<Ev>) {
1328
+ // Once established, grant the peer ample per-session flow-control credit.
1329
+ // Exactly one WebTransport session rides this QUIC connection, so QUIC's
1330
+ // connection-level flow control is the real limit; granting a large WT
1331
+ // credit here keeps a strict peer that honors our advertised session
1332
+ // limits from stalling, while QUIC does the actual enforcement.
1333
+ if self.ready && !self.fc_credit_granted && !self.closed {
1334
+ self.fc_credit_granted = true;
1335
+ self.queue_session_capsule(h3::WT_MAX_DATA_CAPSULE, WT_GRANT_MAX_DATA);
1336
+ self.queue_session_capsule(h3::WT_MAX_STREAMS_BIDI_CAPSULE, WT_GRANT_MAX_STREAMS);
1337
+ self.queue_session_capsule(h3::WT_MAX_STREAMS_UNI_CAPSULE, WT_GRANT_MAX_STREAMS);
1338
+ }
989
1339
  // Queue the CLOSE_WEBTRANSPORT_SESSION capsule + FIN once, if requested.
990
1340
  if let Some(req) = self.close_req.as_mut() {
991
1341
  if !req.capsule_queued {
@@ -1013,9 +1363,13 @@ impl WtSession {
1013
1363
  }
1014
1364
 
1015
1365
  let ids: Vec<u64> = self.streams.keys().copied().collect();
1366
+ let mut wt_sent = 0u64;
1016
1367
  for id in ids {
1017
- self.flush_stream(conn, id, ev);
1368
+ self.flush_stream(conn, id, ev, &mut wt_sent);
1018
1369
  }
1370
+ self.fc_data_sent += wt_sent;
1371
+
1372
+ self.signal_flow_control_blocked();
1019
1373
 
1020
1374
  // Prune fully-terminated streams so a hostile peer churning streams
1021
1375
  // cannot grow the map without bound. Keep the CONNECT (session) stream
@@ -1044,37 +1398,125 @@ impl WtSession {
1044
1398
  // Opens blocked on stream credit simply keep their WT-signal prefix queued
1045
1399
  // in `out`; `flush_stream` retries them on every loop until credit lands.
1046
1400
 
1047
- // If a graceful close finished flushing the CONNECT stream, close QUIC.
1048
- if self.want_quic_close.is_none() {
1049
- if let Some(req) = self.close_req.as_ref() {
1050
- let connect_drained = self
1051
- .streams
1052
- .get(&CONNECT_ID)
1053
- .map(|s| s.out.is_empty() && s.fin_sent)
1054
- .unwrap_or(true);
1055
- if req.capsule_queued && connect_drained {
1056
- self.want_quic_close = Some((req.code, req.reason.clone()));
1401
+ // Graceful QUIC close, issued exactly once. After the CONNECT stream has
1402
+ // flushed the CLOSE_WEBTRANSPORT_SESSION capsule + FIN, close the HTTP/3
1403
+ // connection with H3_NO_ERROR (the WebTransport code/reason ride the
1404
+ // capsule, never the QUIC error field). The close is deferred one flush
1405
+ // pass so the driver's flush_send() serializes the capsule + FIN before the
1406
+ // CONNECTION_CLOSE frame supersedes all buffered stream frames. Ev::Closed
1407
+ // is emitted later by the driver's terminal branch (once conn.is_closed),
1408
+ // so JS never sees the close while the driver thread is still running.
1409
+ if !self.quic_close_issued {
1410
+ if self.want_quic_close.is_none() {
1411
+ if let Some(req) = self.close_req.as_ref() {
1412
+ let connect_drained = self
1413
+ .streams
1414
+ .get(&CONNECT_ID)
1415
+ .map(|s| s.out.is_empty() && s.fin_sent)
1416
+ .unwrap_or(true);
1417
+ if req.capsule_queued && connect_drained {
1418
+ self.want_quic_close = Some((req.code, req.reason.clone()));
1419
+ }
1420
+ }
1421
+ }
1422
+ if self.want_quic_close.is_some() {
1423
+ if self.close_deferred_once {
1424
+ self.want_quic_close = None;
1425
+ self.quic_close_issued = true;
1426
+ let _ = conn.close(true, h3::H3_NO_ERROR, b"");
1427
+ } else {
1428
+ self.close_deferred_once = true;
1057
1429
  }
1058
1430
  }
1059
1431
  }
1432
+ }
1433
+
1434
+ /// If this session initiated a graceful close, the WebTransport close code and
1435
+ /// reason to surface to the application (the wire uses H3_NO_ERROR, but the JS
1436
+ /// `closeInfo` must carry the app-level code/reason).
1437
+ pub fn local_close_info(&self) -> Option<(u32, Vec<u8>)> {
1438
+ self.close_req
1439
+ .as_ref()
1440
+ .map(|req| (req.code, req.reason.clone()))
1441
+ }
1442
+
1443
+ /// Emit WT_DATA_BLOCKED / WT_STREAMS_BLOCKED_* capsules when the peer's
1444
+ /// advertised WebTransport limits are holding back a send, once per distinct
1445
+ /// limit value. QUIC's own flow control does the real enforcement under the
1446
+ /// one-session-per-connection model; this is the protocol-conformant signal
1447
+ /// asking the peer to raise the limit.
1448
+ fn signal_flow_control_blocked(&mut self) {
1449
+ // Limits are only meaningful once the peer's SETTINGS have seeded them.
1450
+ if self.peer_settings.is_none() || self.closed {
1451
+ return;
1452
+ }
1060
1453
 
1061
- if let Some((code, reason)) = self.want_quic_close.take() {
1062
- let _ = conn.close(true, code as u64, &reason);
1454
+ // Data-blocked: unsent WT stream payload while at the peer's WT_MAX_DATA.
1455
+ if self.fc_data_sent >= self.fc_max_data_remote
1456
+ && self.data_blocked_at != self.fc_max_data_remote
1457
+ {
1458
+ let has_pending = self.streams.values().any(|s| {
1459
+ matches!(s.role, Role::WtData { .. })
1460
+ && s.out.iter().any(|c| c.request_id.is_some())
1461
+ });
1462
+ if has_pending {
1463
+ let limit = self.fc_max_data_remote;
1464
+ self.queue_session_capsule(h3::WT_DATA_BLOCKED_CAPSULE, limit);
1465
+ self.data_blocked_at = limit;
1466
+ }
1467
+ }
1468
+
1469
+ // Streams-blocked: more streams opened in a direction than WT_MAX_STREAMS_*.
1470
+ let (first_bidi, first_uni) = if self.is_server {
1471
+ (SERVER_FIRST_WT_BIDI_ID, SERVER_FIRST_WT_UNI_ID)
1472
+ } else {
1473
+ (CLIENT_FIRST_WT_BIDI_ID, CLIENT_FIRST_WT_UNI_ID)
1474
+ };
1475
+ let opened_bidi = (self.next_bidi - first_bidi) / 4;
1476
+ let opened_uni = (self.next_uni - first_uni) / 4;
1477
+
1478
+ if opened_bidi > self.fc_max_streams_bidi_remote
1479
+ && self.streams_bidi_blocked_at != self.fc_max_streams_bidi_remote
1480
+ {
1481
+ let limit = self.fc_max_streams_bidi_remote;
1482
+ self.queue_session_capsule(h3::WT_STREAMS_BLOCKED_BIDI_CAPSULE, limit);
1483
+ self.streams_bidi_blocked_at = limit;
1484
+ }
1485
+ if opened_uni > self.fc_max_streams_uni_remote
1486
+ && self.streams_uni_blocked_at != self.fc_max_streams_uni_remote
1487
+ {
1488
+ let limit = self.fc_max_streams_uni_remote;
1489
+ self.queue_session_capsule(h3::WT_STREAMS_BLOCKED_UNI_CAPSULE, limit);
1490
+ self.streams_uni_blocked_at = limit;
1063
1491
  }
1064
1492
  }
1065
1493
 
1066
- fn flush_stream(&mut self, conn: &mut quiche::Connection, id: u64, ev: &mut Vec<Ev>) {
1494
+ fn flush_stream(
1495
+ &mut self,
1496
+ conn: &mut quiche::Connection,
1497
+ id: u64,
1498
+ ev: &mut Vec<Ev>,
1499
+ wt_sent: &mut u64,
1500
+ ) {
1067
1501
  let Some(st) = self.streams.get_mut(&id) else {
1068
1502
  return;
1069
1503
  };
1504
+ // Only WebTransport stream payload (a WtData stream's request_id-carrying
1505
+ // chunks) counts toward WT_MAX_DATA; the stream-signal prefix and CONNECT
1506
+ // capsules do not.
1507
+ let is_wt_data = matches!(st.role, Role::WtData { .. });
1070
1508
  // Note: we call `stream_send` directly rather than pre-checking
1071
1509
  // `stream_capacity`, because a stream does not exist in quiche until its
1072
1510
  // first `stream_send`, and `stream_capacity` errors (InvalidStreamState)
1073
1511
  // on a not-yet-created stream.
1074
1512
  while let Some(front) = st.out.front_mut() {
1075
1513
  let remaining_len = front.data.len() - front.off;
1514
+ let is_payload = is_wt_data && front.request_id.is_some();
1076
1515
  match conn.stream_send(id, &front.data[front.off..], false) {
1077
1516
  Ok(sent) => {
1517
+ if is_payload {
1518
+ *wt_sent += sent as u64;
1519
+ }
1078
1520
  front.off += sent;
1079
1521
  if front.off >= front.data.len() {
1080
1522
  let done = st.out.pop_front().unwrap();
@@ -1089,7 +1531,8 @@ impl WtSession {
1089
1531
  Err(quiche::Error::Done) => return,
1090
1532
  Err(quiche::Error::StreamLimit) => return, // no stream credit yet; retry next loop
1091
1533
  Err(quiche::Error::StreamStopped(code)) => {
1092
- ev.push(Ev::StreamStopSending { id, code });
1534
+ let app = h3::http_code_to_webtransport_code(code).unwrap_or(code);
1535
+ ev.push(Ev::StreamStopSending { id, code: app });
1093
1536
  // Settle every queued write's promise so a stalled write()
1094
1537
  // (and its WritableStream) cannot hang forever.
1095
1538
  for chunk in st.out.drain(..) {
@@ -1189,3 +1632,89 @@ fn classify_new(id: u64, is_server: bool) -> Role {
1189
1632
  }
1190
1633
  }
1191
1634
  }
1635
+
1636
+ #[cfg(test)]
1637
+ mod tests {
1638
+ use super::*;
1639
+
1640
+ /// A minimal established-looking client session with a CONNECT stream (so
1641
+ /// queued session capsules have somewhere to go) and seeded peer settings.
1642
+ fn client_with_connect() -> WtSession {
1643
+ let mut s = WtSession::new_client("h".into(), "/".into(), None, Vec::new(), Vec::new());
1644
+ s.streams.insert(CONNECT_ID, Stream::new(Role::Connect));
1645
+ s.peer_settings = Some(h3::PeerSettings::default());
1646
+ s
1647
+ }
1648
+
1649
+ fn connect_out_len(s: &WtSession) -> usize {
1650
+ s.streams
1651
+ .get(&CONNECT_ID)
1652
+ .map(|st| st.out.len())
1653
+ .unwrap_or(0)
1654
+ }
1655
+
1656
+ #[test]
1657
+ fn emits_wt_data_blocked_once_per_limit() {
1658
+ let mut s = client_with_connect();
1659
+ s.fc_max_data_remote = 100;
1660
+ s.fc_data_sent = 100;
1661
+ let mut st = Stream::new(Role::WtData { bidi: true });
1662
+ st.out.push_back(OutChunk {
1663
+ data: vec![1, 2, 3],
1664
+ off: 0,
1665
+ request_id: Some(1),
1666
+ });
1667
+ s.streams.insert(4, st);
1668
+
1669
+ s.signal_flow_control_blocked();
1670
+ assert_eq!(connect_out_len(&s), 1); // one WT_DATA_BLOCKED capsule queued
1671
+ s.signal_flow_control_blocked();
1672
+ assert_eq!(connect_out_len(&s), 1); // deduped: not re-queued at the same limit
1673
+
1674
+ // A raised limit that we immediately re-exhaust re-arms the signal.
1675
+ s.fc_max_data_remote = 200;
1676
+ s.fc_data_sent = 200;
1677
+ s.signal_flow_control_blocked();
1678
+ assert_eq!(connect_out_len(&s), 2);
1679
+ }
1680
+
1681
+ #[test]
1682
+ fn no_data_blocked_without_pending_payload() {
1683
+ let mut s = client_with_connect();
1684
+ s.fc_max_data_remote = 100;
1685
+ s.fc_data_sent = 100;
1686
+ // A WtData stream whose only queued chunk is the prefix (request_id None).
1687
+ let mut st = Stream::new(Role::WtData { bidi: false });
1688
+ st.out.push_back(OutChunk {
1689
+ data: vec![0x54],
1690
+ off: 0,
1691
+ request_id: None,
1692
+ });
1693
+ s.streams.insert(14, st);
1694
+ s.signal_flow_control_blocked();
1695
+ assert_eq!(connect_out_len(&s), 0);
1696
+ }
1697
+
1698
+ #[test]
1699
+ fn emits_streams_blocked_when_over_limit() {
1700
+ let mut s = client_with_connect();
1701
+ s.fc_max_streams_bidi_remote = 1;
1702
+ // Simulate having opened 2 bidi WT streams (next_bidi advanced twice).
1703
+ s.next_bidi = CLIENT_FIRST_WT_BIDI_ID + 8;
1704
+ s.signal_flow_control_blocked();
1705
+ assert_eq!(connect_out_len(&s), 1); // WT_STREAMS_BLOCKED_BIDI
1706
+ s.signal_flow_control_blocked();
1707
+ assert_eq!(connect_out_len(&s), 1); // deduped
1708
+ }
1709
+
1710
+ #[test]
1711
+ fn no_signal_before_peer_settings() {
1712
+ let mut s = client_with_connect();
1713
+ s.peer_settings = None;
1714
+ s.fc_max_data_remote = 0;
1715
+ s.fc_data_sent = 0;
1716
+ s.next_bidi = CLIENT_FIRST_WT_BIDI_ID + 8;
1717
+ s.signal_flow_control_blocked();
1718
+ assert_eq!(connect_out_len(&s), 0);
1719
+ }
1720
+ }