instances

type AttachVolumeRequest struct {
	MountPath string
	Readonly  bool
}

type CreateInstanceRequest struct {
	Name                     string                      // Required
	Image                    string                      // Required: OCI reference
	Platform                 string                      // Optional: target platform as os/arch[/variant]; drives image resolution and auto-pull. Empty means host platform.
	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
	Tags                     tags.Tags                   // Optional user-defined key-value tags
	NetworkEnabled           bool                        // Whether to enable networking (uses default network)
	NetworkEgress            *NetworkEgressPolicy        // Optional host-mediated egress policy
	Credentials              map[string]CredentialPolicy // Optional host-managed credential brokering policies
	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)
	HypervisorVersion        string                      // Optional: hypervisor version (defaults to configured default)
	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)
	SnapshotPolicy           *SnapshotPolicy             // Optional snapshot policy defaults for this instance
	AutoStandby              *autostandby.Policy         // Optional automatic standby policy
	HealthCheck              *healthcheck.Policy         // Optional workload health check policy
	RestartPolicy            *restartpolicy.Policy       // Optional whole-instance restart policy
}

type CreateSnapshotRequest struct {
	Kind        SnapshotKind                        // Required: Standby or Stopped
	Name        string                              // Optional: unique per source instance
	Tags        tags.Tags                           // Optional user-defined key-value tags
	Compression *snapshot.SnapshotCompressionConfig // Optional compression override
}

type CredentialInjectAs struct {
	Header string // Header name to set/mutate
	Format string // Format template containing ${value}
}

type CredentialInjectRule struct {
	Hosts []string           // Optional host patterns (api.example.com, *.example.com); empty means all
	As    CredentialInjectAs // Current v1 injection shape
}

type CredentialPolicy struct {
	Source CredentialSource
	Inject []CredentialInjectRule
}

type CredentialSource struct {
	Env string // Host env variable name
}

type EgressEnforcementMode string

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 ForkSnapshotRequest struct {
	Name             string          // Required: name for the new instance
	TargetState      State           // Optional
	TargetHypervisor hypervisor.Type // Optional, allowed only for Stopped snapshots
}

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

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

type HostTopology struct {
	ThreadsPerCore int
	CoresPerSocket int
	Sockets        int
}

type ImageUsageRecorder interface {
	MarkUsed(ctx context.Context, imageName, digest string) error
}

type ImageUsageRecorderSetter interface {
	SetImageUsageRecorder(recorder ImageUsageRecorder)
}

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 + guest boot markers
	StateError          *string // Error message if state couldn't be determined (non-nil when State=Unknown)
	HasSnapshot         bool    // Derived from filesystem check
	BootMarkersHydrated bool    // True when missing boot markers were hydrated from logs in this read
	HealthCheckRuntime  *healthcheck.Runtime
}

type LifecycleEvent struct {
	Action     LifecycleEventAction
	InstanceID string
	Instance   *Instance
}

type LifecycleEventAction string

type LifecycleEventConsumer string

type ListInstancesFilter struct {
	State *State    // Filter by instance state
	Tags  tags.Tags // Filter by tag key-value pairs (all must match)
}

type ListSnapshotsFilter = snapshot.ListSnapshotsFilter

type LogSource string

type Manager interface {
	ListInstances(ctx context.Context, filter *ListInstancesFilter) ([]Instance, error)
	ListSnapshots(ctx context.Context, filter *ListSnapshotsFilter) ([]Snapshot, error)
	GetSnapshot(ctx context.Context, snapshotID string) (*Snapshot, error)
	CreateInstance(ctx context.Context, req CreateInstanceRequest) (*Instance, error)
	CreateSnapshot(ctx context.Context, id string, req CreateSnapshotRequest) (*Snapshot, 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
	DeleteSnapshot(ctx context.Context, snapshotID string) error
	ForkInstance(ctx context.Context, id string, req ForkInstanceRequest) (*Instance, error)
	ForkSnapshot(ctx context.Context, snapshotID string, req ForkSnapshotRequest) (*Instance, error)
	StandbyInstance(ctx context.Context, id string, req StandbyInstanceRequest) (*Instance, error)
	RestoreInstance(ctx context.Context, id string) (*Instance, error)
	RestoreSnapshot(ctx context.Context, id string, snapshotID string, req RestoreSnapshotRequest) (*Instance, error)
	StopInstance(ctx context.Context, id string) (*Instance, error)
	StartInstance(ctx context.Context, id string, req StartInstanceRequest) (*Instance, error)
	UpdateInstance(ctx context.Context, id string, req UpdateInstanceRequest) (*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)
	// SubscribeLifecycleEvents returns the shared internal lifecycle event stream.
	SubscribeLifecycleEvents(consumer LifecycleEventConsumer) (<-chan LifecycleEvent, func())
}

type ManagerConfig struct {
	LifecycleEventBufferSize          int
	FirecrackerSnapshotMemoryBackend  string
	FirecrackerUFFDCacheMaxBytes      int64
	MaxConcurrentRestoresByHypervisor map[hypervisor.Type]int
}

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

type NetworkEgressPolicy struct {
	Enabled         bool                  // Whether host-mediated egress policy is enabled
	EnforcementMode EgressEnforcementMode // all (default) blocks direct non-proxy TCP egress, http_https_only blocks only 80/443
}

type PendingStandbyCompression struct {
	Policy    snapshot.SnapshotCompressionConfig
	NotBefore time.Time
}

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, diskBytes int64, needsGPU bool) error
	// ReserveAllocation tentatively reserves resources for an in-flight operation.
	// Call FinishAllocation once the operation fails or becomes visible to resource accounting.
	ReserveAllocation(ctx context.Context, instanceID string, vcpus int, memoryBytes int64, networkDownloadBps int64, networkUploadBps int64, diskIOBps int64, diskBytes int64, needsGPU bool) error
	// FinishAllocation removes any pending reservation for the given instance ID.
	FinishAllocation(instanceID string)
}

type RestoreSnapshotRequest struct {
	TargetState      State           // Optional
	TargetHypervisor hypervisor.Type // Optional, allowed only for Stopped snapshots
}

type SetSnapshotScheduleRequest = scheduledsnapshots.SetRequest

type Snapshot = snapshot.Snapshot

type SnapshotKind = snapshot.SnapshotKind

type SnapshotPolicy struct {
	Compression             *snapshot.SnapshotCompressionConfig
	StandbyCompressionDelay *time.Duration
}

type SnapshotSchedule = scheduledsnapshots.Schedule

type SnapshotScheduleManager interface {
	SetSnapshotSchedule(ctx context.Context, instanceID string, req SetSnapshotScheduleRequest) (*SnapshotSchedule, error)
	GetSnapshotSchedule(ctx context.Context, instanceID string) (*SnapshotSchedule, error)
	DeleteSnapshotSchedule(ctx context.Context, instanceID string) error
	RunSnapshotSchedules(ctx context.Context) error
}

type SnapshotScheduleRetention = scheduledsnapshots.Retention

type StandbyInstanceRequest struct {
	Compression      *snapshot.SnapshotCompressionConfig // Optional compression override
	CompressionDelay *time.Duration                      // Optional standby-only compression delay override
}

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 as supplied by the caller (tag or digest); the display/API value

	// ResolvedImage is the digest-pinned reference (repo@sha256:...) of the
	// image actually resolved at create time. It is the source of truth for
	// locating the rootfs on boot/start/restore, so a mutable tag (last-pull-wins)
	// can't drift the instance to a different image/arch across restarts. Internal;
	// not exposed on the API. Empty for instances created before this field existed
	// (callers fall back to Image via bootImageRef).
	ResolvedImage string

	// Platform is the resolved image platform as os/arch[/variant] (e.g.
	// "linux/amd64"), captured from the pulled image's metadata at create time.
	// Read-only; echoed on the instance API.
	Platform string

	// 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
	Tags           tags.Tags // User-defined key-value tags
	NetworkEnabled bool      // Whether instance has networking enabled (uses default network)
	NetworkEgress  *NetworkEgressPolicy
	Credentials    map[string]CredentialPolicy
	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 // Boot epoch start time (set on create/start; preserved across standby restore)
	StoppedAt *time.Time // Last time VM was stopped

	// Boot progress markers (derived from guest serial log sentinels and persisted)
	ProgramStartedAt  *time.Time // Set when guest program handoff/start boundary is reached
	GuestAgentReadyAt *time.Time // Set when guest-agent is ready (unless skip_guest_agent=true)

	// 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., "v51.1")
	HypervisorPID     *int            // Hypervisor process ID (may be stale after host restart)

	// Firecracker UFFD snapshot restore metadata.
	FirecrackerSnapshotCacheKey           string
	FirecrackerUseUFFDOnNextRestore       bool
	FirecrackerUFFDSessionID              string
	FirecrackerUFFDPagerVersion           string
	FirecrackerDeferredSnapshotMemoryPath string

	// 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)

	// EnableRosetta attaches an Apple Rosetta virtio-fs share so the guest can
	// execute x86-64 binaries. vz on Apple silicon only. Derived internally when
	// the image platform differs from the host; not a user-facing field.
	EnableRosetta bool

	// Snapshot policy defaults for this instance.
	SnapshotPolicy *SnapshotPolicy

	// Pending standby compression plan for the latest standby snapshot.
	// Persisted so server restarts can recover delayed or interrupted jobs.
	PendingStandbyCompression *PendingStandbyCompression

	// Automatic standby policy driven by host-observed inbound TCP activity.
	AutoStandby *autostandby.Policy

	// Workload health check policy. Health is reported separately from lifecycle state.
	HealthCheck *healthcheck.Policy

	// Whole-instance restart supervision policy and runtime status.
	RestartPolicy *restartpolicy.Policy
	RestartStatus restartpolicy.Status

	// 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")

	// Cumulative time spent in each lifecycle phase. Updated at every state
	// transition by transition orchestration sites (create/start/stop/standby/
	// restore/fork). Consumers use Snapshot() to read live values that include
	// time accrued in the current phase. See lib/instances/phasetracking.
	Phases phasetracking.Tracker `json:"phases,omitempty"`
}

type UpdateInstanceRequest struct {
	Env              map[string]string     // Updated environment variables (merged with existing)
	AutoStandby      *autostandby.Policy   // Replaces the persisted auto-standby policy when non-nil
	HealthCheck      *healthcheck.Policy   // Replaces the persisted health check policy when non-nil
	RestartPolicy    *restartpolicy.Policy // Replaces the persisted restart policy when non-nil
	RestartPolicySet bool                  // True when restart policy was present in the update request
}

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)
}

type WaitForStateResult struct {
	State      State
	StateError *string
	TimedOut   bool
}