SSL configuration API could be improved.

[tomchristie]

Our SSL configuration currently uses the following flags:

• verify - Either True, False, or a <ca_bundle_path>, or an SSLContext.
• cert - Either a <cert_file> or a (<cert_file>, <key_file>) or a (<cert_file>, <key_file>, <password>).
• trust_env - Either True or False. Enables SSLKEYLOGFILE, SSL_CERT_FILE, SSL_CERT_DIR.
• http2 - Sets the alpn protocols to allow HTTP/2 negotiation.

We also have the helper httpx.create_ssl_context() function available.

We have this API because we've followed in the footsteps of requests, but I find the various overloadings a bit confusing, and I'm not wild about having a whole bunch of different configurations at the top-level, when we could instead define them in a way that more tightly binds them to the scope where they're actually used.

I've wondered if we'd provide a better UX if we instead had...

response = httpx.get(..., ssl=<ssl_context>)

And...

ssl_context = httpx.SSLContext(verify=..., cert=..., trust_env=..., http2=...)
response = httpx.get(..., ssl=ssl_context)

This also makes alternate options more obvious...

ssl_context = truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
response = httpx.get(..., ssl=ssl_context)

Which we can currently do that just fine with verify=... but it isn't an obvious API to me, given the overloaded meanings.

There's some further considerations we'd need to make here:

• Is changing the API worth it?
• trust_env is also used elsewhere in the client (proxy config and netrc configuration I think).
• http2 config is also passed through to the default transport.

I'm not sure this is worth us moving on, but maybe?...

[Kludex]

I'm going to provide some "analogous" discussion reference from uvicorn - just because we are also trying to improve the SSL context related settings over there, but the solution there is probably not a good one for here: encode/uvicorn#1815 (comment).