build

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

type Config struct {
	// BuildkitHost 是 buildkit 端点（docker-container://<name> 或
	// tcp://…/unix://… 直连外部 buildkitd——隔离升级路径）。
	BuildkitHost string
	// ManageDaemon 报告是否由平台自管 buildkitd 容器（EnsureRunning 幂等
	// 拉起钉版容器 + 限额 + 内部缓存卷）。指向外部 buildkitd 时应置 false。
	ManageDaemon bool
	// DaemonContainerName 是自管 buildkitd 容器名。
	DaemonContainerName string
	// CacheVolume 是 buildkitd 内部工作缓存的持久化命名卷（缺省）。
	CacheVolume string
	// CacheDir 是 local cache 导入/导出的宿主目录（客户端侧数据根）。
	CacheDir string
	// ArtifactsDir 是 plan JSON / 构建日志归档根目录。
	ArtifactsDir string
	// Concurrency 是构建队列并发上限（≤0 取缺省 2，天花板 8）。
	Concurrency int
	// MemoryBytes / NanoCPUs 是 buildkitd 容器 cgroup 限额。
	MemoryBytes int64
	NanoCPUs    int64
	// PollInterval 是队列 DB 扫描周期。
	PollInterval time.Duration
	// Timeout 是单条构建执行的超时预算（≤0 取缺省 30min；超时 → 终态
	// failed（E_BUILD_FAILED），由队列在认领执行处包裹生效）。
	Timeout time.Duration
	// ContextRoots 是构建上下文的受管根集合（H14 宿主目录信任边界）：
	// 执行侧只接受位于受管根内的 context_dir——builds.request 是跨进程
	// 通道，直写库的越界请求不得把宿主任意目录整目录打进镜像。Normalize
	// 保证系统 temp 根恒在集合内（API 层 compose 暂存/回落基准的落点，
	// MkdirTemp("", …) 所在）；daemon 装配再并入 git 根（gitserver 裸
	// 仓库根，v0.2 worktree 物化路径的前缀形态）与显式配置根。越界构建
	// 终态失败（不静默放宽）。v0.2 挂账：CLI 同宿主构建目录（显式
	// base_dir）改为上传/物化到受管根后，该集合即对全部入队来源完备闭合。
	ContextRoots []string
}

type DaemonManager interface {
	// EnsureImagePresent 确保镜像在本机 daemon 存在（缺失时拉取并排空
	// 响应流）。
	EnsureImagePresent(ctx context.Context, image string) error
	// EnsureVolumePresent 确保命名卷存在（幂等）。
	EnsureVolumePresent(ctx context.Context, name string) error
	// EnsureContainerRunning 把容器收敛到「存在且运行」。
	EnsureContainerRunning(ctx context.Context, spec DaemonSpec) error
}

type DaemonSpec struct {
	// Name 是容器名（缺省 fleetly-buildkit）。
	Name string
	// Image 是钉版镜像（moby/buildkit:v0.32.2）。
	Image string
	// MemoryBytes / NanoCPUs 是 cgroup 硬限额（Spike A E4 形态）。
	MemoryBytes int64
	NanoCPUs    int64
	// CacheVolume 是挂到容器内部工作缓存目录（InternalCacheMountPath）的
	// 命名卷——层缓存随容器重建不丢。空 = 无内部缓存挂载。
	CacheVolume string
}

type Executor interface {
	// Execute 执行一条已 claim（building）的构建记录，终态落库后返回最新
	// 记录；返回的错误已归一为应用错误信封。
	Execute(ctx context.Context, rec state.BuildRecord) (state.BuildRecord, error)
}

type ImageInfo struct {
	// ID 是不可变镜像 ID（`sha256:<hex>` 配置摘要，D9 部署引用形态）。
	ID string
}

type ImageSource interface {
	// InspectImage 按引用检查本机镜像；缺失返回 ErrImageNotFound（适配器
	// 必须把底座 not-found 归一为该哨兵）。
	InspectImage(ctx context.Context, ref string) (ImageInfo, error)
	// LoadImage 把 docker-format tar 流装入本机 daemon（构建产物落本机；
	// 流由 buildkit docker 导出器客户端侧管道给出）。
	LoadImage(ctx context.Context, dockerTar io.Reader) error
}

type PreflightResult struct {
	// Ref 是被检查的镜像引用（tag 或 `名称@sha256:` 形态）。
	Ref string
	// Digest 是本机镜像 ID（`sha256:<hex>`；不可用时为空）。
	Digest string
	// Available 报告镜像在本机 daemon 可得。
	Available bool
	// Warning 是缺失时的警告码（W_ROLLBACK_IMAGE_RISK）；可得时为空。
	Warning string
}

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

type Request struct {
	// BuildID 与 builds.id 一致（产物归档目录与镜像 tag 的可追溯成分）。
	BuildID string `json:"build_id"`
	// AppID / AppName 是平台应用标识与 compose 项目名（镜像 tag 成分）。
	AppID   string `json:"app_id"`
	AppName string `json:"app_name"`
	// Service 是 compose 服务名。
	Service string `json:"service"`
	// Driver 是构建驱动（railpack | dockerfile；由 compose 模式裁决）。
	Driver state.Driver `json:"driver"`
	// ContextDir 是构建上下文绝对路径（compose build.context 相对 compose
	// 文件目录解析后；受控子集内校验过的目录）。
	ContextDir string `json:"context_dir"`
	// Dockerfile 是相对 ContextDir 的 dockerfile 路径（仅 dockerfile 驱动）。
	Dockerfile string `json:"dockerfile,omitempty"`
	// Target 是可选构建目标 stage（v0.1 不开，字段预留 compose 受控子集）。
	Target string `json:"target,omitempty"`
	// SpecHash 是归一化 compose 的 spec_hash（缓存键与可追溯成分）。
	SpecHash string `json:"spec_hash,omitempty"`
	// Platform 是构建目标平台（空 = 宿主默认 linux/amd64）。
	Platform string `json:"platform,omitempty"`
	// Secrets 是构建期凭证（key=值；经 buildkit session secrets 挂载，永不
	// 进镜像层——Spike A E3）。v0.1 构建无凭证输入（compose secrets 是运行
	// 期 Swarm secret），字段存在即契约：加入缓存键 secrets-hash，未来接入
	// 时凭证变化自动正确失效。
	Secrets map[string]string `json:"secrets,omitempty"`
}

type Result struct {
	// ImageRef 是本机镜像引用 fleetly-local/<app>:<tag>。
	ImageRef string
	// ImageDigest 是不可变镜像 ID（`sha256:<hex>` 配置摘要；部署引用取
	// digest，D9）。
	ImageDigest string
	// PlanPath 是 railpack plan JSON 归档路径（dockerfile 驱动为空）。
	PlanPath string
	// LogPath 是构建日志路径。
	LogPath string
	// Duration 是构建净耗时（二次构建加速对照的取证口径）。
	DurationSeconds float64
}