From fa5d9030a813c242bb0e900fb9e12cf668159f52 Mon Sep 17 00:00:00 2001 From: Ruud van Asseldonk Date: Sun, 1 Dec 2024 22:06:33 +0100 Subject: [PATCH] Add pointers about idle timeout in documentation I spent an evening debugging an application, where both ends of the connection were timing out at roughly the same time. I mistakenly assumed that 'on_timeout' would cause ping packets to be sent to keep the connection alive, but after reading through the RFC, it dawned on me that applications are responsible for keeping the connection alive, and Quiche merely detects the timeout. This design does make sense, but a remark like the one I'm adding here would have saved me a lot of time, so I hope it can be helpful to others in the future. --- quiche/src/lib.rs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/quiche/src/lib.rs b/quiche/src/lib.rs index 5e4d6ce6a8..9d41140be9 100644 --- a/quiche/src/lib.rs +++ b/quiche/src/lib.rs @@ -5850,6 +5850,15 @@ impl Connection { /// Processes a timeout event. /// /// If no timeout has occurred it does nothing. + /// + /// Note that while this method handles the _detection_ of timeouts, it + /// does not prevent them. When a `max_idle_timeout` is configured in the + /// transport parameters, the application must make sure to not be idle for + /// that long, either by sending data, or by calling [`send_ack_eliciting`] + /// if there is no data to send. See also the [Deferring Idle Timeout + /// section of RFC 9000][idle]. + /// + /// [idle]: https://www.rfc-editor.org/rfc/rfc9000.html#name-deferring-idle-timeout pub fn on_timeout(&mut self) { let now = time::Instant::now();