Documentation
¶
Overview ¶
Package protocol defines the vsock wire protocol between host API server and in-VM agent. Messages are JSON-encoded with a 4-byte big-endian length prefix.
Message flow:
Host Guest Agent │ │ │──── PingRequest ─────────────▶│ │◀─── PingResponse ────────────│ │ │ │──── ExecRequest ─────────────▶│ │◀─── ExecResponse ────────────│ │ │ │──── FileWriteRequest ────────▶│ │◀─── FileWriteResponse ───────│ │ │ │──── FileReadRequest ─────────▶│ │◀─── FileReadResponse ────────│
Index ¶
- func DecodePayload[T any](env *Envelope) (*T, error)
- func WriteMessage(w io.Writer, msg *Envelope) error
- type Envelope
- type ErrorResponse
- type ExecRequest
- type ExecResponse
- type FileReadRequest
- type FileReadResponse
- type FileWriteRequest
- type FileWriteResponse
- type MessageType
- type PingRequest
- type PingResponse
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecodePayload ¶
DecodePayload extracts a typed payload from a raw Envelope. The Envelope.Payload is initially decoded as a json.RawMessage-like map, so we re-marshal and unmarshal into the target type.
Types ¶
type Envelope ¶
type Envelope struct {
Type MessageType `json:"type"`
Payload any `json:"payload"`
}
Envelope wraps every vsock message with a type discriminator.
type ErrorResponse ¶
type ErrorResponse struct {
Message string `json:"message"`
}
ErrorResponse is returned when the agent encounters an error.
type ExecRequest ¶
type ExecRequest struct {
Command []string `json:"command"`
Env map[string]string `json:"env,omitempty"`
WorkDir string `json:"workdir,omitempty"`
Timeout int `json:"timeout,omitempty"` // seconds, 0 = no timeout
}
ExecRequest asks the agent to run a command.
type ExecResponse ¶
type ExecResponse struct {
ExitCode int `json:"exit_code"`
Stdout string `json:"stdout"`
Stderr string `json:"stderr"`
}
ExecResponse returns the result of a command execution.
type FileReadRequest ¶
type FileReadRequest struct {
Path string `json:"path"`
}
FileReadRequest asks the agent to read a file from the VM.
type FileReadResponse ¶
type FileReadResponse struct {
Content string `json:"content"` // base64-encoded
Size int64 `json:"size"`
Mode int `json:"mode"`
}
FileReadResponse returns the file contents.
type FileWriteRequest ¶
type FileWriteRequest struct {
Path string `json:"path"`
Content string `json:"content"` // base64-encoded for binary, raw for text
Mode int `json:"mode"` // file permissions (e.g., 0644)
Binary bool `json:"binary"` // if true, Content is base64-encoded
}
FileWriteRequest asks the agent to write a file inside the VM.
type FileWriteResponse ¶
type FileWriteResponse struct {
BytesWritten int `json:"bytes_written"`
}
FileWriteResponse confirms the file was written.
type MessageType ¶
type MessageType string
MessageType identifies the kind of vsock message.
const ( TypePingRequest MessageType = "ping_request" TypePingResponse MessageType = "ping_response" TypeExecRequest MessageType = "exec_request" TypeExecResponse MessageType = "exec_response" TypeFileWriteRequest MessageType = "file_write_request" TypeFileWriteResponse MessageType = "file_write_response" TypeFileReadRequest MessageType = "file_read_request" TypeFileReadResponse MessageType = "file_read_response" TypeError MessageType = "error" )
type PingResponse ¶
type PingResponse struct {
Version string `json:"version"`
}
PingResponse confirms the agent is alive.
Source Files