docs(http/upgrade): document linkerd-http-upgrade
#3531
Merged
+62
−12
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.
some aspects of
linkerd-http-upgrade
are incompatible with the 1.0 interface of thehttp
crate (see: hyperium/http#395, linkerd/linkerd2#8733).this new bound requiring that extensions must now be cloneable motivated me to read through this library's internals to gain a lucid understanding of how it works, in order to understand how to gracefully address this comment affixed to the
linkerd_http_upgrade::upgrade::Http11Upgrade
request/response extension:broadly, this library deals with some moderately arcane corners of the HTTP protocol family. the
Upgrade
header is not supported in HTTP/2, and was not yet introduced in HTTP/1.0, so it is a feature specific to HTTP/1.1. moreover, some behavior provided by this library falls into parts of the spec(s) that weMUST
uphold, and isn't currently well documented.this branch includes a sequence of commits adding documentation and additional comments linking to, and quoting, the relevant parts of RFC 9110. some links to RFC 7231, which was obsoleted by RFC 9110 since the original time of writing, are additionally updated.
some comments also did not accurately describe internal logic, or included typos, and are also updated.