jsonrpc2

package module
v0.0.0-...-2d47ceb Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 8, 2024 License: BSD-3-Clause Imports: 17 Imported by: 2

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

View Source 
const (
	Inbound  = "in"
	Outbound = "out"
)

Variables

View Source 
var (
	Started       = event.NewCounter("started", &event.MetricOptions{Description: "Count of started RPCs."})
	Finished      = event.NewCounter("finished", &event.MetricOptions{Description: "Count of finished RPCs (includes error)."})
	ReceivedBytes = event.NewIntDistribution("received_bytes", &event.MetricOptions{
		Description: "Bytes received.",
		Unit:        event.UnitBytes,
	})
	SentBytes = event.NewIntDistribution("sent_bytes", &event.MetricOptions{
		Description: "Bytes sent.",
		Unit:        event.UnitBytes,
	})
	Latency = event.NewDuration("latency", &event.MetricOptions{
		Description: "Elapsed time of an RPC.",
		Unit:        event.UnitMilliseconds,
	})
)
View Source 
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")
)
View Source 
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 

func EncodeMessage(msg Message) ([]byte, error)

func Method 

func Method(v string) event.Label

func NewError 

func NewError(code int64, message string) error

NewError returns an error that will encode on the wire correctly. The standard codes are made available from this package, this function should only be used to build errors for application specific codes as allowed by the specification.

func RPCDirection 

func RPCDirection(v string) event.Label

func RPCID 

func RPCID(v string) event.Label

func StatusCode 

func StatusCode(v string) event.Label

Types

type AsyncCall 

type AsyncCall struct {
	// contains filtered or unexported fields
}

func (*AsyncCall) Await 

func (a *AsyncCall) Await(ctx context.Context, result interface{}) error

Await the results of a Call. The response will be unmarshaled from JSON into the result.

func (*AsyncCall) ID 

func (a *AsyncCall) ID() ID

ID used for this call. This can be used to cancel the call if needed.

func (*AsyncCall) IsReady 

func (a *AsyncCall) IsReady() bool

IsReady can be used to check if the result is already prepared. This is guaranteed to return true on a result for which Await has already returned, or a call that failed to send in the first place.

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 

func Dial(ctx context.Context, dialer Dialer, binder Binder) (*Connection, error)

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.

func NetDialer 

func NetDialer(network, address string, nd net.Dialer) Dialer

NetDialer returns a Dialer using the supplied standard network dialer.

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.

func RawFramer 

func RawFramer() Framer

RawFramer returns a new Framer. The messages are sent with no wrapping, and rely on json decode consistency to determine message boundaries.

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 HandlerFunc func(ctx context.Context, req *Request) (interface{}, error)

func (HandlerFunc) Handle 

func (f HandlerFunc) Handle(ctx context.Context, req *Request) (interface{}, error)

type ID 

type ID struct {
	// contains filtered or unexported fields
}

ID is a Request identifier.

func Int64ID 

func Int64ID(i int64) ID

Int64ID creates a new integer request identifier.

func StringID 

func StringID(s string) ID

StringID creates a new string request identifier.

func (ID) IsValid 

func (id ID) IsValid() bool

IsValid returns true if the ID is a valid identifier. The default value for ID will return false.

func (ID) Raw 

func (id ID) Raw() interface{}

Raw returns the underlying value of the ID.

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 listens on a socket using the net package.

func NetPipe 

func NetPipe(ctx context.Context) (Listener, error)

NetPipe 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 returned from the Accept call.

func NewIdleListener 

func NewIdleListener(timeout time.Duration, wrap Listener) Listener

NewIdleListener wraps a listener with an idle timeout. When there are no active connections for at least the timeout duration a call to accept will fail with ErrIdleTimeout.

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 

func DecodeMessage(data []byte) (Message, error)

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 NewCall 

func NewCall(id ID, method string, params interface{}) (*Request, error)

NewCall constructs a new Call message for the supplied ID, method and parameters.

func NewNotification 

func NewNotification(method string, params interface{}) (*Request, error)

NewNotification constructs a new Notification message for the supplied method and parameters.

func (*Request) IsCall 

func (msg *Request) IsCall() bool

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.

func NewResponse 

func NewResponse(id ID, result interface{}, rerr error) (*Response, error)

NewResponse constructs a new Response message that is a reply to the supplied. If err is set result may be ignored.

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server is a running server that is accepting incoming connections.

func Serve 

func Serve(ctx context.Context, listener Listener, binder Binder) (*Server, error)

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.

func (*Server) Wait 

func (s *Server) Wait() error

Wait returns only when the server has shut down.

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

View all Source files

Directories

Path Synopsis
internal
stack
Package stack provides support for parsing standard goroutine stack traces.
 Package stack provides support for parsing standard goroutine stack traces.
stack/gostacks
The gostacks command processes stdin looking for things that look like stack traces and simplifying them to make the log more readable.
 The gostacks command processes stdin looking for things that look like stack traces and simplifying them to make the log more readable.
stack/stacktest

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.