Should <NetworkingBackend>.start_tls() be an in-place interface?

[tomchristie]

Pull request #699 adds the networking backends to the public interface.
This is a follow-up that reviews one part of the interface.

The question is if we would like to change the interface of start_tls(), so that the following example from the docs...

# Open a TCP stream and upgrade it to SSL.
network_backend = httpcore.SyncBackend()
network_stream = network_backend.connect_tcp("www.example.com", 443)
network_stream = network_stream.start_tls(ssl_context, server_hostname="www.example.com")

# Send the HTTP request.
network_stream.write(request)

Would instead become this...

# Open a TCP stream and upgrade it to SSL.
network_backend = httpcore.SyncBackend()
network_stream = network_backend.connect_tcp("www.example.com", 443)
network_stream.start_tls(ssl_context, server_hostname="www.example.com")

# Send the HTTP request.
network_stream.write(request)

...

There is also an example in the network_stream extension docs...

# Formulate a CONNECT request...
#
# This will establish a connection to 127.0.0.1:8080, and then send the following...
#
# CONNECT http://www.example.com HTTP/1.1
# Host: 127.0.0.1:8080
url = httpcore.URL(b"http", b"127.0.0.1", 8080, b"http://www.example.com")
with httpcore.stream("CONNECT", url) as response:
    network_stream = response.extensions["network_stream"]

    # Upgrade to an SSL stream...
    network_stream = network_stream.start_tls(
        ssl_context=httpcore.default_ssl_context(),
        hostname=b"www.example.com",
    )

    # Manually send an HTTP request over the network stream, and read the response...
    #
    # For a more complete example see the httpcore `TunnelHTTPConnection` implementation.
    network_stream.write(b"GET / HTTP/1.1\r\nHost: example.com\r\n\r\n")
    data = network_stream.read()
    print(data)

Which would instead be this...

```python
# Formulate a CONNECT request...
#
# This will establish a connection to 127.0.0.1:8080, and then send the following...
#
# CONNECT http://www.example.com HTTP/1.1
# Host: 127.0.0.1:8080
url = httpcore.URL(b"http", b"127.0.0.1", 8080, b"http://www.example.com")
with httpcore.stream("CONNECT", url) as response:
    network_stream = response.extensions["network_stream"]

    # Upgrade to an SSL stream...
    network_stream.start_tls(
        ssl_context=httpcore.default_ssl_context(),
        hostname=b"www.example.com",
    )

    # Manually send an HTTP request over the network stream, and read the response...
    #
    # For a more complete example see the httpcore `TunnelHTTPConnection` implementation.
    network_stream.write(b"GET / HTTP/1.1\r\nHost: example.com\r\n\r\n")
    data = network_stream.read()
    print(data)

This would be in-line with start_tls from Python's asyncio stdlib interface.

There's a few different existing API styles out there - Trio and AnyIO use "instantiate a new wrapper class" style. The synchronous stdlib uses ssl.wrap_socket.

Having the .start_tls be a method on the network stream seems convenient for our interface, so I'd suggest we stick with it.

But should it be an in-place operation?

[tomchristie]

I'm not convinced that this is a genuinely valuable piece of work for us to undertake, or that the API is necessarily "better" so my suggestion would be that we leave it as it currently is.