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 ¶
- Variables
- type HandlerFunc
- type NotificationFunc
- type Option
- type Peer
- func (p *Peer) Call(ctx context.Context, method string, params, result any) error
- func (p *Peer) Handle(method string, h HandlerFunc)
- func (p *Peer) HandleNotification(method string, h NotificationFunc)
- func (p *Peer) Notify(method string, params any) error
- func (p *Peer) Serve(ctx context.Context) error
Constants ¶
This section is empty.
Variables ¶
var ErrClosed = errors.New("jsonrpc: peer closed")
ErrClosed is returned by Call and Notify once the peer has stopped.
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 ¶
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 ¶
WithDrainTimeout sets how long Serve waits for running handlers after it stopped; the default is 5 s.
func WithLogger ¶
WithLogger sets the logger; the default discards everything. The peer never logs params or results.
func WithMaxLine ¶
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 (*Peer) Call ¶
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.