- core/bindings 统一语义化版本:
0.1.9(当前)。 - 四处单一事实源(发布时四处必须同步;升级流程见 docs/maintenance.md):
- core:
core/version/version.go(Core = "0.1.9",gtls_version()输出) - Python:
bindings/python/pyproject.toml(version) - Node:
bindings/nodejs/package.json(version) - Python 包内:
bindings/python/geektls/__init__.py(__version__) ⇒ 第 4 处:0.1.4 及之前的清单只写了三处,漏了它(PyPI 元数据是 0.1.4、import geektls; geektls.__version__也是 0.1.4,靠人手同步,没有守门)。 现由tests/e2e/python/test_engine.py::test_version_sources_agree钉住: 绑定的__version__必须等于动态库gtls_version()["core"],漏改其中一处就红。
- core:
- ABI 只增不改(docs/02-ffi-abi.md §4):新增函数追加到函数表尾部;
不删不改签名。破坏性变更升
abi号,旧函数保留一个周期。 - 当前
abi = 1,与包版本0.1.9无锁定关系——abi 升位只在 ABI 破坏时发生。 - 绑定启动核对 abi:三语言绑定的
version()已断言abi == EXPECTED_ABI(不匹配报清晰错误——这是 noble-tls 用户最常见的坑,动态库与包错配)。 - core 版本核对:绑定在
version()里同时回读core字段;建议上层应用 在升级动态库后断言绑定声明的MIN_CORE(当前不强制,0.1.x 阶段 ABI 内 兼容;1.0 起把 core 版本也纳入硬校验)。 utls字段 = 指纹栈溯源(2026-09-29 接线):报告动态库里实际链接的 uTLS / fhttp / quic-go-utls 版本,由二进制 build info 推导(core/version.UTLSVersion), 本地 replace 的 vendor fork 显示为v0.6.9 => ./third_party/fhttp;取不到时为空串。 它与LICENSES.md登记的版本/commit 互为运行时与静态两面——自主化 SC-1~SC-3 完成后, 这条字段会变成"自有代码 + 上游基线"的形态,是那条迁移最直接的观测点。
- 发布面最低支持线 = go 1.26:
core/bindings/golang/tests/smoke的 go 指令统一1.26.x。依据:编译进 DLL 的依赖里要求最高的是golang.org/x/net v0.59.0(go ≥1.26.0);uTLS v1.8.2 / fhttp v0.6.9 / quic-go-utls 只需 ≥1.24。 2026-09-29 起实际为 1.26.3(gVisor 依赖的 go.mod 要求;netstack 档)。 - 测试面
tests/e2e= go 1.27.0:第二指纹预言机链gospider007/{fp,gtls,ja3,...}的 go.mod 要求 1.27.0,属测试专用依赖, 不影响发布面。 - CI 钉
go-version: '1.27'(同时满足两面);release-pypi.yml 用go-version-file: core/go.mod(=1.26 线,正确)。 - 规则:发布面升线只看"编进 DLL 的依赖"的最低要求;测试面可独立更高。
- 本项目自身许可证:MIT(根目录
LICENSE)。三处元数据同步:根LICENSE、bindings/python/pyproject.toml(license = "MIT"的 SPDX 表达式;按 PEP 639 不能再加License ::classifier,新版 setuptools 会报 InvalidConfigError)、bindings/nodejs/package.json("license": "MIT")。LICENSE与LICENSES.md随 wheel 分发(setuptools 的LICEN[CS]E*默认通配)。 - 见根目录 LICENSES.md:全闭包审计无 GPL/LGPL。 剩余注意项:上游 fhttp 无显式 LICENSE(风险登记,未关闭)、JA4+ 的许可证/商标边界 (只依赖 JA4 本体)。两条都不因本项目选 MIT 而消失。
- Python wheel / npm tgz 均把动态库打进包内(
package-data/files)—— 包内库与包版本天然锁死;运行时加载顺序(env → 包内 → 仓库 build → 系统) 保证"显式指定优先于包内",便于开发者替换动态库调试。 - 禁止混用"包 A 的绑定 + 包 B 的动态库":abi 校验在启动时拦截。
日常两条规则 + 发版一个动作(全在 GitHub 界面,无本地命令):
- 平时:面向用户的变更写进
CHANGELOG.md的## Unreleased段;代码 push 到 main (CI 照常跑测试,不发任何渠道)。 - 发版:Actions → release → Run workflow → 填版本号(如
0.1.9,不带 v)。 该 workflow 自动完成全部动作:- 四处版本源同步(
core/version.go/pyproject.toml/package.json/__init__.py)## Unreleased归并为## <版本>(日期);
- 提交 + 推送 main;打并推送四个 tag:
vX(PyPI 流水线触发口)、core/vX、bindings/golang/vX(Go module:tag 即发布)、npm/vX(npm 流水线触发口); - 三平台 smoke(c-shared 构建 + 三语言冒烟)作为发布门槛;
- PyPI(5 平台 wheel)与 npm(3 平台动态库 + publish)——经
workflow_call直接调用(⚠️ GITHUB_TOKEN 推的 tag 不会触发其它 workflow(GitHub 防递归), 所以总控显式调用,而非等 tag 连锁); - 建 GitHub Release 页面。
- 四处版本源同步(
发布后自动生效,无需任何操作:
- Go module:1–3 分钟后
go get github.com/geekbyter/geektls/core@vX可用; pkg.go.dev 自动刷新文档(https://pkg.go.dev/github.com/geekbyter/geektls/core、.../bindings/golang)——Go 没有"发布"动作,打对 tag 即发布。 - PyPI:
pip install geektls==X;npm:npm install geektls@X。
手动打 tag 仍可用(tag 连锁触发:vX→PyPI、npm/vX→npm、
core/vX+bindings/golang/vX→Go),但版本源必须提前同步(release-pypi 有
"四处一致 + 与 tag 匹配"校验,不一致会红)。
会拦住发布的三个点(自查):
- CHANGELOG 缺
## Unreleased段 ⇒ 总控第一步报错(先写 CHANGELOG); - 四个 tag 任一已存在 ⇒ 报错(版本号不可重发;错发只能新版本
retract/deprecate); - 主仓若开了保护分支 / 要求 PR ⇒ 需允许 GitHub Actions 直接 push main,否则 prepare 失败。
secrets 依赖:PYPI_API_TOKEN、NPM_TOKEN(均可经 npm Trusted Publishing /
PyPI 可信发布商迁移为 OIDC 免 token;未迁移时照旧可用)。
| 渠道 | 形态 | 状态 |
|---|---|---|
| PyPI | 平台标签 wheel(py3-none-<plat>,含该平台的动态库) |
本地构建+安装验证通过;上传方案与 CI 见 docs/plans/2026-09-28-pypi-release-plan.md |
wheel 标签必须按平台区分(py3-none-any 是错误的):包内带原生动态库,
标成 any 会让其他平台装完在加载库时失败。因为绑定是 ctypes(不依赖 CPython ABI),
每个平台只需一个轮子,而不是每个 Python 版本一个:
| 平台 | 标签 |
|---|---|
| Linux x86_64 | manylinux_2_28_x86_64 |
| Linux aarch64 | manylinux_2_28_aarch64 |
| macOS arm64 | macosx_11_0_arm64 |
| macOS x86_64 | macosx_11_0_x86_64(CI 在 arm64 runner 上交叉编译;macos-13 已下架) |
| Windows x64 | win_amd64 |
不发 sdist:从源码构建需要 Go 工具链 + C 编译器(失败率高),因此只发布 wheel; 不支持的平台由绑定在加载库时给出明确报错。 | npm | tgz(geektls-0.1.9.tgz,含动态库) | 本地构建+安装验证通过;上传待账号 | | Go module | 见下:当前 go.mod 发不出去 | 需先对齐 module path + 解决两个 vendor fork |
与 PyPI 的根本差别:Go module 没有"上传"动作——发布 = 在 git 仓打 tag,proxy 抓源码, 消费者自己编译。所以门槛不在"构建流水线",而在"依赖能不能被消费者解析":
| PyPI | Go module | |
|---|---|---|
| 发布动作 | python -m build + twine upload |
git tag + push(等 proxy 抓取) |
| 交付物 | 预编译 wheel(含动态库) | 源码,消费端编译 |
| 依赖解析 | 已打进 wheel,消费端不解析 | 消费端按你的 go.mod 自己解析;replace 只在主 module 生效,对消费者一律无效 |
| 撤回 | yank(可标记) | 删不掉(proxy 缓存 + sum.golang.org 校验和永久);只能在新版本 retract 提示 |
| 私有依赖 | 无 | 需 GOPRIVATE/凭证,或内化掉 |
前版记录的"三道闸门"已全部关闭:
- module path 已迁移:
github.com/geektls/core→github.com/geekbyter/geektls/core、github.com/geektls/golang→github.com/geekbyter/geektls/bindings/golang、github.com/geektls/tests/*→github.com/geekbyter/geektls/tests/*(全仓 import 同步重写)。 旧路径在 proxy 上是 404(不是被占用的命名空间);新路径与真实仓一致。 - 三个 vendor fork 已内联进 core 模块:
core/third_party/{fhttp,quic-go-utls,utls-bogdanfinn}删除各自的 go.mod/go.sum,成为 core 的普通子目录包 ⇒ 没有 replace 可被忽略, 消费者go get到的就是带完整补丁的代码。fork 内部互引与其依赖(qpack/circl/mlkem 等)由 core 的 go.mod 统一管理。 - 上游测试套件改为 opt-in:三个 fork 内联后,它们的上游测试(fhttp 的 net/http 套件
39 处、utls 的 crypto/tls 套件 64 处、quic-go-utls 的 self 集成测试)首次纳入
go test ./...范围,对 Go 版本漂移敏感(期望与新版 Go 行为的偏差,非 geektls 回归)。 处理:挂 opt-in build tag(geektls_upstream_nethttp_tests/geektls_upstream_utls_tests/geektls_upstream_quic_integrations),默认不跑; 需要时go test -tags geektls_upstream_nethttp_tests ./third_party/fhttp/显式开启。 geektls 自身行为由 e2e/parity 套件覆盖。 - 许可证:
fhttp上游无显式 LICENSE 的问题依旧存在(发布为公开 Go module = 公开 再分发源码)——LICENSES.md 阻塞项 1 仍需闭环。
- 前置(本地就能跑,别省):
cd core && go mod tidy && go build ./... && go test ./... -count=1 grep -c '^replace' go.mod # 必须为 0 grep -c bogdanfinn go.mod # 必须为 0(fork 已内联,不再引用上游路径)
- 打 tag(顺序:被依赖的先生效;这次只需要两个):
Go 只认 tag,不看分支;子目录 module 的 tag 必须带子目录前缀(
git tag core/v0.1.9 && git push origin core/v0.1.9 # 先 core git tag bindings/golang/v0.1.9 && git push origin bindings/golang/v0.1.9
core/v0.1.9解析的就是仓内core/)。仓库根的v0.1.9tag 是 PyPI 流水线的开关,照打不误—— 它对 Go 无害(根没有 go.mod,不会形成可用的根模块)。 - 发布后验证(照抄;首次抓取 1–3 分钟):
用默认的
curl -s https://proxy.golang.org/github.com/geekbyter/geektls/core/@v/list # 应列出 v0.1.9 cd "$(mktemp -d)" && go mod init t go get github.com/geekbyter/geektls/core@v0.1.9 && go build ./... # 真消费者验收 go list -m -versions github.com/geekbyter/geektls/core
GOSUMDB跑一遍(确认 sum.golang.org 能收录,而不是靠 GOPRIVATE 绕)。 - 撤回机制:发错不能删——在新版本的 go.mod 里
retract v0.1.8并在 tag 的 release note 说明;消费者go get -u会看到提示。 - 大版本:core 若升到 v2,module path 必须带
/v2后缀(语义化导入版本规则)。⚠️ bindings/golang/go.mod:require github.com/geekbyter/geektls/core v0.1.9(fork 依赖 由 core 传递,不必重复 require);本地开发用的replace => ../../core保留即可(消费者忽略)。