Support informational responses with HTTP/1.1 (#581)

* Support information responses with HTTP/1.1

* Add tests for 101 protocol switch

* Document handling a WebSocket session using the network_stream extension

Author: lovelydinosaur

docs/extensions.md

@@ -179,7 +179,9 @@ The interface provided by the network stream:
 
 This API can be used as the foundation for working with HTTP proxies, WebSocket upgrades, and other advanced use-cases.
 
-An example to demonstrate:
+##### `CONNECT` requests
+
+A proxy CONNECT request using the network stream:
 
 ```python
 # Formulate a CONNECT request...
@@ -206,6 +208,52 @@ with httpcore.stream("CONNECT", url) as response:
     print(data)
 ```
 
+##### `Upgrade` requests
+
+Using the `wsproto` package to handle a websockets session:
+
+```python
+import httpcore
+import wsproto
+import os
+import base64
+
+
+url = "http://127.0.0.1:8000/"
+headers = {
+    b"Connection": b"Upgrade",
+    b"Upgrade": b"WebSocket",
+    b"Sec-WebSocket-Key": base64.b64encode(os.urandom(16)),
+    b"Sec-WebSocket-Version": b"13"
+}
+with httpcore.stream("GET", url, headers=headers) as response:
+    if response.status != 101:
+        raise Exception("Failed to upgrade to websockets", response)
+
+    # Get the raw network stream.
+    network_steam = response.extensions["network_stream"]
+
+    # Write a WebSocket text frame to the stream.
+    ws_connection = wsproto.Connection(wsproto.ConnectionType.CLIENT)
+    message = wsproto.events.TextMessage("hello, world!")
+    outgoing_data = ws_connection.send(message)
+    network_steam.write(outgoing_data)
+
+    # Wait for a response.
+    incoming_data = network_steam.read(max_bytes=4096)
+    ws_connection.receive_data(incoming_data)
+    for event in ws_connection.events():
+        if isinstance(event, wsproto.events.TextMessage):
+            print("Got data:", event.data)
+
+    # Write a WebSocket close to the stream.
+    message = wsproto.events.CloseConnection(code=1000)
+    outgoing_data = ws_connection.send(message)
+    network_steam.write(outgoing_data)
+```
+
+##### Extra network information
+
 The network stream abstraction also allows access to various low-level information that may be exposed by the underlying socket:
 
 ```python

httpcore/_async/http11.py

@@ -153,7 +153,7 @@ async def _receive_response_headers(
 
         while True:
             event = await self._receive_event(timeout=timeout)
-            if isinstance(event, h11.Response):
+            if isinstance(event, (h11.Response, h11.InformationalResponse)):
                 break
 
         http_version = b"HTTP/" + event.http_version

httpcore/_sync/http11.py

@@ -153,7 +153,7 @@ def _receive_response_headers(
 
         while True:
             event = self._receive_event(timeout=timeout)
-            if isinstance(event, h11.Response):
+            if isinstance(event, (h11.Response, h11.InformationalResponse)):
                 break
 
         http_version = b"HTTP/" + event.http_version

tests/_async/test_http11.py

@@ -206,3 +206,29 @@ async def test_http11_request_to_incorrect_origin():
     async with AsyncHTTP11Connection(origin=origin, stream=stream) as conn:
         with pytest.raises(RuntimeError):
             await conn.request("GET", "https://other.com/")
+
+
+@pytest.mark.anyio
+async def test_http11_upgrade_connection():
+    origin = Origin(b"https", b"example.com", 443)
+    stream = AsyncMockStream(
+        [
+            b"HTTP/1.1 101 OK\r\n",
+            b"Connection: upgrade\r\n",
+            b"Upgrade: custom\r\n",
+            b"\r\n",
+            b"...",
+        ]
+    )
+    async with AsyncHTTP11Connection(
+        origin=origin, stream=stream, keepalive_expiry=5.0
+    ) as conn:
+        async with conn.stream(
+            "GET",
+            "https://example.com/",
+            headers={"Connection": "upgrade", "Upgrade": "custom"},
+        ) as response:
+            assert response.status == 101
+            network_stream = response.extensions["network_stream"]
+            content = await network_stream.read(max_bytes=1024)
+            assert content == b"..."

tests/_sync/test_http11.py

@@ -206,3 +206,29 @@ def test_http11_request_to_incorrect_origin():
     with HTTP11Connection(origin=origin, stream=stream) as conn:
         with pytest.raises(RuntimeError):
             conn.request("GET", "https://other.com/")
+
+
+
+def test_http11_upgrade_connection():
+    origin = Origin(b"https", b"example.com", 443)
+    stream = MockStream(
+        [
+            b"HTTP/1.1 101 OK\r\n",
+            b"Connection: upgrade\r\n",
+            b"Upgrade: custom\r\n",
+            b"\r\n",
+            b"...",
+        ]
+    )
+    with HTTP11Connection(
+        origin=origin, stream=stream, keepalive_expiry=5.0
+    ) as conn:
+        with conn.stream(
+            "GET",
+            "https://example.com/",
+            headers={"Connection": "upgrade", "Upgrade": "custom"},
+        ) as response:
+            assert response.status == 101
+            network_stream = response.extensions["network_stream"]
+            content = network_stream.read(max_bytes=1024)
+            assert content == b"..."