jsonrpc2

Documentation

Overview

Package jsonrpc2 is a minimal implementation of the JSON RPC 2 spec. https://www.jsonrpc.org/specification It is intended to be compatible with other implementations at the wire level.

Index

• Constants
• func Log(direction Direction, id *ID, elapsed time.Duration, method string, ...)
• type Canceler
• type Conn
  • func NewConn(s Stream) *Conn
  • func (c *Conn) Call(ctx context.Context, method string, params, result interface{}) error
  • func (c *Conn) Cancel(id ID)
  • func (c *Conn) Notify(ctx context.Context, method string, params interface{}) error
  • func (c *Conn) Reply(ctx context.Context, req *Request, result interface{}, err error) error
  • func (c *Conn) Run(ctx context.Context) error
• type Direction
  • func (d Direction) String() string
• type Error
  • func NewErrorf(code int64, format string, args ...interface{}) *Error
  • func (err *Error) Error() string
• type Handler
• type ID
  • func (id *ID) MarshalJSON() ([]byte, error)
  • func (id *ID) String() string
  • func (id *ID) UnmarshalJSON(data []byte) error
• type Logger
• type Request
  • func (r *Request) IsNotify() bool
• type Response
• type Stream
  • func NewHeaderStream(in io.Reader, out io.Writer) Stream
  • func NewStream(in io.Reader, out io.Writer) Stream
• type VersionTag
  • func (VersionTag) MarshalJSON() ([]byte, error)
  • func (VersionTag) UnmarshalJSON(data []byte) error

Constants

const (
	// Send indicates the message is outgoing.
	Send = Direction(true)
	// Receive indicates the message is incoming.
	Receive = Direction(false)
)

const (
	// CodeUnknownError should be used for all non coded errors.
	CodeUnknownError = -32001
	// CodeParseError is used when invalid JSON was received by the server.
	CodeParseError = -32700
	//CodeInvalidRequest is used when the JSON sent is not a valid Request object.
	CodeInvalidRequest = -32600
	// CodeMethodNotFound should be returned by the handler when the method does
	// not exist / is not available.
	CodeMethodNotFound = -32601
	// CodeInvalidParams should be returned by the handler when method
	// parameter(s) were invalid.
	CodeInvalidParams = -32602
	// CodeInternalError is not currently returned but defined for completeness.
	CodeInternalError = -32603

	//CodeServerOverloaded is returned when a message was refused due to a
	//server being temporarily unable to accept any new messages.
	CodeServerOverloaded = -32000
)

Functions

func Log

func Log(direction Direction, id *ID, elapsed time.Duration, method string, payload *json.RawMessage, err *Error)

Log is an implementation of Logger that outputs using log.Print It is not used by default, but is provided for easy logging in users code.

Types

type Canceler

type Canceler func(context.Context, *Conn, *Request)

Canceler is an option you can pass to NewConn which is invoked for cancelled outgoing requests. The request will have the ID filled in, which can be used to propagate the cancel to the other process if needed. It is okay to use the connection to send notifications, but the context will be in the cancelled state, so you must do it with the background context instead.

type Conn

type Conn struct {
	Handler            Handler
	Canceler           Canceler
	Logger             Logger
	Capacity           int
	RejectIfOverloaded bool
	// contains filtered or unexported fields
}

Conn is a JSON RPC 2 client server connection. Conn is bidirectional; it does not have a designated server or client end.

func NewConn

func NewConn(s Stream) *Conn

NewConn creates a new connection object around the supplied stream. You must call Run for the connection to be active.

func (*Conn) Call

func (c *Conn) Call(ctx context.Context, method string, params, result interface{}) error

Call sends a request over the connection and then waits for a response. If the response is not an error, it will be decoded into result. result must be of a type you an pass to json.Unmarshal.

func (*Conn) Cancel

func (c *Conn) Cancel(id ID)

Cancel cancels a pending Call on the server side. The call is identified by its id. JSON RPC 2 does not specify a cancel message, so cancellation support is not directly wired in. This method allows a higher level protocol to choose how to propagate the cancel.

func (*Conn) Notify

func (c *Conn) Notify(ctx context.Context, method string, params interface{}) error

Notify is called to send a notification request over the connection. It will return as soon as the notification has been sent, as no response is possible.

func (*Conn) Reply

func (c *Conn) Reply(ctx context.Context, req *Request, result interface{}, err error) error

Reply sends a reply to the given request. It is an error to call this if request was not a call. You must call this exactly once for any given request. If err is set then result will be ignored.

func (*Conn) Run

func (c *Conn) Run(ctx context.Context) error

Run blocks until the connection is terminated, and returns any error that caused the termination. It must be called exactly once for each Conn. It returns only when the reader is closed or there is an error in the stream.

type Direction

type Direction bool

Direction is used to indicate to a logger whether the logged message was being sent or received.

func (Direction) String

func (d Direction) String() string

type Error

type Error struct {
	// Code is an error code indicating the type of failure.
	Code int64 `json:"code"`
	// Message is a short description of the error.
	Message string `json:"message"`
	// Data is optional structured data containing additional information about the error.
	Data *json.RawMessage `json:"data"`
}

Error represents a structured error in a Response.

func NewErrorf

func NewErrorf(code int64, format string, args ...interface{}) *Error

NewErrorf builds a Error struct for the suppied message and code. If args is not empty, message and args will be passed to Sprintf.

func (*Error) Error

func (err *Error) Error() string

type Handler

type Handler func(context.Context, *Conn, *Request)

Handler is an option you can pass to NewConn to handle incoming requests. If the request returns false from IsNotify then the Handler must eventually call Reply on the Conn with the supplied request. Handlers are called synchronously, they should pass the work off to a go routine if they are going to take a long time.

type ID

type ID struct {
	Name   string
	Number int64
}

ID is a Request identifier. Only one of either the Name or Number members will be set, using the number form if the Name is the empty string.

func (*ID) MarshalJSON

func (id *ID) MarshalJSON() ([]byte, error)

func (*ID) String

func (id *ID) String() string

String returns a string representation of the ID. The representation is non ambiguous, string forms are quoted, number forms are preceded by a #

func (*ID) UnmarshalJSON

func (id *ID) UnmarshalJSON(data []byte) error

type Logger

type Logger = func(direction Direction, id *ID, elapsed time.Duration, method string, payload *json.RawMessage, err *Error)

Logger is an option you can pass to NewConn which is invoked for all messages flowing through a Conn. direction indicates if the message being recieved or sent id is the message id, if not set it was a notification elapsed is the time between a call being seen and the response, and is negative for anything that is not a response. method is the method name specified in the message payload is the parameters for a call or notification, and the result for a response

type Request

type Request struct {
	// VersionTag is always encoded as the string "2.0"
	VersionTag VersionTag `json:"jsonrpc"`
	// Method is a string containing the method name to invoke.
	Method string `json:"method"`
	// Params is either a struct or an array with the parameters of the method.
	Params *json.RawMessage `json:"params,omitempty"`
	// The id of this request, used to tie the Response back to the request.
	// Will be either a string or a number. If not set, the Request is a notify,
	// and no response is possible.
	ID *ID `json:"id,omitempty"`
}

Request is sent to a server to represent a Call or Notify operaton.

func (*Request) IsNotify

func (r *Request) IsNotify() bool

IsNotify returns true if this request is a notification.

type Response

type Response struct {
	// VersionTag is always encoded as the string "2.0"
	VersionTag VersionTag `json:"jsonrpc"`
	// Result is the response value, and is required on success.
	Result *json.RawMessage `json:"result,omitempty"`
	// Error is a structured error response if the call fails.
	Error *Error `json:"error,omitempty"`
	// ID must be set and is the identifier of the Request this is a response to.
	ID *ID `json:"id,omitempty"`
}

Response is a reply to a Request. It will always have the ID field set to tie it back to a request, and will have either the Result or Error fields set depending on whether it is a success or failure response.

type Stream

type Stream interface {
	// Read gets the next message from the stream.
	// It is never called concurrently.
	Read(context.Context) ([]byte, error)
	// Write sends a message to the stream.
	// It must be safe for concurrent use.
	Write(context.Context, []byte) error
}

Stream abstracts the transport mechanics from the JSON RPC protocol. A Conn reads and writes messages using the stream it was provided on construction, and assumes that each call to Read or Write fully transfers a single message, or returns an error.

func NewHeaderStream

func NewHeaderStream(in io.Reader, out io.Writer) Stream

NewHeaderStream returns a Stream built on top of an io.Reader and io.Writer The messages are sent with HTTP content length and MIME type headers. This is the format used by LSP and others.

func NewStream

func NewStream(in io.Reader, out io.Writer) Stream

NewStream returns a Stream built on top of an io.Reader and io.Writer The messages are sent with no wrapping, and rely on json decode consistency to determine message boundaries.

type VersionTag

type VersionTag struct{}

VersionTag is a special 0 sized struct that encodes as the jsonrpc version tag. It will fail during decode if it is not the correct version tag in the stream.

func (VersionTag) MarshalJSON

func (VersionTag) MarshalJSON() ([]byte, error)

func (VersionTag) UnmarshalJSON

func (VersionTag) UnmarshalJSON(data []byte) error