hypervisor

type CPUTopology struct {
	ThreadsPerCore int
	CoresPerDie    int
	DiesPerPackage int
	Packages       int
}

type Capabilities struct {
	// SupportsSnapshot indicates if Snapshot/Restore are available
	SupportsSnapshot bool

	// SupportsHotplugMemory indicates if ResizeMemory is available
	SupportsHotplugMemory bool

	// SupportsPause indicates if Pause/Resume are available
	SupportsPause bool

	// SupportsVsock indicates if vsock communication is available
	SupportsVsock bool

	// SupportsGPUPassthrough indicates if PCI device passthrough is available
	SupportsGPUPassthrough bool

	// SupportsDiskIOLimit indicates if disk I/O rate limiting is available
	SupportsDiskIOLimit bool
}

type ClientFactory func(socketPath string) (Hypervisor, error)

type DiskConfig struct {
	Path       string
	Readonly   bool
	IOBps      int64 // Sustained I/O rate limit in bytes/sec (0 = unlimited)
	IOBurstBps int64 // Burst I/O rate in bytes/sec (0 = same as IOBps)
}

type ForkNetworkConfig struct {
	TAPDevice string
	IP        string
	MAC       string
	Netmask   string
}

type ForkPrepareRequest struct {
	// SnapshotConfigPath is optional. When empty, implementations should only
	// validate fork support and return without snapshot rewrites.
	SnapshotConfigPath string

	SourceDataDir string
	TargetDataDir string

	VsockCID    int64
	VsockSocket string

	SerialLogPath string
	Network       *ForkNetworkConfig
}

type ForkPrepareResult struct {
	// VsockCIDUpdated indicates whether snapshot state was updated to use
	// ForkPrepareRequest.VsockCID.
	VsockCIDUpdated bool
}

type Hypervisor interface {
	// DeleteVM sends a graceful shutdown signal to the guest.
	DeleteVM(ctx context.Context) error

	// Shutdown stops the VMM process gracefully.
	Shutdown(ctx context.Context) error

	// GetVMInfo returns current VM state information.
	GetVMInfo(ctx context.Context) (*VMInfo, error)

	// Pause suspends VM execution.
	// Check Capabilities().SupportsPause before calling.
	Pause(ctx context.Context) error

	// Resume continues VM execution after pause.
	// Check Capabilities().SupportsPause before calling.
	Resume(ctx context.Context) error

	// Snapshot creates a VM snapshot at the given path.
	// Check Capabilities().SupportsSnapshot before calling.
	Snapshot(ctx context.Context, destPath string) error

	// ResizeMemory changes the VM's memory allocation.
	// Check Capabilities().SupportsHotplugMemory before calling.
	ResizeMemory(ctx context.Context, bytes int64) error

	// ResizeMemoryAndWait changes the VM's memory allocation and waits for it to stabilize.
	// This polls until the actual memory size matches the target or stabilizes.
	// Check Capabilities().SupportsHotplugMemory before calling.
	ResizeMemoryAndWait(ctx context.Context, bytes int64, timeout time.Duration) error

	// Capabilities returns what features this hypervisor supports.
	Capabilities() Capabilities
}

type NetworkConfig struct {
	TAPDevice string
	IP        string
	MAC       string
	Netmask   string
	// DownloadBps limits host->guest bandwidth in bytes/sec (0 = unlimited).
	// Hypeman enforces this host-side via TAP shaping for all hypervisors.
	// Firecracker also maps it to per-interface API rate limiters.
	DownloadBps int64
	// UploadBps limits guest->host bandwidth in bytes/sec (0 = unlimited).
	// Hypeman enforces this host-side via TAP shaping for all hypervisors.
	// Firecracker also maps it to per-interface API rate limiters.
	UploadBps int64
}

type Type string

type VMConfig struct {
	// Compute resources
	VCPUs        int
	MemoryBytes  int64
	HotplugBytes int64
	Topology     *CPUTopology

	// Storage
	Disks []DiskConfig

	// Network
	Networks []NetworkConfig

	// Console
	SerialLogPath string

	// Vsock
	VsockCID    int64
	VsockSocket string

	// PCI device passthrough (GPU, etc.)
	PCIDevices []string

	// Boot configuration
	KernelPath string
	InitrdPath string
	KernelArgs string
}

type VMInfo struct {
	State            VMState
	MemoryActualSize *int64 // Current actual memory size in bytes (if available)
}

type VMStarter interface {
	// SocketName returns the socket filename for this hypervisor.
	// Uses short names to stay within Unix socket path length limits (SUN_LEN ~108 bytes).
	SocketName() string

	// GetBinaryPath returns the path to the hypervisor binary, extracting if needed.
	GetBinaryPath(p *paths.Paths, version string) (string, error)

	// GetVersion returns the version of the hypervisor binary.
	// For embedded binaries (Cloud Hypervisor), returns the latest supported version.
	// For system binaries (QEMU), queries the installed binary for its version.
	GetVersion(p *paths.Paths) (string, error)

	// StartVM launches the hypervisor process and boots the VM.
	// Returns the process ID and a Hypervisor client for subsequent operations.
	StartVM(ctx context.Context, p *paths.Paths, version string, socketPath string, config VMConfig) (pid int, hv Hypervisor, err error)

	// RestoreVM starts the hypervisor and restores VM state from a snapshot.
	// Each hypervisor implements its own restore flow:
	// - Cloud Hypervisor: starts process, calls Restore API
	// - QEMU: would start with -incoming or -loadvm flags (not yet implemented)
	// Returns the process ID and a Hypervisor client. The VM is in paused state after restore.
	RestoreVM(ctx context.Context, p *paths.Paths, version string, socketPath string, snapshotPath string) (pid int, hv Hypervisor, err error)

	// PrepareFork allows hypervisors to prepare forked instance state.
	// For snapshot-based forks, implementations can rewrite snapshot config with
	// fork identity (paths, vsock, network). Hypervisors that don't support fork
	// should return ErrNotSupported.
	PrepareFork(ctx context.Context, req ForkPrepareRequest) (ForkPrepareResult, error)
}

type VMState string

type VsockDialer interface {
	// DialVsock connects to the guest on the specified port.
	// Returns a net.Conn that can be used for bidirectional communication.
	DialVsock(ctx context.Context, port int) (net.Conn, error)

	// Key returns a unique identifier for this dialer, used for connection pooling.
	Key() string
}

type VsockDialerFactory func(vsockSocket string, vsockCID int64) VsockDialer