The net Package

Implemented by *TCPConn, *UDPConn, *UnixConn, *IPConn, *tls.Conn, and the pair from net.Pipe

Read and write like a file, with one addition that matters: a deadline. Nothing else bounds a read, so a peer that connects and then goes quiet holds the goroutine open forever.

defer c.Close()
c.SetDeadline(time.Now().Add(30 * time.Second))

fmt.Fprintln(c, "PING")

buf := make([]byte, 64)
n, err := c.Read(buf)
if err != nil {
    log.Println("read:", err)
    return
}
fmt.Println(c.RemoteAddr(), string(buf[:n]))

Implemented by *TCPListener, *UnixListener, and the listener tls.NewListener wraps

Accept in a loop, one goroutine per connection. Closing the listener is what makes the blocked Accept return, and testing for ErrClosed is how the loop tells a shutdown from a real failure.

defer ln.Close()

for {
    conn, err := ln.Accept()
    if err != nil {
        if errors.Is(err, net.ErrClosed) {
            return
        }
        continue
    }
    go func(c net.Conn) {
        defer c.Close()
        io.Copy(c, c)
    }(conn)
}

Implemented by *UDPConn, *UnixConn on unixgram, *IPConn

One call moves one datagram, and the sender comes back with it because there is no fixed peer to assume. Size the buffer for the largest packet you expect; anything longer is truncated and the rest is gone.

defer pc.Close()

buf := make([]byte, 1500)
pc.SetReadDeadline(time.Now().Add(5 * time.Second))

n, addr, err := pc.ReadFrom(buf)
if err != nil {
    return
}

pc.WriteTo([]byte("ack"), addr)
fmt.Println(n, "bytes from", addr)

Implemented by *TCPAddr, *UDPAddr, *UnixAddr, *IPAddr, *IPNet

Two strings is all the interface promises, so reaching the port means asserting to the concrete type. That is cheaper and safer than parsing the string back apart.

a := c.RemoteAddr()
fmt.Println(a.Network(), a.String()) // tcp 192.0.2.9:54123

if tcp, ok := a.(*net.TCPAddr); ok {
    fmt.Println(tcp.IP, tcp.Port)
}

Implemented by *OpError, *DNSError, *AddrError, and the string error types

Timeout is the one question worth asking of a network error, because it is the one whose answer changes what you do. A deadline that expired is worth another attempt; a refused connection is not.

var ne net.Error
if errors.As(err, &ne) && ne.Timeout() {
    fmt.Println("timed out, worth retrying")
}

Satisfies net.Conn, io.Reader, io.Writer, io.Closer, io.ReaderFrom, io.WriterTo

The typed connection is what gets you the TCP-only calls. CloseWrite is the interesting one: it sends the peer an EOF so they know the request is finished, while you stay open to read the answer.

defer c.Close()

c.SetNoDelay(true)   // send small writes immediately
c.SetKeepAlive(true)
c.SetKeepAlivePeriod(30 * time.Second)

fmt.Fprintln(c, "request")
c.CloseWrite()       // "that is all I am sending"

io.Copy(os.Stdout, c)

Satisfies net.Listener

AcceptTCP saves the type assertion when you want the TCP-only methods on each connection. The deadline gives a blocked accept somewhere to go, which is one way to check a shutdown flag on a timer.

defer ln.Close()

ln.SetDeadline(time.Now().Add(time.Second))

c, err := ln.AcceptTCP()
if err != nil {
    return // a timeout lands here too
}
defer c.Close()
c.SetNoDelay(true)

Satisfies net.Conn, net.PacketConn

Reading with the From variant is what tells you who to answer. Raising the receive buffer is worth doing on a socket that takes bursts, since a full kernel buffer drops packets and tells nobody.

defer c.Close()
c.SetReadBuffer(1 << 20)

buf := make([]byte, 1500)
n, addr, err := c.ReadFromUDP(buf)
if err != nil {
    return
}

c.WriteToUDP([]byte("pong"), addr)
fmt.Println(n, addr.IP, addr.Port)

Satisfies net.Conn, net.PacketConn

A local socket, so the same reads and writes as TCP with none of the network in between. ReadMsgUnix and WriteMsgUnix are the pair that carry a file descriptor from one process to another.

defer c.Close()

c.Write([]byte("hello"))
c.CloseWrite()

Satisfies net.Listener

The socket is a file on disk, and Close deletes it by default. Turn that off when the path was handed to you by systemd or a supervisor, since removing it takes the service down with it.

ln.SetUnlinkOnClose(false)
defer ln.Close()

c, err := ln.AcceptUnix()
if err != nil {
    return
}
defer c.Close()

Satisfies net.Addr through IPAddr, fmt.Stringer, encoding.TextMarshaler

A bad address comes back as nil rather than an error, so the check is a nil test. Use Equal rather than ==: one IPv4 address has a 4-byte and a 16-byte form and only Equal knows they are the same.

ip := net.ParseIP("10.0.0.37")
if ip == nil {
    log.Fatal("bad address")
}

fmt.Println(ip.To4(), ip.IsPrivate(), ip.IsLoopback()) // 10.0.0.37 true false
fmt.Println(ip.Equal(net.ParseIP("::ffff:10.0.0.37"))) // true

Satisfies net.Addr, fmt.Stringer

Contains is the allowlist check, and it is why you keep the second return from ParseCIDR rather than the first. Mask.Size turns the mask back into the prefix length a human wrote.

_, block, _ := net.ParseCIDR("10.0.0.0/24")

fmt.Println(block.Contains(net.ParseIP("10.0.0.99"))) // true

ones, bits := block.Mask.Size()
fmt.Println(block.IP, ones, bits) // 10.0.0.0 24 32

Satisfies fmt.Stringer

Masking an address clears its host bits, which is how you get from an address to the network it sits in. Size is the inverse of CIDRMask.

m := net.CIDRMask(24, 32)

ones, bits := m.Size()
fmt.Println(m, ones, bits) // ffffff00 24 32

fmt.Println(net.ParseIP("10.0.0.37").Mask(m)) // 10.0.0.0

Satisfies net.Addr

The fields are there, so reading a client's port is a field access rather than a parse. AddrPort hands back the netip form, which is comparable and works as a map key.

a, err := net.ResolveTCPAddr("tcp", "127.0.0.1:9000")
if err != nil {
    log.Fatal(err)
}

fmt.Println(a.IP, a.Port, a.Network()) // 127.0.0.1 9000 tcp
fmt.Println(a.AddrPort())              // [::ffff:127.0.0.1]:9000

Satisfies net.Addr

What ReadFromUDP hands back, so this is the value you key a per-peer map on. Use the value from AddrPort as the key, since a *UDPAddr is a pointer and compares by identity.

a, _ := net.ResolveUDPAddr("udp", "239.0.0.1:9999")

fmt.Println(a.IP, a.Port)  // 239.0.0.1 9999
fmt.Println(a.AddrPort())  // [::ffff:239.0.0.1]:9999

Satisfies net.Addr

A path rather than a host and port, so String gives you the filename back. Network distinguishes the stream, datagram, and seqpacket flavours.

a, _ := net.ResolveUnixAddr("unix", "/tmp/app.sock")

fmt.Println(a.Network(), a.String()) // unix /tmp/app.sock

Satisfies net.Addr

An address with no port on it, which is what a bare hostname resolves to. The Zone field carries the interface an IPv6 link-local address is scoped to.

a, err := net.ResolveIPAddr("ip", "localhost")
if err != nil {
    return
}

fmt.Println(a.Network(), a.IP) // ip 127.0.0.1

Satisfies fmt.Stringer

Six bytes for Ethernet, and a slice rather than an array so the longer formats fit too. Printing it gives the colon-separated hex back.

hw, err := net.ParseMAC("00:1b:44:11:3a:b7")
if err != nil {
    log.Fatal(err)
}

fmt.Println(hw, len(hw)) // 00:1b:44:11:3a:b7 6

Declare one and keep it. DialContext is the reason: a handler's context is already cancelled when the client gives up, so the dial stops instead of running on for a request nobody is waiting for.

d := net.Dialer{
    Timeout:   5 * time.Second,
    KeepAlive: 30 * time.Second,
}

c, err := d.DialContext(ctx, "tcp", "example.com:80")
if err != nil {
    return err
}
defer c.Close()

The listening half of Dialer. Control runs on the raw descriptor before the bind, which is the only place to set a socket option like SO_REUSEPORT.

lc := net.ListenConfig{KeepAlive: 30 * time.Second}

ln, err := lc.Listen(ctx, "tcp", ":0")
if err != nil {
    return err
}
defer ln.Close()

fmt.Println("listening on", ln.Addr())

Every method takes a context, which the package-level Lookup functions cannot. PreferGo forces Go's own DNS client instead of the system resolver, so the behaviour is the same everywhere.

r := &net.Resolver{PreferGo: true}

ips, err := r.LookupIP(ctx, "ip4", "go.dev")
if err != nil {
    return err
}
fmt.Println(ips)

Finding the machine's own routable address means filtering: skip the ones that are down and skip loopback. Flags is a bitmask, so the test is an & rather than an equality check.

ifis, err := net.Interfaces()
if err != nil {
    log.Fatal(err)
}

for _, ifi := range ifis {
    if ifi.Flags&net.FlagUp == 0 || ifi.Flags&net.FlagLoopback != 0 {
        continue
    }
    addrs, _ := ifi.Addrs()
    fmt.Println(ifi.Name, ifi.MTU, ifi.HardwareAddr, addrs)
}

Satisfies error, net.Error

Almost every error from this package is one of these. errors.As gets you the operation and the address that failed, and errors.Is reaches through Unwrap to the syscall underneath.

_, err := net.Dial("tcp", "127.0.0.1:1")

var oe *net.OpError
if errors.As(err, &oe) {
    fmt.Println(oe.Op, oe.Net, oe.Addr) // dial tcp 127.0.0.1:1
}

if errors.Is(err, syscall.ECONNREFUSED) {
    fmt.Println("nothing listening")
}

Satisfies error, net.Error

IsNotFound is the field that decides what to do next. A name that does not exist will not exist on the retry either; a resolver you could not reach might answer next time.

_, err := net.LookupHost("nonexistent.invalid.")

var de *net.DNSError
if errors.As(err, &de) {
    if de.IsNotFound {
        fmt.Println("no such host:", de.Name)
        return
    }
    fmt.Println("lookup failed, retry:", de.Err)
}

Satisfies error, net.Error

What you get for malformed input rather than a failed connection. The message names the problem and the string that caused it.

_, _, err := net.SplitHostPort("localhost")

var ae *net.AddrError
if errors.As(err, &ae) {
    fmt.Println(ae.Err, ae.Addr) // missing port in address localhost
}