Revise and add additional 0-rtt doc comments

quinn-rs / quinn

Async-friendly QUIC implementation in Rust

Apache License 2.0

3.57k stars 363 forks source link

Revise and add additional 0-rtt doc comments #1826

Open gretchenfrage opened 2 months ago

gretchenfrage commented 2 months ago

I had a hard time getting 0-RTT actually working in practice. It escalated to me forking rustls so I could put in a bunch of print statements. Although I did find the 0-rtt tests, there were some subtle enough pitfalls that I didn't notice the relevant ways my attempts were diverging.

In hopes of improving understandability and discoverability of this, this PR adds notes about these pitfalls to some of the doc comments, and also largely rewrites the doc comment for Connecting::into_0rtt to make its behavior more clear, especially across various edge cases.

This PR does not change any code or APIs.

gretchenfrage commented 2 months ago

Thanks for the feedback! Happy to workshop this into something we both think is good.

gretchenfrage commented 1 week ago

Thanks to some other changes that have been made to the code base since this was last reviewed, some of the "where should this be documented" questions sort of solved themselves. I've shuffled things around, changed some things, and tried to make sure the current revision reflects the feedback given.

Current change set:

Rustls-specific documentation on crypto::rustls::ServerConfig and crypto::rustls::ClientConfig
Non-Rustls-specific documentation Connection::into_0rtt
A warning regarding latency on SendStream::stopped

Thanks!