Files
knowledge-governance/internal/librarydeadletter/deadletter.go
T
姚章浩 c2402947a9
build / build (push) Successful in 1m26s
feat(library): 死信按精确指纹解除,保留上游记录
上游 task_dead_letters 没有解决标记,purge/DELETE 会销毁"失败过"的唯一证据。
治理侧新增解除记录(迁移 073):绑定实时行逐字节指纹、重放引用、源侧观测摘要与
操作人;行被改过、重放后又出现新死信、源侧未结清都不命中,封存照旧阻断。
指纹先压紧空白再摘要,避免 PG to_jsonb::text 与 json.Marshal 的空白差异。

试过:go test ./internal/{librarydeadletter,libraryagent,httpapi,releaseadapter/v071,
platform/postgres},make verify 15 项全绿。
2026-10-29 06:55:13 +08:00

254 lines
10 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// Package librarydeadletter 定义上游死信(task_dead_letters)的精确解除契约。
//
// 为什么需要它:WeKnora v0.7.1 的 task_dead_letters 没有"已解决"标记,导出/封存
// 按"存在即阻断"处理。上游只提供两种运维动作——整队列 purge 与直接 DELETE,
// 两者都会销毁"这条任务失败过"的唯一证据,不能当作产品能力。治理平台因此保留
// 上游原始行,另外记录一条绑定到精确指纹的解除记录:指纹必须与实时行逐字节一致,
// 行变化或新死信出现都不再命中,继续阻断。
package librarydeadletter
import (
"bytes"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"strings"
"time"
)
// FingerprintPrefix 让指纹在日志/审计里自解释:算法一旦更换无需猜。
const FingerprintPrefix = "sha256:"
// Fingerprint 对上游用 to_jsonb(row)::text 取回的行文本求摘要。
//
// 为什么按原始行文本而不是逐字段重组:PostgreSQL 的 jsonb 文本已规范化(键有序),
// 任何字段变化都会改变字节;逐字段重组会漏掉上游新增列,等于给"行被改过"开后门。
func Fingerprint(raw []byte) string {
// 先压紧空白:PostgreSQL 的 to_jsonb::text 带空格,Go 的 json.Marshal 不带,
// 两边必须对同一份内容得到同一个指纹,否则解除永远命中不上。
compacted := raw
if len(raw) > 0 {
var buffer bytes.Buffer
if err := json.Compact(&buffer, raw); err == nil {
compacted = buffer.Bytes()
}
}
sum := sha256.Sum256(compacted)
return FingerprintPrefix + hex.EncodeToString(sum[:])
}
// ValidFingerprint 校验调用方传入的指纹形状,避免把通配符或截断值当解除依据。
func ValidFingerprint(value string) bool {
if !strings.HasPrefix(value, FingerprintPrefix) {
return false
}
body := strings.TrimPrefix(value, FingerprintPrefix)
if len(body) != 64 {
return false
}
_, err := hex.DecodeString(body)
return err == nil
}
// Row 是 task_dead_letters 的一行。字段与上游 000041 迁移一致;Payload 保留原始
// JSON 文本,因为任务参数本身就是证据。
type Row struct {
ID int64 `json:"id"`
TenantID uint64 `json:"tenant_id"`
TaskType string `json:"task_type"`
Scope string `json:"scope"`
ScopeID string `json:"scope_id"`
RelatedID string `json:"related_id"`
Payload json.RawMessage `json:"payload"`
LastError string `json:"last_error"`
FailCount int `json:"fail_count"`
FailedAt time.Time `json:"failed_at"`
}
// Settlement 只记录与死信无关的两个计数:未完成文档与待办操作。死信单独成表,
// 由指纹逐条解释,不能用"总数"含糊过去。
type Settlement struct {
Unsettled int64 `json:"unsettled"`
PendingOps int64 `json:"pending_ops"`
}
// Observation 是主机侧(能读源库的一方)生成的只读观测。治理平台不直接连源库,
// 因此解除记录绑定的是这份观测的摘要:平台重算摘要,换一个字节就不再接受。
type Observation struct {
Project string `json:"project"`
TenantID uint64 `json:"tenant_id"`
KnowledgeBaseID string `json:"kb_id"`
CapturedAt time.Time `json:"captured_at"`
Settlement Settlement `json:"settlement"`
Rows []json.RawMessage `json:"dead_letters"`
}
// Replay 记录"真实重放"的引用。平台无法自己向上游发起重放(那需要源侧管理员权限,
// 属于放大授权),所以只接受可核对的引用,并把"重放之后没有再次失败"作为机器检查项:
// 同一任务键在重放时间之后若出现新的死信行,解除无效。
type Replay struct {
Queue string `json:"queue"`
TaskID string `json:"task_id"`
At time.Time `json:"at"`
Evidence string `json:"evidence"`
}
// Request 是创建解除记录的输入。Observation 保持原始字节,摘要按这串字节计算。
type Request struct {
Project string `json:"project"`
TenantID uint64 `json:"tenant_id"`
KnowledgeBaseID string `json:"kb_id"`
DeadLetterID int64 `json:"dead_letter_id"`
Replay Replay `json:"replay"`
Note string `json:"note"`
Observation json.RawMessage `json:"observation"`
Digest string `json:"observation_digest"`
}
// Release 是验证通过后落库的解除记录。
type Release struct {
Project string
TenantID uint64
KnowledgeBaseID string
DeadLetterID int64
Fingerprint string
TaskType string
Scope string
ScopeID string
RelatedID string
Replay Replay
Observation json.RawMessage
Digest string
Note string
}
// Verify 检查解除请求是否可被接受。它不信任调用方自报的结论:
// 指纹由观测里的原始行重算,结清计数必须为 0,重放时间必须晚于失败时间,
// 且同一任务键在重放之后不得再有新的失败行。
func Verify(req Request, expectedProject string, now time.Time) (Release, error) {
if expectedProject == "" {
return Release{}, errors.New("死信解除需要平台侧已配置的实例身份")
}
if req.Project != "" && req.Project != expectedProject {
return Release{}, fmt.Errorf("解除记录实例 %q 与当前实例 %q 不一致", req.Project, expectedProject)
}
if req.DeadLetterID <= 0 {
return Release{}, errors.New("dead_letter_id 必须指定一条精确死信")
}
if len(req.Observation) == 0 || req.Digest == "" {
return Release{}, errors.New("缺少源侧观测或摘要")
}
if got := Fingerprint(req.Observation); got != req.Digest {
return Release{}, errors.New("观测摘要与提交的观测不一致(可能被改写或格式化)")
}
var observation Observation
if err := json.Unmarshal(req.Observation, &observation); err != nil {
return Release{}, errors.New("源侧观测不是合法 JSON")
}
if observation.Project != expectedProject {
return Release{}, fmt.Errorf("观测实例 %q 与当前实例 %q 不一致", observation.Project, expectedProject)
}
if observation.Settlement.Unsettled != 0 || observation.Settlement.PendingOps != 0 {
return Release{}, fmt.Errorf("源侧尚未结清:未完成文档 %d、待办操作 %d",
observation.Settlement.Unsettled, observation.Settlement.PendingOps)
}
if observation.CapturedAt.IsZero() || observation.CapturedAt.After(now.Add(time.Minute)) {
return Release{}, errors.New("源侧观测时间缺失或晚于当前时间")
}
if req.Replay.Queue == "" || req.Replay.TaskID == "" {
return Release{}, errors.New("重放必须给出队列与任务号")
}
if req.Replay.At.IsZero() {
return Release{}, errors.New("重放必须给出实际发生时间")
}
if req.Replay.At.After(now.Add(time.Minute)) {
return Release{}, errors.New("重放时间晚于当前时间")
}
if req.TenantID != 0 && observation.TenantID != 0 && req.TenantID != observation.TenantID {
return Release{}, errors.New("请求租户与观测租户不一致")
}
if req.KnowledgeBaseID != "" && observation.KnowledgeBaseID != "" && req.KnowledgeBaseID != observation.KnowledgeBaseID {
return Release{}, errors.New("请求知识库与观测知识库不一致")
}
var target *Row
var targetFingerprint string
for _, raw := range observation.Rows {
var row Row
if err := json.Unmarshal(raw, &row); err != nil {
return Release{}, errors.New("观测里的死信行不是合法 JSON")
}
if row.ID != req.DeadLetterID {
continue
}
if target != nil {
return Release{}, errors.New("观测里出现重复的死信 id")
}
copied := row
target = &copied
targetFingerprint = Fingerprint(raw)
}
if target == nil {
return Release{}, errors.New("观测里没有这条死信:上游记录可能已被删除,不能用解除掩盖删除")
}
if target.FailedAt.After(req.Replay.At) {
return Release{}, errors.New("重放时间早于这条死信的失败时间")
}
// 重放失败会再写一条死信行(asynq 中间件对每次耗尽都落一行)。同一任务键在
// 重放之后仍有新行,说明重放没有成功,或者又失败了一次。
for _, raw := range observation.Rows {
var row Row
if err := json.Unmarshal(raw, &row); err != nil {
return Release{}, errors.New("观测里的死信行不是合法 JSON")
}
if row.ID == target.ID {
continue
}
if sameKey(row, *target) && row.FailedAt.After(req.Replay.At) {
return Release{}, fmt.Errorf("重放之后同一任务仍产生新死信(id=%d),不能解除", row.ID)
}
}
if target.TenantID != observation.TenantID {
return Release{}, errors.New("死信租户与观测租户不一致")
}
return Release{
Project: observation.Project,
TenantID: target.TenantID,
KnowledgeBaseID: observation.KnowledgeBaseID,
DeadLetterID: target.ID,
Fingerprint: targetFingerprint,
TaskType: target.TaskType,
Scope: target.Scope,
ScopeID: target.ScopeID,
RelatedID: target.RelatedID,
Replay: req.Replay,
Observation: req.Observation,
Digest: req.Digest,
Note: req.Note,
}, nil
}
func sameKey(a, b Row) bool {
return a.TenantID == b.TenantID && a.TaskType == b.TaskType && a.Scope == b.Scope &&
a.ScopeID == b.ScopeID && a.RelatedID == b.RelatedID
}
// Unreleased 返回没有被精确解除记录覆盖的死信指纹。任何一行不匹配都阻断:
// 行被改过、出现新行、或解除记录缺失,三种情况都必须看得见。
func Unreleased(rows [][]byte, released map[string]bool) ([]string, error) {
missing := make([]string, 0, len(rows))
for _, raw := range rows {
var row Row
if err := json.Unmarshal(raw, &row); err != nil {
return nil, errors.New("源库死信行无法解析,按阻断处理")
}
digest := Fingerprint(raw)
if !released[digest] {
missing = append(missing, fmt.Sprintf("%d:%s", row.ID, digest))
}
}
return missing, nil
}