From d2f1f6d70d9bf9dcaec7cea3bcb2c6dc65b931a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oscar=20S=C3=B6derlund?= Date: Mon, 30 Sep 2024 14:21:01 +0200 Subject: [PATCH] chore(clouderror): clarify GoDoc for error wrapping MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: John Blåberg Kristoffersson --- clouderror/wrap.go | 17 ++++++++++------- wrap.go | 8 ++++---- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/clouderror/wrap.go b/clouderror/wrap.go index d8b4aee4..4bf37f8e 100644 --- a/clouderror/wrap.go +++ b/clouderror/wrap.go @@ -13,25 +13,28 @@ import ( "google.golang.org/grpc/status" ) -// Wrap an error with a gRPC status. +// Wrap masks the gRPC status of the provided error by replacing it with the provided status. func Wrap(err error, s *status.Status) error { return &wrappedStatusError{status: s, err: err, caller: NewCaller(runtime.Caller(1))} } -// WrapCaller wraps an error with a gRPC status and a caller. +// WrapCaller masks the gRPC status of the provided error by replacing it with the provided status. +// The call site of the error is captured from the provided caller. func WrapCaller(err error, s *status.Status, caller Caller) error { return &wrappedStatusError{status: s, err: err, caller: caller} } -// WrapTransient wraps transient errors (possibly status.Status) with -// appropriate codes.Code. The returned error will always be a status.Status -// with description set to msg. +// WrapTransient masks the gRPC status of the provided error by replacing the status message. +// If the original error has transient (retryable) gRPC status code, the status code is forwarded. +// Otherwise, the status code is masked with INTERNAL. func WrapTransient(err error, msg string) error { return WrapTransientCaller(err, msg, NewCaller(runtime.Caller(1))) } -// WrapTransientCaller wraps transient errors with an appropriate codes.Code and caller. -// The returned error will always be a status.Status with description set to msg. +// WrapTransient masks the gRPC status of the provided error by replacing the status message. +// If the original error has transient (retryable) gRPC status code, the status code is forwarded. +// Otherwise, the status code is masked with INTERNAL. +// The call site of the error is captured from the provided caller. func WrapTransientCaller(err error, msg string, caller Caller) error { if s, ok := status.FromError(err); ok { switch s.Code() { diff --git a/wrap.go b/wrap.go index cda5cc6d..c2ebe869 100644 --- a/wrap.go +++ b/wrap.go @@ -7,14 +7,14 @@ import ( "google.golang.org/grpc/status" ) -// Wrap an error with a gRPC status. +// Wrap masks the gRPC status of the provided error by replacing it with the provided status. func Wrap(err error, s *status.Status) error { return clouderror.WrapCaller(err, s, clouderror.NewCaller(runtime.Caller(1))) } -// WrapTransient wraps transient errors (possibly status.Status) with -// appropriate codes.Code. The returned error will always be a status.Status -// with description set to msg. +// WrapTransient masks the gRPC status of the provided error by replacing the status message. +// If the original error has transient (retryable) gRPC status code, the status code will be forwarded. +// Otherwise, the status code will be masked with INTERNAL. func WrapTransient(err error, msg string) error { return clouderror.WrapTransientCaller(err, msg, clouderror.NewCaller(runtime.Caller(1))) }