Datagrams and Unix Sockets

## Two shapes of socket, two constructors Go's `net` package splits socket creation along the connection-oriented / connectionless line, and the split shows up in which constructor you call and which interface you get back. - **Connection-oriented** (`"tcp"`, `"unix"`, `"unixpacket"`): `net.Listen` returns a `net.Listener`, and each peer becomes its own `net.Conn` with `Read`/`Write`. - **Connectionless** (`"udp"`, `"unixgram"`): `net.ListenPacket` returns a `net.PacketConn`. There is no listener, no handshake, and no per-peer object. One socket is the whole server. ```go pc, err := net.ListenPacket("udp", ":8125") ``` The returned value satisfies: ```go type PacketConn interface { ReadFrom(p []byte) (n int, addr Addr, err error) WriteTo(p []byte, addr Addr) (n int, err error) Close() error LocalAddr() Addr // plus deadline methods } ``` ## What ReadFrom actually does `ReadFrom` copies **one datagram** out of the socket's receive queue into your slice and returns how many bytes it copied together with the sender's address. That is the whole difference from a stream read, and almost every UDP bug in a Go service traces back to forgetting it: - **One call, one message.** If three datagrams are queued, three `ReadFrom` calls return them one at a time. They are never concatenated, and Go never merges or splits them. - **The message is complete or it is cut.** A stream read returning fewer bytes than you asked for means "more later". A datagram read returning fewer bytes than the datagram contained means the rest was thrown away by the kernel — there is no "later" for that message. - **The sender comes with the message.** Because the socket is not connected to anybody, the only way to know who to answer is the `addr` the read returns. You keep it if you need to reply. - **The address type is an interface.** `addr` is a `net.Addr`; for a UDP socket the dynamic type is `*net.UDPAddr`, for a `unixgram` socket `*net.UnixAddr`. You can pass it straight back to `WriteTo` without ever type-asserting it. ## A typical agent loop A statsd-style metrics agent is the canonical shape: a fire-and-forget protocol where each line is one datagram, senders never wait for a reply, and losing a message costs a data point rather than correctness. ```go buf := make([]byte, 1500) for { n, addr, err := pc.ReadFrom(buf) if err != nil { return err } handleMetric(buf[:n], addr) } ``` One buffer is reused for every read, because the read loop owns it. If you hand `buf[:n]` to another goroutine you must copy it first — the next `ReadFrom` overwrites the same array. ## Replying, and connected UDP sockets To answer a peer: ```go _, err := pc.WriteTo(reply, addr) ``` The same socket, the same port, addressed per message. If instead your program talks to exactly one remote — a client, not a server — you can *connect* a UDP socket with `net.Dial("udp", host)`. That returns an ordinary `net.Conn`: `Read` and `Write` work with no address argument because the kernel filters to that peer, and on Linux an ICMP port-unreachable from that peer surfaces as a `connection refused` error on a later read or write, which an unconnected socket never sees. ## When to reach for the concrete type `net.ListenUDP("udp", &net.UDPAddr{Port: 8125})` returns `*net.UDPConn` instead of the interface. You want it when you need something the interface does not expose: `ReadFromUDP` (which hands you `*net.UDPAddr` directly), `ReadMsgUDP` (out-of-band data and kernel flags), or `SetReadBuffer` (asking the kernel for a bigger receive queue). Accepting `net.PacketConn` in your own function signatures is still the better habit — it keeps the code testable and works unchanged for `"unixgram"`. ## What you give up Nothing in this API retransmits, orders, deduplicates or acknowledges. A datagram protocol is a design choice you make because loss is cheaper than latency — metrics, logs, discovery beacons, telemetry. If losing a message is not acceptable, either put the reliability in your own protocol or use a stream.