control

Documentation

Overview

Package control implements the stream-json control channel: the request/response frames that ride the same stdio pipes as events. It is a pure state machine over a write function — no process, no session knowledge — so its behaviour is fully testable without a child. Frame shapes are pinned in contracts/control-channel.md, characterized from the 2.1.226 captures and the SDK 0.3.226 oracle.

Index

• Variables
• type Conn
  • func NewConn(write func([]byte) error) *Conn
  • func (c *Conn) Close(err error)
  • func (c *Conn) HandleFrame(line []byte) bool
  • func (c *Conn) Request(ctx context.Context, subtype string, params any) (json.RawMessage, error)
  • func (c *Conn) SetHandler(subtype string, h Handler)
• type Handler

Variables

var ErrClosed = errors.New("control: connection closed")

ErrClosed reports a request made on (or failed by) a closed Conn.

Types

type Conn

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

Conn is one control-channel multiplexer.

func NewConn

func NewConn(write func([]byte) error) *Conn

NewConn returns a mux that emits frames through write. write must be safe for concurrent use (handlers respond from their own goroutines).

func (*Conn) Close

func (c *Conn) Close(err error)

Close fails all pending requests with err (ErrClosed when nil), cancels in-flight incoming handlers, and refuses further requests. Idempotent.

func (*Conn) HandleFrame

func (c *Conn) HandleFrame(line []byte) bool

HandleFrame routes one stdout line. It reports false for non-control frames so the session pump passes them on to event decoding.

func (*Conn) Request

func (c *Conn) Request(ctx context.Context, subtype string, params any) (json.RawMessage, error)

Request sends one control request and waits for its response. params must marshal to a JSON object (or be nil); subtype is set on it.

func (*Conn) SetHandler

func (c *Conn) SetHandler(subtype string, h Handler)

SetHandler registers the responder for an incoming subtype. An unregistered subtype gets an error control_response naming it (the oracle's behaviour). Not safe to call after frames start flowing.

type Handler

type Handler func(ctx context.Context, req json.RawMessage) (any, error)

Handler answers one incoming control request of a registered subtype. The returned value marshals into the success response's payload; an error becomes an error control_response. The context is cancelled if the CLI sends control_cancel_request for this request or the Conn closes.