What You Will Build
This project builds a chat room. A client connects over WebSocket and picks a nickname. Then each message that a member sends goes to each member of the room. When a member joins or leaves, the others see a notice.
The server uses only the Zig standard library. It uses the parts from the four WebSocket chapters of Networking:
- The WebSocket Handshake: the
server answers the upgrade with
std.http.Server. - WebSocket Frames: the header, the length forms and the mask.
- A WebSocket Client: the client in the last chapter of this project is that client, imported from its file.
- A WebSocket Server on a Socket: the gaps in std that this project must fill.
Read those four first if WebSocket is new to you.
The parts
The server has four parts. Each part is one file, and each file is a snippet that CI compiles and runs:
| File | What it does | Runs where |
|---|---|---|
chat-protocol.zig | Parses commands from clients and formats events for clients | browser |
chat-hub.zig | Keeps the members and copies each line into their outboxes | browser |
chat-frames.zig | Reads frames from a client, with fragments and close codes | browser |
chat-server.zig | Puts the parts on real sockets, with three clients | native |
The first three files take bytes and return bytes. They never see a socket, thus their chapters run in your browser. The last file imports the other three and adds the sockets and the tasks.
Four decisions
A chat server looks simple: read a message, and send it to everybody. Four questions make it difficult, and each chapter answers one of them.
- What does a message mean? WebSocket frames the bytes. It does not say what the bytes mean. The Protocol defines a small text protocol.
- Who writes to a socket? Each member receives lines from many other members, and each sender runs in a different task. If two tasks write to one socket at the same time, the frames can mix. The Hub gives each connection one writer.
- What if a client does not read? A broadcast that waits for one slow member stops the room. Slow Clients drops that member instead.
- What does std not read? std refuses a message in fragments and does not return the close code. Read the Frames Yourself writes the reader that the server needs.
The Server puts the four answers on real sockets.
What it does not do
The room is one room, with up to eight members. It keeps no history, so a new member sees only the messages that arrive after the member joins. It has no accounts, no TLS and no persistence. Each of those is a separate decision, and none of them changes the four parts above.