Vor dem Upgrade ablehnen

check_request weiß, wer werten darf, und nichts fragt es. Wenn handle_connection läuft, hat die Bibliothek schon 101 gesendet, also kommt der Handler zu spät, um mit einem Status abzulehnen. Die Entscheidung muss im Handshake laufen, nachdem die Bibliothek die Anfrage gelesen hat und bevor sie antwortet. Die Bibliothek hat genau dafür einen Platz.

Der Anfrage-Hook

serve nimmt ein Schlüsselwortargument, process_request: eine Funktion, die die Bibliothek einmal pro Handshake als process_request(connection, request) aufruft, nachdem sie die Anfrage gelesen hat und bevor sie irgendeine Antwort schreibt. request.path ist das ganze Anfrageziel samt Query, und request.headers ist dasselbe Headers-Objekt, das du in Lektion 2 gelesen hast. Was die Funktion zurückgibt, entscheidet, was als Nächstes passiert:

• None bedeutet “mach weiter”: Die Bibliothek antwortet 101 und ruft deinen Handler auf, wie bisher immer.

• Ein Antwortobjekt bedeutet “sende stattdessen das hier”: Die Bibliothek schreibt diese Antwort, schließt die Verbindung und ruft deinen Handler nie auf.

GET /score, no token
  process_request returns a response:
    HTTP/1.1 401 Unauthorized
    WWW-Authenticate: Bearer
  no WebSocket connection; the handler never runs

GET /watch
  process_request returns None:
    HTTP/1.1 101 Switching Protocols
  then frames flow, and viewer_handler runs

In Worten: Zwei Handshakes kommen nebeneinander an. Der an /score ohne Token wird mit 401 und einer Bearer-Aufforderung beantwortet, und es entsteht nie eine WebSocket-Verbindung. Der an /watch passiert den Hook, bekommt seine 101 und wird ein Zuschauer.

Eine Antwort, die die Bibliothek baut

Die Bytes der Antwort schreibst du nicht selbst. Die Verbindung, die der Hook bekommt, hat dafür eine Methode: connection.respond(status, text) gibt eine Antwort mit diesem Status zurück, mit einem Klartext-Body, der text enthält, und mit den Headern, die die Bibliothek hinzufügt (Connection: close, Content-Length, Content-Type: text/plain; charset=utf-8, ein Date und ein Server). Die headers der Antwort lassen sich noch ändern, bevor du sie zurückgibst, und eine 401 sollte eine Aufforderung (Challenge) tragen, den Header, der dem Client sagt, wie er sich authentifizieren soll. Die Server in HTTP with Python haben www-authenticate: Bearer gesendet; hier:

response = connection.respond(401, "a valid scorekeeper token is needed\n")
response.headers["WWW-Authenticate"] = "Bearer"

Der Hook gibt dann response zurück.

Was sieht ein Client? In einem Lauf auf einem lokalen Computer hat ein Hook, der so eine Antwort zurückgab (mit dem kürzeren Text “a valid token is needed” und einem Zeilenumbruch), den Python-Client der Bibliothek InvalidStatus auslösen lassen, mit der Meldung server rejected WebSocket connection: HTTP 401. Seine Antwort hatte den Status 401, den Grund Unauthorized, die Header Connection: close, Content-Length: 24 (die Länge dieses Textes; der Text dieser Lektion ergibt 36), Content-Type: text/plain; charset=utf-8 und WWW-Authenticate: Bearer und genau diesen Text als Body. Der Handler wurde für diese /score-Anfrage nie aufgerufen, für eine /watch-Anfrage dagegen schon.

Eine Funktion, die eine Funktion erstellt

Der Hook nimmt genau zwei Argumente, connection und request, und die Bibliothek wählt sie. Das erwartete Token muss ihn auf andere Weise erreichen. make_handler(board) hatte denselben Bedarf: Es gibt einen verschachtelten handler(connection) zurück, der sich board merkt. make_request_check(expected) macht dasselbe mit dem Token. Es definiert ein verschachteltes process_request(connection, request), das check_request(request.path, request.headers, expected) aufruft, None zurückgibt, wenn diese Antwort None ist, und andernfalls die 401-Antwort mit ihrer Aufforderung baut und zurückgibt. Dann gibt make_request_check diese verschachtelte Funktion zurück, ohne sie aufzurufen. Das Token wird einmal gewählt, wenn der Server gebaut wird, und jeder Handshake danach wird damit geprüft.

In Kapitel 2 hat check_upgrade die Bytes der Antwort selbst zurückgegeben, Statuszeile und Header von Hand ausgeschrieben. Hier ist die Entscheidung deine und die Bytes sind die der Bibliothek.

Einbauen

open_server(board, *, serve=serve) wird zu open_server(board, token, *, serve=serve), und sein Aufruf von serve bekommt neben den Keepalive-Werten aus Kapitel 8 ein weiteres Schlüsselwortargument: process_request=make_request_check(token). Das main aus Kapitel 10 wird das Token mit read_token lesen und hier übergeben.

Der Text der Antwort nennt das Problem und sonst nichts. Er enthält nie das erwartete Token, und er wiederholt nie, was der Client gesendet hat. Das könnte ein echtes Token mit einem Tippfehler sein oder ein Token, das für einen anderen Dienst gedacht ist.

Deine Aufgabe

Schreibe in scoreboard_server.py make_request_check(expected) wie beschrieben und gib open_server seinen Parameter token und das Argument process_request. check_request aus Lektion 2 trifft weiterhin die Entscheidung.

Klicke auf Run. Der Abschnitt zu Lektion 3 baut deinen Hook mit dem erwarteten Token der Demo und ruft ihn zweimal mit einer Stellvertreter-Verbindung auf. Das respond dieses Stellvertreters gibt ein einfaches Objekt mit status_code, einem headers-Dictionary und body zurück, nicht die Antwort der Bibliothek, damit die Demo keinen Server braucht; der Lauf oben zeigt die echte. Eine fertige Version hat auf der Seite ausgegeben:

Lesson 3: the request hook
    /score without a token: 401, WWW-Authenticate: Bearer, body 'a valid scorekeeper token is needed\n'
    /watch: None (the handshake goes on to 101)

Klicke dann auf Submit.

Ein Punktezähler ohne das Token wird jetzt vor 101 abgelehnt, und Zuschauer brauchen weiterhin nichts. Die nächste Lektion stellt eine andere Frage über einen Handshake: nicht, wer ihn gesendet hat, sondern welche Webseite den Browser dazu gebracht hat, ihn zu senden.