Debian Codegraph @

third_party/rust/neqo-transport/src/path.rs

raw
1 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
2 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
3 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
4 // option. This file may not be copied, modified, or distributed
5 // except according to those terms.
6
7 use std::{
8 cell::RefCell,
9 fmt::{self, Display},
10 net::SocketAddr,
11 rc::Rc,
12 time::{Duration, Instant},
13 };
14
15 use neqo_common::{hex, qdebug, qinfo, qlog::NeqoQlog, qtrace, qwarn, Datagram, Encoder, IpTos};
16 use neqo_crypto::random;
17
18 use crate::{
19 ackrate::{AckRate, PeerAckDelay},
20 cid::{ConnectionId, ConnectionIdRef, ConnectionIdStore, RemoteConnectionIdEntry},
21 ecn,
22 frame::FrameType,
23 packet::{PacketBuilder, PacketType},
24 pmtud::Pmtud,
25 recovery::{RecoveryToken, SentPacket},
26 rtt::{RttEstimate, RttSource},
27 sender::PacketSender,
28 stats::FrameStats,
29 ConnectionParameters, Stats,
30 };
31
32 /// The number of times that a path will be probed before it is considered failed.
33 ///
34 /// Note that with [`crate::ecn`], a path is probed [`MAX_PATH_PROBES`] with ECN
35 /// marks and [`MAX_PATH_PROBES`] without.
36 pub const MAX_PATH_PROBES: usize = 3;
37 /// The maximum number of paths that `Paths` will track.
38 const MAX_PATHS: usize = 15;
39
40 pub type PathRef = Rc<RefCell<Path>>;
41
42 /// A collection for network paths.
43 /// This holds a collection of paths that have been used for sending or
44 /// receiving, plus an additional "temporary" path that is held only while
45 /// processing a packet.
46 /// This structure limits its storage and will forget about paths if it
47 /// is exposed to too many paths.
48 #[derive(Debug, Default)]
49 pub struct Paths {
50 /// All of the paths. All of these paths will be permanent.
51 #[expect(clippy::struct_field_names, reason = "This is the best name.")]
52 paths: Vec<PathRef>,
53 /// This is the primary path. This will only be `None` initially, so
54 /// care needs to be taken regarding that only during the handshake.
55 /// This path will also be in `paths`.
56 primary: Option<PathRef>,
57
58 /// The path that we would prefer to migrate to.
59 migration_target: Option<PathRef>,
60
61 /// Connection IDs that need to be retired.
62 to_retire: Vec<u64>,
63
64 /// `QLog` handler.
65 qlog: NeqoQlog,
66 }
67
68 impl Paths {
69 /// Find the path for the given addresses.
70 /// This might be a temporary path.
71 pub fn find_path(
72 &self,
73 local: SocketAddr,
74 remote: SocketAddr,
75 conn_params: &ConnectionParameters,
76 now: Instant,
77 stats: &mut Stats,
78 ) -> PathRef {
79 self.paths
80 .iter()
81 .find_map(|p| p.borrow().received_on(local, remote).then(|| Rc::clone(p)))
82 .unwrap_or_else(|| {
83 let mut p =
84 Path::temporary(local, remote, conn_params, self.qlog.clone(), now, stats);
85 if let Some(primary) = self.primary.as_ref() {
86 p.prime_rtt(primary.borrow().rtt());
87 }
88 Rc::new(RefCell::new(p))
89 })
90 }
91
92 /// Get a reference to the primary path, if one exists.
93 pub fn primary(&self) -> Option<PathRef> {
94 self.primary.clone()
95 }
96
97 /// Returns true if the path is not permanent.
98 pub fn is_temporary(&self, path: &PathRef) -> bool {
99 // Ask the path first, which is simpler.
100 path.borrow().is_temporary() || !self.paths.iter().any(|p| Rc::ptr_eq(p, path))
101 }
102
103 fn retire(to_retire: &mut Vec<u64>, retired: &PathRef) {
104 if let Some(cid) = &retired.borrow().remote_cid {
105 let seqno = cid.sequence_number();
106 if cid.connection_id().is_empty() {
107 qdebug!("Connection ID {seqno} is zero-length, not retiring");
108 } else {
109 to_retire.push(seqno);
110 }
111 }
112 }
113
114 /// Adopt a temporary path as permanent.
115 /// The first path that is made permanent is made primary.
116 pub fn make_permanent(
117 &mut self,
118 path: &PathRef,
119 local_cid: Option<ConnectionId>,
120 remote_cid: RemoteConnectionIdEntry,
121 now: Instant,
122 ) {
123 debug_assert!(self.is_temporary(path));
124
125 // Make sure not to track too many paths.
126 // This protects index 0, which contains the primary path.
127 if self.paths.len() >= MAX_PATHS {
128 debug_assert_eq!(self.paths.len(), MAX_PATHS);
129 let removed = self.paths.remove(1);
130 Self::retire(&mut self.to_retire, &removed);
131 if self
132 .migration_target
133 .as_ref()
134 .is_some_and(|target| Rc::ptr_eq(target, &removed))
135 {
136 qinfo!(
137 "[{}] The migration target path had to be removed",
138 path.borrow()
139 );
140 self.migration_target = None;
141 }
142 debug_assert_eq!(Rc::strong_count(&removed), 1);
143 }
144
145 qdebug!("[{}] Make permanent", path.borrow());
146 path.borrow_mut().make_permanent(local_cid, remote_cid);
147 self.paths.push(Rc::clone(path));
148 if self.primary.is_none() {
149 assert!(self.select_primary(path, now).is_none());
150 }
151 }
152
153 /// Select a path as the primary. Returns the old primary path.
154 /// Using the old path is only necessary if this change in path is a reaction
155 /// to a migration from a peer, in which case the old path needs to be probed.
156 #[must_use]
157 fn select_primary(&mut self, path: &PathRef, now: Instant) -> Option<PathRef> {
158 qdebug!("[{}] set as primary path", path.borrow());
159 let old_path = self.primary.replace(Rc::clone(path)).inspect(|old| {
160 old.borrow_mut().set_primary(false, now);
161 });
162
163 // Swap the primary path into slot 0, so that it is protected from eviction.
164 let idx = self
165 .paths
166 .iter()
167 .enumerate()
168 .find_map(|(i, p)| Rc::ptr_eq(p, path).then_some(i))?;
169 self.paths.swap(0, idx);
170
171 path.borrow_mut().set_primary(true, now);
172 old_path
173 }
174
175 /// Migrate to the identified path. If `force` is true, the path
176 /// is forcibly marked as valid and the path is used immediately.
177 /// Otherwise, migration will occur after probing succeeds.
178 /// The path is always probed and will be abandoned if probing fails.
179 /// Returns `true` if the path was migrated.
180 pub fn migrate(
181 &mut self,
182 path: &PathRef,
183 force: bool,
184 now: Instant,
185 stats: &mut Stats,
186 ) -> bool {
187 debug_assert!(!self.is_temporary(path));
188 let baseline = self.primary().map_or_else(
189 || ecn::Info::default().baseline(),
190 |p| p.borrow().ecn_info.baseline(),
191 );
192 path.borrow_mut().set_ecn_baseline(baseline);
193 if force || path.borrow().is_valid() {
194 path.borrow_mut().set_valid(now);
195 drop(self.select_primary(path, now));
196 self.migration_target = None;
197 } else {
198 self.migration_target = Some(Rc::clone(path));
199 }
200 path.borrow_mut().probe(stats);
201 self.migration_target.is_none()
202 }
203
204 /// Process elapsed time for active paths.
205 /// Returns an true if there are viable paths remaining after tidying up.
206 ///
207 /// TODO(mt) - the paths should own the RTT estimator, so they can find the PTO
208 /// for themselves.
209 pub fn process_timeout(&mut self, now: Instant, pto: Duration, stats: &mut Stats) -> bool {
210 let to_retire = &mut self.to_retire;
211 let mut primary_failed = false;
212 self.paths.retain(|p| {
213 if p.borrow_mut().process_timeout(now, pto, stats) {
214 true
215 } else {
216 qdebug!("[{}] Retiring path", p.borrow());
217 if p.borrow().is_primary() {
218 primary_failed = true;
219 }
220 Self::retire(to_retire, p);
221 false
222 }
223 });
224
225 if primary_failed {
226 self.primary = None;
227 // Find a valid path to fall back to.
228 #[expect(
229 clippy::option_if_let_else,
230 reason = "The alternative is less readable."
231 )]
232 if let Some(fallback) = self
233 .paths
234 .iter()
235 .rev() // More recent paths are toward the end.
236 .find(|p| p.borrow().is_valid())
237 {
238 // Need a clone as `fallback` is borrowed from `self`.
239 let path = Rc::clone(fallback);
240 qinfo!("[{}] Failing over after primary path failed", path.borrow());
241 drop(self.select_primary(&path, now));
242 true
243 } else {
244 false
245 }
246 } else {
247 // See if the PMTUD raise timer wants to fire.
248 if let Some(path) = self.primary() {
249 path.borrow_mut()
250 .pmtud_mut()
251 .maybe_fire_raise_timer(now, stats);
252 }
253 true
254 }
255 }
256
257 /// Get when the next call to `process_timeout()` should be scheduled.
258 pub fn next_timeout(&self, pto: Duration) -> Option<Instant> {
259 self.paths
260 .iter()
261 .filter_map(|p| p.borrow().next_timeout(pto))
262 .min()
263 }
264
265 /// Set the identified path to be primary.
266 /// This panics if `make_permanent` hasn't been called.
267 pub fn handle_migration(
268 &mut self,
269 path: &PathRef,
270 remote: SocketAddr,
271 now: Instant,
272 stats: &mut Stats,
273 ) {
274 // The update here needs to match the checks in `Path::received_on`.
275 // Here, we update the remote port number to match the source port on the
276 // datagram that was received. This ensures that we send subsequent
277 // packets back to the right place.
278 path.borrow_mut().update_port(remote.port());
279
280 if path.borrow().is_primary() {
281 // Update when the path was last regarded as valid.
282 path.borrow_mut().update(now);
283 return;
284 }
285
286 if let Some(old_path) = self.select_primary(path, now) {
287 // Need to probe the old path if the peer migrates.
288 old_path.borrow_mut().probe(stats);
289 // TODO(mt) - suppress probing if the path was valid within 3PTO.
290 }
291 }
292
293 /// Select a path to send on. This will select the first path that has
294 /// probes to send, then fall back to the primary path.
295 pub fn select_path(&self) -> Option<PathRef> {
296 self.paths
297 .iter()
298 .find_map(|p| p.borrow().has_probe().then(|| Rc::clone(p)))
299 .or_else(|| self.primary.clone())
300 }
301
302 /// A `PATH_RESPONSE` was received.
303 /// Returns `true` if migration occurred.
304 #[must_use]
305 pub fn path_response(&mut self, response: [u8; 8], now: Instant, stats: &mut Stats) -> bool {
306 // TODO(mt) consider recording an RTT measurement here as we don't train
307 // RTT for non-primary paths.
308 for p in &self.paths {
309 if p.borrow_mut().path_response(response, now, stats) {
310 // The response was accepted. If this path is one we intend
311 // to migrate to, then migrate.
312 if let Some(primary) = self
313 .migration_target
314 .take_if(|target| Rc::ptr_eq(target, p))
315 {
316 drop(self.select_primary(&primary, now));
317 return true;
318 }
319 break;
320 }
321 }
322 false
323 }
324
325 /// Retire all of the connection IDs prior to the indicated sequence number.
326 /// Keep active paths if possible by pulling new connection IDs from the provided store.
327 /// One slightly non-obvious consequence of this is that if migration is being attempted
328 /// and the new path cannot obtain a new connection ID, the migration attempt will fail.
329 pub fn retire_cids(&mut self, retire_prior: u64, store: &mut ConnectionIdStore<[u8; 16]>) {
330 let to_retire = &mut self.to_retire;
331 let migration_target = &mut self.migration_target;
332
333 // First, tell the store to release any connection IDs that are too old.
334 let mut retired = store.retire_prior_to(retire_prior);
335 to_retire.append(&mut retired);
336
337 self.paths.retain(|p| {
338 let mut path = p.borrow_mut();
339 let Some(current) = path.remote_cid.as_ref() else {
340 return true;
341 };
342 if current.sequence_number() < retire_prior && !current.connection_id().is_empty() {
343 to_retire.push(current.sequence_number());
344 let new_cid = store.next();
345 let has_replacement = new_cid.is_some();
346 // There must be a connection ID available for the primary path as we
347 // keep that path at the first index.
348 debug_assert!(!path.is_primary() || has_replacement);
349 path.remote_cid = new_cid;
350 if !has_replacement
351 && migration_target
352 .as_ref()
353 .is_some_and(|target| Rc::ptr_eq(target, p))
354 {
355 qinfo!(
356 "[{path}] NEW_CONNECTION_ID with Retire Prior To forced migration to fail"
357 );
358 *migration_target = None;
359 }
360 has_replacement
361 } else {
362 true
363 }
364 });
365 }
366
367 /// Write out any `RETIRE_CONNECTION_ID` frames that are outstanding.
368 pub fn write_frames(
369 &mut self,
370 builder: &mut PacketBuilder,
371 tokens: &mut Vec<RecoveryToken>,
372 stats: &mut FrameStats,
373 ) {
374 while let Some(seqno) = self.to_retire.pop() {
375 if builder.remaining() < 1 + Encoder::varint_len(seqno) {
376 self.to_retire.push(seqno);
377 break;
378 }
379 builder.encode_varint(FrameType::RetireConnectionId);
380 builder.encode_varint(seqno);
381 tokens.push(RecoveryToken::RetireConnectionId(seqno));
382 stats.retire_connection_id += 1;
383 }
384
385 if let Some(path) = self.primary() {
386 // Write out any ACK_FREQUENCY frames.
387 path.borrow_mut().write_cc_frames(builder, tokens, stats);
388 }
389 }
390
391 pub fn lost_retire_cid(&mut self, lost: u64) {
392 self.to_retire.push(lost);
393 }
394
395 pub fn acked_retire_cid(&mut self, acked: u64) {
396 self.to_retire.retain(|&seqno| seqno != acked);
397 }
398
399 pub fn lost_ack_frequency(&self, lost: &AckRate) {
400 if let Some(path) = self.primary() {
401 path.borrow_mut().lost_ack_frequency(lost);
402 }
403 }
404
405 pub fn acked_ack_frequency(&self, acked: &AckRate) {
406 if let Some(path) = self.primary() {
407 path.borrow_mut().acked_ack_frequency(acked);
408 }
409 }
410
411 pub fn acked_ecn(&self) {
412 if let Some(path) = self.primary() {
413 path.borrow_mut().acked_ecn();
414 }
415 }
416
417 pub fn lost_ecn(&self, pt: PacketType, stats: &mut Stats) {
418 if let Some(path) = self.primary() {
419 path.borrow_mut().lost_ecn(pt, stats);
420 }
421 }
422
423 /// Get an estimate of the RTT on the primary path.
424 #[cfg(test)]
425 pub fn rtt(&self) -> Duration {
426 // Rather than have this fail when there is no active path,
427 // make a new RTT estimate and interrogate that.
428 // That is more expensive, but it should be rare and breaking encapsulation
429 // is worse, especially as this is only used in tests.
430 self.primary().map_or_else(
431 || RttEstimate::default().estimate(),
432 |p| p.borrow().rtt().estimate(),
433 )
434 }
435
436 pub fn set_qlog(&mut self, qlog: NeqoQlog) {
437 for p in &mut self.paths {
438 p.borrow_mut().set_qlog(qlog.clone());
439 }
440 self.qlog = qlog;
441 }
442 }
443
444 /// The state of a path with respect to address validation.
445 #[derive(Debug)]
446 enum ProbeState {
447 /// The path was last valid at the indicated time.
448 Valid,
449 /// The path was previously valid, but a new probe is needed.
450 ProbeNeeded { probe_count: usize },
451 /// The path hasn't been validated, but a probe has been sent.
452 Probing {
453 /// The number of probes that have been sent.
454 probe_count: usize,
455 /// The probe that was last sent.
456 data: [u8; 8],
457 /// Whether the probe was sent in a datagram padded to the path MTU.
458 mtu: bool,
459 /// When the probe was sent.
460 sent: Instant,
461 },
462 /// Validation failed the last time it was attempted.
463 Failed,
464 }
465
466 impl ProbeState {
467 /// Determine whether the current state requires probing.
468 const fn probe_needed(&self) -> bool {
469 matches!(self, Self::ProbeNeeded { .. })
470 }
471 }
472
473 /// A network path.
474 ///
475 /// Paths are used a little bit strangely by connections:
476 /// they need to encapsulate all the state for a path (which
477 /// is normal), but that information is not propagated to the
478 /// `Paths` instance that holds them. This is because the packet
479 /// processing where changes occur can't hold a reference to the
480 /// `Paths` instance that owns the `Path`. Any changes to the
481 /// path are communicated to `Paths` afterwards.
482 #[derive(Debug)]
483 pub struct Path {
484 /// A local socket address.
485 local: SocketAddr,
486 /// A remote socket address.
487 remote: SocketAddr,
488 /// The connection IDs that we use when sending on this path.
489 /// This is only needed during the handshake.
490 local_cid: Option<ConnectionId>,
491 /// The current connection ID that we are using and its details.
492 remote_cid: Option<RemoteConnectionIdEntry>,
493
494 /// Whether this is the primary path.
495 primary: bool,
496 /// Whether the current path is considered valid.
497 state: ProbeState,
498 /// For a path that is not validated, this is `None`. For a validated
499 /// path, the time that the path was last valid.
500 validated: Option<Instant>,
501 /// A path challenge was received and `PATH_RESPONSE` has not been sent.
502 challenge: Option<[u8; 8]>,
503
504 /// The round trip time estimate for this path.
505 rtt: RttEstimate,
506 /// A packet sender for the path, which includes congestion control and a pacer.
507 sender: PacketSender,
508
509 /// The number of bytes received on this path.
510 /// Note that this value might saturate on a long-lived connection,
511 /// but we only use it before the path is validated.
512 received_bytes: usize,
513 /// The number of bytes sent on this path.
514 sent_bytes: usize,
515 /// The ECN-related state for this path (see RFC9000, Section 13.4 and Appendix A.4)
516 ecn_info: ecn::Info,
517 /// For logging of events.
518 qlog: NeqoQlog,
519 }
520
521 impl Path {
522 /// Create a path from addresses and a remote connection ID.
523 /// This is used for migration and for new datagrams.
524 pub fn temporary(
525 local: SocketAddr,
526 remote: SocketAddr,
527 conn_params: &ConnectionParameters,
528 qlog: NeqoQlog,
529 now: Instant,
530 stats: &mut Stats,
531 ) -> Self {
532 let iface_mtu = if conn_params.pmtud_iface_mtu_enabled() {
533 match mtu::interface_and_mtu(remote.ip()) {
534 Ok((name, mtu)) => {
535 qdebug!(
536 "Outbound interface {name} for destination {ip} has MTU {mtu}",
537 ip = remote.ip()
538 );
539 stats.pmtud_iface_mtu = mtu;
540 Some(mtu)
541 }
542 Err(e) => {
543 qwarn!(
544 "Failed to determine outbound interface for destination {ip}: {e}",
545 ip = remote.ip()
546 );
547 None
548 }
549 }
550 } else {
551 None
552 };
553 let mut sender = PacketSender::new(conn_params, Pmtud::new(remote.ip(), iface_mtu), now);
554 sender.set_qlog(qlog.clone());
555 Self {
556 local,
557 remote,
558 local_cid: None,
559 remote_cid: None,
560 primary: false,
561 state: ProbeState::ProbeNeeded { probe_count: 0 },
562 validated: None,
563 challenge: None,
564 rtt: RttEstimate::default(),
565 sender,
566 received_bytes: 0,
567 sent_bytes: 0,
568 ecn_info: ecn::Info::default(),
569 qlog,
570 }
571 }
572
573 pub fn set_ecn_baseline(&mut self, baseline: ecn::Count) {
574 self.ecn_info.set_baseline(baseline);
575 }
576
577 /// Return the DSCP/ECN marking to use for outgoing packets on this path.
578 pub fn tos(&self, tokens: &mut Vec<RecoveryToken>) -> IpTos {
579 self.ecn_info.ecn_mark(tokens).into()
580 }
581
582 /// Whether this path is the primary or current path for the connection.
583 pub const fn is_primary(&self) -> bool {
584 self.primary
585 }
586
587 /// Whether this path is a temporary one.
588 pub const fn is_temporary(&self) -> bool {
589 self.remote_cid.is_none()
590 }
591
592 /// By adding a remote connection ID, we make the path permanent
593 /// and one that we will later send packets on.
594 /// If `local_cid` is `None`, the existing value will be kept.
595 pub(crate) fn make_permanent(
596 &mut self,
597 local_cid: Option<ConnectionId>,
598 remote_cid: RemoteConnectionIdEntry,
599 ) {
600 if self.local_cid.is_none() {
601 self.local_cid = local_cid;
602 }
603 self.remote_cid.replace(remote_cid);
604 }
605
606 /// Determine if this path was the one that the provided datagram was received on.
607 fn received_on(&self, local: SocketAddr, remote: SocketAddr) -> bool {
608 self.local == local && self.remote == remote
609 }
610
611 /// Update the remote port number. Any flexibility we allow in `received_on`
612 /// need to be adjusted at this point.
613 fn update_port(&mut self, port: u16) {
614 self.remote.set_port(port);
615 }
616
617 /// Set whether this path is primary.
618 pub(crate) fn set_primary(&mut self, primary: bool, now: Instant) {
619 qtrace!("[{self}] Make primary {primary}");
620 debug_assert!(self.remote_cid.is_some());
621 self.primary = primary;
622 if !primary {
623 self.sender.discard_in_flight(now);
624 }
625 }
626
627 /// Set the current path as valid. This updates the time that the path was
628 /// last validated and cancels any path validation.
629 pub fn set_valid(&mut self, now: Instant) {
630 qdebug!("[{self}] Path validated {now:?}");
631 self.state = ProbeState::Valid;
632 self.validated = Some(now);
633 }
634
635 /// Update the last use of this path, if it is valid.
636 /// This will keep the path active slightly longer.
637 pub fn update(&mut self, now: Instant) {
638 if self.validated.is_some() {
639 self.validated = Some(now);
640 }
641 }
642
643 /// Get the PL MTU.
644 pub fn plpmtu(&self) -> usize {
645 self.pmtud().plpmtu()
646 }
647
648 /// Get a reference to the PMTUD state.
649 pub fn pmtud(&self) -> &Pmtud {
650 self.sender.pmtud()
651 }
652
653 /// Get the first local connection ID.
654 /// Only do this for the primary path during the handshake.
655 pub const fn local_cid(&self) -> Option<&ConnectionId> {
656 self.local_cid.as_ref()
657 }
658
659 /// Set the remote connection ID based on the peer's choice.
660 /// This is only valid during the handshake.
661 pub fn set_remote_cid(&mut self, cid: ConnectionIdRef) {
662 if let Some(remote_cid) = self.remote_cid.as_mut() {
663 remote_cid.update_cid(ConnectionId::from(cid));
664 }
665 }
666
667 /// Access the remote connection ID.
668 pub fn remote_cid(&self) -> Option<&ConnectionId> {
669 self.remote_cid
670 .as_ref()
671 .map(super::cid::ConnectionIdEntry::connection_id)
672 }
673
674 /// Set the stateless reset token for the connection ID that is currently in use.
675 pub fn set_reset_token(&mut self, token: [u8; 16]) {
676 if let Some(remote_cid) = self.remote_cid.as_mut() {
677 remote_cid.set_stateless_reset_token(token);
678 }
679 }
680
681 /// Determine if the provided token is a stateless reset token.
682 pub fn is_stateless_reset(&self, token: &[u8; 16]) -> bool {
683 self.remote_cid
684 .as_ref()
685 .is_some_and(|rcid| rcid.is_stateless_reset(token))
686 }
687
688 /// Make a datagram.
689 pub fn datagram<V: Into<Vec<u8>>>(
690 &mut self,
691 payload: V,
692 tos: IpTos,
693 stats: &mut Stats,
694 ) -> Datagram {
695 // Make sure to use the TOS value from before calling ecn::Info::on_packet_sent, which may
696 // update the ECN state and can hence change it - this packet should still be sent
697 // with the current value.
698 self.ecn_info.on_packet_sent(stats);
699 Datagram::new(self.local, self.remote, tos, payload.into())
700 }
701
702 /// Get local address as `SocketAddr`
703 pub const fn local_address(&self) -> SocketAddr {
704 self.local
705 }
706
707 /// Get remote address as `SocketAddr`
708 pub const fn remote_address(&self) -> SocketAddr {
709 self.remote
710 }
711
712 /// Whether the path has been validated.
713 pub const fn is_valid(&self) -> bool {
714 self.validated.is_some()
715 }
716
717 /// Handle a `PATH_RESPONSE` frame. Returns true if the response was accepted.
718 pub fn path_response(&mut self, response: [u8; 8], now: Instant, stats: &mut Stats) -> bool {
719 if let ProbeState::Probing { data, mtu, .. } = &mut self.state {
720 if response == *data {
721 let need_full_probe = !*mtu;
722 self.set_valid(now);
723 if need_full_probe {
724 qdebug!("[{self}] Sub-MTU probe successful, reset probe count");
725 self.probe(stats);
726 }
727 true
728 } else {
729 false
730 }
731 } else {
732 false
733 }
734 }
735
736 /// The path has been challenged. This generates a response.
737 /// This only generates a single response at a time.
738 pub fn challenged(&mut self, challenge: [u8; 8]) {
739 self.challenge = Some(challenge.to_owned());
740 }
741
742 /// At the next opportunity, send a probe.
743 /// If the probe count has been exhausted already, marks the path as failed.
744 fn probe(&mut self, stats: &mut Stats) {
745 let probe_count = match &self.state {
746 ProbeState::Probing { probe_count, .. } => *probe_count + 1,
747 ProbeState::ProbeNeeded { probe_count, .. } => *probe_count,
748 _ => 0,
749 };
750 self.state = if probe_count >= MAX_PATH_PROBES {
751 if self.ecn_info.is_marking() {
752 // The path validation failure may be due to ECN blackholing, try again without ECN.
753 qinfo!("[{self}] Possible ECN blackhole, disabling ECN and re-probing path");
754 self.ecn_info
755 .disable_ecn(stats, ecn::ValidationError::BlackHole);
756 ProbeState::ProbeNeeded { probe_count: 0 }
757 } else {
758 qinfo!("[{self}] Probing failed");
759 ProbeState::Failed
760 }
761 } else {
762 qdebug!("[{self}] Initiating probe");
763 ProbeState::ProbeNeeded { probe_count }
764 };
765 }
766
767 /// Returns true if this path have any probing frames to send.
768 pub const fn has_probe(&self) -> bool {
769 self.challenge.is_some() || self.state.probe_needed()
770 }
771
772 pub fn write_frames(
773 &mut self,
774 builder: &mut PacketBuilder,
775 stats: &mut FrameStats,
776 mtu: bool, // Whether the packet we're writing into will be a full MTU.
777 now: Instant,
778 ) -> bool {
779 if builder.remaining() < 9 {
780 return false;
781 }
782 // Send PATH_RESPONSE.
783 let resp_sent = if let Some(challenge) = self.challenge.take() {
784 qtrace!("[{self}] Responding to path challenge {}", hex(challenge));
785 builder.encode_varint(FrameType::PathResponse);
786 builder.encode(&challenge[..]);
787
788 // These frames are not retransmitted in the usual fashion.
789 stats.path_response += 1;
790
791 if builder.remaining() < 9 {
792 return true;
793 }
794 true
795 } else {
796 false
797 };
798
799 // Send PATH_CHALLENGE.
800 if let ProbeState::ProbeNeeded { probe_count } = self.state {
801 qtrace!("[{self}] Initiating path challenge {probe_count}");
802 let data = random::<8>();
803 builder.encode_varint(FrameType::PathChallenge);
804 builder.encode(&data);
805
806 // As above, no recovery token.
807 stats.path_challenge += 1;
808
809 self.state = ProbeState::Probing {
810 probe_count,
811 data,
812 mtu,
813 sent: now,
814 };
815 true
816 } else {
817 resp_sent
818 }
819 }
820
821 /// Write `ACK_FREQUENCY` frames.
822 pub fn write_cc_frames(
823 &mut self,
824 builder: &mut PacketBuilder,
825 tokens: &mut Vec<RecoveryToken>,
826 stats: &mut FrameStats,
827 ) {
828 self.rtt.write_frames(builder, tokens, stats);
829 }
830
831 pub fn lost_ack_frequency(&mut self, lost: &AckRate) {
832 self.rtt.frame_lost(lost);
833 }
834
835 pub fn acked_ecn(&mut self) {
836 self.ecn_info.acked_ecn();
837 }
838
839 pub fn lost_ecn(&mut self, pt: PacketType, stats: &mut Stats) {
840 self.ecn_info.lost_ecn(pt, stats);
841 }
842
843 pub fn acked_ack_frequency(&mut self, acked: &AckRate) {
844 self.rtt.frame_acked(acked);
845 }
846
847 /// Process a timer for this path.
848 /// This returns true if the path is viable and can be kept alive.
849 pub fn process_timeout(&mut self, now: Instant, pto: Duration, stats: &mut Stats) -> bool {
850 if let ProbeState::Probing { sent, .. } = &self.state {
851 if now >= *sent + pto {
852 self.probe(stats);
853 }
854 }
855 if matches!(self.state, ProbeState::Failed) {
856 // Retire failed paths immediately.
857 false
858 } else if self.primary {
859 // Keep valid primary paths otherwise.
860 true
861 } else if matches!(self.state, ProbeState::Valid) {
862 // Retire validated, non-primary paths.
863 // Allow more than `2 * MAX_PATH_PROBES` times the PTO so that an old
864 // path remains around until after a previous path fails.
865 let count = u32::try_from(2 * MAX_PATH_PROBES + 1).expect("result fits in u32");
866 self.validated
867 .is_some_and(|validated| validated + (pto * count) > now)
868 } else {
869 // Keep paths that are being actively probed.
870 true
871 }
872 }
873
874 /// Return the next time that this path needs servicing.
875 /// This only considers retransmissions of probes, not cleanup of the path.
876 /// If there is no other activity, then there is no real need to schedule a
877 /// timer to cleanup old paths.
878 pub fn next_timeout(&self, pto: Duration) -> Option<Instant> {
879 if let ProbeState::Probing { sent, .. } = &self.state {
880 Some(*sent + pto)
881 } else {
882 None
883 }
884 }
885
886 /// Get the RTT estimator for this path.
887 pub const fn rtt(&self) -> &RttEstimate {
888 &self.rtt
889 }
890
891 /// Mutably borrow the RTT estimator for this path.
892 pub fn rtt_mut(&mut self) -> &mut RttEstimate {
893 &mut self.rtt
894 }
895
896 /// Mutably borrow the PMTUD discoverer for this path.
897 pub fn pmtud_mut(&mut self) -> &mut Pmtud {
898 self.sender.pmtud_mut()
899 }
900
901 /// Read-only access to the owned sender.
902 pub const fn sender(&self) -> &PacketSender {
903 &self.sender
904 }
905
906 /// Pass on RTT configuration: the maximum acknowledgment delay of the peer,
907 /// and maybe the minimum delay.
908 pub fn set_ack_delay(
909 &mut self,
910 max_ack_delay: Duration,
911 min_ack_delay: Option<Duration>,
912 ack_ratio: u8,
913 ) {
914 let ack_delay = min_ack_delay.map_or_else(
915 || PeerAckDelay::fixed(max_ack_delay),
916 |m| {
917 PeerAckDelay::flexible(
918 max_ack_delay,
919 m,
920 ack_ratio,
921 self.sender.cwnd(),
922 self.plpmtu(),
923 self.rtt.estimate(),
924 )
925 },
926 );
927 self.rtt.set_ack_delay(ack_delay);
928 }
929
930 /// Initialize the RTT for the path based on an existing estimate.
931 pub fn prime_rtt(&mut self, rtt: &RttEstimate) {
932 self.rtt.prime_rtt(rtt);
933 }
934
935 /// Record received bytes for the path.
936 pub fn add_received(&mut self, count: usize) {
937 self.received_bytes = self.received_bytes.saturating_add(count);
938 }
939
940 /// Record sent bytes for the path.
941 pub fn add_sent(&mut self, count: usize) {
942 self.sent_bytes = self.sent_bytes.saturating_add(count);
943 }
944
945 /// Record a packet as having been sent on this path.
946 pub fn packet_sent(&mut self, sent: &mut SentPacket, now: Instant) {
947 if !self.is_primary() {
948 sent.clear_primary_path();
949 }
950 self.sender.on_packet_sent(sent, self.rtt.estimate(), now);
951 }
952
953 /// Discard a packet that previously might have been in-flight.
954 pub fn discard_packet(&mut self, sent: &SentPacket, now: Instant, stats: &mut Stats) {
955 if self.rtt.first_sample_time().is_none() {
956 // When discarding a packet there might not be a good RTT estimate.
957 // But discards only occur after receiving something, so that means
958 // that there is some RTT information, which is better than nothing.
959 // Two cases: 1. at the client when handling a Retry and
960 // 2. at the server when disposing the Initial packet number space.
961 qinfo!(
962 "[{self}] discarding a packet without an RTT estimate; guessing RTT={:?}",
963 now - sent.time_sent()
964 );
965 stats.rtt_init_guess = true;
966 self.rtt.update(
967 &self.qlog,
968 now - sent.time_sent(),
969 Duration::new(0, 0),
970 RttSource::Guesstimate,
971 now,
972 );
973 }
974
975 self.sender.discard(sent, now);
976 }
977
978 /// Record packets as acknowledged with the sender.
979 pub fn on_packets_acked(
980 &mut self,
981 acked_pkts: &[SentPacket],
982 ack_ecn: Option<ecn::Count>,
983 now: Instant,
984 stats: &mut Stats,
985 ) {
986 debug_assert!(self.is_primary());
987
988 let ecn_ce_received = self.ecn_info.on_packets_acked(acked_pkts, ack_ecn, stats);
989 if ecn_ce_received {
990 let cwnd_reduced = self
991 .sender
992 .on_ecn_ce_received(acked_pkts.first().expect("must be there"), now);
993 if cwnd_reduced {
994 self.rtt.update_ack_delay(self.sender.cwnd(), self.plpmtu());
995 }
996 }
997
998 self.sender
999 .on_packets_acked(acked_pkts, &self.rtt, now, stats);
1000 }
1001
1002 /// Record packets as lost with the sender.
1003 pub fn on_packets_lost(
1004 &mut self,
1005 prev_largest_acked_sent: Option<Instant>,
1006 confirmed: bool,
1007 lost_packets: &[SentPacket],
1008 stats: &mut Stats,
1009 now: Instant,
1010 ) {
1011 debug_assert!(self.is_primary());
1012 let cwnd_reduced = self.sender.on_packets_lost(
1013 self.rtt.first_sample_time(),
1014 prev_largest_acked_sent,
1015 self.rtt.pto(confirmed), // Important: the base PTO, not adjusted.
1016 lost_packets,
1017 stats,
1018 now,
1019 );
1020 if cwnd_reduced {
1021 self.rtt.update_ack_delay(self.sender.cwnd(), self.plpmtu());
1022 }
1023 }
1024
1025 /// Determine whether we should be setting a PTO for this path. This is true when either the
1026 /// path is valid or when there is enough remaining in the amplification limit to fit a
1027 /// full-sized path (i.e., the path MTU).
1028 pub fn pto_possible(&self) -> bool {
1029 // See the implementation of `amplification_limit` for details.
1030 self.amplification_limit() >= self.plpmtu()
1031 }
1032
1033 /// Get the number of bytes that can be written to this path.
1034 pub fn amplification_limit(&self) -> usize {
1035 if matches!(self.state, ProbeState::Failed) {
1036 0
1037 } else if self.is_valid() {
1038 usize::MAX
1039 } else {
1040 self.received_bytes
1041 .checked_mul(3)
1042 .map_or(usize::MAX, |limit| {
1043 let budget = if limit == 0 {
1044 // If we have received absolutely nothing thus far, then this endpoint
1045 // is the one initiating communication on this path. Allow enough space for
1046 // probing.
1047 self.plpmtu() * 5
1048 } else {
1049 limit
1050 };
1051 budget.saturating_sub(self.sent_bytes)
1052 })
1053 }
1054 }
1055
1056 /// Update the `NeqoQLog` instance.
1057 pub fn set_qlog(&mut self, qlog: NeqoQlog) {
1058 self.sender.set_qlog(qlog);
1059 }
1060 }
1061
1062 impl Display for Path {
1063 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1064 if self.is_primary() {
1065 write!(f, "pri-")?; // primary
1066 }
1067 if !self.is_valid() {
1068 write!(f, "unv-")?; // unvalidated
1069 }
1070 write!(f, "path")?;
1071 if let Some(entry) = self.remote_cid.as_ref() {
1072 write!(f, ":{}", entry.connection_id())?;
1073 }
1074 write!(f, " {}->{}", self.local, self.remote)?;
1075 Ok(())
1076 }
1077 }