jsonrpc

Documentation

Overview

Package jsonrpc defines the types required by JSON-RPC 2.0 servers and clients.

For the Kwil RPC services, the following are also defined here:

• Known method names.
• The shared objects used in request parameters and response. These types are the JSON-RPC "schema".
• Error codes and structured error data objects.

Index

• type Error
  • func NewError(code ErrorCode, message string, data json.RawMessage) *Error
  • func (e Error) Error() string
• type ErrorCode
• type Method
• type Request
  • func NewRequest(id any, method string, params json.RawMessage) *Request
• type Response
  • func NewErrorResponse(id any, rpcErr *Error) *Response
  • func NewResponse(id any, result any) (*Response, error)

Types

type Error

type Error struct {
	// Code is an integer error code. Values on [-32768,-32000] are reserved by
	// JSON-RPC 2.0, but any other values may be used.
	Code ErrorCode `json:"code"`
	// Message is a "A String providing a short description of the error."
	Message string `json:"message"`
	// Data is "a Primitive or Structured value that contains additional
	// information about the error. This may be omitted. The value of this
	// member is defined by the Server (e.g. detailed error information, nested
	// errors etc.). The requester may attempt to unmarshal into the expected
	// detailed error type for the method.
	Data json.RawMessage `json:"data,omitempty"`
}

Error is the "error" object defined by JSON-RPC 2.0

func NewError

func NewError(code ErrorCode, message string, data json.RawMessage) *Error

NewError constructs a new error.

func (Error) Error

func (e Error) Error() string

Error satisfies the Go error interface.

type ErrorCode

type ErrorCode int32

const (
	// JSON-RPC 2.0 spec errors
	ErrorParse          ErrorCode = -32700 // Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.
	ErrorInternal       ErrorCode = -32603 // Internal JSON-RPC error.
	ErrorInvalidParams  ErrorCode = -32602 // Invalid method parameter(s).
	ErrorUnknownMethod  ErrorCode = -32601 // The method does not exist / is not available
	ErrorInvalidRequest ErrorCode = -32600 // The JSON sent is not a valid Request object

	// ErrorResultEncoding is when the application handles the request without
	// error, but a result structure fails to encode to JSON.
	ErrorResultEncoding ErrorCode = -32000
	ErrorTimeout        ErrorCode = -32001

	ErrorTxInternal       ErrorCode = -200 // any issue from txApp, cometbft, etc. in handling a tx
	ErrorTxExecFailure    ErrorCode = -201 // txCode != transactions.CodeOk
	ErrorTxNotFound       ErrorCode = -202 // abci.ErrTxNotFound
	ErrorTxPayloadInvalid ErrorCode = -203

	ErrorEngineInternal        ErrorCode = -300
	ErrorEngineDatasetNotFound ErrorCode = -301
	ErrorEngineDatasetExists   ErrorCode = -302
	ErrorEngineInvalidSchema   ErrorCode = -303

	ErrorDBInternal ErrorCode = -400

	ErrorAccountInternal ErrorCode = -500

	ErrorIdentInternal ErrorCode = -600
	ErrorIdentInvalid  ErrorCode = -601

	ErrorNodeInternal ErrorCode = -700

	ErrorValidatorsInternal ErrorCode = -800
	ErrorValidatorNotFound  ErrorCode = -801

	// reserve -900 to -999 for the KGW
	ErrorKGWInternal         ErrorCode = -900
	ErrorKGWNotAuthorized    ErrorCode = -901
	ErrorKGWInvalidPayload   ErrorCode = -902
	ErrorKGWNotAllowed       ErrorCode = -903
	ErrorKGWNotFound         ErrorCode = -904
	ErrorKGWTooManyRequests  ErrorCode = -905
	ErrorKGWMethodNotAllowed ErrorCode = -906
)

type Method

type Method string

Method is a type used for all recognized JSON-RPC method names.

type Request

type Request struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      any             `json:"id,omitempty"` // int, string, null
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params"` // object in 2.0, array in 1.0
}

Request is the "request" object defined by JSON-RPC 2.0. The Params field may be either named (and object) or positional (an array). The initial implementation of the server will support named only.

func NewRequest

func NewRequest(id any, method string, params json.RawMessage) *Request

NewRequest creates a new Request for certain method given the structured request parameters struct marshalled to JSON. The id is permitted to be a string or numeric.

type Response

type Response struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      any             `json:"id,omitempty"`
	Result  json.RawMessage `json:"result,omitempty"` // object, marshalled by handler
	Error   *Error          `json:"error,omitempty"`
}

Response is the "response" object defined by JSON-RPC 2.0. The "result" field is required on success, and may be any shape determined by the method. Either the "response" or "error" field are expected to be set.

func NewErrorResponse

func NewErrorResponse(id any, rpcErr *Error) *Response

NewErrorResponse constructs a new Response for a request ID and Error.

func NewResponse

func NewResponse(id any, result any) (*Response, error)

NewResponse encodes the result and creates a Response.