Map any errx error to a canonical gRPC status.Status with typed google.rpc error details — ErrorInfo (the stable (reason, domain) identity), RetryInfo, LocalizedMessage, and Help. The end-user-safe message becomes the status message; unredacted fields never cross the wire.
gRPC's rich error model (google.rpc.Status + errdetails) is the industry standard for machine-readable RPC errors, but wiring it by hand per handler is tedious and inconsistent. contrib/grpc derives the whole thing from your errx identity in one call, so clients get a stable (reason, domain), retry timing, and a localized message automatically.
go get github.com/ubgo/errx/contrib/grpcPulls google.golang.org/grpc and google.golang.org/genproto/googleapis/rpc.
-
Return errx errors from your service methods:
func (s *server) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.User, error) { u, err := s.store.User(ctx, req.Id) if err != nil { return nil, errxgrpc.Err(ctx, errx.Wrap(err, "users: lookup"). WithDomain("users"). WithCode("NOT_FOUND"). // → codes.NotFound WithPublic("User not found"). // → status message + LocalizedMessage WithSafe("user_id", req.Id)) // → ErrorInfo.metadata } return u, nil }
errxgrpc.Err(ctx, err)returns a readyerror(niliferrisnil) — return it directly. -
Client side — read the typed details back:
st := status.Convert(err) for _, d := range st.Details() { switch info := d.(type) { case *errdetails.ErrorInfo: log.Printf("reason=%s domain=%s", info.Reason, info.Domain) case *errdetails.RetryInfo: time.Sleep(info.RetryDelay.AsDuration()) } }
e := errx.New("pq: deadlock on user_orders").
WithDomain("billing").
WithCode("TX_FAIL").
WithPublic("Please retry").
WithHint("use exponential backoff").
WithRetryable(2 * time.Second).
WithLocalized("fr-FR", "Veuillez réessayer").
With("internal_sql", "…"). // unsafe → dropped
WithSafe("order_id", "o-9") // safe → ErrorInfo.metadata
st := errxgrpc.Status(context.Background(), e)
// st.Code() == codes.Unavailable (retryable expected error)
// st.Message() == "Please retry"
// st.Details() contains ErrorInfo{Reason:"TX_FAIL", Domain:"billing",
// Metadata:{"order_id":"o-9"}}, RetryInfo{2s},
// LocalizedMessage{"fr-FR","Veuillez réessayer"}, Help{…hint…}
return st.Err()errxgrpc.CodeFor(err) resolves the canonical codes.Code: explicit code mapping first, else by class (ClassDefect → Internal, ClassCancelled → Canceled, retryable expected → Unavailable, other expected → InvalidArgument).
| errx code | gRPC code |
|---|---|
NOT_FOUND |
NotFound |
ALREADY_EXISTS |
AlreadyExists |
CONFLICT |
Aborted |
VALIDATION, INVALID_ARGUMENT |
InvalidArgument |
UNAUTHENTICATED |
Unauthenticated |
PERMISSION_DENIED, FORBIDDEN |
PermissionDenied |
RESOURCE_EXHAUSTED |
ResourceExhausted |
FAILED_PRECONDITION |
FailedPrecondition |
UNAVAILABLE |
Unavailable |
UNIMPLEMENTED |
Unimplemented |
TIMEOUT |
DeadlineExceeded |
| Detail | From |
|---|---|
ErrorInfo{Reason, Domain, Metadata} |
code, domain, and safe fields |
RetryInfo{RetryDelay} |
WithRetryable(d) |
LocalizedMessage{Locale, Message} |
each WithLocalized entry, else the public message as en-US |
Help{Links:[{Description, Url}]} |
WithHint / Remediation + WithURL / error-doc registry |
| Symbol | Purpose |
|---|---|
errxgrpc.Status(ctx, err) *status.Status |
Build the full status + details. |
errxgrpc.Err(ctx, err) error |
Status(...).Err(); nil if err is nil. Return from handlers. |
errxgrpc.CodeFor(err) codes.Code |
Resolve just the gRPC code. |
Only WithSafe fields appear in ErrorInfo.Metadata. Unsafe fields are dropped by errx.Snapshot before this module runs — sensitive data cannot reach the wire. The operator message is never sent; the public/localized message is.
See the root README for the full error model and docs/use-cases.md for end-to-end gRPC patterns.