jsonrpc

Documentation

Overview

Package jsonrpc implements a JSON-RPC 2.0 client and server over Unix sockets.

This package provides the communication layer between the agent and UI components, allowing them to operate as separate processes while maintaining a structured communication protocol. The implementation follows the JSON-RPC 2.0 specification (https://www.jsonrpc.org/specification) and is specifically designed for local inter-process communication via Unix domain sockets.

Architecture

The package consists of two main components:

• Client: Connects to a server via a Unix socket and provides methods for making RPC calls and sending notifications.
• Server: Listens on a Unix socket, accepts client connections, and dispatches incoming requests to registered method handlers.

This package focuses solely on the JSON-RPC protocol implementation and does not define application-specific method names or parameter types. Those are defined in the api package, which serves as the public API contract for the aigent system.

Usage

Server example:

server := jsonrpc.NewServer(socketPath, logger)
server.RegisterMethod("method.name", handleMethod)
if err := server.Start(); err != nil {
	log.Fatal(err)
}
defer server.Stop()

Client example:

client := jsonrpc.NewClient(socketPath, logger)
if err := client.Connect(); err != nil {
	log.Fatal(err)
}
defer client.Disconnect()

var result SomeResultType
err := client.Call(ctx, "method.name", someParams, &result)

Socket Path Management

The package provides utility functions for generating socket paths:

• GetDefaultSocketPath: Returns the default socket path for the agent
• GetUniqueSocketPath: Generates a unique socket path based on a prefix, useful when multiple instances need to run simultaneously

Index

• Constants
• func GetDefaultSocketPath() string
• func GetUniqueSocketPath(prefix string) string
• type Client
  • func NewClient(socketPath string, logger *slog.Logger) *Client
  • func (c *Client) Call(ctx context.Context, method string, params any, result any) error
  • func (c *Client) Connect() error
  • func (c *Client) Disconnect() error
  • func (c *Client) Notify(method string, params any) error
  • func (c *Client) RegisterNotificationHandler(method string, handler NotificationHandler)
• type Error
• type MethodHandler
• type Notification
• type NotificationHandler
• type Request
• type Response
• type Server
  • func NewServer(socketPath string, logger *slog.Logger) *Server
  • func (s *Server) RegisterMethod(method string, handler MethodHandler)
  • func (s *Server) SendNotification(method string, params any) error
  • func (s *Server) Start() error
  • func (s *Server) Stop() error

Constants

const (
	ErrCodeParseError     = -32700
	ErrCodeInvalidRequest = -32600
	ErrCodeMethodNotFound = -32601
	ErrCodeInvalidParams  = -32602
	ErrCodeInternalError  = -32603
	// -32000 to -32099 are reserved for implementation-defined server errors
	ErrCodeServerError = -32000
)

Standard error codes as defined in the JSONRPC 2.0 spec

Functions

func GetDefaultSocketPath

func GetDefaultSocketPath() string

GetDefaultSocketPath returns the default socket path for the agent

func GetUniqueSocketPath

func GetUniqueSocketPath(prefix string) string

GetUniqueSocketPath returns a unique socket path based on a prefix

Types

type Client

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

Client represents a JSONRPC client that connects to a Unix socket

func NewClient

func NewClient(socketPath string, logger *slog.Logger) *Client

NewClient creates a new JSONRPC client

func (*Client) Call

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

Call makes a JSONRPC method call and waits for the response

func (*Client) Connect

func (c *Client) Connect() error

Connect connects to the server

func (*Client) Disconnect

func (c *Client) Disconnect() error

Disconnect disconnects from the server

func (*Client) Notify

func (c *Client) Notify(method string, params any) error

Notify sends a JSONRPC notification (no response expected)

func (*Client) RegisterNotificationHandler

func (c *Client) RegisterNotificationHandler(method string, handler NotificationHandler)

RegisterNotificationHandler registers a handler for a specific notification method

type Error

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

Error represents a JSONRPC error

type MethodHandler

type MethodHandler func(ctx context.Context, params json.RawMessage) (any, error)

MethodHandler is a function that handles a JSONRPC method call

type Notification

type Notification struct {
	JSONRPC string `json:"jsonrpc"`
	Method  string `json:"method"`
	Params  any    `json:"params,omitempty"`
}

Notification represents a JSONRPC notification (a request without an ID)

type NotificationHandler

type NotificationHandler func(params json.RawMessage)

NotificationHandler is a function that handles a JSONRPC notification

type Request

type Request struct {
	JSONRPC string `json:"jsonrpc"`
	Method  string `json:"method"`
	Params  any    `json:"params,omitempty"`
	ID      any    `json:"id,omitempty"` // Can be string, number, or null
}

Request represents a JSONRPC request

type Response

type Response struct {
	JSONRPC string `json:"jsonrpc"`
	Result  any    `json:"result,omitempty"`
	Error   *Error `json:"error,omitempty"`
	ID      any    `json:"id,omitempty"` // Should match the id of the request
}

Response represents a JSONRPC response

type Server

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

Server represents a JSONRPC server that listens on a Unix socket

func NewServer

func NewServer(socketPath string, logger *slog.Logger) *Server

NewServer creates a new JSONRPC server

func (*Server) RegisterMethod

func (s *Server) RegisterMethod(method string, handler MethodHandler)

RegisterMethod registers a method handler

func (*Server) SendNotification

func (s *Server) SendNotification(method string, params any) error

SendNotification sends a notification to all connected clients

func (*Server) Start

func (s *Server) Start() error

Start starts the server

func (*Server) Stop

func (s *Server) Stop() error

Stop stops the server