Adjust terminology regarding tokens #2086
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
RFC 9000 presents some unfortunate complications to naming things. It introduces a concept of a "token" that may cause a connection to be validated early. In some ways, these tokens must be treated discretely differently based on whether they originated from a NEW_TOKEN frame or a Retry packet. It also introduces an unrelated concept of a "stateless reset token". If our code and documentation were to constantly use phrases like "token originating from NEW_TOKEN frame," that would be extremely cumbersome. Moreover, it would risk feeling like leaking spec internals to the user. As such, this commit tries to move things towards the following naming convention: - A token from a NEW_TOKEN frame is called a "validation token", or "address validation token", although the shorter form should be used most often. - A token from a Retry packet is called a "retry token". We should avoid saying "stateless retry token" because this phrase is not used at all in RFC 9000 and is confusingly similar to "stateless reset token". This commit changes public usages of that phrase. - In the generic case of either, we call it a "token". - We still call a stateless reset token a "reset token" or "stateless reset token".
Ralith
approved these changes
Dec 14, 2024
This was referenced Dec 19, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
RFC 9000 presents some unfortunate complications to naming things. It introduces a concept of a "token" that may cause a connection to be validated early. In some ways, these tokens must be treated discretely differently based on whether they originated from a NEW_TOKEN frame or a Retry packet. It also introduces an unrelated concept of a "stateless reset token".
If our code and documentation were to constantly use phrases like "token originating from NEW_TOKEN frame," that would be extremely cumbersome. Moreover, it would risk feeling like leaking spec internals to the user.
As such, this commit tries to move things towards the following naming convention:
A token from a NEW_TOKEN frame is called a "validation token", or "address validation token", although the shorter form should be used most often.
A token from a Retry packet is called a "retry token".
We should avoid saying "stateless retry token" because this phrase is not used at all in RFC 9000 and is confusingly similar to "stateless reset token". This commit changes public usages of that phrase.
In the generic case of either, we call it a "token".
We still call a stateless reset token a "reset token" or "stateless reset token".
Just recently, on the Discord, I noticed an example of someone mixing up "stateless reset" and "stateless retry". Notably, I wrote this code before I noticed that happening naturally. They're extremely easy to mix up.