rpc

README

rpc

this is a fork version of github.com/gorilla/rpc

rpc support for JSON-RPC 1.0/2.0 Specification.

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

Documentation

Overview

Package terryding77/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 (
		"net/http"
		"github.com/terryding77/rpc"
		"github.com/terryding77/rpc/jsonrpc"
	)

	func main() {
		s := rpc.NewServer()
		s.RegisterCodec(jsonrpc.NewCodec(), "application/json")
		s.RegisterService(new(HelloService), "")
        http.Handle("/rpc", s)
        log.Print("start server")
        log.Fatal(http.ListenAndServe(":8080", nil))
	}

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.

Use curl to test this:

curl -H "Content-Type:application/json" -X POST --data '{"jsonrpc":"2.0","method":"HelloService.Say","params":{"Who":"terry"},"id":1}' http://localhost:8080/rpc

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.

Index

• Variables
• func WriteHTTPError(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 RequestInfo
• type Server
  • func NewServer() *Server
  • func (s *Server) HasMethod(method string) bool
  • func (s *Server) RegisterAfterFunc(f func(i *RequestInfo))
  • func (s *Server) RegisterBeforeFunc(f func(i *RequestInfo))
  • func (s *Server) RegisterCodec(codec Codec, contentType string)
  • func (s *Server) RegisterInterceptFunc(f func(i *RequestInfo) *http.Request)
  • 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 WriteHTTPError

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

WriteHTTPError writes the status code and msg into HTTP ResponseWriter

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 RequestInfo

type RequestInfo struct {
	Method     string
	Error      error
	Request    *http.Request
	StatusCode int
}

RequestInfo contains all the information we pass to before/after functions

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

func (s *Server) RegisterAfterFunc(f func(i *RequestInfo))

RegisterAfterFunc registers the specified function as the function that will be called after every request

Note: Only one function can be registered, subsequent calls to this method will overwrite all the previous functions.

func (*Server) RegisterBeforeFunc

func (s *Server) RegisterBeforeFunc(f func(i *RequestInfo))

RegisterBeforeFunc registers the specified function as the function that will be called before every request.

Note: Only one function can be registered, subsequent calls to this method will overwrite all the previous functions.

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

func (s *Server) RegisterInterceptFunc(f func(i *RequestInfo) *http.Request)

RegisterInterceptFunc registers the specified function as the function that will be called before every request. The function is allowed to intercept the request e.g. add values to the context.

Note: Only one function can be registered, subsequent calls to this method will overwrite all the previous functions.

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