diff --git a/clients/go/README.md b/clients/go/README.md index 01f45a1d..cb291de7 100644 --- a/clients/go/README.md +++ b/clients/go/README.md @@ -92,7 +92,11 @@ returned subscription owns cancellation and exposes `Close` for deterministic goroutine cleanup. Raw protobuf messages remain available through the `mxgateway` package aliases and the `Raw` helper methods. Typed errors support `errors.As` for `GatewayError`, `CommandError`, and `MxAccessError`; command -errors preserve the raw reply. +errors preserve the raw reply. Authentication failures are distinguishable with +`errors.Is(err, mxgateway.ErrUnauthenticated)` (missing/rejected API key) and +`errors.Is(err, mxgateway.ErrPermissionDenied)` (valid key, not authorised); +both match a `*GatewayError` by its gRPC status code and leave the message +(and its credential redaction) unchanged. `EnsureMxAccessSuccess` follows COM semantics: only a **negative** HRESULT is a failure, so positive success codes such as `S_FALSE` (1) pass. `StatusSucceeded` diff --git a/clients/go/mxgateway/errors.go b/clients/go/mxgateway/errors.go index 318cd5d0..28d29ea6 100644 --- a/clients/go/mxgateway/errors.go +++ b/clients/go/mxgateway/errors.go @@ -6,6 +6,8 @@ import ( "strings" pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated" + "google.golang.org/grpc/codes" + "google.golang.org/grpc/status" "google.golang.org/protobuf/proto" ) @@ -199,6 +201,32 @@ func (e *GatewayError) Error() string { return fmt.Sprintf("mxgateway: %s failed: %v", e.Op, e.Err) } +// ErrUnauthenticated is matched (via errors.Is) by any GatewayError whose gRPC +// status code is Unauthenticated: the API key was missing, malformed or +// rejected. Fix the credential rather than retrying. +var ErrUnauthenticated = errors.New("mxgateway: unauthenticated") + +// ErrPermissionDenied is matched (via errors.Is) by any GatewayError whose gRPC +// status code is PermissionDenied: the API key is valid but not authorised for +// the operation. This is distinct from ErrUnauthenticated. +var ErrPermissionDenied = errors.New("mxgateway: permission denied") + +// Is lets errors.Is(err, ErrUnauthenticated) and errors.Is(err, +// ErrPermissionDenied) classify a transport failure by its gRPC status code. +// It adds no text to the error message, so credential redaction is unaffected. +func (e *GatewayError) Is(target error) bool { + if e == nil || e.Err == nil { + return false + } + switch target { + case ErrUnauthenticated: + return status.Code(e.Err) == codes.Unauthenticated + case ErrPermissionDenied: + return status.Code(e.Err) == codes.PermissionDenied + } + return false +} + // Unwrap returns the wrapped transport error. func (e *GatewayError) Unwrap() error { if e == nil { diff --git a/clients/go/mxgateway/errors_auth_test.go b/clients/go/mxgateway/errors_auth_test.go new file mode 100644 index 00000000..068ab74b --- /dev/null +++ b/clients/go/mxgateway/errors_auth_test.go @@ -0,0 +1,33 @@ +package mxgateway + +import ( + "errors" + "testing" + + "google.golang.org/grpc/codes" + "google.golang.org/grpc/status" +) + +func TestGatewayErrorClassifiesAuthCodes(t *testing.T) { + unauth := &GatewayError{Op: "invoke", Err: status.Error(codes.Unauthenticated, "bad key")} + denied := &GatewayError{Op: "invoke", Err: status.Error(codes.PermissionDenied, "no")} + other := &GatewayError{Op: "invoke", Err: status.Error(codes.Unavailable, "down")} + + if !errors.Is(unauth, ErrUnauthenticated) || errors.Is(unauth, ErrPermissionDenied) { + t.Fatal("Unauthenticated misclassified") + } + if !errors.Is(denied, ErrPermissionDenied) || errors.Is(denied, ErrUnauthenticated) { + t.Fatal("PermissionDenied misclassified") + } + if errors.Is(other, ErrUnauthenticated) || errors.Is(other, ErrPermissionDenied) { + t.Fatal("Unavailable must match neither") + } + var ge *GatewayError + if !errors.As(error(unauth), &ge) { + t.Fatal("errors.As to *GatewayError must still work") + } + wrapped := redactSecrets(unauth, "x") + if !errors.Is(wrapped, ErrUnauthenticated) { + t.Fatal("classification must survive the redaction wrapper") + } +}