Why can an io.Reader's Read return n > 0 bytes and io.EOF in the same call?

## What the contract actually promises The documented behaviour of `Read(p []byte) (n int, err error)` is deliberately loose in one specific way. When a reader hits an error or the end of its input *after* successfully filling `n > 0` bytes, it is allowed to do either of two things: 1. return `(n, io.EOF)` — the data and the ending in the same call; or 2. return `(n, nil)` now and report `(0, io.EOF)` on the following call. Both are conforming. The contract also tells callers what to do about it in one line: *process the n > 0 bytes returned before considering the error*. Everything else in this topic follows from that sentence. ## Why the loose contract exists Go's readers are thin wrappers over whatever is underneath — a file descriptor, a socket, a decompressor, a byte slice in memory. Some of those learn that the source is exhausted as part of the very syscall that returned the last bytes; forcing them to hide that knowledge and return it on a later call would mean an extra bookkeeping state in every implementation, and often an extra syscall. Allowing the combined form keeps implementations cheap. The cost is pushed onto callers, and it is a small cost — provided callers obey the ordering rule. ## The bug this produces ``` // WRONG: drops the final chunk for { n, err := r.Read(buf) if err != nil { break } consume(buf[:n]) } ``` Against `os.File`, which normally reports the end on a separate call, this loop looks perfect and passes every test. Point it at a reader that combines the two — many network and decompression wrappers do — and the last few kilobytes vanish, with no error anywhere. The symptom is a file that is *almost* right: a truncated last record, a JSON document missing its closing brace, a checksum that does not match. The correct shape puts the data first: ``` for { n, err := r.Read(buf) if n > 0 { consume(buf[:n]) } if err == io.EOF { return nil } if err != nil { return err } } ``` Note that the rule is not special to `io.EOF`. If a reader returns `(n, someRealError)`, those `n` bytes are still real data that the source produced; whether you keep them is your decision, but the loop must at least be aware of them. ## The other end of the range The contract also says something about the empty case: a return of `(0, nil)` is *not* a report that the stream ended. It means nothing happened, and a caller should treat it as a no-op and read again. Implementations are discouraged from producing it, except when `len(p) == 0`. So `(0, nil)` never means "done", and only `io.EOF` does. ## Why you rarely see this yourself Most application code does not write raw read loops. `io.Copy`, `io.ReadAll`, `bufio.Reader` and `bufio.Scanner` already implement the rule correctly, which is a strong argument for using them instead of hand-rolling. The moment you *do* hand-roll — a framing layer, a chunked protocol, a progress-reporting wrapper — the rule becomes yours to honour. ## Testing for it The standard library ships adversarial readers precisely for this, in `testing/iotest`: - `iotest.DataErrReader(r)` wraps a reader so the final error arrives *with* the final data rather than on a separate call — exactly the shape that breaks the wrong loop. - `iotest.OneByteReader(r)` returns one byte per call, exposing loops that assume the buffer is filled. - `iotest.HalfReader(r)` returns half of the requested bytes per call. - `iotest.ErrReader(err)` returns `(0, err)` immediately, for the failure path. Running the same read loop over the same input through each of these, and asserting the same output every time, is what actually pins the behaviour down. A single test against a `strings.Reader` proves very little. ## The one-line summary to say out loud The byte count and the error are independent return values, not alternatives. Read the count first; interpret the error second.