feat: relay-key 共用模块（三桥 + homeagent）
Sha256 clamp relay_key 过 160 字节上限，避免服务端 400 被 worker 当暂时失败让位，导致邮件驱动会话无本地 UI 静默挂死。 新增 relay_key.go / relay-key.js + 15 个纯函数测试。
This commit is contained in:
111
plugins/homeagent-mail-bridge/relay_key.go
Normal file
111
plugins/homeagent-mail-bridge/relay_key.go
Normal file
@ -0,0 +1,111 @@
|
||||
package main
|
||||
|
||||
// relay_key 长度收敛 —— 三个 Node 插件里 `lib/relay-key.js` 的 Go 对应物。
|
||||
//
|
||||
// **不能共用那个文件**（homeagent 是 Go 子进程插件），但语义必须一致 ——
|
||||
// 因此这里把那边的注释与判据原样搬过来，`relay_key_test.go` 逐条钉住。
|
||||
//
|
||||
// # 为什么需要它
|
||||
//
|
||||
// relay_key 是免配额通道的幂等键，服务端列宽 160 字节（超了返回 400）。
|
||||
// 插件按「会话 id + 某个平台侧调用 id」拼这个键，平常七十来字节，很安全。
|
||||
//
|
||||
// 但生产上踩到一次：pi 会话里 bash 的 relay_key 突然超限，报文
|
||||
// 「relay_key 过长（上限 160 字节）」。查真实会话文件后发现 toolCallId
|
||||
// 有两种形态：
|
||||
//
|
||||
// toolu_bdrk_01F6roEBHa8nic1mYiyLgNWK 35 字节
|
||||
// toolu_bdrk_01FsWUWhEs4arnEWo44gqzLC~sig1:CAISoQIK… 437 ~ 13601 字节
|
||||
//
|
||||
// 启用 extended thinking 时 Bedrock 把**思考签名**拼进了 toolCallId。
|
||||
// 同一条会话里两种形态混着出现，于是权限询问随机成功随机失败。
|
||||
//
|
||||
// homeagent 侧的键目前都是自己拼的（"homeagent:" + mailID），长度可控。
|
||||
// 但 mailID 来自 Gateway、replyTo 来自邮件头，都不是本地常量 —— 而
|
||||
// 「这个值一直很短」正是 pi 侧那次事故的前提假设。
|
||||
|
||||
import (
|
||||
"crypto/sha256"
|
||||
"encoding/hex"
|
||||
"fmt"
|
||||
"net/http"
|
||||
)
|
||||
|
||||
// RelayKeyMaxBytes 服务端 relay_key 列宽（字节）。与 gateway 侧 160 保持一致。
|
||||
const RelayKeyMaxBytes = 160
|
||||
|
||||
// hashSuffixBytes = len(":sha256:") + 64 位 hex
|
||||
const hashSuffixBytes = 8 + 64
|
||||
|
||||
// truncateToBytes 按字节截断，回退到最近的字符边界（不产生半个字符）。
|
||||
//
|
||||
// Go 的 string 是 UTF-8 字节序列，直接 s[:n] 会切出无效字节。
|
||||
// 键里可能有中文（邮件主题派生的键），按 rune 数算会超字节上限，
|
||||
// 按字节硬切会切出半个字符。
|
||||
func truncateToBytes(s string, maxBytes int) string {
|
||||
if maxBytes <= 0 {
|
||||
return ""
|
||||
}
|
||||
if len(s) <= maxBytes {
|
||||
return s
|
||||
}
|
||||
end := maxBytes
|
||||
// UTF-8 续字节是 10xxxxxx。若切点落在字符中间，往前退到该字符首字节之前。
|
||||
for end > 0 && s[end]&0xc0 == 0x80 {
|
||||
end--
|
||||
}
|
||||
return s[:end]
|
||||
}
|
||||
|
||||
// ClampRelayKey 把 relay_key 收敛到服务端能接受的长度。
|
||||
//
|
||||
// 未超限时**原样返回** —— 这一点很重要：绝大多数键本来就合规，
|
||||
// 改写它们会让插件升级前后算出不同的键，等于把已发出的询问变成新询问。
|
||||
//
|
||||
// 超限时用 sha256 而不是直接截断：直接截断会让两次不同的调用撞成同一个键
|
||||
// （前缀相同后缀被切掉），而这个键的全部意义是幂等 —— 撞键意味着第二次
|
||||
// 询问被服务端当成重复请求丢掉。保留可读前缀让日志里 grep 会话 id 仍然有用。
|
||||
func ClampRelayKey(key string) string {
|
||||
return clampRelayKeyTo(key, RelayKeyMaxBytes)
|
||||
}
|
||||
|
||||
func clampRelayKeyTo(key string, limit int) string {
|
||||
if len(key) <= limit {
|
||||
return key
|
||||
}
|
||||
sum := sha256.Sum256([]byte(key))
|
||||
hash := hex.EncodeToString(sum[:])
|
||||
// 上限小到装不下哈希时只留哈希（截断哈希仍然确定，只是碰撞面变大；
|
||||
// 这条路径在真实配置下不会走到 —— 160 远大于 72）。
|
||||
if limit <= hashSuffixBytes {
|
||||
return truncateToBytes(hash, limit)
|
||||
}
|
||||
return fmt.Sprintf("%s:sha256:%s", truncateToBytes(key, limit-hashSuffixBytes), hash)
|
||||
}
|
||||
|
||||
// IsPermanentFailure 这次失败是不是「永远不会成功」。
|
||||
//
|
||||
// # 为什么必须分类
|
||||
//
|
||||
// 插件在请求失败时有两条路：重试/让位，或当场表态。原来除 409 之外
|
||||
// 一律当「暂时失败」—— 而 400（请求本身不合法）重试一万次也是 400。
|
||||
// 邮件驱动的会话没有本地 UI，让位等于让守卫消失。
|
||||
//
|
||||
// # 判据
|
||||
//
|
||||
// - 4xx（除 408 / 429）= 永久：请求本身有问题，重试不会变好
|
||||
// - 408 / 429 = 暂时：超时与限流，等一会儿真的可能成功
|
||||
// - 5xx = 暂时：服务端的问题
|
||||
// - status <= 0（网络层错误、DNS、连接被拒）= 暂时
|
||||
//
|
||||
// 401 归到永久：密钥无效要人去后台重新登记，不是等一等就好的事
|
||||
// （实测过一次 —— opencode 拿着已撤销的密钥重试了 18 小时，2690 次 401）。
|
||||
func IsPermanentFailure(status int) bool {
|
||||
if status <= 0 {
|
||||
return false
|
||||
}
|
||||
if status == http.StatusRequestTimeout || status == http.StatusTooManyRequests {
|
||||
return false
|
||||
}
|
||||
return status >= 400 && status < 500
|
||||
}
|
||||
244
plugins/homeagent-mail-bridge/relay_key_test.go
Normal file
244
plugins/homeagent-mail-bridge/relay_key_test.go
Normal file
@ -0,0 +1,244 @@
|
||||
package main
|
||||
|
||||
// relay_key.go 的测试 —— 逐条对齐 Node 侧 test/relay-key.test.mjs。
|
||||
//
|
||||
// 事故背景（生产实测）：pi 会话里 bash 的 relay_key 突然超过服务端 160 字节
|
||||
// 列宽，返回 400。真实会话文件里 toolCallId 有两种形态：
|
||||
//
|
||||
// toolu_bdrk_01F6roEBHa8nic1mYiyLgNWK 35 字节
|
||||
// toolu_bdrk_01FsWUWhEs4arnEWo44gqzLC~sig1:CAISoQIK… 437 ~ 13601 字节
|
||||
//
|
||||
// 启用 extended thinking 时 Bedrock 把思考签名拼进了 toolCallId。
|
||||
// 更严重的是那次 400 被归入「暂时失败 → 让位给本地决策」，而邮件驱动的
|
||||
// worker 没有 TUI —— 那次 bash 没有任何人批准就执行了。
|
||||
|
||||
import (
|
||||
"crypto/sha256"
|
||||
"encoding/hex"
|
||||
"strings"
|
||||
"testing"
|
||||
"unicode/utf8"
|
||||
)
|
||||
|
||||
// ─── truncateToBytes ───
|
||||
|
||||
func TestTruncateToBytes_UnderLimit(t *testing.T) {
|
||||
if got := truncateToBytes("abcdef", 10); got != "abcdef" {
|
||||
t.Fatalf("未超限应原样返回，得到 %q", got)
|
||||
}
|
||||
if got := truncateToBytes("abcdef", 6); got != "abcdef" {
|
||||
t.Fatalf("恰好等于上限应原样返回，得到 %q", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestTruncateToBytes_ASCII(t *testing.T) {
|
||||
if got := truncateToBytes("abcdef", 3); got != "abc" {
|
||||
t.Fatalf("want abc, got %q", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestTruncateToBytes_NoHalfRune(t *testing.T) {
|
||||
// "中文" = 6 字节。上限 4 时不能切出 "中" + 半个 "文"
|
||||
got := truncateToBytes("中文", 4)
|
||||
if got != "中" {
|
||||
t.Fatalf("want 中, got %q", got)
|
||||
}
|
||||
if !utf8.ValidString(got) {
|
||||
t.Fatal("截断结果不是合法 UTF-8")
|
||||
}
|
||||
}
|
||||
|
||||
func TestTruncateToBytes_AllLimitsStayValid(t *testing.T) {
|
||||
s := "会话abc标识def中文gh"
|
||||
for limit := 0; limit <= len(s)+2; limit++ {
|
||||
got := truncateToBytes(s, limit)
|
||||
if len(got) > limit {
|
||||
t.Fatalf("limit=%d 时超了：%d 字节", limit, len(got))
|
||||
}
|
||||
if !utf8.ValidString(got) {
|
||||
t.Fatalf("limit=%d 时切出了半个字符", limit)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestTruncateToBytes_ZeroOrNegative(t *testing.T) {
|
||||
if got := truncateToBytes("abc", 0); got != "" {
|
||||
t.Fatalf("上限 0 应返回空串，得到 %q", got)
|
||||
}
|
||||
if got := truncateToBytes("abc", -5); got != "" {
|
||||
t.Fatalf("负上限应返回空串，得到 %q", got)
|
||||
}
|
||||
}
|
||||
|
||||
// ─── ClampRelayKey ───
|
||||
|
||||
func TestClampRelayKey_NormalKeyUnchanged(t *testing.T) {
|
||||
// homeagent 侧真实的键形状
|
||||
key := "homeagent:53e4c9ea-878c-4479-b2f7-58b4be36cf96"
|
||||
if len(key) > RelayKeyMaxBytes {
|
||||
t.Fatalf("这个键本来就该合规，长度 %d", len(key))
|
||||
}
|
||||
if got := ClampRelayKey(key); got != key {
|
||||
t.Fatalf("合规的键必须原样返回（否则升级前后算出不同键），得到 %q", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestClampRelayKey_ExactlyAtLimit(t *testing.T) {
|
||||
key := strings.Repeat("k", RelayKeyMaxBytes)
|
||||
if got := ClampRelayKey(key); got != key {
|
||||
t.Fatal("恰好等于上限时应原样返回（边界不能差一）")
|
||||
}
|
||||
}
|
||||
|
||||
func TestClampRelayKey_OneByteOver(t *testing.T) {
|
||||
key := strings.Repeat("k", RelayKeyMaxBytes+1)
|
||||
got := ClampRelayKey(key)
|
||||
if got == key {
|
||||
t.Fatal("超一个字节就该收敛")
|
||||
}
|
||||
if len(got) > RelayKeyMaxBytes {
|
||||
t.Fatalf("收敛后仍然超限：%d 字节", len(got))
|
||||
}
|
||||
}
|
||||
|
||||
func TestClampRelayKey_RealWorldLengths(t *testing.T) {
|
||||
// 生产实测 437 ~ 13601 字节都出现过
|
||||
for _, n := range []int{437, 1000, 5493, 13601} {
|
||||
key := "homeagent:toolu_bdrk_01X~sig1:" + strings.Repeat("A", n)
|
||||
got := ClampRelayKey(key)
|
||||
if len(got) > RelayKeyMaxBytes {
|
||||
t.Fatalf("n=%d 时超了：%d 字节", n, len(got))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestClampRelayKey_Deterministic(t *testing.T) {
|
||||
key := "sess:" + strings.Repeat("x", 500)
|
||||
if ClampRelayKey(key) != ClampRelayKey(key) {
|
||||
t.Fatal("同一输入必须得到同一输出（幂等键的根本要求）")
|
||||
}
|
||||
}
|
||||
|
||||
// 这正是不能直接截断的理由：两个键前 160 字节完全相同，
|
||||
// 直接截断会让它们变成同一个键，第二次询问被服务端当重复请求丢掉。
|
||||
func TestClampRelayKey_NoCollisionOnSharedPrefix(t *testing.T) {
|
||||
common := strings.Repeat("a", 300)
|
||||
k1 := common + ":call-1"
|
||||
k2 := common + ":call-2"
|
||||
if ClampRelayKey(k1) == ClampRelayKey(k2) {
|
||||
t.Fatal("前缀相同尾部不同的两个键不能撞成一个")
|
||||
}
|
||||
}
|
||||
|
||||
func TestClampRelayKey_KeepsReadablePrefix(t *testing.T) {
|
||||
prefix := "homeagent:53e4c9ea-878c-4479-b2f7-58b4be36cf96"
|
||||
got := ClampRelayKey(prefix + ":" + strings.Repeat("A", 900))
|
||||
if !strings.HasPrefix(got, prefix) {
|
||||
t.Fatalf("收敛结果应保留可读前缀（日志里还能 grep），得到 %q", got)
|
||||
}
|
||||
if !strings.Contains(got, ":sha256:") {
|
||||
t.Fatalf("收敛结果应带 sha256 后缀，得到 %q", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestClampRelayKey_HashIsOfOriginalKey(t *testing.T) {
|
||||
key := "sess:" + strings.Repeat("y", 400)
|
||||
sum := sha256.Sum256([]byte(key))
|
||||
want := hex.EncodeToString(sum[:])
|
||||
if !strings.HasSuffix(ClampRelayKey(key), ":sha256:"+want) {
|
||||
t.Fatal("哈希必须是原始键的完整 sha256，不是截断后的")
|
||||
}
|
||||
}
|
||||
|
||||
func TestClampRelayKey_CJKNoHalfRune(t *testing.T) {
|
||||
key := "会话标识:" + strings.Repeat("中", 300)
|
||||
got := ClampRelayKey(key)
|
||||
if len(got) > RelayKeyMaxBytes {
|
||||
t.Fatalf("超限：%d 字节", len(got))
|
||||
}
|
||||
if !utf8.ValidString(got) {
|
||||
t.Fatal("切出了半个字符")
|
||||
}
|
||||
}
|
||||
|
||||
func TestClampRelayKey_TinyLimitFallsBackToHash(t *testing.T) {
|
||||
key := strings.Repeat("z", 500)
|
||||
got := clampRelayKeyTo(key, 20)
|
||||
if len(got) > 20 {
|
||||
t.Fatalf("超限：%d 字节", len(got))
|
||||
}
|
||||
if got != clampRelayKeyTo(key, 20) {
|
||||
t.Fatal("退化路径也必须确定")
|
||||
}
|
||||
}
|
||||
|
||||
func TestClampRelayKey_Empty(t *testing.T) {
|
||||
if got := ClampRelayKey(""); got != "" {
|
||||
t.Fatalf("空键应返回空串，得到 %q", got)
|
||||
}
|
||||
}
|
||||
|
||||
// ─── IsPermanentFailure ───
|
||||
|
||||
func TestIsPermanentFailure_400(t *testing.T) {
|
||||
// 事故的核心：原来 400 被当暂时失败让位，那条 bash 无人批准就执行了
|
||||
if !IsPermanentFailure(400) {
|
||||
t.Fatal("400 必须是永久失败")
|
||||
}
|
||||
}
|
||||
|
||||
func TestIsPermanentFailure_409(t *testing.T) {
|
||||
// 这条链上没有人类，永远不会有人点头
|
||||
if !IsPermanentFailure(409) {
|
||||
t.Fatal("409 必须是永久失败")
|
||||
}
|
||||
}
|
||||
|
||||
func TestIsPermanentFailure_401(t *testing.T) {
|
||||
// 实测：opencode 拿着已撤销的密钥重试了 18 小时，2690 次 401
|
||||
if !IsPermanentFailure(401) {
|
||||
t.Fatal("401 必须是永久失败：密钥无效要人去后台登记")
|
||||
}
|
||||
}
|
||||
|
||||
func TestIsPermanentFailure_Other4xx(t *testing.T) {
|
||||
for _, s := range []int{403, 404, 422} {
|
||||
if !IsPermanentFailure(s) {
|
||||
t.Fatalf("%d 应当是永久失败", s)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestIsPermanentFailure_TimeoutAndRateLimit(t *testing.T) {
|
||||
if IsPermanentFailure(408) {
|
||||
t.Fatal("408 是暂时失败（超时，等一会儿可能成功）")
|
||||
}
|
||||
if IsPermanentFailure(429) {
|
||||
t.Fatal("429 是暂时失败（限流，等一会儿可能成功）")
|
||||
}
|
||||
}
|
||||
|
||||
func TestIsPermanentFailure_5xx(t *testing.T) {
|
||||
for _, s := range []int{500, 502, 503, 504} {
|
||||
if IsPermanentFailure(s) {
|
||||
t.Fatalf("%d 是暂时失败（服务端的问题）", s)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestIsPermanentFailure_NoStatus(t *testing.T) {
|
||||
// 网络层错误：DNS 解析失败、连接被拒，都没有 HTTP 状态码
|
||||
if IsPermanentFailure(0) {
|
||||
t.Fatal("无 status 应按暂时处理")
|
||||
}
|
||||
if IsPermanentFailure(-1) {
|
||||
t.Fatal("负 status 应按暂时处理")
|
||||
}
|
||||
}
|
||||
|
||||
func TestIsPermanentFailure_Success(t *testing.T) {
|
||||
// 本不该走到这里，但不能误判成永久
|
||||
if IsPermanentFailure(200) || IsPermanentFailure(302) {
|
||||
t.Fatal("2xx / 3xx 不算永久失败")
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user