documentation

Documentation

Overview

The go-rpcgen project is an attempt to create an easy-to-use, open source protobuf service binding for the standard Go RPC package. It provides a protoc-gen-go (based on the standard "main" from goprotobuf and leveraging its libraries) which has a plugin added to also output RPC stub code.

Prerequisites

You will need the protobuf compiler for your operating system of choice. You can retrieve this from http://code.google.com/p/protobuf/downloads/list if you do not have it already. As this package builds a plugin for the protoc from that package, you will need to have your $GOPATH/bin in your path when you run protoc.

You will also need the goprotobuf package, which would normally be installed automatically by the go tool but it needs some help currently. For some reason, the usual "go get --fix" doesn't quite do enough, so it must be done in two steps:

go get -v -u -d code.google.com/p/goprotobuf/compiler
go fix code.google.com/p/goprotobuf/...

Installation

To install, run the following command:

go get -v -u github.com/kylelemons/go-rpcgen/protoc-gen-go

Because (as mentioned above) goprotobuf hasn't been fully updated to Go 1 yet, You will need to run "go fix" on the output of this package before the .pb.go will compile under the go tool.

Usage

Usage of the package is pretty straightforward. Once you have installed the protoc-gen-go plugin, you can compile protobufs with the following command (where file.proto is the protocol buffer file(s) in question):

protoc --go_out=. file.proto && go fix

This will generate a file named like file.pb.go which contains, in addition to the usual Go bindings for the messages, an interface for each service containing the methods for that service and functions for creating and using them with the RPC package. As mentioned above, the "go fix" is necessary to fix the imports in the generated .pb.go file.

Examples

Given the following basic .proto definition:

package echoservice;
message payload {
    required string message = 1;
}
service echo_service {
    rpc echo (payload) returns (payload);
}

The protoc-gen-go plugin will generate a service definition similar to below:

// EchoService is an interface satisfied by the generated client and
// which must be implemented by the object wrapped by the server.
type EchoService interface {
    Echo(in *Payload, out *Payload) error
}

// DialEchoService returns a EchoService for calling the EchoService servince at addr (TCP).
func DialEchoService(addr string) (EchoService, error) {

// NewEchoServiceClient returns an *rpc.Client wrapper for calling the methods of
// EchoService remotely.
func NewEchoServiceClient(conn net.Conn) EchoService

// ListenAndServeEchoService serves the given EchoService backend implementation
// on all connections accepted as a result of listening on addr (TCP).
func ListenAndServeEchoService(addr string, backend EchoService) error

// ServeEchoService serves the given EchoService backend implementation on conn.
func ServeEchoService(conn net.Conn, backend EchoService) error

Any type which implements EchoService can thus be registered via ServeEchoService or ListenAndServeEchoService to be called remotely via NewEchoServiceClient.

See the examples/ subdirectory for some complete examples demonstrating basic usage.