rwebtransport 0.2.1 → 0.2.2

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.
@@ -23,7 +23,12 @@ pub const WAKE_TOKEN: Token = Token(1);
23
23
  /// server flooding datagrams or stream data cannot grow it without limit (OOM).
24
24
  /// When exceeded, unread stream data stays in quiche (flow-controlling the peer)
25
25
  /// and excess datagrams are dropped by quiche's bounded recv queue.
26
- const MAX_INFLIGHT_BATCHES: i64 = 128;
26
+ ///
27
+ /// `pub` so the neon sinks can wake the driver the moment a batch is dequeued and the counter crosses
28
+ /// back below this cap: back-pressure is set on the driver thread but cleared on the JS thread, so
29
+ /// without that wake the driver would keep withholding data (including a terminal frame) until an
30
+ /// unrelated event happened to run another loop iteration.
31
+ pub const MAX_INFLIGHT_BATCHES: i64 = 128;
27
32
 
28
33
  /// State shared between the driver thread and the JS-facing handle so that
29
34
  /// synchronous property reads (e.g. `datagrams.maxDatagramSize`) don't require a
@@ -76,17 +76,32 @@ impl Finalize for SessionHandle {
76
76
  }
77
77
  }
78
78
 
79
+ /// Decrement the in-flight batch counter once the JS thread has dequeued (or failed to schedule) a
80
+ /// batch, and WAKE the driver when this decrement crosses back below the cap. Back-pressure
81
+ /// ([`driver::MAX_INFLIGHT_BATCHES`]) is set on the driver thread but cleared here on the JS thread, so
82
+ /// without this wake the driver would keep withholding stream data (a completed stream's terminal
83
+ /// bytes stranded in quiche, its JS consumer hung) until some unrelated event happened to run another
84
+ /// driver iteration. `fetch_sub` returns the PREVIOUS value, so `== cap` is exactly the crossing.
85
+ fn release_inflight_batch(shared: &DriverShared, waker: &mio::Waker) {
86
+ if shared.inflight.fetch_sub(1, Ordering::Relaxed) == driver::MAX_INFLIGHT_BATCHES {
87
+ let _ = waker.wake();
88
+ }
89
+ }
90
+
79
91
  /// Bridges driver events onto the JS event loop.
80
92
  struct NeonSink {
81
93
  channel: Channel,
82
94
  callback: Arc<Root<JsFunction>>,
83
95
  shared: Arc<DriverShared>,
96
+ /// Wakes the driver thread when a dequeued batch clears back-pressure (see `release_inflight_batch`).
97
+ waker: Arc<mio::Waker>,
84
98
  }
85
99
 
86
100
  impl EventSink for NeonSink {
87
101
  fn emit(&self, events: Vec<Ev>) {
88
102
  let cb = self.callback.clone();
89
103
  let shared = self.shared.clone();
104
+ let waker = self.waker.clone();
90
105
  // Count this batch as in flight to the JS loop; the driver reads this to
91
106
  // back off from pulling more data out of quiche when JS falls behind.
92
107
  self.shared.inflight.fetch_add(1, Ordering::Relaxed);
@@ -96,8 +111,9 @@ impl EventSink for NeonSink {
96
111
  // behaviour that aborts the process on some platforms). Failing the emit
97
112
  // silently is the correct behaviour during teardown.
98
113
  let result = self.channel.try_send(move |mut cx| {
99
- // Dequeued by the JS loop: no longer contributing to queue depth.
100
- shared.inflight.fetch_sub(1, Ordering::Relaxed);
114
+ // Dequeued by the JS loop: no longer contributing to queue depth. Wake
115
+ // the driver if this cleared back-pressure so it re-drains withheld data.
116
+ release_inflight_batch(&shared, &waker);
101
117
  let f = cb.to_inner(&mut cx);
102
118
  for ev in &events {
103
119
  let obj = ev_to_js(&mut cx, ev)?;
@@ -109,7 +125,7 @@ impl EventSink for NeonSink {
109
125
  });
110
126
  if result.is_err() {
111
127
  // The callback will never run, so undo the in-flight increment here.
112
- self.shared.inflight.fetch_sub(1, Ordering::Relaxed);
128
+ release_inflight_batch(&self.shared, &self.waker);
113
129
  }
114
130
  }
115
131
  }
@@ -294,6 +310,7 @@ fn connect(mut cx: FunctionContext) -> JsResult<JsBox<SessionHandle>> {
294
310
  channel: cx.channel(),
295
311
  callback: Arc::new(callback.root(&mut cx)),
296
312
  shared: shared.clone(),
313
+ waker: waker.clone(),
297
314
  });
298
315
 
299
316
  let setup = driver::SessionSetup {
@@ -483,19 +500,23 @@ struct NeonServerSink {
483
500
  channel: Channel,
484
501
  callback: Arc<Root<JsFunction>>,
485
502
  shared: Arc<DriverShared>,
503
+ /// Wakes the server driver when a dequeued batch clears back-pressure (see `release_inflight_batch`).
504
+ waker: Arc<mio::Waker>,
486
505
  }
487
506
 
488
507
  impl ServerEventSink for NeonServerSink {
489
508
  fn emit(&self, messages: Vec<ServerMsg>) {
490
509
  let cb = self.callback.clone();
491
510
  let shared = self.shared.clone();
511
+ let waker = self.waker.clone();
492
512
  // Balance every emit (setup, teardown, and per-loop batches) so the
493
513
  // backpressure counter can never underflow and silently disable itself.
494
514
  self.shared.inflight.fetch_add(1, Ordering::Relaxed);
495
515
  // `try_send`, not `send`: see NeonSink::emit. `send` would panic across
496
516
  // the N-API boundary if the environment is shutting down.
497
517
  let result = self.channel.try_send(move |mut cx| {
498
- shared.inflight.fetch_sub(1, Ordering::Relaxed);
518
+ // Dequeued: decrement and, if this cleared back-pressure, wake the driver.
519
+ release_inflight_batch(&shared, &waker);
499
520
  let f = cb.to_inner(&mut cx);
500
521
  for msg in &messages {
501
522
  let obj = server_msg_to_js(&mut cx, msg)?;
@@ -506,7 +527,7 @@ impl ServerEventSink for NeonServerSink {
506
527
  Ok(())
507
528
  });
508
529
  if result.is_err() {
509
- self.shared.inflight.fetch_sub(1, Ordering::Relaxed);
530
+ release_inflight_batch(&self.shared, &self.waker);
510
531
  }
511
532
  }
512
533
  }
@@ -569,6 +590,7 @@ fn server_listen(mut cx: FunctionContext) -> JsResult<JsBox<ServerHandle>> {
569
590
  channel: cx.channel(),
570
591
  callback: Arc::new(callback.root(&mut cx)),
571
592
  shared: shared.clone(),
593
+ waker: waker.clone(),
572
594
  });
573
595
 
574
596
  let setup = ServerSetup {
@@ -1011,3 +1033,44 @@ fn main(mut cx: ModuleContext) -> NeonResult<()> {
1011
1033
  cx.export_function("serverShutdown", server_shutdown)?;
1012
1034
  Ok(())
1013
1035
  }
1036
+
1037
+ #[cfg(test)]
1038
+ mod tests {
1039
+ use super::*;
1040
+
1041
+ fn shared_with_inflight(n: i64) -> Arc<DriverShared> {
1042
+ let shared = Arc::new(DriverShared::default());
1043
+ shared.inflight.store(n, Ordering::Relaxed);
1044
+ shared
1045
+ }
1046
+
1047
+ /// Whether the driver's waker fired: poll with a zero timeout and look for `WAKE_TOKEN`.
1048
+ fn waker_fired(poll: &mut mio::Poll) -> bool {
1049
+ let mut events = mio::Events::with_capacity(4);
1050
+ poll.poll(&mut events, Some(std::time::Duration::from_millis(0)))
1051
+ .expect("poll");
1052
+ events.iter().any(|e| e.token() == driver::WAKE_TOKEN)
1053
+ }
1054
+
1055
+ // Back-pressure is set on the driver thread but cleared here on the JS thread, so releasing a batch
1056
+ // must wake the driver EXACTLY when the decrement crosses back below the cap: not while still at or
1057
+ // above it (still back-pressured), and not when already below it (a spurious wake). Getting this
1058
+ // wrong is the stranded-terminal-frame hang.
1059
+ #[test]
1060
+ fn release_wakes_only_when_the_decrement_clears_backpressure() {
1061
+ let mut poll = mio::Poll::new().expect("poll");
1062
+ let waker = mio::Waker::new(poll.registry(), driver::WAKE_TOKEN).expect("waker");
1063
+
1064
+ // Already below the cap: not back-pressured, so no wake.
1065
+ release_inflight_batch(&shared_with_inflight(driver::MAX_INFLIGHT_BATCHES - 1), &waker);
1066
+ assert!(!waker_fired(&mut poll), "no wake when already below the cap");
1067
+
1068
+ // Still at/above the cap after the decrement: still back-pressured, so no wake.
1069
+ release_inflight_batch(&shared_with_inflight(driver::MAX_INFLIGHT_BATCHES + 1), &waker);
1070
+ assert!(!waker_fired(&mut poll), "no wake while still at or above the cap");
1071
+
1072
+ // Exactly at the cap: the decrement crosses below it, clearing back-pressure -> wake.
1073
+ release_inflight_batch(&shared_with_inflight(driver::MAX_INFLIGHT_BATCHES), &waker);
1074
+ assert!(waker_fired(&mut poll), "wake exactly when back-pressure clears");
1075
+ }
1076
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rwebtransport",
3
- "version": "0.2.1",
3
+ "version": "0.2.2",
4
4
  "description": "A fully-compatible WebTransport client and server for Node.js, powered by Cloudflare quiche + BoringSSL via neon.",
5
5
  "author": "Dacely Cloud",
6
6
  "homepage": "https://github.com/dacely-cloud/rwebtransport#readme",