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.

Share game state

As long as you’re running a single server process, you can share state by storing it in a global variable.

What if you need to scale to multiple server processes?

In that case, you must design a way for the process that handles a given connection to be aware of relevant events for that client. This is often achieved with a publish / subscribe mechanism.

How can you make two connection handlers agree on which game they’re playing? When the first player starts a game, you give it an identifier. Then, you communicate the identifier to the second player. When the second player joins the game, you look it up with the identifier.

In addition to the game itself, you need to keep track of the WebSocket connections of the two players. Since both players receive the same events, you don’t need to treat the two connections differently; you can store both in the same set.

Let’s sketch this in code.

A module-level dict enables lookups by identifier:

JOIN = {}

When the first player starts the game, initialize and store it:

import secrets

async def handler(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:

        ...

    finally:
        del JOIN[join_key]

When the second player joins the game, look it up:

async def handler(websocket):
    ...

    join_key = ...  # TODO

    # Find the Connect Four game.
    game, connected = JOIN[join_key]

    # Register to receive moves from this game.
    connected.add(websocket)
    try:

        ...

    finally:
        connected.remove(websocket)

Notice how we’re carefully cleaning up global state with try: ... finally: ... blocks. Else, we could leave references to games or connections in global state, which would cause a memory leak.

In both connection handlers, you have a game pointing to the same Connect4 instance, so you can interact with the game, and a connected set of connections, so you can send game events to both players as follows:

async def handler(websocket):

    ...

    for connection in connected:
        await connection.send(json.dumps(event))

    ...

Perhaps you spotted a major piece missing from the puzzle. How does the second player obtain join_key? Let’s design new events to carry this information.

To start a game, the first player sends an "init" event:

{type: "init"}

The connection handler for the first player creates a game as shown above and responds with:

{type: "init", join: "<join_key>"}

With this information, the user interface of the first player can create a link to http://localhost:8000/?join=<join_key>. For the sake of simplicity, we will assume that the first player shares this link with the second player outside of the application, for example via an instant messaging service.

To join the game, the second player sends a different "init" event:

{type: "init", join: "<join_key>"}

The connection handler for the second player can look up the game with the join key as shown above. There is no need to respond.

Let’s dive into the details of implementing this design.

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 WATCH global variable similar to JOIN;

• 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 watch query parameter;

• update the initGame() function to handle such links;

• update the handler() coroutine to invoke a watch() 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

app.py

#!/usr/bin/env python

import asyncio
import json
import secrets

import websockets

from connect4 import PLAYER1, PLAYER2, Connect4


JOIN = {}

WATCH = {}


async def error(websocket, message):
    """
    Send an error message.

    """
    event = {
        "type": "error",
        "message": message,
    }
    await websocket.send(json.dumps(event))


async def replay(websocket, game):
    """
    Send previous moves.

    """
    # Make a copy to avoid an exception if game.moves changes while iteration
    # is in progress. If a move is played while replay is running, moves will
    # be sent out of order but each move will be sent once and eventually the
    # UI will be consistent.
    for player, column, row in game.moves.copy():
        event = {
            "type": "play",
            "player": player,
            "column": column,
            "row": row,
        }
        await websocket.send(json.dumps(event))


async def play(websocket, game, player, connected):
    """
    Receive and process moves from a player.

    """
    async for message in websocket:
        # Parse a "play" event from the UI.
        event = json.loads(message)
        assert event["type"] == "play"
        column = event["column"]

        try:
            # Play the move.
            row = game.play(player, column)
        except RuntimeError as exc:
            # Send an "error" event if the move was illegal.
            await error(websocket, str(exc))
            continue

        # Send a "play" event to update the UI.
        event = {
            "type": "play",
            "player": player,
            "column": column,
            "row": row,
        }
        websockets.broadcast(connected, json.dumps(event))

        # If move is winning, send a "win" event.
        if game.winner is not None:
            event = {
                "type": "win",
                "player": game.winner,
            }
            websockets.broadcast(connected, json.dumps(event))


async def start(websocket):
    """
    Handle a connection from the first player: start a new game.

    """
    # Initialize a Connect Four game, the set of WebSocket connections
    # receiving moves from this game, and secret access tokens.
    game = Connect4()
    connected = {websocket}

    join_key = secrets.token_urlsafe(12)
    JOIN[join_key] = game, connected

    watch_key = secrets.token_urlsafe(12)
    WATCH[watch_key] = game, connected

    try:
        # Send the secret access tokens to the browser of the first player,
        # where they'll be used for building "join" and "watch" links.
        event = {
            "type": "init",
            "join": join_key,
            "watch": watch_key,
        }
        await websocket.send(json.dumps(event))
        # Receive and process moves from the first player.
        await play(websocket, game, PLAYER1, connected)
    finally:
        del JOIN[join_key]
        del WATCH[watch_key]


async def join(websocket, join_key):
    """
    Handle a connection from the second player: join an existing game.

    """
    # 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:
        # Send the first move, in case the first player already played it.
        await replay(websocket, game)
        # Receive and process moves from the second player.
        await play(websocket, game, PLAYER2, connected)
    finally:
        connected.remove(websocket)


async def watch(websocket, watch_key):
    """
    Handle a connection from a spectator: watch an existing game.

    """
    # Find the Connect Four game.
    try:
        game, connected = WATCH[watch_key]
    except KeyError:
        await error(websocket, "Game not found.")
        return

    # Register to receive moves from this game.
    connected.add(websocket)
    try:
        # Send previous moves, in case the game already started.
        await replay(websocket, game)
        # Keep the connection open, but don't receive any messages.
        await websocket.wait_closed()
    finally:
        connected.remove(websocket)


async def handler(websocket):
    """
    Handle a connection and dispatch it according to who is connecting.

    """
    # 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"])
    elif "watch" in event:
        # Spectator watches an existing game.
        await watch(websocket, event["watch"])
    else:
        # First player starts a new game.
        await start(websocket)


async def main():
    async with websockets.serve(handler, "", 8001):
        await asyncio.Future()  # run forever


if __name__ == "__main__":
    asyncio.run(main())

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Connect Four</title>
  </head>
  <body>
    <div class="actions">
      <a class="action new" href="/">New</a>
      <a class="action join" href="">Join</a>
      <a class="action watch" href="">Watch</a>
    </div>
    <div class="board"></div>
    <script src="main.js" type="module"></script>
  </body>
</html>

main.js

import { createBoard, playMove } from "./connect4.js";

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 if (params.has("watch")) {
      // Spectator watches an existing game.
      event.watch = params.get("watch");
    } else {
      // First player starts a new game.
    }
    websocket.send(JSON.stringify(event));
  });
}

function showMessage(message) {
  window.setTimeout(() => window.alert(message), 50);
}

function receiveMoves(board, websocket) {
  websocket.addEventListener("message", ({ data }) => {
    const event = JSON.parse(data);
    switch (event.type) {
      case "init":
        // Create links for inviting the second player and spectators.
        document.querySelector(".join").href = "?join=" + event.join;
        document.querySelector(".watch").href = "?watch=" + event.watch;
        break;
      case "play":
        // Update the UI with the move.
        playMove(board, event.player, event.column, event.row);
        break;
      case "win":
        showMessage(`Player ${event.player} wins!`);
        // No further messages are expected; close the WebSocket connection.
        websocket.close(1000);
        break;
      case "error":
        showMessage(event.message);
        break;
      default:
        throw new Error(`Unsupported event type: ${event.type}.`);
    }
  });
}

function sendMoves(board, websocket) {
  // Don't send moves for a spectator watching a game.
  const params = new URLSearchParams(window.location.search);
  if (params.has("watch")) {
    return;
  }

  // When clicking a column, send a "play" event for a move in that column.
  board.addEventListener("click", ({ target }) => {
    const column = target.dataset.column;
    // Ignore clicks outside a column.
    if (column === undefined) {
      return;
    }
    const event = {
      type: "play",
      column: parseInt(column, 10),
    };
    websocket.send(JSON.stringify(event));
  });
}

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);
});