jsonrpc

README

jsonrpc

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

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

Socket

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

HTTP

conn := NewConn(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 NewConn(errlog *log.Logger) *Conn
  • func (conn *Conn) Notify(t Transport, method string, in interface{}) error
  • func (conn *Conn) Register(method string, f interface{}) bool
  • func (conn *Conn) Send(t Transport, method string, in, out interface{}) error
  • func (conn *Conn) Serve(ctx context.Context, t Transport) error
  • func (conn *Conn) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Error
  • func NewError(code int, msg string) *Error
  • func NewErrorWithData(code int, msg string, data interface{}) *Error
  • func (err *Error) Error() string
• type HTTPClient
  • func NewHTTPClient(path string) *HTTPClient
  • func (client *HTTPClient) Notify(method string, params interface{}) error
  • func (client *HTTPClient) Request(method string, params, result interface{}) error
• type Transport
  • func NewHTTPTransport(w http.ResponseWriter, r *http.Request) Transport
  • func NewSocketTransport(conn net.Conn) 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 (
	ErrInvalidContentType = errors.New("无效的报头 Content-Type")
	ErrMissContentLength  = errors.New("缺少 Content-Length 报头")
)

一些错误定义

Types

type Conn

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

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

func NewConn

func NewConn(errlog *log.Logger) *Conn

NewConn 声明新的 Conn 实例

errlog 表示在 serveHTTP 和 Serve 中部分不会中断执行的错误输出。 如果为空，则不会输出这些错误。

func (*Conn) Notify

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

Notify 发送通知信息

func (*Conn) Register

func (conn *Conn) Register(method string, f interface{}) bool

Register 注册一个新的服务

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

func(notify bool, params, result pointer) error

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

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

func (*Conn) Send

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

Send 发送请求内容，并获取其返回的数据

func (*Conn) Serve

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

Serve 作为服务端运行

t 表示的是传输层的实例； ctx 可以用于中断当前的服务。但是需要注意，t 的 Read 和 Write 也有可能会阻塞整个服务，想要让 ctx 的取消启作用，还必须要有一定的机制从 Transport 中退出。

func (*Conn) ServeHTTP

func (conn *Conn) ServeHTTP(w http.ResponseWriter, r *http.Request)

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 HTTPClient

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

HTTPClient http 的客户端

func NewHTTPClient

func NewHTTPClient(path string) *HTTPClient

NewHTTPClient 声明新的 HTTPClient 对象

func (*HTTPClient) Notify

func (client *HTTPClient) Notify(method string, params interface{}) error

Notify 请求 JSON RPC 服务端

func (*HTTPClient) Request

func (client *HTTPClient) Request(method string, params, result interface{}) error

Request 请求 JSON RPC 服务端

type Transport

type Transport interface {
	// 从转输层读取内容并转换成对象 v
	Read(v interface{}) error

	// 将对象 v 写入传输层
	Write(v interface{}) error
}

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

func NewHTTPTransport

func NewHTTPTransport(w http.ResponseWriter, r *http.Request) Transport

NewHTTPTransport 声明基于 HTTP 的 Transport 实例

https://www.simple-is-better.org/json-rpc/transport_http.html

func NewSocketTransport

func NewSocketTransport(conn net.Conn) Transport

NewSocketTransport 声明基于网络通讯的 Transport 实例

HTTP 和 websocket 有专门的实现方法

func NewWebsocketTransport

func NewWebsocketTransport(conn *websocket.Conn) Transport

NewWebsocketTransport 声明基于 websocket 的 Transport 实例