Btw, I can contribute the fix and possibly also the "merge" filesystem from the linked PR if desired. It merges any number and type of file systems into one overarching.

io.EOF is considered special and should not normally be wrapped. The documentation mentions only Read, but I believe it applies anywhere: https://pkg.go.dev/io#pkg-variables

Anyone know why io.EOF gets to be an exception to the advice in package errors about checking error identity?

wraps errors with a stacktrace

There is no reason to do this. Callers who want a stack trace when they receive an error can easily generate one themselves. Callers who don't want a stack trace should not be required to pay the costs of generating one.

related #39155

Anyone know why io.EOF gets to be an exception to the advice in package errors about checking error identity?

Because the io.Reader interface was well-defined and widely used (to put it mildly) by the time error wrapping was introduced.

Also, checks for io.EOF are likely to occur in a performance-critical hot path, which might have been sufficient reason to require an unwrapped sentinel anyway. Or possibly not; the existing definition of io.Reader made the question moot.

Because the io.Reader interface was well-defined and widely used (to put it mildly) by the time error wrapping was introduced.

Is io.Reader the only widely-used interface that specifies a sentinel error as part of its API? Even if so, that's orthogonal to the way its caller checks for error identity, isn't it? And, concretely, fstest.TestFS() was (presumably) written post-1.13, so why isn't it using errors.Is(err, io.EOF)?

An io.Reader is specified as returning io.EOF at end-of-file, not an error wrapping io.EOF. The fstest package is testing for a conformant io.Reader, so it checks for an io.EOF. It reporting an error in this circumstance is an example of it functioning as intended: It has correctly detected an incorrect implementation.

I'm not certain if there are other interfaces in the standard library specified as returning a sentinel error. If there are, the rationale for Read returning an unwrapped io.EOF would apply to them as well.

As @seankhliao pointed out, there is more discussion of io.EOF and error wrapping in #39155.

An io.Reader is specified as returning io.EOF at end-of-file, not an error wrapping io.EOF.

The linked discussion was informative, thank you.

I parse

EOF is the error returned by Read

as entirely compatible with wrapping + errors.Is; if that's not the intent, it should probably be made more explicit? And it's not just the Read method of an io.Reader that's bound by this constraint, but apparently the ReadDir method of a fs.ReadDirFile, too. Others?

OK, the discussion around EOF is interesting. Thanks for the explanation around that. My key takeaway is:

EOF is not an error, it is expected behavior

which in turn leaves me wonder why it is of type error in the first place, but that was a bad design decision made way back I assume.

There is no reason to do this. Callers who want a stack trace when they receive an error can easily generate one themselves. Callers who don't want a stack trace should not be required to pay the costs of generating one.

I am not sure I understand that. When I get the error at a point where I want to print/debug/... it, I don't have the program counter of where the error originated from? How can I generate a stack trace at that point? Can you maybe please give me some pointers on how that would be done? I would like to see the same output as if the code would have panicked instead of returning an error. The only way I know of how of how that is achievable is using runtime.Callers(), but that has to be called where the error originally was generated. Or can the same be achieved with tracing enabled somehow?

Based on the conversation, it doesn't look like we're going to be able to make this change because of io.Reader's contract. There's too much code out there that relies on == io.EOF, so I'm inclined to close this issue. @zepatrik Please comment if you feel it should be reopened.

The specific case in fstest is actually not io.Reader, but fs.ReadDirFile. The io package documentation is fairly clear that Read must return an io.EOF without wrapping ("Read must return EOF itself, not an error wrapping EOF..."), but the fs package doesn't mention wrapping.

The requirements for fs.ReadDirFile could probably stand to be documented more clearly.

@neild Filed #47086 to track that.

Change https://golang.org/cl/333149 mentions this issue: io/fs: document requirement that ReadDir return an unwrapped io.EOF