jsonrpc2

Documentation

Index

• Constants
• func Call[Result, ErrorData, Params any](ctx context.Context, conn *Conn, method string, params Params) (Result, error)
• func Notify[Params any](ctx context.Context, conn *Conn, method string, params Params) error
• func RegisterHandler[Params, Result any](c *Conn, method string, h Handler[Params, Result])
• type Conn
  • func NewConnection(transport transport.Session, opts ...ConnectionInitializationOption) *Conn
  • func (c *Conn) Call(ctx context.Context, id ID, method string, params any, result any) error
  • func (c *Conn) Close() error
  • func (c *Conn) Notify(ctx context.Context, method string, params any) error
  • func (c *Conn) Open() error
  • func (c *Conn) Serve(ctx context.Context) error
• type ConnectionInitializationOption
  • func WithHandler[Params, Result any](method string, h Handler[Params, Result]) ConnectionInitializationOption
  • func WithHandlerFunc[Params, Result any](method string, h HandlerFunc[Params, Result]) ConnectionInitializationOption
  • func WithLogger(logger *slog.Logger) ConnectionInitializationOption
• type Error
  • func NewError[Data any](code int, message string, data Data) Error[Data]
  • func (e Error[Data]) Error() string
• type Handler
• type HandlerFunc
  • func (f HandlerFunc[Params, Result]) HandleRequest(ctx context.Context, req Params) (Result, error)
• type ID
  • func NewID[T interface{ ... }](v T) ID
  • func (id ID) IsNull() bool
  • func (id ID) MarshalJSON() ([]byte, error)
  • func (id ID) String() string
  • func (id *ID) UnmarshalJSON(data []byte) error
• type Method
• type Request
  • func (r *Request[Params]) MarshalJSON() ([]byte, error)
  • func (r *Request[Params]) UnmarshalJSON(data []byte) error
• type Response
  • func (r *Response[Result, ErrorData]) MarshalJSON() ([]byte, error)
  • func (r *Response[Result, ErrorData]) UnmarshalJSON(data []byte) error

Constants

const (
	CodeParseError     = -32700
	CodeInvalidRequest = -32600
	CodeMethodNotFound = -32601
	CodeInvalidParams  = -32602
	CodeInternalError  = -32603
)

Functions

func Call

func Call[Result, ErrorData, Params any](ctx context.Context, conn *Conn, method string, params Params) (Result, error)

Call sends a request to the server and waits for a response. Call returns the result and an error if the request fails. When the result is unsuccessful, the error `jsonrpc2.Error[ErrorData]` type.

func Notify

func Notify[Params any](ctx context.Context, conn *Conn, method string, params Params) error

Notify sends a notification to the server. Notify returns an error if the request fails.

func RegisterHandler

func RegisterHandler[Params, Result any](c *Conn, method string, h Handler[Params, Result])

RegisterHandler registers a request handler.

Types

type Conn

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

Conn represents a JSON-RPC 2.0 connection.

func NewConnection

func NewConnection(transport transport.Session, opts ...ConnectionInitializationOption) *Conn

NewConnection creates a new JSON-RPC 2.0 connection.

func (*Conn) Call

func (c *Conn) Call(ctx context.Context, id ID, method string, params any, result any) error

Call sends a request to the server and waits for a response.

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection. Any blocked Call will return with an error. It is safe to call Close multiple times. Close will return nil if the connection is already closed. Close will return an error if the connection is not closed cleanly. Close closes the underlying reader and writer if they implement io.Closer.

func (*Conn) Notify

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

Notify sends a notification to the server.

func (*Conn) Open

func (c *Conn) Open() error

Open opens the connection. Open returns an error if the connection is already closed. Open starts message processing in a new goroutine.

func (*Conn) Serve

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

Serve starts serving requests. Serve will return an error if the connection is closed.

type ConnectionInitializationOption

type ConnectionInitializationOption func(*Conn)

ConnectionInitializationOption represents a JSON-RPC 2.0 connection initialization option.

func WithHandler

func WithHandler[Params, Result any](method string, h Handler[Params, Result]) ConnectionInitializationOption

WithHandler registers a request handler.

func WithHandlerFunc

func WithHandlerFunc[Params, Result any](method string, h HandlerFunc[Params, Result]) ConnectionInitializationOption

WithHandlerFunc registers a request handler function.

func WithLogger

func WithLogger(logger *slog.Logger) ConnectionInitializationOption

WithLogger sets a logger for the connection.

type Error

type Error[Data any] struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    Data   `json:"data,omitempty,omitzero"`
}

Error represents a JSON-RPC 2.0 error. The error object must contain a code and a message. The error object may contain data.

func NewError

func NewError[Data any](code int, message string, data Data) Error[Data]

NewError creates a new JSON-RPC 2.0 error.

func (Error[Data]) Error

func (e Error[Data]) Error() string

Error implements the error interface.

type Handler

type Handler[Params, Result any] interface {
	HandleRequest(ctx context.Context, req Params) (Result, error)
}

Handler represents a JSON-RPC 2.0 request handler.

type HandlerFunc

type HandlerFunc[Params, Result any] func(ctx context.Context, req Params) (Result, error)

HandlerFunc represents a JSON-RPC 2.0 request handler function.

func (HandlerFunc[Params, Result]) HandleRequest

func (f HandlerFunc[Params, Result]) HandleRequest(ctx context.Context, req Params) (Result, error)

HandleRequest calls f(ctx, req).

type ID

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

ID represents a JSON-RPC 2.0 request ID. The ID can be a string, number, or null. If the ID is a string, it must be unique. If the ID is a number, it must be an integer. If the ID is null, the request is a notification.

func NewID

func NewID[T interface {
	string | int | int8 | int16 | int32 | int64 | uint | uint8 | uint16 | uint32 | uint64 | json.Number
}](v T) ID

NewID creates a new ID from a string or an integer.

func (ID) IsNull

func (id ID) IsNull() bool

IsNull returns true if the ID is null.

func (ID) MarshalJSON

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

MarshalJSON implements the json.Marshaler interface.

func (ID) String

func (id ID) String() string

String returns the ID as a string. If the ID is an integer, it is converted to a string. If the ID is null, it returns an empty string.

func (*ID) UnmarshalJSON

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

UnmarshalJSON implements the json.Unmarshaler interface.

type Method

type Method string

Method represents a JSON-RPC 2.0 request method.

type Request

type Request[Params any] struct {
	ID     ID     `json:"id,omitzero"`
	Method Method `json:"method"`
	Params Params `json:"params,omitempty"`
}

Request represents a JSON-RPC 2.0 request. The request object must contain a method. The request object may contain an ID. The request object may contain parameters.

func (*Request[Params]) MarshalJSON

func (r *Request[Params]) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*Request[Params]) UnmarshalJSON

func (r *Request[Params]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

type Response

type Response[Result, ErrorData any] struct {
	ID     ID               `json:"id,omitzero"`
	Result Result           `json:"result,omitempty,omitzero"`
	Error  Error[ErrorData] `json:"error,omitzero"`
}

Response represents a JSON-RPC 2.0 response. The response object must contain a unique ID. The response object may contain a result or an error.

func (*Response[Result, ErrorData]) MarshalJSON

func (r *Response[Result, ErrorData]) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*Response[Result, ErrorData]) UnmarshalJSON

func (r *Response[Result, ErrorData]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.