grpc

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 interface{}) error
• func NewErrorResponse(err error) *goapb.ErrorResponse
• func NewServiceError(resp *goapb.ErrorResponse) *goa.ServiceError
• func NewStatusError(code codes.Code, err error, details ...proto.Message) error
• type ClientError
  • func (c *ClientError) Error() string
• type Invoker
  • func NewInvoker(fn RemoteFunc, enc RequestEncoder, dec ResponseDecoder) Invoker
• type RemoteFunc
• type RequestDecoder
• type RequestEncoder
• type ResponseDecoder
• type ResponseEncoder
• type StreamHandler
  • func NewStreamHandler(e goa.Endpoint, dec RequestDecoder) StreamHandler
• type UnaryHandler
  • func NewUnaryHandler(e goa.Endpoint, dec RequestDecoder, enc ResponseEncoder) UnaryHandler

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.