🏆Capstone project: Finish the Client CLI

Until now you have stood on the server’s side of the scoreboard, deciding what to send, when to refuse and how to close. This lesson stands you on the other side of your own protocol. Everything the server decides reaches a client as a message, a close code or an exception, and a command-line client has to turn each of them into an exit status that a person, or a script, can act on.

scoreboard_client.py is half written. client_parser() declares the two commands, watch and score, and their options. The supplied main(argv=None, *, connect=connect) parses them, refuses a bad command line with parser.error (exit status 2: --points outside 1 to 10, a blank --team, a --wait out of range), reads the token file for score and returns 1 with one line on standard error if it cannot, and then returns whatever watch(...) or score(...) returns. format_snapshot(snapshot) turns a snapshot into one line, teams in the order the message lists them.

snapshot = {"version": 3, "scores": {"Owls": 4, "Foxes": 0}}
parts = []
for team in snapshot["scores"]:
    parts.append(f"{team} {snapshot['scores'][team]}")
line = f"version {snapshot['version']}: " + ", ".join(parts)
print(line)

Never go backwards

watch(url, max_messages, wait, *, connect=connect) connects, prints one line per snapshot with format_snapshot, and stops after max_messages lines. It applies the rule from Chapter 8’s lesson on reconnecting: a client never shows a board older than one it has already shown. Keep the version of the last snapshot printed, start below any real version (-1 works), and skip a snapshot whose version is not greater. Only printed lines count toward --max-messages.

The server already sends versions in order, but the client does not rely on the server alone: it keeps the rule even if a server, a proxy or a later version of your own code does not. Not every message is a snapshot. A valid error envelope is meant for a scorekeeper, so watch skips it. A score envelope breaks the protocol, because only the scorekeeper sends scores, and so does anything parse_message refuses.

How it ended decides the exit status

Every way the conversation can end has one exit status in the contract. For watch:

Every exit with 1 writes exactly one line to standard error that says why, with print(..., file=sys.stderr); standard output holds only snapshot lines. A refused handshake names its status, as in HTTP 503.

Why 1008 for a bad message? RFC 6455 section 7.4.1 makes 1008, policy violation, the generic code when no more specific one fits. 1003 is for a kind of data the endpoint cannot accept, such as a binary frame, and invalid UTF-8 is already failed by the library itself with 1007. Valid JSON that breaks the scoreboard’s rules is a matter of this protocol’s policy, as the server’s own no such path close is.

Two facts decide the order of your except clauses. TimeoutError is a kind of OSError, so its clause must come before an except OSError: that would otherwise catch it with the wrong message. And InvalidStatus is not an OSError at all: it is a WebSocketException, so it needs a clause of its own. Pass open_timeout, close_timeout and proxy=None to connect, as Chapter 6 did, and pass the wait to every recv, so no silent server can keep the client for ever.

The token goes in a header

score(url, token, team, points, *, connect=connect) sends one score and reports the answer. The token travels in the handshake, as an extra header:

headers = {"Authorization": f"Bearer {token}"}
with connect(url, additional_headers=headers, open_timeout=WAIT, close_timeout=WAIT, proxy=None) as connection:
    connection.send(text)

On a local computer, a server’s process_request hook read exactly one value, Bearer and the token, from a handshake sent that way. Chapter 9 also accepted ?token= in the URL, but only for a browser page, which cannot add the header. This client is not a browser, and a URL is exactly the kind of text that servers and proxies write into their logs.

Build the score envelope with scoreboard_messages.encode_message, send it once, and read one answer with recv(timeout=WAIT). A snapshot answer is printed with format_snapshot, exit 0. An error envelope, a refused handshake, a close before the answer, a timeout or no connection is one line on standard error, exit 1. The line for a refused handshake names the status, such as HTTP 401, and never the token: the token appears on no stream.

watch does not reconnect when its connection drops. Reconnecting with backoff, from Chapter 8, stays something you can recognize rather than something this client does: it ends, and its exit status says how.

Your task

Write watch and score. Most of each is except clauses. Then run seven commands of your client against a scoreboard written for this course, so that a mistake you see is the client’s and not your server’s:

python pl_ws.py client-main

A finished version, run on the site, printed, after the list of commands:

1 watch | version 0: Owls 0, Foxes 0, Herons 0
1 watch | version 1: Owls 3, Foxes 0, Herons 0
1 watch | version 2: Owls 3, Foxes 2, Herons 0
1 watch exited with 0
2 score | version 1: Owls 3, Foxes 0, Herons 0
2 score exited with 0
3 score | version 2: Owls 3, Foxes 2, Herons 0
3 score exited with 0
4 wrong token ! the scoreboard refused the connection: HTTP 401
4 wrong token exited with 1
5 unknown team ! the scoreboard refused the score: unknown team
5 unknown team exited with 1

Lines with | went to standard output and lines with ! to standard error. Command 6, --points 11, is refused by the supplied main with its usage and exit status 2, and command 7 watches a port where nothing listens and exits with 1. Your own lines on standard error may say it differently. Then run the tests and ask for their exit status:

python -m pytest -q
echo $?

The six assert False tests still fail, so echo $? prints 1: you have not written a test of your own for either program yet. That is Lesson 4.