Merge pull request #54 from knz/20201028-oserror

New sub-package `oserror`.

Author: knz

README.md

@@ -47,6 +47,7 @@ Table of contents:
 | wrappers to attach [`logtags`](https://github.com/cockroachdb/logtags) details from `context.Context` |                     |                         |                            | ✔                    |
 | `errors.FormatError()`, `Formatter`, `Printer`                                                        |                     |                         | (under construction)       | ✔                    |
 | `errors.SafeFormatError()`, `SafeFormatter`                                                           |                     |                         |                            | ✔                    |
+| wrapper-aware `IsPermission()`, `IsTimeout()`, `IsExist()`, `IsNotExist()`                            |                     |                         |                            | ✔                    |
 
 "Forward compatibility" above refers to the ability of this library to
 recognize and properly handle network communication of error types it
@@ -61,6 +62,8 @@ older version of the package.
 - test error identity with `errors.Is()` as usual.
   **Unique in this library**: this works even if the error has traversed the network!
   Also, `errors.IsAny()` to recognize two or more reference errors.
+- replace uses of `os.IsPermission()`, `os.IsTimeout()`, `os.IsExist()` and `os.IsNotExist()` by their analog in sub-package `oserror` so
+  that they can peek through layers of wrapping.
 - access error causes with `errors.UnwrapOnce()` / `errors.UnwrapAll()` (note: `errors.Cause()` and `errors.Unwrap()` also provided for compatibility with other error packages).
 - encode/decode errors to protobuf with `errors.EncodeError()` / `errors.DecodeError()`.
 - extract **PII-free safe details** with `errors.GetSafeDetails()`.

errbase/adapters.go

@@ -18,7 +18,9 @@ import (
 	"context"
 	goErr "errors"
 	"fmt"
+	"os"
 
+	"github.com/cockroachdb/errors/errorspb"
 	"github.com/gogo/protobuf/proto"
 	pkgErr "github.com/pkg/errors"
 )
@@ -75,6 +77,108 @@ func encodePkgWithStack(
 	return "" /* withStack does not have a message prefix */, safeDetails, nil
 }
 
+func encodePathError(
+	_ context.Context, err error,
+) (msgPrefix string, safe []string, details proto.Message) {
+	p := err.(*os.PathError)
+	msg := p.Op + " " + p.Path
+	details = &errorspb.StringsPayload{
+		Details: []string{p.Op, p.Path},
+	}
+	return msg, []string{p.Op}, details
+}
+
+func decodePathError(
+	_ context.Context, cause error, _ string, _ []string, payload proto.Message,
+) (result error) {
+	m, ok := payload.(*errorspb.StringsPayload)
+	if !ok || len(m.Details) < 2 {
+		// If this ever happens, this means some version of the library
+		// (presumably future) changed the payload type, and we're
+		// receiving this here. In this case, give up and let
+		// DecodeError use the opaque type.
+		return nil
+	}
+	return &os.PathError{
+		Op:   m.Details[0],
+		Path: m.Details[1],
+		Err:  cause,
+	}
+}
+
+func encodeLinkError(
+	_ context.Context, err error,
+) (msgPrefix string, safe []string, details proto.Message) {
+	p := err.(*os.LinkError)
+	msg := p.Op + " " + p.Old + " " + p.New
+	details = &errorspb.StringsPayload{
+		Details: []string{p.Op, p.Old, p.New},
+	}
+	return msg, []string{p.Op}, details
+}
+
+func decodeLinkError(
+	_ context.Context, cause error, _ string, _ []string, payload proto.Message,
+) (result error) {
+	m, ok := payload.(*errorspb.StringsPayload)
+	if !ok || len(m.Details) < 3 {
+		// If this ever happens, this means some version of the library
+		// (presumably future) changed the payload type, and we're
+		// receiving this here. In this case, give up and let
+		// DecodeError use the opaque type.
+		return nil
+	}
+	return &os.LinkError{
+		Op:  m.Details[0],
+		Old: m.Details[1],
+		New: m.Details[2],
+		Err: cause,
+	}
+}
+
+func encodeSyscallError(
+	_ context.Context, err error,
+) (msgPrefix string, safe []string, details proto.Message) {
+	p := err.(*os.SyscallError)
+	return p.Syscall, nil, nil
+}
+
+func decodeSyscallError(
+	_ context.Context, cause error, msg string, _ []string, _ proto.Message,
+) (result error) {
+	return os.NewSyscallError(msg, cause)
+}
+
+// OpaqueErrno represents a syscall.Errno error object that
+// was constructed on a different OS/platform combination.
+type OpaqueErrno struct {
+	msg     string
+	details *errorspb.ErrnoPayload
+}
+
+// Error implements the error interface.
+func (o *OpaqueErrno) Error() string { return o.msg }
+
+// Is tests whether this opaque errno object represents a special os error type.
+func (o *OpaqueErrno) Is(target error) bool {
+	return (target == os.ErrPermission && o.details.IsPermission) ||
+		(target == os.ErrExist && o.details.IsExist) ||
+		(target == os.ErrNotExist && o.details.IsNotExist)
+}
+
+// Temporary tests whether this opaque errno object encodes a temporary error.
+func (o *OpaqueErrno) Temporary() bool { return o.details.IsTemporary }
+
+// Timeout tests whether this opaque errno object encodes a timeout error.
+func (o *OpaqueErrno) Timeout() bool { return o.details.IsTimeout }
+
+func encodeOpaqueErrno(
+	_ context.Context, err error,
+) (msg string, safe []string, payload proto.Message) {
+	e := err.(*OpaqueErrno)
+	return e.Error(), []string{e.Error()}, e.details
+}
+
 func init() {
 	baseErr := goErr.New("")
 	RegisterLeafDecoder(GetTypeKey(baseErr), decodeErrorString)
@@ -86,4 +190,16 @@ func init() {
 
 	ws := pkgErr.WithStack(baseErr)
 	RegisterWrapperEncoder(GetTypeKey(ws), encodePkgWithStack)
+
+	pKey := GetTypeKey(&os.PathError{})
+	RegisterWrapperEncoder(pKey, encodePathError)
+	RegisterWrapperDecoder(pKey, decodePathError)
+	pKey = GetTypeKey(&os.LinkError{})
+	RegisterWrapperEncoder(pKey, encodeLinkError)
+	RegisterWrapperDecoder(pKey, decodeLinkError)
+	pKey = GetTypeKey(&os.SyscallError{})
+	RegisterWrapperEncoder(pKey, encodeSyscallError)
+	RegisterWrapperDecoder(pKey, decodeSyscallError)
+
+	RegisterLeafEncoder(GetTypeKey(&OpaqueErrno{}), encodeOpaqueErrno)
 }

errbase/adapters_errno.go

@@ -0,0 +1,66 @@
+// Copyright 2019 The Cockroach Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+// implied. See the License for the specific language governing
+// permissions and limitations under the License.
+
+// +build !plan9
+
+package errbase
+
+import (
+	"context"
+	"os"
+	"runtime"
+	"syscall"
+
+	"github.com/cockroachdb/errors/errorspb"
+	"github.com/gogo/protobuf/proto"
+)
+
+const thisArch = runtime.GOOS + ":" + runtime.GOARCH
+
+func encodeErrno(_ context.Context, err error) (msg string, safe []string, payload proto.Message) {
+	e := err.(syscall.Errno)
+	payload = &errorspb.ErrnoPayload{
+		OrigErrno:    int64(e),
+		Arch:         thisArch,
+		IsPermission: e.Is(os.ErrPermission),
+		IsExist:      e.Is(os.ErrExist),
+		IsNotExist:   e.Is(os.ErrNotExist),
+		IsTimeout:    e.Timeout(),
+		IsTemporary:  e.Temporary(),
+	}
+	return e.Error(), []string{e.Error()}, payload
+}
+
+func decodeErrno(_ context.Context, msg string, _ []string, payload proto.Message) error {
+	m, ok := payload.(*errorspb.ErrnoPayload)
+	if !ok {
+		// If this ever happens, this means some version of the library
+		// (presumably future) changed the payload type, and we're
+		// receiving this here. In this case, give up and let
+		// DecodeError use the opaque type.
+		return nil
+	}
+	if m.Arch != thisArch {
+		// The errno object is coming from a different platform. We'll
+		// keep it opaque here.
+		return &OpaqueErrno{msg: msg, details: m}
+	}
+	return syscall.Errno(m.OrigErrno)
+}
+
+func init() {
+	pKey := GetTypeKey(syscall.Errno(0))
+	RegisterLeafEncoder(pKey, encodeErrno)
+	RegisterLeafDecoder(pKey, decodeErrno)
+}

errbase/adapters_errno_test.go

@@ -0,0 +1,74 @@
+// Copyright 2019 The Cockroach Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+// implied. See the License for the specific language governing
+// permissions and limitations under the License.
+
+// +build !plan9
+
+package errbase_test
+
+import (
+	"context"
+	"reflect"
+	"syscall"
+	"testing"
+
+	"github.com/cockroachdb/errors/errbase"
+	"github.com/cockroachdb/errors/errorspb"
+	"github.com/cockroachdb/errors/oserror"
+	"github.com/cockroachdb/errors/testutils"
+	"github.com/gogo/protobuf/types"
+)
+
+func TestAdaptErrno(t *testing.T) {
+	tt := testutils.T{T: t}
+
+	// Arbitrary values of errno on a given platform are preserved
+	// exactly when decoded on the same platform.
+	origErr := syscall.Errno(123)
+	newErr := network(t, origErr)
+	tt.Check(reflect.DeepEqual(newErr, origErr))
+
+	// Common values of errno preserve their properties
+	// across a network encode/decode even though they
+	// may not decode to the same type.
+	for i := 0; i < 2000; i++ {
+		origErr := syscall.Errno(i)
+		enc := errbase.EncodeError(context.Background(), origErr)
+
+		// Trick the decoder into thinking the error comes from a different platform.
+		details := &enc.Error.(*errorspb.EncodedError_Leaf).Leaf.Details
+		var d types.DynamicAny
+		if err := types.UnmarshalAny(details.FullDetails, &d); err != nil {
+			t.Fatal(err)
+		}
+		errnoDetails := d.Message.(*errorspb.ErrnoPayload)
+		errnoDetails.Arch = "OTHER"
+		any, err := types.MarshalAny(errnoDetails)
+		if err != nil {
+			t.Fatal(err)
+		}
+		details.FullDetails = any
+
+		// Now decode the error. This produces an OpaqueErrno payload.
+		dec := errbase.DecodeError(context.Background(), enc)
+		if _, ok := dec.(*errbase.OpaqueErrno); !ok {
+			t.Fatalf("expected OpaqueErrno, got %T", dec)
+		}
+
+		// Now check that the properties have been preserved properly.
+		tt.CheckEqual(oserror.IsPermission(origErr), oserror.IsPermission(dec))
+		tt.CheckEqual(oserror.IsExist(origErr), oserror.IsExist(dec))
+		tt.CheckEqual(oserror.IsNotExist(origErr), oserror.IsNotExist(dec))
+		tt.CheckEqual(oserror.IsTimeout(origErr), oserror.IsTimeout(dec))
+	}
+}

errbase/adapters_test.go

@@ -18,6 +18,7 @@ import (
 	"context"
 	goErr "errors"
 	"fmt"
+	"os"
 	"reflect"
 	"strings"
 	"testing"
@@ -170,3 +171,22 @@ func TestAdaptProtoErrorsWithWrapper(t *testing.T) {
 	// Moreover, it preserves the entire structure.
 	tt.CheckDeepEqual(newErr, origErr)
 }
+
+func TestAdaptOsErrors(t *testing.T) {
+	// The special os error types are preserved exactly.
+
+	tt := testutils.T{T: t}
+	var origErr error
+
+	origErr = &os.PathError{Op: "hello", Path: "world", Err: goErr.New("woo")}
+	newErr := network(t, origErr)
+	tt.Check(reflect.DeepEqual(newErr, origErr))
+
+	origErr = &os.LinkError{Op: "hello", Old: "world", New: "universe", Err: goErr.New("woo")}
+	newErr = network(t, origErr)
+	tt.Check(reflect.DeepEqual(newErr, origErr))
+
+	origErr = &os.SyscallError{Syscall: "hello", Err: goErr.New("woo")}
+	newErr = network(t, origErr)
+	tt.Check(reflect.DeepEqual(newErr, origErr))
+}