These are the notes for Go episode 60. Raju's order counter and his kitchen are two programs that need to talk, and one day they'll be on two computers. We find each other with IP addresses and ports, talk over TCP like a phone call (net.Listen, Accept, net.Dial, net.Conn), serve many callers with a goroutine per connection, stop waiting for silent callers with deadlines, discover that TCP is a byte stream and invent message framing, then shout token numbers with UDP and handle addresses as values with net/netip.
All outputs are from real runs (Go 1.24.7, linux/amd64) on 127.0.0.1. Port numbers and the order of concurrent replies change from run to run.
Facts and sources
- Go 1.18 release notes: "The new
net/netippackage defines a new IP address type,Addr. Compared to the existingnet.IPtype, thenetip.Addrtype takes less memory, is immutable, and is comparable so it supports==and can be used as a map key." The package also definesAddrPortandPrefix. - Everything else (error messages, timings) is from the real runs below.
Addresses and ports
Real-life example: a shopping mall. You need the building's street address, then the shop number inside it.
| Mall | Network | Example |
|---|---|---|
| street address of the building | IP address: names one computer | 192.168.1.25 (IPv4), ::1 (IPv6) |
| shop number inside | port: names one program on that computer, 0–65535 | 9000 |
| "this same building" | loopback address: this computer itself | 127.0.0.1, localhost, ::1 |
IP and port together are written host:port, e.g. 127.0.0.1:9000; IPv6 addresses go in brackets: [::1]:9000. IPv4 addresses are four numbers 0–255; IPv6 is the newer, longer kind. Port 0 in Listen means "pick any free port".
TCP vs UDP
A protocol is an agreed set of rules for talking.
| TCP (Transmission Control Protocol) | UDP (User Datagram Protocol) | |
|---|---|---|
| Real life | a phone call: dial, pick up, talk, hang up | shouting "token 42 ready!" |
| Connection | yes | no |
| Delivery | reliable, in order, lost data re-sent | packets may be lost, repeated or reordered |
| Shape of data | a byte stream (no message boundaries) | packets (each send = one whole message) |
| Go | net.Listen / Accept / net.Dial |
net.ListenPacket / WriteTo / ReadFrom |
| Used for | web, databases, email, SSH | DNS lookups, live video, games |
A packet is a small piece of data sent across the network on its own.
TCP: Listen, Accept, Dial
net.Listen("tcp", addr)→ anet.Listener, the server side waiting for callers.ln.Accept()blocks until the next caller connects and returns anet.Conn.net.Dial("tcp", addr)is the client side: it connects and returns anet.Conn.- A
net.Connis one live connection. It is anio.Readerand anio.Writer(plusClose,LocalAddr,RemoteAddrand the deadline methods), sofmt.Fprintln,bufioandiowork on it like on a file.
package main
import (
"bufio"
"fmt"
"net"
)
func main() {
// the kitchen: listen for connections on port 9000
ln, err := net.Listen("tcp", "127.0.0.1:9000")
if err != nil {
fmt.Println("listen:", err)
return
}
defer ln.Close()
go kitchen(ln)
// the counter: call the kitchen
conn, err := net.Dial("tcp", "127.0.0.1:9000")
if err != nil {
fmt.Println("dial:", err)
return
}
defer conn.Close()
fmt.Fprintln(conn, "2 masala chai") // write one line
reply, _ := bufio.NewReader(conn).ReadString('\n') // read one line
fmt.Print("counter got: ", reply)
_, err = net.Dial("tcp", "127.0.0.1:9001") // nobody listens here
fmt.Println("dial 9001:", err)
}
func kitchen(ln net.Listener) {
for {
c, err := ln.Accept() // wait for the next caller
if err != nil {
return
}
order, _ := bufio.NewReader(c).ReadString('\n')
fmt.Print("kitchen got: ", order)
fmt.Fprintln(c, "ready: "+order[:len(order)-1])
c.Close()
}
}
Real output:
kitchen got: 2 masala chai
counter got: ready: 2 masala chai
dial 9001: dial tcp 127.0.0.1:9001: connect: connection refused
connection refused means the computer answered but no program listens on that port.
A goroutine per connection
Three customers call at once; each chai takes 200 ms.
package main
import (
"bufio"
"fmt"
"net"
"sync"
"time"
)
func cook(c net.Conn) {
defer c.Close()
order, _ := bufio.NewReader(c).ReadString('\n')
time.Sleep(200 * time.Millisecond) // making the chai
fmt.Fprint(c, "ready: ", order)
}
func serve(ln net.Listener, oneAtATime bool) {
for {
c, err := ln.Accept()
if err != nil {
return
}
if oneAtATime {
cook(c) // the next caller waits until this one is done
} else {
go cook(c) // a goroutine per connection
}
}
}
func rush(addr string) {
start := time.Now()
var wg sync.WaitGroup
for i := 1; i <= 3; i++ {
wg.Add(1)
go func() {
defer wg.Done()
c, _ := net.Dial("tcp", addr)
defer c.Close()
fmt.Fprintf(c, "order %d\n", i)
reply, _ := bufio.NewReader(c).ReadString('\n')
fmt.Printf(" %s took %v\n", reply[:len(reply)-1], time.Since(start).Round(100*time.Millisecond))
}()
}
wg.Wait()
}
func main() {
for _, one := range []bool{true, false} {
ln, _ := net.Listen("tcp", "127.0.0.1:0") // port 0: pick any free port
go serve(ln, one)
fmt.Println("one at a time:", one, "on", ln.Addr())
rush(ln.Addr().String())
ln.Close()
}
}
Real output (one run):
one at a time: true on 127.0.0.1:40355
ready: order 3 took 200ms
ready: order 1 took 400ms
ready: order 2 took 600ms
one at a time: false on 127.0.0.1:40739
ready: order 3 took 200ms
ready: order 1 took 200ms
ready: order 2 took 200ms
One at a time, the third caller waited for the other two (200/400/600 ms). With go cook(c) every caller is served in about 200 ms. This is the standard shape of a Go server: one loop that only accepts, and one goroutine per connection, each closing its own connection with defer c.Close(). Goroutines are cheap (episode 43), so thousands of connections are fine.
Timeouts and deadlines
By default Read waits forever. If the other side goes silent (the cook went home, a cable was pulled), the program hangs.
net.DialTimeout(network, addr, d)gives up connecting afterd. (Anet.DialerwithDialContextdoes the same with a context.)conn.SetReadDeadline(t),SetWriteDeadline(t),SetDeadline(t)(both): after the momentt, reads/writes fail with a timeout error.- A deadline is a moment, not a duration: set a new one before each wait. A zero
time.Timeremoves it.
package main
import (
"bufio"
"errors"
"fmt"
"net"
"time"
)
func main() {
ln, _ := net.Listen("tcp", "127.0.0.1:0")
defer ln.Close()
go func() { // a kitchen that takes the order and never answers
for {
c, err := ln.Accept()
if err != nil {
return
}
bufio.NewReader(c).ReadString('\n')
time.Sleep(time.Hour) // the cook went home
}
}()
conn, _ := net.DialTimeout("tcp", ln.Addr().String(), 2*time.Second) // give up connecting after 2 s
defer conn.Close()
fmt.Fprintln(conn, "1 ginger chai")
conn.SetReadDeadline(time.Now().Add(500 * time.Millisecond)) // stop waiting at this moment
start := time.Now()
_, err := bufio.NewReader(conn).ReadString('\n')
fmt.Println("after", time.Since(start).Round(100*time.Millisecond), "->", err)
var ne net.Error
if errors.As(err, &ne) && ne.Timeout() {
fmt.Println("it was a timeout: tell the customer, try again later")
}
}
Real output:
after 500ms -> read tcp 127.0.0.1:50956->127.0.0.1:36033: i/o timeout
it was a timeout: tell the customer, try again later
net.Error is an interface with Timeout() bool; errors.As finds it inside the error so you can tell a timeout from other failures (and retry, as in the mini project). errors.Is(err, os.ErrDeadlineExceeded) also works.
Message framing
TCP keeps the order of bytes but not where one Write ended. Two writes can arrive in one Read; one write can arrive in two. So programs must mark message boundaries: message framing.
package main
import (
"bufio"
"encoding/binary"
"fmt"
"io"
"net"
"time"
)
func main() {
ln, _ := net.Listen("tcp", "127.0.0.1:0")
defer ln.Close()
go func() {
c, _ := net.Dial("tcp", ln.Addr().String())
defer c.Close()
c.Write([]byte("2 chai")) // message 1
c.Write([]byte("1 samosa")) // message 2
time.Sleep(300 * time.Millisecond)
c.Write([]byte("2 chai\n1 samosa\n")) // the same, each ending in \n
for _, m := range []string{"2 chai", "1 samosa with chutney"} {
binary.Write(c, binary.BigEndian, uint16(len(m))) // 2-byte length first
c.Write([]byte(m))
}
}()
c, _ := ln.Accept()
time.Sleep(100 * time.Millisecond) // the kitchen was busy for a moment
buf := make([]byte, 1024)
n, _ := c.Read(buf) // TCP is a stream of bytes, not of messages
fmt.Printf("one Read: %q\n", buf[:n])
r := bufio.NewReader(c)
for i := 0; i < 2; i++ { // framing 1: a delimiter
line, _ := r.ReadString('\n')
fmt.Printf("by delimiter: %q\n", line)
}
for i := 0; i < 2; i++ { // framing 2: a length prefix
var size uint16
binary.Read(r, binary.BigEndian, &size)
msg := make([]byte, size)
io.ReadFull(r, msg) // read exactly size bytes
fmt.Printf("by length %d: %q\n", size, msg)
}
}
Real output:
one Read: "2 chai1 samosa"
by delimiter: "2 chai\n"
by delimiter: "1 samosa\n"
by length 6: "2 chai"
by length 21: "1 samosa with chutney"
| Framing | How | Good for | Watch out |
|---|---|---|---|
| Delimiter | end each message with a special byte, e.g. \n; read with bufio.Reader.ReadString('\n') or bufio.Scanner |
text protocols (SMTP, Redis' RESP, line-based chat) | the delimiter can't appear inside a message (or must be escaped) |
| Length prefix | send the length first (binary.Write(c, binary.BigEndian, uint16(len(m)))), then exactly that many bytes (io.ReadFull) |
binary protocols, databases | limit the maximum length you accept |
bufio over a connection also saves system calls: it reads big chunks and hands them out piece by piece. Big endian means the most significant byte is sent first ("network byte order"). io.ReadFull keeps reading until it has exactly len(buf) bytes.
UDP: net.ListenPacket
package main
import (
"fmt"
"net"
"time"
)
func main() {
// the kitchen's announcement board: UDP, no connection
board, _ := net.ListenPacket("udp", "127.0.0.1:0")
defer board.Close()
// the counter shouts three updates at the board's address
shout, _ := net.ListenPacket("udp", "127.0.0.1:0")
defer shout.Close()
for _, m := range []string{"token 41 ready", "token 42 ready", "token 43 ready"} {
shout.WriteTo([]byte(m), board.LocalAddr()) // one call = one packet
}
buf := make([]byte, 1500)
for {
board.SetReadDeadline(time.Now().Add(300 * time.Millisecond))
n, from, err := board.ReadFrom(buf) // one packet, and who sent it
if err != nil {
fmt.Println("no more packets:", err)
break
}
fmt.Printf("%q from %v\n", buf[:n], from)
}
}
Real output (one run):
"token 41 ready" from 127.0.0.1:36072
"token 42 ready" from 127.0.0.1:36072
"token 43 ready" from 127.0.0.1:36072
no more packets: read udp 127.0.0.1:42493: i/o timeout
net.ListenPacket("udp", addr)→ anet.PacketConn: noAccept, no connection.WriteTo(b, addr)sends one packet;ReadFrom(buf)returns one whole packet and the sender's address.- Nothing tells the receiver that no more packets are coming, so use a deadline.
- On loopback nothing is lost; on a real network packets can be lost or reordered, so UDP programs add their own sequence numbers or accept the loss. Keep packets small (under about 1,200–1,400 bytes) to avoid fragmentation.
net.Dial("udp", addr)gives a "connected" UDP socket whoseWritealways sends toaddr(used in the mini project).
Addresses as values: net.ResolveTCPAddr and net/netip
package main
import (
"fmt"
"net"
"net/netip"
)
func main() {
addr, err := net.ResolveTCPAddr("tcp", "localhost:8080") // name -> IP + port
fmt.Println("resolved:", addr, err)
ip, _ := netip.ParseAddr("192.168.1.25")
fmt.Println(ip, "IPv4:", ip.Is4(), "loopback:", ip.IsLoopback(), "private:", ip.IsPrivate())
ap, _ := netip.ParseAddrPort("[::1]:9000")
fmt.Println("IPv6 address:", ap.Addr(), "port:", ap.Port(), "loopback:", ap.Addr().IsLoopback())
shop, _ := netip.ParsePrefix("192.168.1.0/24") // the shop's own network
fmt.Println("in the shop network:", shop.Contains(ip))
seen := map[netip.Addr]int{} // netip.Addr is comparable: a map key
seen[ip]++
seen[netip.MustParseAddr("192.168.1.25")]++
fmt.Println("visits from", ip, "=", seen[ip])
_, err = netip.ParseAddr("300.1.1.1")
fmt.Println(err)
}
Real output:
resolved: 127.0.0.1:8080 <nil>
192.168.1.25 IPv4: true loopback: false private: true
IPv6 address: ::1 port: 9000 loopback: true
in the shop network: true
visits from 192.168.1.25 = 2
ParseAddr("300.1.1.1"): IPv4 field has value >255
net.ResolveTCPAddr("tcp", "localhost:8080")turns a name into an IP and port, asking DNS (the internet's phone book that maps names to IP addresses) when needed.netip.ParseAddr,ParseAddrPort,ParsePrefixparse addresses;Is4,Is6,IsLoopback,IsPrivateclassify them.- A prefix (CIDR notation, e.g.
192.168.1.0/24) means all addresses sharing the first 24 bits;Containschecks membership. - Private addresses (
10.x,172.16–31.x,192.168.x) are for home and office networks. netip.Addris small, immutable and comparable: use it with==and as a map key (the two separately parsed copies above counted as one key).
Mini project: the kitchen order line
- Kitchen: TCP server, a goroutine per connection, one order per line, 10 s idle deadline.
- Reply
ready: <order>. - Counter:
DialTimeout2 s, read deadline 3 s, retry once on a timeout. - UDP board: announce
token N readywhen an order is done.
Solution
// The kitchen order line (Go episode 60 mini project): a TCP kitchen, a counter that retries, a UDP token board.
package main
import (
"bufio"
"errors"
"fmt"
"net"
"strings"
"sync/atomic"
"time"
)
var tokens atomic.Int64 // shared by all connections
// kitchen: one order per line, a goroutine per connection, 10 s idle deadline.
func kitchen(ln net.Listener, board string) {
for {
c, err := ln.Accept()
if err != nil {
return // listener closed
}
go handle(c, board)
}
}
func handle(c net.Conn, board string) {
defer c.Close()
udp, err := net.Dial("udp", board) // a "connected" UDP socket: Write sends to board
if err != nil {
return
}
defer udp.Close()
r := bufio.NewReader(c)
for {
c.SetReadDeadline(time.Now().Add(10 * time.Second)) // drop silent callers
line, err := r.ReadString('\n')
if err != nil {
return // EOF, timeout or a broken connection
}
order := strings.TrimSpace(line)
time.Sleep(50 * time.Millisecond) // cooking
c.SetWriteDeadline(time.Now().Add(2 * time.Second))
fmt.Fprintf(c, "ready: %s\n", order)
fmt.Fprintf(udp, "token %d ready (%s)", tokens.Add(1), order)
}
}
// order sends one order and waits for the reply, retrying once on a timeout.
func order(addr, what string) (string, error) {
var err error
for attempt := 1; attempt <= 2; attempt++ {
var c net.Conn
c, err = net.DialTimeout("tcp", addr, 2*time.Second)
if err != nil {
continue
}
fmt.Fprintln(c, what)
c.SetReadDeadline(time.Now().Add(3 * time.Second))
var reply string
reply, err = bufio.NewReader(c).ReadString('\n')
c.Close()
if err == nil {
return strings.TrimSpace(reply), nil
}
var ne net.Error
if !errors.As(err, &ne) || !ne.Timeout() {
break // not a timeout: don't retry
}
}
return "", err
}
func main() {
board, _ := net.ListenPacket("udp", "127.0.0.1:0")
defer board.Close()
go func() {
buf := make([]byte, 1500)
for {
n, _, err := board.ReadFrom(buf)
if err != nil {
return
}
fmt.Printf(" board: %s\n", buf[:n])
}
}()
ln, _ := net.Listen("tcp", "127.0.0.1:0")
defer ln.Close()
go kitchen(ln, board.LocalAddr().String())
for _, o := range []string{"2 masala chai", "1 samosa"} {
reply, err := order(ln.Addr().String(), o)
fmt.Println("counter:", reply, err)
}
_, err := order("127.0.0.1:1", "1 ginger chai") // nobody there
fmt.Println("counter:", err)
time.Sleep(100 * time.Millisecond) // let the board print
}
Real output (one run; the board lines can move around because they arrive on another goroutine):
board: token 1 ready (2 masala chai)
counter: ready: 2 masala chai <nil>
counter: ready: 1 samosa <nil>
counter: dial tcp 127.0.0.1:1: connect: connection refused
board: token 2 ready (1 samosa)
tokens is an atomic.Int64 (episode 50) because many connection goroutines add to it at once.
Common mistakes (and the real messages)
| Mistake | What you see | Why | Fix |
|---|---|---|---|
ignoring Dial's error |
dial tcp 127.0.0.1:9001: connect: connection refused |
nothing listens on that port | check err; retry later or report |
| handling connections inside the accept loop | the 3rd caller takes 600 ms | one at a time | go handle(conn) |
no deadline on Read |
the program hangs forever | the peer went silent | SetReadDeadline before each read |
expecting one Write = one Read |
"2 chai1 samosa" |
TCP is a byte stream | delimiter or length prefix |
forgetting conn.Close() |
accept tcp ...: too many open files |
each connection uses a file descriptor | defer c.Close() |
| UDP for data that must arrive | silently lost packets | UDP never re-sends | TCP, or your own acknowledgements |
| invalid address text | ParseAddr("300.1.1.1"): IPv4 field has value >255 |
each IPv4 part is 0–255 | validate input, check the error |
A file descriptor is the numbered handle the operating system gives each open file or connection; a process may only have a limited number open.
Practice
- Change the kitchen so a caller can send many orders on one connection (it already loops — test it with two
Fprintlns before reading). - Write a
readMsg(r *bufio.Reader) ([]byte, error)for the length-prefix framing that rejects messages over 4 KB. - What happens to the UDP board if nothing listens on its address when the counter shouts?
- Use
map[netip.Addr]intto count connections per client IP in the accept loop.
Solutions
1. Two lines written back to back are read one by one by the bufio.Reader loop; the kitchen replies to each in order.
2.
func readMsg(r *bufio.Reader) ([]byte, error) {
var size uint16
if err := binary.Read(r, binary.BigEndian, &size); err != nil {
return nil, err
}
if size > 4096 {
return nil, fmt.Errorf("message too big: %d bytes", size)
}
msg := make([]byte, size)
_, err := io.ReadFull(r, msg)
return msg, err
}
3. WriteTo usually still succeeds: UDP has no connection, so the sender isn't told the packet was lost (on loopback a later read on a connected UDP socket may report connection refused from an ICMP message, but you can't rely on it).
4.
seen := map[netip.Addr]int{}
for {
c, err := ln.Accept()
if err != nil {
return
}
ap, _ := netip.ParseAddrPort(c.RemoteAddr().String())
seen[ap.Addr()]++ // only the accept loop touches seen: no lock needed
go handle(c)
}
Quick quiz
1. The client writes "hi" then "there" over TCP. What can one Read on the server return? (From the video.)
A. only "hi" · B. only "hithere" · C. "hi", "hithere" or even "h" · D. always "hi" then "there"
Answer
C. TCP is a byte stream; a Read returns whatever bytes have arrived. Frame your messages.
2. You want each read to wait at most 5 s, on a connection that lives for an hour. Is one SetReadDeadline(time.Now().Add(5*time.Second)) at the start enough?
Answer
No. A deadline is a moment; after 5 s every read fails. Set a new deadline before each read.
3. What does listening on 127.0.0.1:0 do?
Answer
Picks any free port on the loopback address; ln.Addr() tells you which one.
Interview questions
- TCP vs UDP? TCP: connection, reliable, ordered byte stream. UDP: connectionless packets, no delivery or order guarantee, lower overhead.
- Structure of a TCP server in Go?
net.Listen, a loop callingAccept,go handle(conn)withdefer conn.Close()and deadlines. - Why do TCP protocols need framing? TCP doesn't preserve message boundaries; use delimiters or length prefixes.
- How do you avoid hanging on a dead peer?
DialTimeout/DialContextfor connecting,SetReadDeadline/SetWriteDeadlinebefore each operation. - How do you detect a timeout?
errors.As(err, &netErr) && netErr.Timeout(), orerrors.Is(err, os.ErrDeadlineExceeded). - What does
connection refusedmean? The host is reachable but nothing listens on that port. - Why
net/netipovernet.IP?netip.Addris smaller, immutable and comparable (map keys,==). - What is a file descriptor and why does closing connections matter? An OS handle for an open file or socket; leaking them ends in
too many open files.
Glossary
| Term | Meaning | Example |
|---|---|---|
| Network | computers connected so programs can exchange data | your Wi-Fi |
| IP address | a number naming one computer on a network | 192.168.1.25 |
| IPv4 / IPv6 | the older 4-number and newer longer address kinds | 127.0.0.1 / ::1 |
| Port | a number (0–65535) naming one program on a computer | 9000 |
| Loopback / localhost | the address of this computer itself | 127.0.0.1 |
| Protocol | agreed rules for talking | TCP, UDP, HTTP |
| TCP | reliable, ordered, connection-based byte stream | net.Dial("tcp", ...) |
| UDP | connectionless packets, no guarantees | net.ListenPacket("udp", ...) |
| Packet | a small piece of data sent on its own | one UDP message |
| Connection | a live two-way link between two programs | a net.Conn |
| Server / client | the side that listens / the side that dials | kitchen / counter |
net.Listen |
starts listening on an address | net.Listen("tcp", ":9000") |
net.Listener / Accept |
the listening socket / waits for the next caller | c, err := ln.Accept() |
net.Dial / net.DialTimeout |
connect to an address (with a time limit) | net.DialTimeout("tcp", a, 2*time.Second) |
net.Conn |
one connection: Reader + Writer + deadlines | fmt.Fprintln(conn, ...) |
| Connection refused | nothing listens on that port | connect: connection refused |
| Deadline | a moment after which waiting fails | SetReadDeadline(t) |
| Timeout | the error when a deadline passes | i/o timeout |
net.Error |
error interface with Timeout() |
errors.As(err, &ne) |
| Byte stream | data with order but no message boundaries | TCP |
| Message framing | marking where each message ends | \n, length prefix |
| Delimiter | a byte that ends a message | \n |
| Length prefix | the size sent before the message | 2 bytes, big endian |
| Big endian | most significant byte first | binary.BigEndian |
io.ReadFull |
reads exactly len(buf) bytes |
io.ReadFull(r, msg) |
bufio over a connection |
buffered reading, fewer system calls | bufio.NewReader(conn) |
net.ListenPacket |
opens a UDP socket | net.ListenPacket("udp", ...) |
WriteTo / ReadFrom |
send / receive one UDP packet | n, from, err := pc.ReadFrom(buf) |
| DNS | maps names to IP addresses | localhost → 127.0.0.1 |
net.ResolveTCPAddr |
resolves host:port to a *net.TCPAddr |
net.ResolveTCPAddr("tcp", "localhost:8080") |
net/netip |
small, comparable address types (Go 1.18) | netip.ParseAddr |
netip.Addr / AddrPort / Prefix |
an IP / IP + port / a network range | 192.168.1.0/24 |
| Private address | an address for home/office networks | 192.168.x.x |
| File descriptor | an OS handle for an open file or socket | leaking → too many open files |
Summary
- An IP address finds the computer, a port finds the program;
127.0.0.1is this computer. - TCP = a reliable, ordered connection:
net.Listen+Accepton the server,net.Dialon the client, a goroutine per connection. - Put deadlines on every wait (
DialTimeout,SetReadDeadline), and checkTimeout(). - TCP is a byte stream: frame messages with a delimiter (bufio) or a length prefix (
encoding/binary+io.ReadFull). - UDP sends whole packets with no connection and no guarantees:
ListenPacket,WriteTo,ReadFrom. net/netipgives small, comparable addresses, prefixes and parsing with clear errors.
Next episode: HTTP servers with net/http: http.Handler, HandlerFunc, ServeMux, Go 1.22 routing patterns, PathValue, query and form values, FileServer and httptest.