gosuda.org/zstd：无需 CGO 且具备崩溃隔离的 DataDog/zstd 即插即用压缩库

gosuda.org/zstd 是一个 CGO_ENABLED=0 的 Go 压缩库,它在隔离的工作进程中运行官方 C Zstandard(libzstd 1.5.7)引擎,并通过 HQQ 共享内存进行通信。它提供了与 github.com/DataDog/zstd 兼容的直接替换 API(包括一次性 Compress/Decompress、流式 io.Writer/io.Reader、预处理字典以及可复用的零分配上下文),同时使 C 代码的执行完全处于 Go 运行时地址空间之外。

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

为何解压应置于 Go 堆之外

在生产环境的后端系统中,压缩与解压直接位于不可信输入的边界上。日志收集器、消息代理、RPC 网关和存储引擎每分钟都要解压数吉字节的外部帧数据。

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

然而,通过 cgo 将 libzstd 链接到 Go 服务中,会带来两个运维方面的痛点:

1. 构建与部署摩擦:与 go-sqlite3 一样,DataDog/zstd 需要 CGO_ENABLED=1 以及目标 C 编译器工具链。为 linux/arm64 或 windows/arm64 进行交叉编译或构建静态二进制文件,需要外部 C 系统根目录(sysroot)。
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 调用方 (zstd.Ctx)                    共享内存槽位                          C11 工作进程 (zstd_hooks.c)
2--------------------                    ------------------                    -------------------------
3src []byte  ------------------------->  请求槽位载荷  ------------------------->  ZSTD_compressCCtx(
4                                                                                cctx, resp_slot, src, level)
5dst []byte  <-------------------------  响应槽位载荷  <-------------------------  将压缩帧直接写入
6                                                                              共享响应槽位

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 及以上),约 200 ns 的共享内存往返开销与 libzstd 内部消耗的 CPU 时间相比可以忽略不计。然而,对于一次压缩数千条 100 字节至 1 KiB 小消息的工作负载,即使每项仅耗费 200 ns,累积起来也相当可观。

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 或内存不足事件),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/架构目标)
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