Support RFC 8441 CONNECT requests

This allows the `:protocol` pseudo header field when the method is
CONNECT as allowed in RFC 8441 for websocket over HTTP/2 support.

Note that this doesn't introduce any extra constraints on CONNECT
methods (other than allowing the `:protocol` header) and hence should
support any existing functionality.

Author: pgjones

HISTORY.rst

@@ -21,6 +21,8 @@ API Changes (Backward-Compatible)
   ``h2.events.PingAcknowledged`` is deprecated in favour of the identical
   ``h2.events.PingAckReceived``.
 - Added ``ENABLE_CONNECT_PROTOCOL`` to ``h2.settings.SettingCodes``.
+- Support ``CONNECT`` requests with a ``:protocol`` pseudo header
+  thereby supporting RFC 8441.
 
 Bugfixes
 ~~~~~~~~

h2/utilities.py

@@ -33,6 +33,7 @@
     b':authority', u':authority',
     b':path', u':path',
     b':status', u':status',
+    b':protocol', u':protocol',
 ])
 
 
@@ -47,13 +48,19 @@
     b':scheme', u':scheme',
     b':path', u':path',
     b':authority', u':authority',
-    b':method', u':method'
+    b':method', u':method',
+    b':protocol', u':protocol',
 ])
 
 
 _RESPONSE_ONLY_HEADERS = frozenset([b':status', u':status'])
 
 
+# A Set of pseudo headers that are only valid if the method is
+# CONNECT, see RFC 8441 § 5
+_CONNECT_REQUEST_ONLY_HEADERS = frozenset([b':protocol', u':protocol'])
+
+
 if sys.version_info[0] == 2:  # Python 2.X
     _WHITESPACE = frozenset(whitespace)
 else:  # Python 3.3+
@@ -323,6 +330,7 @@ def _reject_pseudo_header_fields(headers, hdr_validation_flags):
     """
     seen_pseudo_header_fields = set()
     seen_regular_header = False
+    method = None
 
     for header in headers:
         if _custom_startswith(header[0], b':', u':'):
@@ -344,18 +352,25 @@ def _reject_pseudo_header_fields(headers, hdr_validation_flags):
                     "Received custom pseudo-header field %s" % header[0]
                 )
 
+            if header[0] in (b':method', u':method'):
+                if not isinstance(header[1], bytes):
+                    method = header[1].encode('utf-8')
+                else:
+                    method = header[1]
+
         else:
             seen_regular_header = True
 
         yield header
 
     # Check the pseudo-headers we got to confirm they're acceptable.
     _check_pseudo_header_field_acceptability(
-        seen_pseudo_header_fields, hdr_validation_flags
+        seen_pseudo_header_fields, method, hdr_validation_flags
     )
 
 
 def _check_pseudo_header_field_acceptability(pseudo_headers,
+                                             method,
                                              hdr_validation_flags):
     """
     Given the set of pseudo-headers present in a header block and the
@@ -394,6 +409,13 @@ def _check_pseudo_header_field_acceptability(pseudo_headers,
                 "Encountered response-only headers %s" %
                 invalid_request_headers
             )
+        if method != b'CONNECT':
+            invalid_headers = pseudo_headers & _CONNECT_REQUEST_ONLY_HEADERS
+            if invalid_headers:
+                raise ProtocolError(
+                    "Encountered connect-request-only headers %s" %
+                    invalid_headers
+                )
 
 
 def _validate_host_authority_header(headers):

test/test_invalid_headers.py

@@ -54,6 +54,7 @@ class TestInvalidFrameSequences(object):
         base_request_headers + [('name', 'value with trailing space ')],
         [header for header in base_request_headers
          if header[0] != ':authority'],
+        [(':protocol', 'websocket')] + base_request_headers,
     ]
     server_config = h2.config.H2Configuration(
         client_side=False, header_encoding='utf-8'

test/test_rfc8441.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+"""
+test_rfc8441
+~~~~~~~~~~~~
+
+Test the RFC 8441 extended connect request support.
+"""
+import h2.config
+import h2.connection
+import h2.events
+
+
+class TestRFC8441(object):
+    """
+    Tests that the client supports sending an extended connect request
+    and the server supports receiving it.
+    """
+
+    def test_can_send_headers(self, frame_factory):
+        headers = [
+            (b':authority', b'example.com'),
+            (b':path', b'/'),
+            (b':scheme', b'https'),
+            (b':method', b'CONNECT'),
+            (b':protocol', b'websocket'),
+            (b'user-agent', b'someua/0.0.1'),
+        ]
+
+        client = h2.connection.H2Connection()
+        client.initiate_connection()
+        client.send_headers(stream_id=1, headers=headers)
+
+        server = h2.connection.H2Connection(
+            config=h2.config.H2Configuration(client_side=False)
+        )
+        events = server.receive_data(client.data_to_send())
+        event = events[1]
+        assert isinstance(event, h2.events.RequestReceived)
+        assert event.stream_id == 1
+        assert event.headers == headers