gosuda.org/zstd: 具备零 CGO 与崩溃隔离功能的 Drop-In DataDog/zstd 压缩

gosuda.org/zstd 是一个 CGO_ENABLED=0 的 Go 压缩库，它在隔离的工作进程中通过 HQQ 共享内存运行官方的 C Zstandard（libzstd 1.5.7）引擎。它为 github.com/DataDog/zstd 提供了一个直接替代的 API（包括单次 Compress/Decompress、流式 io.Writer/io.Reader、预处理字典以及可重用的零分配 context），同时将 C 语言的执行完全置于 Go 运行时地址空间之外。

1go get gosuda.org/zstd@v0.3.10507

为什么解压应当脱离你的 Go 堆内存

在生产环境的后端中，压缩和解压直接位于不受信任的输入边界上。日志收集器、消息代理、RPC 网关和存储引擎每分钟都在解压数千兆字节外部提供的帧。

许多 Go 团队选择 github.com/DataDog/zstd 是因为它直接绑定到上游的 C 语言 libzstd：C 语言实现提供了高的单核吞吐量、针对小记录的紧凑字典压缩比，以及不增加 Go 垃圾回收扫描时间的堆外 C 内存区（ZSTD_CCtx 和 ZSTD_DCtx）。

然而，通过 cgo 将 libzstd 链接到 Go 服务中会带来两个运营痛点：

1. 构建与部署摩擦：就像 go-sqlite3 一样，DataDog/zstd 要求 CGO_ENABLED=1 以及目标 C 编译器工具链。交叉编译服务或为 linux/arm64 或 windows/arm64 构建静态二进制文件需要外部的 C 系统根目录。
2. 不受信任输入下的共享地址空间：在与 Go 服务器相同的虚拟地址空间内解压损坏或对抗性的有效载荷，意味着原生 C 代码或自定义字典处理中的任何漏洞都可能终止整个 Go 进程。

gosuda.org/zstd 保留了精确的上游 C 语言 libzstd 1.5.7 引擎以及熟悉的 github.com/DataDog/zstd API，但将 C 语言的执行移至一个经过验证的子进程（zstd_server）中，该子进程通过缓存行共享内存与你的 Go 程序相连。

github.com/DataDog/zstd 的直接替代品

从 github.com/DataDog/zstd 迁移只需将导入路径更改为 "gosuda.org/zstd"。无需安装外部二进制文件或进行设置代码：在首次调用时，gosuda.org/zstd 会为你的平台具现化一个内嵌的、经 SLSA 认证的 zstd_server 二进制文件，通过 gosuda.org/hqq/secureexec 验证其 SHA-256 摘要，并打开一个共享内存会话池。

 1package main
 2
 3import (
 4	"bytes"
 5	"fmt"
 6	"io"
 7	"log"
 8
 9	"gosuda.org/zstd"
10)
11
12func main() {
13	// 1. 单次 Compress / Decompress（镜像 github.com/DataDog/zstd）
14	src := []byte("shared-memory zstd payload without cgo")
15	compressed, err := zstd.CompressLevel(nil, src, zstd.BestSpeed)
16	if err != nil {
17		log.Fatal(err)
18	}
19	plain, err := zstd.Decompress(nil, compressed)
20	if err != nil {
21		log.Fatal(err)
22	}
23	fmt.Printf("one-shot: %d bytes -> %d bytes (%s)\n", len(src), len(compressed), plain)
24
25	// 2. 带有字典支持的流式 Writer 和 Reader
26	var buf bytes.Buffer
27	w := zstd.NewWriterLevel(&buf, zstd.DefaultCompression)
28	if _, err := w.Write(src); err != nil {
29		log.Fatal(err)
30	}
31	if err := w.Close(); err != nil {
32		log.Fatal(err)
33	}
34
35	r := zstd.NewReader(&buf)
36	defer r.Close()
37	streamed, err := io.ReadAll(r)
38	if err != nil {
39		log.Fatal(err)
40	}
41	fmt.Printf("streamed: %s\n", streamed)
42}

支持的平台和内嵌二进制文件

所有六个目标平台都随附了通过平台特定构建标签（internal/embedded/embed_<goos>_<goarch>.go）内嵌的预构建、SHA-256 固定的工作进程二进制文件：

共享内存数据路径内部原理

为了使吞吐量与进程内的 cgo 保持竞争力，gosuda.org/zstd 在热路径上避免了套接字序列化和堆内存分配。

1. 零分配槽位编码（zstd_ctx.go 和 c/zstd_hooks.c）

当你使用可重用的 zstd.Ctx（或者当包级别的 Compress 和 Decompress 函数从内部会话池中借用一个 Ctx 时），数据将直接通过映射的 StandardLink 槽位流动：

1Go Caller (zstd.Ctx)                    Shared-Memory Slot                    C11 Worker (zstd_hooks.c)
2--------------------                    ------------------                    -------------------------
3src []byte  ------------------------->  Request Slot Payload  ------------->  ZSTD_compressCCtx(
4                                                                                cctx, resp_slot, src, level)
5dst []byte  <-------------------------  Response Slot Payload <-------------  Writes compressed frame directly
6                                                                              into shared response slot

1. 生成的 hqq-bindgen 客户端将 src 直接复制到内存映射的请求槽位中，并翻转 SeqLock 序列字。
2. C 工作进程在请求槽位中就地读取 src，并将响应槽位的有效载荷指针直接作为目标缓冲区传递给 ZSTD_compressCCtx 或 ZSTD_decompressDCtx。
3. Go 客户端将生成的切片从响应槽位复制到调用者提供的 dst 切片中。在稳定状态下，ctx.CompressTo(dst, src, level) 和 ctx.DecompressInto(dst, src) 执行 0 allocs/op。

预处理字典（CDict 和 DDict）位于 C 工作进程中，由经过生成检查的 64 位句柄（zstd.idl 中的 handle CDict、handle DDict）支持。通过 ctx.NewCDict(rawDict, level) 一次性创建字典会在 C 工作进程内部解析字典表，并返回一个轻量级句柄，该句柄可以在数千次调用中重复使用，而无需重新发送字典字节。

2. 通过批量分帧来摊销 IPC 开销（zstd_bulk.go）

对于大型有效载荷（16 KiB 及以上），与在 libzstd 内部花费的 CPU 时间相比，约 200 纳秒的共享内存往返微不足道。然而，对于同时压缩数千条 100 字节到 1 KiB 的小型消息的工作负载而言，每个项目支付哪怕 200 纳秒也会积少成多。

gosuda.org/zstd 在 BulkCtx（zstd_bulk.go）上提供了 CompressBulk 和 DecompressBulk 以消除每个项目的往返开销：

 1bctx, err := client.NewBulkCtx(1 << 20)
 2if err != nil {
 3	log.Fatal(err)
 4}
 5defer bctx.Close()
 6
 7items := [][]byte{
 8	[]byte(`{"event":"login","user":101}`),
 9	[]byte(`{"event":"purchase","user":101,"amount":4200}`),
10	[]byte(`{"event":"logout","user":101}`),
11}
12compressedItems, err := bctx.CompressBulk(nil, items, zstd.DefaultCompression)

CompressBulk 将整个 [][]byte 批次打包到共享内存中的单个带长度前缀的请求帧中。C 工作进程在 C 中循环遍历每个项目（c/zstd_hooks.c 中的 compress_bulk），将所有压缩帧连续写入响应槽位，并在单次共享内存往返中返回整个批次。

3. 在不崩溃调用者的前提下存活于工作进程终止

由于 zstd_server 运行在单独的操作系统进程中，C 工作进程内部的致命失败绝不会导致你的 Go 应用程序崩溃：

• 如果 zstd_server 在外部被杀死（例如通过 SIGKILL 或 OOM 事件），HQQ 传输层会立即检测到断开的对端，并从正在进行的 Compress 或 Decompress 调用中返回一个类型化的 *rt.TransportError。
• 包级函数（zstd.Compress、zstd.Decompress、zstd.NewWriter、zstd.NewReader）会自动检测到共享的默认工作进程已消失，在下一次调用时衍生出一个全新的、经过验证的 zstd_server 实例，并恢复正常操作。

仓库布局

代码库将直接替换的 DataDog/zstd 门面与低级的 hqq-bindgen 会话和批量原语进行了分离：

1gosuda.org/zstd
2├── autolaunch.go / hashes.go  # 直接替换的 Compress/Decompress API、自动恢复池以及 SHA-256 哈希
3├── zstd_stream.go             # 流式 Writer/Reader（NewWriterLevelDict、NewReaderDict）
4├── zstd_ctx.go                # 基于 hqq-bindgen 包装的零分配 Ctx、CDict 和 DDict
5├── zstd_bulk.go               # 单次往返的 CompressBulk 和 DecompressBulk 分帧
6├── zstd.go                    # 为 zstd IDL 服务生成的 hqq-bindgen Go 客户端
7├── zstd.idl                   # 定义 Context、CDict、DDict 以及 RPC 方法的 HQQ IDL 架构
8├── internal/embedded/         # 带有平台标记的 //go:embed zstd_server 二进制文件（6 个 OS/Arch 目标）
9└── c/                         # C11 服务器实现（zstd_server.c、zstd_hooks.c、main.c）

入门指南

使用 go get 安装 gosuda.org/zstd，并在 CGO_ENABLED=0 的情况下使用它：

1go get gosuda.org/zstd@v0.3.10507

• GitHub 仓库：https://github.com/gosuda/hqq-zstd
• 架构与基准测试：docs/ARCHITECTURE.md
• HQQ 核心运行时：https://gosuda.org/hqq