Reliability and Consistency Contract zh

可靠性与一致性契约

SPACK 把资源交付视为协议契约，而不只是实现层面的单元测试。

默认 CI 门禁

• Ubuntu 和 Windows 上运行 task lint、task check、task test 和 task build。
• Linux CI 上运行 task test:race。
• fuzz target 以普通 Go fuzz 测试提交，因此 seed corpus 会在 go test ./... 中运行。
• task integration:container:smoke 会在 Linux CI 上针对构建出的容器镜像执行。

协议覆盖

HTTP 矩阵覆盖：

• GET 和 HEAD。
• ETag 和 If-None-Match。
• Last-Modified 和 If-Modified-Since。
• Range 部分内容。
• Range 加 Accept-Encoding，其中 Range 请求必须绕过编码变体，并保留部分响应头语义。

重点 fuzz target 覆盖：

• request path 归一化，包括编码路径穿越、反斜杠和类似 UNC 的输入。
• Accept-Encoding 解析。
• 图片 Accept 解析。
• HTTP 边界上的 Range header 处理。

运行扩展 fuzz：

task test:fuzz:parsers

源资源与缓存一致性

源资源重新扫描测试需要断言文件修改、删除和重命名会同步修正：

• catalog 条目。
• 源资源 sidecar 变体。
• 生成的 artifact 变体。
• memory cache 条目。
• 磁盘上的 artifact 文件。

一致性规则很严格：已经过期的源资源不能继续保留过期 catalog 记录、内存缓存条目或生成产物。

编译期产物契约

压缩和图片生成是构建期优化步骤。运行时必须能够在不把重型生成逻辑放入请求路径的前提下，服务原始源资源或预计算产物。

编译器应该记录足够的元数据，让运行时选择已经准备好的响应计划，包括源字节数、输出字节数、目标编码或图片格式、尺寸和缓存策略。

图片生成契约

图片引擎使用 libvips。SPACK 的图片生成需要 CGO 和原生 libvips 库。

• 图片任务按源资源批处理。
• 每个批次只打开并解码一次源图片。
• 宽度变体从金字塔生成，因此较小宽度可以复用最近的较大 resize 结果。
• 写入产物前需要执行源字节数、像素数、宽高、全局预估解码内存预算和输出变体数量限制。
• 生成变体元数据记录源字节数、源像素数、源尺寸、输出字节数、输出尺寸、节省字节数、节省比例、目标格式和引擎名称。
• 低收益变体会被跳过，不写入磁盘。
• 编译器构建和执行环境中都必须存在原生 libvips 运行时库。

容器黑盒契约

容器 smoke 测试使用实际镜像启动，并要求：

• read-only root filesystem。
• drop all Linux capabilities。
• no-new-privileges。
• 只读资源卷。
• 用于运行时临时文件的可写 /tmp tmpfs。

测试会对运行中的容器验证 /livez、/、/app.js 和 Range 请求。

Catalog 压力测试

大规模 catalog 扫描是 opt-in，因为它会创建大量文件。

task test:stress:catalog
SPACK_STRESS_ASSET_COUNT=1000000 task test:stress:catalog

压力测试会在 test log 中记录资源数量、扫描耗时、源字节数和 heap delta。发布准入应保存这些日志，并同时记录被测机器规格和镜像 digest。