Remove top-level re-exports

[cpu]

This branch removes all top-level re-exports except for the "paved path" re-exports we expect all-to-most users will be using.

An informal poll indicates users find it confusing when there are multiple names for the same things. See #1386 for more discussion.

[djc]

It makes sense to me to relegate the crypto parts to a module, as I think these will be rarely used (assuming most users will pick the default crypto provider or select a crypto provider via a feature flag).

For the others, I really don't see removing the top-level re-exports as a good idea. These have been at the top-level forever, so we'd be putting every downstream user through a bunch of churn for the sole goal of removing the re-exports.

I suppose we could alternatively remove the "original" re-exports from the client/server modules instead, which I personally also find unattractive because the documentation for those modules provides a good place to find everything related to that particular context.

So, after considering all the context, I would prefer to keep the situation as-is for ClientConnection, ClientConfig, ServerName, ServerConfig and ServerConnection.

[cpu]

I would prefer to keep the situation as-is for ClientConnection, ClientConfig, ServerName, ServerConfig and ServerConnection.

@ctz @jsha What do you think of this proposal?

[ctz]

I think of the API as being in two groups -- let's call them "paved path" and "detail". "Paved path" would be types that every user will need¹, and I think it makes sense for these types to be front-and-centre at the top of the crate path hierarchy. "Detail" would be for complex uses, or types that need to be public but aren't directly referred to by name², and everything else.

For these commits, I think the first 6 are "detail" that deserve to be lower down in the hierarchy rather than the top level. The rest of the commits I think are "paved path" types that deserve a place at the top of the hierarchy, but shouldn't be lost further down.

Footnotes

1. I'm assuming every user is interested in being a TLS server and client -- probably not accurate. ↩

2. example: rustls::client::WantsClientCert -- needs to be public, but would never be named ↩

[cpu]

@ctz What you describe makes sense to me, and I would be OK with leaving the server/client re-exports if we additionally moved some of your comment to a CONTRIBUTING.md style guide update to help evaluate additional re-exports in the future (happy to do that in this branch, or as a follow-up).

I'd like Jsha to have a chance to weigh in before I make updates to the branch since he opened #1386. Let's table this until then?

[jsha]

Yes this makes sense to me. As I understand it: we would keep the five "paved path" types we're talking about exported in two places, because even across a breaking release, it's not worth breaking someone's code over. The types that aren't yet in a release would get a single name (under a module). And for new "paved path" types, that's presumably a discussion for #1386 / a contibuting.md update. 👍

[cpu]

I've restored the "paved path" re-exports and tacked on an update to CONTRIBUTING.md to mention this subject.

[djc]

Thanks for getting this done!