ctr

type AttachableInjection struct {
	// SbshBinaryPath is the host path of the static sbsh binary that will be
	// bind-mounted RO at AttachableBinaryPath inside the container.
	SbshBinaryPath 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` (#66) connects to is the
	// `socket` entry inside this directory.
	HostTTYDir string

	// UseProfile, when true, instructs the wrapper to append
	// `--profiles-dir AttachableTTYDir --profile AttachableProfileName` to
	// the sbsh terminal invocation. The runner is responsible for writing
	// the profile YAML to <HostTTYDir>/AttachableProfileFile before the
	// container starts; the wrapper itself never touches the filesystem.
	UseProfile bool

	// SocketGID, when non-zero, is the numeric GID of the kukeon system
	// group on the host. The wrapper emits `sbsh terminal --socket-mode
	// AttachableSocketMode --socket-gid <SocketGID>` so the per-container
	// control socket is created with mode 0660 owned by the kukeon group,
	// matching the group-traversal layout on the parent tty/ directory and
	// `/opt/kukeon`. Zero (the default) preserves sbsh's hard-coded 0o600
	// owner-only behavior — the legacy contract for callers that have no
	// kukeon group configured. Requires sbsh v0.10.0 or later inside the
	// container; the staged binary at /.kukeon/bin/sbsh must support the
	// `--socket-mode` and `--socket-gid` flags.
	SocketGID int

	// CaptureGID and LogFileGID, when non-zero, are the numeric GIDs of
	// the kukeon system group on the host. The wrapper emits `sbsh terminal
	// --capture-mode AttachableCaptureMode --capture-gid <CaptureGID>` and
	// `--log-file-mode AttachableLogFileMode --log-file-gid <LogFileGID>`
	// so the per-container capture transcript and log file are created
	// with mode 0640 owned by the kukeon group, matching the socket and
	// parent tty/ layout — without these flags sbsh's default 0o600
	// owner-only files are unreadable to non-root kukeon-group operators
	// invoking `kuke log` from the host.
	//
	// In practice both will be the same GID (the kukeon group GID) for
	// now, but separate fields keep the API parallel to SocketGID and
	// leave room for divergent group choices later. Zero (the default)
	// preserves sbsh's hard-coded 0o600 owner-only behavior. Requires
	// sbsh v0.10.2 or later inside the container; the staged binary at
	// /.kukeon/bin/sbsh must support the `--capture-mode`, `--capture-gid`,
	// `--log-file-mode`, and `--log-file-gid` flags.
	CaptureGID int
	LogFileGID int
}

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)

	ResolveSbshCachePath(namespace, imageRef, baseRunPath string, creds []RegistryCredentials) (string, 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, sbsh 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)

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

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