Build Real-Time Chat with FastAPI and WebSockets

Implementing the WebSocket Endpoint

In your main.py file, you'll define a WebSocket endpoint. This endpoint will be responsible for managing client connections and broadcasting messages. A common approach is to maintain a list of active WebSocket connections. When a new client connects, their WebSocket object is added to this list. When a client sends a message, it's broadcast to all other connected clients.

Here’s a simplified structure:

from fastapi import FastAPI, WebSocket

app = FastAPI()

connected_clients = []

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    connected_clients.append(websocket)
    try:
        while True:
            data = await websocket.receive_text()
            # Broadcast message to all clients
            for client in connected_clients:
                await client.send_text(f"Message text was: {data}")
    except Exception as e:
        print(f"Client disconnected: {e}")
        connected_clients.remove(websocket)

The websocket.accept() call establishes the connection. The while True loop continuously listens for incoming messages. When a message is received, it iterates through the connected_clients list and sends the message to each one. The try...except block handles disconnections gracefully by removing the client from the active list.

Broadcasting Messages

The broadcasting mechanism is central to a chat app. Every time a message is received from one client, it needs to be relayed to all other connected clients. In the example above, this is handled by iterating through the connected_clients list. For larger-scale applications, you might consider more sophisticated broadcasting strategies, such as using a message queue or a pub/sub system to avoid blocking the main WebSocket thread.

A crucial aspect of broadcasting is ensuring that messages are not sent back to the sender, unless that's the desired behavior for a specific chat room or feature. You can achieve this by checking the client's identity before sending.

Managing Client Connections

The connected_clients list is a simple in-memory store of active connections. For production applications, especially those expecting a large number of concurrent users, this approach might not scale well. You would need to consider distributed systems, such as Redis, to manage connection states across multiple server instances. This ensures that messages can be broadcast to clients connected to any server instance, not just the one that received the message.

Handling disconnections is also vital. When a WebSocket connection is closed (either intentionally by the client or due to network issues), the server must detect this and remove the client from the active list to prevent errors when trying to send messages to a closed connection. The websocket.receive_text() method will raise an exception when the connection is closed, which our try...except block catches.

Running the Application

To run your FastAPI WebSocket server, use Uvicorn from your terminal:

uvicorn main:app --reload

The --reload flag is useful during development, as it automatically restarts the server when you make changes to your code.

Testing the Chat App

You can test your WebSocket endpoint using various tools. A simple way is to use another Python script with the websockets library, or a JavaScript client in a web browser. For a web browser, you would use the browser's native WebSocket API:

const socket = new WebSocket("ws://localhost:8000/ws");

socket.onopen = function(event) {
  console.log("WebSocket connection opened");
  socket.send("Hello from the browser!");
};

socket.onmessage = function(event) {
  console.log("Message from server: ", event.data);
};

socket.onclose = function(event) {
  console.log("WebSocket connection closed");
};

socket.onerror = function(event) {
  console.error("WebSocket error observed:", event);
};

When you run the server and connect a client (or multiple clients), you can send messages from one client and see them appear on all connected clients. This confirms that the real-time communication is functioning as expected.

Scalability and Further Improvements

While this example provides a functional real-time chat app, scaling it for production requires additional considerations. For high concurrency, you might integrate a message broker like Redis or RabbitMQ. This decouples the message producers from consumers and allows for horizontal scaling of your FastAPI application instances. You could also implement features like user authentication, private messaging, chat rooms, and message history storage using a database.

The surprising detail here is not the complexity of WebSockets with FastAPI, but how elegantly FastAPI abstracts away much of the boilerplate. You are left focusing on the core logic of message handling and broadcasting, rather than wrestling with low-level network protocols.

What nobody has addressed yet is how to efficiently manage user presence (who is online/offline) across a distributed WebSocket deployment without incurring significant overhead.