Go compress/zstd 多帧解压的内存控制

Go 项目里常说的 compress/zstd，本文指公开包 github.com/klauspost/compress/zstd。连续多帧解压要同时控制四项资源：压缩输入字节、单帧窗口、并发在途块和跨帧累计输出。只设置 WithDecoderMaxMemory 不能替代总输出上限，因为许多小 frame 仍可能连续产生大量数据。

官方包文档：https://pkg.go.dev/github.com/klauspost/compress/zstd

项目仓库：https://github.com/klauspost/compress/tree/master/zstd

用户任务：连续读完 frame，但不让内存失控

Zstandard 允许一个数据流由多个相互独立的 frame 组成。解码器可以流式读取它们，但“能读多帧”和“资源有上限”是两个不同问题。攻击者可以提供声明大窗口的 frame，也可以拼接大量小 frame，让每个 frame 都不过单帧限制，却让累计输出持续增长。

最稳妥的目标不是“估算最终大小后一次分配”，而是建立硬边界：

• 压缩输入最多读取多少字节；
• 单个 frame 可请求多大的解码窗口；
• 流式解码允许多少并发与预读；
• 所有 frame 合计最多写出多少解压字节。

交互拆解：内存不是一个开关

WithDecoderMaxWindow 用来拒绝请求过大窗口的 frame。WithDecoderMaxMemory 对流式解码主要约束窗口，对 DecodeAll 还承担内存解码大小限制。WithDecoderConcurrency(1) 关闭异步流式解码，减少在途块与 goroutine；WithDecoderLowmem(true) 进一步偏向低内存，但可能增加运行时分配。

这些选项约束的是解码器内部资源，不是整个多帧流的累计输出。累计输出必须由调用方在解码流外层计数。

组件实现：给多帧输出加硬上限

下面的函数不把完整输出保存在内存，而是把解码流写入调用方提供的 io.Writer。它从解码器最多读取 maxOutput+1 字节：多出的 1 字节只用于判断是否超限。压缩侧同样使用 maxCompressed+1 检测过大的输入。

package zstdlimit

import (
    "errors"
    "io"
    "math"

    "github.com/klauspost/compress/zstd"
)

var (
    ErrCompressedTooLarge = errors.New("zstd compressed input exceeds limit")
    ErrOutputTooLarge     = errors.New("zstd decoded output exceeds limit")
    ErrInvalidLimit       = errors.New("zstd limit must be positive and finite")
)

func DecodeFrames(
    src io.Reader,
    dst io.Writer,
    maxCompressed int64,
    maxOutput int64,
    maxWindow uint64,
    maxMemory uint64,
) error {
    // 需要加 1 做超限探测，因此拒绝零值、负值和 MaxInt64。
    if maxCompressed  maxOutput {
        return ErrOutputTooLarge
    }
    if compressed.N == 0 {
        // 成功解码时读取到了探测字节，说明压缩输入超过上限。
        return ErrCompressedTooLarge
    }
    return nil
}

如果 dst 是文件、对象存储上传流或受背压控制的网络 Writer，完整解压内容不会驻留在堆上。如果 dst 是 bytes.Buffer，仍然会保留最多 maxOutput+1 字节，因此上限必须按进程预算设置，而不是照搬业务允许的最大文件大小。

错误可见性：区分是哪一道边界拒绝

调用方至少要区分三类失败：

• 格式或完整性错误：魔数不匹配、截断、校验失败、未知字典等，由解码器返回。
• 解码器资源错误：frame 请求的窗口或解码内存超过配置，应记录为输入被拒绝，而不是服务内部故障。
• 应用配额错误：累计输出或压缩输入超过业务上限，返回稳定的业务错误。

日志应记录来源、压缩字节计数、已写输出字节和错误类别，不要记录完整压缩内容。对外部请求，超限通常映射为“载荷过大”或“压缩数据不符合策略”，不要暴露内部内存阈值。

性能检查：低内存设置也有代价

Concurrency=1 会减少并行解码和预读，吞吐可能低于默认配置；Lowmem(true) 可能以更多分配换较低常驻内存。选择时应同时测量峰值 RSS、分配次数、吞吐和尾延迟，而不是只看单次耗时。

高并发服务还要把“单请求上限”乘以最大并发数。即使每个解码器都限制为 32 MiB，100 个同时运行的请求仍可能形成不可接受的进程峰值。常见做法是在请求级限制之外，再加一个全局并发信号量或工作队列。

解码器可以通过 Reset 顺序复用以减少重复分配，但同一个流式 Decoder 不应同时服务多个流。长期池化还会保留已经增长的内部缓冲；当输入尺寸分布差异很大时，应为大任务单独建实例，或定期关闭并释放池中对象。

边界状态：这些测试不能省

最小配置速查

• 不可信数据优先使用流式 NewReader，避免无界 DecodeAll。
• 用 WithDecoderMaxWindow 拒绝大窗口 frame。
• 用 WithDecoderMaxMemory 设置解码器内存边界，但不要把它当累计输出配额。
• 内存优先时设置 WithDecoderConcurrency(1) 与 WithDecoderLowmem(true)。
• 在解码流外层统计 maxOutput+1，覆盖整个多帧序列。
• 对压缩输入、请求并发和目标 Writer 也分别设限。

多帧解压的关键是承认“每帧安全”不等于“整个流有界”。窗口限制保护解码器处理单个 frame，外部累计计数保护应用处理整条流，再配合输入和并发上限，才构成完整的内存控制。