jsonrpc

Documentation

Overview

Package jsonrpc implements a tolerant JSON-RPC 2.0 envelope used by the MCP gateway. It parses only what the inspector needs (id, method, params, result, error) and preserves unknown fields verbatim so protocol revisions pass through untouched.

Index

• Constants
• type Error
  • func (e *Error) Error() string
• type ID
  • func (id ID) IsZero() bool
  • func (id ID) Key() string
  • func (id ID) MarshalJSON() ([]byte, error)
  • func (id ID) String() string
  • func (id *ID) UnmarshalJSON(b []byte) error
• type Message
  • func NewError(id ID, code int, msg string) *Message
  • func NewResult(id ID, result any) (*Message, error)
  • func Parse(data []byte) (*Message, error)
  • func (m *Message) IsNotification() bool
  • func (m *Message) IsRequest() bool
  • func (m *Message) IsResponse() bool
  • func (m *Message) Marshal() ([]byte, error)

Constants

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

	// CodePolicyDenied is returned when the gateway blocks a request by
	// policy. The session stays alive; the client sees a readable refusal.
	CodePolicyDenied = -32010
	// CodeApprovalRejected is returned when a human reviewer rejects a held
	// tool call.
	CodeApprovalRejected = -32011
	// CodeBudgetExceeded is returned when a session/tool budget is exhausted.
	CodeBudgetExceeded = -32012
)

Standard and gateway-specific error codes.

Types

type Error

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

Error is a JSON-RPC error object.

func (*Error) Error

func (e *Error) Error() string

type ID

type ID struct {
	Raw json.RawMessage
}

ID is a JSON-RPC id: string, integer, or null. The zero value means "absent" (notification). Raw preserves the exact wire bytes so the gateway can correlate responses and re-emit the id byte for byte.

func (ID) IsZero

func (id ID) IsZero() bool

IsZero reports whether the id was absent (a notification).

func (ID) Key

func (id ID) Key() string

Key returns a map key for correlation. Distinct wire encodings ("1" vs "\"1\"") produce distinct keys, matching JSON-RPC semantics where ids are compared by value and type.

func (ID) MarshalJSON

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

MarshalJSON re-emits the exact bytes received.

func (ID) String

func (id ID) String() string

func (*ID) UnmarshalJSON

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

UnmarshalJSON captures the raw id bytes.

type Message

type Message struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      ID              `json:"id,omitempty"`
	Method  string          `json:"method,omitempty"`
	Params  json.RawMessage `json:"params,omitempty"`
	Result  json.RawMessage `json:"result,omitempty"`
	Error   *Error          `json:"error,omitempty"`

	// Extra holds unrecognized top-level fields, re-emitted on Marshal.
	Extra map[string]json.RawMessage `json:"-"`
}

Message is a single JSON-RPC 2.0 message. Exactly one of Method (request / notification) or Result/Error (response) is set. Extra carries any fields beyond the standard five so re-serialization drops nothing.

func NewError

func NewError(id ID, code int, msg string) *Message

NewError builds an error response answering id.

func NewResult

func NewResult(id ID, result any) (*Message, error)

NewResult builds a success response answering id.

func Parse

func Parse(data []byte) (*Message, error)

Parse decodes a single JSON-RPC message, tolerating and preserving unknown top-level fields. It returns an error only for malformed JSON or a message that is neither request, notification, nor response.

func (*Message) IsNotification

func (m *Message) IsNotification() bool

IsNotification reports whether m is a notification (no response expected).

func (*Message) IsRequest

func (m *Message) IsRequest() bool

IsRequest reports whether m is a request expecting a response.

func (*Message) IsResponse

func (m *Message) IsResponse() bool

IsResponse reports whether m answers an earlier request.

func (*Message) Marshal

func (m *Message) Marshal() ([]byte, error)

Marshal serializes the message, re-emitting preserved unknown fields.