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

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func DecodeError

    func DecodeError(err error) proto.Message

      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

      func EncodeError(err error) error

        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

        func ErrInvalidType(svc, m, expected string, actual interface{}) error

          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

              func NewStatusError(code codes.Code, err error, details ...proto.Message) error

                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.

                  func (*ClientError) Error

                  func (c *ClientError) Error() string

                    Error builds an error message.

                    type Invoker

                    type Invoker interface {
                    	Invoke(ctx context.Context, req interface{}) (res interface{}, err error)
                    }

                      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 interface{}, opts ...grpc.CallOption) (respb interface{}, err error)

                          RemoteFunc invokes a RPC method.

                          type RequestDecoder

                          type RequestDecoder func(ctx context.Context, pb interface{}, md metadata.MD) (v interface{}, err error)

                            RequestDecoder is used by the server to decode gRPC request message type and any incoming metadata to goa type.

                            type RequestEncoder

                            type RequestEncoder func(ctx context.Context, v interface{}, md *metadata.MD) (pb interface{}, err error)

                              RequestEncoder is used by the client to encode goa type to gRPC message type and sets the outgoing metadata.

                              type ResponseDecoder

                              type ResponseDecoder func(ctx context.Context, pb interface{}, hdr, trlr metadata.MD) (v interface{}, err error)

                                ResponseDecoder is used by the client to decode gRPC response message type and any incoming metadata (headers and trailers) to goa type.

                                type ResponseEncoder

                                type ResponseEncoder func(ctx context.Context, v interface{}, hdr, trlr *metadata.MD) (pb interface{}, err error)

                                  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 interface{}) (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 interface{}) (req interface{}, 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 interface{}) (respb interface{}, 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.

                                          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.