compute

type ACLRule struct {
	// ID is the agent-facing rule identifier returned by AddACLRule.
	ID string
	// Direction is ingress or egress.
	Direction string
	// Action is allow, drop, or reject.
	Action string
	// Protocol is tcp, udp, icmp, or empty for any.
	Protocol string
	// Src is an optional CIDR or address.
	Src string
	// Dst is an optional CIDR or address.
	Dst string
	// Port is an optional destination port or range.
	Port string
}

type Backend interface {
	CreateSandbox(context.Context, Sandbox) error
	ListSandboxes(context.Context) ([]Sandbox, error)
	GetSandbox(context.Context, string) (Sandbox, error)
	ExtendSandbox(context.Context, string, time.Time) (Sandbox, error)
	PinSandbox(context.Context, string, bool, string, time.Time) (Sandbox, error)
	DeleteSandbox(context.Context, string) error
	BeginCreateInstance(context.Context, CreateInstance) (PendingInstance, error)
	ListInstances(context.Context, string) ([]Instance, error)
	GetInstance(context.Context, Ref) (Instance, error)
	DeleteInstance(context.Context, Ref) error
	Exec(context.Context, ExecRequest, io.Writer, io.Writer) (int64, error)
	OpenExec(context.Context, ExecRequest) (io.ReadWriteCloser, error)
	ListNetworks(context.Context, string) ([]Network, error)
	CreateNetwork(context.Context, string, Network) (Network, error)
	AttachNIC(context.Context, Ref, string, string, string, string) (NIC, error)
	GetNetwork(context.Context, string, string) (Network, error)
	DeleteNetwork(context.Context, string, string) error
	DetachNIC(context.Context, Ref, string) error
	PeerNetworks(context.Context, string, string, string) error
	AddACLRule(context.Context, string, string, ACLRule) (ACLRule, error)
	RemoveACLRule(context.Context, string, string, string) error
	CreateForward(context.Context, string, string, Ref, int64, int64, string) (Forward, error)
	InstanceForward(context.Context, Ref, int64, string) (Forward, error)
	StartInstance(context.Context, Ref, bool) (Instance, error)
	StopInstance(context.Context, Ref, bool) (Instance, error)
	RestartInstance(context.Context, Ref, bool) (Instance, error)
	WaitInstance(context.Context, WaitRequest) (WaitResult, error)
	ReadFile(context.Context, FileReadRequest) (FileReadResult, error)
	ReadBinaryFile(context.Context, Ref, string) (io.ReadCloser, error)
	DeleteFile(context.Context, Ref, string) error
	WriteFile(context.Context, FileWriteRequest) (FileWriteResult, error)
	CreateSnapshot(context.Context, Ref, string) error
	RestoreSnapshot(context.Context, Ref, string) error
	DeleteSnapshot(context.Context, Ref, string) error
	ListSnapshots(context.Context, Ref) ([]Snapshot, error)
	PublishInstance(context.Context, Ref, string) (string, error)
	GetSandboxImage(context.Context, string, string) (CatalogImage, error)
}

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

type CatalogImage struct {
	// Name is the catalog lookup key.
	Name string
	// OS is the operating system family.
	OS string
	// Version is the guest operating system version.
	Version string
	// Platform identifies the backend.
	Platform string
	// Kind is the default guest kind.
	Kind string
	// Kinds lists supported guest kinds.
	Kinds []string
	// Desktop marks images with desktop tooling.
	Desktop bool
	// Description is optional catalog guidance.
	Description string
	// Reference is the immutable imgoci release or upstream remote alias.
	Reference string
	// Alias names a qualified cluster-local image in the image-build project.
	Alias string
	// Seed is the host-local Lume VM name for macOS images.
	Seed string
	// Fingerprint is derived during reconciliation, not an image build identity.
	Fingerprint string
	// CPUs is the default CPU count.
	CPUs int64
	// MemoryMB is the default memory limit in MiB.
	MemoryMB int64
	// DiskGB is the default root disk limit in GiB.
	DiskGB int64
}

type CreateInstance struct {
	// Ref identifies the new guest.
	Ref Ref
	// Image supplies the reconciled catalog source.
	Image CatalogImage
	// Kind selects a supported guest kind.
	Kind string
	// Network is default, none, or an agent-facing network name.
	Network string
	// Host optionally pins the sandbox's configured member.
	Host string
	// CPUs is the requested CPU count.
	CPUs int64
	// MemoryMB is the memory limit in MiB.
	MemoryMB int64
	// DiskGB is the root disk limit in GiB.
	DiskGB int64
	// Start requests a running rather than stopped guest.
	Start bool
}

type ExecRequest struct {
	// Ref identifies the guest.
	Ref Ref
	// Argv is a native argument vector; shell callers use sh -c or cmd.exe /c.
	Argv []string
	// User is a Linux numeric UID; Windows exec uses the agent service identity.
	User string
	// Cwd is the optional absolute guest working directory.
	Cwd string
	// Env contains parsed KEY=VALUE entries.
	Env map[string]string
	// Stdin is the bounded input string.
	Stdin string
	// Timeout is the exec-only budget; request cancellation still wins.
	Timeout time.Duration
}

type ExecResult struct {
	// ExitCode is the guest process exit status, or -1 on timeout.
	ExitCode int64
	// Stdout contains at most 64 KiB of standard output.
	Stdout string
	// Stderr contains at most 64 KiB of standard error.
	Stderr string
	// StdoutTruncated reports discarded standard output bytes.
	StdoutTruncated bool
	// StderrTruncated reports discarded standard error bytes.
	StderrTruncated bool
	// TimedOut reports an exec-only deadline, not caller cancellation.
	TimedOut bool
}

type FileReadRequest struct {
	// Ref identifies the guest.
	Ref Ref
	// Path is an absolute guest path.
	Path string
	// MaxBytes is the read cap; zero selects 64 KiB.
	MaxBytes int64
}

type FileReadResult struct {
	// Content contains at most MaxBytes of file data.
	Content string
	// Truncated reports discarded trailing bytes.
	Truncated bool
}

type FileWriteRequest struct {
	// Ref identifies the guest.
	Ref Ref
	// Path is an absolute guest path.
	Path string
	// Content is the exact text to write.
	Content string
	// Mode is an optional octal mode such as 0644.
	Mode string
}

type FileWriteResult struct {
	// Bytes is the number of content bytes written.
	Bytes int64
}

type Forward struct {
	// Address is the listen address on the uplink range.
	Address string
	// Port is the listen port.
	Port int64
	// Protocol is tcp or udp.
	Protocol string
	// Network is the agent-facing network name.
	Network string
	// Instance is the target instance name.
	Instance string
}

type Impairment struct {
	// LatencyMS is added delay in milliseconds.
	LatencyMS int64
	// JitterMS is delay variation and requires LatencyMS.
	JitterMS int64
	// LossPercent is packet loss percent.
	LossPercent float64
	// RateMbit is a rate limit in Mbit/s.
	RateMbit int64
	// Clear removes existing impairment on the NIC.
	Clear bool
}

type Instance struct {
	// Ref identifies the instance.
	Ref Ref
	// Image is the catalog name used to create the guest.
	Image string
	// OS is the guest operating system recorded by Incus image metadata.
	OS string
	// Kind is container or vm.
	Kind string
	// Host is the actual member.
	Host string
	// Status is the observed Incus state.
	Status string
	// CPUs is the configured CPU count.
	CPUs int64
	// MemoryMB is the configured memory in MiB.
	MemoryMB int64
	// DiskGB is the root disk limit in GiB.
	DiskGB int64
	// Desktop marks desktop-capable images.
	Desktop bool
	// NICs contains observed network devices.
	NICs []NIC
	// Snapshots contains guest snapshot names.
	Snapshots []string
	// VNCURL is an optional backend-reported VNC endpoint, used when port forwards are unavailable.
	VNCURL string
}

type NIC struct {
	// Name is the configured device name used by network operations.
	Name string
	// GuestName is the observed OS interface name, which may differ on VMs.
	GuestName string
	// Network is the metadata-resolved agent-facing network name.
	Network string
	// MAC is the observed hardware address.
	MAC string
	// Addresses contains observed guest IP addresses.
	Addresses []string
}

type Network struct {
	// Name is the agent-facing network name.
	Name string
	// PhysicalName is the opaque Incus bridge identifier, never exposed in DTOs.
	PhysicalName string
	// Project is the Incus project containing the managed network.
	Project string
	// Kind is bridge or ovn.
	Kind string
	// CIDR is the configured network prefix.
	CIDR string
	// Gateway is the bridge gateway address, if any.
	Gateway string
	// Host identifies the sandbox's member-local L2 domain.
	Host string
	// DHCP enables address assignment.
	DHCP bool
	// NAT enables outbound translation.
	NAT bool
	// DNS enables DNS service.
	DNS bool
}

type Options struct {
	// Host is the member used to pin bridge-backed sandboxes.
	Host string
	// DefaultTTL is used when create or extend omits a TTL. Zero selects 240 minutes.
	DefaultTTL time.Duration
	// MaxTTL is the upper bound for create and extend. Zero selects 1440 minutes.
	MaxTTL time.Duration
	// PinIdentities allows these exact subjects to pin and unpin sandboxes.
	// An empty list disables pinning.
	PinIdentities []string
	// DefaultNetworkKind selects ovn or bridge for new sandboxes. Empty selects ovn.
	DefaultNetworkKind string
	// Logger receives operational logs. Nil selects a no-op logger.
	Logger *slog.Logger
	// OnSandboxExpired purges transient artifacts once a sandbox is expired.
	OnSandboxExpired func(string)
	// OnReap expires transient artifacts before each backend reaper scan.
	OnReap func()
	// DesktopReady probes the guest session after Incus agent readiness.
	DesktopReady func(context.Context, Ref) (bool, error)
	// Mac is the optional Lume backend. Nil leaves Incus-only operation.
	Mac Backend
}

type PendingInstance interface {
	Wait(context.Context) (Instance, error)
}

type Ref struct {
	// Sandbox is the agent-facing sandbox name.
	Sandbox string
	// Name is the instance name within the project.
	Name string
}

type Sandbox struct {
	// Name is the agent-facing lifecycle unit.
	Name string
	// Platform identifies the compute backend.
	Platform string
	// Subject records the creator without enforcing ownership policy.
	Subject string
	// Host is the member shared by this sandbox's bridge-backed instances.
	Host string
	// NetworkKind records the default fabric; empty denotes a legacy bridge sandbox.
	NetworkKind string
	// CreatedAt is the original creation time.
	CreatedAt time.Time
	// ExpiresAt is the persisted reaper deadline.
	ExpiresAt time.Time
	// Pinned exempts this sandbox from TTL expiry until explicitly unpinned.
	Pinned bool
	// PinnedBy is the identity that established the current pin.
	PinnedBy string
	// PinnedAt is when the current pin was established.
	PinnedAt time.Time
}

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

type Snapshot struct {
	// Name is the agent-facing snapshot name.
	Name string
	// CreatedAt is the snapshot creation time.
	CreatedAt time.Time
}

type WaitRequest struct {
	// Ref identifies the guest.
	Ref Ref
	// Until is running, agent, network, desktop, or stopped.
	Until string
	// Timeout is the wait-only budget; request cancellation still wins.
	Timeout time.Duration
}

type WaitResult struct {
	// Status is the observed guest state.
	Status string
	// Elapsed is time spent waiting.
	Elapsed time.Duration
}