rpc

README

RPC lib based Golang

In distributed computing, a remote procedure call (RPC) is when a computer program causes a procedure (subroutine) to execute in a different address space (commonly on another computer on a shared network), which is coded as if it were a normal (local) procedure call, without the programmer explicitly coding the details for the remote interaction. That is, the programmer writes essentially the same code whether the subroutine is local to the executing program, or remote. This is a form of client–server interaction (caller is client, executor is server), typically implemented via a request–response message-passing system. In the object-oriented programming paradigm, RPC calls are represented by remote method invocation (RMI). The RPC model implies a level of location transparency, namely that calling procedures is largely the same whether it is local or remote, but usually they are not identical, so local calls can be distinguished from remote calls. Remote calls are usually orders of magnitude slower and less reliable than local calls, so distinguishing them is important.

Todos

• Codec feature.
• RPC implemention over TCP.
• RPC implemention over HTTP.
• JSON RPC(v2) implemention over TCP and HTTP.
• more test cases.
• compatible with JSON RPC 1.0

Documention

About interface Codec

Codec is a interface contains fields:

// Codec to encode and decode
// for client to encode request and decode response
// for server to encode response den decode request
type Codec interface {
	ServerCodec
	ClientCodec
}


// ServerCodec .
// parse request and write response to client.
type ServerCodec interface {
	// parse encoded data into a Request
	ReadRequest(data []byte) ([]Request, error)
	// ReadRequestBody parse params
	ReadRequestBody(reqBody []byte, rcvr interface{}) error
	// generate a single Response with needed params
	NewResponse(replyv interface{}) Response
	// ErrResponse to generate a Reponse contains error
	ErrResponse(errcode int, err error) Response
	// EncodeResponses .
	EncodeResponses(v interface{}) ([]byte, error)
}

// ClientCodec .
// prase response and write request to server
type ClientCodec interface {
	// generate a single NewRequest with needed params
	NewRequest(method string, argv interface{}) Request
	// EncodeRequests .
	EncodeRequests(v interface{}) ([]byte, error)
	// parse encoded data into a Response
	ReadResponse(data []byte) ([]Response, error)
	// ReadResponseBody .
	ReadResponseBody(respBody []byte, rcvr interface{}) error
}

Server Side API

Register will register all exported method of rcvr

func (s *Server) Register(rcvr interface{})

RegisterName only register the appointed method of rcvr

func (s *Server) RegisterName(rcvr interface{}, methodName string)

ServeTCP to run TCP server

func (s *Server) ServeTCP(tcpAddr string)

ServeHTTP to implement http.Handler interface so that the server can serve with HTTP request

func (s *Server) ServeHTTP(w http.ResponseWriter, req *http.NewRequest)

ListenAndServe to run an http server and handle each request

func (s *Server) ListenAndServe(httpAddr string)

Client Side API

Call to send a RPC request to server and recv response

func (c *Client) Call(method string, args, reply interface{}) error

Close c.conn (tcp connection)

func (c *Client) Close()

Examples

RPC gob

JSON RPC

JSON RPC Array

Documentation

Overview

Package rpc support rpc call methos for both server and client.

Index

• Constants
• func DebugF(format string, argvs ...interface{})
• func JSON(w http.ResponseWriter, statusCode int, v interface{}) error
• func String(w http.ResponseWriter, statusCode int, byts []byte) error
• type Client
  • func NewClientWithCodec(codec ClientCodec, tcpAddr string) *Client
  • func (c *Client) Call(method string, args, reply interface{}) error
  • func (c *Client) Close()
• type ClientCodec
• type Codec
  • func NewGobCodec() Codec
• type Error
  • func (r *Error) Error() string
  • func (r *Error) Wrap(err error) error
• type Request
• type Response
• type Server
  • func NewServerWithCodec(codec ServerCodec) *Server
  • func (s *Server) ListenAndServe(addr string)
  • func (s *Server) Register(rcvr interface{}) error
  • func (s *Server) RegisterName(rcvr interface{}, methodName string) error
  • func (s *Server) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (s *Server) ServeTCP(addr string)
• type ServerCodec

Constants

const (
	// Success 0 .
	Success = 0
	// ParseErr -32700 语法解析错误,服务端接收到无效的json。该错误发送于服务器尝试解析json文本
	ParseErr = -32700
	// InvalidRequest -32600 无效请求发送的json不是一个有效的请求对象。
	InvalidRequest = -32600
	// MethodNotFound -32601 找不到方法 该方法不存在或无效
	MethodNotFound = -32601
	// InvalidParamErr -32602 无效的参数 无效的方法参数。
	InvalidParamErr = -32602
	// InternalErr -32603 内部错误 JSON-RPC内部错误。
	InternalErr = -32603
)

Functions

func DebugF

func DebugF(format string, argvs ...interface{})

DebugF .

func JSON

func JSON(w http.ResponseWriter, statusCode int, v interface{}) error

JSON .

func String

func String(w http.ResponseWriter, statusCode int, byts []byte) error

String .

Types

type Client

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

Client as a data struct to connect to server, send and recv data TODO: finish multi request support

func NewClientWithCodec

func NewClientWithCodec(codec ClientCodec, tcpAddr string) *Client

NewClientWithCodec generate a Client prototype rpc.NewClientWithCodec(codec Codec, tcpAddr string) if codec is nil will use default gobCodec, tcpAddr or httpAddr is empty only when you are sure about it will never be used, otherwise it panic while using some functions.

func (*Client) Call

func (c *Client) Call(method string, args, reply interface{}) error

Call .

func (*Client) Close

func (c *Client) Close()

Close the client connectio to the server

type ClientCodec

type ClientCodec interface {
	// generate a single NewRequest with needed params
	NewRequest(method string, argv interface{}) Request
	// EncodeRequests .
	EncodeRequests(v interface{}) ([]byte, error)
	// parse encoded data into a Response
	ReadResponse(data []byte) ([]Response, error)
	// ReadResponseBody .
	ReadResponseBody(respBody []byte, rcvr interface{}) error
}

ClientCodec .

type Codec

type Codec interface {
	ServerCodec
	ClientCodec
}

Codec ... to encode and decode for client to encode request and decode response for server to encode response den decode request

func NewGobCodec

func NewGobCodec() Codec

NewGobCodec to generate a new gobCodec instance

type Error

type Error struct {
	ErrCode int
	ErrMsg  string
}

Error . of rpc protocol

func (*Error) Error

func (r *Error) Error() string

func (*Error) Wrap

func (r *Error) Wrap(err error) error

Wrap an error into this

type Request

type Request interface {
	// Method() to return the string of method name.
	// exmaple, "StructDemo.Method1"
	// and, should has no more form
	Method() string

	// Params means all ([]byte) data contains request args
	// all these origin params (interface{} type)
	// should be result of codec encoded
	Params() []byte

	// Ident to get indentify of request
	Ident() string
}

Request interface contains necessary methods

type Response

type Response interface {
	// Error to return err that response struct contains
	// if there is no any error happend, should return nil
	Error() error

	// ErrorCode to return errcode(int) if ok return SUCCESS(0)
	ErrCode() int

	// Reply means all ([]byte) data contains response body
	// all these response data (interface{} type)
	// should be result of codec encoded
	Reply() []byte

	// SetReqIdent .
	SetReqIdent(ident string)
}

Response interface contains necessary methods

type Server

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

Server data struct to serve RPC request over TCP and HTTP

func NewServerWithCodec

func NewServerWithCodec(codec ServerCodec) *Server

NewServerWithCodec generate a server to handle all tcp request from rpc client, if codec is nil will use default gobCodec

func (*Server) ListenAndServe

func (s *Server) ListenAndServe(addr string)

ListenAndServe open http support can serve http request

func (*Server) Register

func (s *Server) Register(rcvr interface{}) error

Register parse register type and method maybe save into a Map, input value is a varible want to got varible type name, and all Method Name

func (*Server) RegisterName

func (s *Server) RegisterName(rcvr interface{}, methodName string) error

RegisterName ... only want to export one method of rcvr

func (*Server) ServeHTTP

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

ServeHTTP handle request over HTTP, it also implement the interface of http.Handler

func (*Server) ServeTCP

func (s *Server) ServeTCP(addr string)

ServeTCP Dealing with request decode and Call and response

type ServerCodec

type ServerCodec interface {
	// parse encoded data into a Request
	ReadRequest(data []byte) ([]Request, error)
	// ReadRequestBody parse params
	ReadRequestBody(reqBody []byte, rcvr interface{}) error
	// generate a single Response with needed params
	NewResponse(replyv interface{}) Response
	// ErrResponse to generate a Reponse contains error
	ErrResponse(errcode int, err error) Response
	// EncodeResponses .
	EncodeResponses(v interface{}) ([]byte, error)
}

ServerCodec . parse request and write response to client.