Add websocket subprotocol support

## Rationale:

We have to manually do this currently even while it should be part of the handshake.

This leads to ignorance of this feature, and chrome not working due to a missing header when testing only in firefox (which ignores if none of sent subprotocols come back)

## Implementation and usage:

I’m adding a kwarg to `do_handshake` which allows the user to specifiy subprotocols his/her client speaks. `do_handshake` returns an additional header with the chosen protocol if the handshake is successful. This doesn’t break the API in any way.

If the server speaks any of the supplied subprotocols, the first protocol spoken by both is selected from the the client-supplied list, else the handshake fails. Essentially this means that you order the `protocols` sequence by preference: best protocol first, worst last.

## Open Questions:

1. The agreed-upon protocol is valuable information not only for the Server, but the user: If we speak multiple protocols, we want to know which one the handshake selected. The user has to extract it from the headers, which are simply a sequence and no dict, making this impractical.

    Should we change the response tuple to include the protocol as fifth mamber? This would break unpacking assignments like this:

        ```python
        >>> code, response_headers, parser, writer = do_handshake('get', headers, transport)
        Traceback (most recent call last):
          File "<stdin>", line 1, in <module>
        ValueError: too many values to unpack (expected 4)
        ```

        We could also return something unpackable to 4 elemets that also has a “protocol” field, but that would make the code more complex (tuples are very useful to avoid creating Java-style result-classes).

2. Autobahn|Python forbids duplicate mentions of protocols in the comma-separated list sent by the server. Should we also fail the handshake when this happens or be more lenient?

Author: flying-sheep

aiohttp/websocket.py

@@ -21,7 +21,7 @@
 
 WS_KEY = b'258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
 WS_HDRS = ('UPGRADE', 'CONNECTION',
-           'SEC-WEBSOCKET-VERSION', 'SEC-WEBSOCKET-KEY')
+           'SEC-WEBSOCKET-VERSION', 'SEC-WEBSOCKET-KEY', 'SEC-WEBSOCKET-PROTOCOL')
 
 Message = collections.namedtuple('Message', ['tp', 'data', 'extra'])
 
@@ -182,10 +182,14 @@ def close(self, code=1000, message=b''):
             opcode=OPCODE_CLOSE)
 
 
-def do_handshake(method, headers, transport):
+def do_handshake(method, headers, transport, protocols=()):
     """Prepare WebSocket handshake. It return http response code,
     response headers, websocket parser, websocket writer. It does not
-    perform any IO."""
+    perform any IO.
+
+    `protocols` is a sequence of known protocols. On successful handshake,
+    the returned response headers contain the first protocol in this list
+    which the server also knows."""
 
     # WebSocket accepts only GET
     if method.upper() != 'GET':
@@ -201,6 +205,21 @@ def do_handshake(method, headers, transport):
         raise errors.HttpBadRequest(
             'No CONNECTION upgrade hdr: {}'.format(
                 headers.get('CONNECTION')))
+    
+    # find common sub-protocol between client and server
+    protocol = None
+    if 'SEC-WEBSOCKET-PROTOCOL' in headers:
+        req_protocols = {str(proto.strip()) for proto in
+            headers['SEC-WEBSOCKET-PROTOCOL'].split(',')}
+        
+        for proto in protocols:
+            if proto in req_protocols:
+                protocol = proto
+                break
+        else:
+            raise errors.HttpBadRequest(
+                'Client protocols {} don’t overlap server-known ones {}'
+                .format(protocols, req_protocols))
 
     # check supported version
     version = headers.get('SEC-WEBSOCKET-VERSION')
@@ -218,12 +237,17 @@ def do_handshake(method, headers, transport):
         raise errors.HttpBadRequest(
             'Handshake error: {!r}'.format(key)) from None
 
-    # response code, headers, parser, writer
-    return (101,
-            (('UPGRADE', 'websocket'),
+    response_headers = [('UPGRADE', 'websocket'),
              ('CONNECTION', 'upgrade'),
              ('TRANSFER-ENCODING', 'chunked'),
              ('SEC-WEBSOCKET-ACCEPT', base64.b64encode(
-                 hashlib.sha1(key.encode() + WS_KEY).digest()).decode())),
+                 hashlib.sha1(key.encode() + WS_KEY).digest()).decode())]
+    
+    if protocol:
+        response_headers.append(('SEC-WEBSOCKET-PROTOCOL', protocol))
+
+    # response code, headers, parser, writer
+    return (101,
+            response_headers,
             WebSocketParser,
             WebSocketWriter(transport))