TCP Sockets

A reliable byte stream

Go’s net package models a TCP connection as a net.Conn — which is just an io.Reader and an io.Writer with an address and deadlines bolted on. That single fact is the key to the whole package: because a connection is a Reader/Writer, everything that works on files and buffers — io.Copy, bufio, json.NewDecoder — works on a socket unchanged. A server listens and accepts; a client dials:

graph LR
C["client<br/>net.Dial"] -->|"3-way handshake"| S["server<br/>net.Listen + Accept"]
C -->|"Write bytes →"| S
S -->|"← Write bytes"| C
C -.->|"Close"| S

// server: accept connections, a goroutine each
ln, err := net.Listen("tcp", ":9000")
if err != nil { log.Fatal(err) }
defer ln.Close()
for {
	conn, err := ln.Accept()
	if err != nil { continue }
	go handle(conn) // one goroutine per connection
}

// client: dial and use the Conn as a Reader/Writer
conn, err := net.Dial("tcp", "example.com:9000")
if err != nil { log.Fatal(err) }
defer conn.Close()
fmt.Fprintln(conn, "hello")

The Conn interface, hands-on

Real sockets need a network, but a net.Conn is an interface — so we can exercise the exact same Read/Write mechanics in memory with net.Pipe(), which returns two connected ends. This runs anywhere, no network involved:

package main

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

func main() {
// net.Pipe gives two ends of an in-memory connection — the SAME
// net.Conn interface a TCP socket implements, with no network at all.
server, client := net.Pipe()

// the "server" side: read one line, write a framed reply, then close
go func() {
	defer server.Close()
	line, _ := bufio.NewReader(server).ReadString('\n')
	fmt.Fprintf(server, "echo: %s", line)
}()

// the "client" side: send a request, read until the server closes
fmt.Fprintf(client, "hello\n")
reply, _ := io.ReadAll(client)
fmt.Print(string(reply)) // echo: hello
client.Close()
}

Framing: where does a message end?

TCP is a stream, not a sequence of messages. One Write of 100 bytes may arrive as two Reads of 60 and 40 — or two Writes may coalesce into one Read. So you need framing: an agreed rule for where each message ends. The two common rules are a delimiter (a newline, say) and a length prefix. Here the server bufio.Scanners on newlines and correctly recovers three distinct messages no matter how TCP chunks them — all over an in-memory net.Pipe:

package main

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

func main() {
server, client := net.Pipe()

// server: split the byte stream back into messages on '\n'
done := make(chan struct{})
go func() {
	defer close(done)
	sc := bufio.NewScanner(server)
	for sc.Scan() {
		fmt.Printf("message: %q\n", sc.Text())
	}
}()

// client: three logical messages, newline-framed
io.WriteString(client, "alpha\nbravo\n")
io.WriteString(client, "charlie\n") // a separate Write — framing still works
client.Close()                       // signals EOF; scanner loop ends
<-done
}

For binary protocols a delimiter is fragile (the payload might contain the delimiter byte), so you prefix each message with its length. That pattern — and designing a full protocol with a header and checksum — gets its own page: framing & custom protocols.

Deadlines, not blocking forever

A network read can hang indefinitely — a peer that opened a connection and then went silent will park your goroutine forever. Deadlines are the fix: they make a stalled Read/Write return a net.Error with Timeout()==true once the wall-clock deadline passes. (Deadlines are absolute times, not durations — re-set them before each operation.) net.Pipe honors deadlines too, so this runs in-process:

package main

import (
"errors"
"fmt"
"net"
"time"
)

func main() {
server, client := net.Pipe()
defer server.Close()
defer client.Close()

// No one ever writes to this pipe, so the Read would block forever —
// the deadline turns that into a timeout error instead.
client.SetReadDeadline(time.Now().Add(50 * time.Millisecond))

buf := make([]byte, 16)
_, err := client.Read(buf)

var netErr net.Error
if errors.As(err, &netErr) && netErr.Timeout() {
	fmt.Println("read timed out — peer is idle, connection still usable")
} else {
	fmt.Println("unexpected:", err)
}
}

In real code: conn.SetDeadline(time.Now().Add(30*time.Second)) for the whole connection, or SetReadDeadline/SetWriteDeadline separately. A timeout is not fatal — extend and retry, or treat it as an idle client and close.

One goroutine per connection

The idiomatic server is an Accept loop that hands each connection to its own goroutine. Goroutines are cheap (a few KB), so this scales to tens of thousands of connections — the runtime multiplexes them onto threads and the OS poller for you, no thread pool to size:

func handle(conn net.Conn) {
	defer conn.Close()
	conn.SetDeadline(time.Now().Add(30 * time.Second))
	sc := bufio.NewScanner(conn)
	for sc.Scan() {
		line := sc.Text()
		fmt.Fprintf(conn, "you said: %s\n", line) // echo, framed
	}
}

for {
	conn, err := ln.Accept()
	if err != nil { return } // listener closed
	go handle(conn)          // never block the accept loop
}

The rule: never do slow work in the Accept loop itself — accept, hand off, loop. Any state shared between connection goroutines must be synchronized (a sync.Mutex or a channel).

Reference

See also

• UDP sockets — the connectionless cousin, with message boundaries but no reliability.
• framing & custom protocols — length-prefix framing and designing a binary protocol on top of a stream.
• fmt & io — the io.Reader/io.Writer interfaces a net.Conn is built on.
• the Go scheduler — why one goroutine per connection scales.
• TLS & HTTPS — wrapping a TCP connection in encryption.

Next: the connectionless cousin — UDP sockets.

Related topics