Documentation
¶
Overview ¶
Package artifactcache 提供 Worker 节点本地的内容寻址制品缓存（FR-178）。
痛点：建实例时 DownloadCore 每次都把核心 jar 重新下载到实例工作目录、不查本地有没有， 删实例再建 = 重下大 jar 等很久。本缓存按 sha256 持久缓存下载过的核心 jar，建实例命中 即从缓存秒拷到工作目录（免网络），未命中才下载并在校验后存入缓存。
布局：<root>/<sha256[:2]>/<sha256> 为 blob，<root>/<sha256[:2]>/<sha256>.meta 为 sidecar 元数据 JSON（name/type/version/sourceUrl/size/cachedAt/lastUsedAt）。 这是 Worker 本地派生资产，绝不进 CP 数据库，可随时整体删除重建。
范围（首版写死）：仅服务于 DownloadCore 的服务端核心 jar，不缓存插件/其它下载路径。 并发安全：写用临时文件 + 原子 rename；同 sha256 并发写「最后 rename 胜」，内容一致无害。
FR-330 增强：meta 增加组合缓存键 CoreKey（core|mcVersion|build），无 sha256 的下载源 （Sponge Maven 等）经 LookupCoreKey 反查命中；GetTo 命中时全量校验内容，损坏即作废回退。
Index ¶
- type Cache
- func (c *Cache) Cap() int64
- func (c *Cache) Clear() (int, error)
- func (c *Cache) EnforceCap() error
- func (c *Cache) Evict(sha string) error
- func (c *Cache) GetTo(sha, dest string) (bool, error)
- func (c *Cache) Has(sha string) bool
- func (c *Cache) List() ([]Entry, error)
- func (c *Cache) LookupCoreKey(key string) (string, bool)
- func (c *Cache) Put(sha, srcPath string, meta Meta) error
- func (c *Cache) SetCap(maxBytes int64)
- func (c *Cache) TotalBytes() (int64, error)
- type Entry
- type Meta
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache 是一个根目录下的内容寻址制品缓存。可被多个 goroutine 安全共享。
func (*Cache) EnforceCap ¶
EnforceCap 在设了 cap 时按 LRU（lastUsedAt 升序）淘汰，直到总占用回落到 cap 以内。 Put 内部会自动调用；外部改 cap（SetCap）后可显式调用以立即收敛。
func (*Cache) GetTo ¶
GetTo 把缓存中 sha256 的 blob 拷贝到 dest（命中返回 true 并 touch LastUsedAt）。 未命中返回 (false, nil) 且不创建 dest，调用方据此走下载路径。 拷贝用临时文件 + 原子 rename，避免半成品文件被实例读到。
命中校验（FR-330）：拷贝时全量核算内容 sha256，与缓存键不符（磁盘损坏/外部篡改） 即作废该条目并按未命中返回——绝不把脏内容交付给实例，调用方回退下载重建缓存。
func (*Cache) LookupCoreKey ¶
LookupCoreKey 按组合缓存键（FR-330：`core|mcVersion|build`）反查已缓存的 sha256。 多条命中（异常态：重复缓存）取 LastUsedAt 最新一条；空键/未命中返回 ("", false)。 缓存条目量级小（个位数~几十个核心 jar），全量扫描 meta 即可，不另建索引文件。
func (*Cache) Put ¶
Put 把 srcPath 文件存入缓存（键为 sha256，调用方保证内容确为该 sha256）。 已存在则仅刷新 meta（不重复拷贝）。存入后若设了 cap 且超限，按 LRU（lastUsedAt 升序）淘汰。 写用临时文件 + 原子 rename 保证并发安全。
func (*Cache) TotalBytes ¶
TotalBytes 返回缓存总占用字节（所有 blob 之和，不含 meta）。
type Entry ¶
type Entry struct {
SHA256 string `json:"sha256"`
Name string `json:"name"`
Type string `json:"type"`
Version string `json:"version"`
Size int64 `json:"size"`
CachedAt time.Time `json:"cachedAt"`
LastUsedAt time.Time `json:"lastUsedAt"`
// CoreKey 组合缓存键（FR-330），meta 缺失时为空。
CoreKey string `json:"coreKey,omitempty"`
}
Entry 是 List 返回的一条缓存项（合并 sha256 与元数据）。 meta 缺失（仅有 blob）时 Name/Version 为空、Size 取 blob 实际大小、LastUsedAt 取 blob mtime。
type Meta ¶
type Meta struct {
// Name 人类可读名称（如 "paper-1.20.4"），缺省可空。
Name string `json:"name"`
// Type 制品类型（首版固定 "core"）。
Type string `json:"type"`
// Version 版本标记（如 "1.20.4-435"），可空。
Version string `json:"version"`
// SourceURL 首次下载来源 URL（诊断用），可空。
SourceURL string `json:"sourceUrl"`
// Size 字节数。
Size int64 `json:"size"`
// CachedAt 首次存入缓存时间。
CachedAt time.Time `json:"cachedAt"`
// LastUsedAt 最近命中（GetTo）或存入时间，LRU 淘汰依据。
LastUsedAt time.Time `json:"lastUsedAt"`
// CoreKey 组合缓存键（FR-330）：sha256 未知的下载源（Sponge Maven 等）按
// `core|mcVersion|build` 反查缓存条目；可空（sha 键之外的补充索引）。
CoreKey string `json:"coreKey,omitempty"`
}
Meta 是缓存项的 sidecar 元数据（随 blob 一同落盘，命中时 touch LastUsedAt）。
Source Files