jsonrpc

package
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: Oct 29, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package jsonrpc is the bidirectional, line-delimited JSON-RPC 2.0 peer of the Arvel Provider Protocol (PROTOCOL §2). It sits on jsonl.Scanner and jsonl.Writer and replaces the connection layer of the ACP library, which limits lines to 10 MiB (docs/FINDINGS.md, spike S0.1).

Concurrency and ordering

Every incoming request runs in its own goroutine. Notifications that carry the same key (by default their params.sessionId) are handled one at a time in arrival order; notifications with different keys run in parallel. A response is handed to its Call only after every notification received before it has been handled, so a client sees all session/update messages of a turn before the session/prompt result. On the sending side Notify returns after the line has been written, so Notify calls followed by a handler's return reach the wire in that order.

A notification handler may call Call, but the response is then not ordered after other notifications (that would deadlock). A notification handler must never wait for a request handler of the same peer.

Cancellation

Cancelling the context of Call writes nothing: ACP cancellation is semantic, through session/cancel. A late response to a cancelled call is dropped.

Errors

Errors on the wire are *protocol.RPCError. A handler that returns another error produces the generic "internal error" without the error text, since the text may hold a secret. A handler panic is recovered and answered with the Arvel error "internal".

Shutdown

Serve returns when the reader reaches end of input, fails, or the context ends. A goroutine blocked in Read cannot be interrupted; it ends when the caller closes the reader. Serve does not wait for it.

Index

Constants

This section is empty.

Variables

View Source
var ErrClosed = errors.New("jsonrpc: peer closed")

ErrClosed is returned by Call and Notify once the peer has stopped.

View Source
var ErrServing = errors.New("jsonrpc: Serve already called")

ErrServing is returned by a second call to Serve.

Functions

This section is empty.

Types

type HandlerFunc

type HandlerFunc func(ctx context.Context, params json.RawMessage) (result any, err error)

HandlerFunc answers one request. The returned value is marshalled into the result; a returned *protocol.RPCError is sent as is.

type NotificationFunc

type NotificationFunc func(ctx context.Context, params json.RawMessage)

NotificationFunc handles one notification.

type Option

type Option func(*config)

Option configures a Peer.

func WithDrainTimeout

func WithDrainTimeout(d time.Duration) Option

WithDrainTimeout sets how long Serve waits for running handlers after it stopped; the default is 5 s.

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger sets the logger; the default discards everything. The peer never logs params or results.

func WithMaxLine

func WithMaxLine(n int) Option

WithMaxLine sets the longest accepted incoming line; the default is jsonl.DefaultMaxLine (64 MiB).

func WithNotificationKey

func WithNotificationKey(f func(method string, params json.RawMessage) string) Option

WithNotificationKey sets the function that groups notifications into ordered queues. Notifications with the same key are handled one at a time in arrival order. The default key is params.sessionId, or "" when absent.

type Peer

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

Peer is one end of a line-delimited JSON-RPC 2.0 connection. See the package documentation for the concurrency and ordering contract.

func NewPeer

func NewPeer(r io.Reader, w io.Writer, opts ...Option) *Peer

NewPeer returns a Peer that reads lines from r and writes lines to w.

func (*Peer) Call

func (p *Peer) Call(ctx context.Context, method string, params, result any) error

Call sends a request and waits for the response. Cancelling ctx stops the wait and writes nothing to the wire. An error response is returned as a *protocol.RPCError.

func (*Peer) Handle

func (p *Peer) Handle(method string, h HandlerFunc)

Handle registers the handler of a request method, replacing any earlier one.

func (*Peer) HandleNotification

func (p *Peer) HandleNotification(method string, h NotificationFunc)

HandleNotification registers the handler of a notification method.

func (*Peer) Notify

func (p *Peer) Notify(method string, params any) error

Notify sends a notification. It returns after the line has been written.

func (*Peer) Serve

func (p *Peer) Serve(ctx context.Context) error

Serve reads and dispatches messages until the input ends, fails or ctx is done. It returns nil at a clean end of input, the read error, or ctx.Err(). Serve may be called once.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL