Part 2 - Route & broadcast#
This is the second part of the tutorial.
In the first part, you created a server and connected one browser; you could play if you shared the same browser.
In this second part, you will connect a second browser; you can play from different browsers on a local network.
In the third part, you will deploy the game to the web; you can play from any browser connected to the Internet.
In the first part of the tutorial, you opened a WebSocket connection from a
browser to a server and exchanged events to play moves. The state of the game
was stored in an instance of the Connect4 class,
referenced as a local variable in the connection handler coroutine.
Now you want to open two WebSocket connections from two separate browsers, one for each player, to the same server in order to play the same game. This requires moving the state of the game to a place where both connections can access it.
Start a game#
We’ll start with the initialization sequence for the first player.
In main.js, define a function to send an initialization event when the
WebSocket connection is established, which triggers an open event:
function initGame(websocket) {
websocket.addEventListener("open", () => {
// Send an "init" event for the first player.
const event = { type: "init" };
websocket.send(JSON.stringify(event));
});
}
Update the initialization sequence to call initGame():
window.addEventListener("DOMContentLoaded", () => {
// Initialize the UI.
const board = document.querySelector(".board");
createBoard(board);
// Open the WebSocket connection and register event handlers.
const websocket = new WebSocket("ws://localhost:8001/");
initGame(websocket);
receiveMoves(board, websocket);
sendMoves(board, websocket);
});
In app.py, define a new handler coroutine — keep a copy of the
previous one to reuse it later:
import secrets
JOIN = {}
async def start(websocket):
# Initialize a Connect Four game, the set of WebSocket connections
# receiving moves from this game, and secret access token.
game = Connect4()
connected = {websocket}
join_key = secrets.token_urlsafe(12)
JOIN[join_key] = game, connected
try:
# Send the secret access token to the browser of the first player,
# where it'll be used for building a "join" link.
event = {
"type": "init",
"join": join_key,
}
await websocket.send(json.dumps(event))
# Temporary - for testing.
print("first player started game", id(game))
async for message in websocket:
print("first player sent", message)
finally:
del JOIN[join_key]
async def handler(websocket):
# Receive and parse the "init" event from the UI.
message = await websocket.recv()
event = json.loads(message)
assert event["type"] == "init"
# First player starts a new game.
await start(websocket)
In index.html, add an <a> element to display the link to share with
the other player.
<body>
<div class="actions">
<a class="action join" href="">Join</a>
</div>
<!-- ... -->
</body>
In main.js, modify receiveMoves() to handle the "init" message and
set the target of that link:
switch (event.type) {
case "init":
// Create link for inviting the second player.
document.querySelector(".join").href = "?join=" + event.join;
break;
// ...
}
Restart the WebSocket server and reload http://localhost:8000/ in the browser. There’s a link labeled JOIN below the board with a target that looks like http://localhost:8000/?join=95ftAaU5DJVP1zvb.
The server logs say first player started game .... If you click the board,
you see "play" events. There is no feedback in the UI, though, because
you haven’t restored the game logic yet.
Before we get there, let’s handle links with a join query parameter.
Join a game#
We’ll now update the initialization sequence to account for the second player.
In main.js, update initGame() to send the join key in the "init"
message when it’s in the URL:
function initGame(websocket) {
websocket.addEventListener("open", () => {
// Send an "init" event according to who is connecting.
const params = new URLSearchParams(window.location.search);
let event = { type: "init" };
if (params.has("join")) {
// Second player joins an existing game.
event.join = params.get("join");
} else {
// First player starts a new game.
}
websocket.send(JSON.stringify(event));
});
}
In app.py, update the handler coroutine to look for the join key in
the "init" message, then load that game:
async def error(websocket, message):
event = {
"type": "error",
"message": message,
}
await websocket.send(json.dumps(event))
async def join(websocket, join_key):
# Find the Connect Four game.
try:
game, connected = JOIN[join_key]
except KeyError:
await error(websocket, "Game not found.")
return
# Register to receive moves from this game.
connected.add(websocket)
try:
# Temporary - for testing.
print("second player joined game", id(game))
async for message in websocket:
print("second player sent", message)
finally:
connected.remove(websocket)
async def handler(websocket):
# Receive and parse the "init" event from the UI.
message = await websocket.recv()
event = json.loads(message)
assert event["type"] == "init"
if "join" in event:
# Second player joins an existing game.
await join(websocket, event["join"])
else:
# First player starts a new game.
await start(websocket)
Restart the WebSocket server and reload http://localhost:8000/ in the browser.
Copy the link labeled JOIN and open it in another browser. You may also open it in another tab or another window of the same browser; however, that makes it a bit tricky to remember which one is the first or second player.
You must start a new game when you restart the server.
Since games are stored in the memory of the Python process, they’re lost when you stop the server.
Whenever you make changes to app.py, you must restart the server,
create a new game in a browser, and join it in another browser.
The server logs say first player started game ... and second player
joined game .... The numbers match, proving that the game local
variable in both connection handlers points to same object in the memory of
the Python process.
Click the board in either browser. The server receives "play" events from
the corresponding player.
In the initialization sequence, you’re routing connections to start() or
join() depending on the first message received by the server. This is a
common pattern in servers that handle different clients.
Why not use different URIs for start() and join()?
Instead of sending an initialization event, you could encode the join key
in the WebSocket URI e.g. ws://localhost:8001/join/<join_key>. The
WebSocket server would parse websocket.path and route the connection,
similar to how HTTP servers route requests.
When you need to send sensitive data like authentication credentials to the server, sending it an event is considered more secure than encoding it in the URI because URIs end up in logs.
For the purposes of this tutorial, both approaches are equivalent because the join key comes from an HTTP URL. There isn’t much at risk anyway!
Now you can restore the logic for playing moves and you’ll have a fully functional two-player game.
Add the game logic#
Once the initialization is done, the game is symmetrical, so you can write a single coroutine to process the moves of both players:
async def play(websocket, game, player, connected):
...
With such a coroutine, you can replace the temporary code for testing in
start() by:
await play(websocket, game, PLAYER1, connected)
and in join() by:
await play(websocket, game, PLAYER2, connected)
The play() coroutine will reuse much of the code you wrote in the first
part of the tutorial.
Try to implement this by yourself!
Keep in mind that you must restart the WebSocket server, reload the page to start a new game with the first player, copy the JOIN link, and join the game with the second player when you make changes.
When play() works, you can play the game from two separate browsers,
possibly running on separate computers on the same local network.
A complete solution is available at the bottom of this document.
Watch a game#
Let’s add one more feature: allow spectators to watch the game.
The process for inviting a spectator can be the same as for inviting the second player. You will have to duplicate all the initialization logic:
declare a
WATCHglobal variable similar toJOIN;generate a watch key when creating a game; it must be different from the join key, or else a spectator could hijack a game by tweaking the URL;
include the watch key in the
"init"event sent to the first player;generate a WATCH link in the UI with a
watchquery parameter;update the
initGame()function to handle such links;update the
handler()coroutine to invoke awatch()coroutine for spectators;prevent
sendMoves()from sending"play"events for spectators.
Once the initialization sequence is done, watching a game is as simple as
registering the WebSocket connection in the connected set in order to
receive game events and doing nothing until the spectator disconnects. You
can wait for a connection to terminate with
wait_closed():
async def watch(websocket, watch_key):
...
connected.add(websocket)
try:
await websocket.wait_closed()
finally:
connected.remove(websocket)
The connection can terminate because the receiveMoves() function closed it
explicitly after receiving a "win" event, because the spectator closed
their browser, or because the network failed.
Again, try to implement this by yourself.
When watch() works, you can invite spectators to watch the game from other
browsers, as long as they’re on the same local network.
As a further improvement, you may support adding spectators while a game is
already in progress. This requires replaying moves that were played before
the spectator was added to the connected set. Past moves are available in
the moves attribute of the game.
This feature is included in the solution proposed below.
Broadcast#
When you need to send a message to the two players and to all spectators, you’re using this pattern:
async def handler(websocket):
...
for connection in connected:
await connection.send(json.dumps(event))
...
Since this is a very common pattern in WebSocket servers, websockets provides
the broadcast() helper for this purpose:
async def handler(websocket):
...
websockets.broadcast(connected, json.dumps(event))
...
Calling broadcast() once is more efficient than
calling send() in a loop.
However, there’s a subtle difference in behavior. Did you notice that there’s
no await in the second version? Indeed, broadcast() is a function,
not a coroutine like send()
or recv().
It’s quite obvious why recv()
is a coroutine. When you want to receive the next message, you have to wait
until the client sends it and the network transmits it.
It’s less obvious why send() is
a coroutine. If you send many messages or large messages, you could write
data faster than the network can transmit it or the client can read it. Then,
outgoing data will pile up in buffers, which will consume memory and may
crash your application.
To avoid this problem, send()
waits until the write buffer drains. By slowing down the application as
necessary, this ensures that the server doesn’t send data too quickly. This
is called backpressure and it’s useful for building robust systems.
That said, when you’re sending the same messages to many clients in a loop,
applying backpressure in this way can become counterproductive. When you’re
broadcasting, you don’t want to slow down everyone to the pace of the slowest
clients; you want to drop clients that cannot keep up with the data stream.
That’s why broadcast() doesn’t wait until write buffers drain.
For our Connect Four game, there’s no difference in practice: the total amount of data sent on a connection for a game of Connect Four is less than 64 KB, so the write buffer never fills up and backpressure never kicks in anyway.
Summary#
In this second part of the tutorial, you learned how to:
configure a connection by exchanging initialization messages;
keep track of connections within a single server process;
wait until a client disconnects in a connection handler;
broadcast a message to many connections efficiently.
You can now play a Connect Four game from separate browser, communicating over WebSocket connections with a server that synchronizes the game logic!
However, the two players have to be on the same local network as the server, so the constraint of being in the same place still mostly applies.
Head over to the third part of the tutorial to deploy the game to the web and remove this constraint.
Solution#
1#!/usr/bin/env python
2
3import asyncio
4import json
5import secrets
6
7import websockets
8
9from connect4 import PLAYER1, PLAYER2, Connect4
10
11
12JOIN = {}
13
14WATCH = {}
15
16
17async def error(websocket, message):
18 """
19 Send an error message.
20
21 """
22 event = {
23 "type": "error",
24 "message": message,
25 }
26 await websocket.send(json.dumps(event))
27
28
29async def replay(websocket, game):
30 """
31 Send previous moves.
32
33 """
34 # Make a copy to avoid an exception if game.moves changes while iteration
35 # is in progress. If a move is played while replay is running, moves will
36 # be sent out of order but each move will be sent once and eventually the
37 # UI will be consistent.
38 for player, column, row in game.moves.copy():
39 event = {
40 "type": "play",
41 "player": player,
42 "column": column,
43 "row": row,
44 }
45 await websocket.send(json.dumps(event))
46
47
48async def play(websocket, game, player, connected):
49 """
50 Receive and process moves from a player.
51
52 """
53 async for message in websocket:
54 # Parse a "play" event from the UI.
55 event = json.loads(message)
56 assert event["type"] == "play"
57 column = event["column"]
58
59 try:
60 # Play the move.
61 row = game.play(player, column)
62 except RuntimeError as exc:
63 # Send an "error" event if the move was illegal.
64 await error(websocket, str(exc))
65 continue
66
67 # Send a "play" event to update the UI.
68 event = {
69 "type": "play",
70 "player": player,
71 "column": column,
72 "row": row,
73 }
74 websockets.broadcast(connected, json.dumps(event))
75
76 # If move is winning, send a "win" event.
77 if game.winner is not None:
78 event = {
79 "type": "win",
80 "player": game.winner,
81 }
82 websockets.broadcast(connected, json.dumps(event))
83
84
85async def start(websocket):
86 """
87 Handle a connection from the first player: start a new game.
88
89 """
90 # Initialize a Connect Four game, the set of WebSocket connections
91 # receiving moves from this game, and secret access tokens.
92 game = Connect4()
93 connected = {websocket}
94
95 join_key = secrets.token_urlsafe(12)
96 JOIN[join_key] = game, connected
97
98 watch_key = secrets.token_urlsafe(12)
99 WATCH[watch_key] = game, connected
100
101 try:
102 # Send the secret access tokens to the browser of the first player,
103 # where they'll be used for building "join" and "watch" links.
104 event = {
105 "type": "init",
106 "join": join_key,
107 "watch": watch_key,
108 }
109 await websocket.send(json.dumps(event))
110 # Receive and process moves from the first player.
111 await play(websocket, game, PLAYER1, connected)
112 finally:
113 del JOIN[join_key]
114 del WATCH[watch_key]
115
116
117async def join(websocket, join_key):
118 """
119 Handle a connection from the second player: join an existing game.
120
121 """
122 # Find the Connect Four game.
123 try:
124 game, connected = JOIN[join_key]
125 except KeyError:
126 await error(websocket, "Game not found.")
127 return
128
129 # Register to receive moves from this game.
130 connected.add(websocket)
131 try:
132 # Send the first move, in case the first player already played it.
133 await replay(websocket, game)
134 # Receive and process moves from the second player.
135 await play(websocket, game, PLAYER2, connected)
136 finally:
137 connected.remove(websocket)
138
139
140async def watch(websocket, watch_key):
141 """
142 Handle a connection from a spectator: watch an existing game.
143
144 """
145 # Find the Connect Four game.
146 try:
147 game, connected = WATCH[watch_key]
148 except KeyError:
149 await error(websocket, "Game not found.")
150 return
151
152 # Register to receive moves from this game.
153 connected.add(websocket)
154 try:
155 # Send previous moves, in case the game already started.
156 await replay(websocket, game)
157 # Keep the connection open, but don't receive any messages.
158 await websocket.wait_closed()
159 finally:
160 connected.remove(websocket)
161
162
163async def handler(websocket):
164 """
165 Handle a connection and dispatch it according to who is connecting.
166
167 """
168 # Receive and parse the "init" event from the UI.
169 message = await websocket.recv()
170 event = json.loads(message)
171 assert event["type"] == "init"
172
173 if "join" in event:
174 # Second player joins an existing game.
175 await join(websocket, event["join"])
176 elif "watch" in event:
177 # Spectator watches an existing game.
178 await watch(websocket, event["watch"])
179 else:
180 # First player starts a new game.
181 await start(websocket)
182
183
184async def main():
185 async with websockets.serve(handler, "", 8001):
186 await asyncio.get_running_loop().create_future() # run forever
187
188
189if __name__ == "__main__":
190 asyncio.run(main())
1<!DOCTYPE html>
2<html lang="en">
3 <head>
4 <title>Connect Four</title>
5 </head>
6 <body>
7 <div class="actions">
8 <a class="action new" href="/">New</a>
9 <a class="action join" href="">Join</a>
10 <a class="action watch" href="">Watch</a>
11 </div>
12 <div class="board"></div>
13 <script src="main.js" type="module"></script>
14 </body>
15</html>
1import { createBoard, playMove } from "./connect4.js";
2
3function initGame(websocket) {
4 websocket.addEventListener("open", () => {
5 // Send an "init" event according to who is connecting.
6 const params = new URLSearchParams(window.location.search);
7 let event = { type: "init" };
8 if (params.has("join")) {
9 // Second player joins an existing game.
10 event.join = params.get("join");
11 } else if (params.has("watch")) {
12 // Spectator watches an existing game.
13 event.watch = params.get("watch");
14 } else {
15 // First player starts a new game.
16 }
17 websocket.send(JSON.stringify(event));
18 });
19}
20
21function showMessage(message) {
22 window.setTimeout(() => window.alert(message), 50);
23}
24
25function receiveMoves(board, websocket) {
26 websocket.addEventListener("message", ({ data }) => {
27 const event = JSON.parse(data);
28 switch (event.type) {
29 case "init":
30 // Create links for inviting the second player and spectators.
31 document.querySelector(".join").href = "?join=" + event.join;
32 document.querySelector(".watch").href = "?watch=" + event.watch;
33 break;
34 case "play":
35 // Update the UI with the move.
36 playMove(board, event.player, event.column, event.row);
37 break;
38 case "win":
39 showMessage(`Player ${event.player} wins!`);
40 // No further messages are expected; close the WebSocket connection.
41 websocket.close(1000);
42 break;
43 case "error":
44 showMessage(event.message);
45 break;
46 default:
47 throw new Error(`Unsupported event type: ${event.type}.`);
48 }
49 });
50}
51
52function sendMoves(board, websocket) {
53 // Don't send moves for a spectator watching a game.
54 const params = new URLSearchParams(window.location.search);
55 if (params.has("watch")) {
56 return;
57 }
58
59 // When clicking a column, send a "play" event for a move in that column.
60 board.addEventListener("click", ({ target }) => {
61 const column = target.dataset.column;
62 // Ignore clicks outside a column.
63 if (column === undefined) {
64 return;
65 }
66 const event = {
67 type: "play",
68 column: parseInt(column, 10),
69 };
70 websocket.send(JSON.stringify(event));
71 });
72}
73
74window.addEventListener("DOMContentLoaded", () => {
75 // Initialize the UI.
76 const board = document.querySelector(".board");
77 createBoard(board);
78 // Open the WebSocket connection and register event handlers.
79 const websocket = new WebSocket("ws://localhost:8001/");
80 initGame(websocket);
81 receiveMoves(board, websocket);
82 sendMoves(board, websocket);
83});