jsonrpc2

README

jsonrpc2

Package jsonrpc2 is an implementation of the JSON-RPC 2 specification for Go.

Documentation

Overview

Package jsonrpc2 is an implementation of the JSON-RPC 2 specification for Go.

Index

• Constants
• type Code
• type Combined
• type Conn
  • func NewConn(s Stream, options ...Options) *Conn
  • func (c *Conn) AddHandler(handler Handler)
  • 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) Run(ctx context.Context) error
• type Direction
  • func (d Direction) String() string
• type Error
  • func Errorf(c Code, format string, args ...interface{}) *Error
  • func NewError(c Code, message string) *Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type Handler
• type ID
  • func (id *ID) MarshalJSON() ([]byte, error)
  • func (id *ID) String() string
  • func (id *ID) UnmarshalJSON(data []byte) error
• type Interface
• type Options
  • func WithHandlers(hs ...Handler) Options
  • func WithLogger(logger *zap.Logger) Options
• type Request
  • func (r *Request) Conn() *Conn
  • func (r *Request) IsNotify() bool
  • func (r *Request) Parallel()
  • func (r *Request) Reply(ctx context.Context, result interface{}, reqErr error) error
• type Stream
  • func NewStream(in io.Reader, out io.Writer) Stream
• type WireRequest
• type WireResponse

Constants

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

const (
	// ContentTypeJSONRPC is the custom mime type content for the Language Server Protocol.
	ContentTypeJSONRPC = "application/jsonrpc; charset=utf-8"

	// ContentTypeVSCodeJSONRPC is the default mime type content for the Language Server Protocol Specification.
	ContentTypeVSCodeJSONRPC = "application/vscode-jsonrpc; charset=utf-8"
)

const (
	// HeaderContentLength is the HTTP header name of the length of the content part in bytes. This header is required.
	// This entity header indicates the size of the entity-body, in bytes, sent to the recipient.
	//
	// RFC 7230, section 3.3.2: Content-Length:
	//  https://tools.ietf.org/html/rfc7230#section-3.3.2
	HeaderContentLength = "Content-Length"

	// HeaderContentType is the mime type of the content part. Defaults to "application/vscode-jsonrpc; charset=utf-8".
	// This entity header is used to indicate the media type of the resource.
	//
	// RFC 7231, section 3.1.1.5: Content-Type:
	//  https://tools.ietf.org/html/rfc7231#section-3.1.1.5
	HeaderContentType = "Content-Type"

	// HeaderContentSeparator is the header and content part separator.
	HeaderContentSeparator = "\r\n"
)

const Version = "2.0"

Version represents a JSON-RPC version.

Types

type Code

type Code int64

Code represents a error's category.

const (
	// ParseError is the invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.
	ParseError Code = -32700

	// InvalidRequest is the JSON sent is not a valid Request object.
	InvalidRequest Code = -32600

	// MethodNotFound is the method does not exist / is not available.
	MethodNotFound Code = -32601

	// InvalidParams is the invalid method parameter(s).
	InvalidParams Code = -32602

	// InternalError is the internal JSON-RPC error.
	InternalError Code = -32603

	// ServerNotInitialized is the error of server not initialized.
	ServerNotInitialized Code = -32002

	// UnknownError should be used for all non coded errors.
	UnknownError Code = -32001

	// RequestCancelled is the cancellation error.
	//
	// Defined by the Language Server Protocol.
	RequestCancelled Code = -32800

	// ContentModified is the state change that invalidates the result of a request in execution.
	//
	// Defined by the Language Server Protocol.
	ContentModified Code = -32801

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

type Combined

type Combined struct {
	JSONRPC string           `json:"jsonrpc"`
	ID      *ID              `json:"id,omitempty"`
	Method  string           `json:"method"`
	Params  *json.RawMessage `json:"params,omitempty"`
	Result  *json.RawMessage `json:"result,omitempty"`
	Error   *Error           `json:"error,omitempty"`
}

Combined represents a all the fields of both Request and Response. We can decode this and then work out which it is.

type Conn

type Conn struct {
	// 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, options ...Options) *Conn

NewConn creates a new connection object that reads and writes messages from the supplied stream and dispatches incoming messages to the supplied handler.

func (*Conn) AddHandler

func (c *Conn) AddHandler(handler Handler)

AddHandler adds a new handler to the set the connection will invoke. Handlers are invoked in the reverse order of how they were added, this allows the most recent addition to be the first one to attempt to handle a message.

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.

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.

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 a number indicating the error type that occurred.
	Code Code `json:"code"`

	// Message a string providing a short description of the error.
	Message string `json:"message"`

	// Data a Primitive or Structured value that contains additional
	// information about the error. Can be omitted.
	Data *json.RawMessage `json:"data"`
}

Error represents a jsonrpc2 error.

func Errorf

func Errorf(c Code, format string, args ...interface{}) *Error

Errorf builds a Error struct for the suppied code, format and args.

func NewError

func NewError(c Code, message string) *Error

NewError builds a Error struct for the suppied code and message.

func (*Error) Error

func (e *Error) Error() string

Error implements error.Error.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap implements errors.Unwrap.

Returns the error underlying the receiver, which may be nil.

type Handler

type Handler interface {
	// Deliver is invoked 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.
	// If Deliver returns true all subsequent handlers will be invoked with
	// delivered set to true, and should not attempt to deliver the message.
	Deliver(ctx context.Context, r *Request, delivered bool) bool

	// Cancel is invoked for canceled outgoing requests.
	// It is okay to use the connection to send notifications, but the context will
	// be in the canceled state, so you must do it with the background context
	// instead.
	// If Cancel returns true all subsequent handlers will be invoked with
	// canceled set to true, and should not attempt to cancel the message.
	Cancel(ctx context.Context, conn *Conn, id ID, canceled bool) bool

	// Request is called near the start of processing any request.
	Request(ctx context.Context, conn *Conn, direction Direction, r *WireRequest) context.Context

	// Response is called near the start of processing any response.
	Response(ctx context.Context, conn *Conn, direction Direction, r *WireResponse) context.Context

	// Done is called when any request is fully processed.
	// For calls, this means the response has also been processed, for notifies
	// this is as soon as the message has been written to the stream.
	// If err is set, it implies the request failed.
	Done(ctx context.Context, err error)

	// Read is called with a count each time some data is read from the stream.
	// The read calls are delayed until after the data has been interpreted so
	// that it can be attributed to a request/response.
	Read(ctx context.Context, n int64) context.Context

	// Write is called each time some data is written to the stream.
	Write(ctx context.Context, n int64) context.Context

	// Error is called with errors that cannot be delivered through the normal
	// mechanisms, for instance a failure to process a notify cannot be delivered
	// back to the other party.
	Error(ctx context.Context, err error)
}

Handler is the interface used to hook into the message handling of an rpc connection.

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)

MarshalJSON implements json.Marshaler.

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

UnmarshalJSON implements json.Unmarshaler.

type Interface

type Interface interface {
	Cancel(id ID)
	Notify(ctx context.Context, method string, params interface{}) (err error)
	Call(ctx context.Context, method string, params, result interface{}) (err error)
	Run(ctx context.Context) (err error)
}

Interface represents an interface for issuing requests that speak the JSON-RPC 2 protocol.

type Options

type Options func(*Conn)

Options represents a functional options.

func WithHandlers

func WithHandlers(hs ...Handler) Options

WithHandlers apply custom hander to Conn.

func WithLogger

func WithLogger(logger *zap.Logger) Options

WithLogger apply custom Logger to Conn.

type Request

type Request struct {
	WireRequest
	// contains filtered or unexported fields
}

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

func (*Request) Conn

func (r *Request) Conn() *Conn

Conn returns the connection that created this request.

func (*Request) IsNotify

func (r *Request) IsNotify() bool

IsNotify returns true if this request is a notification.

func (*Request) Parallel

func (r *Request) Parallel()

Parallel indicates that the system is now allowed to process other requests in parallel with this one. It is safe to call any number of times, but must only be called from the request handling go routine. It is implied by both reply and by the handler returning.

func (*Request) Reply

func (r *Request) Reply(ctx context.Context, result interface{}, reqErr error) error

Reply sends a reply to the given request.

type Stream

type Stream interface {
	// Read gets the next message from the stream.
	Read(ctx context.Context) (data []byte, n int64, err error)

	// Write sends a message to the stream.
	Write(ctx context.Context, data []byte) (n int64, err error)
}

Stream abstracts the transport mechanics from the JSON-RPC protocol.

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 HTTP content length and MIME type headers. This is the format used by LSP and others.

type WireRequest

type WireRequest struct {
	// JSONRPC is always encoded as the string "2.0"
	JSONRPC string `json:"jsonrpc"`

	// Method is a string containing the method name to invoke.
	//
	// Method names that begin with the word rpc followed by a period character (U+002E or ASCII 46) are reserved
	// for rpc-internal methods and extensions and MUST NOT be used for anything else.
	Method string `json:"method"`

	// Params is either a struct or an array with the parameters of the method.
	Params *json.RawMessage `json:"params,omitempty"`

	// ID is 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"`
}

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

type WireResponse

type WireResponse struct {
	// JSONRPC is always encoded as the string "2.0"
	JSONRPC string `json:"jsonrpc"`

	// Result is the response value, and is required on success.
	// This member MUST NOT exist if there was an error invoking the method.
	//
	// The value of this member is determined by the method invoked on the Server.
	Result *json.RawMessage `json:"result,omitempty"`

	// Error is the object in case a request fails., and is required on error.
	// This member MUST NOT exist if there was no error triggered during invocation.
	//
	// The value for this member MUST be an Object.
	Error *Error `json:"error,omitempty"`

	// ID is the request id.
	//
	// ID must be set and is the identifier of the Request this is a response to.
	//
	// It MUST be the same as the value of the id member in the Request Object.
	// If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request), it MUST be Null.
	ID *ID `json:"id,omitempty"`
}

WireResponse 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.