context: DeadlineExceeded silently implements net.Error

[AlekSi]

// DeadlineExceeded is the error returned by Context.Err when the context's
// deadline passes.
var DeadlineExceeded error = deadlineExceededError{}

type deadlineExceededError struct{}

func (deadlineExceededError) Error() string   { return "context deadline exceeded" }
func (deadlineExceededError) Timeout() bool   { return true }
func (deadlineExceededError) Temporary() bool { return true }

The fact that context.DeadlineExceeded implements net.Error with both Timeout() and Temporary() returning true is not visible in the public documentation.

I guess it is way too late to remove those methods, so I propose to mention that fact in the documentation.

[AlekSi]

@gopherbot documentation

[AlekSi]

/cc @neild who recently filled a somewhat related proposal

[seankhliao]

the implementation is intentional #14238

[ianlancetaylor]

I guess I don't see why it's interesting to specifically document this fact. How does that help people?

[jsha]

It's interesting to me to document that DeadlineExceeded implements net.Error and returns true for Temporary(). Here's why: I had some code that errored out with a "context deadline exceeded" error. I'm planning to add retries to avoid that problem. The most generic way to add those retries is to check for err.Temporary() (with appropriate errors.As(..) casts).

I went looking for documentation on whether DeadlineExceeded is a Temporary error (I could see arguments either way), and wound up here. It would be great to have this in the official documentation rather than a GitHub issue.

Edit: I see now that Temporary is deprecated as of Go 1.18, in favor of Timeout. I believe the same arguments above apply to Timeout.

[neild]

net.Error.Temporary is meaningless. As you note, it's been deprecated.

It seems obvious to me that DeadlineExceeded is a timeout. I'd be very surprised if DeadlineExceeded implemented net.Error but returned false for Timeout.

So the question is whether context should document that the standard implementation of Context returns errors that implement net.Error. I suppose we could, but I suspect that doing so would cause more confusion than benefit: Now users will wonder if they should be type converting context errors to net.Error and checking the Timeout method, when the simple path is direct comparison to context.DeadlineExceeded.

[jsha]

Direct comparison to context.DeadlineExceeded is only appropriate if all possible timeout errors return context.DeadlineExceeded or something that wraps it. For non-stdlib packages that can definitely be a grab bag. Is it true of stdlib packages? For instance, if a net/http request errors out due to a ReadTimeout or a WriteTimeout, is that a context.DeadlineExceeded?

[DSpeichert]

For instance, if a net/http request errors out due to a ReadTimeout or a WriteTimeout, is that a context.DeadlineExceeded?

It is not - probably historical reasons. There has been an attempt to change it.