Support connection Upgrade and CONNECT. #872

• Initially raised as discussion Trailing Data in WebSocket Upgrade Requests #871

In cases of CONNECT and Upgrade requests, it is necessary to handle the incoming data (h11.Connection.trailing_data).

https://h11.readthedocs.io/en/latest/api.html?highlight=trailing_data#switching-protocols

However, accessing trailing_data in HTTPCore requires a very lengthy property access.

with httpcore.ConnectionPool() as http:
    with http.stream("GET", url, headers=headers) as response:
        # Get the trailing data.
        trailing_data, _ = response.stream._stream._connection._h11_state.trailing_data

Making this accessible through the public API would be beneficial for developers using the "network_stream".

Related HTTPCore documentation: https://www.encode.io/httpcore/extensions/#network_stream

Here is what tomchristie suggested in the discussion. #871 (comment)

We could then either...

• Make the available through a publicly documented response extension.trailing_data
• Ensure that the is returned by the network stream, on the first .trailing_data``.read()

The second one of these is neatest from the user-perspective.

We'd probably implement that as a proxy class onto the underlying network stream, that's able to additionally deal with pushing the trailing data in the event back onto the stream...h11

# This kinda thing...
class UpgradeNetworkStream():
    def __init__(self, leading_data, network_stream):
        # We need to push any data that's already been read back onto the stream.
        self._leading_data = leading_data
        self._network_stream = network_stream

    def read(...)
        if self._leading_data:
            initial = self._leading_data
            self._leading_data = b''
            return initial
        else:
            return self._network_stream.read()