Close Both Ways

After Lesson 1, every conversation ends with one side hanging up. The server cannot tell a client that finished from a client whose program crashed, and neither side can say why it stopped. WebSocket has a proper ending for this, the closing handshake, and it is built from the close frames you encoded in Chapter 4.

The closing handshake

RFC 6455 describes it in sections 1.4, 5.5.1 and 7.1.1:

1. One side, either one, sends a close frame: opcode 8, a 2-byte code such as 1000 (“normal closure”), and an optional reason in UTF-8.

2. The other side answers with a close frame of its own. After sending a close, an endpoint sends no more data.

3. Once both closes have been exchanged, in the normal case the server closes the TCP connection first, and the client waits for it.

The picture shows both orders, the client first at the top and the server first below it. In each half, look at which side closes the TCP connection, and at what the client’s last recv returns.

In words, the top half: the client sends a masked close with code 1000 and the reason “done”; the server answers with an unmasked close carrying the same code and reason, then closes the TCP connection; the client’s next recv returns b"", and only then is the conversation over.

The RFC says the answering close “typically” echoes the code it received. This course echoes the code and the reason, which is exactly what the websockets library you meet in Chapter 6 does.

Why the server closes TCP first: RFC 6455 section 7.1.1 asks for it so that the server, not the client, holds the TIME_WAIT state, a short period during which the side that closed first keeps a record of the finished connection. That one sentence of TCP is all this lesson needs.

Two helpers

close_frame(event, *, mask_key=None) builds the answer to a close event. read_message reports a close as {"type": "close", "code": ..., "reason": ...}, so the answer is ws_frames.close_payload(event["code"], event["reason"]) in a close frame, masked when a mask_key is given, because a client’s answer must be masked like every client frame. A close 1000 “bye” is answered with these bytes:

88 05 03 e8 62 79 65

88 is a final close frame, 05 the payload length, 03 e8 the code 1000, and the last three bytes are “bye”.

wait_for_close(read_exact, role) reads events with ws_frames.read_message(read_exact, role=role) and drops each one until a close arrives, then returns its code. It is how a side that has already sent its close waits for the answer: anything else that arrives is data the peer sent before it saw the close, and it is read and thrown away.

Client first

This is the order in Run’s well-behaved conversation. After the last echo, client_conversation:

1. sends a masked close: client_frame(ws_frames.OP_CLOSE, ws_frames.close_payload(1000, "done"), random_bytes=random_bytes);

2. calls wait_for_close(read_exact, "client") for the server’s answer and keeps its code;

3. calls sock.recv(1) once more, which returns b"" when the server has closed TCP;

4. returns the echoes and that code.

Step 3 uses sock.recv directly, not read_exact, because here b"" is the expected ending, not an error.

On the server’s side, serve_conversation checks each event before replying: a close is answered with sock.sendall(close_frame(event)), and the function returns at once with {"messages": n, "code": event["code"]}. It reads nothing more. When it returns, the with block around the connection in the wiring closes the socket, which is the server closing TCP first.

Server first

The server starts the closing handshake when it reaches its limit, as in the lower half of the picture. After the echo that makes max_messages, it sends close 1000 with the reason “message limit reached”, calls wait_for_close(read_exact, "server"), and returns {"messages": n, "code": 1000}.

A client may have sent another text before the server’s close reached it. wait_for_close reads that text and drops it, because a server that has sent its close sends nothing more.

The client must be ready for this too. While it waits for an echo, a close may arrive instead. Then it answers with close_frame(event, mask_key=random_bytes(4)), calls sock.recv(1) for the end of the connection, and returns the echoes it has, with the close’s code.

The code nobody sends

A close frame may have an empty payload, 88 00 from a server. parse_close_payload reports it as code 1005, which RFC 6455 reserves as a label for “no status code was present”. Your Chapter 4 codec refuses to put 1005 in a frame: close_payload(1005) raises ValueError. So close_frame checks for 1005 first and answers an empty close with an empty close.

Run

Press Run. The output after this lesson:

A conversation:
client: {'echoes': ['hello', 'café ✓', 'third message'], 'code': 1000}
server: {'messages': 3, 'code': 1000}
server thread still running: False
A rude client:
client: the server closed the connection without a close frame
server: stopped by ValueError: (1002, 'the frame breaks the masking rule')
server thread still running: False

Both sides now report 1000: the conversation ended because both agreed it was over. The rude client is unchanged; that is Lesson 3’s.

Then press Submit. It runs close_frame and wait_for_close on their own, gives serve_conversation stand-in clients that close in each of the ways above, runs client_conversation against a stand-in server that answers its close and one that closes first, and has your client and your server close a conversation together.

A well-behaved peer now gets a clean ending. A peer that breaks the rules still kills the server’s thread with an exception, and the next lesson makes the server answer it with a close of its own.