rpc

README

rpc

gorilla/rpc is a foundation for RPC over HTTP services, providing access to the exported methods of an object through HTTP requests.

Read the full documentation here: http://www.gorillatoolkit.org/pkg/rpc

Documentation

Overview

Package gorilla/rpc is a foundation for RPC over HTTP services, providing access to the exported methods of an object through HTTP requests.

This package derives from the standard net/rpc package but uses a single HTTP request per call instead of persistent connections. Other differences compared to net/rpc:

• Multiple codecs can be registered in the same server.
• A codec is chosen based on the "Content-Type" header from the request.
• Service methods also receive http.Request as parameter.
• This package can be used on Google App Engine.

Let's setup a server and register a codec and service:

import (
	"http"
	"github.com/gorilla/rpc/v2"
	"github.com/gorilla/rpc/v2/json"
)

func init() {
	s := rpc.NewServer()
	s.RegisterCodec(json.NewCodec(), "application/json")
	s.RegisterService(new(HelloService), "")
	http.Handle("/rpc", s)
}

This server handles requests to the "/rpc" path using a JSON codec. A codec is tied to a content type. In the example above, the JSON codec is registered to serve requests with "application/json" as the value for the "Content-Type" header. If the header includes a charset definition, it is ignored; only the media-type part is taken into account.

A service can be registered using a name. If the name is empty, like in the example above, it will be inferred from the service type.

That's all about the server setup. Now let's define a simple service:

type HelloArgs struct {
	Who string
}

type HelloReply struct {
	Message string
}

type HelloService struct {}

func (h *HelloService) Say(r *http.Request, args *HelloArgs, reply *HelloReply) error {
	reply.Message = "Hello, " + args.Who + "!"
	return nil
}

The example above defines a service with a method "HelloService.Say" and the arguments and reply related to that method.

The service must be exported (begin with an upper case letter) or local (defined in the package registering the service).

When a service is registered, the server inspects the service methods and make available the ones that follow these rules:

• The method name is exported.
• The method has three arguments: *http.Request, *args, *reply.
• All three arguments are pointers.
• The second and third arguments are exported or local.
• The method has return type error.

All other methods are ignored.

Gorilla has packages with common RPC codecs. Check out their documentation:

JSON: http://gorilla-web.appspot.com/pkg/rpc/json

Index

• Variables
• func WriteError(w http.ResponseWriter, status int, msg string)
• type Codec
• type CodecRequest
• type CompressionSelector
  • func (_ *CompressionSelector) Select(r *http.Request) Encoder
• type Encoder
• type EncoderSelector
• type Server
  • func NewServer() *Server
  • func (s *Server) HasMethod(method string) bool
  • func (s *Server) RegisterCodec(codec Codec, contentType string)
  • func (s *Server) RegisterService(receiver interface{}, name string) error
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

Variables

var DefaultEncoder = &encoder{}

var DefaultEncoderSelector = &encoderSelector{}

Functions

func WriteError

func WriteError(w http.ResponseWriter, status int, msg string)

Types

type Codec

type Codec interface {
	NewRequest(*http.Request) CodecRequest
}

Codec creates a CodecRequest to process each request.

type CodecRequest

type CodecRequest interface {
	// Reads the request and returns the RPC method name.
	Method() (string, error)
	// Reads the request filling the RPC method args.
	ReadRequest(interface{}) error
	// Writes the response using the RPC method reply.
	WriteResponse(http.ResponseWriter, interface{})
	// Writes an error produced by the server.
	WriteError(w http.ResponseWriter, status int, err error)
}

CodecRequest decodes a request and encodes a response using a specific serialization scheme.

type CompressionSelector

type CompressionSelector struct {
}

CompressionSelector generates the compressed http encoder.

func (*CompressionSelector) Select

func (_ *CompressionSelector) Select(r *http.Request) Encoder

Select method selects the correct compression encoder based on http HEADER.

type Encoder

type Encoder interface {
	Encode(w http.ResponseWriter) io.Writer
}

Encoder interface contains the encoder for http response. Eg. gzip, flate compressions.

type EncoderSelector

type EncoderSelector interface {
	Select(r *http.Request) Encoder
}

EncoderSelector interface provides a way to select encoder using the http request. Typically people can use this to check HEADER of the request and figure out client capabilities. Eg. "Accept-Encoding" tells about supported compressions.

type Server

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

Server serves registered RPC services using registered codecs.

func NewServer

func NewServer() *Server

NewServer returns a new RPC server.

func (*Server) HasMethod

func (s *Server) HasMethod(method string) bool

HasMethod returns true if the given method is registered.

The method uses a dotted notation as in "Service.Method".

func (*Server) RegisterCodec

func (s *Server) RegisterCodec(codec Codec, contentType string)

RegisterCodec adds a new codec to the server.

Codecs are defined to process a given serialization scheme, e.g., JSON or XML. A codec is chosen based on the "Content-Type" header from the request, excluding the charset definition.

func (*Server) RegisterService

func (s *Server) RegisterService(receiver interface{}, name string) error

RegisterService adds a new service to the server.

The name parameter is optional: if empty it will be inferred from the receiver type name.

Methods from the receiver will be extracted if these rules are satisfied:

• The receiver is exported (begins with an upper case letter) or local (defined in the package registering the service).
• The method name is exported.
• The method has three arguments: *http.Request, *args, *reply.
• All three arguments are pointers.
• The second and third arguments are exported or local.
• The method has return type error.

All other methods are ignored.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP