jsonrpc

README

jsonrpc

JSON RPC 2.0 的实现，目前实现了对以下传输层的接口：

• socket, net 包中所有支持 Conn 接口的实现；
• websocket, 采用了 github.com/gorilla/websocket 作为底层调用；
• HTTP 普通的 HTTP 请求方式；

目前不支持批处理模式

Socket

srv := NewServer()
conn := srv.NewConn(NewSocketTransport(), nil)
listen, err := net.Listen("tcp", ":8080")
for {
    c, err := listen.Accept()
    conn.Serve(ctx, NewSocketTransport(c))
}

HTTP

srv := NewServer()
conn := srv.NewHTTPConn(nil)
http.Handle(conn)

安装

go get github.com/issue9/jsonrpc

文档

版权

本项目采用 MIT 开源授权许可证，完整的授权说明可在 LICENSE 文件中找到。

Documentation

Overview

Package jsonrpc 实现简单的 JSON RPC 2.0

https://wiki.geekdream.com/Specification/json-rpc_2.0.html

Index

• Constants
• Variables
• type Conn
  • func (conn *Conn) Notify(method string, in interface{}) error
  • func (conn *Conn) Send(method string, in, out interface{}) error
  • func (conn *Conn) Serve(ctx context.Context) error
• type Error
  • func NewError(code int, msg string) *Error
  • func NewErrorWithData(code int, msg string, data interface{}) *Error
  • func (err *Error) Error() string
• type HTTPConn
  • func (h *HTTPConn) Notify(method string, params interface{}) error
  • func (h *HTTPConn) Send(method string, params, result interface{}) error
  • func (h *HTTPConn) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Server
  • func NewServer() *Server
  • func (s *Server) Exists(method string) bool
  • func (s *Server) NewConn(t Transport, errlog *log.Logger) *Conn
  • func (s *Server) NewHTTPConn(url string, errlog *log.Logger) *HTTPConn
  • func (s *Server) Register(method string, f interface{}) bool
  • func (s *Server) RegisterBefore(f func(method string) error)
  • func (s *Server) Registers(methods map[string]interface{})
• type Transport
  • func NewSocketTransport(header bool, conn net.Conn) Transport
  • func NewStreamTransport(header bool, in io.Reader, out io.Writer, close func() error) Transport
  • func NewWebsocketTransport(conn *websocket.Conn) Transport

Constants

const (
	CodeParseError           = -32700
	CodeInvalidRequest       = -32600
	CodeMethodNotFound       = -32601
	CodeInvalidParams        = -32602
	CodeInternalError        = -32603
	CodeServerErrorStart     = -32099
	CodeServerErrorEnd       = -32000
	CodeServerNotInitialized = -32002
	CodeUnknownErrorCode     = -32001
)

JSON RPC 2.0 定义的错误代码

const Version = "2.0"

Version JSON RPC 的版本

Variables

var (
	ErrInvalidHeader      = errors.New("无效的报头格式")
	ErrInvalidContentType = errors.New("无效的报头 Content-Type")
	ErrMissContentLength  = errors.New("缺少 Content-Length 报头")
)

一些错误定义

Types

type Conn

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

Conn JSON RPC 连接对象

json-rpc 客户端和服务端是对等的，两者都使用 conn 初始化。

func (*Conn) Notify

func (conn *Conn) Notify(method string, in interface{}) error

Notify 发送通知信息

仅发送 in 至服务端，会忽略服务端返回的信息。

func (*Conn) Send

func (conn *Conn) Send(method string, in, out interface{}) error

Send 发送请求内容

发送数据 in 至服务，并获取返回的内容填充至 out。

func (*Conn) Serve

func (conn *Conn) Serve(ctx context.Context) error

Serve 作为服务端运行

t 表示的是传输层的实例； ctx 可以用于中断当前的服务。但是需要注意，可能会被 Transport.Read 阻塞而无法退出， 所以在调用 cancel 之后，可能还需要向 Conn 发送一条任意指令才行。

type Error

type Error struct {
	// 错误代码
	Code int `json:"code"`

	// 错误的简短描述
	Message string `json:"message"`

	// 详细的错误描述信息，可以为空
	Data interface{} `json:"data,omitempty"`
}

Error JSON-RPC 返回的错误类型

func NewError

func NewError(code int, msg string) *Error

NewError 新的 Error 对象

func NewErrorWithData

func NewErrorWithData(code int, msg string, data interface{}) *Error

NewErrorWithData 新的 Error 对象

func (*Error) Error

func (err *Error) Error() string

type HTTPConn

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

HTTPConn 表示 json rpc 的 HTTP 服务端中间件

func (*HTTPConn) Notify

func (h *HTTPConn) Notify(method string, params interface{}) error

Notify 请求 JSON RPC 服务端

func (*HTTPConn) Send

func (h *HTTPConn) Send(method string, params, result interface{}) error

Send 请求 JSON RPC 服务端

func (*HTTPConn) ServeHTTP

func (h *HTTPConn) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Server

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

Server JSON RPC 服务实例

func NewServer

func NewServer() *Server

NewServer 新的 Server 实例

func (*Server) Exists

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

Exists 是否已经存在相同的方法名

func (*Server) NewConn

func (s *Server) NewConn(t Transport, errlog *log.Logger) *Conn

NewConn 创建长链接的 JSON RPC 实例

t 表示传输层的操作实例； errlog 表示在 serveHTTP 和 Serve 中部分不会中断执行的错误输出。 如果为空，则不会输出这些错误。

func (*Server) NewHTTPConn

func (s *Server) NewHTTPConn(url string, errlog *log.Logger) *HTTPConn

NewHTTPConn 声明 HTTP 服务端中间件

url 表示主动请求时的 URL 地址，如果不需要，可以传递空值； errlog 表示错误日志输出通道，不需要可以为空。

func (*Server) Register

func (s *Server) Register(method string, f interface{}) bool

Register 注册一个新的服务

f 为处理服务的函数，其原型为以下方式：

func(notify bool, params, result pointer) error

其中 notify 表示是否为通知类型的请求；params 为用户请求的对象； result 为返回给用户的数据对象；error 则为处理出错是的返回值。 params 和 result 必须为指针类型。

返回值表示是否添加成功，在已经存在相同值时，会添加失败。

NOTE: 如果 f 的签名不正确，则会直接 panic

func (*Server) RegisterBefore

func (s *Server) RegisterBefore(f func(method string) error)

RegisterBefore 注册 Before 函数

f 的原型如下：

func(method string)(err error)

method RPC 服务名； 如果返回错误值，则会退出 RPC 调用，返回错误尽量采用 *Error 类型；

NOTE: 如果多次调用，仅最后次启作用。

func (*Server) Registers

func (s *Server) Registers(methods map[string]interface{})

Registers 注册多个服务方法

如果已经存在相同的方法名，则会直接 panic

type Transport

type Transport interface {
	// 从转输层读取内容并转换成对象 v
	//
	// 如果返回的是 *Error 类型的错误，则直接将该错误信息反馈给客户端，
	// 如果是普通错误，则统一转换成 CodeParseError 传递给客户端。
	Read(v interface{}) error

	// 将对象 v 写入传输层
	//
	// 如果返回的是 *Error 类型的错误，则直接将该错误信息反馈给客户端，
	// 如果是普通错误，则错误代码不确定。
	Write(v interface{}) error

	Close() error
}

Transport 用于操作 JSON RPC 的传输层接口

func NewSocketTransport

func NewSocketTransport(header bool, conn net.Conn) Transport

NewSocketTransport 声明基于 socket 的 Transport 实例

HTTP 和 websocket 有专门的实现方法

func NewStreamTransport

func NewStreamTransport(header bool, in io.Reader, out io.Writer, close func() error) Transport

NewStreamTransport 返回基于流的 Transport 实例

header 是否需要解析报头内容； close 指定了关闭 in 和 out 的函数，如果不需要关闭，则可以传递 nil 值。

func NewWebsocketTransport

func NewWebsocketTransport(conn *websocket.Conn) Transport

NewWebsocketTransport 声明基于 websocket 的 Transport 实例