jsonrpc2

type BatchClient ¶ added in v1.0.0

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

BatchClient is the raw-frame batch client mode.

It exposes only frame primitives so batch-mode callers can write a complete JSON-RPC batch array and read the response frame without passing through the single-message Conn.Call API. The supplied Stream must be frame-capable; the built-in framers satisfy this requirement.

func NewBatchClient(stream Stream) (*BatchClient, error)

func (c *BatchClient) Close() error

func (c *BatchClient) ReadFrame(ctx context.Context) (data []byte, n int64, err error)

func (c *BatchClient) WriteFrame(ctx context.Context, data []byte) (int64, error)

type BatchServer ¶ added in v1.0.0

type BatchServer struct {
	Conn
}

BatchServer is the batch-capable server endpoint mode.

It names the existing Conn batch dispatch path explicitly. New batch-only server APIs can grow behind this type without changing single-client or peer constructors.

func NewBatchServer(stream Stream, opts ...Option) *BatchServer

type Call ¶ added in v0.7.0

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

Call is a request that expects a Response. The response carries a matching ID.

func NewCall(id ID, method string, params RawMessage) *Call

func (c *Call) ID() ID

func (c *Call) Method() string

func (c *Call) Params() RawMessage

type Code ¶

type Code int32

Code is an error code as defined by the JSON-RPC 2.0 specification.

See https://www.jsonrpc.org/specification#error_object for details.

const (
	// ParseError indicates that invalid JSON was received by the server, or that
	// an error occurred on the server while parsing the JSON text.
	ParseError Code = -32700

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

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

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

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

	// JSONRPCReservedErrorRangeStart is the start of the JSON-RPC reserved error
	// code range.
	//
	// It does not denote a real error code. No LSP error codes should be defined
	// between the start and end of the range. For backwards compatibility the
	// ServerNotInitialized and UnknownError codes are left in the range.
	//
	// @since 3.16.0.
	JSONRPCReservedErrorRangeStart Code = -32099

	// CodeServerErrorStart is reserved for implementation-defined server errors.
	//
	// Deprecated: Use JSONRPCReservedErrorRangeStart instead.
	CodeServerErrorStart = JSONRPCReservedErrorRangeStart

	// ServerNotInitialized indicates that the server has not been initialized.
	ServerNotInitialized Code = -32002

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

	// JSONRPCReservedErrorRangeEnd is the end of the JSON-RPC reserved error code
	// range.
	//
	// It does not denote a real error code.
	//
	// @since 3.16.0.
	JSONRPCReservedErrorRangeEnd Code = -32000

	// CodeServerErrorEnd is reserved for implementation-defined server errors.
	//
	// Deprecated: Use JSONRPCReservedErrorRangeEnd instead.
	CodeServerErrorEnd = JSONRPCReservedErrorRangeEnd
)

type Codec ¶ added in v1.0.0

type Codec interface {
	// Marshal encodes v into its JSON representation. A nil v encodes to the JSON
	// null literal. A [RawMessage] value is returned verbatim.
	Marshal(v any) ([]byte, error)

	// Unmarshal decodes the JSON in data into the value pointed to by v. When v is
	// a *RawMessage the bytes are copied verbatim into a slice the caller owns.
	Unmarshal(data []byte, v any) error
}

Codec marshals and unmarshals the user payloads of a JSON-RPC message: the "params" of a request and the "result" of a response. The envelope itself is never routed through a Codec; only the user-controlled payload is.

Implementations must be safe for concurrent use, must not escape HTML-sensitive characters (to match a json.Encoder with SetEscapeHTML(false)), and must treat a RawMessage (or encoding/json.RawMessage) as an opaque, already-encoded value that is passed through verbatim without re-encoding.

var DefaultCodec Codec = JSONCodec{}

type Conn ¶

type Conn interface {
	// Call invokes method on the peer and waits for the response.
	//
	// params is marshaled with the connection's [Codec] before being sent; a nil
	// params sends no parameters. The response result is unmarshaled into result,
	// which may be nil to discard it. The returned [ID] is unique to this
	// connection and is the id under which the call was sent.
	//
	// Call returns the error response sent by the peer, the local marshaling or
	// write error, or ctx.Err() if ctx is canceled before the response arrives.
	Call(ctx context.Context, method string, params, result any) (ID, error)

	// Notify invokes method on the peer without waiting for a response.
	//
	// params is marshaled with the connection's [Codec]; a nil params sends no
	// parameters.
	Notify(ctx context.Context, method string, params any) error

	// Go starts the connection's read goroutine, dispatching incoming requests
	// to handler. It must be called exactly once per Conn and returns
	// immediately; block on [Conn.Done] to wait for the connection to
	// terminate.
	//
	// Dispatch is direct-return: handler's return values become the response,
	// no per-request reply machinery is allocated, and the request is a pooled
	// concrete value whose method and params are borrowed from the transport
	// frame, valid until the handler returns (see [Handler] for the lifetime
	// contract and [Request.Clone] for retention).
	//
	// By default a request handler runs inline on the read goroutine, so
	// handlers observe requests in wire order and the next message is not read
	// until the current handler returns. A handler that wants to overlap later
	// requests (for example a long-running call, or a server that issues calls
	// back to the peer) must release itself with [Async] or be wrapped with
	// [AsyncHandler]; otherwise a handler that issues a server-initiated
	// [Conn.Call] back into this same connection deadlocks the read goroutine,
	// because the response to that call cannot be read while the read goroutine
	// is blocked running the handler. A server-initiated [Conn.Notify] needs no
	// release, since it never waits for a response. See [Handler] for the full
	// reentrancy contract.
	//
	// [Conn.Close] is the authoritative teardown. Canceling ctx is observed only
	// between frames: the read loop checks ctx before it starts the next frame, so
	// a cancellation requests a graceful stop at the next frame boundary, but a
	// reader already blocked mid-frame (waiting on the peer) is not interrupted by
	// ctx-cancel. Close, by contrast, closes the underlying stream and so unblocks
	// a reader parked in the middle of a frame. To guarantee prompt termination,
	// call Close rather than relying on ctx cancellation. A termination caused by
	// canceling ctx is treated as a clean shutdown and is not reported by
	// [Conn.Err].
	Go(ctx context.Context, handler Handler)

	// Close stops accepting new work, waits for in-flight calls and handlers to
	// drain, closes the underlying stream, and blocks until the connection has
	// fully terminated (the read goroutine has exited). It reports the stream's
	// close error. After Close returns, [Conn.Done] is already closed.
	Close() error

	// Done returns a channel that is closed when the connection has fully
	// terminated: the read goroutine has exited and all in-flight work has
	// drained.
	Done() <-chan struct{}

	// Err reports the error that terminated the connection, or nil if it was
	// closed cleanly. A clean end of stream ([io.EOF]) is reported as nil.
	Err() error
}

Conn is the common interface to JSON-RPC clients and servers.

Conn is bidirectional: it has no designated server or client end. It manages the JSON-RPC 2.0 protocol on top of a Stream, correlating responses back to the calls that produced them and dispatching incoming requests to a Handler.

A Conn is created with NewConn and driven by a single read goroutine that is started by Conn.Go. The same Conn may be used concurrently for outgoing Conn.Call and Conn.Notify from many goroutines.

func NewConn(stream Stream, opts ...Option) Conn

type Error ¶

type Error struct {
	// Message is a short description of the error.
	Message string `json:"message"`

	// Data is an optional primitive or structured value that carries additional
	// information about the error. It is omitted from the wire form when the
	// zero value.
	Data RawMessage `json:"data,omitzero"`

	// Code is a number indicating the error type that occurred.
	Code Code `json:"code"`
}

Error is the wire representation of a JSON-RPC error object.

It is the structured value carried in the "error" member of a Response. It implements the error interface so that a handler can return it directly, and it preserves its Code across the error<->wire mapping performed by [toWireError].

func Errorf(c Code, format string, args ...any) *Error

func NewError(c Code, message string) *Error

func (e *Error) Error() string

func (e *Error) Is(target error) bool

type ErrorView ¶ added in v1.0.0

type ErrorView struct {
	// Raw is the borrowed raw error-object span.
	Raw []byte

	CodeRaw []byte

	// MessageRaw is the borrowed raw string value span, including quotes.
	// MessageBytes is the borrowed unquoted string body. When MessageEscaped is
	// true, MessageBytes contains raw escaped body bytes.
	MessageRaw   []byte
	MessageBytes []byte

	// Data is the borrowed raw "data" value span, or nil when absent or null.
	Data []byte

	Code           Code
	MessageEscaped bool
}

ErrorView is a zero-copy view of a JSON-RPC error object.

func (e *ErrorView) MessageString() (string, bool)

func (e *ErrorView) Owned() (*Error, bool)

type FrameView ¶ added in v1.0.0

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

FrameView is a view of one framed JSON-RPC body.

A FrameView returned by ScanFrameView borrows the frame slice passed to it: Bytes and every byte slice reachable from MessageView alias that slice. The borrowed view is valid only until the caller mutates/reuses the frame, the stream performs the next read into the same storage, or a callback that received the view returns. Call Clone before retaining a FrameView beyond that lifetime.

A FrameView returned by NewFrameView or FrameView.Clone owns a private copy of the frame, so its borrowed spans remain valid for the FrameView's lifetime.

func NewFrameView(frame []byte) (FrameView, error)

func ScanFrameView(frame []byte) (FrameView, error)

func (v *FrameView) Bytes() []byte

func (v *FrameView) Clone() (FrameView, error)

func (v *FrameView) MessageView() MessageView

func (v *FrameView) OwnsFrame() bool

type Framer ¶ added in v0.7.0

type Framer func(conn io.ReadWriteCloser) Stream

Framer adapts a byte-oriented connection into a message-oriented Stream by supplying the wire framing. The same Framer value can wrap many connections.

type Handler ¶

type Handler func(ctx context.Context, req *Request) (result any, err error)

Handler is invoked to handle an incoming Request. It is the direct-return handler shape: the returned result (or error) becomes the call's response, so dispatch needs no per-request reply machinery. To answer a call with a JSON-RPC error, return that error (an *Error is sent verbatim; any other error is wrapped). For a notification the result is discarded and a non-nil error fails the connection.

Lifetime contract: req, its Method, and its Params are valid only until the handler returns; the request struct is pooled and recycled afterward. The three legal retention patterns are:

1. Copy what you need before returning (unmarshal params, copy the method).
2. Take Request.Clone and retain the owned clone.
3. Release with Async, which clones the request in place automatically; the request then remains valid until the (now concurrent) handler returns.

The per-request ctx likewise dies with the handler; use DetachContext for work that outlives it. Builds tagged jsonrpc2poison scribble recycled requests so violations fail loudly in tests.

Reentrancy and the deadlock-avoidance contract: in the synchronous case a Handler runs inline on the connection's read loop, which is blocked until the handler returns or releases itself. Because a Conn is symmetric, a handler may call back into the same connection while serving a request (the pattern LSP relies on), but it must observe one rule. To make a server-initiated *call* back to the peer with Conn.Call and await its response from within a handler, the handler MUST first release the read loop with Async (or be wrapped with AsyncHandler); otherwise it deadlocks, because the response to that callback must be read by the very read loop that is blocked running the handler. A server-initiated *notification* with Conn.Notify does not require Async: Notify only writes and never waits for a response.

The connection enforces a deterministic outcome for a misbehaving handler: if a handler panics, the connection answers an unanswered call with an InternalError response, then fails the connection so the panic is surfaced through Conn.Err rather than silently swallowed.

func AsyncHandler(handler Handler) Handler

func CancelHandler(handler Handler) (h Handler, canceller func(id ID))

type ID ¶

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

ID is a JSON-RPC request identifier.

Per the specification an identifier is a string, an integer, or null. ID stores the value without boxing it into an interface, so constructing and encoding an integer identifier performs no heap allocation.

The zero value is a valid, unset identifier (kind none); it encodes as the JSON null literal and is used for notifications and for error responses that have no associated request id.

func NewNumberID(v int64) ID

func NewStringID(v string) ID

func (id ID) Format(f fmt.State, r rune)

func (id ID) IsNumber() bool

func (id ID) IsString() bool

func (id ID) IsValid() bool

func (id ID) Number() (int64, bool)

func (id ID) StringValue() (string, bool)

type IDView ¶ added in v1.0.0

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

IDView is a zero-copy view of a JSON-RPC identifier.

StringBytes exposes the borrowed string body with surrounding quotes removed. When StringEscaped is true, those bytes are raw escaped body bytes, not decoded text; decode on demand with StringValue or ID.

func (id IDView) ID() (ID, bool)

func (id IDView) IsNumber() bool

func (id IDView) IsString() bool

func (id IDView) IsValid() bool

func (id IDView) Number() (int64, bool)

func (id IDView) Raw() []byte

func (id IDView) StringBytes() ([]byte, bool)

func (id IDView) StringEscaped() bool

func (id IDView) StringValue() (string, bool)

type JSONCodec ¶ added in v1.0.0

type JSONCodec struct{}

JSONCodec is the default Codec implementation, backed by encoding/json/v2 (github.com/go-json-experiment/json). It produces compact output with no trailing newline and no HTML escaping, consistent with json.Marshal, and passes RawMessage values through verbatim.

func (JSONCodec) Marshal(v any) ([]byte, error)

func (JSONCodec) Unmarshal(data []byte, v any) error

type Message ¶ added in v0.7.0

type Message interface {
	// contains filtered or unexported methods
}

Message is the interface implemented by all JSON-RPC message types.

The set of implementations is closed: only *Call, *Notification, and *Response satisfy it. The unexported method makes the set impossible to extend from outside the package.

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

type MessageView ¶ added in v1.0.0

type MessageView struct {
	Error ErrorView

	// JSONRPC is the borrowed raw value span of the "jsonrpc" member.
	JSONRPC []byte

	// IDRaw is the borrowed raw value span of the "id" member. ID is the parsed
	// view of the same span. For notifications and null IDs, ID is invalid.
	IDRaw []byte

	// MethodRaw is the borrowed raw string value span, including quotes.
	// MethodBytes is the borrowed unquoted string body. When MethodEscaped is
	// true, MethodBytes contains raw escaped body bytes; use MethodString or
	// Owned at explicit slow/owning boundaries.
	MethodRaw   []byte
	MethodBytes []byte

	// Params and Result are borrowed raw JSON value spans. Params is nil when the
	// request omits params or explicitly sets params to null. Result preserves a
	// null result as the borrowed bytes "null".
	Params []byte
	Result []byte

	// ErrorRaw is the borrowed raw value span of the "error" member. Error is a
	// parsed borrowed view of the same error object when Kind is
	// MessageViewResponseError.
	ErrorRaw []byte
	ID       IDView

	Kind MessageViewKind

	MethodEscaped bool
}

MessageView is a zero-copy view of a single JSON-RPC message.

Every byte slice in MessageView aliases the frame passed to ScanMessageView or ScanFrameView. The view is valid only while that frame remains valid and unmodified. Callback-scoped APIs may make this lifetime even shorter: when a view is delivered to a callback, callers must treat it as invalid after the callback returns unless they first call Clone or Owned.

The view deliberately exposes borrowed []byte spans rather than RawMessage to avoid making borrowed bytes look like the package's ordinary owned decoded message payloads.

func ScanMessageView(frame []byte) (MessageView, error)

func (v *MessageView) Clone() MessageView

func (v *MessageView) MethodString() (string, bool)

func (v *MessageView) Owned() (Message, error)

type MessageViewKind ¶ added in v1.0.0

type MessageViewKind uint8

MessageViewKind classifies a borrowed MessageView.

const (
	// MessageViewInvalid is the zero value and is not returned for a successful
	// scan.
	MessageViewInvalid MessageViewKind = iota
	// MessageViewCall is a request that carries a non-null identifier and expects
	// a response.
	MessageViewCall
	// MessageViewNotification is a request with no identifier or a null
	// identifier.
	MessageViewNotification
	// MessageViewResponseResult is a response carrying a result member. A JSON
	// null result is represented by the borrowed bytes "null".
	MessageViewResponseResult
	// MessageViewResponseError is a response carrying an error object.
	MessageViewResponseError
)

func (k MessageViewKind) String() string

type Notification ¶ added in v0.7.0

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

Notification is a request that does not expect a response and therefore carries no ID.

func NewNotification(method string, params RawMessage) *Notification

func (n *Notification) Method() string

func (n *Notification) Params() RawMessage

type Option ¶ added in v1.0.0

type Option func(*conn)

Option configures a Conn created by NewConn.

func WithCodec(c Codec) Option

func WithPreempter(p Preempter) Option

type ParsedMessage ¶ added in v1.0.0

type ParsedMessage struct {
	// Msg holds the decoded [*Call] or [*Notification] when the message is
	// well-formed, and is nil when Err is set.
	Msg RequestMessage

	// Err describes why a malformed message could not be decoded, and is nil for
	// a well-formed message.
	Err *Error

	// Batch reports whether the message came from a top-level JSON array.
	Batch bool
}

ParsedMessage is the parsed form of one request in a single-or-batch input.

When the message is well-formed Err is nil and Msg holds the decoded *Call or *Notification. When the message is malformed Err describes why and Msg is nil; the surrounding batch is still reported so that a caller can answer the valid entries and produce error responses for the invalid ones. Batch reports whether the message came from a JSON array.

func ParseRequests(data []byte) ([]*ParsedMessage, error)

type ParsedMessageView ¶ added in v1.0.0

type ParsedMessageView struct {
	Err   *Error
	View  MessageView
	Batch bool
}

ParsedMessageView is the borrowed-view form of one request parsed from a single-or-batch input.

When Err is nil, View holds a borrowed call or notification view. When Err is non-nil, View is invalid and Err describes the per-member parse/request problem. Batch reports whether the member came from a JSON array. All byte slices reachable from View alias the input passed to ScanRequestViews or AppendRequestViews.

func AppendRequestViews(dst []ParsedMessageView, data []byte) ([]ParsedMessageView, error)

func ScanRequestViews(data []byte) ([]ParsedMessageView, error)

type Peer ¶ added in v1.0.0

type Peer = Conn

Peer is the bidirectional JSON-RPC endpoint mode.

It names the existing Conn capability set explicitly: both sides may send calls, notifications, and responses, with Async required for handlers that wait on server-initiated calls.

func NewPeer(stream Stream, opts ...Option) Peer

type PipelineClient ¶ added in v1.0.0

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

PipelineClient is the pipelined client mode.

It supports concurrent client-driven calls and notifications, but it does not dispatch server-initiated requests. The response reader is client-only: for frame-capable streams it scans borrowed response views and unmarshals the result directly into the waiting call's destination before the next frame can invalidate the borrowed bytes.

func NewPipelineClient(stream Stream, opts ...Option) *PipelineClient

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

func (c *PipelineClient) Close() error

func (c *PipelineClient) Done() <-chan struct{}

func (c *PipelineClient) Err() error

func (c *PipelineClient) Go(ctx context.Context, _ Handler)

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

type Preempter ¶ added in v1.0.0

type Preempter interface {
	// Preempt is called for each incoming request before it is dispatched.
	// Returning [ErrNotHandled] (or a nil handled value) defers the request to
	// the [Handler]; returning any other result handles the request inline and
	// it is not passed to the Handler.
	Preempt(ctx context.Context, req *Request) (handled any, err error)
}

Preempter is an optional hook consulted for every incoming Request before it is dispatched to the Handler. It runs inline on the read loop, so it must not block; it is intended for fast, ordered handling such as "$/cancelRequest" notifications that must be observed ahead of the request they cancel. The request follows the same borrowed lifetime as a Handler's: valid only until Preempt returns.

type RawMessage ¶ added in v0.7.0

type RawMessage []byte

RawMessage is a raw, already-encoded JSON value.

It mirrors the semantics of encoding/json's RawMessage: the bytes are stored verbatim on encode and returned verbatim on decode. A RawMessage exposed by a decoded request BORROWS the decoder's input (see DecodeMessage); other decoded values own their backing arrays.

type Request ¶

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

Request is the concrete request shape used by direct-return dispatch. It is a value, not an interface: the scanner fills it in place and dispatch embeds it in the per-request bookkeeping, so a request needs no message box. Method and params spans are borrowed from the transport frame and are valid until the handler returns.

func (r *Request) Clone() *Request

func (r *Request) ID() ID

func (r *Request) IsCall() bool

func (r *Request) Method() string

func (r *Request) Params() RawMessage

type RequestMessage ¶ added in v1.0.0

type RequestMessage interface {
	Message

	// Method reports the name of the method to invoke.
	Method() string

	// Params reports the raw, already-encoded parameters of the method, or nil
	// when the request carries no parameters.
	Params() RawMessage
	// contains filtered or unexported methods
}

RequestMessage is the shared interface for wire messages that ask a peer to invoke a method. The set of implementations is closed to *Call and *Notification. It is the message-model view used by ParseRequests and batch parsing; handlers receive the concrete Request instead.

type Response ¶ added in v0.7.0

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

Response is a reply to a Call. It carries the same ID as the call it answers, and exactly one of a result or an error.

func NewResponse(id ID, result RawMessage, err error) *Response

func (r *Response) Err() error

func (r *Response) ID() ID

func (r *Response) Result() RawMessage

type Server ¶ added in v1.0.0

type Server = Conn

Server is the server-oriented runtime mode.

It currently uses Conn because the existing connection already provides the server read loop, preemption, async handler release, and batch dispatch. The separate name keeps server-only call sites from depending on client-mode constructors.

func NewServer(stream Stream, opts ...Option) Server

type ServerFunc ¶ added in v0.7.0

type ServerFunc func(context.Context, Conn) error

ServerFunc is an adapter that implements the StreamServer interface using an ordinary function.

func (f ServerFunc) ServeStream(ctx context.Context, c Conn) error

type SingleClient ¶ added in v1.0.0

type SingleClient = SyncClient

SingleClient is the single-flight, caller-owned-read-loop client mode.

It is an alias of SyncClient so the current low-latency synchronous client becomes the named baseline for the mode split without adding another runtime layer.

func NewSingleClient(stream Stream, opts ...Option) (*SingleClient, error)

type Stream ¶

type Stream interface {
	// Read decodes the next message from the stream. It returns [io.EOF] when
	// the peer closes the connection at a clean frame boundary, and
	// [io.ErrUnexpectedEOF] when the connection ends in the middle of a frame.
	//
	// A decoded request's method and params borrow the stream's read buffer
	// and are valid only until the next Read; copy what you retain. Responses
	// own their bytes.
	Read(ctx context.Context) (Message, int64, error)

	// Write frames msg and writes it to the stream as a single contiguous write.
	Write(ctx context.Context, msg Message) (int64, error)

	// Close closes the underlying connection.
	Close() error
}

Stream is a bidirectional channel of JSON-RPC messages over a single connection. A Stream adapts a byte transport (the framing) to the message boundary: Read decodes the next framed Message and Write frames and emits one.

The int64 returned by Read and Write is the number of wire bytes transferred for that message, including any framing overhead (the LSP header, or the newline delimiter for ndjson). It is informational and is intended for transport accounting; a zero count accompanies an error.

A Stream owns the underlying connection: Close closes it. Read is expected to be driven from a single goroutine (the connection's read loop). Write is safe for concurrent use; concurrent writers are serialized so that each message is emitted as one contiguous frame.

func NewChannelStreamPair(capacity int) (left, right Stream)

func NewHeaderStream(conn io.ReadWriteCloser) Stream

Content-Length: <n>\r\n
[Content-Type: ...\r\n]
\r\n
<n bytes of JSON>

func NewNDJSONStream(conn io.ReadWriteCloser) Stream

func NewRawStream(conn io.ReadWriteCloser) Stream

func NewStream(conn io.ReadWriteCloser) Stream

type StreamServer ¶ added in v0.7.0

type StreamServer interface {
	ServeStream(context.Context, Conn) error
}

StreamServer is used to serve incoming jsonrpc2 clients communicating over a newly created connection.

ServeStream is called once per accepted connection, on its own goroutine, with a Conn wrapping that connection. It should drive the connection (typically by calling Conn.Go and waiting on Conn.Done) and return when the connection is finished. The connection's stream is closed by Serve after ServeStream returns.

func HandlerServer(h Handler) StreamServer

type SyncClient ¶ added in v1.0.0

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

SyncClient is a synchronous JSON-RPC 2.0 client that owns its read loop: it never starts a background read goroutine. Each SyncClient.Call writes the request and then reads frames on the caller's own goroutine until the matching response arrives, so a round trip collapses the dedicated-reader-to-caller hand-off that a Conn pays (the third goroutine hop). On an in-process transport this is the lowest-latency request path the package offers.

The tradeoff is the reason it is a distinct type rather than the default Call path: a SyncClient cannot asynchronously receive server-initiated requests (there is no background reader to dispatch them), and its calls are serialized — exactly one call may be outstanding at a time, guarded by an internal mutex. A peer that issues server-to-client calls, or a caller that needs concurrent in-flight calls on one connection, must use Conn with Conn.Go. SyncClient is for the common client-drives-server request/reply shape over an in-process or point-to-point transport.

A SyncClient requires a Stream that also exposes raw frame access (the built-in NewNDJSONStream and NewHeaderStream framers do); a plain Stream without frame access is rejected by NewSyncClient.

func NewSyncClient(stream Stream, opts ...Option) (*SyncClient, error)

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

func (c *SyncClient) Close() error

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