Add pointers about idle timeout in documentation

[ruuda]

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.

[LPardue]

Adding a note to help users seems sensible but I don't think the proposal covers the considerations with enough nuance.

The QUIC idle timeout is negotiated between endpoints, so it doesn't necessarily matter what the local endpoint configured, since the peer can affect it. This suggests that we might want to expose the value of the idle timeout. timeout() and timeout_instant() can return values unrelated to the idle timeout, so aren't necessarily correct.

Also, idle timeout is a useful feature of QUIC, so we shouldn't unilaterally recommend that applications keep a connection alive when there may be no good reason to. The RFC text seems sufficient in terms of guidance. Pointing to the functions that reset the idle timer seems helpful though.

[hawkinsw]

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.

Thank you for taking the initiative on adding documentation for on_timeout. In an application I am writing I, too, struggled with using this function correctly. I will defer to the experts on the best way to improve the documentation (e.g., you and @LPardue ), but I know that more documentation will really help users like me!

Thank you, again!