wsrpc

README

wsrpc

wsrpc is a golang module that implements JSON-RPC 2.0 over WebSocket.
Since WebSocket is full-duplex, wsrpc support two-way procedure call.

Install

Just use the Go toolchain:

go get -u github.com/1354092549/wsrpc

License

This library is licensed under BSD 3-Clause License.
Please see LICENSE for licensing details.
You can use TLDRLegal to see a summary first. (!!!NOT LEGAL ADVICE!!!)

Documentation

Index

• Variables
• func IsJSONArray(in []byte) bool
• func IsJSONNull(in []byte) bool
• func IsJSONObject(in []byte) bool
• type LowLevelRPCMethod
• type MessageAdapter
• type RPCErrorInfo
  • func ToRPCError(err error) RPCErrorInfo
  • func (err RPCErrorInfo) Error() string
• type WebsocketMessageAdapter
  • func NewWebsocketMessageAdapter(conn *websocket.Conn) *WebsocketMessageAdapter
  • func (a *WebsocketMessageAdapter) ReadMessage() ([]byte, error)
  • func (a *WebsocketMessageAdapter) WriteMessage(data []byte) error
• type WebsocketRPC
  • func NewWebsocketRPC() *WebsocketRPC
  • func (rpc *WebsocketRPC) Connect(conn *websocket.Conn) *WebsocketRPCConn
  • func (rpc *WebsocketRPC) ConnectAdapter(adapter MessageAdapter) *WebsocketRPCConn
  • func (rpc *WebsocketRPC) Register(name string, fobj interface{}, inName []string, outName []string)
  • func (rpc *WebsocketRPC) RegisterExplicitly(name string, fobj interface{}) error
  • func (rpc *WebsocketRPC) RegisterLowLevel(name string, method LowLevelRPCMethod)
• type WebsocketRPCConn
  • func (rpcConn *WebsocketRPCConn) CallExplicitly(name string, params interface{}, reply interface{}) error
  • func (rpcConn *WebsocketRPCConn) CallLowLevel(name string, params json.RawMessage, reply *json.RawMessage) error
  • func (rpcConn *WebsocketRPCConn) MakeCall(name string, fptr interface{}, inName []string, outName []string)
  • func (rpcConn *WebsocketRPCConn) MakeNotify(name string, fptr interface{}, inName []string)
  • func (rpcConn *WebsocketRPCConn) NotifyExplicitly(name string, params interface{}) error
  • func (rpcConn *WebsocketRPCConn) NotifyLowLevel(name string, params json.RawMessage) error
  • func (rpcConn *WebsocketRPCConn) ServeConn()

Variables

var RPCInternalError = RPCErrorInfo{
	Code:    -32603,
	Message: "Internal error"}

RPCInternalError represents an internal error.

var RPCInvalidParamsError = RPCErrorInfo{
	Code:    -32602,
	Message: "Invalid params"}

RPCInvalidParamsError represents an error that params are invalid.

var RPCInvalidRequestError = RPCErrorInfo{
	Code:    -32600,
	Message: "Invalid Request"}

RPCInvalidRequestError represents that the JSON sent is not a valid Request object.

var RPCMothedNotFoundError = RPCErrorInfo{
	Code:    -32601,
	Message: "Method not found"}

RPCMothedNotFoundError represents an error that method is not found.

var RPCParseError = RPCErrorInfo{
	Code:    -32700,
	Message: "Parse error"}

RPCParseError represents that an error occurred while parsing the JSON text.

Functions

func IsJSONArray

func IsJSONArray(in []byte) bool

IsJSONArray checks the input whether it is a JSON array or not.

func IsJSONNull

func IsJSONNull(in []byte) bool

IsJSONNull checks the input whether it is a JSON null value or not.

func IsJSONObject

func IsJSONObject(in []byte) bool

IsJSONObject checks the input whether it is a JSON object or not.

Types

type LowLevelRPCMethod

type LowLevelRPCMethod func(rpcConn *WebsocketRPCConn, arg json.RawMessage, reply *json.RawMessage) error

LowLevelRPCMethod is an RPC method that send and receive raw messages

type MessageAdapter

type MessageAdapter interface {
	// ReadMessage reads a message. If the connection is closed, this function must return an error.
	ReadMessage() ([]byte, error)
	// WriteMessage writes a message. If the connection is closed, this function must return an error.
	WriteMessage(data []byte) error
}

MessageAdapter is an adapter for rpc services to read and write messages.

type RPCErrorInfo

type RPCErrorInfo struct {
	Code    int32       `json:"code"`
	Message string      `json:"message"`
	Data    interface{} `json:"data,omitempty"`
}

RPCErrorInfo represents an RPC error that provides error code and message information. This type implements error

func ToRPCError

func ToRPCError(err error) RPCErrorInfo

ToRPCError is a helper function to convert error to RPCErrorInfo. If err is a RPCErrorInfo, then return it. If not, then create a RPCErrorInfo with Message = err.Error()

func (RPCErrorInfo) Error

func (err RPCErrorInfo) Error() string

type WebsocketMessageAdapter

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

WebsocketMessageAdapter is an adapter for rpc services to work with gorilla/websocket

func NewWebsocketMessageAdapter

func NewWebsocketMessageAdapter(conn *websocket.Conn) *WebsocketMessageAdapter

NewWebsocketMessageAdapter creates a adapter.

func (*WebsocketMessageAdapter) ReadMessage

func (a *WebsocketMessageAdapter) ReadMessage() ([]byte, error)

ReadMessage reads a message. If the connection is closed, this function must return an error.

func (*WebsocketMessageAdapter) WriteMessage

func (a *WebsocketMessageAdapter) WriteMessage(data []byte) error

WriteMessage writes a message. If the connection is closed, this function must return an error.

type WebsocketRPC

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

WebsocketRPC represents an RPC service that run over websocket

func NewWebsocketRPC

func NewWebsocketRPC() *WebsocketRPC

NewWebsocketRPC will create a websocket rpc object.

func (*WebsocketRPC) Connect

func (rpc *WebsocketRPC) Connect(conn *websocket.Conn) *WebsocketRPCConn

Connect is a function to create a rpc connection binded to a websocket connection.

func (*WebsocketRPC) ConnectAdapter

func (rpc *WebsocketRPC) ConnectAdapter(adapter MessageAdapter) *WebsocketRPCConn

ConnectAdapter is a function to create a rpc connection binded to an adapter.

func (*WebsocketRPC) Register

func (rpc *WebsocketRPC) Register(name string, fobj interface{}, inName []string, outName []string)

Register is used to register a normal function for RPC.

The function can have a pointer argument to receive RPC connection object (optional, must be the first in argument, do not provide name for this argument). The function can also have an error return value. (optional, must be the last out argument, do not provide name for this argument)

If inName is nil, then you can only call this function by postion (in JSON array). If outName is not nil, then it will return result by name (in JSON object). If inName/outName is not nil, the length of them must be equal to the number of in/out arguments. (not including special params described above, of course)

func (*WebsocketRPC) RegisterExplicitly

func (rpc *WebsocketRPC) RegisterExplicitly(name string, fobj interface{}) error

RegisterExplicitly provides a `net/rpc`-like way to register a function. In this way, the struct is defined explicitly by the caller

funcObj must have three in arguments. The first is a pointer to RPC connection, the second is used to receive the params (can be a pointer or not), and the third is used to send the result (must be a pointer). Moreover, the function can have no out parameters or have one out parameter to return error info.

func (*WebsocketRPC) RegisterLowLevel

func (rpc *WebsocketRPC) RegisterLowLevel(name string, method LowLevelRPCMethod)

RegisterLowLevel is used to register a normal function for RPC in low-level way (use json.RawMessage).

type WebsocketRPCConn

type WebsocketRPCConn struct {
	//RPC is a pointer to the RPC service
	RPC *WebsocketRPC
	//Session saves the user defined session data
	Session map[string]interface{}
	//Timeout sets the time to wait for a response, default is 10 seconds
	Timeout time.Duration
	// contains filtered or unexported fields
}

WebsocketRPCConn represents an RPC connection to WebsocketRPC

func (*WebsocketRPCConn) CallExplicitly

func (rpcConn *WebsocketRPCConn) CallExplicitly(name string, params interface{}, reply interface{}) error

CallExplicitly provides a `net/rpc`-like way to call a remote procedure. In this way, the struct is defined explicitly by the caller

func (*WebsocketRPCConn) CallLowLevel

func (rpcConn *WebsocketRPCConn) CallLowLevel(name string, params json.RawMessage, reply *json.RawMessage) error

CallLowLevel is used to call a remote rrocedure in low-level way (use json.RawMessage).

func (*WebsocketRPCConn) MakeCall

func (rpcConn *WebsocketRPCConn) MakeCall(name string, fptr interface{}, inName []string, outName []string)

MakeCall is used to make a proxy (as a normal function) to a remote procedure. About inName and outName, you can see details in Register.

func (*WebsocketRPCConn) MakeNotify

func (rpcConn *WebsocketRPCConn) MakeNotify(name string, fptr interface{}, inName []string)

MakeNotify is used to make a proxy (as a normal function) to send a notification. About inName, you can see details in Register.

func (*WebsocketRPCConn) NotifyExplicitly

func (rpcConn *WebsocketRPCConn) NotifyExplicitly(name string, params interface{}) error

NotifyExplicitly provides a `net/rpc`-like way to send a notification. In this way, the struct is defined explicitly by the caller

func (*WebsocketRPCConn) NotifyLowLevel

func (rpcConn *WebsocketRPCConn) NotifyLowLevel(name string, params json.RawMessage) error

NotifyLowLevel is used to send a notification in low-level way (use json.RawMessage).

func (*WebsocketRPCConn) ServeConn

func (rpcConn *WebsocketRPCConn) ServeConn()

ServeConn is a function that you should call it at last to receive messages continuously. It will block until the connection is closed.