Multi-Connection TCP Server with net.Listener

Your Goal for Today

Learning Outcome: Build a TCP server using net.Listener that accepts and manages multiple connections.

This is the front door to our broker. Every message produced and every message consumed will pass through this TCP server. We'll cover:

1. The fundamental pattern of a Go network server: Listen, Accept, Handle.
2. Why a simple, sequential server is insufficient for a real-world system.
3. The idiomatic Go solution for concurrency: one goroutine per connection.
4. A look under the hood to understand why this model is so efficient in Go.
5. A hands-on implementation of a basic concurrent TCP server.

1. The Core TCP Server Pattern

At its heart, any TCP server performs three steps in a loop:

1. Listen: Bind to a network port and listen for incoming connections. In Go, this is done with net.Listen.
2. Accept: Wait for a client to connect. When one does, Accept the connection, which gives you a net.Conn object to communicate with that specific client.
3. Handle: Read data from and write data to the net.Conn object.

Let's start by seeing this pattern in its most basic, sequential form. The following video first demonstrates the problem with a simple blocking server before showing the concurrent solution. We'll focus on the problem first.

As you saw, the l.Accept() call blocks until a client connects. Then, the handle(conn) call blocks until that client disconnects. Only then can the loop continue to accept the next client. For a system like a message broker that needs to serve many producers and consumers simultaneously, this is unworkable.

2. The Go Solution: One Goroutine Per Connection

The solution in Go is both elegant and powerful. Instead of calling the handler function directly, we launch it in a separate goroutine.

go handleConnection(conn)

This simple go keyword is the key. It allows the for loop to immediately iterate and call listener.Accept() again, ready for the next client, while the previously accepted connection is handled concurrently.

This pattern is the foundation of almost all network services in Go.

3. Under the Hood: Why is this so Efficient?

Given your interest in system design and your goal of mastery, it's worth asking: why is this "goroutine-per-connection" model, which is often discouraged in other languages due to "thread-per-connection" overhead, the standard in Go?

The answer lies in Go's runtime scheduler and its integrated network poller. Unlike OS threads, goroutines are extremely lightweight (a few KB of stack). The Go runtime multiplexes these M goroutines onto a small number of N OS threads (the M:N model). When a goroutine makes a blocking network call (like conn.Read()), the runtime doesn't block the OS thread. Instead, it parks the goroutine, informs the network poller it's waiting for data on that connection, and schedules another runnable goroutine on the same OS thread.

This is a deep topic, but the following article gives a superb, concise overview for an experienced engineer.

Understanding this mechanism is key to appreciating Go's design and building high-performance network services. You aren't just creating a thread for every connection; you are handing off a lightweight task to a highly optimized I/O event reactor.

4. Hands-On: Building Your First Concurrent Server

It's time to write the code. Since we're starting our new message broker project, let's set up the directory.

1. In your Go workspace, create a new directory for the project (e.g., gokafka).
2. Inside gokafka, run go mod init gokafka (or your chosen module path).
3. Create the directory structure: cmd/server/.
4. Create a new file: cmd/server/main.go.

Now, let's look at a clean, complete implementation of this pattern.

Now, translate that into your cmd/server/main.go file. Here is a complete version you can use, which implements a simple echo server. This code directly reflects the patterns from the videos and articles.

cmd/server/main.go

package main

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

func main() {
	// 1. Listen for incoming connections.
	listener, err := net.Listen("tcp", ":8080")
	if err != nil {
		log.Fatalf("Failed to bind to port 8080: %v", err)
	}
	defer listener.Close()
	log.Println("TCP server listening on port 8080")

	// 2. The Accept Loop.
	for {
		// Wait for a connection. This is a blocking call.
		conn, err := listener.Accept()
		if err != nil {
			log.Printf("Failed to accept connection: %v", err)
			continue // Don't crash the server, just log the error.
		}

		// 3. Handle the connection in a new goroutine.
		// The loop can now immediately go back to waiting for the next connection.
		log.Printf("Accepted connection from %s", conn.RemoteAddr())
		go handleConnection(conn)
	}
}

// handleConnection reads data from the connection and echoes it back.
func handleConnection(conn net.Conn) {
	// Ensure the connection is closed when the function returns.
	defer conn.Close()
	defer log.Printf("Closing connection from %s", conn.RemoteAddr())

	// Use a buffered reader for efficiency.
	reader := bufio.NewReader(conn)

	for {
		// Read until the next newline character.
		line, err := reader.ReadString('\n')
		if err != nil {
			// If it's an EOF, it just means the client disconnected.
			if err != io.EOF {
				log.Printf("Read error: %v", err)
			}
			return // Exit the handler.
		}

		// Echo the data back to the client.
		_, err = conn.Write([]byte("Echo: " + line))
		if err != nil {
			log.Printf("Write error: %v", err)
			return // Exit on write error.
		}
	}
}

5. Test Your Server

You can now run your server from the root of your gokafka project:

go run ./cmd/server

You should see the "TCP server listening on port 8080" message. To test its concurrent capabilities, open two or three separate terminal windows and use telnet:

Terminal 1:

telnet localhost 8080

Type hello from client 1 and press Enter. You should see Echo: hello from client 1.

Terminal 2:

telnet localhost 8080

Type hello from client 2 and press Enter. You should see Echo: hello from client 2.

Both clients are being served at the same time. Check the server logs; you'll see it accepting and handling both connections. Congratulations, you've built the network foundation of your message broker!

Conclusion

Today you took the first major step in building our message broker. You've implemented the fundamental networking pattern in Go and, importantly, you've seen the runtime mechanics that make it so powerful.

Key Takeaways:

• The core of a Go TCP server is the net.Listen, listener.Accept, handleConnection pattern.
• Handling each connection in its own goroutine (go handleConnection(conn)) is the key to concurrency.
• This pattern is highly efficient because Go's runtime scheduler and network poller work together to avoid blocking OS threads on I/O.
• A net.Conn is an io.Reader and io.Writer, making it easy to work with standard library packages like bufio.

Next Up

Our current server runs forever, but it has a flaw: if we stop it with Ctrl+C, it terminates immediately, potentially cutting off active client connections mid-communication. This is not acceptable for a reliable system.

In the next lesson, we will implement graceful shutdown. You will learn to use sync.WaitGroup and OS signals to ensure that when the server is asked to stop, it waits for all active connections to finish their work before exiting.