Skip to content
Tutorials Center
My learning

Topics

Lesson 139 of 147 ยท Projects

Project: Real-Time Chat Server

Build a TCP chat server in Go step by step - a hub goroutine that owns all state, one goroutine per client, nicknames, rooms, commands and graceful shutdown.

A chat server is the classic Go project because it uses the language the way it was designed to be used. Hundreds of people are connected at once, each one sends lines at unpredictable moments, and every line must reach everybody else. In many languages this means threads, locks and careful thinking about who may touch what. In Go it becomes a small set of goroutines that talk through channels.

You will build the server in four stages, and every stage is a complete program you can run. First a hub that owns all the state and is driven only by messages. Then a TCP server with one goroutine per connection, nicknames and a login handshake. Then commands and rooms (/who, /nick, /msg, /me, /join, /quit). Finally protection and shutdown: slow clients get disconnected instead of blocking everyone, and the whole server stops cleanly through a context. The ideas come from goroutines, channels, select and TCP servers.

Our editor runs one program with no outside network, so every stage starts the server on 127.0.0.1 with a free port (:0) and then plays the part of the users itself: a small test client connects, sends lines and prints exactly what it receives. On your own machine you can drop the driver, listen on a fixed port such as :4000, and connect with nc localhost 4000 from several terminals.

The plan

Three decisions shape the whole design.

  1. One goroutine owns the state. The set of connected clients, their names and their rooms live in plain maps inside a hub. Only the hub's goroutine reads or writes them, so there is no mutex and no data race. Everyone else sends the hub an event on a channel. This is the "share memory by communicating" rule from the concurrency patterns lesson.
  2. Each client gets two goroutines. A reader turns incoming lines into events. A writer drains the client's out channel to the socket. The hub never writes to a socket itself, so a slow network can never stop it.
  3. Only the hub sends on a client's out channel after login, and only the hub closes it. Sending on a closed channel panics, so "exactly one owner closes" is the rule that keeps the shutdown code simple.

Stage 1: the hub

Start without any network. The hub receives events from one channel and delivers text to each client's out channel. A client is just a name and a buffered channel:

Go Stage 1: a hub driven by events

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 bufio.Scanner or fmt.Scan), it gets the next line from this box.

Things worth noticing:

  • One events channel keeps order. If joins, leaves and messages used three channels, select would pick randomly among the ready ones and the order of events would be lost. One channel means the hub sees exactly the order in which events were sent.
  • Bob's list ends at <bob> hello carol: the hub closed his out channel when he left, before announcing the departure to the others. The range loops at the end only finish because every out channel was closed. That is the signal a real writer goroutine will use to stop.
  • broadcast uses select with a default case. A plain c.out <- msg would block the whole hub the moment one client stops reading. Dropping the message is a first answer; stage 4 replaces it with something better.

Stage 2: TCP, nicknames and a login handshake

Now connect real sockets. For each accepted connection the server starts a handler goroutine, which starts a writer goroutine and then runs the login conversation: ask for a nickname, check it, and retry until the hub accepts it.

The hub is the only place that knows which names are taken, so login asks it. The join event carries a reply channel, and the handler waits for the answer. This request and reply over a channel pattern turns the hub into a small server of its own.

The driver at the bottom plays three users. It prints each line the way a terminal would show it, prefixed by who received it:

Go Stage 2: TCP server with nicknames

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 bufio.Scanner or fmt.Scan), it gets the next line from this box.

Read the handler carefully, because it holds the patterns the rest of the project reuses:

  • The writer goroutine is a for range c.out loop. When the channel is closed, the loop ends and writerDone is closed. The handler waits for it before returning, so the last messages are written before conn.Close() runs through defer.
  • When the reader gets EOF (the user disconnected), the handler sends evLeave. The hub closes out, which stops the writer. A disconnect therefore cleans everything up through the same path as a normal leave.
  • A client that disconnects before it chooses a name was never given to the hub, so the handler closes out itself. That is the only case where the handler closes it.
  • login sends prompts straight to c.out. This is safe because the hub does not know the client yet. After login, only the hub sends.

The handler does s.hub.events <- event{...} with no way out. If the hub stopped, every handler would block forever and leak. Stage 4 fixes this with a submit method that also watches the hub's done channel.

Stage 3: commands and rooms

Real chat needs more than broadcasting. Each client now has a room (everyone starts in lobby), and lines that start with / are commands:

Command What it does
/who List the names in your room
/nick NAME Change your name (must be free)
/msg NAME TEXT Private message to one person in any room
/me TEXT Action message: * alice waves
/join ROOM Move to another room
/help Show this list
/quit Leave

Two design points. Parsing happens in the handler (it needs no shared state), and produces an event. Anything that touches shared state happens in the hub, including error messages to a user: an evNotice event asks the hub to tell the sender something. That keeps "only the hub sends on out" true even for Unknown command.

The hub's handle method is now a switch over event kinds. Messages go to toRoom, which filters clients by room:

Go Stage 3: rooms, nicknames and commands

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 bufio.Scanner or fmt.Scan), it gets the next line from this box.

A few details are easy to miss:

  • The driver must read every line the server sends, in order. When bob joins, alice receives * bob joined, so the script has a see(alice) for it; skip one and the next see would show an older line. A real terminal client avoids this by reading the socket in its own goroutine, which is how you would write the client side of this project.
  • /nick renames a client inside the hub, which updates both c.name and the names map. The handler goroutine never reads c.name after login, so there is no race.
  • /join go does not close or reopen anything. The client keeps the same out channel and the same socket; only the string c.room changes.
  • Private messages ignore rooms: h.names finds the target anywhere on the server.
  • /quit ends the reader loop and falls through to the same evLeave as a closed socket. The last see(alice, bob) shows alice getting * robert left and bob getting end-of-file, because the hub closed his channel, the writer finished and the handler closed the connection.

Stage 4: slow clients and graceful shutdown

Two problems are left. The first is a slow client. Dropping a message silently is dangerous in a chat: the reader might miss half a conversation and never know. A better policy is to disconnect a client whose buffer is full, so it can reconnect and start from a clean state. The hub's tell becomes deliver, which evicts a client whose buffer is full. When a message goes to a whole room, toRoom first delivers it to everyone it can and only afterwards drops the slow clients, so the order of events is the same on every run.

The second problem is shutdown. Today the server just stops when main returns. A real server should stop accepting connections, tell every user it is going away, let each writer flush, close the sockets and only then exit. The plan:

  1. A context.Context signals shutdown. The hub's loop becomes a select between ctx.Done() and the events channel.
  2. On shutdown the hub announces * server is shutting down, then removes every client, which closes every out channel. Each writer drains its remaining lines, then closes its socket, which unblocks the reader. The writer is the one that closes the connection, so the farewell always gets out before the socket does.
  3. Handlers talk to the hub through submit, which gives up when the hub's done channel is closed. Without it, a handler sending an event after shutdown would block forever.
  4. A sync.WaitGroup counts the accept loop and all handlers, so Shutdown can wait until everything has really stopped.
  5. A client that is still typing its nickname when shutdown starts is not known to the hub. context.AfterFunc closes its connection when the context is cancelled, but is stopped as soon as login succeeds (otherwise it could cut off the farewell).

The driver now also adds a fake client called sloth that never reads, with a two-message buffer, to show eviction without having to fill a real TCP buffer:

Go Stage 4: eviction and graceful shutdown

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 bufio.Scanner or fmt.Scan), it gets the next line from this box.

Check the end of the output: alice and bob receive * server is shutting down and then end-of-file, which is the sign of an orderly close. shy, who never logged in, gets no farewell (the hub did not know them), but their connection is closed by the AfterFunc and Shutdown still returns. If Shutdown hung, the program would hit the 5 second limit of our editor, which is exactly how a leaked goroutine shows up in practice.

Design lessons from this project

  • State owned by one goroutine needs no locks. The hub could have been a struct with a sync.Mutex; for a chat server the event loop is just as fast and much easier to reason about, because every change is a step in a single, ordered story.
  • Never let a slow consumer block a fast producer. Each client has a bounded buffer and a policy for when it is full. The same idea appears as backpressure in pipelines.
  • One owner closes a channel. The hub closes out; senders never do. This rule removes the classic "send on closed channel" panic.
  • Every goroutine needs a way to stop. The reader stops when the socket closes, the writer when out closes, the hub when the context is cancelled, and a WaitGroup proves it. Review goroutine leaks whenever you add a new goroutine.
  • Parsing and state are separate. parseLine is a pure function from text to event. You can test it in a table test without any network, as shown in table-driven tests.

Ideas to extend it

  • Write a real terminal client that reads the server's lines in one goroutine while reading the keyboard in another.
  • Add /rooms to list rooms and the number of people in each.
  • Keep the last 20 messages per room and send them to new arrivals.
  • Add idle timeouts with conn.SetReadDeadline and close users who say nothing for ten minutes.
  • Add flood protection: allow at most five lines per second per client using a time.Ticker.
  • Serve the same hub over WebSockets or server-sent events (see Streaming, SSE and WebSockets).
  • Write the hub tests with net.Pipe instead of real sockets.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does the hub in this project need no mutex to protect its maps?

    All access to the clients and names maps happens inside the single hub goroutine. Other goroutines communicate by sending events on a channel, so there is nothing shared to lock. Regular Go maps are not safe for concurrent writes.
  2. 2. What happens if a goroutine sends on a channel that another goroutine has closed?

    Sending on a closed channel panics. That is why the design gives each out channel exactly one closer (the hub) and lets only the hub send after login.
  3. 3. Why does hub.submit use select with <-h.done instead of a plain h.events <- ev?

    After shutdown nobody receives from events, so a plain send would block forever and leak the handler goroutine. Watching done gives the sender a way out.
  4. 4. Why is the connection closed by the writer goroutine in stage 4, not directly by the shutdown code?

    The writer drains out until it is closed, writing every queued line, and only then closes the socket. Closing earlier could discard the * server is shutting down message.
  5. 5. In stage 1 the three join, leave and say events travel through one channel. What would be lost with three separate channels?

    With several ready channels, select chooses one at random, so a message could be processed before the join that came earlier. One channel keeps events in the order they were sent.

Summary

  • A chat server is a hub goroutine that owns all state plus a reader and a writer goroutine per connection.
  • Clients and the hub communicate only through channels: events go in, text comes out.
  • Use a reply channel inside an event when the sender needs an answer (name already taken).
  • Bounded out buffers plus a drop or evict policy keep one slow client from stalling everybody.
  • Parse input into events outside the hub, and keep every state change inside it.
  • Shut down with a context, close each out channel from its single owner, make senders watch a done channel and count goroutines with a WaitGroup.

Next: Project: A Small Markdown-to-HTML Converter