Provide better errors caused by context cancellation

[radeksimko]

#91 was closed partially because we were worried about implications in terms of backwards incompatibility.

I do however believe that the library should provide decent error messages - i.e. not context deadline exceeded by default, so I'm hoping this can be revisited before v1 as that gives us chance to make some breaking changes.

[paultyng]

#94 would probably solve this I think?

[radeksimko]

AFAICT that would still require the caller to add errors.Is/errors.As on their end, which seems appropriate for handling some command-specific errors, but not so much for handling every error?

[paultyng]

That is in fact what Go encourages so that people don't rely on direct casting but use those functions always:

var ErrPermission = errors.New("permission denied")

// DoSomething returns an error wrapping ErrPermission if the user
// does not have permission to do something.
func DoSomething() error {
    if !userHasPermission() {
        // If we return ErrPermission directly, callers might come
        // to depend on the exact error value, writing code like this:
        //
        //     if err := pkg.DoSomething(); err == pkg.ErrPermission { … }
        //
        // This will cause problems if we want to add additional
        // context to the error in the future. To avoid this, we
        // return an error wrapping the sentinel so that users must
        // always unwrap it:
        //
        //     if err := pkg.DoSomething(); errors.Is(err, pkg.ErrPermission) { ... }
        return fmt.Errorf("%w", ErrPermission)
    }
    // ...
}