Files
knowledge-governance/internal/governance/library_operation.go
T
姚章浩 a7d643635a
build / build (push) Successful in 1m27s
fix(library): 守卫按行取作业身份、同作业多代次、原作业续作与执行域准入
R1 维护/发布守卫硬编码 j.id=$1:维护类入口的 $1 是 scope/instance,作业号在 $2,
导致 update/release/ingress 六个入口正常路径全部匹配不到作业。改为按被更新行自己的
owner_job_id 生成条件,并同时要求该代次在 library_attempts 里仍活跃。

R2 认领只改 jobs.attempt_epoch 不改 attempts.epoch,第二次接管即错位;唯一索引
(job_id) 与"每次接管新 attempt 且历史不可变"矛盾。改为同作业多代次:锁作业行与
operation 行、同 owner 幂等续租、活跃未过期者让路、过期/本作业旧代次标 abandoned、
新代次 epoch=max+1,并清同 operation 其它作业行租约。迟到 write/renew/finish 一律
ErrLibraryEpochStale(finish 补了"只能在活跃态进来一次")。

R3 续作不再新建 -resume 作业:PrepareLibraryJobResume 让原业务作业回 pending 并显式
结束上一代,维护窗口/journal/预备份/写集合仍按原作业 id 归属,代次由 worker 起手递增。

R4 执行域准入改为注册 handler 前读事实:目标实况(KB/租户/schema/索引)、旧 release
路由绑定的 KB、未释放维护窗口持有者;未知或重叠即拒绝执行(不做维护动作、不停既有服务)。

同时自纠 5 项设计偏离:current 次序键取意图创建时间(旧意图迟到事实被拒)、首次锚点
改事务 FOR UPDATE + 回读且 NULL≠0、版本事件冲突只做加法且 xmax=0 才算新事实、
恢复作为新 kind=recover 意图推进 current、隔离测试加测试库护栏并清理残留 schema。

测试:真实 PG(kg-pgtest-writeset,一用例一 schema)新增 8 条集成用例覆盖上述正负例;
go test ./... 全绿(50 包)、go vet/build rc=0、web tsc + vitest 485 通过、make verify 16 项通过。
2026-10-30 17:20:40 +08:00

156 lines
7.8 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 governance
import (
"crypto/sha256"
"encoding/hex"
"errors"
"fmt"
"strings"
"time"
)
// 发布执行身份:operation / attempt 与版本事件、current 指针的唯一约定。
//
// 为什么必须把这几件事分开:
// - operation 是**用户的一次明确意图**(发布到这个快照 / 恢复到这个快照)。它不该被
// "这个快照已经成功过"吞掉——用户再次要求同一个目标状态是一次新意图,必须真的执行并
// 留下自己的记录(F01)。
// - attempt 是这次意图的**执行代次**(epoch)。崩溃、接管只新增代次,不新造意图,
// 否则维护窗口、预备份、写集合的谱系就断了(F15)。旧代次一旦失租就不能再写(F13)。
// - 版本事件是**不可变事实**,同一快照被两个 operation 引用是两条事件,谁也不能覆盖谁
// (F02/F09)。current 只是一个"现在生效的是哪条事件"的指针,用单调次序做条件更新,
// 不反过来修改历史。
// ErrLibraryEpochStale:这次写入来自已经失租/被接管的执行代次。
// 调用方必须停止副作用并把控制权交给当前代次,不能用"重试"掩盖。
var ErrLibraryEpochStale = errors.New("library attempt epoch is stale: another attempt owns this operation")
// ErrLibraryCurrentStale:这条事件不是当前该生效的事实(有更晚的真相已登记)。
var ErrLibraryCurrentStale = errors.New("library current pointer already advanced past this event")
// ErrLibraryOperationConflict:同一 operation 键被用在了不同的请求内容上。
var ErrLibraryOperationConflict = errors.New("library operation key reused with a different request")
// LibraryAttemptState 是一次执行代次的状态。
type LibraryAttemptState string
const (
// LibraryAttemptClaimed:已被某个 worker 认领,尚未进入维护窗口。
LibraryAttemptClaimed LibraryAttemptState = "claimed"
// LibraryAttemptRunning:正在执行(持有目标执行域)。
LibraryAttemptRunning LibraryAttemptState = "running"
LibraryAttemptCompleted LibraryAttemptState = "completed"
LibraryAttemptFailed LibraryAttemptState = "failed"
LibraryAttemptAbandoned LibraryAttemptState = "abandoned"
)
// LibraryOperation 是一次明确意图。字段一旦写入就不再改变(锚点另见 LibraryAnchors)。
type LibraryOperation struct {
ID string `json:"id"`
Scope string `json:"scope"`
Kind LibraryJobKind `json:"kind"`
TargetSnapshotID string `json:"target_snapshot_id"`
RequestDigest string `json:"request_digest"`
OperationKey string `json:"operation_key"`
Actor string `json:"actor"`
CreatedAt time.Time `json:"created_at"`
}
// LibraryAnchors 是 operation 的**不可变首次锚点**:预备份身份/字节、写集合摘要、
// 目标指纹。所有 attempt 继承它;接管不许"再拍一份",也不许用新值覆盖它(F07/F09)。
type LibraryAnchors struct {
FirstBackupSnapshotID string `json:"first_backup_snapshot_id,omitempty"`
FirstBackupBytes *int64 `json:"first_backup_bytes,omitempty"`
FirstBackupAt *time.Time `json:"first_backup_at,omitempty"`
WriteSetDigest string `json:"writeset_digest,omitempty"`
WriteSetRows *int64 `json:"writeset_rows,omitempty"`
TargetFingerprint string `json:"target_fingerprint,omitempty"`
RecordedAt *time.Time `json:"recorded_at,omitempty"`
}
// LibraryAttempt 是 operation 的一次执行代次。
type LibraryAttempt struct {
OperationID string `json:"operation_id"`
Epoch int `json:"epoch"`
JobID string `json:"job_id"`
QueueJobID string `json:"queue_job_id"`
Owner string `json:"owner"`
State LibraryAttemptState `json:"state"`
StartedAt time.Time `json:"started_at"`
HeartbeatAt *time.Time `json:"heartbeat_at,omitempty"`
LeaseUntil *time.Time `json:"lease_until,omitempty"`
FinishedAt *time.Time `json:"finished_at,omitempty"`
Outcome string `json:"outcome,omitempty"`
}
// LibraryOperationID 由 (scope, kind, operation 键) 决定:同一个客户端重放键永远得到
// 同一个 operation(幂等),换一个键就是一次新意图(不是"历史成功")。
func LibraryOperationID(scope string, kind LibraryJobKind, operationKey string) string {
sum := sha256.Sum256([]byte(string(kind) + "|" + scope + "|" + operationKey))
return "libop-" + hex.EncodeToString(sum[:])[:24]
}
// LibraryVersionEventID 生成一条**不可变版本事件**的 ID:同一个 operation 对同一快照
// 同一类别只产生一条事件(重放幂等);不同 operation 即使引用同一快照也是不同事件,
// 因此 `source_job_id`/`evidence`/`created_at` 不会被后来的执行覆盖(F02)。
// operationID 为空时退回旧形状,供历史行/旧调用方保持同一身份。
func LibraryVersionEventID(kind LibraryVersionKind, scope, snapshotID, operationID string) string {
identity := string(kind) + "|" + scope + "|" + snapshotID
if operationID != "" {
identity += "|" + operationID
}
sum := sha256.Sum256([]byte(identity))
return "libver-" + hex.EncodeToString(sum[:])[:16]
}
// CurrentOrderKey 给"这条事实是什么时候被记录为真相的"一个**单调可比较**的键。
//
// 用它做 current 指针的条件更新:后来登记的事实可以推进指针,更早的不能把指针拉回历史。
// 旧执行代次"迟到 finalize 反转 current"在写边界就被拦住了(epoch 守卫),
// 所以这里不需要也不该再拿 operation 的创建时间当次序——恢复回滚必须能把指针指回更早发布的
// 快照,那个事件的**登记时间**是新的。
func CurrentOrderKey(recordedAt time.Time, operationID string, epoch int) string {
return fmt.Sprintf("%020d|%s|%09d", recordedAt.UTC().UnixNano(), operationID, epoch)
}
// CanAdvanceCurrent 判断一条新事实能否推进 current 指针(纯函数,供写入路径与测试共用)。
// 返回 false 表示"这条事件只能确认自己的历史",调用方必须拒绝把它登记成当前状态。
func CanAdvanceCurrent(currentOrderKey, nextOrderKey string) bool {
if nextOrderKey == "" {
return false
}
if currentOrderKey == "" {
return true
}
return nextOrderKey > currentOrderKey
}
// LibraryJobTypePrefix 是所有整库发布相关队列作业的类型前缀。
//
// 这些类型的准入条件(生产闸口、精确授权、维护互斥、目标身份核验)只在发布管理专用
// 入口里判断,所以它们对通用 queue 入口是**保留类型**:通用入口的通用 engineer 角色
// 检查替代不了准入,允许它造一个 library.* 作业就是绕过整条准入链(F14)。
const LibraryJobTypePrefix = "library."
// IsReservedLibraryJobType 按前缀整类判断,而不是逐个列举类型:
// 以后新增一种 library 作业类型时不会漏掉准入。
func IsReservedLibraryJobType(jobType string) bool {
return strings.HasPrefix(strings.TrimSpace(jobType), LibraryJobTypePrefix)
}
// ValidateLibraryOperation 只做结构校验:缺字段就拒绝,不猜默认值。
func ValidateLibraryOperation(op LibraryOperation) error {
if op.ID == "" || op.OperationKey == "" || op.RequestDigest == "" || op.CreatedAt.IsZero() {
return errors.New("library operation requires id, key, digest and created_at")
}
if op.Scope != "internal" && op.Scope != "external" {
return errors.New("library operation requires internal or external scope")
}
switch op.Kind {
case LibraryJobSeal, LibraryJobSync, LibraryJobRestore, LibraryJobBaseline, LibraryJobRecover:
default:
return fmt.Errorf("unsupported library operation kind %q", op.Kind)
}
return nil
}