c2402947a9
build / build (push) Successful in 1m26s
上游 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 项全绿。
254 lines
10 KiB
Go
254 lines
10 KiB
Go
// 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
|
||
}
|