Documentation

Overview

    Package protobuf implements Protocol Buffers encoding support for YARPC.

    To use this package, you must have protoc installed, as well as the Golang protoc plugin from either github.com/golang/protobuf or github.com/gogo/protobuf. We recommend github.com/gogo/protobuf.

    go get github.com/gogo/protobuf/protoc-gen-gogoslick
    

    You must also install the Protobuf plugin for YARPC:

    go get go.uber.org/yarpc/encoding/protobuf/protoc-gen-yarpc-go
    

    To generate YARPC compatible code from a Protobuf file, use the command:

    protoc --gogoslick_out=. --yarpc-go_out=. foo.proto
    

    The Golang protoc plugin will generate the Golang types in foo.pb.go, while the YARPC plugin will generate the YARPC types in foo.pb.yarpc.go.

    The client interface for a service named Bar will be generated with the name BarYARPCClient, and can be instantiated with a transport.ClientConfig.

    barClient := foo.NewBarYARPCClient(dispatcher.ClientConfig("myservice"))
    

    The server interface will be generated with the name BarYARPCServer. This is the interface that should be implemented on the server-side. Procedures can be constructed from an implementation of BarYARPCServer using the BuildBarYARPCProcedures method.

    dispatcher.Register(foo.BuildBarYARPCProcedures(barServer))
    

    Proto3 defines a mapping to JSON, so for every RPC method, two Procedures are created for every RPC method: one that will handle the standard Protobuf binary encoding, and one that will handle the JSON encoding.

    If coupled with an HTTP Inbound, Protobuf procedures can be called using curl. Given the following Protobuf definition:

    syntax = "proto3;
    
    package foo.bar;
    
    message EchoRequest {
      string value = 1;
    }
    
    message EchoResponse {
      string value = 1;
    }
    
    service Baz {
      rpc Echo(EchoRequest) returns (EchoResponse) {}
    }
    

    And the following configuration:

    service:
      name: hello
    yarpc:
      inbounds:
        http:
           address: ":8080"
    

    If running locally, one could make the following call:

    curl \
      http://0.0.0.0:8080 \
      -H 'context-ttl-ms: 2000' \
      -H "rpc-caller: curl-$(whoami)" \
      -H 'rpc-service: hello' \
      -H 'rpc-encoding: json' \
      -H 'rpc-procedure: foo.bar.Baz::Echo' \
      -d '{"value":"sample"}'
    

    Where context-ttl-ms is the timeout in milliseconds, rpc-caller is the name of the entity making the request, rpc-service is the name of the configured service, rpc-encoding is json, rpc-procedure is the name of the Protobuf method being called in the form proto_package.proto_service::proto_method, and the data is the JSON representation of the request.

    If using Yab, one can also use:

    yab -p http://0.0.0.0:8080 -e json -s hello -p foo.bar.Baz::Echo -r '{"value":"sample"}'
    

    See https://github.com/yarpc/yab for more details.

    Except for any ClientOptions (such as UseJSON), the types and functions defined in this package should not be directly used in applications, instead use the code generated from protoc-gen-yarpc-go.

    Index

    Constants

    View Source
    const (
    	// Encoding is the name of this encoding.
    	Encoding transport.Encoding = "proto"
    
    	// JSONEncoding is the name of the JSON encoding.
    	//
    	// Protobuf handlers are able to handle both Encoding and JSONEncoding encodings.
    	JSONEncoding transport.Encoding = "json"
    )

    Variables

    This section is empty.

    Functions

    func BuildProcedures

    func BuildProcedures(params BuildProceduresParams) []transport.Procedure

      BuildProcedures builds the transport.Procedures.

      func CastError

      func CastError(expectedType proto.Message, actualType proto.Message) error

        CastError returns an error saying that generated code could not properly cast a proto.Message to it's expected type.

        func GetErrorDetails

        func GetErrorDetails(err error) []interface{}

          GetErrorDetails returns the error details of the error.

          This method supports extracting details from wrapped errors.

          Each element in the returned slice of interface{} is either a proto.Message or an error to explain why the element is not a proto.Message, most likely because the error detail could not be unmarshaled. See: https://github.com/gogo/status/blob/master/status.go#L193

          func NewError

          func NewError(code yarpcerrors.Code, message string, options ...ErrorOption) error

            NewError returns a new YARPC protobuf error. To access the error's fields, use the yarpcerrors package APIs for the code and message, and the `GetErrorDetails(error)` function for error details. The `yarpcerrors.Details()` will not work on this error.

            If the Code is CodeOK, this will return nil.

            func NewOnewayHandler

            func NewOnewayHandler(params OnewayHandlerParams) transport.OnewayHandler

              NewOnewayHandler returns a new OnewayHandler.

              func NewStreamHandler

              func NewStreamHandler(params StreamHandlerParams) transport.StreamHandler

                NewStreamHandler returns a new StreamHandler.

                func NewUnaryHandler

                func NewUnaryHandler(params UnaryHandlerParams) transport.UnaryHandler

                  NewUnaryHandler returns a new UnaryHandler.

                  Types

                  type BuildProceduresOnewayHandlerParams

                  type BuildProceduresOnewayHandlerParams struct {
                  	MethodName string
                  	Handler    transport.OnewayHandler
                  }

                    BuildProceduresOnewayHandlerParams contains the parameters for a OnewayHandler for BuildProcedures.

                    type BuildProceduresParams

                    type BuildProceduresParams struct {
                    	ServiceName         string
                    	UnaryHandlerParams  []BuildProceduresUnaryHandlerParams
                    	OnewayHandlerParams []BuildProceduresOnewayHandlerParams
                    	StreamHandlerParams []BuildProceduresStreamHandlerParams
                    }

                      BuildProceduresParams contains the parameters for BuildProcedures.

                      type BuildProceduresStreamHandlerParams

                      type BuildProceduresStreamHandlerParams struct {
                      	MethodName string
                      	Handler    transport.StreamHandler
                      }

                        BuildProceduresStreamHandlerParams contains the parameters for a StreamHandler for BuildProcedures.

                        type BuildProceduresUnaryHandlerParams

                        type BuildProceduresUnaryHandlerParams struct {
                        	MethodName string
                        	Handler    transport.UnaryHandler
                        }

                          BuildProceduresUnaryHandlerParams contains the parameters for a UnaryHandler for BuildProcedures.

                          type Client

                          type Client interface {
                          	Call(
                          		ctx context.Context,
                          		requestMethodName string,
                          		request proto.Message,
                          		newResponse func() proto.Message,
                          		options ...yarpc.CallOption,
                          	) (proto.Message, error)
                          	CallOneway(
                          		ctx context.Context,
                          		requestMethodName string,
                          		request proto.Message,
                          		options ...yarpc.CallOption,
                          	) (transport.Ack, error)
                          }

                            Client is a protobuf client.

                            func NewClient

                            func NewClient(params ClientParams) Client

                              NewClient creates a new client.

                              type ClientOption

                              type ClientOption interface {
                              	// contains filtered or unexported methods
                              }

                                ClientOption is an option for a new Client.

                                var UseJSON ClientOption = useJSON{}

                                  UseJSON says to use the json encoding for client/server communication.

                                  func ClientBuilderOptions

                                  func ClientBuilderOptions(_ transport.ClientConfig, structField reflect.StructField) []ClientOption

                                    ClientBuilderOptions returns ClientOptions that yarpc.InjectClients should use for a specific client given information about the field into which the client is being injected.

                                    type ClientParams

                                    type ClientParams struct {
                                    	ServiceName  string
                                    	ClientConfig transport.ClientConfig
                                    	AnyResolver  jsonpb.AnyResolver
                                    	Options      []ClientOption
                                    }

                                      ClientParams contains the parameters for creating a new Client.

                                      type ClientStream

                                      type ClientStream struct {
                                      	// contains filtered or unexported fields
                                      }

                                        ClientStream is a protobuf-specific client stream.

                                        func (*ClientStream) Close

                                        func (c *ClientStream) Close(options ...yarpc.StreamOption) error

                                          Close will close the protobuf stream.

                                          func (*ClientStream) Context

                                          func (c *ClientStream) Context() context.Context

                                            Context returns the context of the stream.

                                            func (*ClientStream) Receive

                                            func (c *ClientStream) Receive(newMessage func() proto.Message, options ...yarpc.StreamOption) (proto.Message, error)

                                              Receive will receive a protobuf message from the client stream.

                                              func (*ClientStream) Send

                                              func (c *ClientStream) Send(message proto.Message, options ...yarpc.StreamOption) error

                                                Send will send a protobuf message to the client stream.

                                                type ErrorOption

                                                type ErrorOption struct {
                                                	// contains filtered or unexported fields
                                                }

                                                  ErrorOption is an option for the NewError constructor.

                                                  func WithErrorDetails

                                                  func WithErrorDetails(details ...proto.Message) ErrorOption

                                                    WithErrorDetails adds to the details of the error.

                                                    type OnewayHandlerParams

                                                    type OnewayHandlerParams struct {
                                                    	Handle      func(context.Context, proto.Message) error
                                                    	NewRequest  func() proto.Message
                                                    	AnyResolver jsonpb.AnyResolver
                                                    }

                                                      OnewayHandlerParams contains the parameters for creating a new OnewayHandler.

                                                      type ServerStream

                                                      type ServerStream struct {
                                                      	// contains filtered or unexported fields
                                                      }

                                                        ServerStream is a protobuf-specific server stream.

                                                        func (*ServerStream) Context

                                                        func (s *ServerStream) Context() context.Context

                                                          Context returns the context of the stream.

                                                          func (*ServerStream) Receive

                                                          func (s *ServerStream) Receive(newMessage func() proto.Message, options ...yarpc.StreamOption) (proto.Message, error)

                                                            Receive will receive a protobuf message from the server stream.

                                                            func (*ServerStream) Send

                                                            func (s *ServerStream) Send(message proto.Message, options ...yarpc.StreamOption) error

                                                              Send will send a protobuf message to the server stream.

                                                              type StreamClient

                                                              type StreamClient interface {
                                                              	Client
                                                              
                                                              	CallStream(
                                                              		ctx context.Context,
                                                              		requestMethodName string,
                                                              		opts ...yarpc.CallOption,
                                                              	) (*ClientStream, error)
                                                              }

                                                                StreamClient is a protobuf client with streaming.

                                                                func NewStreamClient

                                                                func NewStreamClient(params ClientParams) StreamClient

                                                                  NewStreamClient creates a new stream client.

                                                                  type StreamHandlerParams

                                                                  type StreamHandlerParams struct {
                                                                  	Handle func(*ServerStream) error
                                                                  }

                                                                    StreamHandlerParams contains the parameters for creating a new StreamHandler.

                                                                    type UnaryHandlerParams

                                                                    type UnaryHandlerParams struct {
                                                                    	Handle      func(context.Context, proto.Message) (proto.Message, error)
                                                                    	NewRequest  func() proto.Message
                                                                    	AnyResolver jsonpb.AnyResolver
                                                                    }

                                                                      UnaryHandlerParams contains the parameters for creating a new UnaryHandler.

                                                                      Directories

                                                                      Path Synopsis
                                                                      Package main provides a protoc plugin that generates code for the protobuf encoding for YARPC.
                                                                      Package main provides a protoc plugin that generates code for the protobuf encoding for YARPC.
                                                                      Package reflection exposes information about protobuf services required to implement the gRPC server reflection API and return information about the compatible registered yarpc services.
                                                                      Package reflection exposes information about protobuf services required to implement the gRPC server reflection API and return information about the compatible registered yarpc services.
                                                                      internal