protobuf

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.

Oneway methods are supported as well. To use, define your RPC method to return the uber.yarpc.Oneway type defined in go.uber.org/yarpc/yarpcproto/yarpc.proto.

syntax = "proto3;

import "go.uber.org/yarpc/yarpcproto/yarpc.proto";

package foo;

message FireRequest {}

service Baz {
  rpc Fire(FireRequest) returns (uber.yarpc.Oneway) {}
}

Corresponding BazYARPCClient and BazYARPCServer interfaces will be generated.

type BazYARPCClient interface {
  Fire(context.Context, *FireRequest, ...yarpc.CallOption) (yarpc.Ack, error)
}

type BazYARPCServer interface {
  Fire(context.Context, *FireRequest) error
}

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
• func BuildProcedures(params BuildProceduresParams) []transport.Procedure
• func CastError(expectedType proto.Message, actualType proto.Message) error
• func NewOnewayHandler(params OnewayHandlerParams) transport.OnewayHandler
• func NewUnaryHandler(params UnaryHandlerParams) transport.UnaryHandler
• type BuildProceduresOnewayHandlerParams
• type BuildProceduresParams
• type BuildProceduresUnaryHandlerParams
• type Client
  • func NewClient(params ClientParams) Client
• type ClientOption
  • func ClientBuilderOptions(_ transport.ClientConfig, structField reflect.StructField) []ClientOption
• type ClientParams
• type OnewayHandlerParams
• type UnaryHandlerParams

Constants

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"
)

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 NewOnewayHandler

func NewOnewayHandler(params OnewayHandlerParams) transport.OnewayHandler

NewOnewayHandler returns a new OnewayHandler.

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
}

BuildProceduresParams contains the parameters 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
	Options      []ClientOption
}

ClientParams contains the parameters for creating a new Client.

type OnewayHandlerParams

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

OnewayHandlerParams contains the parameters for creating a new OnewayHandler.

type UnaryHandlerParams

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

UnaryHandlerParams contains the parameters for creating a new UnaryHandler.