search

rustls / tokio-rustls

Async TLS for the Tokio runtime
Apache License 2.0
118 stars 68 forks source link

README and examples use unavailable API #18

Open str4d opened 1 year ago

str4d commented 1 year ago

The README has this example code: https://github.com/rustls/tokio-rustls/blob/63b8d6f10392c1e7a1c81cf3c526c4d4054ff71d/README.md?plain=1#L22-L23

This API was added in rustls 0.21.6. However, Cargo.toml (for the latest published release) only require rustls 0.21.0, leading to compilation errors if someone updates tokio-rustls without also updating the rustls point release (and the error message does not make it obvious that this is the solution).

djc commented 1 year ago

I'm aware of this. How do you think we should address it? (Did you end up in a state where you're using a newer version of tokio-rustls, or just consuming the mainline README while using an older version of the relevant crates? Do you not update crates regularly?)

str4d commented 1 year ago

What happened is I upgraded a binary project from tonic 0.9 to tonic 0.10, in which the feature flag tls-webpki-roots is enabled. That update did not change the tokio-rustls version, so the versions of both that and rustls in my Cargo.lock remained at the version it was at when I added the tonic 0.9. It did however include the migration away from the deprecated rustls API (https://github.com/hyperium/tonic/pull/1443).

The "minimum correct fix" would have been for tonic to add a direct dependency on rustls = "0.21.6", ensuring the API they use is available. But that also applies to every downstream of this crate. If this crate had made that dependency bump when its examples were bumped, then all downstream consumers of this crate would have automatically handled the issue. But that is somewhat by happenstance; it would have been technically fine for this crate to have its 0.21.0 bound, as long as its examples were still recommending the older deprecated API (then downstreams would be doing something this crate didn't recommend).

This is one of those weird issues caused by crates re-exporting the public APIs of their dependencies; there is no way to easily constrain minimum patch updates of transient dependencies of a crate, without adding a direct dependency on that transient dependency, and while it's obvious in this case, it's not generally obvious that the re-exported API is not controlled by the patch revision of the re-exporting crate.

str4d commented 1 year ago

For this crate, I think it would be fine to just ensure that any compiling code in this repository (including examples) is using APIs that are part of the minimum versions selected for the crate's dependencies. If, for example, a Cargo.lock file had been checked in (as the new Cargo team guidance allows for), then this issue would likely have been discovered at the time the examples were updated, and the fact that the Cargo.lock file required a bump to get examples compiling would be a good indication that the Cargo.toml file also needed bumping.

str4d commented 1 year ago

I've opened https://github.com/hyperium/tonic/issues/1510 about fixing the downstream instance of this issue that hit me.

djc commented 1 year ago

9 did upgrade the dependency for the library, it just didn't get released.

pronebird commented 8 months ago

I am seeing unresolved imports tokio_rustls::rustls::OwnedTrustAnchor, tokio_rustls::rustls::ServerName while trying to compile the example code today. Also a lot of errors related to missing webpki_roots which I am not sure if I should pull it separately to compile examples. This is fairly confusing.

djc commented 8 months ago

You probably have a version mismatch between rustls and tokio-rustls versions.