vm

type Instance interface {
	// SetCPUAndMemory configures the number of vCPUs and RAM (in MiB)
	// that will be exposed to the guest when the VM starts. It must be
	// called before [Instance.Start].
	SetCPUAndMemory(ctx context.Context, cpu uint8, ram uint32) error

	// AddFS attaches a host directory mountPath to the guest as a
	// virtio-fs share identified by tag. The guest mounts the share by
	// referring to tag. Must be called before [Instance.Start].
	AddFS(ctx context.Context, tag, mountPath string, opts ...MountOpt) error

	// AddDisk attaches a host file at mountPath to the guest as a virtio
	// block device identified by blockID. Use [WithReadOnly] for
	// read-only attachment and [WithVmdk] when the file is a VMDK image.
	// Must be called before [Instance.Start].
	AddDisk(ctx context.Context, blockID, mountPath string, opts ...MountOpt) error

	// AddNIC attaches a virtio-net interface to the guest. endpoint is
	// the path to the host-side AF_UNIX socket that bridges packets to
	// the network helper, mac is the link-layer address presented to the
	// guest, and mode selects the socket framing (see [NetworkMode]).
	// Implementation-specific tuning is supplied via [NetworkOpt]
	// values; see [WithNICFeatures] and [WithNICFlags]. Must be called
	// before [Instance.Start].
	AddNIC(ctx context.Context, endpoint string, mac net.HardwareAddr, mode NetworkMode, opts ...NetworkOpt) error

	// Start boots the VM and waits for the guest agent (vminitd) to
	// connect back over the TTRPC control channel. Configuration methods
	// must not be called after Start. Returns an error if the VM exits or
	// the guest fails to connect within an implementation-defined
	// timeout.
	Start(ctx context.Context, opts ...StartOpt) error

	// Client returns the TTRPC client connected to the guest agent. The
	// returned client is valid only after a successful [Instance.Start]
	// and until [Instance.Shutdown] is called. The client is shared and
	// must not be closed by callers.
	Client() *ttrpc.Client

	// Shutdown stops the VM, closes the TTRPC connection, and releases
	// associated host resources. It is safe to call Shutdown on a VM that
	// failed to start. The instance is not reusable after Shutdown
	// returns.
	Shutdown(context.Context) error

	// StartStream opens a raw bidirectional byte stream into the VM,
	// identified by streamID. The guest side claims the stream by
	// presenting the same ID; see docs/vsock-streaming.md for the
	// coordination protocol. The returned net.Conn is owned by the
	// caller, who must Close it when done.
	//
	// If the underlying transport is not yet available (for example, the
	// VM is still booting), StartStream retries for an
	// implementation-defined window before returning an error wrapping
	// errdefs.ErrUnavailable.
	//
	// opts is reserved for future per-stream configuration; no options
	// are currently defined.
	//
	// TODO: Consider making this interface optional, a per RPC implementation
	// is possible but likely less efficient.
	StartStream(ctx context.Context, streamID string, opts ...StreamOpt) (net.Conn, error)
}

type Manager interface {
	// NewInstance constructs a new VM instance whose runtime state
	// (sockets, FIFOs, console pipes, etc.) is rooted at the directory
	// given by state. The state directory must already exist and be
	// writable. The returned instance is not yet running; configure it via
	// the SetCPUAndMemory / AddFS / AddDisk / AddNIC methods and then call
	// [Instance.Start].
	NewInstance(ctx context.Context, state string) (Instance, error)
}

type MountConfig struct {
	// Readonly mounts the filesystem or disk read-only inside the guest.
	Readonly bool

	// Vmdk indicates that the backing file is a VMDK image rather than a
	// raw block device. Only meaningful for [Instance.AddDisk].
	Vmdk bool
}

type MountOpt func(*MountConfig)

type NetworkMode int

type NetworkOpt func(*NetworkOpts)

type NetworkOpts struct {
	// Features is a bitmask of implementation-specific virtio-net feature
	// bits. Zero means "use the implementation default".
	Features uint32

	// Flags is a bitmask of implementation-specific virtio-net flags.
	// Zero means "use the implementation default".
	Flags uint32
}

type StartOpt func(*StartOpts)

type StartOpts struct {
	// InitArgs are appended to the command line of the guest init process
	// (vminitd). They are interpreted by vminitd, not by the kernel.
	InitArgs []string

	// ConsoleWriter, if non-nil, receives a copy of the guest serial
	// console output in addition to the implementation's default sink
	// (typically os.Stderr). Useful for capturing boot logs in tests.
	ConsoleWriter io.Writer
}

type StreamOpt func(*StreamOpts)

type StreamOpts struct{}