What does gzip.Reader.Multistream(false) change when reading a file of concatenated gzip members?

## Concatenation is part of the format RFC 1952 permits a gzip file to consist of a sequence of complete members, each with its own header, DEFLATE body and trailer. Decompressing the file means decompressing each member and concatenating the results. This is why appending to a `.gz` archive works at all: a log rotator can compress each rotation separately and append the bytes, and every standard tool reads the result as one logical file. Go implements that default faithfully. `gzip.NewReader` gives you a reader that walks from one member into the next without telling you, and returns `io.EOF` only when the last member ends. ## What the flag changes `(*gzip.Reader).Multistream(ok bool)` selects between the two behaviours. With `false`, `Read` returns `io.EOF` at the end of the *current* member. The reader is now a per-member reader, and the file becomes a sequence you iterate. You advance with `Reset(r)`, which re-initialises the reader over the same underlying source. It returns `io.EOF` when there is no further member, which is the loop's exit condition, and any other error means a malformed next header. Crucially, `Reset` restores the default multistream behaviour, so a loop must set the flag again on every iteration. ```go br := bufio.NewReader(f) // gzip.Reader needs an io.ByteReader here zr, err := gzip.NewReader(br) if err != nil { return err } defer zr.Close() for { zr.Multistream(false) name := zr.Header.Name if _, err := io.Copy(dst, zr); err != nil { // stops at this member's end return err } use(name) if err := zr.Reset(br); errors.Is(err, io.EOF) { return nil } else if err != nil { return err } } ``` ## The io.ByteReader requirement The documentation is explicit that in this mode the underlying reader must implement `io.ByteReader` for the position to be left just after the gzip stream. The reason is buffering: a decompressor reading in chunks would normally consume past the member's last byte, and then the caller could not pick up the next member — or the non-gzip bytes that follow — from the right offset. Byte-at-a-time access at the boundary makes the position exact. An `*os.File` does not implement `io.ByteReader`; `*bufio.Reader` and `*bytes.Reader` do. Wrapping in `bufio.NewReader` is the normal fix, and you must then pass that same `*bufio.Reader` to `Reset`, not the original file, or you will restart from a different position. ## When you actually need it - Each member is one rotation, and you want its `Header.Name` and `ModTime` to route or timestamp what is inside. Those fields belong to a member, so reading transparently across boundaries loses all of them but the first. - A container format embeds gzip members among other data — an index, a manifest, a length-prefixed frame — and the reader must stop exactly where the member does. - You are validating an archive member by member, so a corrupt member can be reported individually instead of failing the whole file. ## When you do not If all you want is the bytes, leave the default alone. Reading transparently is simpler, verifies every member's checksum on the way through, and needs no `io.ByteReader`. Reaching for `Multistream(false)` because the file 'has several parts' and then re-implementing what the default already does is a common over-engineering. ## The failure it prevents The operational version of this is a shipper that appends a member per rotation and a consumer that reads only `Header.Name` from the file it opened. With the default reader that name is the *first* member's, so every batch is attributed to the earliest rotation and the mislabelling only surfaces when someone at 3 a.m. is trying to work out which hour a line came from. Switching to per-member reading is what makes the metadata usable.