Part 1 - Send & receive - websockets 12.0 documentation
Description: In this tutorial, you’re going to build a web-based Connect Four game. The web removes the constraint of being in the same room for playing a game. Two players can connect over of the Internet, reg...

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

# Part 1 - Send & receive

In this tutorial, you’re going to build a web-based Connect Four game.

The web removes the constraint of being in the same room for playing a game. Two players can connect over of the Internet, regardless of where they are, and play in their browsers.

When a player makes a move, it should be reflected immediately on both sides. This is difficult to implement over HTTP due to the request-response style of the protocol.

Indeed, there is no good way to be notified when the other player makes a move. Workarounds such as polling or long-polling introduce significant overhead.

Enter WebSocket.

The WebSocket protocol provides two-way communication between a browser and a server over a persistent connection. That’s exactly what you need to exchange moves between players, via a server.

This is the first part of the tutorial.

- In this first part, you will create a server and connect one browser; you can play if you share the same browser.

- In the 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.

## Prerequisites

This tutorial assumes basic knowledge of Python and JavaScript.

If you’re comfortable with virtual environments, you can use one for this tutorial. Else, don’t worry: websockets doesn’t have any dependencies; it shouldn’t create trouble in the default environment.

If you haven’t installed websockets yet, do it now:

    $ pip install websockets

Confirm that websockets is installed:

    $ python -m websockets --version

This tutorial is written for websockets 12.0.

If you installed another version, you should switch to the corresponding version of the documentation.

## Download the starter kit

Create a directory and download these three files: `connect4.js`, `connect4.css`, and `connect4.py`.

The JavaScript module, along with the CSS file, provides a web-based user interface. Here’s its API.

connect4.PLAYER1

  Color of the first player.

connect4.PLAYER2

  Color of the second player.

connect4.createBoard(board)

  Draw a board.

  Arguments:

    - board – DOM element containing the board; must be initially empty.

connect4.playMove(board, player, column, row)

  Play a move.

  Arguments:

    - board – DOM element containing the board.

    - player – `PLAYER1` or `PLAYER2`.

    - column – between `0` and `6`.

    - row – between `0` and `5`.

The Python module provides a class to record moves and tell when a player wins. Here’s its API.

connect4.PLAYER1 = "red"

  Color of the first player.

connect4.PLAYER2 = "yellow"

  Color of the second player.

class connect4.Connect4

  A Connect Four game.

  play(player, column)

    Play a move.

    Parameters:

      - player – `PLAYER1` or `PLAYER2`.

      - column – between `0` and `6`.

    Returns:

      Row where the checker lands, between `0` and `5`.

    Raises:

      RuntimeError – if the move is illegal.

  moves

    List of moves played during this game, as `(player, column, row)` tuples.

  winner

    `PLAYER1` or `PLAYER2` if they won; `None` if the game is still ongoing.

## Bootstrap the web UI

Create an `index.html` file next to `connect4.js` and `connect4.css` with this content:

    <!DOCTYPE html>
    <html lang="en">
      <head>
        <title>Connect Four</title>
      </head>
      <body>
        <div class="board"></div>
        <script src="main.js" type="module"></script>
      </body>
    </html>

This HTML page contains an empty `<div>` element where you will draw the Connect Four board. It loads a `main.js` script where you will write all your JavaScript code.

Create a `main.js` file next to `index.html`. In this script, when the page loads, draw the board:

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

    window.addEventListener("DOMContentLoaded", () => {
      // Initialize the UI.
      const board = document.querySelector(".board");
      createBoard(board);
    });

Open a shell, navigate to the directory containing these files, and start an HTTP server:

    $ python -m http.server

Open http://localhost:8000/ in a web browser. The page displays an empty board with seven columns and six rows. You will play moves in this board later.

## Bootstrap the server

Create an `app.py` file next to `connect4.py` with this content:

    #!/usr/bin/env python

    import asyncio

    import websockets

    async def handler(websocket):
        while True:
            message = await websocket.recv()
            print(message)

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

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

The entry point of this program is `asyncio.run(main())`. It creates an asyncio event loop, runs the `main()` coroutine, and shuts down the loop.

The `main()` coroutine calls `serve()` to start a websockets server. `serve()` takes three positional arguments:

- `handler` is a coroutine that manages a connection. When a client connects, websockets calls `handler` with the connection in argument. When `handler` terminates, websockets closes the connection.

- The second argument defines the network interfaces where the server can be reached. Here, the server listens on all interfaces, so that other devices on the same local network can connect.

- The third argument is the port on which the server listens.

Invoking `serve()` as an asynchronous context manager, in an `async with` block, ensures that the server shuts down properly when terminating the program.

For each connection, the `handler()` coroutine runs an infinite loop that receives messages from the browser and prints them.

Open a shell, navigate to the directory containing `app.py`, and start the server:

    $ python app.py

This doesn’t display anything. Hopefully the WebSocket server is running. Let’s make sure that it works. You cannot test the WebSocket server with a web browser like you tested the HTTP server. However, you can test it with websockets’ interactive client.

Open another shell and run this command:

    $ python -m websockets ws://localhost:8001/

You get a prompt. Type a message and press “Enter”. Switch to the shell where the server is running and check that the server received the message. Good!

Exit the interactive client with Ctrl-C or Ctrl-D.

Now, if you look at the console where you started the server, you can see the stack trace of an exception:

    connection handler failed
    Traceback (most recent call last):
      ...
      File "app.py", line 22, in handler
        message = await websocket.recv()
      ...
    websockets.exceptions.ConnectionClosedOK: received 1000 (OK); then sent 1000 (OK)

Indeed, the server was waiting for the next message with `recv()` when the client disconnected. When this happens, websockets raises a `ConnectionClosedOK` exception to let you know that you won’t receive another message on this connection.

This exception creates noise in the server logs, making it more difficult to spot real errors when you add functionality to the server. Catch it in the `handler()` coroutine:

    async def handler(websocket):
        while True:
            try:
                message = await websocket.recv()
            except websockets.ConnectionClosedOK:
                break
            print(message)

Stop the server with Ctrl-C and start it again:

    $ python app.py

You must restart the WebSocket server when you make changes.

The WebSocket server loads the Python code in `app.py` then serves every WebSocket request with this version of the code. As a consequence, changes to `app.py` aren’t visible until you restart the server.

This is unlike the HTTP server that you started earlier with `python -m http.server`. For every request, this HTTP server reads the target file and sends it. That’s why changes are immediately visible.

It is possible to restart the WebSocket server automatically but this isn’t necessary for this tutorial.

Try connecting and disconnecting the interactive client again. The `ConnectionClosedOK` exception doesn’t appear anymore.

This pattern is so common that websockets provides a shortcut for iterating over messages received on the connection until the client disconnects:

    async def handler(websocket):
        async for message in websocket:
            print(message)

Restart the server and check with the interactive client that its behavior didn’t change.

At this point, you bootstrapped a web application and a WebSocket server. Let’s connect them.

## Transmit from browser to server

In JavaScript, you open a WebSocket connection as follows:

    const websocket = new WebSocket("ws://localhost:8001/");

Before you exchange messages with the server, you need to decide their format. There is no universal convention for this.

Let’s use JSON objects with a `type` key identifying the type of the event and the rest of the object containing properties of the event.

Here’s an event describing a move in the middle slot of the board:

    const event = {type: "play", column: 3};

Here’s how to serialize this event to JSON and send it to the server:

    websocket.send(JSON.stringify(event));

Now you have all the building blocks to send moves to the server.

Add this function to `main.js`:

    function sendMoves(board, websocket) {
      // 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));
      });
    }

`sendMoves()` registers a listener for `click` events on the board. The listener figures out which column was clicked, builds a event of type `"play"`, serializes it, and sends it to the server.

Modify the initialization to open the WebSocket connection and call the `sendMoves()` function:

    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/");
      sendMoves(board, websocket);
    });

Check that the HTTP server and the WebSocket server are still running. If you stopped them, here are the commands to start them again:

    $ python -m http.server

    $ python app.py

Refresh http://localhost:8000/ in your web browser. Click various columns in the board. The server receives messages with the expected column number.

There isn’t any feedback in the board because you haven’t implemented that yet. Let’s do it.

## Transmit from server to browser

In JavaScript, you receive WebSocket messages by listening to `message` events. Here’s how to receive a message from the server and deserialize it from JSON:

    websocket.addEventListener("message", ({ data }) => {
      const event = JSON.parse(data);
      // do something with event
    });

You’re going to need three types of messages from the server to the browser:

    {type: "play", player: "red", column: 3, row: 0}
    {type: "win", player: "red"}
    {type: "error", message: "This slot is full."}

The JavaScript code receiving these messages will dispatch events depending on their type and take appropriate action. For example, it will react to an event of type `"play"` by displaying the move on the board with the `playMove()` function.

Add this function to `main.js`:

    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 "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}.`);
        }
      });
    }

Why does `showMessage` use `window.setTimeout`?

When `playMove()` modifies the state of the board, the browser renders changes asynchronously. Conversely, `window.alert()` runs synchronously and blocks rendering while the alert is visible.

If you called `window.alert()` immediately after `playMove()`, the browser could display the alert before rendering the move. You could get a “Player red wins!” alert without seeing red’s last move.

We’re using `window.alert()` for simplicity in this tutorial. A real application would display these messages in the user interface instead. It wouldn’t be vulnerable to this problem.

Modify the initialization to call the `receiveMoves()` function:

    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/");
      receiveMoves(board, websocket);
      sendMoves(board, websocket);
    });

At this point, the user interface should receive events properly. Let’s test it by modifying the server to send some events.

Sending an event from Python is quite similar to JavaScript:

    event = {"type": "play", "player": "red", "column": 3, "row": 0}
    await websocket.send(json.dumps(event))

Don’t forget to serialize the event with `json.dumps()`.

Else, websockets raises `TypeError: data is a dict-like object`.

Modify the `handler()` coroutine in `app.py` as follows:

    import json

    from connect4 import PLAYER1, PLAYER2

    async def handler(websocket):
        for player, column, row in [
            (PLAYER1, 3, 0),
            (PLAYER2, 3, 1),
            (PLAYER1, 4, 0),
            (PLAYER2, 4, 1),
            (PLAYER1, 2, 0),
            (PLAYER2, 1, 0),
            (PLAYER1, 5, 0),
        ]:
            event = {
                "type": "play",
                "player": player,
                "column": column,
                "row": row,
            }
            await websocket.send(json.dumps(event))
            await asyncio.sleep(0.5)
        event = {
            "type": "win",
            "player": PLAYER1,
        }
        await websocket.send(json.dumps(event))

Restart the WebSocket server and refresh http://localhost:8000/ in your web browser. Seven moves appear at 0.5 second intervals. Then an alert announces the winner.

Good! Now you know how to communicate both ways.

Once you plug the game engine to process moves, you will have a fully functional game.

## Add the game logic

In the `handler()` coroutine, you’re going to initialize a game:

    from connect4 import Connect4

    async def handler(websocket):
        # Initialize a Connect Four game.
        game = Connect4()

        ...

Then, you’re going to iterate over incoming messages and take these steps:

- parse an event of type `"play"`, the only type of event that the user interface sends;

- play the move in the board with the `play()` method, alternating between the two players;

- if `play()` raises `RuntimeError` because the move is illegal, send an event of type `"error"`;

- else, send an event of type `"play"` to tell the user interface where the checker lands;

- if the move won the game, send an event of type `"win"`.

Try to implement this by yourself!

Keep in mind that you must restart the WebSocket server and reload the page in the browser when you make changes.

When it works, you can play the game from a single browser, with players taking alternate turns.

Enable debug logs to see all messages sent and received.

Here’s how to enable debug logs:

    import logging

    logging.basicConfig(format="%(message)s", level=logging.DEBUG)

If you’re stuck, a solution is available at the bottom of this document.

## Summary

In this first part of the tutorial, you learned how to:

- build and run a WebSocket server in Python with `serve()`;

- receive a message in a connection handler with `recv()`;

- send a message in a connection handler with `send()`;

- iterate over incoming messages with `async for message in websocket: ...`;

- open a WebSocket connection in JavaScript with the `WebSocket` API;

- send messages in a browser with `WebSocket.send()`;

- receive messages in a browser by listening to `message` events;

- design a set of events to be exchanged between the browser and the server.

You can now play a Connect Four game in a browser, communicating over a WebSocket connection with a server where the game logic resides!

However, the two players share a browser, so the constraint of being in the same room still applies.

Move on to the second part of the tutorial to break this constraint and play from separate browsers.

## Solution

app.py

     1#!/usr/bin/env python
     2
     3import asyncio
     4import itertools
     5import json
     6
     7import websockets
     8
     9from connect4 import PLAYER1, PLAYER2, Connect4
    10
    11
    12async def handler(websocket):
    13    # Initialize a Connect Four game.
    14    game = Connect4()
    15
    16    # Players take alternate turns, using the same browser.
    17    turns = itertools.cycle([PLAYER1, PLAYER2])
    18    player = next(turns)
    19
    20    async for message in websocket:
    21        # Parse a "play" event from the UI.
    22        event = json.loads(message)
    23        assert event["type"] == "play"
    24        column = event["column"]
    25
    26        try:
    27            # Play the move.
    28            row = game.play(player, column)
    29        except RuntimeError as exc:
    30            # Send an "error" event if the move was illegal.
    31            event = {
    32                "type": "error",
    33                "message": str(exc),
    34            }
    35            await websocket.send(json.dumps(event))
    36            continue
    37
    38        # Send a "play" event to update the UI.
    39        event = {
    40            "type": "play",
    41            "player": player,
    42            "column": column,
    43            "row": row,
    44        }
    45        await websocket.send(json.dumps(event))
    46
    47        # If move is winning, send a "win" event.
    48        if game.winner is not None:
    49            event = {
    50                "type": "win",
    51                "player": game.winner,
    52            }
    53            await websocket.send(json.dumps(event))
    54
    55        # Alternate turns.
    56        player = next(turns)
    57
    58
    59async def main():
    60    async with websockets.serve(handler, "", 8001):
    61        await asyncio.Future()  # run forever
    62
    63
    64if __name__ == "__main__":
    65    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="board"></div>
     8    <script src="main.js" type="module"></script>
     9  </body>
    10</html>

main.js

     1import { createBoard, playMove } from "./connect4.js";
     2
     3function showMessage(message) {
     4  window.setTimeout(() => window.alert(message), 50);
     5}
     6
     7function receiveMoves(board, websocket) {
     8  websocket.addEventListener("message", ({ data }) => {
     9    const event = JSON.parse(data);
    10    switch (event.type) {
    11      case "play":
    12        // Update the UI with the move.
    13        playMove(board, event.player, event.column, event.row);
    14        break;
    15      case "win":
    16        showMessage(`Player ${event.player} wins!`);
    17        // No further messages are expected; close the WebSocket connection.
    18        websocket.close(1000);
    19        break;
    20      case "error":
    21        showMessage(event.message);
    22        break;
    23      default:
    24        throw new Error(`Unsupported event type: ${event.type}.`);
    25    }
    26  });
    27}
    28
    29function sendMoves(board, websocket) {
    30  // When clicking a column, send a "play" event for a move in that column.
    31  board.addEventListener("click", ({ target }) => {
    32    const column = target.dataset.column;
    33    // Ignore clicks outside a column.
    34    if (column === undefined) {
    35      return;
    36    }
    37    const event = {
    38      type: "play",
    39      column: parseInt(column, 10),
    40    };
    41    websocket.send(JSON.stringify(event));
    42  });
    43}
    44
    45window.addEventListener("DOMContentLoaded", () => {
    46  // Initialize the UI.
    47  const board = document.querySelector(".board");
    48  createBoard(board);
    49  // Open the WebSocket connection and register event handlers.
    50  const websocket = new WebSocket("ws://localhost:8001/");
    51  receiveMoves(board, websocket);
    52  sendMoves(board, websocket);
    53});