grpc

func ClientSafeMessage ¶

func ClientSafeMessage(err error) (string, bool)

ClientSafeMessage reports the words a client may be told for err: the text of the first client-safe sentinel in its chain, and false when there is none.

"First" is a position in the chain, not in the lists. The chain is walked outermost-first — depth-first through a Join, in the order it was joined — and each node is compared against the client-safe sentinels, registered and platform alike; the first node that is one of them supplies the message. So a more specific wrapper outranks what it wraps: a domain sentinel declared as Wrap(platformerrors.ErrUnrecognizedInputValue, "...") and registered speaks with its own words, because the walk reaches it before it reaches the platform sentinel inside it. A bare platform sentinel, or a registered sentinel built with New, is unaffected — there is only one node to match.

The interceptors consult it through clientMessage, for an error a handler returned bare, and so does PrepareAndLogGRPCStatus for the description a handler passed it — which is how identity/grpc and authentication/signin/grpc get this behavior without asking for it, and why neither has to say the word.

It stays exported for the handler that builds its own status by hand, carrying a code the mappers would not pick or a message this package cannot guess. Such a handler still wants a registered sentinel's own words to win over its own description, since the sentinel is more specific and was registered precisely to be quoted. Without this it either re-implements the two lists or its clients read "FailedPrecondition" where a sentinel had something better to say.

func DecodeErrorFromStatus ¶

func DecodeErrorFromStatus(ctx context.Context, err error) error

DecodeErrorFromStatus extracts the EncodedError from gRPC status details (if present) and decodes it so errors.Is() works across the wire. Returns the decoded error, or the original status error if no encoded detail is found.

func MapToGRPC ¶

func MapToGRPC(err error, defaultCode codes.Code) codes.Code

MapToGRPC returns the appropriate gRPC code for known sentinel errors. It tries PlatformMapper first, then each registered domain mapper. Use std errors.Is for matching. Returns defaultCode if no match.

func PrepareAndLogGRPCStatus ¶

func PrepareAndLogGRPCStatus(err error, logger logging.Logger, span tracing.Span, defaultCode codes.Code, descriptionFmt string, descriptionArgs ...any) error

PrepareAndLogGRPCStatus derives the gRPC code via MapToGRPC, then logs, traces, and returns a status error. defaultCode is the fallback for an error no mapper claims.

This is the spelling a handler holding an observability.Operation wants: observability's function of the same name takes the code it is handed and cannot map, because this package imports it and the reverse edge is a cycle. Logger and Span are on Operation so that reaching this one costs nothing:

grpcerrors.PrepareAndLogGRPCStatus(err, op.Logger(), op.Span(), codes.Internal, "doing the thing")

What comes back is still the error that went in. The chain is intact under a status, not rendered into one, so UnaryErrorEncodingInterceptor has a chain to encode and a client's errors.Is matches the sentinel a handler returned. See observability.GRPCStatusError for what that costs and why the message is the description rather than the chain.

The code is a default in a second sense too: the interceptor re-runs MapToGRPC over the chain this preserves, so a mapper registered after a handler guessed still wins. The message follows ClientSafeMessage — a registered client-safe sentinel's own words outrank the description, since the sentinel is more specific and was registered precisely to be quoted.

func RegisterClientSafeSentinels ¶

func RegisterClientSafeSentinels(sentinels ...error)

RegisterClientSafeSentinels records errors whose own message the interceptors may put on the wire verbatim, rather than the generic string a gRPC code renders as.

It is the companion to RegisterGRPCErrorMapper and answers the other half of the same question: the mapper decides the status, this decides whether the status carries the sentinel's own words. Registering a mapper without these is the usual case — most sentinels describe the system rather than the caller — and a sentinel whose text names a table, a key, or a policy must not be registered here at all.

This module's own sets are links.ClientSafeSentinels and identity.ClientSafeSentinels, and errormappers.Register hands both over alongside the five mappers, so a consumer registering the domain tier gets both halves in one call.

It is additive and safe to call from more than one goroutine, and a sentinel registered twice costs a second comparison and nothing else.

func RegisterGRPCErrorMapper ¶

func RegisterGRPCErrorMapper(m GRPCErrorMapper)

RegisterGRPCErrorMapper registers a domain-specific error mapper, which MapToGRPC consults after PlatformMapper and in registration order.

A package that owns sentinels declares the mapper — dataprivacy.GRPCMapper and its three counterparts in this module are the pattern — and the composition root registers it. For this module's four that is one call, errormappers.Register, which service.Register makes for a service built from a service.Config and a service assembled by hand makes itself; this function is what a consumer calls for a mapper of its own. Doing it from an init function is a consumer's choice to make and not this module's, because a mapper that installs itself by being linked in is a side effect nothing downstream can opt out of.

func StreamErrorEncodingInterceptor ¶

func StreamErrorEncodingInterceptor() grpc.StreamServerInterceptor

StreamErrorEncodingInterceptor returns a stream interceptor that encodes handler errors into gRPC status details for wire transmission.

func UnaryErrorDecodingInterceptor ¶

func UnaryErrorDecodingInterceptor() grpc.UnaryClientInterceptor

UnaryErrorDecodingInterceptor is DecodeErrorFromStatus as a client interceptor, so a caller gets sentinels back without remembering to ask.

DecodeErrorFromStatus on its own is a function every call site has to wrap its result in, and the one that forgets gets a *status.Error that no errors.Is matches — which reads exactly like a server that failed to encode, and is why the encoding side has been an interceptor from the start and this side was not. The two are now symmetric: the server encodes on the way out, the client decodes on the way in, and the sentinel a store returned is the sentinel the caller compares against.

The error it returns answers to both idioms — see decodedError — because making the decode automatic would otherwise silently break every caller that reads status.Code, which is the more common of the two and the one nobody would think to re-check after installing an interceptor.

Std errors.Is works on what it returns, which is not free — see decodedError's Is method for why it takes one, and what the alternative silently cost.

Unary only, and that is narrower than the encoding side: the server has StreamErrorEncodingInterceptor, so a streaming RPC's error does cross the wire encoded, but nothing on the client decodes it yet. A client of a streaming RPC therefore gets a *status.Error that std errors.Is does not match, and DecodeErrorFromStatus is what such a client calls by hand today.

func UnaryErrorEncodingInterceptor ¶

func UnaryErrorEncodingInterceptor() grpc.UnaryServerInterceptor

UnaryErrorEncodingInterceptor returns a unary interceptor that encodes handler errors into gRPC status details for wire transmission. Handlers should return errors (optionally wrapped); the interceptor will derive the gRPC code via MapToGRPC and attach the encoded error to details.