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 ListenAndServe(ctx context.Context, network, addr string, server StreamServer, ...) error
- func MethodNotFound(ctx context.Context, r *Request) error
- func Serve(ctx context.Context, ln net.Listener, server StreamServer, ...) error
- type Conn
- type Error
- type Handler
- type ID
- type Request
- type ServerFunc
- type Stream
- type StreamServer
- type VersionTag
- type WireRequest
- type WireResponse
Constants ¶
const ( // ErrIdleTimeout is returned when serving timed out waiting for new connections. ErrIdleTimeout = constError("timed out waiting for new connections") // ErrDisconnected signals that the stream or connection exited normally. ErrDisconnected = constError("disconnected") )
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 )
Variables ¶
This section is empty.
Functions ¶
func ListenAndServe ¶
func ListenAndServe(ctx context.Context, network, addr string, server StreamServer, idleTimeout time.Duration) error
ListenAndServe starts an jsonrpc2 server on the given address. If idleTimeout is non-zero, ListenAndServe exits after there are no clients for this duration, otherwise it exits only on error.
func MethodNotFound ¶
MethodNotFound is a Handler that replies to all call requests with the standard method not found response. This should normally be the final handler in a chain.
func Serve ¶
func Serve(ctx context.Context, ln net.Listener, server StreamServer, idleTimeout time.Duration) error
Serve accepts incoming connections from the network, and handles them using the provided server. If idleTimeout is non-zero, ListenAndServe exits after there are no clients for this duration, otherwise it exits only on error.
Types ¶
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 ¶
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{}) (_ ID, err 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) Notify ¶
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.
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.
type Handler ¶
Handler 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. The handler should return ErrNotHandled if it could not handle the request.
func AsyncHandler ¶
AsyncHandler returns a handler that processes each request goes in its own goroutine. The handler returns immediately, without the request being processed. Each request then waits for the previous request to finish before it starts. This allows the stream to unblock at the cost of unbounded goroutines all stalled on the previous one.
func CancelHandler ¶
CancelHandler returns a handler that supports cancellation, and a function that can be used to trigger canceling in progress requests.
type ID ¶
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) Format ¶
Format writes the ID to the formatter. If the rune is q the representation is non ambiguous, string forms are quoted, number forms are preceded by a #
func (*ID) MarshalJSON ¶
func (*ID) UnmarshalJSON ¶
type Request ¶
type Request struct { // The Wire values of the request. WireRequest // contains filtered or unexported fields }
Request is sent to a server to represent a Call or Notify operaton.
func (*Request) OnReply ¶
func (r *Request) OnReply(do func())
OnReply adds a done callback to the request. All added callbacks are invoked during the one required call to Reply, and then dropped. It is an error to call this after Reply. This call is not safe for concurrent use, but should only be invoked by handlers and in general only one handler should be working on a request at any time.
type ServerFunc ¶
The ServerFunc type is an adapter that implements the StreamServer interface using an ordinary function.
func (ServerFunc) ServeStream ¶
func (f ServerFunc) ServeStream(ctx context.Context, s Stream) error
ServeStream calls f(ctx, s).
type Stream ¶
type Stream interface { // Read gets the next message from the stream. // It is never called concurrently. Read(context.Context) ([]byte, int64, error) // Write sends a message to the stream. // It must be safe for concurrent use. Write(context.Context, []byte) (int64, 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 ¶
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.
type StreamServer ¶
A StreamServer is used to serve incoming jsonrpc2 clients communicating over a newly created stream.
func HandlerServer ¶
func HandlerServer(h Handler) StreamServer
HandlerServer returns a StreamServer that handles incoming streams using the provided handler.
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
type WireRequest ¶
type WireRequest 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"` }
WireRequest is sent to a server to represent a Call or Notify operaton.
type WireResponse ¶
type WireResponse 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"` }
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.
Directories ¶
Path | Synopsis |
---|---|
Package servertest provides utilities for running tests against a remote LSP server.
|
Package servertest provides utilities for running tests against a remote LSP server. |