Skip to content

kylelemons/go-rpcgen

Folders and files

NameName
Last commit message
Last commit date
Oct 2, 2013
Oct 2, 2013
Oct 2, 2013
Oct 2, 2013
Jan 6, 2013
Oct 2, 2013
Apr 1, 2012
Oct 2, 2013
Feb 10, 2012
Apr 1, 2012
Mar 2, 2013
Oct 2, 2013
Apr 20, 2012

Repository files navigation

// Copyright 2013 Google. All rights reserved.
//
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file or at
// https://developers.google.com/open-source/licenses/bsd

// 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.
//
// Installation
//
// To install, run the following command:
//   go get -v -u github.com/kylelemons/go-rpcgen/protoc-gen-go
//
// 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
//
// 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 and a webrpc package.
//
// Configuration
//
// By default, protoc-gen-go will generate both RPC and web-based stubs,
// but this can be configured by setting the GO_STUBS environment variable.
// This variable is a comma-separated list of the stubs to generate.  The known
// stubs are:
//
//   rpc // Generate stubs for net/rpc
//   web // Generate stubs for direct HTTP access, e.g. via AppEngine
//
// Generated Code for RPC
//
// 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.
//   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 or
// DialEchoService.
//
// Generated Code for WebRPC
//
// In addition to the above, the following are also generated to facilitate
// serving RPCs over the web (e.g. AppEngine; see example_ae/):
//
//   // EchoServiceWeb is the web-based RPC version of the interface which
//   // must be implemented by the object wrapped by the webrpc server.
//   type EchoServiceWeb interface {
//     Echo(r *http.Request, in *Payload, out *Payload) error
//   }
//
//   // NewEchoServiceWebClient returns a webrpc wrapper for calling EchoService
//   // remotely via the web.  The remote URL is the base URL of the webrpc server.
//   func NewEchoServiceWebClient(remote *url.URL, pro webrpc.Protocol) EchoService
//
//   // Register a EchoServiceWeb implementation with the given webrpc ServeMux.
//   // If mux is nil, the default webrpc.ServeMux is used.
//   func RegisterEchoServiceWeb(this EchoServiceWeb, mux webrpc.ServeMux) error
//
// Any type which implements EchoServiceWeb (notice that the handlers also
// receive the *http.Request) can be registered.  The RegisterEchoServiceWeb
// function registers the given backend implementation to be called from the
// web via the webrpc package.
//
// Examples
//
// See the examples/ subdirectory for some complete examples demonstrating
// basic usage.  See the example_ae/ subdirectory for an appengine example and
// for directions about how to deploy go-rpcgen on appengine.
//
// Acknowledgements
//
// Thanks to the following people:
//   Bill Broadley <bill@broadley.org> - for beta testing and examples
package rpcgendoc