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"
	"github.com/gorilla/rpc/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

• type Codec
• type CodecRequest
• 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) RegisterTCPService(receiver interface{}, name string) error
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

Types

type Codec

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

Codec creates a CodecRequest to process each request.

type CodecRequest

type CodecRequest interface {
	// Reads request and returns the RPC method name.
	Method() (string, error)
	// Reads request filling the RPC method args.
	ReadRequest(interface{}) error
	// Writes response using the RPC method reply. The error parameter is
	// the error returned by the method call, if any.
	WriteResponse(http.ResponseWriter, interface{}, error) error
}

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

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

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

RegisterTCPService adds a new TCP service to the server. No HTTP request struct will be passed to the service methods.

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 two arguments: *args, *reply.
• Both arguments are pointers.
• Both 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