rpc

Documentation

Overview

Package rpc is the host's end of rig/1: newline-delimited JSON-RPC 2.0 to one plugin process.

Index

• Variables
• func AsError(err error) *protocol.Error
• type Conn
  • func New(r io.Reader, w io.Writer, opts Options) *Conn
  • func (c *Conn) Call(ctx context.Context, method string, params, result any) error
  • func (c *Conn) Done() <-chan struct{}
  • func (c *Conn) Err() error
  • func (c *Conn) Notify(method string, params any) error
  • func (c *Conn) WriteRaw(line []byte) error
• type Message
• type Options
• type Process
  • func Start(cmd *exec.Cmd, opts Options) (*Process, error)
  • func (p *Process) Close(grace time.Duration) error
  • func (p *Process) Pid() int

Variables

var ErrClosed = errors.New("plugin connection closed")

Functions

func AsError

func AsError(err error) *protocol.Error

AsError keeps a protocol error as it is and makes anything else an internal error.

Types

type Conn

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

func New

func New(r io.Reader, w io.Writer, opts Options) *Conn

func (*Conn) Call

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

Call sends a request and waits for the answer; cancelling ctx sends $/cancel.

func (*Conn) Done

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

func (*Conn) Err

func (c *Conn) Err() error

func (*Conn) Notify

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

func (*Conn) WriteRaw

func (c *Conn) WriteRaw(line []byte) error

WriteRaw sends a line as it is, for tests that send what no well-behaved host would.

type Message

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

type Options

type Options struct {
	// OnRequest answers the plugin's host/* requests; nil answers MethodNotFound.
	OnRequest func(ctx context.Context, method string, params json.RawMessage) (any, error)
	// OnNotify sees the plugin's notifications ($/progress, $/stream, host/log).
	OnNotify func(method string, params json.RawMessage)
	// Tap sees every line: dir '>' host to plugin, '<' plugin to host. Transcripts record through it.
	Tap func(dir byte, line []byte)
}

type Process

type Process struct {
	*Conn
	// contains filtered or unexported fields
}

Process is a plugin started as a child process, speaking on its stdin and stdout.

func Start

func Start(cmd *exec.Cmd, opts Options) (*Process, error)

Start runs cmd and connects to it; stderr goes wherever cmd.Stderr points.

func (*Process) Close

func (p *Process) Close(grace time.Duration) error

Close asks the plugin to shut down, waits up to grace for it to exit, then kills it.

func (*Process) Pid

func (p *Process) Pid() int