Part 2 - Route & broadcast - websockets 12.0 documentation
Description: 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 c...

Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# 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

      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.Future()  # run forever
    187
    188
    189if __name__ == "__main__":
    190    asyncio.run(main())

index.html

     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>

main.js

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