Deadlines and Half-Close

## The three methods Every `net.Conn` — TCP, Unix-domain, UDP `net.PacketConn` and the connections `crypto/tls` wraps — carries three deadline methods: ``` SetDeadline(t time.Time) error // both directions SetReadDeadline(t time.Time) error // reads only SetWriteDeadline(t time.Time) error // writes only ``` The argument is a **`time.Time`**, an absolute instant, not a `time.Duration`. This is the single most misread part of the API: engineers coming from socket libraries that take `SO_RCVTIMEO`-style durations expect "give me five seconds per read" and instead get "fail all reads after 15:04:05.999". ## What the deadline is attached to The deadline is state on the connection, not an argument to a call. Setting it affects **all pending and future I/O** in that direction — including a `Read` that another goroutine is already blocked in — and it stays set until you change it. Nothing resets it when a read completes successfully. So the lifecycle of a deadline is entirely in your hands: * **future instant** — reads block normally until data arrives or that instant is reached, whichever comes first; * **instant already passed** — reads return an error immediately without touching the network; * **zero value (`time.Time{}`)** — no deadline; reads block indefinitely. After a deadline has been exceeded the connection is not closed or poisoned: setting a new deadline in the future makes it usable again. ## Why the loop must refresh it Consider a client for a long-lived framed protocol that sets one deadline after dialing and then loops reading frames. For the first `d` of the connection's life everything works. The instant the clock passes the deadline, every subsequent read returns a timeout error with no delay — the client spins through an error loop at full CPU, and the failure looks nothing like a network problem because it is not one. The mirror image is a connection with no deadline at all, which blocks forever the moment the peer stops sending. The correct shape is to set the deadline once per logical read unit: ``` func readFrame(c net.Conn) ([]byte, error) { if err := c.SetReadDeadline(time.Now().Add(5 * time.Second)); err != nil { return nil, err } var n uint32 if err := binary.Read(c, binary.BigEndian, &n); err != nil { return nil, err } buf := make([]byte, n) _, err := io.ReadFull(c, buf) return buf, err } ``` Notice that one deadline spans **two** read operations here — the length header and the body — and possibly many more syscalls underneath, because `io.ReadFull` loops. That is usually what you want: the budget belongs to "receive one frame", not to "one call into the kernel". If you wanted a separate budget for the body you would set the deadline again after reading the header. ## Recognising the error A read that hits its deadline returns an error that satisfies the `net.Error` interface with `Timeout()` reporting true, and that matches `errors.Is(err, os.ErrDeadlineExceeded)`. Both are worth knowing: the interface assertion is the old idiom, the sentinel comparison is the modern one and works through wrapping. ## Resumability after a timeout The connection survives a deadline, but your **protocol state** may not. If the timeout fired after `io.ReadFull` had already consumed nine of a frame's twelve bytes, those bytes are gone and the stream is now misaligned — the next read would interpret body bytes as a length header. For any framed protocol, treat a timeout that fires mid-frame as fatal for that connection and reconnect. Only a read that consumed nothing (a timeout while idle, waiting for the next frame to begin) is safe to retry on the same connection. ## Choosing the value The deadline should come from the protocol, not from a general intuition about "slow networks". For a request/response exchange it is the worst acceptable server latency. For a long-lived stream that is idle most of the time, a five-second read deadline would fire constantly; the right value is derived from the heartbeat interval — typically enough time for two missed heartbeats — so an idle connection is still proven alive without being torn down. ## Writes deserve the same treatment `SetWriteDeadline` matters less often, because a write into an open TCP send window returns quickly, but it is not optional. When the peer stops reading, the window fills and `Write` blocks exactly as `Read` does. A wire layer that bounds only reads still has a way to hang.