io.EOF and Stream Endings

## What io.EOF is `io.EOF` is one variable in the standard library's `io` package, declared as `var EOF = errors.New("EOF")`. Because `errors.New` returns a fresh pointer every time it is called, that single value is unique: code recognises the end of a stream by comparing against **that** value, not by looking at the message text. Values used this way are called *sentinel errors*. ## Why an ending is reported through the error slot The reading contract in Go is one method: ``` Read(p []byte) (n int, err error) ``` There are only two return slots — how many bytes landed in `p`, and an error. There is no third boolean saying "the stream is over", so the end has to be reported through the error slot. `io.EOF` is that report. It is a *status*, not a fault: the producer said everything it had to say and closed the conversation politely. This is why the Go standard library's documentation is careful to say that `io.EOF` "means no more input is available", and why library code that consumes a stream is expected to convert it into ordinary success. ## The caller's idiom A hand-written read loop distinguishes three outcomes on every iteration: bytes arrived, the stream ended, something broke. ``` buf := make([]byte, 32*1024) for { n, err := r.Read(buf) if n > 0 { consume(buf[:n]) } if err == io.EOF { return nil // finished, and that is success } if err != nil { return err // a real failure } } ``` The two `if`s must be in that order and must be separate. Collapsing them into a single `if err != nil { return err }` turns a normal finish into an error return; collapsing them the other way, `if err != nil { break }` followed by `return nil`, turns a disk or network failure into a silent success. ## Helpers that absorb it for you Most real code never writes that loop, because the standard library already contains it: - `io.ReadAll(r)` reads to the end and returns `(data, nil)`. A successful call returns a nil error, not `io.EOF`. - `io.Copy(dst, src)` returns `(written int64, err error)` and likewise reports `nil` at a clean end; it never returns `io.EOF`. - `bufio.Scanner` never exposes `io.EOF` at all: `Scan` returns `false` at the end, and `Err` reports the first *non-EOF* error, so it is `nil` when the input simply ran out. The one common helper that deliberately does the opposite is `io.CopyN(dst, src, n)`: it must copy exactly `n` bytes, so if the source ends first it returns `io.EOF` as a genuine complaint. `io.ReadFull` behaves the same way in spirit, returning `io.EOF` only when it read nothing and `io.ErrUnexpectedEOF` when it read some but not all of the buffer. The pattern behind all of this: a helper that has no expectation of length treats the end as success, and a helper that was told how many bytes it needs treats an early end as an error. ## == or errors.Is Historically the test is `err == io.EOF`, and the standard library's own stream plumbing still compares by identity. `errors.Is(err, io.EOF)` does the same job and additionally unwraps an error chain, so it is the safer choice when the error has crossed a package boundary that may have annotated it. Reading `err.Error() == "EOF"` is always wrong — the message is not the contract. ## What io.EOF does not tell you It says the byte stream stopped. It does **not** say the producer meant to stop. A file copied halfway, an upload cut off mid-flight and a complete file all end the same way at the byte layer. If your format needs to know the difference, the *format* has to carry it — a length prefix, a record terminator, a checksum, or a trailer — and the code then compares what it actually read against what was promised. Detecting truncation is a framing problem, not something `io.EOF` can answer. ## And the mirror rule Never return `io.EOF` to signal a real failure. If your reader dies mid-record, return the underlying error or `io.ErrUnexpectedEOF`; handing a caller `io.EOF` tells it everything is fine and it will stop cleanly on corrupt data.