control

package
v0.3.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 21, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package control implements virtle's local runtime control socket protocol.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FailedPrecondition 

func FailedPrecondition(err error) error

FailedPrecondition wraps err as an RPC failed-precondition error.

func IsSocketUnavailable 

func IsSocketUnavailable(err error) bool

IsSocketUnavailable reports whether err means no control socket is reachable.

func Listen 

func Listen(path string) (net.Listener, error)

Listen opens a private Unix socket at path for control requests.

Types

type BalloonRequest 

type BalloonRequest struct {
	TargetBytes int64 `json:"targetBytes,omitempty"`
}

BalloonRequest asks the runtime to resize or query the memory balloon.

type BalloonResponse 

type BalloonResponse struct {
	ActualBytes int64 `json:"actualBytes"`
	TargetBytes int64 `json:"targetBytes,omitempty"`
}

BalloonResponse reports the current and requested balloon sizes.

type Client 

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

Client sends typed requests to a control socket.

func Dial 

func Dial(path string) *Client

Dial returns a client for the control socket at path.

func (*Client) Balloon 

func (c *Client) Balloon(ctx context.Context, req BalloonRequest) (BalloonResponse, error)

Balloon sends a balloon request.

func (*Client) GuestExec 

func (c *Client) GuestExec(ctx context.Context, req GuestExecRequest) (GuestExecResponse, error)

GuestExec sends a guest process execution request.

func (*Client) GuestPS 

func (c *Client) GuestPS(ctx context.Context, req GuestPSRequest) (GuestPSResponse, error)

GuestPS sends a guest process list request.

func (*Client) GuestRead 

func (c *Client) GuestRead(ctx context.Context, req GuestReadRequest) (GuestReadResponse, error)

GuestRead sends a guest file read request.

func (*Client) GuestWrite 

func (c *Client) GuestWrite(ctx context.Context, req GuestWriteRequest) (GuestWriteResponse, error)

GuestWrite sends a guest file write request.

func (*Client) Hotplug 

func (c *Client) Hotplug(ctx context.Context, req HotplugRequest) (HotplugResponse, error)

Hotplug sends a hotplug request.

func (*Client) Methods 

func (c *Client) Methods(ctx context.Context, req MethodsRequest) (MethodsResponse, error)

Methods sends a methods request.

func (*Client) Raw 

func (c *Client) Raw(ctx context.Context, method string, params json.RawMessage) (json.RawMessage, error)

Raw sends a request to method with raw JSON params and returns the raw JSON result.

func (*Client) Status 

func (c *Client) Status(ctx context.Context, req StatusRequest) (StatusResponse, error)

Status sends a status request.

func (*Client) Suspend 

func (c *Client) Suspend(ctx context.Context, req SuspendRequest) (SuspendResponse, error)

Suspend sends a suspend request.

type ErrorCode 

type ErrorCode string

ErrorCode classifies a control socket RPC failure. 

const (
	// ErrInvalidRequest means the request envelope could not be decoded.
	ErrInvalidRequest ErrorCode = "invalid_request"
	// ErrUnknownMethod means the requested RPC method is not implemented.
	ErrUnknownMethod ErrorCode = "unknown_method"
	// ErrInvalidParams means the request params did not match the method.
	ErrInvalidParams ErrorCode = "invalid_params"
	// ErrUnsupported means the runtime was built or configured without a capability.
	ErrUnsupported ErrorCode = "unsupported"
	// ErrFailedPrecondition means the runtime is not ready for the requested operation.
	ErrFailedPrecondition ErrorCode = "failed_precondition"
	// ErrInternal means the request failed with an unexpected internal error.
	ErrInternal ErrorCode = "internal"
)

type GuestExecRequest 

type GuestExecRequest struct {
	Path          string   `json:"path"`
	Args          []string `json:"args,omitempty"`
	CaptureOutput bool     `json:"captureOutput,omitempty"`
	// Timeout bounds the guest command; zero or omitted waits indefinitely.
	Timeout units.Duration `json:"timeout,omitempty"`
}

GuestExecRequest asks the guest agent to execute a process.

type GuestExecResponse 

type GuestExecResponse struct {
	Exited   bool   `json:"exited"`
	ExitCode int    `json:"exitCode"`
	OutData  string `json:"outData,omitempty"`
	ErrData  string `json:"errData,omitempty"`
}

GuestExecResponse reports the completed guest process status.

type GuestPSRequest 

type GuestPSRequest struct{}

GuestPSRequest asks for the guest process list.

type GuestPSResponse 

type GuestPSResponse struct {
	ProcessList string `json:"processList,omitempty"`
}

GuestPSResponse reports the guest process list.

type GuestReadRequest 

type GuestReadRequest struct {
	Path string `json:"path"`
}

GuestReadRequest asks the guest agent to read a file.

type GuestReadResponse 

type GuestReadResponse struct {
	Path       string `json:"path"`
	DataBase64 string `json:"data-base64"`
}

GuestReadResponse reports base64-encoded file data read from the guest.

type GuestWriteRequest 

type GuestWriteRequest struct {
	Path       string `json:"path"`
	DataBase64 string `json:"data-base64"`
}

GuestWriteRequest asks the guest agent to write base64-encoded data to a file.

type GuestWriteResponse 

type GuestWriteResponse struct {
	Path string `json:"path"`
}

GuestWriteResponse reports the guest file path that was written.

type Handlers 

type Handlers struct {
	Core    RuntimeCore
	Guest   RuntimeGuest
	Suspend RuntimeSuspend
	Hotplug RuntimeHotplug
	Balloon RuntimeBalloon
}

Handlers groups the runtime capabilities used by a control router.

type HotplugRequest 

type HotplugRequest struct {
	ID     string `json:"id"`
	Detach bool   `json:"detach"`
}

HotplugRequest asks the runtime to attach or detach a configured device.

type HotplugResponse 

type HotplugResponse struct {
	ID     string `json:"id"`
	Detach bool   `json:"detach"`
}

HotplugResponse identifies the hotplug operation that completed.

type MethodsRequest 

type MethodsRequest struct{}

MethodsRequest asks which RPC methods are available on this control socket.

type MethodsResponse 

type MethodsResponse struct {
	Methods []string `json:"methods"`
}

MethodsResponse reports RPC methods available on this control socket.

type RPCError 

type RPCError struct {
	Code    ErrorCode `json:"code"`
	Message string    `json:"message"`
}

RPCError is the structured error returned over the control socket.

func (*RPCError) Error 

func (e *RPCError) Error() string

type Router 

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

Router dispatches typed control socket requests to runtime capabilities.

func NewRouter 

func NewRouter(handlers Handlers) (*Router, error)

NewRouter creates a router from explicit runtime capability handlers.

type RuntimeBalloon 

type RuntimeBalloon interface {
	Balloon(context.Context, BalloonRequest) (BalloonResponse, error)
}

RuntimeBalloon is implemented by runtimes that can control a memory balloon.

type RuntimeCore 

type RuntimeCore interface {
	Status(context.Context, StatusRequest) (StatusResponse, error)
}

RuntimeCore is the minimum runtime surface required by a control router.

type RuntimeGuest 

type RuntimeGuest interface {
	GuestPS(context.Context, GuestPSRequest) (GuestPSResponse, error)
	GuestExec(context.Context, GuestExecRequest) (GuestExecResponse, error)
	GuestRead(context.Context, GuestReadRequest) (GuestReadResponse, error)
	GuestWrite(context.Context, GuestWriteRequest) (GuestWriteResponse, error)
}

RuntimeGuest is implemented by handlers that can interact with the guest agent.

type RuntimeHotplug 

type RuntimeHotplug interface {
	Hotplug(context.Context, HotplugRequest) (HotplugResponse, error)
}

RuntimeHotplug is implemented by runtimes that can attach and detach devices.

type RuntimeState 

type RuntimeState string

RuntimeState is the lifecycle state reported by the control socket. 

const (
	// RuntimeStarting means the manager is still preparing the VM.
	RuntimeStarting RuntimeState = "starting"
	// RuntimeReady means the runtime is available for control requests.
	RuntimeReady RuntimeState = "ready"
	// RuntimeSuspending means a suspend request is in progress.
	RuntimeSuspending RuntimeState = "suspending"
	// RuntimeSuspended means VM state has been saved.
	RuntimeSuspended RuntimeState = "suspended"
	// RuntimeStopping means teardown has started.
	RuntimeStopping RuntimeState = "stopping"
	// RuntimeStopped means teardown has completed.
	RuntimeStopped RuntimeState = "stopped"
)

type RuntimeStats 

type RuntimeStats struct {
	StartedAt       time.Time `json:"startedAt,omitempty"`
	BootStartedAt   time.Time `json:"bootStartedAt,omitempty"`
	QMPReadyAt      time.Time `json:"qmpReadyAt,omitempty"`
	FilesReadyAt    time.Time `json:"filesReadyAt,omitempty"`
	SSHReadyAt      time.Time `json:"sshReadyAt,omitempty"`
	SSHStartedAt    time.Time `json:"sshStartedAt,omitempty"`
	CompletedAt     time.Time `json:"completedAt,omitempty"`
	SSHAttempts     int       `json:"sshAttempts,omitempty"`
	StartedToBoot   string    `json:"startedToBoot,omitempty"`
	BootToQMP       string    `json:"bootToQMP,omitempty"`
	FilesToSSH      string    `json:"filesToSSH,omitempty"`
	BootToCompleted string    `json:"bootToCompleted,omitempty"`
	Total           string    `json:"total,omitempty"`
}

RuntimeStats reports lifecycle timing captured during launch and teardown.

type RuntimeSuspend 

type RuntimeSuspend interface {
	Suspend(context.Context, SuspendRequest) (SuspendResponse, error)
}

RuntimeSuspend is implemented by runtimes that can save VM state.

type Server 

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

Server serves control socket requests for a router.

func NewServer 

func NewServer(h *Router) (*Server, error)

NewServer returns a closable control server for router.

func (*Server) Close 

func (s *Server) Close() error

Close stops accepting new control socket connections.

func (*Server) Serve 

func (s *Server) Serve(l net.Listener) error

Serve handles control requests from l until the listener closes.

type StatusPaths 

type StatusPaths struct {
	ControlSocket    string `json:"controlSocket"`
	QMPSocket        string `json:"qmpSocket"`
	GuestAgentSocket string `json:"guestAgentSocket,omitempty"`
	SSHReadySocket   string `json:"sshReadySocket,omitempty"`
}

StatusPaths are host-side sockets associated with the runtime.

type StatusRequest 

type StatusRequest struct{}

StatusRequest asks for the current runtime status.

type StatusResponse 

type StatusResponse struct {
	State RuntimeState `json:"state"`
	CID   int          `json:"cid"`
	Paths StatusPaths  `json:"paths"`
	Stats RuntimeStats `json:"stats"`
}

StatusResponse reports runtime status and connection paths.

type SuspendRequest 

type SuspendRequest struct{}

SuspendRequest asks the runtime to save VM state and exit.

type SuspendResponse 

type SuspendResponse struct {
	Saved       bool   `json:"saved"`
	VMStatePath string `json:"vmStatePath,omitempty"`
}

SuspendResponse reports whether suspend state was saved.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.