TCP Chat Server

Build a multi-client chat server that broadcasts messages to all connected users.

GoroutinesNetworkingChannels

Overview

A chat server has to do two things that pull in opposite directions at once: accept new TCP connections while simultaneously reading from every connection already open, and relay whatever any one client types out to every other client, all without ever letting two goroutines write to the same slice at the same time. Go's combination of lightweight goroutines and channels makes this almost boringly straightforward compared to the same problem in a language without built-in concurrency support — one goroutine per client connection, plus one dedicated broadcaster goroutine that owns the client list and is the only thing ever allowed to touch it.

By the end of this tutorial you will have a working `net.Listen`-based TCP server: each incoming connection gets its own goroutine reading lines from that client and forwarding them to a single shared `broadcast` channel, and one central goroutine reads from that channel and writes each message out to every other connected client's socket. You will see why routing all writes to the shared client list through a single goroutine — the "own it in one place" pattern — is often simpler and just as fast as protecting a shared slice with a mutex directly.

What You'll Build

A `Client` struct wrapping a `net.Conn` and the username chosen at connect time.
An accept loop using `net.Listen` and `Accept()` that spawns one goroutine per connection.
A per-client read loop using `bufio.Scanner` that forwards each line to a shared `broadcast` channel.
A central `broadcaster()` goroutine that owns the client list and fans every message out to everyone else.
Safe client registration and removal on connect/disconnect via dedicated `register`/`unregister` channels.
A `main()` that starts the listener and the broadcaster and loops forever accepting new clients.

Prerequisites

Goroutines and channels — the same worker-pool concepts from the Concurrent URL Checker project.
The `net` package — `net.Listen`, `Listener.Accept()`, and reading/writing a `net.Conn`.
`bufio.Scanner` for reading newline-delimited text from a connection.
Struct methods with pointer receivers — `func (c *Client) ...`.
The `select` statement for waiting on multiple channels at once (used briefly in the broadcaster).

Project Structure

The whole server lives in a single file, `main.go`. A `Client` struct pairs a `net.Conn` with a display name. Three unbuffered channels connect every goroutine to a single `broadcaster()` goroutine: `register` (a new client just connected), `unregister` (a client disconnected), and `broadcast` (a chat message needs to go out to everyone). `broadcaster()` is the only goroutine that ever reads or writes the `clients` map directly — every other goroutine only ever talks to it through those three channels, which is what makes the whole design safe without a single explicit `sync.Mutex` anywhere in the file.

Each connected client is handled by its own `handleClient()` goroutine, spawned from the accept loop in `main()`. That goroutine's only job is reading lines from its own socket and forwarding them (with the sender's name attached) onto the shared `broadcast` channel — it never writes to any other client's socket directly, which is what `broadcaster()` is for.

Step 1: Define the Client and Message Types

Every message that reaches `broadcaster()` needs to carry both the text and, implicitly, which `Client` sent it, so the message text is pre-formatted with the sender's name before it is ever put on the `broadcast` channel — that keeps `broadcaster()` itself simple: it never needs to know who sent a message, only where to send it.

package main

import "net"

// Client represents one connected chat participant: their raw TCP
// connection and the display name they chose when they connected.
type Client struct {
	conn net.Conn
	name string
}

Step 2: Build the Accept Loop

`net.Listen("tcp", addr)` opens a socket bound to `addr` and returns a `net.Listener`; calling `Accept()` on it blocks until a client connects, then returns a `net.Conn` for that one connection and immediately lets the next call to `Accept()` block again. Wrapping every accepted connection in `go handleClient(...)` is what lets the accept loop keep listening for new clients without ever waiting on an existing one to finish.

import (
	"fmt"
	"log"
	"net"
)

// acceptLoop blocks forever, accepting new TCP connections on listener
// and spawning a dedicated goroutine to handle each one.
func acceptLoop(listener net.Listener, register, unregister chan *Client, broadcast chan string) {
	for {
		conn, err := listener.Accept() // Blocks until a new client connects
		if err != nil {
			log.Println("accept error:", err) // A single failed accept shouldn't crash the whole server
			continue
		}
		go handleClient(conn, register, unregister, broadcast) // One goroutine per connection; the loop moves on immediately
	}
}

Step 3: Handle One Client Connection

`handleClient()` first asks for a username with `fmt.Fprintln(conn, ...)` (writing straight to the socket) and reads the reply with a `bufio.Scanner`, then sends this new `Client` on the `register` channel so `broadcaster()` can add it to the shared list. `defer` schedules the `unregister` send and `conn.Close()` together, so however this function eventually returns — the client closes the connection, or `Scan()` hits an error — cleanup always happens.

import (
	"bufio"
	"fmt"
	"net"
	"strings"
)

// handleClient owns one client's connection for its entire lifetime: it
// prompts for a name, registers the client, then relays every line the
// client sends to the shared broadcast channel until the connection closes.
func handleClient(conn net.Conn, register, unregister chan *Client, broadcast chan string) {
	fmt.Fprintln(conn, "Enter your name:") // Write directly to the socket; the client sees this as server output
	scanner := bufio.NewScanner(conn)
	if !scanner.Scan() { // Client disconnected before sending a name at all
		conn.Close()
		return
	}
	name := strings.TrimSpace(scanner.Text())
	if name == "" {
		name = "Anonymous"
	}

	client := &Client{conn: conn, name: name}
	register <- client // Tell broadcaster() to add this client to the shared list

	defer func() {
		unregister <- client // Runs no matter how this function returns: disconnect, error, or scanner ending
		conn.Close()
	}()

	broadcast <- fmt.Sprintf("* %s has joined the chat *", name)

	for scanner.Scan() { // Blocks here until the client sends a line, disconnects, or the connection errors out
		text := strings.TrimSpace(scanner.Text())
		if text == "" {
			continue // Ignore blank lines instead of broadcasting an empty message
		}
		broadcast <- fmt.Sprintf("%s: %s", name, text) // Prefix with the sender's name before it ever reaches broadcaster()
	}
}

Step 4: Broadcast Messages to Every Client

`broadcaster()` is the one goroutine in the whole program that owns the `clients` map outright — nothing else ever reads or writes it. A `select` statement waits on all three channels at once and handles whichever one has a value ready first, which is what lets one goroutine safely serve `register`, `unregister`, and `broadcast` without any of them blocking the others for long.

// broadcaster owns the live client list and is the only goroutine allowed
// to read or write it, which is what keeps this design safe without a
// mutex: every other goroutine only ever talks to it through channels.
func broadcaster(register, unregister chan *Client, broadcast chan string) {
	clients := make(map[*Client]bool) // Set of currently connected clients; the bool value is never actually used

	for {
		select { // Waits on whichever of these three channels has a value ready first
		case client := <-register:
			clients[client] = true
			fmt.Println("registered:", client.name)

		case client := <-unregister:
			if _, ok := clients[client]; ok {
				delete(clients, client)
				fmt.Println("unregistered:", client.name)
			}

		case message := <-broadcast:
			for client := range clients { // Fan the message out to every currently connected client
				fmt.Fprintln(client.conn, message) // Writing to a closed/dead conn here just returns a harmless error
			}
		}
	}
}

Step 5: Manage the Client List Safely

It is worth being explicit about why Step 4 needs no `sync.Mutex` at all: `register`, `unregister`, and `broadcast` are all unbuffered channels, and `broadcaster()`'s `select` loop processes exactly one event at a time, one at a time, forever. Every other goroutine in the program only ever interacts with the client list indirectly, by sending a value on one of those three channels — this is Go's "share memory by communicating" philosophy applied directly, rather than the more traditional "communicate by sharing memory (behind a lock)" a Java or C# chat server would typically use.

// No code in this step — it is a checkpoint. The three channels declared
// in Step 6's main() (register, unregister, broadcast) are the entire
// synchronization mechanism for the client list; nothing else is needed.

Step 6: Wire Up main()

`main()` creates the three shared channels, starts `broadcaster()` as its own long-lived goroutine, opens the TCP listener, and hands off to `acceptLoop()`, which then runs forever. Notice that `acceptLoop()` is called directly (not with `go`) as the very last line of `main()` — if it were started as a goroutine instead, `main()` would return immediately afterward and the whole program would exit before ever accepting a single client.

import (
	"fmt"
	"log"
	"net"
)

const port = ":9000"

func main() {
	register := make(chan *Client)   // New client just connected and picked a name
	unregister := make(chan *Client) // A client's connection ended
	broadcast := make(chan string)   // A line of chat text needs to go out to everyone

	go broadcaster(register, unregister, broadcast) // Runs for the entire lifetime of the server

	listener, err := net.Listen("tcp", port)
	if err != nil {
		log.Fatal("failed to start server:", err) // Can't recover from this; exit immediately
	}
	defer listener.Close()

	fmt.Println("Chat server listening on port", port)
	acceptLoop(listener, register, unregister, broadcast) // Blocks forever; must NOT be run with "go" or main() would exit
}

Complete Code

Here is the full server assembled in one file, ready to save as `main.go` and run with `go run main.go`. Connect with any TCP client, for example `nc localhost 9000` (or `telnet localhost 9000`) from multiple terminals at once.

package main

import (
	"bufio"
	"fmt"
	"log"
	"net"
	"strings"
)

const port = ":9000"

type Client struct {
	conn net.Conn
	name string
}

func broadcaster(register, unregister chan *Client, broadcast chan string) {
	clients := make(map[*Client]bool)

	for {
		select {
		case client := <-register:
			clients[client] = true
			fmt.Println("registered:", client.name)

		case client := <-unregister:
			if _, ok := clients[client]; ok {
				delete(clients, client)
				fmt.Println("unregistered:", client.name)
			}

		case message := <-broadcast:
			for client := range clients {
				fmt.Fprintln(client.conn, message)
			}
		}
	}
}

func handleClient(conn net.Conn, register, unregister chan *Client, broadcast chan string) {
	fmt.Fprintln(conn, "Enter your name:")
	scanner := bufio.NewScanner(conn)
	if !scanner.Scan() {
		conn.Close()
		return
	}
	name := strings.TrimSpace(scanner.Text())
	if name == "" {
		name = "Anonymous"
	}

	client := &Client{conn: conn, name: name}
	register <- client

	defer func() {
		unregister <- client
		conn.Close()
	}()

	broadcast <- fmt.Sprintf("* %s has joined the chat *", name)

	for scanner.Scan() {
		text := strings.TrimSpace(scanner.Text())
		if text == "" {
			continue
		}
		broadcast <- fmt.Sprintf("%s: %s", name, text)
	}
}

func acceptLoop(listener net.Listener, register, unregister chan *Client, broadcast chan string) {
	for {
		conn, err := listener.Accept()
		if err != nil {
			log.Println("accept error:", err)
			continue
		}
		go handleClient(conn, register, unregister, broadcast)
	}
}

func main() {
	register := make(chan *Client)
	unregister := make(chan *Client)
	broadcast := make(chan string)

	go broadcaster(register, unregister, broadcast)

	listener, err := net.Listen("tcp", port)
	if err != nil {
		log.Fatal("failed to start server:", err)
	}
	defer listener.Close()

	fmt.Println("Chat server listening on port", port)
	acceptLoop(listener, register, unregister, broadcast)
}

Sample Run

Click Run to see what this code prints.

Extend This Project

Add private messaging with a `/msg <name> <text>` command parsed inside `handleClient()` before broadcasting.
Give `broadcaster()` a `whoisonline` channel so a client can type `/who` and get back a list of currently connected names.
Add graceful shutdown: listen for `SIGINT` with `os/signal`, close the listener, and notify every connected client before exiting.
Rate-limit each client with a `time.Ticker` so a single connection cannot flood the broadcast channel with messages.
Add chat rooms by giving each `Client` a `room` field and changing `broadcaster()` to fan messages out only to clients in the same room.

Summary

You built a working multi-client chat server using goroutines and channels as Go's answer to a problem most languages solve with threads and locks: one goroutine per client connection, a single `broadcaster()` goroutine that is the sole owner of the shared client list, and three channels — `register`, `unregister`, `broadcast` — as the only path any other goroutine has to affect that list. That "own the shared state in one goroutine, talk to it only through channels" pattern is Go's idiomatic alternative to `sync.Mutex`, and it is one you will see again in almost any non-trivial concurrent Go server.