jsonrpc

Documentation

Overview

Package jsonrpc implements a JSONRPC2.0 compliant server as described in https://www.jsonrpc.org/specification

Index

• Constants
• Variables
• type Conn
  • func ConnFromContext(ctx context.Context) (Conn, bool)
• type ConnKey
• type Error
  • func Err(code int, data any) *Error
  • func (e *Error) CloneWithData(data any) *Error
• type EventListener
• type HTTP
  • func NewHTTP(rpc *Server, log utils.SimpleLogger) *HTTP
  • func (h *HTTP) ServeHTTP(writer http.ResponseWriter, req *http.Request)
  • func (h *HTTP) WithListener(listener NewRequestListener) *HTTP
• type Method
• type NewRequestListener
• type Parameter
• type Request
• type SelectiveListener
  • func (l *SelectiveListener) OnNewRequest(method string)
  • func (l *SelectiveListener) OnRequestFailed(method string, data any)
  • func (l *SelectiveListener) OnRequestHandled(method string, took time.Duration)
• type Server
  • func NewServer(poolMaxGoroutines int, log utils.SimpleLogger) *Server
  • func (s *Server) HandleReadWriter(ctx context.Context, rw io.ReadWriter) error
  • func (s *Server) HandleReader(ctx context.Context, reader io.Reader) ([]byte, http.Header, error)
  • func (s *Server) RegisterMethods(methods ...Method) error
  • func (s *Server) WithListener(listener EventListener) *Server
  • func (s *Server) WithValidator(validator Validator) *Server
• type Validator
• type Websocket
  • func NewWebsocket(rpc *Server, log utils.SimpleLogger) *Websocket
  • func (ws *Websocket) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (ws *Websocket) WithConnParams(p *WebsocketConnParams) *Websocket
  • func (ws *Websocket) WithListener(listener NewRequestListener) *Websocket
• type WebsocketConnParams
  • func DefaultWebsocketConnParams() *WebsocketConnParams

Constants

const (
	InvalidJSON    = -32700 // Invalid JSON was received by the server.
	InvalidRequest = -32600 // The JSON sent is not a valid Request object.
	MethodNotFound = -32601 // The method does not exist / is not available.
	InvalidParams  = -32602 // Invalid method parameter(s).
	InternalError  = -32603 // Internal JSON-RPC error.
)

const MaxRequestBodySize = 10 * utils.Megabyte

Variables

var (
	ErrInvalidID = errors.New("id should be a string or an integer")
)

Types

type Conn

type Conn interface {
	io.Writer
	Equal(Conn) bool
}

func ConnFromContext

func ConnFromContext(ctx context.Context) (Conn, bool)

ConnFromContext returns a writable connection. The connection should be written in a separate goroutine, since writes from handlers are blocked until the initial response is sent.

type ConnKey

type ConnKey struct{}

ConnKey the key used to retrieve the connection from the context passed to a handler. It is exported to allow transports to set it manually if they decide not to use HandleReadWriter, which sets it automatically. Manually setting the connection can be especially useful when testing handlers.

type Error

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

func Err

func Err(code int, data any) *Error

func (*Error) CloneWithData

func (e *Error) CloneWithData(data any) *Error

CloneWithData copies the error and sets the data field on the copy

type EventListener

type EventListener interface {
	NewRequestListener
	OnRequestHandled(method string, took time.Duration)
	OnRequestFailed(method string, data any)
}

type HTTP

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

func NewHTTP

func NewHTTP(rpc *Server, log utils.SimpleLogger) *HTTP

func (*HTTP) ServeHTTP

func (h *HTTP) ServeHTTP(writer http.ResponseWriter, req *http.Request)

ServeHTTP processes an incoming HTTP request

func (*HTTP) WithListener

func (h *HTTP) WithListener(listener NewRequestListener) *HTTP

WithListener registers a NewRequestListener

type Method

type Method struct {
	Name    string
	Params  []Parameter
	Handler any
	// contains filtered or unexported fields
}

type NewRequestListener

type NewRequestListener interface {
	OnNewRequest(method string)
}

type Parameter

type Parameter struct {
	Name     string
	Optional bool
}

type Request

type Request struct {
	Version string `json:"jsonrpc"`
	Method  string `json:"method"`
	Params  any    `json:"params,omitempty"`
	ID      any    `json:"id,omitempty"`
}

type SelectiveListener

type SelectiveListener struct {
	OnNewRequestCb     func(method string)
	OnRequestHandledCb func(method string, took time.Duration)
	OnRequestFailedCb  func(method string, data any)
}

func (*SelectiveListener) OnNewRequest

func (l *SelectiveListener) OnNewRequest(method string)

func (*SelectiveListener) OnRequestFailed

func (l *SelectiveListener) OnRequestFailed(method string, data any)

func (*SelectiveListener) OnRequestHandled

func (l *SelectiveListener) OnRequestHandled(method string, took time.Duration)

type Server

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

func NewServer

func NewServer(poolMaxGoroutines int, log utils.SimpleLogger) *Server

NewServer instantiates a JSONRPC server

func (*Server) HandleReadWriter

func (s *Server) HandleReadWriter(ctx context.Context, rw io.ReadWriter) error

HandleReadWriter permits methods to send messages on the connection after the server sends the initial response. rw must permit concurrent writes. A non-nil error indicates the initial response could not be sent, and that no method will be able to write the connection.

func (*Server) HandleReader

func (s *Server) HandleReader(ctx context.Context, reader io.Reader) ([]byte, http.Header, error)

HandleReader processes a request to the server It returns the response in a byte array, only returns an error if it can not create the response byte array

func (*Server) RegisterMethods

func (s *Server) RegisterMethods(methods ...Method) error

RegisterMethods verifies and creates an endpoint that the server recognises.

- name is the method name - handler is the function to be called when a request is received for the associated method. It should have (any, *jsonrpc.Error) as its return type - paramNames are the names of parameters in the order that they are expected by the handler

func (*Server) WithListener

func (s *Server) WithListener(listener EventListener) *Server

WithListener registers an EventListener

func (*Server) WithValidator

func (s *Server) WithValidator(validator Validator) *Server

WithValidator registers a validator to validate handler struct arguments

type Validator

type Validator interface {
	Struct(any) error
}

type Websocket

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

func NewWebsocket

func NewWebsocket(rpc *Server, log utils.SimpleLogger) *Websocket

func (*Websocket) ServeHTTP

func (ws *Websocket) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP processes an HTTP request and upgrades it to a websocket connection. The connection's entire "lifetime" is spent in this function.

func (*Websocket) WithConnParams

func (ws *Websocket) WithConnParams(p *WebsocketConnParams) *Websocket

WithConnParams sanity checks and applies the provided params.

func (*Websocket) WithListener

func (ws *Websocket) WithListener(listener NewRequestListener) *Websocket

WithListener registers a NewRequestListener

type WebsocketConnParams

type WebsocketConnParams struct {
	// Maximum message size allowed.
	ReadLimit int64
	// Maximum time to write a message.
	WriteDuration time.Duration
}

func DefaultWebsocketConnParams

func DefaultWebsocketConnParams() *WebsocketConnParams