protobuf

package
v1.73.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 31, 2024 License: MIT Imports: 22 Imported by: 26

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 added in v1.39.0 

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 added in v1.39.0 

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 added in v1.27.0 

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 added in v1.27.0 

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 added in v1.27.0 

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

ClientStream is a protobuf-specific client stream.

func (*ClientStream) Close added in v1.27.0 

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

Close will close the protobuf stream.

func (*ClientStream) Context added in v1.27.0 

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

Context returns the context of the stream.

func (*ClientStream) Receive added in v1.27.0 

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 added in v1.27.0 

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

Send will send a protobuf message to the client stream.

type ErrorOption added in v1.39.0 

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

ErrorOption is an option for the NewError constructor.

func WithErrorDetails added in v1.39.0 

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

WithErrorDetails adds to the details of the error. If any errors are encountered, it returns the first error encountered. See: https://github.com/gogo/status/blob/master/status.go#L175

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 added in v1.27.0 

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

ServerStream is a protobuf-specific server stream.

func (*ServerStream) Context added in v1.27.0 

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

Context returns the context of the stream.

func (*ServerStream) Receive added in v1.27.0 

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 added in v1.27.0 

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

Send will send a protobuf message to the server stream.

type StreamClient added in v1.27.0 

type StreamClient interface {
	Client

	CallStream(
		ctx context.Context,
		requestMethodName string,
		opts ...yarpc.CallOption,
	) (*ClientStream, error)
}

StreamClient is a protobuf client with streaming.

func NewStreamClient added in v1.27.0 

func NewStreamClient(params ClientParams) StreamClient

NewStreamClient creates a new stream client.

type StreamHandlerParams added in v1.27.0 

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.

Source Files

View all Source files

Directories

Path Synopsis
internal
testpb
testpb/v2
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.
internal/lib
Package lib contains the library code for protoc-gen-yarpc-go.
 Package lib contains the library code for protoc-gen-yarpc-go.
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.
internal/lib
Package lib contains the library code for protoc-gen-yarpc-go-v2.
 Package lib contains the library code for protoc-gen-yarpc-go-v2.
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.