discussion: re-exporting rustls-pki-types

[jsha]

Pulling out a conversation from #1651 (comment):

One question I've had is if we should be re-exporting the pki-types, maybe as rustls::types? I think that would make life a bit easier? We could do the same across some of the other crates, I suppose.

My feeling is no. We can document that rustls depends on pki-types 1.0, but I think the pattern of re-exporting a crate in multiple places is confusing.

One of my very confusing experiences as a Rust beginner was noticing that hyper::Response and http::Response have the same documentation, the same methods, and so on, but are in different libraries. It's not documented that one is actually a re-export of the other, so I thought it might have been copy-pasted code or an older version of the same library. I wound up spending some time looking carefully for differences to see why these were different types, and of course found none.

[djc]

Fair enough. I agree the documentation situation for re-exports is pretty weak, but I like using them in practice -- avoiding the extra import and (hopefully not much in this case, but in many other situations) the coupled version tracking. Maybe this needs a rustdoc feature to clearly highlight re-exports? Would be a nice to have IMO.

[ctz]

I quite like reexports, and think they work well if

• used sparingly,
• they're dependencies that are absolutely required for 99% of uses of the "primary" crate. I think pki-types satisfies that; but not (eg) webpki.
• are kept "flat", eg. in some crate there are a large number of transitive reexports of lower-level crates (which also reexport their dependencies) which is a bit much. It leads to things like the rsa crate transitively reexporting rand_core many times through the reexports of all its dependencies.

[cpu]

they're dependencies that are absolutely required for 99% of uses of the "primary" crate. I think pki-types satisfies that; but not (eg) webpki.

Having done a few dependent crate updates at this point I agree with this assessment RE: pki-types. The dependent crates I've been updating don't use pki-types anywhere except for interacting with rustls. Having to carry and version an independent dependency on pki-types feels like noise that could be cut out with a re-export.

[jsha]

Reopening discussion to consider rustls/pki-types#24.

Also I wanted to note (and this is clearly a rustdoc bug): the rustls re-exports will show Available on crate feature alloc only for some items like CertificateDer::into_owned, even though rustls doesn't have a crate feature alloc.

[djc]

Also I wanted to note (and this is clearly a rustdoc bug): the rustls re-exports will show Available on crate feature alloc only for some items like CertificateDer::into_owned, even though rustls doesn't have a crate feature alloc.

Should we file for this?

Why is it useful to reopen this issue rather than discussing on the PR itself?