docs(http/upgrade): document `linkerd-http-upgrade` #3531

cratelyn · 2025-01-15T21:34:18Z

some aspects of linkerd-http-upgrade are incompatible with the 1.0 interface of the http 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:

// Note: this relies on their only having been 2 Inner clones, so don't
// implement `Clone` for this type. [sic]
pub struct Http11Upgrade {
    half: Half,
    inner: Arc<Inner>,
}

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 we MUST 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.

Signed-off-by: katelyn martin <kate@buoyant.io>

rfc 9110 obsoletes the following rfc's: 2818, 7230, 7231, 7232, 7233, 7235, 7538, 7615, and 7694. this updates a comment related to connection upgrade logic, linking to the current rfc, 9110. this information now lives in section 9.3.6, paragraph 12. Signed-off-by: katelyn martin <kate@buoyant.io>

this function has since been renamed `halves()`. Signed-off-by: katelyn martin <kate@buoyant.io>

this adds a comment additionally clarifying that HTTP/2 does not support upgrades. Signed-off-by: katelyn martin <kate@buoyant.io>

this function performs some important behavior that we MUST implement, as a proxy/intermediary. to help elucidate the mandated behavior expected of us by the HTTP/1 specification, add documentation comments noting the related passages from rfc 9110 § 7.6.1. Signed-off-by: katelyn martin <kate@buoyant.io>

Signed-off-by: katelyn martin <kate@buoyant.io>

this comment is not true. this commit updates it, reflecting the current state of the upgrade body's `Drop` logic. Signed-off-by: katelyn martin <kate@buoyant.io>

note: this commit will not compile, code changes are intentionally elided from this commit. this commit upgrades hyper, http, tonic, prost, related dependencies, and their assorted cargo features. see <linkerd/linkerd2#8733>. see also: * #3379 * #3380 * #3382 * #3405 * hyperium/hyper#3796 * #3411 * #3421 * #3427 * #3428 * #3432 * #3433 * #3444 * #3445 * #3454 * #3455 * #3456 * #3457 * #3461 * #3459 * #3465 * #3466 * #3467 * #3468 * linkerd/linkerd2-proxy-api#421 * linkerd/linkerd2#13492 * linkerd/linkerd2#13493 * hyperium/hyper#3816 * #3472 * #3473 * #3479 * tokio-rs/tokio#7059 * #3509 * hyperium/http-body#140 * #3515 * hyperium/http-body#141 * #3530 * #3531 * #3540 * #3556 * #3558 * #3559 * #3564 * #3567 * #3573 * #3583 * hyperium/http-body#144 * #3585 * #3586 * #3597 * #3598 * #3611 * #3614 * #3615 * #3616 * #3647 * #3651 * #3653 * #3654 * #3655 * #3656 * #3657 * #3660 * #3671 * #3672 * #3673 * #3676 * hyperium/http-body#147 * #3692 * #3699 * #3700 * #3701 * #3708 * linkerd/drain-rs#36 * #3715 * #3717 * eminence/procfs#340 --- squash: chore(deps): add hyper-util workspace dependency chore(deps): add http-body-util workspace dependency chore(deps): upgrade linkerd2-proxy-api this commit represents main as of linkerd/linkerd2-proxy-api#421. Signed-off-by: katelyn martin <kate@buoyant.io>

## ✨ chore(deps): upgrade to hyperium 1.x crates this branch performs an exciting upgrade for our proxy. this branch upgrades a number of our dependencies so that we use the 1.0 release family of the `hyper` http framework, and its ecosystem. see the [v1.0 announcement][hyper-v1] for more information. this branch upgrades the following dependencies: * `h2`: 0.3 -> 0.4 * `http`: 0.2 -> 1 * `http-body`: 0.4 -> 1 * `hyper`: 0.14.32 -> 1 * `prost`: 0.12 -> 0.13 * `prost-build`: 0.12 -> 0.13 * `prost-types`: 0.12 -> 0.13 * `tonic`: 0.10 -> 0.12 * `tonic-build`: 0.10 -> 0.12 a `hyper-util` dependency is added, which provides among other things, legacy-compatible interfaces such as `hyper_util::client::legacy::Client`, or glue to use `hyper` with the tokio runtime. see <https://docs.rs/hyper-util/latest/hyper_util/> for more information. a `http-body-util` dependency is added, which provides a `BodyExt` trait and a channel-backed body for use in unit tests. the `deprecated` feature flag that was active on our `0.14` hyper dependency has been removed, along with the `stream` and `runtime` feature flags. the `linkerd2-proxy-api` dependency is updated. see: <linkerd/linkerd2-proxy-api#421> ### 📝 notes for review bear particular attention to changes involving `http_body::Body` middleware. the change from two separate `poll_data()` and `poll_trailers()` functions, to a single `poll_frame()` method, induces some subtle changes to various pieces of middleware. also bear in mind that failing to set a timer, in our case `hyper_util::rt::TokioTimer`, can cause http/2 clients, or http/1 and http/2 servers, to panic. make sure that any uses of `hyper::server::conn::http1::Builder`, `hyper::client::conn::http1::Builder`, or `hyper::client::conn::http2::Builder` install a timer. ### ❗ breaking change: `l5d-proxy-error` values the `l5d-proxy-error` header can be examined to observe the cause of proxy errors encountered when sending meshed traffic. by virtue of this using a newer `hyper` client in the proxy, some error messages may in turn look different. for example, an error like `"connect timed out after 1s"` may now appear as `"client error (Connect)"`. ### 📚 other notes this work, by virtue of touching so many parts of the system, is carried out in distinct commits. an initial commit upgrades the dependencies at th workspace level. subsequent commits will not compile if the `--workspace` flag is provided, but the intent of this branch is to update each crate individually. use commands like, e.g. `cargo check --tests -p linkerd-proxy-http` to build particular crates at intermediate commits within this branch. this commit is also only the final leaf in an _extended_ line of work. this has been done to mitigate the effort of reviewing this change, and the risk of churn in the event of any unanticipated errors. see the top-level comment in linkerd/linkerd2#8733 for an overview of all of the work that brought us to this juncture. [hyper-v1]: https://seanmonstar.com/blog/hyper-v1/ --- * chore(deps): upgrade to hyper 1.x note: this commit will not compile, code changes are intentionally elided from this commit. this commit upgrades hyper, http, tonic, prost, related dependencies, and their assorted cargo features. see <linkerd/linkerd2#8733>. see also: * #3379 * #3380 * #3382 * #3405 * hyperium/hyper#3796 * #3411 * #3421 * #3427 * #3428 * #3432 * #3433 * #3444 * #3445 * #3454 * #3455 * #3456 * #3457 * #3461 * #3459 * #3465 * #3466 * #3467 * #3468 * linkerd/linkerd2-proxy-api#421 * linkerd/linkerd2#13492 * linkerd/linkerd2#13493 * hyperium/hyper#3816 * #3472 * #3473 * #3479 * tokio-rs/tokio#7059 * #3509 * hyperium/http-body#140 * #3515 * hyperium/http-body#141 * #3530 * #3531 * #3540 * #3556 * #3558 * #3559 * #3564 * #3567 * #3573 * #3583 * hyperium/http-body#144 * #3585 * #3586 * #3597 * #3598 * #3611 * #3614 * #3615 * #3616 * #3647 * #3651 * #3653 * #3654 * #3655 * #3656 * #3657 * #3660 * #3671 * #3672 * #3673 * #3676 * hyperium/http-body#147 * #3692 * #3699 * #3700 * #3701 * #3708 * linkerd/drain-rs#36 * #3715 * #3717 * eminence/procfs#340 --- squash: chore(deps): add hyper-util workspace dependency chore(deps): add http-body-util workspace dependency chore(deps): upgrade linkerd2-proxy-api this commit represents main as of linkerd/linkerd2-proxy-api#421. Signed-off-by: katelyn martin <kate@buoyant.io> * chore(http/box): upgrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(hyper-balance): upgrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(http/retain): ugrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(http/stream-timeouts): upgrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(http/classify): upgrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(http/upgrade): upgrade to hyper 1.x NOTE: there is a comment noting that the upgrade middleware does not expect to be cloneable. it is unfortunately, however, at odds with the new bounds expected of extensions. so, `Http11Upgrade` is now Clone'able, but a comment is left in place noting this weakened invariant. it's worth investigating how upgrades have changed since, in more detail, but for the current moment we are interested in being especially conservative about changing behavior, and focusing on api changes like `Body::poll_frame(..)`. Signed-off-by: katelyn martin <kate@buoyant.io> * chore(metrics): upgrade to hyper 1.x a brief note; this commit happened to tickle an unfortunate sharp edge in `BoxBody` and `Full`'s respective constructors. type inference could not figure out how to construct the body, so we refrain from boxing the response body now. Signed-off-by: katelyn martin <kate@buoyant.io> * chore(http/metrics): upgrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(http/prom): upgrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(http/insert): upgrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(http/retry): deprecate linkerd-http-body-compat Signed-off-by: katelyn martin <kate@buoyant.io> * chore(mock/http-body): upgrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(http/retry): upgrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(proxy/tap): upgrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(proxy/http): update to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(app/core): upgrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(app/test): upgrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(app/admin): upgrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(app/outbound): upgrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(app/inbound): upgrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(app/integration): upgrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(app): upgrade to hyper 1.x Signed-off-by: katelyn martin <kate@buoyant.io> * chore(transport-header): update generated code Signed-off-by: katelyn martin <kate@buoyant.io> * chore(spiffe-proto): update generated code Signed-off-by: katelyn martin <kate@buoyant.io> * chore(opencensus-proto): update generated code Signed-off-by: katelyn martin <kate@buoyant.io> * chore(opentelemetry-proto): update generated code Signed-off-by: katelyn martin <kate@buoyant.io> * chore(deny.toml): update cargo-deny directives this commit updates the contents of `deny.toml`. Signed-off-by: katelyn martin <kate@buoyant.io> * chore: `compile` has been renamed to `compile_protos` this addresses deprecation warnings, updating calls to a function that has since been renamed. Signed-off-by: katelyn martin <kate@buoyant.io> * chore(deps): remove `linkerd-http-body-compat` dependencies this commit removes this crate, which we added to future proof code for this upgrade, from its dependents. Signed-off-by: katelyn martin <kate@buoyant.io> * chore(http/body-compat): remove `linkerd-http-body-compat` crate Signed-off-by: katelyn martin <kate@buoyant.io> * chore(deps): update to drain 0.2.1 see linkerd/drain-rs#41. Signed-off-by: katelyn martin <kate@buoyant.io> --------- Signed-off-by: katelyn martin <kate@buoyant.io>

cratelyn added 7 commits January 15, 2025 16:18

docs(http/upgrade): add crate-level docs, rfc link

c7a6ab6

Signed-off-by: katelyn martin <kate@buoyant.io>

nit(http/upgrade): update incorrect comment

52e3d41

this function has since been renamed `halves()`. Signed-off-by: katelyn martin <kate@buoyant.io>

docs(http/upgrade): add comments to wants_upgrade

be90317

this adds a comment additionally clarifying that HTTP/2 does not support upgrades. Signed-off-by: katelyn martin <kate@buoyant.io>

nit(http/upgrade): fix typo in Http11Upgrade comment

993e48c

Signed-off-by: katelyn martin <kate@buoyant.io>

docs(http/upgrade): update incorrect comment

317807a

this comment is not true. this commit updates it, reflecting the current state of the upgrade body's `Drop` logic. Signed-off-by: katelyn martin <kate@buoyant.io>

cratelyn marked this pull request as ready for review January 15, 2025 21:42

cratelyn requested a review from a team as a code owner January 15, 2025 21:42

sfleen approved these changes Jan 16, 2025

View reviewed changes

cratelyn merged commit a4a55fa into main Jan 16, 2025
15 checks passed

cratelyn deleted the kate/http-upgrade.2-docs-and-comments branch January 16, 2025 15:36

cratelyn mentioned this pull request Jan 15, 2025

proxy: Figure out the plan for Hyper 1.0 migration linkerd/linkerd2#8733

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(http/upgrade): document `linkerd-http-upgrade` #3531

docs(http/upgrade): document `linkerd-http-upgrade` #3531

Uh oh!

cratelyn commented Jan 15, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

docs(http/upgrade): document linkerd-http-upgrade #3531

docs(http/upgrade): document linkerd-http-upgrade #3531

Uh oh!

Conversation

cratelyn commented Jan 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

docs(http/upgrade): document `linkerd-http-upgrade` #3531

docs(http/upgrade): document `linkerd-http-upgrade` #3531

cratelyn commented Jan 15, 2025 •

edited

Loading