// Package containerengine 定义更新执行器所依赖的容器运行时边界。
//
// 该包只声明容器运行时所必需的最小抽象，包括引擎接口、镜像、容器、
// 挂载等数据结构，不包含任何具体实现细节；具体实现见同包的 moby.go。
package containerengine

import (
	"context"
	"errors"
	"io"
)

// ErrNotFound 表示在容器引擎中找不到目标对象（镜像或容器）。
var ErrNotFound = errors.New("container engine object not found")

// Platform 描述一个显式的 OCI 操作系统与 CPU 平台。
type Platform struct {
	// OS 表示操作系统名称，例如 linux。
	OS string
	// Architecture 表示 CPU 架构，例如 amd64。
	Architecture string
	// Variant 表示架构变体，例如 v8，可为空字符串。
	Variant string
}

// Image 引擎返回的不可变镜像信息。
type Image struct {
	// ID 表示镜像的唯一标识。
	ID string
	// RepoDigests 表示镜像在仓库中的内容摘要列表。
	RepoDigests []string
	// DescriptorDigest 表示 OCI 描述符摘要，不可用时为空字符串。
	DescriptorDigest string
	// Platform 表示镜像的目标操作系统与 CPU 平台。
	Platform Platform
}

// RestartPolicy 传递给引擎的重启策略，引擎不会为其附加隐式默认值。
type RestartPolicy struct {
	// Name 表示策略名称，例如 always、on-failure。
	Name string
	// MaximumRetryCount 表示策略为 on-failure 时的最大重试次数。
	MaximumRetryCount int
}

// Mount 表示一个显式的容器挂载。
type Mount struct {
	// Type 表示挂载类型，例如 bind、volume。
	Type string
	// Source 表示宿主机上的源路径或卷名。
	Source string
	// Target 表示容器内的目标路径。
	Target string
	// ReadOnly 表示挂载是否为只读。
	ReadOnly bool
}

// ContainerSpec 包含后端执行器控制的容器全部属性。
type ContainerSpec struct {
	// Name 表示容器名称。
	Name string
	// ImageReference 表示要使用的镜像引用。
	ImageReference string
	// Platform 表示容器运行的目标平台。
	Platform Platform
	// Environment 表示以 KEY=VALUE 形式给出的环境变量列表。
	Environment []string
	// Labels 表示附加到容器的键值标签。
	Labels map[string]string
	// NetworkMode 表示容器的网络模式。
	NetworkMode string
	// RestartPolicy 表示容器的重启策略。
	RestartPolicy RestartPolicy
	// Mounts 表示容器的挂载列表。
	Mounts []Mount
	// User 表示容器内的运行用户。
	User string
	// StopTimeoutSeconds 表示停止容器的超时秒数。
	StopTimeoutSeconds int
}

// Container 执行幂等检查所需的容器运行时状态。
type Container struct {
	// ID 表示容器标识。
	ID string
	// Name 表示容器名称。
	Name string
	// ImageID 表示容器所基于的镜像标识。
	ImageID string
	// ImageReference 表示创建容器时使用的镜像引用。
	ImageReference string
	// Platform 表示容器的运行平台。
	Platform string
	// Running 表示容器是否正在运行。
	Running bool
	// Dead 表示容器是否已经停止且不可重启。
	Dead bool
	// Status 表示容器的原始状态字符串。
	Status string
	// Environment 表示容器的环境变量列表。
	Environment []string
	// Labels 表示容器的键值标签。
	Labels map[string]string
	// NetworkMode 表示容器的网络模式。
	NetworkMode string
	// RestartPolicy 表示容器的重启策略。
	RestartPolicy RestartPolicy
	// Mounts 表示容器的挂载列表。
	Mounts []Mount
	// User 表示容器内的运行用户。
	User string
	// StopTimeoutSeconds 表示停止容器的超时秒数。
	StopTimeoutSeconds int
}

// Engine 更新执行器所需的最小容器运行时 API。
//
// 所有方法都通过 context 传递取消与超时控制；
// 各方法的具体行为由实现决定，详见 MobyEngine。
type Engine interface {
	// Ping 探测引擎是否可达。
	Ping(context.Context) error
	// PullImage 从远端仓库拉取指定镜像。
	PullImage(context.Context, string) error
	// LoadImage 从归档读取流加载镜像。
	LoadImage(context.Context, io.Reader) error
	// InspectImage 检查镜像并返回其不可变信息。
	InspectImage(context.Context, string) (Image, error)
	// CreateContainer 依据规格创建容器并返回其状态。
	CreateContainer(context.Context, ContainerSpec) (Container, error)
	// StartContainer 启动指定容器。
	StartContainer(context.Context, string) error
	// ContainerLogs 读取指定容器的日志流。
	ContainerLogs(context.Context, string) (io.ReadCloser, error)
	// StopContainer 停止指定容器。
	StopContainer(context.Context, string) error
	// InspectContainer 检查容器并返回其运行时状态。
	InspectContainer(context.Context, string) (Container, error)
	// RemoveContainer 移除指定容器，force 决定是否强制移除。
	RemoveContainer(context.Context, string, bool) error
	// Close 释放引擎底层资源。
	Close() error
}