Accept or Refuse the Upgrade

Your server can read a request and compute the accept value for its key. Now it has to decide: switch to WebSocket, or refuse. This lesson writes that decision, check_upgrade(request), which takes the dictionary from Lesson 2 and returns the bytes of the whole response.

The yes

For the RFC’s example request, the server’s answer is this, every line ending in \r\n:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

The status 101 Switching Protocols is in the 1xx class you met in HTTP with Python. Most 1xx statuses say that more HTTP is coming; this one says that what comes next is no longer HTTP. Upgrade: websocket and Connection: Upgrade repeat what the client asked for, now as the server’s agreement. Sec-WebSocket-Accept carries the value from Lesson 3. Then comes the empty line, and nothing else: no Content-Length, no body.

After that empty line, HTTP is finished on this connection. The bytes that follow, in either direction, are WebSocket frames, and the next chapter reads them.

Your server never sends Sec-WebSocket-Protocol or Sec-WebSocket-Extensions in its 101, because this course negotiates neither.

Tokens, not exact values

Before it says yes, the server checks that the client really asked. The Upgrade header must contain the token websocket, and Connection must contain the token upgrade, both without regard to case. Lesson 1 showed why an exact comparison fails: Connection: keep-alive, Upgrade asks for the upgrade just as well as Connection: Upgrade does.

has_token(value, token) answers the question for any comma-separated header value. Cut the value at every comma, strip each piece, lowercase it, and compare it with the token, also lowercased:

value = "keep-alive, Upgrade"
for item in value.split(","):
    print(item.strip().lower())

It is tempting to write "upgrade" in value.lower() instead. That finds upgrade inside upgrades too, and inside any longer word that contains it. Comparing whole tokens finds only the token, so has_token("upgrades", "upgrade") is False.

Checking the key

A key must be the base64 of 16 bytes. base64.b64decode will tell you, with one argument added. By default it skips characters that are not part of the base64 alphabet without a word, so a key with four ! in front of the RFC’s, !!!!dGhlIHNhbXBsZSBub25jZQ==, still decodes to the 16 bytes of the sample nonce. With validate=True it refuses that key and raises binascii.Error. Missing padding raises the same error either way.

binascii.Error is a kind of ValueError, so except ValueError: around the decode catches it. After a successful decode, check the length with len: dGhl is valid base64 but decodes to only 3 bytes.

Remember the doubled key from Lesson 2. Two Sec-WebSocket-Key lines arrive as one value with ", " in the middle, and a comma and a space are not base64 characters, so this check refuses that request too.

Two ways to say no

RFC 6455 lets a server refuse a handshake with an ordinary HTTP error, and this course uses exactly two.

400 Bad Request answers every request that is malformed or incomplete. check_upgrade returns a 400 when:

1. the method is not GET;

2. the version is not exactly HTTP/1.1;

3. there is no host header;

4. upgrade has no websocket token, or is missing;

5. connection has no upgrade token, or is missing;

6. sec-websocket-key or sec-websocket-version is missing;

7. the key is not strict base64;

8. the key does not decode to 16 bytes.

The RFC allows any version from HTTP/1.1 up, but no later version of HTTP uses this handshake, so your server accepts HTTP/1.1 exactly.

426 Upgrade Required answers a request that is complete and well formed but asks for a WebSocket version other than 13. It carries a Sec-WebSocket-Version: 13 header, which tells the client the version this server speaks, so a client that knows several versions can try again with that one. Check the version last, after every 400 rule has passed. Do not confuse it with 505 HTTP Version Not Supported, which is about the HTTP version in the request line, not the WebSocket version. RFC 6455 suggests 426 here and requires only the Sec-WebSocket-Version header, so 426 is this course’s choice: it names the reason for the refusal.

Both refusals are 4xx statuses, the class that says the client’s request is at fault. refuse(status) builds either one: the status line, for 426 the version header, then Content-Length: 0 and Connection: close, then the empty line. Content-Length: 0 says no body follows, and Connection: close says the server closes the connection after this answer. The two responses are:

HTTP/1.1 400 Bad Request
Content-Length: 0
Connection: close

HTTP/1.1 426 Upgrade Required
Sec-WebSocket-Version: 13
Content-Length: 0
Connection: close

A real server may refuse with other statuses as well. The RFC’s own example of a version mismatch answers 400 Bad Request with a Sec-WebSocket-Version header, and a server that checks where a connection comes from might answer 403 Forbidden, as Chapter 9 does. These two cover everything your server checks now.

RFC 6455 does not say in which order a server must check these rules, so a request with two faults could fairly get either status. Your server checks in the order of the list above, version last.

Your task

In ws_handshake.py, write these three functions, in this order:

1. has_token(value, token): True if any comma-separated item of value, stripped and lowercased, equals token lowercased.

2. refuse(status): the complete 400 or 426 response above, as bytes.

3. check_upgrade(request): a 400 or a 426 by the rules above, otherwise the 101 response with accept_value of the key, as bytes. Use headers.get(name, "") for a header that may be missing.

Press Run. The Lesson 4 section prints the 101 response for the RFC’s request as a bytes value, \r\n and all:

Lesson 4: check_upgrade
b'HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=\r\n\r\n'

That line is from a local run of the finished lesson. When yours matches, press Submit. The server side of the handshake is complete; the next lesson writes the client that asks.