instances

type AttachVolumeRequest struct {
	MountPath string
	Readonly  bool
}

type CreateInstanceRequest struct {
	Name                     string             // Required
	Image                    string             // Required: OCI reference
	Size                     int64              // Base memory in bytes (default: 1GB)
	HotplugSize              int64              // Hotplug memory in bytes (default: 0, set explicitly to enable)
	OverlaySize              int64              // Overlay disk size in bytes (default: 10GB)
	Vcpus                    int                // Default 2
	NetworkBandwidthDownload int64              // Download rate limit bytes/sec (0 = auto, proportional to CPU)
	NetworkBandwidthUpload   int64              // Upload rate limit bytes/sec (0 = auto, proportional to CPU)
	DiskIOBps                int64              // Disk I/O rate limit bytes/sec (0 = auto, proportional to CPU)
	Env                      map[string]string  // Optional environment variables
	Metadata                 map[string]string  // Optional user-defined key-value metadata
	NetworkEnabled           bool               // Whether to enable networking (uses default network)
	Devices                  []string           // Device IDs or names to attach (GPU passthrough)
	Volumes                  []VolumeAttachment // Volumes to attach at creation time
	Hypervisor               hypervisor.Type    // Optional: hypervisor type (defaults to config)
	GPU                      *GPUConfig         // Optional: vGPU configuration
	Entrypoint               []string           // Override image entrypoint (nil = use image default)
	Cmd                      []string           // Override image cmd (nil = use image default)
	SkipKernelHeaders        bool               // Skip kernel headers installation (disables DKMS)
	SkipGuestAgent           bool               // Skip guest-agent installation (disables exec/stat API)
}

type ForkInstanceRequest struct {
	Name        string // Required: name for the new forked instance
	FromRunning bool   // Optional: allow forking from Running by auto standby/fork/restore
	TargetState State  // Optional: desired final state of forked instance (Stopped, Standby, Running). Empty means inherit source state.
}

type GPUConfig struct {
	Profile string // vGPU profile name (e.g., "L40S-1Q")
}

type HostTopology struct {
	ThreadsPerCore int
	CoresPerSocket int
	Sockets        int
}

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

type Instance struct {
	StoredMetadata

	// Derived fields (not stored in metadata.json)
	State       State   // Derived from socket + VMM query
	StateError  *string // Error message if state couldn't be determined (non-nil when State=Unknown)
	HasSnapshot bool    // Derived from filesystem check
}

type ListInstancesFilter struct {
	State    *State            // Filter by instance state
	Metadata map[string]string // Filter by metadata key-value pairs (all must match)
}

type LogSource string

type Manager interface {
	ListInstances(ctx context.Context, filter *ListInstancesFilter) ([]Instance, error)
	CreateInstance(ctx context.Context, req CreateInstanceRequest) (*Instance, error)
	// GetInstance returns an instance by ID, name, or ID prefix.
	// Lookup order: exact ID match -> exact name match -> ID prefix match.
	// Returns ErrAmbiguousName if prefix matches multiple instances.
	GetInstance(ctx context.Context, idOrName string) (*Instance, error)
	DeleteInstance(ctx context.Context, id string) error
	ForkInstance(ctx context.Context, id string, req ForkInstanceRequest) (*Instance, error)
	StandbyInstance(ctx context.Context, id string) (*Instance, error)
	RestoreInstance(ctx context.Context, id string) (*Instance, error)
	StopInstance(ctx context.Context, id string) (*Instance, error)
	StartInstance(ctx context.Context, id string, req StartInstanceRequest) (*Instance, error)
	StreamInstanceLogs(ctx context.Context, id string, tail int, follow bool, source LogSource) (<-chan string, error)
	RotateLogs(ctx context.Context, maxBytes int64, maxFiles int) error
	AttachVolume(ctx context.Context, id string, volumeId string, req AttachVolumeRequest) (*Instance, error)
	DetachVolume(ctx context.Context, id string, volumeId string) (*Instance, error)
	// ListInstanceAllocations returns resource allocations for all instances.
	// Used by the resource manager for capacity tracking.
	ListInstanceAllocations(ctx context.Context) ([]resources.InstanceAllocation, error)
	// ListRunningInstancesInfo returns info needed for utilization metrics collection.
	// Used by the resource manager for VM utilization tracking.
	ListRunningInstancesInfo(ctx context.Context) ([]resources.InstanceUtilizationInfo, error)
	// SetResourceValidator sets the validator for aggregate resource limit checking.
	// Called after initialization to avoid circular dependencies.
	SetResourceValidator(v ResourceValidator)
	// GetVsockDialer returns a VsockDialer for the specified instance.
	GetVsockDialer(ctx context.Context, instanceID string) (hypervisor.VsockDialer, error)
}

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

type ResourceLimits struct {
	MaxOverlaySize       int64 // Maximum overlay disk size in bytes per instance
	MaxVcpusPerInstance  int   // Maximum vCPUs per instance (0 = unlimited)
	MaxMemoryPerInstance int64 // Maximum memory in bytes per instance (0 = unlimited)
}

type ResourceValidator interface {
	// ValidateAllocation checks if the requested resources are available.
	// Returns nil if allocation is allowed, or a detailed error describing
	// which resource is insufficient and the current capacity/usage.
	ValidateAllocation(ctx context.Context, vcpus int, memoryBytes int64, networkDownloadBps int64, networkUploadBps int64, diskIOBps int64, needsGPU bool) error
}

type StartInstanceRequest struct {
	Entrypoint []string // Override entrypoint (nil = keep previous/image default)
	Cmd        []string // Override cmd (nil = keep previous/image default)
}

type State string

type StoredMetadata struct {
	// Identification
	Id    string // Auto-generated CUID2
	Name  string
	Image string // OCI reference

	// Resources (matching Cloud Hypervisor terminology)
	Size                     int64 // Base memory in bytes
	HotplugSize              int64 // Hotplug memory in bytes
	OverlaySize              int64 // Overlay disk size in bytes
	Vcpus                    int
	NetworkBandwidthDownload int64 // Download rate limit in bytes/sec (external→VM), 0 = auto
	NetworkBandwidthUpload   int64 // Upload rate limit in bytes/sec (VM→external), 0 = auto
	DiskIOBps                int64 // Disk I/O rate limit in bytes/sec, 0 = auto

	// Configuration
	Env            map[string]string
	Metadata       map[string]string // User-defined key-value metadata
	NetworkEnabled bool              // Whether instance has networking enabled (uses default network)
	IP             string            // Assigned IP address (empty if NetworkEnabled=false)
	MAC            string            // Assigned MAC address (empty if NetworkEnabled=false)

	// Attached volumes
	Volumes []VolumeAttachment // Volumes attached to this instance

	// Timestamps (stored for historical tracking)
	CreatedAt time.Time
	StartedAt *time.Time // Last time VM was started
	StoppedAt *time.Time // Last time VM was stopped

	// Versions
	KernelVersion string // Kernel version (e.g., "ch-v6.12.9")

	// Hypervisor configuration
	HypervisorType    hypervisor.Type // Hypervisor type (e.g., "cloud-hypervisor")
	HypervisorVersion string          // Hypervisor version (e.g., "v49.0")
	HypervisorPID     *int            // Hypervisor process ID (may be stale after host restart)

	// Paths
	SocketPath string // Path to API socket
	DataDir    string // Instance data directory

	// vsock configuration
	VsockCID    int64  // Guest vsock Context ID
	VsockSocket string // Host-side vsock socket path

	// Attached devices (GPU passthrough)
	Devices []string // Device IDs attached to this instance

	// GPU configuration (vGPU mode)
	GPUProfile  string // vGPU profile name (e.g., "L40S-1Q")
	GPUMdevUUID string // mdev device UUID

	// Command overrides (like docker run <image> <command>)
	Entrypoint []string // Override image entrypoint (nil = use image default)
	Cmd        []string // Override image cmd (nil = use image default)

	// Boot optimizations
	SkipKernelHeaders bool // Skip kernel headers installation (disables DKMS)
	SkipGuestAgent    bool // Skip guest-agent installation (disables exec/stat API)

	// Shutdown configuration
	StopTimeout int // Grace period in seconds for graceful stop (0 = use default 5s)

	// Exit information (populated from serial console sentinel when VM stops)
	ExitCode    *int   // App exit code, nil if VM hasn't exited
	ExitMessage string // Human-readable description of exit (e.g., "command not found", "killed by signal 9 (SIGKILL) - OOM")
}

type VolumeAttachment struct {
	VolumeID    string // Volume ID
	MountPath   string // Mount path in guest
	Readonly    bool   // Whether mounted read-only
	Overlay     bool   // If true, create per-instance overlay for writes (requires Readonly=true)
	OverlaySize int64  // Size of overlay disk in bytes (max diff from base)
}