Skip to content
Tutorials Center
My learning

Topics

Lesson 38 of 40 ยท Projects and Practice

Project: A Chat Room Server with asyncio

Build a multi-user chat room with asyncio streams: one handler per client, broadcast through per-client queues, commands, slow-client protection and clean disconnects.

A chat room is the textbook network application for asyncio: many long-lived connections, each mostly idle, with messages from one client fanned out to all the others. It exercises streams, queues, tasks and cleanup together, and every real-time system (games, dashboards, notifications) has the same shape.

You will build the server in one piece, then drive it with scripted clients. As in the other networking lessons, the browser cannot open sockets, so the clients and server talk over the in-memory connection from the streams lesson. The ChatServer.handle(reader, writer) method is exactly what you would pass to asyncio.start_server() on your own machine.

Design

flowchart LR
    A["client A reader"] --> H1["handler A"]
    H1 -->|"broadcast"| QB["outbox B"]
    H1 -->|"broadcast"| QC["outbox C"]
    QB --> SB["sender B"] --> WB["client B writer"]
    QC --> SC["sender C"] --> WC["client C writer"]

Each client has one handler task that reads, and one sender task that writes from a private outbox queue.

Key decisions:

  1. One handler per connection (what start_server gives you), reading lines and acting on them.
  2. A separate outbox queue and sender task per client. The handler never writes to another client's socket directly. If it did, one slow client would stall the broadcast to everybody (drain() waits for that client).
  3. Bounded outboxes and put_nowait. If a client's outbox is full it is too slow; we drop that message for them instead of waiting. Policy choices are explicit: here, drop messages; you could also disconnect them.
  4. Cleanup in finally, so a client that disconnects abruptly is removed and announced exactly once.
  5. Commands: /who lists users, /quit leaves politely.

The complete program

Python Chat room server and scripted clients

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Read the three transcripts side by side. Alice is told about Bob and Carol joining, hears Bob's message, and sees * bob left. Bob never sees the messages sent after his /quit. Carol's first attempts get helpful error replies instead of crashing the server.

What each part teaches

Handler plus sender per client

Reading and writing for one client are independent. The handler loop waits for input from that client; the sender loop waits for output destined for that client. Having two tasks lets a slow writer (client with a poor connection) leave the reader unaffected and, more importantly, lets everyone else keep chatting. That separation is the single most important design point of a chat server.

Fan-out through queues

broadcast() is a plain synchronous function: it uses put_nowait, which never waits, and so it can be called from any handler without suspending. Each client's sender task then takes messages from its own queue at its own pace. A queue per consumer is the standard asyncio pattern for fan-out, the counterpart of the worker pool's fan-in. See flow control for why the queue is bounded.

Slow clients

A client who stops reading eventually fills its socket buffer. writer.drain() in its sender task then waits, its outbox fills, and put_nowait raises QueueFull; the server counts the drop and moves on. Nobody else is affected. Other policies you could choose: disconnect the client, or keep only the most recent messages.

Disconnects

A TCP client can vanish at any time. readline() then returns b"" (clean close) or raises ConnectionResetError. The finally block removes the user from clients, announces the departure once, stops the sender with a None sentinel and closes the writer. Because cleanup is in finally, it also runs if the handler is cancelled at server shutdown.

Running it for real

On your own computer, replace the in-memory connection with real sockets:

Python
async def main():
    chat = ChatServer()
    server = await asyncio.start_server(chat.handle, "127.0.0.1", 9000)
    async with server:
        await server.serve_forever()

asyncio.run(main())

Then connect with several terminals using nc 127.0.0.1 9000 or telnet 127.0.0.1 9000 and chat. A matching client reads the keyboard and the socket concurrently:

Python
async def chat_client():
    reader, writer = await asyncio.open_connection("127.0.0.1", 9000)

    async def show_incoming():
        while line := await reader.readline():
            print(line.decode().rstrip())

    printer = asyncio.create_task(show_incoming())
    loop = asyncio.get_running_loop()
    while True:
        text = await loop.run_in_executor(None, input)        # blocking input() in a thread
        writer.write(text.encode() + b"\n")
        await writer.drain()

Extensions to try

  1. Private messages: /msg bob hello delivers only to Bob.
  2. Rooms: keep rooms: dict[str, set[str]] and /join room so broadcasts go to one room.
  3. Idle timeout: wrap reader.readline() in asyncio.timeout(300) and disconnect silent users (timeouts).
  4. Flood protection: a token bucket per user; excess messages get a warning.
  5. Message history: a collections.deque(maxlen=20) replayed to new users on join.
  6. Graceful shutdown: on a signal, broadcast "server closing", cancel handlers and await server.wait_closed().
  7. Framing: replace line-based text with length-prefixed JSON messages (framing).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does each client have its own outbox queue and sender task?

    If handlers wrote directly to every writer, one slow drain() would stall the broadcast. A per-client queue isolates each connection.
  2. 2. Why does broadcast() use put_nowait instead of await put()?

    put_nowait raises QueueFull immediately instead of suspending, so the server can drop or disconnect the slow client and carry on.
  3. 3. Where is the right place to remove a disconnected user from the clients dictionary?

    finally runs for clean quits, abrupt disconnects, errors and cancellation, so the user is always removed exactly once.
  4. 4. What does readline() return when the client closes the connection?

    End of stream is reported as empty bytes, which ends the "while line := await reader.readline()" loop.

Summary

  • Chat servers are one handler per connection plus a queue-fed sender per connection for fan-out.
  • Bounded outboxes with put_nowait protect the server from slow clients; choose and document the drop policy.
  • Put cleanup in finally, and stop sender tasks with a sentinel.
  • The same handler runs unchanged with asyncio.start_server() on real sockets.

Next: Project: a job scheduler with graceful shutdown