jsonrpc: github.com/chowey/jsonrpc Index | Files

package jsonrpc

import "github.com/chowey/jsonrpc"

Package jsonrpc implements the JSON-RPC 2.0 specification over HTTP.

Regular functions can be registered to a Handler and then called using standard JSON-RPC 2.0 semantics. The only limitations on functions are as follows:

- the first parameter may be a context.Context
- the remaining parameters must be able to unmarshal from JSON
- return values must be (optionally) a value and (optionally) an error
- if there is a return value, it must be able to marshal as JSON

Here is a simple example of a JSON-RPC 2.0 command that echos its input:

h := jsonrpc.NewHandler()
h.RegisterMethod("echo", func (in string) string { return in })
http.ListenAndServe(":8080", h)

You would call this over HTTP with standard JSON-RPC 2.0 semantics:

=> {"jsonrpc": "2.0", "id": 1, "method": "echo", "params": ["Hello world!"]}
<= {"jsonrpc": "2.0", "id": 1, "result": "Hello world!"}

As a convenience, structs may also be registered to a Handler. In this case, each method of the struct is registered using the method "Type.Method". For example:

type Echo struct{}

func (Echo) Echo(s string) string {
	return s
}

func main() {
	e := &Echo{}
	h := jsonrpc.NewHandler()
	h.Register(e)
	http.ListenAndServe(":8080", h)
}

Then you would call this over HTTP as follows:

=> {"jsonrpc": "2.0", "id": 1, "method": "Echo.Echo", "params": ["Hello world!"]}
<= {"jsonrpc": "2.0", "id": 1, "result": "Hello world!"}

As a further convenience, you may pass in one or more structs into the NewHandler constructor. For example:

http.ListenAndServe(":8080", jsonrpc.NewHandler(&Echo{}))

Index

Package Files

jsonrpc.go

Constants

const (
    StatusParseError     = -32700 // Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.
    StatusInvalidRequest = -32600 // The JSON sent is not a valid Request object.
    StatusMethodNotFound = -32601 // The method does not exist / is not available.
    StatusInvalidParams  = -32602 // Invalid method parameter(s).
    StatusInternalError  = -32603 // Internal JSON-RPC error.
)

JSON-RPC 2.0 reserved status codes.

type Encoder Uses

type Encoder interface {
    Encode(v interface{}) error
}

Encoder is something that can encode into JSON. By default it is a json.Encoder

type Error Uses

type Error struct {
    Code    int         `json:"code"`
    Message string      `json:"message"`
    Data    interface{} `json:"data"`
}

Error represents a JSON-RPC 2.0 error. If an Error is returned from a registered function, it will be sent directly to the client.

func (*Error) Error Uses

func (err *Error) Error() string

type Handler Uses

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

Handler is an http.Handler that responds to JSON-RPC 2.0 requests.

func NewHandler Uses

func NewHandler(rcvrs ...interface{}) *Handler

NewHandler initializes a new Handler. If receivers are provided, they will be registered.

func (*Handler) Register Uses

func (h *Handler) Register(rcvr interface{})

Register is a convenience function. It will call RegisterMethod on each method of the provided receiver. The registered method name will follow the pattern "Type.Method".

func (*Handler) RegisterMethod Uses

func (h *Handler) RegisterMethod(name string, fn interface{})

RegisterMethod registers a method under the given name. Methods must be valid functions with the following restrictions:

- the first parameter may be a context.Context
- the remaining parameters must be able to unmarshal from JSON
- return values must be (optionally) a value and (optionally) an error
- if there is a return value, it must be able to marshal as JSON

If the first parameter is a context.Context, then it will receive the context from the HTTP request.

func (*Handler) ServeConn Uses

func (h *Handler) ServeConn(ctx context.Context, rw io.ReadWriter)

ServeConn provides JSON-RPC over any bi-directional stream.

func (*Handler) ServeHTTP Uses

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

func (*Handler) SetEncoderFactory Uses

func (h *Handler) SetEncoderFactory(fn func(w io.Writer) Encoder)

SetEncoderFactory configures what encoder will be loaded for sending JSON-RPC responses. By default the Handler will use json.NewEncoder.

Package jsonrpc imports 9 packages (graph). Updated 2020-02-14. Refresh now. Tools for package owners.