instance

type Capacity struct {
	// Host is what the host has: its logical CPUs and its memory.
	Host Resources `json:"host"`

	// ReservedMemoryBytes is withheld from instances altogether.
	ReservedMemoryBytes int64 `json:"reserved_memory_bytes"`

	// CPUOvercommit scales the host's CPUs into the vCPUs instances may be
	// given: 4 lets four vCPUs share each CPU.
	CPUOvercommit float64 `json:"cpu_overcommit"`
	// MemoryOvercommit scales the host's memory, less ReservedMemoryBytes,
	// into the memory instances may be given.
	MemoryOvercommit float64 `json:"memory_overcommit"`
}

type Config struct {
	// Store keeps the definitions of instances and snapshots.
	Store Store
	// Networks defines the networks and attaches instances to them.
	Networks Networks

	// RunDir holds ephemeral runtime state. Empty is defaults.RunDir.
	RunDir string

	// Images provides the images instances boot from.
	Images Images
	// Kernels looks up the kernels instances boot.
	Kernels Kernels
	// Volumes looks up the volumes instances mount.
	Volumes Volumes
	// Initrds provides the initramfs guests boot from.
	Initrds Initrds
	// Starters launch VMMs, one for each hypervisor version the daemon
	// carries, by type. The first of each type is its default version.
	Starters map[hypervisor.Type][]hypervisor.Starter

	// Shares, if set, lets instances mount host directories. Without it,
	// an instance that mounts one cannot start.
	Shares Shares
	// AllowedDirectories are the host directories instances may mount. An
	// instance that mounts any other cannot start.
	AllowedDirectories hostfs.AllowedDirectories

	// Capacity limits the CPU and memory instances may be given. The zero
	// value is unlimited.
	Capacity Capacity

	// Events records what happens to instances. Nil records nothing.
	Events Recorder
	// Logger is where the Manager logs. Nil is slog.Default().
	Logger *slog.Logger
}

type Exit struct {
	// Code is the exit code the guest reported, if it reported one. A clean
	// end always has one.
	Code *int

	// Failure is why the end was not clean, or nil if it was.
	Failure error
}

type FrozenGuest struct {
	// Instance is the definition of the instance the guest belonged to, as
	// it was when the guest was frozen.
	Instance Spec `yaml:"instance" json:"instance"`

	// IP is the guest's address on its network, which it keeps.
	IP string `yaml:"ip,omitempty" json:"ip,omitempty"`
	// MAC is the hardware address of the guest's network interface.
	MAC string `yaml:"mac,omitempty" json:"mac,omitempty"`

	// HypervisorType is the hypervisor that froze the guest. Only it can
	// resume the guest.
	HypervisorType hypervisor.Type `yaml:"hypervisor_type,omitempty" json:"hypervisor_type,omitempty"`
	// HypervisorVersion is the version of that hypervisor, which must match
	// as well.
	HypervisorVersion string `yaml:"hypervisor_version,omitempty" json:"hypervisor_version,omitempty"`

	// VCPUs is how many vCPUs the guest ran with, which a resume is admitted
	// on. It can differ from Instance's after a resize.
	VCPUs int `yaml:"vcpus,omitempty" json:"vcpus,omitempty"`
	// MemoryBytes is how much memory the guest ran with, as VCPUs is.
	MemoryBytes int64 `yaml:"memory_bytes,omitempty" json:"memory_bytes,omitempty"`
	// ImageDigest is the image the guest booted from, which a resume pulls
	// if the host no longer has it.
	ImageDigest string `yaml:"image_digest,omitempty" json:"image_digest,omitempty"`
}

type HeldResources struct {
	// Name is the instance's name.
	Name string `json:"name"`
	// State is the instance's state: starting, running or paused.
	State State `json:"state"`
	// Resources is what the instance holds.
	Resources Resources `json:"resources"`
}

type Images interface {
	Ensure(ctx context.Context, ref string, policy image.PullPolicy) (*image.Image, error)
}

type Initrds interface {
	Prepare(ctx context.Context) (string, error)
}

type Instance struct {
	// Spec is the instance's definition.
	Spec Spec `json:"spec"`
	// Status is what was last observed of the instance.
	Status Status `json:"status"`
}

type Kernels interface {
	Kernel(nameOrID string) (kernel.Kernel, error)
	Path(k kernel.Kernel) (string, error)
}

type LogOptions struct {
	// Source is which log. Empty is the guest's console.
	Source LogSource

	// TailLines limits the output to the last lines. Zero means all of it.
	TailLines int

	// Follow keeps writing new output until the instance stops or the
	// context is cancelled.
	Follow bool
}

type LogSource string

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

type Mount struct {
	// Type is what the mount attaches.
	Type MountType `yaml:"type" json:"type"`

	// Source is the volume's name for a volume, and the host directory's
	// absolute path for a directory. A file and a tmpfs have none.
	Source string `yaml:"source,omitempty" json:"source,omitempty"`

	// Target is the absolute path the mount appears at in the guest.
	Target string `yaml:"target" json:"target"`

	// ReadOnly stops the guest writing to the mount. A volume that every
	// instance attaching it mounts read-only can be shared between them.
	ReadOnly bool `yaml:"read_only,omitempty" json:"read_only,omitempty"`

	// Content is a file's contents. Only a file has them.
	Content []byte `yaml:"content,omitempty" json:"content,omitempty"`

	// Mode is a file's permission bits in the guest, where root owns it.
	// Zero is 0644.
	Mode uint32 `yaml:"mode,omitempty" json:"mode,omitempty"`
}

type MountType string

type Networks interface {
	Network(nameOrID string) (network.Network, error)
	Networks() []network.Network
	AttachInstance(
		ctx context.Context, n network.Network, instanceID string, opts network.AttachOptions,
	) (network.Attachment, error)
	ConnectInstance(ctx context.Context, n network.Network, instanceID string) error
	DetachInstance(ctx context.Context, n network.Network, instanceID string)
	Allocation(networkName, instanceID string) (network.Allocation, error)
	InstanceAt(networkName, ip string) (instanceID string, ok bool)
	Release(networkName, instanceID string) error
	Reconcile(networks []string, live map[string]struct{}) (int, error)
}

type Recorder interface {
	Record(e event.Event)
}

type Resources struct {
	// VCPUs is a number of vCPUs.
	VCPUs int `json:"vcpus"`
	// MemoryBytes is an amount of guest memory.
	MemoryBytes int64 `json:"memory_bytes"`
}

type RestartMode string

type RestartPolicy struct {
	// Mode is when the instance is restarted. Empty is RestartModeNo.
	Mode RestartMode `yaml:"mode,omitempty" json:"mode,omitempty"`

	// MaxRetries is how many times in a row an on-failure instance is
	// restarted before it is left Failed. Zero means no limit.
	MaxRetries int `yaml:"max_retries,omitempty" json:"max_retries,omitempty"`
}

type Shares interface {
	Start(ctx context.Context, s virtiofs.Share) (*process.Process, error)
}

type Snapshot struct {
	// ID identifies the snapshot for as long as it exists.
	ID string `yaml:"id" json:"id"`
	// Name is what people call the snapshot. No two on a host share one.
	Name string `yaml:"name" json:"name"`
	// Kind says whether the snapshot holds a guest, or a disk alone.
	Kind SnapshotKind `yaml:"kind" json:"kind"`

	// FrozenGuest is what the snapshot's guest ran with. A disk snapshot
	// has its Instance alone.
	FrozenGuest `yaml:",inline"`

	// CreatedAt is when the snapshot was taken.
	CreatedAt time.Time `yaml:"created_at" json:"created_at"`

	// SizeBytes is the space the snapshot occupies, measured when read.
	SizeBytes int64 `yaml:"-" json:"-"`
}

type SnapshotKind string

type Spec struct {
	// ID identifies the instance for as long as it is defined. What the
	// host holds for the instance is named after it.
	ID string `yaml:"id" json:"id"`
	// Name is what people call the instance. No two instances on a host
	// share one.
	Name string `yaml:"name" json:"name"`
	// Hostname is the guest's hostname. Empty is the instance's name.
	Hostname string `yaml:"hostname,omitempty" json:"hostname,omitempty"`
	// ImageRef is the image the instance was created from, as it was
	// given.
	ImageRef string `yaml:"image_ref" json:"image_ref"`

	// ImageDigest is the digest ImageRef resolved to when the instance was
	// created. The instance always boots that image: pulling ImageRef again
	// does not change it.
	ImageDigest string `yaml:"image_digest" json:"image_digest"`

	// HypervisorType is the hypervisor the instance runs on. Empty is
	// hypervisor.DefaultType.
	HypervisorType hypervisor.Type `yaml:"hypervisor_type,omitempty" json:"hypervisor_type,omitempty"`
	// HypervisorVersion is the version of that hypervisor. Empty is the
	// daemon's default version of it.
	HypervisorVersion string `yaml:"hypervisor_version,omitempty" json:"hypervisor_version,omitempty"`
	// KernelName is the kernel the guest boots.
	KernelName string `yaml:"kernel_name" json:"kernel_name"`
	// KernelArgs is the kernel's command line. Empty is the hypervisor's
	// default.
	KernelArgs string `yaml:"kernel_args,omitempty" json:"kernel_args,omitempty"`
	// VCPUs is how many vCPUs the guest boots with.
	VCPUs int `yaml:"vcpus" json:"vcpus"`
	// MemoryBytes is how much memory the guest boots with.
	MemoryBytes int64 `yaml:"memory_bytes" json:"memory_bytes"`
	// DiskBytes is the size of the overlay disk the guest writes to.
	DiskBytes int64 `yaml:"disk_bytes" json:"disk_bytes"`
	// NetworkName is the network the instance is attached to.
	NetworkName string `yaml:"network_name" json:"network_name"`
	// StaticIP is the address the instance takes on its network. Empty
	// takes a free one.
	StaticIP string `yaml:"static_ip,omitempty" json:"static_ip,omitempty"`

	// MaxVCPUs is the most vCPUs the instance can be resized to while it
	// runs: it boots with room for them. Zero leaves no room.
	MaxVCPUs int `yaml:"max_vcpus,omitempty" json:"max_vcpus,omitempty"`
	// MaxMemoryBytes is the most memory the instance can be resized to
	// while it runs, as MaxVCPUs is for vCPUs.
	MaxMemoryBytes int64 `yaml:"max_memory_bytes,omitempty" json:"max_memory_bytes,omitempty"`

	// DiskBytesPerSecond limits the bytes per second each of the instance's
	// disks is read and written at. Zero is unlimited.
	DiskBytesPerSecond int64 `yaml:"disk_bytes_per_second,omitempty" json:"disk_bytes_per_second,omitempty"`
	// DiskIOPS limits the operations per second each of the instance's
	// disks is read and written at. Zero is unlimited.
	DiskIOPS int64 `yaml:"disk_iops,omitempty" json:"disk_iops,omitempty"`
	// UploadBytesPerSecond limits the bytes per second the guest sends.
	// Zero is unlimited.
	UploadBytesPerSecond int64 `yaml:"upload_bytes_per_second,omitempty" json:"upload_bytes_per_second,omitempty"`
	// DownloadBytesPerSecond limits the bytes per second the guest
	// receives. Zero is unlimited.
	DownloadBytesPerSecond int64 `yaml:"download_bytes_per_second,omitempty" json:"download_bytes_per_second,omitempty"`

	// StandbyAfter is how long the instance may be idle, running but doing
	// next to nothing, before it is put on standby. Zero is never.
	StandbyAfter time.Duration `yaml:"standby_after,omitempty" json:"standby_after,omitempty"`

	// Ports are the guest's ports published on the host.
	Ports []network.PortMapping `yaml:"ports,omitempty" json:"ports,omitempty"`
	// Mounts are what the guest mounts: volumes, files, host directories
	// and tmpfs.
	Mounts []Mount `yaml:"mounts,omitempty" json:"mounts,omitempty"`
	// Env is the workload's environment, over the image's.
	Env map[string]string `yaml:"env,omitempty" json:"env,omitempty"`
	// Cmd is the command the workload runs, in place of the image's
	// entrypoint and command. Empty is the image's.
	Cmd []string `yaml:"cmd,omitempty" json:"cmd,omitempty"`

	// InitMode is how the guest starts the command: auto, exec or systemd.
	// Empty is auto: systemd if the command is systemd, else exec.
	InitMode guest.InitMode `yaml:"init_mode,omitempty" json:"init_mode,omitempty"`

	// User is who the workload runs as in the exec init mode: user, uid,
	// user:group or uid:gid, looked up in the guest's /etc/passwd and
	// /etc/group. Empty is the image's USER, or root if it has none.
	User string `yaml:"user,omitempty" json:"user,omitempty"`

	// Labels are for people and tools to find the instance by. Dicer does
	// not read them.
	Labels map[string]string `yaml:"labels,omitempty" json:"labels,omitempty"`
	// Restart says what happens when the instance ends without being asked
	// to.
	Restart RestartPolicy `yaml:"restart,omitempty" json:"restart,omitzero"`

	// HealthCheck is how the instance's health is checked, overriding its
	// image's; a Disabled one switches the image's off. Nil means the
	// image's, if it declares one.
	HealthCheck *health.Check `yaml:"healthcheck,omitempty" json:"health_check,omitempty"`

	// CreatedAt is when the instance was defined.
	CreatedAt time.Time `yaml:"created_at" json:"created_at,omitzero"`
	// UpdatedAt is when its definition last changed.
	UpdatedAt time.Time `yaml:"updated_at" json:"updated_at,omitzero"`

	// RemoveOnExit deletes the instance once it stops, unless its restart
	// policy will start it again.
	RemoveOnExit bool `yaml:"remove_on_exit,omitempty" json:"remove_on_exit,omitempty"`

	// StoppedByUser records that a user stopped the instance and has not
	// started it since. An unless-stopped instance is not started at boot
	// while it is set.
	StoppedByUser bool `yaml:"stopped_by_user,omitempty" json:"stopped_by_user,omitempty"`
}

type State string

type Stats struct {
	// InstanceID is the ID of the instance the stats are of.
	InstanceID string `json:"instance_id"`
	// Name is the instance's name when they were read.
	Name string `json:"name"`

	// StartedAt is when the VMM was started. Totals read with another
	// StartedAt are of another VMM, and cannot be compared.
	StartedAt time.Time `json:"started_at"`

	// ReadAt is when the stats were read.
	ReadAt time.Time `json:"read_at"`

	// Held is the vCPUs and guest memory the instance holds.
	Held Resources `json:"held"`

	// CPUTime is the CPU time the VMM has used, user and system.
	CPUTime time.Duration `json:"cpu_time"`

	// ResidentMemoryBytes is the VMM's resident host memory: the guest
	// memory backed so far and its own. Memory a guest frees stays resident.
	ResidentMemoryBytes int64 `json:"resident_memory_bytes"`

	// DiskReadBytes is what the VMM process read from storage: the guest's
	// disks, and the VMM's own files, such as the console log and a
	// snapshot's memory. Reads served from the page cache are not counted.
	DiskReadBytes int64 `json:"disk_read_bytes"`
	// DiskWrittenBytes is what the VMM process wrote to storage, counted as
	// it writes, before the data reaches the disk.
	DiskWrittenBytes int64 `json:"disk_written_bytes"`

	// NetworkReceiveBytes is what the guest received on its network
	// interface.
	NetworkReceiveBytes int64 `json:"network_receive_bytes"`
	// NetworkTransmitBytes is what the guest transmitted on it.
	NetworkTransmitBytes int64 `json:"network_transmit_bytes"`

	// NetworkReceivePackets is the packets the guest received.
	NetworkReceivePackets int64 `json:"network_receive_packets"`
	// NetworkTransmitPackets is the packets the guest transmitted.
	NetworkTransmitPackets int64 `json:"network_transmit_packets"`

	// NetworkReceiveDrops is the packets dropped on their way to the guest,
	// which mostly means it does not take them as fast as they come.
	NetworkReceiveDrops int64 `json:"network_receive_drops"`
	// NetworkTransmitDrops is the packets dropped on their way from the
	// guest.
	NetworkTransmitDrops int64 `json:"network_transmit_drops"`

	// NetworkReceiveErrors is the packets to the guest that failed with an
	// error.
	NetworkReceiveErrors int64 `json:"network_receive_errors"`
	// NetworkTransmitErrors is the packets from the guest that failed with
	// an error.
	NetworkTransmitErrors int64 `json:"network_transmit_errors"`
}

type Status struct {
	// InstanceID is the ID of the instance the status is of.
	InstanceID string `json:"instance_id,omitempty"`
	// State is where the instance is in its lifecycle.
	State State `json:"state"`
	// StateError is why the instance is Failed, or what ended it when it is
	// Restarting.
	StateError string `json:"state_error,omitempty"`

	// VMMPID is the process ID of the instance's VMM, or nil without one.
	VMMPID *int `json:"hypervisor_pid,omitempty"`
	// HypervisorSocketPath is the VMM's control socket.
	HypervisorSocketPath string `json:"hypervisor_socket_path,omitempty"`
	// HypervisorVersion is the version of the hypervisor the guest runs on.
	HypervisorVersion string `json:"hypervisor_version,omitempty"`
	// VsockCID is the guest's vsock context ID.
	VsockCID int64 `json:"vsock_cid,omitempty"`
	// VsockPath is the VMM's socket for the guest's vsock device, which the
	// guest agent is reached through.
	VsockPath string `json:"vsock_path,omitempty"`

	// VCPUs is how many vCPUs the instance was admitted with. The spec may
	// have been edited since.
	VCPUs int `json:"vcpus,omitempty"`
	// MemoryBytes is how much memory the instance was admitted with, as
	// VCPUs is.
	MemoryBytes int64 `json:"memory_bytes,omitempty"`

	// ImageDigest is the image the guest booted from.
	ImageDigest string `json:"image_digest,omitempty"`

	// IP is the instance's address on its network, held while it is
	// defined. It is filled in by Status and not stored, and is empty while
	// the instance holds no network allocation.
	IP string `json:"-"`
	// MAC is the hardware address of the guest's network interface, as IP
	// is filled in.
	MAC string `json:"-"`

	// HealthCheck is the check this run was started with, or nil for none.
	HealthCheck *health.Check `json:"health_check,omitempty"`

	// Health is what that check has found, or nil if there is none.
	Health *health.Health `json:"health,omitempty"`

	// StartedAt is when the instance's VMM started, for an instance that
	// has one.
	StartedAt time.Time `json:"started_at,omitzero"`
	// UpdatedAt is when the status was last written.
	UpdatedAt time.Time `json:"updated_at,omitzero"`

	// ExitCode is the exit code the guest reported when it last ended on
	// its own, if it reported one.
	ExitCode *int `json:"exit_code,omitempty"`

	// FinishedAt is when the guest last ended without being asked to.
	FinishedAt time.Time `json:"finished_at,omitzero"`

	// RestartCount is how many times in a row the restart policy has
	// started the instance again. A start a user asks for resets it.
	RestartCount int `json:"restart_count,omitempty"`

	// NextRestartAt is when a Restarting instance is due to start again.
	NextRestartAt time.Time `json:"next_restart_at,omitzero"`
}

type Store interface {
	CreateInstance(instance Spec) error
	Instance(nameOrID string) (Spec, error)
	Instances() []Spec
	MatchingInstances(match func(Spec) bool) []Spec
	UpdateInstance(instance Spec) error
	RenameInstance(nameOrID string, renamed Spec) error
	DeleteInstance(nameOrID string) error
	// InstanceDir is the persistent directory holding an instance's
	// definition and overlay disk.
	InstanceDir(name string) string

	// StageSnapshot returns an empty directory to write a snapshot's files
	// in, which CreateSnapshot moves into place.
	StageSnapshot() (string, error)
	CreateSnapshot(snapshot Snapshot, staged string) error
	Snapshot(nameOrID string) (Snapshot, error)
	Snapshots() []Snapshot
	DeleteSnapshot(nameOrID string) error
	// SnapshotDir is the directory holding a snapshot's files.
	SnapshotDir(name string) string
}

type Usage struct {
	// ByState counts instances per state, and names every state even when
	// no instance is in it.
	ByState map[State]int `json:"by_state"`

	// ByHealth counts checked instances per health status, and names every
	// status even when no instance has it.
	ByHealth map[health.Status]int `json:"by_health"`

	// Capacity is what instances may be given, and how that was arrived at.
	Capacity Capacity `json:"capacity"`

	// Held is what the instances listed in Instances hold between them.
	Held Resources `json:"held"`

	// Instances are the instances holding resources, in name order.
	Instances []HeldResources `json:"instances"`
}

type Volumes interface {
	Volume(nameOrID string) (volume.Volume, error)
	Path(v volume.Volume) string
}

type WaitCondition int

type WaitOptions struct {
	// ID, if set, is the instance to wait for, which tells it apart from a
	// later one given the same name.
	ID string

	// Condition is what to wait for. The zero value waits for a stop.
	Condition WaitCondition

	// NextStop waits for the instance's next stop, even if it is stopped
	// now: for a caller about to start it.
	NextStop bool
}

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