goa: goa.design/goa/grpc Index | Files | Directories

package grpc

import "goa.design/goa/grpc"

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

Package Files

client.go doc.go encoding.go error.go handler.go

func DecodeError Uses

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 Uses

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 Uses

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 Uses

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 Uses

func NewServiceError(resp *goapb.ErrorResponse) *goa.ServiceError

NewServiceError returns a goa ServiceError type for the given ErrorResponse message.

func NewStatusError Uses

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.

type ClientError Uses

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 Uses

func (c *ClientError) Error() string

Error builds an error message.

type Invoker Uses

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 Uses

func NewInvoker(fn RemoteFunc, enc RequestEncoder, dec ResponseDecoder) Invoker

NewInvoker returns an invoker to invoke gRPC methods.

type RemoteFunc Uses

type RemoteFunc func(ctx context.Context, reqpb interface{}, opts ...grpc.CallOption) (respb interface{}, err error)

RemoteFunc invokes a RPC method.

type RequestDecoder Uses

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 Uses

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 Uses

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 Uses

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 Uses

type StreamHandler interface {
    // Handle handles a streaming RPC.
    //
    // input contains the goa endpoint payload type (if any) and goa generated
    // endpoint stream interface.
    Handle(ctx context.Context, input interface{}) (err error)
    // Decode decodes the protocol buffer message type and incoming metadata to
    // the goa type. For client-side and bidirectional streams, the request
    // message type will be 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 Uses

func NewStreamHandler(e goa.Endpoint, dec RequestDecoder) StreamHandler

NewStreamHandler returns a handler to handle streaming gRPC endpoints.

type UnaryHandler Uses

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 Uses

func NewUnaryHandler(e goa.Endpoint, dec RequestDecoder, enc ResponseEncoder) UnaryHandler

NewUnaryHandler returns a handler to handle unary gRPC endpoints.

Directories

PathSynopsis
codegenPackage 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.
middlewarePackage middleware contains gRPC server and client interceptors that wraps unary and streaming RPCs to provide additional functionality.
middleware/xrayPackage 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.
pbPackage goapb contains protocol buffer message types used by the code generation logic.

Package grpc imports 9 packages (graph). Updated 2019-11-08. Refresh now. Tools for package owners.