Documentation
¶
Overview ¶
Package grpc contains code generation logic to produce a server that serves gRPC requests and a client that encode requests to and decode responses from a gRPC server. It produces gRPC service definitions (.proto files) from Goa expressions that were created by executing a design DSL. It then compiles the definition using the protocol buffer compiler (protoc) using the Go gRPC plugin, and generates code that hooks up the compiled protocol buffer types and gRPC code with the types and code generated by Goa. It uses the "proto3" syntax to generate gRPC service and protocol buffer message definitions.
In addition to the code generation logic, the grpc package contains:
- A customizable server and client handler interface to handle unary and streaming RPCs.
- Encoder and decoder interfaces to convert a protocol buffer type to a Goa type and vice versa.
- Error handlers to encode and decode error responses.
- Interceptors (a.k.a middlewares) to wrap additional functionality around unary and streaming RPCs.
Index ¶
- func DecodeError(err error) proto.Message
- func EncodeError(err error) error
- func ErrInvalidType(svc, m, expected string, actual any) error
- func NewErrorResponse(err error) *goapb.ErrorResponse
- func NewServiceError(resp *goapb.ErrorResponse) *goa.ServiceError
- func NewStatusError(code codes.Code, err error, details ...protoiface.MessageV1) error
- type ClientError
- type Invoker
- type RemoteFunc
- type RequestDecoder
- type RequestEncoder
- type ResponseDecoder
- type ResponseEncoder
- type StreamHandler
- type UnaryHandler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecodeError ¶
DecodeError returns the error message encoded in the status details if error is a gRPC status error. It assumes that the error message is encoded as the first item in the details. It returns nil if the error is not a gRPC status error or if no detail is found.
func EncodeError ¶
EncodeError returns a gRPC status error from the given error with the error response encoded in the status details. If error is a goa ServiceError type it implements a heuristic to compute the status code from the Timeout, Fault, and Temporary characteristics of the ServiceError. If error is not a ServiceError or a gRPC status error it returns a gRPC status error with Unknown code and Fault characteristic set.
func ErrInvalidType ¶
ErrInvalidType is the error returned when the wrong type is given to a encoder or decoder.
func NewErrorResponse ¶
func NewErrorResponse(err error) *goapb.ErrorResponse
NewErrorResponse creates a new ErrorResponse protocol buffer message from the given error. If the given error is a goa ServiceError, the ErrorResponse message will be set with the corresponding Timeout, Temporary, and Fault characteristics. If the error is not a goa ServiceError, it creates an ErrorResponse message with the Fault field set to true.
func NewServiceError ¶
func NewServiceError(resp *goapb.ErrorResponse) *goa.ServiceError
NewServiceError returns a goa ServiceError type for the given ErrorResponse message.
func NewStatusError ¶
NewStatusError creates a gRPC status error with the error response messages added to its details.
Types ¶
type ClientError ¶
type ClientError struct {
// Name is a name for this class of errors.
Name string
// Message contains the specific error details.
Message string
// Service is the name of the service.
Service string
// Method is the name of the service method.
Method string
// Is the error temporary?
Temporary bool
// Is the error a timeout?
Timeout bool
// Is the error a server-side fault?
Fault bool
}
ClientError is an error returned by a gRPC service client.
type Invoker ¶
Invoker invokes a gRPC method. The request and response types are goa types.
func NewInvoker ¶
func NewInvoker(fn RemoteFunc, enc RequestEncoder, dec ResponseDecoder) Invoker
NewInvoker returns an invoker to invoke gRPC methods.
type RemoteFunc ¶
type RemoteFunc func(ctx context.Context, reqpb any, opts ...grpc.CallOption) (respb any, err error)
RemoteFunc invokes a RPC method.
type RequestDecoder ¶
RequestDecoder is used by the server to decode gRPC request message type and any incoming metadata to goa type.
type RequestEncoder ¶
RequestEncoder is used by the client to encode goa type to gRPC message type and sets the outgoing metadata.
type ResponseDecoder ¶
ResponseDecoder is used by the client to decode gRPC response message type and any incoming metadata (headers and trailers) to goa type.
type ResponseEncoder ¶
ResponseEncoder is used by the server to encode goa type to gRPC response message type and sets the response headers and trailers.
type StreamHandler ¶
type StreamHandler interface {
// Handle handles a streaming RPC.
//
// input contains the endpoint payload (if any) and generated
// endpoint stream.
Handle(ctx context.Context, input any) (err error)
// Decode decodes the protocol buffer message and metadata to
// the service type. For client-side and bidirectional streams,
// the message is nil.
Decode(ctx context.Context, reqpb any) (req any, err error)
}
StreamHandler handles a streaming RPC. The stream may be client-side, server-side, or bidirectional.
func NewStreamHandler ¶
func NewStreamHandler(e goa.Endpoint, dec RequestDecoder) StreamHandler
NewStreamHandler returns a handler to handle streaming gRPC endpoints.
type UnaryHandler ¶
type UnaryHandler interface {
// Handle handles a unary RPC.
//
// It takes a protocol buffer message type and returns a
// protocol buffer message type and any error when executing the
// RPC.
Handle(ctx context.Context, reqpb any) (respb any, err error)
}
UnaryHandler handles a unary RPC. The request and response types are protocol buffer message types.
func NewUnaryHandler ¶
func NewUnaryHandler(e goa.Endpoint, dec RequestDecoder, enc ResponseEncoder) UnaryHandler
NewUnaryHandler returns a handler to handle unary gRPC endpoints.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package codegen contains the code generation logic to generate gRPC service definitions (.proto files) from the design DSLs and the corresponding server and client code that wraps the goa-generated endpoints with the protocol buffer compiler (protoc) generated clients and servers.
|
Package codegen contains the code generation logic to generate gRPC service definitions (.proto files) from the design DSLs and the corresponding server and client code that wraps the goa-generated endpoints with the protocol buffer compiler (protoc) generated clients and servers. |
|
Package middleware contains gRPC server and client interceptors that wraps unary and streaming RPCs to provide additional functionality.
|
Package middleware contains gRPC server and client interceptors that wraps unary and streaming RPCs to provide additional functionality. |
|
xray
Package xray contains unary and streaming server and client interceptors that create AWS X-Ray segments from the gRPC requests and responses and send the segments to an AWS X-ray daemon.
|
Package xray contains unary and streaming server and client interceptors that create AWS X-Ray segments from the gRPC requests and responses and send the segments to an AWS X-ray daemon. |
|
Package goapb contains protocol buffer message types used by the code generation logic.
|
Package goapb contains protocol buffer message types used by the code generation logic. |