| // Copyright 2019 The LUCI 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. |
| |
| // Package appstatus can attach/reterieve an application-specific response |
| // status to/from an error. It designed to prevent accidental exposure of |
| // internal statuses to RPC clients, for example Spanner's statuses. |
| // |
| // Attaching a status |
| // |
| // Use ToError, Error and Errorf to create new status-annotated errors. |
| // Use Attach and Attachf to annotate existing errors with a status. |
| // |
| // if req.PageSize < 0 { |
| // return appstatus.Errorf(codes.InvalidArgument, "page size cannot be negative") |
| // } |
| // if err := checkState(); err != nil { |
| // return appstatus.Attachf(err, codes.PreconditionFailed, "invalid state") |
| // } |
| // |
| // This may be done deep in the function call hierarchy. |
| // |
| // Do not use appstatus in code where you don't explicitly intend to return a |
| // specific status. This is unnecessary because any unrecognized error is |
| // treated as internal and because it is explicitly prohibited to attach a |
| // status to an error chain multiple times. When a status is attached, the |
| // package supports its propagation all the way to the requester |
| // unless there is code that explicitly throws it away. |
| // |
| // Returning a status |
| // |
| // Use GRPCifyAndLog right before returning the error from a gRPC method |
| // handler. Usually it is done in a Postlude of a service decorator, see |
| // ../cmd/svcdec. |
| // |
| // func NewMyServer() pb.MyServer { |
| // return &pb.DecoratedMyServer{ |
| // Service: &actualImpl{}, |
| // Postlude: func(ctx context.Context, methodName string, rsp proto.Message, err error) error { |
| // return appstatus.GRPCifyAndLog(ctx, err) |
| // }, |
| // } |
| // } |
| // |
| // It recognizes only appstatus-annotated errors and treats any other error as |
| // internal. This behavior is important to avoid accidentally returning errors |
| // from Spanner or other client library that also uses grpc/status package to |
| // communicate status code from *other* services. For example, if a there is a |
| // typo in Spanner SQL statement, spanner package may return a status-annotated |
| // errors with code NotFound. In this case, our RPC must respond with internal |
| // error and not NotFound. |
| package appstatus |
