README and examples use unavailable API

[str4d]

The README has this example code:

tokio-rustls/README.md

Lines 22 to 23 in 63b8d6f

	let mut root_cert_store = RootCertStore::empty();
	root_cert_store.add_trust_anchors(webpki_roots::TLS_SERVER_ROOTS.0.iter().map(|ta| {

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]

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]

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 (hyperium/tonic#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]

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]

I've opened hyperium/tonic#1510 about fixing the downstream instance of this issue that hit me.

[djc]

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

[pronebird]

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]

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