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 ¶
- Variables
- func EncodeMessage(msg Message) ([]byte, error)
- func NewError(code int64, message string) error
- type AsyncCall
- type Binder
- type Connection
- func (c *Connection) Call(ctx context.Context, method string, params interface{}) *AsyncCall
- func (c *Connection) Cancel(id ID)
- func (c *Connection) Close() error
- func (c *Connection) Notify(ctx context.Context, method string, params interface{}) error
- func (c *Connection) Respond(id ID, result interface{}, rerr error) error
- func (c *Connection) Wait() error
- type ConnectionOptions
- type Dialer
- type Framer
- type Handler
- type HandlerFunc
- type ID
- type Listener
- type Message
- type NetListenOptions
- type Preempter
- type Reader
- type Request
- type Response
- type Server
- type Writer
Constants ¶
This section is empty.
Variables ¶
var ( // ErrIdleTimeout is returned when serving timed out waiting for new connections. ErrIdleTimeout = errors.New("timed out waiting for new connections") // ErrNotHandled is returned from a handler to indicate it did not handle the // message. ErrNotHandled = errors.New("JSON RPC not handled") // ErrAsyncResponse is returned from a handler to indicate it will generate a // response asynchronously. ErrAsyncResponse = errors.New("JSON RPC asynchronous response") )
var ( // ErrUnknown should be used for all non coded errors. ErrUnknown = NewError(-32001, "JSON RPC unknown error") // ErrParse is used when invalid JSON was received by the server. ErrParse = NewError(-32700, "JSON RPC parse error") // ErrInvalidRequest is used when the JSON sent is not a valid Request object. ErrInvalidRequest = NewError(-32600, "JSON RPC invalid request") // ErrMethodNotFound should be returned by the handler when the method does // not exist / is not available. ErrMethodNotFound = NewError(-32601, "JSON RPC method not found") // ErrInvalidParams should be returned by the handler when method // parameter(s) were invalid. ErrInvalidParams = NewError(-32602, "JSON RPC invalid params") // ErrInternal indicates a failure to process a call correctly ErrInternal = NewError(-32603, "JSON RPC internal error") // ErrServerOverloaded is returned when a message was refused due to a // server being temporarily unable to accept any new messages. ErrServerOverloaded = NewError(-32000, "JSON RPC overloaded") )
Functions ¶
func EncodeMessage ¶
Types ¶
type AsyncCall ¶
type AsyncCall struct {
// contains filtered or unexported fields
}
func (*AsyncCall) Await ¶
Await the results of a Call. The response will be unmarshaled from JSON into the result.
type Binder ¶
type Binder interface {
// Bind is invoked when creating a new connection.
// The connection is not ready to use when Bind is called.
Bind(context.Context, *Connection) (ConnectionOptions, error)
}
Binder builds a connection configuration. This may be used in servers to generate a new configuration per connection. ConnectionOptions itself implements Binder returning itself unmodified, to allow for the simple cases where no per connection information is needed.
type Connection ¶
type Connection struct {
// contains filtered or unexported fields
}
Connection manages the jsonrpc2 protocol, connecting responses back to their calls. Connection is bidirectional; it does not have a designated server or client end.
func Dial ¶
Dial uses the dialer to make a new connection, wraps the returned reader and writer using the framer to make a stream, and then builds a connection on top of that stream using the binder.
func (*Connection) Call ¶
func (c *Connection) Call(ctx context.Context, method string, params interface{}) *AsyncCall
Call invokes the target method and returns an object that can be used to await the response. The params will be marshaled to JSON before sending over the wire, and will be handed to the method invoked. You do not have to wait for the response, it can just be ignored if not needed. If sending the call failed, the response will be ready and have the error in it.
func (*Connection) Cancel ¶
func (c *Connection) Cancel(id ID)
Cancel is used to cancel an inbound message by ID, it does not cancel outgoing messages. This is only used inside a message handler that is layering a cancellation protocol on top of JSON RPC 2. It will not complain if the ID is not a currently active message, and it will not cause any messages that have not arrived yet with that ID to be cancelled.
func (*Connection) Close ¶
func (c *Connection) Close() error
Close can be used to close the underlying stream, and then wait for the connection to fully shut down. This does not cancel in flight requests, but waits for them to gracefully complete.
func (*Connection) Notify ¶
func (c *Connection) Notify(ctx context.Context, method string, params interface{}) error
Notify invokes the target method but does not wait for a response. The params will be marshaled to JSON before sending over the wire, and will be handed to the method invoked.
func (*Connection) Respond ¶
func (c *Connection) Respond(id ID, result interface{}, rerr error) error
Respond deliverers a response to an incoming Call. It is an error to not call this exactly once for any message for which a handler has previously returned ErrAsyncResponse. It is also an error to call this for any other message.
func (*Connection) Wait ¶
func (c *Connection) Wait() error
Wait blocks until the connection is fully closed, but does not close it.
type ConnectionOptions ¶
type ConnectionOptions struct {
// Framer allows control over the message framing and encoding.
// If nil, HeaderFramer will be used.
Framer Framer
// Preempter allows registration of a pre-queue message handler.
// If nil, no messages will be preempted.
Preempter Preempter
// Handler is used as the queued message handler for inbound messages.
// If nil, all responses will be ErrNotHandled.
Handler Handler
}
ConnectionOptions holds the options for new connections.
func (ConnectionOptions) Bind ¶
func (o ConnectionOptions) Bind(context.Context, *Connection) (ConnectionOptions, error)
Bind returns the options unmodified.
type Dialer ¶
type Dialer interface {
// Dial returns a new communication byte stream to a listening server.
Dial(ctx context.Context) (io.ReadWriteCloser, error)
}
Dialer is used by clients to dial a server.
type Framer ¶
type Framer interface {
// Reader wraps a byte reader into a message reader.
Reader(rw io.Reader) Reader
// Writer wraps a byte writer into a message writer.
Writer(rw io.Writer) Writer
}
Framer wraps low level byte readers and writers into jsonrpc2 message readers and writers. It is responsible for the framing and encoding of messages into wire form.
func HeaderFramer ¶
func HeaderFramer() Framer
HeaderFramer returns a new Framer. The messages are sent with HTTP content length and MIME type headers. This is the format used by LSP and others.
type Handler ¶
type Handler interface {
// Handle is invoked for each incoming request.
// If the request is a call, it must return a value or an error for the reply.
Handle(ctx context.Context, req *Request) (interface{}, error)
}
Handler handles messages on a connection.
type HandlerFunc ¶
type ID ¶
type ID struct {
// contains filtered or unexported fields
}
ID is a Request identifier.
type Listener ¶
type Listener interface {
// Accept an inbound connection to a server.
// It must block until an inbound connection is made, or the listener is
// shut down.
Accept(context.Context) (io.ReadWriteCloser, error)
// Close is used to ask a listener to stop accepting new connections.
Close() error
// Dialer returns a dialer that can be used to connect to this listener
// locally.
// If a listener does not implement this it will return a nil.
Dialer() Dialer
}
Listener is implemented by protocols to accept new inbound connections.
func NetListener ¶
func NetListener(ctx context.Context, network, address string, options NetListenOptions) (Listener, error)
NetListener returns a new Listener that listents on a socket using the net package.
func NetPipeListener ¶
NetPipeListener returns a new Listener that listens using net.Pipe. It is only possibly to connect to it using the Dialier returned by the Dialer method, each call to that method will generate a new pipe the other side of which will be returnd from the Accept call.
type Message ¶
type Message interface {
// contains filtered or unexported methods
}
Message is the interface to all jsonrpc2 message types. They share no common functionality, but are a closed set of concrete types that are allowed to implement this interface. The message types are *Request and *Response.
func DecodeMessage ¶
type NetListenOptions ¶
type NetListenOptions struct {
NetListenConfig net.ListenConfig
NetDialer net.Dialer
}
NetListenOptions is the optional arguments to the NetListen function.
type Preempter ¶
type Preempter interface {
// Preempt is invoked for each incoming request before it is queued.
// If the request is a call, it must return a value or an error for the reply.
// Preempt should not block or start any new messages on the connection.
Preempt(ctx context.Context, req *Request) (interface{}, error)
}
Preempter handles messages on a connection before they are queued to the main handler. Primarily this is used for cancel handlers or notifications for which out of order processing is not an issue.
type Reader ¶
type Reader interface {
// Read gets the next message from the stream.
Read(context.Context) (Message, int64, error)
}
Reader abstracts the transport mechanics from the JSON RPC protocol. A Conn reads messages from the reader it was provided on construction, and assumes that each call to Read fully transfers a single message, or returns an error. A reader is not safe for concurrent use, it is expected it will be used by a single Conn in a safe manner.
type Request ¶
type Request struct {
// ID of this request, used to tie the Response back to the request.
// This will be nil for notifications.
ID ID
// Method is a string containing the method name to invoke.
Method string
// Params is either a struct or an array with the parameters of the method.
Params json.RawMessage
}
Request is a Message sent to a peer to request behavior. If it has an ID it is a call, otherwise it is a notification.
func NewNotification ¶
NewNotification constructs a new Notification message for the supplied method and parameters.
type Response ¶
type Response struct {
// result is the content of the response.
Result json.RawMessage
// err is set only if the call failed.
Error error
// id of the request this is a response to.
ID ID
}
Response is a Message used as a reply to a call Request. It will have the same ID as the call it is a response to.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is a running server that is accepting incoming connections.
func Serve ¶
Serve starts a new server listening for incoming connections and returns it. This returns a fully running and connected server, it does not block on the listener. You can call Wait to block on the server, or Shutdown to get the sever to terminate gracefully. To notice incoming connections, use an intercepting Binder.
type Writer ¶
type Writer interface {
// Write sends a message to the stream.
Write(context.Context, Message) (int64, error)
}
Writer abstracts the transport mechanics from the JSON RPC protocol. A Conn writes messages using the writer it was provided on construction, and assumes that each call to Write fully transfers a single message, or returns an error. A writer is not safe for concurrent use, it is expected it will be used by a single Conn in a safe manner.
Source Files