ctr

type AttachableInjection struct {
	// KukettyBinaryPath is the host path of the kuketty binary that will
	// be bind-mounted RO at AttachableBinaryPath inside the container.
	// The daemon stages this from its own /bin/kuketty at provision time
	// (kukeond image ships kuketty alongside the daemon binary).
	KukettyBinaryPath string

	// HostTTYDir is the host path of the per-container tty directory that
	// will be bind-mounted at AttachableTTYDir inside the container. The
	// host-visible socket that `kuke attach` connects to is the `socket`
	// entry inside this directory.
	HostTTYDir string

	// HostMetadataPath is the host path of the per-container kuketty
	// metadata file. The runner renders the metadata to this path before
	// the container starts; the OCI bind mount maps it to
	// AttachableMetadataPath inside the container.
	HostMetadataPath string

	// RenderMetadata, when non-nil, is invoked from inside the OCI
	// args-wrap spec opt with the resolved workload argv — i.e. the merge
	// of the image's ENTRYPOINT + CMD and any user override that
	// containerd's WithImageConfig and our WithProcessArgs have already
	// applied to s.Process.Args by the time the wrap runs. The callback
	// is expected to render the ContainerDoc with the workload argv baked
	// into Spec.Command / Spec.Args and write it atomically to
	// HostMetadataPath. nil disables metadata rendering — used by unit
	// tests that exercise only the args-wrap shape.
	RenderMetadata func(workloadArgv []string) error
}

type BuildOption func(*buildOpts)

type CPUResources struct {
	Weight *uint64
	Quota  *int64
	Period *uint64
	Cpus   string
	Mems   string
}

type CgroupResources struct {
	CPU    *CPUResources
	Memory *MemoryResources
	IO     *IOResources
}

type CgroupSpec struct {
	// Group is the target cgroup path, e.g. /kukeon/workloads/runner.
	Group string
	// Mountpoint overrides the default cgroup mount (/sys/fs/cgroup) when non-empty.
	Mountpoint string
	// Resources defines the controller knobs that should be configured for the cgroup.
	Resources CgroupResources
}

type Client interface {
	Connect() error
	Close() error

	CreateNamespace(namespace string) error
	DeleteNamespace(namespace string) error
	ListNamespaces() ([]string, error)
	GetNamespace(namespace string) (string, error)
	ExistsNamespace(namespace string) (bool, error)
	CleanupNamespaceResources(namespace, snapshotter string) error

	GetCgroupMountpoint() string
	GetCurrentCgroupPath() (string, error)
	CgroupPath(group, mountpoint string) (string, error)
	NewCgroup(spec CgroupSpec) (*cgroup2.Manager, error)
	LoadCgroup(group string, mountpoint string) (*cgroup2.Manager, error)
	DeleteCgroup(group, mountpoint string) error
	// EnsureSubtreeControllers writes "+<ctrl>" to the named group's own
	// cgroup.subtree_control AND to every ancestor up to the unified cgroup
	// mount, so the group's children inherit the controllers. The level-
	// agnostic primitive used by every realm/space/stack ensure path (issue
	// #327) and by the cell wrappers below (issues #312, #314). Filters the
	// requested set against what the host root advertises and returns the
	// effective set actually written. Idempotent — re-running on an already-
	// delegated subtree is a no-op.
	EnsureSubtreeControllers(group, mountpoint string, controllers []string) ([]string, error)
	// EnableCellSubtreeControllers enables the named cgroup-v2 controllers in
	// the cell cgroup's own subtree_control AND in every ancestor's
	// subtree_control up to the unified cgroup mount, so child cgroups (the
	// per-container task cgroups runc creates under Linux.CgroupsPath)
	// inherit the controllers and cell-level resource accounting / limits
	// become effective. Returns the effective controller set actually
	// written (the requested set filtered against the host root's
	// cgroup.controllers) so the runner can persist it on
	// CellStatus.SubtreeControllers (issue #328). Thin wrapper around
	// EnsureSubtreeControllers kept for the cell call sites' readability.
	// Issue #312.
	EnableCellSubtreeControllers(group, mountpoint string, controllers []string) ([]string, error)
	// EnableCellAllSubtreeControllers is the cell/profile=NestedCgroupRuntime
	// counterpart: it delegates the full host-available cgroup-v2 controller
	// set on the cell's subtree_control (and every ancestor's), rather than
	// the kukeon resource subset. Returns the effective controller set
	// actually written so the runner can persist it on
	// CellStatus.SubtreeControllers (issue #328). Used by cells that host
	// an inner cgroup runtime (an embedded containerd or systemd) which
	// needs to in turn delegate arbitrary controllers to its own children.
	// Issue #314.
	EnableCellAllSubtreeControllers(group, mountpoint string) ([]string, error)
	// RelocateProcessesToLeaf drains every PID currently in <group>/cgroup.procs
	// into a freshly-mkdir'd leaf cgroup at <group>/<leaf>. Used to satisfy
	// cgroup-v2's no-internal-process rule (issue #336): subtree_control
	// widening for non-thread-aware controllers (memory, io, ...) is rejected
	// by the kernel when the target cgroup hosts processes directly. The
	// leaf inherits the parent's controllers via the parent's subtree_control,
	// so resource accounting at <group> still applies — the PIDs just live
	// one level deeper. Idempotent: re-running on an already-drained group
	// is a no-op.
	RelocateProcessesToLeaf(group, mountpoint, leaf string) error
	CreateContainerFromSpec(namespace string, spec intmodel.ContainerSpec, creds []RegistryCredentials, opts ...BuildOption) (containerd.Container, error)

	CreateContainer(namespace string, spec ContainerSpec, creds []RegistryCredentials) (containerd.Container, error)
	GetContainer(namespace, id string) (containerd.Container, error)
	ListContainers(namespace string, filters ...string) ([]containerd.Container, error)
	ExistsContainer(namespace, id string) (bool, error)
	DeleteContainer(namespace, id string, opts ContainerDeleteOptions) error
	StartContainer(namespace string, spec ContainerSpec, taskSpec TaskSpec) (containerd.Task, error)
	StopContainer(namespace, id string, opts StopContainerOptions) (*containerd.ExitStatus, error)

	TaskStatus(namespace, id string) (containerd.Status, error)
	TaskMetrics(namespace, id string) (*apitypes.Metric, error)

	// ContainerProcessUID returns the resolved process.User.UID from the
	// given container's OCI runtime spec. Used after CreateContainerFromSpec
	// to chown the host-side per-container Attachable tty directory to the
	// runtime uid the container will execute as — which can be non-root
	// when the image carries a USER directive (or the cell profile sets
	// container.user). Without this, kuketty inside the container fails to
	// create its socket/log/capture files in the bind-mounted dir.
	ContainerProcessUID(namespace string, container containerd.Container) (uint32, error)

	// LoadImage imports an OCI/docker image tarball into the specified
	// containerd namespace and returns the names of the imported images.
	LoadImage(namespace string, reader io.Reader) ([]string, error)

	// ListImages enumerates images in the specified containerd namespace.
	ListImages(namespace string) ([]ImageInfo, error)

	// GetImage returns metadata for the named image ref in the specified
	// containerd namespace. Returns errdefs.ErrImageNotFound if
	// the ref is absent.
	GetImage(namespace, ref string) (ImageInfo, error)

	// ImageChainID returns the chainID the image at ref would unpack to
	// today, computed from the current rootfs DiffIDs in the namespace's
	// content store. Pair with ContainerRootChainID to detect that an
	// image tag has been re-pointed since a container was created (the
	// digest-drift signal missing from bootstrapCell's image comparison
	// in issue #915 defect 2). Returns errdefs.ErrImageNotFound if the
	// ref is absent.
	ImageChainID(namespace, ref string) (string, error)

	// ContainerRootChainID returns the chainID of the parent layer stack
	// the container's root snapshot was committed against — i.e. the
	// image content the container is anchored on at the moment of the
	// call, regardless of what the image ref by the same name resolves
	// to today. Returns errdefs.ErrContainerNotFound if the container is
	// absent.
	ContainerRootChainID(namespace, containerID string) (string, error)

	// DeleteImage removes the named image ref from the specified
	// containerd namespace. Returns errdefs.ErrImageNotFound if the ref
	// is absent so callers can distinguish missing from operational
	// failures.
	DeleteImage(namespace, ref string) error

	// PruneImages reclaims dangling image layers and the orphaned leases
	// pinning them in the specified containerd namespace, leaving tagged
	// images and the snapshots backing live containers untouched. Returns
	// the count of leases released vs. retained.
	PruneImages(namespace string) (PruneResult, error)

	// NamespaceStorage returns the per-namespace storage footprint —
	// snapshot count (across every registered snapshotter in
	// KukeonKnownSnapshotters), lease count, and content-blob count plus
	// summed byte size. Used by `kuke status` to surface accumulation
	// before the data volume fills (issue #1039); the figures come from
	// containerd's metadata stores (boltdb iterators), not an on-disk
	// du, so the call stays cheap enough for the status command's
	// budget. Per-snapshot disk usage is intentionally omitted — it
	// would require walking the snapshotter's filesystem.
	NamespaceStorage(namespace string) (StorageStats, error)
}

type ContainerDeleteOptions struct {
	// SnapshotCleanup indicates whether to clean up snapshots.
	SnapshotCleanup bool
}

type ContainerRuntime struct {
	// Name is the runtime name (e.g., "io.containerd.runc.v2").
	Name string
	// Options are runtime-specific options.
	Options interface{}
}

type ContainerSpec struct {
	// ID is the unique identifier for the container.
	ID string
	// Image is the image reference to use for the container.
	Image string
	// SnapshotKey is the key for the snapshot. If empty, defaults to ID.
	SnapshotKey string
	// Snapshotter is the snapshotter to use. If empty, uses default.
	Snapshotter string
	// Runtime is the runtime configuration.
	Runtime *ContainerRuntime
	// SpecOpts are OCI spec options to apply.
	SpecOpts []oci.SpecOpts
	// Labels are key-value pairs to attach to the container.
	Labels map[string]string
	// CNIConfigPath is the path to the CNI configuration to use for this container.
	CNIConfigPath string
}

type IOResources struct {
	Weight   uint16
	Throttle []IOThrottleEntry
}

type IOThrottleEntry struct {
	Type  IOThrottleType
	Major int64
	Minor int64
	Rate  uint64
}

type IOThrottleType string

type ImageInfo struct {
	Name      string
	Size      int64
	CreatedAt time.Time
	Digest    string
	MediaType string
	Labels    map[string]string
}

type MemoryResources struct {
	Min  *int64
	Max  *int64
	Low  *int64
	High *int64
	Swap *int64
}

type NamespacePaths struct {
	Net string
	IPC string
	UTS string
	PID string
}

type PruneResult struct {
	LeasesDeleted  int
	LeasesRetained int
}

type RegistryCredentials struct {
	// Username is the registry username.
	Username string
	// Password is the registry password or token.
	Password string
	// ServerAddress is the registry server address (e.g., "docker.io", "registry.example.com").
	// If empty, credentials apply to the registry extracted from the image reference.
	ServerAddress string
}

type ResolvedVolume struct {
	HostPath string
	Realm    string
	Space    string
	Stack    string
	Name     string
}

type StopContainerOptions struct {
	// Signal is the signal to send (defaults to SIGTERM).
	Signal string
	// Timeout is the timeout for graceful shutdown.
	Timeout *time.Duration
	// Force indicates whether to force kill if timeout is exceeded.
	Force bool
}

type StorageStats struct {
	// Snapshots is the total snapshot count across every registered
	// snapshotter in KukeonKnownSnapshotters. Aggregated so the status
	// row reads at-a-glance — a per-snapshotter breakdown would just
	// noise the report when one snapshotter dominates in practice
	// (overlayfs on real installs).
	Snapshots int
	// Leases is the total lease count from leases.Manager.List. Leases
	// are containerd GC roots — accumulation past the live-image count
	// is the leak signal issue #1039 surfaces.
	Leases int
	// Blobs is the count of content-store blobs (committed manifests,
	// layers, configs).
	Blobs int
	// BlobsBytes is the summed Size field across the content-store
	// walk — cheap because content.Info already carries the byte size,
	// so no extra file stat is needed.
	BlobsBytes int64
}

type TaskIO struct {
	// Stdin is the path to stdin (if any).
	Stdin string
	// Stdout is the path to stdout (if any).
	Stdout string
	// Stderr is the path to stderr (if any).
	Stderr string
	// Terminal indicates if the task should have a TTY.
	Terminal bool
	// LogFilePath, when set, makes the runtime shim write the task's
	// stdout and stderr to this host path via cio.LogFile. The shim
	// opens the file in append mode; if no file exists yet it is
	// created. Mutually exclusive with Terminal — log files do not
	// pair with a TTY.
	LogFilePath string
}

type TaskSpec struct {
	// IO is the IO configuration for the task.
	IO *TaskIO
	// Options are task creation options.
	Options []containerd.NewTaskOpts
}

type VolumeScope struct {
	Realm string
	Space string
	Stack string
}