Documentation
¶
Overview ¶
Package acp is a minimal Agent Client Protocol client: JSON-RPC 2.0 lines carried between the daemon and one agent process per worker. A per-worker host process owns the agent (see ServeHost), so the agent survives a daemon restart; the client below is the daemon's side of that link.
Index ¶
- Variables
- func KillHost(workerdir string, wait time.Duration) (bool, error)
- func ServeHost(ctx context.Context, workerdir string) error
- type CallResult
- type Client
- func (c *Client) AwaitCall(ctx context.Context, id int64, result any) (int64, error)
- func (c *Client) Call(ctx context.Context, method string, params any, result any) error
- func (c *Client) Close()
- func (c *Client) Detached() bool
- func (c *Client) Done() <-chan struct{}
- func (c *Client) ExitError() error
- func (c *Client) Exited() bool
- func (c *Client) Expect(id int64) <-chan CallResult
- func (c *Client) Kill()
- func (c *Client) Notifications() <-chan Notification
- func (c *Client) Notify(method string, params any) error
- func (c *Client) PID() int
- func (c *Client) Requests() <-chan Request
- func (c *Client) Reserve() int64
- func (c *Client) Respond(req Request, result any) error
- func (c *Client) RespondError(req Request, code int, message string) error
- func (c *Client) Send(id int64, method string, params any) error
- func (c *Client) Seq() int64
- func (c *Client) SetNextID(n int64)
- type LaunchSpec
- type Notification
- type RPCError
- type Request
Constants ¶
This section is empty.
Variables ¶
var ErrClosed = errors.New("acp: link to the agent's host closed")
ErrClosed is returned for requests outstanding when the link to the agent's host ends. Exited reports whether the agent itself exited.
Functions ¶
func KillHost ¶ added in v0.1.2
KillHost attaches to a worker's host only to end its agent, and waits up to wait for the exit. It reports whether a host answered: one that does not is already gone, which is the outcome the caller wants. Nothing is replayed, since a client that only kills has no use for the stream.
Types ¶
type CallResult ¶
type CallResult struct {
Seq int64
Result json.RawMessage
Err error
}
CallResult is the answer to a client request, tagged with the stream position of the line that carried it.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the daemon's handle on one worker's agent, connected through the worker's host socket.
func Attach ¶
Attach connects to the host of a worker the daemon has lost, resuming the stream after resumeSeq. expect lists request ids still in flight from before the loss; their replayed responses are routed to Expect channels.
func Launch ¶
func Launch(hostArgv []string, workerdir string, launch LaunchSpec) (*Client, error)
Launch writes launch.json into workerdir, starts the host process detached, and returns a client once the host's socket answers. The host outlives the caller: it keeps the agent alive across a daemon restart.
func (*Client) AwaitCall ¶
AwaitCall waits for the response to a request registered with Expect and unpacks it like Call. It returns the stream position of the response.
func (*Client) Close ¶
func (c *Client) Close()
Close drops the connection to the host. The agent keeps running; a later Attach resumes it.
func (*Client) Detached ¶
Detached reports whether the link ended without the agent exiting: the host replaced this connection or the daemon is shutting down.
func (*Client) Done ¶
func (c *Client) Done() <-chan struct{}
Done is closed when the link to the host has ended, by the agent's exit or by losing the host.
func (*Client) Expect ¶
func (c *Client) Expect(id int64) <-chan CallResult
Expect registers id as in flight and returns the channel its result arrives on. An id already registered (e.g. by Attach) returns the existing channel.
func (*Client) Kill ¶
func (c *Client) Kill()
Kill asks the host to terminate the agent's process group.
func (*Client) Notifications ¶
func (c *Client) Notifications() <-chan Notification
Notifications delivers agent notifications in stream order. Closed when the link ends.
func (*Client) RespondError ¶
RespondError answers an agent-to-client request with an error.
func (*Client) Send ¶
Send writes a request with an id from Reserve. Pair it with Expect before sending so a fast response cannot be missed.
type LaunchSpec ¶
type LaunchSpec struct {
Argv []string `json:"argv"`
Env []string `json:"env"`
Cwd string `json:"cwd"`
StderrPath string `json:"stderr_path"`
}
LaunchSpec describes how the host starts the agent; persisted as launch.json in the worker directory so the host needs no other input.
type Notification ¶
type Notification struct {
Seq int64
Method string
Params json.RawMessage
}
Notification is a JSON-RPC notification from the agent (no id). Seq is the host's stream position of the line that carried it.
type RPCError ¶
type RPCError struct {
Code int `json:"code"`
Message string `json:"message"`
Data json.RawMessage `json:"data,omitempty"`
}
RPCError is the JSON-RPC error object.
type Request ¶
type Request struct {
Seq int64
ID json.RawMessage
Method string
Params json.RawMessage
}
Request is a JSON-RPC request from the agent that the client must answer. Seq is the host's stream position of the line that carried it.
Source Files