Audit default Builder options

[seanmonstar]

Prior to marking hyper 1.0, it would be wise to audit all the default options in the various connection Builders. While changing them would be a compilation breaking change, it would be a behavioral change. (We could add a note that default options are not meant to be relied upon, that setting them explicitly is better, and thus reserve the ability to change defaults?)

This issue balances two of hyper's tenets: Correct vs Flexible. The existence of an option fulfills flexible, but as that tenet description points out, we should favor the default being safer, since Correct is more important.

I know some of the options that should probably include defaults are slightly tricky: timeouts. They only work if a impl Timer is provided, otherwise they can't set any timeouts. But we can discuss here how best to handle that: default on but only enabled if a timer is provided, warn if a timer is not provided, or require a timer be provided.

Action Items

• Document that builder defaults are subject to change and not considered "stable" #3336
• Pick a default for HTTP/2 server max concurrent streams #3358
• Decide what to do about a missing Timer #3393
• Confirm all options have been audited

[seanmonstar]

One thing I was thinking about was that the defaults, whatever they are, shouldn't be relied upon. I'd like to document that, since we could want to either (a) add a new option with a default, or (b) adjust a default, with the goal of protecting the most people. There's a couple things now that are documented separately about stability, so I'd probably also add a # Stability section the main doc page. But it would also be good to add more details to each Builder docs.

I've added an action item.