98294b9583
build / build (push) Failing after 24s
why:审计 19 项(12 P1 / 7 P2)来自同一批根因,逐点试错会把协议撕成十几份:
· 意图与执行混为一谈(F01/F15):`library.sync:<scope>:<快照>` 是终身幂等键,
A→B→A 的第三次发布拿到第一次的历史成功作业,什么都不做;
· 版本行既是实体又是事件(F02/F09):主键只由 (kind,scope,快照) 决定、写入是
upsert,第二个作业覆盖 `source_job_id`/`evidence`/`created_at`;
· 接管没有代次(F13):两个 worker 都能认领同一 pending 作业,失租的旧执行还能
写业务状态、释放别人的维护锁;
· 早退与终态没有统一政策(F03/F04/F05/F06):半写窗口的前置检查失败会重新开门、
服务起不来也照样开入口、journal 终态后收尾不可重建、恢复成功不回写 current;
· 数据身份与准入各写一套(F07/F08/F14/F17):接管丢了复用语义、全库搬运不改
location_hash、通用入口可造 library.* 作业、目标模型从没被问过;
· 存储/容量/UI/CI 判据各自为政(F10/F11/F12/F16/F18/F19)。
what:按批准的一套协议集中实施(详见 handoffs/release-consolidated-implementation/
current-contract.md):
· operation(一次明确意图)/ attempt(epoch 代次)/ 不可变版本事件 / current 指针;
治理库迁移 76,只动治理库,不碰 WeKnora Schema/源码/镜像;
· 所有业务状态、阶段、版本事件、维护锁写入带 epoch 守卫(失租代次写不进去);
心跳失租立刻取消 handler;
· 半写窗口早退保持关闭;服务未全部健康绝不开入口;journal 终态可从持久事实重建
收尾;恢复成功登记 recovery 事件并推进 current;
· worker 在动维护前核对业务行/kind/scope/队列关联;通用入口拒绝 library.*;
· 全库搬运重算 location_hash 并与文档级导入共用实现;接管消费写集合的复用决定;
发布前核目标实时模型契约、容量门禁前置;
· 存储保护闭包改为全量依赖、类型只认显式登记、保护未知则不出可删候选;
· 页面核 HTTP 状态与结构、恢复纳入轮询、Wiki 差异覆盖标题/摘要/父级。
how:`make verify` rc=0(16 项必需检查全绿,含 go test 全量与前端 485 例);
`go vet ./...` rc=0;`npx tsc -p tsconfig.json --noEmit` rc=0;逐项负例见各包测试
(F03/F04/F08/F12/F13/F14/F16/F18/F19 都有先红后绿记录)。
未执行:治理库迁移到任何已有库、真实 PG/ES/S3/WeKnora 集成、故障注入、部署。
213 lines
9.3 KiB
Go
213 lines
9.3 KiB
Go
package postgres
|
||
|
||
import (
|
||
"context"
|
||
"errors"
|
||
"fmt"
|
||
"time"
|
||
|
||
"github.com/jackc/pgx/v5"
|
||
|
||
"knowledge-governance/internal/governance"
|
||
)
|
||
|
||
// 写入栅栏:所有"业务状态 / 维护锁"的写都必须证明调用方仍是当前执行代次。
|
||
//
|
||
// 为什么单独放一份:F13 的根因不是某一条 SQL 写错了,而是"同一个 job_id 被两个代次
|
||
// 同时使用"这件事本身没有被表达出来。只要有一处更新不带代次条件,失租的旧执行就能
|
||
// 用同一个 job_id 写业务终态、释放别人刚拿到的维护锁。所以这里给每个可变入口配一个
|
||
// 带守卫的版本,worker 只准走这些版本;不带守卫的旧方法留给 API(它代表"当前意图",
|
||
// 没有执行代次)。
|
||
|
||
const epochFence = `EXISTS (SELECT 1 FROM library_jobs j WHERE j.id=$1 AND j.attempt_epoch=$%d AND j.lease_owner=$%d)`
|
||
|
||
// AdvanceLibraryJobGuarded 只在调用方仍是该作业当前代次时写业务状态。
|
||
func (s *Store) AdvanceLibraryJobGuarded(ctx context.Context, attempt governance.LibraryAttempt,
|
||
state governance.LibraryJobState, stage, message, recovery, snapshotID, targetSnapshotID string, now time.Time) error {
|
||
finished := any(nil)
|
||
if state == governance.LibraryJobSucceeded || state == governance.LibraryJobFailed || state == governance.LibraryJobCancelled {
|
||
finished = now.UTC()
|
||
}
|
||
tag, err := s.db.Exec(ctx, `
|
||
UPDATE library_jobs SET
|
||
state=$2,
|
||
stage = CASE WHEN $3='' THEN stage ELSE $3 END,
|
||
error = CASE WHEN $4='' THEN error ELSE $4 END,
|
||
recovery = CASE WHEN $5='' THEN recovery ELSE $5 END,
|
||
snapshot_id = CASE WHEN $6='' THEN snapshot_id ELSE $6 END,
|
||
target_snapshot_id = CASE WHEN $7='' THEN target_snapshot_id ELSE $7 END,
|
||
updated_at=$8,
|
||
finished_at=COALESCE($9, finished_at)
|
||
WHERE id=$1 AND attempt_epoch=$10 AND lease_owner=$11`,
|
||
attempt.JobID, string(state), stage, message, recovery, snapshotID, targetSnapshotID, now.UTC(), finished,
|
||
attempt.Epoch, attempt.Owner)
|
||
if err != nil {
|
||
return fmt.Errorf("advance library job (guarded): %w", err)
|
||
}
|
||
if tag.RowsAffected() != 1 {
|
||
return s.fencedWriteError(ctx, attempt, "advance library job")
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// UpdateLibraryStageGuarded 是阶段进度的守卫版:失租代次不能再写"我这一阶段成功了"。
|
||
func (s *Store) UpdateLibraryStageGuarded(ctx context.Context, attempt governance.LibraryAttempt,
|
||
stage, state string, total, completed, bytesTotal, bytesDone *int64, detail string, now time.Time) error {
|
||
tag, err := s.db.Exec(ctx, `
|
||
UPDATE library_job_stages SET
|
||
state = CASE WHEN $3='' THEN state ELSE $3 END,
|
||
total = COALESCE($4, total),
|
||
completed = COALESCE($5, completed),
|
||
bytes_total = COALESCE($6, bytes_total),
|
||
bytes_done = COALESCE($7, bytes_done),
|
||
detail = CASE WHEN $8='' THEN detail ELSE $8 END,
|
||
updated_at = $9
|
||
WHERE job_id=$1 AND stage=$2
|
||
AND EXISTS (SELECT 1 FROM library_jobs j WHERE j.id=$1 AND j.attempt_epoch=$10 AND j.lease_owner=$11)`,
|
||
attempt.JobID, stage, state, total, completed, bytesTotal, bytesDone, detail, now.UTC(),
|
||
attempt.Epoch, attempt.Owner)
|
||
if err != nil {
|
||
return fmt.Errorf("update library stage (guarded): %w", err)
|
||
}
|
||
if tag.RowsAffected() != 1 {
|
||
return s.fencedWriteError(ctx, attempt, "update library stage")
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// ReleaseLibraryMaintenanceGuarded 释放 scope 维护锁,但只认当前代次。
|
||
func (s *Store) ReleaseLibraryMaintenanceGuarded(ctx context.Context, scope, ownerJobID string,
|
||
attempt governance.LibraryAttempt, now time.Time) error {
|
||
tag, err := s.db.Exec(ctx, `
|
||
UPDATE library_maintenance SET state='released', released_at=$3, updated_at=$3
|
||
WHERE scope=$1 AND owner_job_id=$2 AND released_at IS NULL
|
||
AND `+fmt.Sprintf(epochFence, 4, 5), scope, ownerJobID, now.UTC(), attempt.Epoch, attempt.Owner)
|
||
if err != nil {
|
||
return fmt.Errorf("release library maintenance (guarded): %w", err)
|
||
}
|
||
if tag.RowsAffected() == 0 {
|
||
if s.releasedByThisJob(ctx, "library_maintenance", "scope", scope, ownerJobID) {
|
||
return ErrMaintenanceReleased
|
||
}
|
||
return s.fencedWriteError(ctx, attempt, "release library maintenance")
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// ReleaseInstanceMaintenanceGuarded 释放实例维护锁,但只认当前代次。
|
||
func (s *Store) ReleaseInstanceMaintenanceGuarded(ctx context.Context, instance, ownerJobID string,
|
||
attempt governance.LibraryAttempt, now time.Time) error {
|
||
tag, err := s.db.Exec(ctx, `
|
||
UPDATE library_instance_maintenance SET state='released', released_at=$3, updated_at=$3
|
||
WHERE instance=$1 AND owner_job_id=$2 AND released_at IS NULL
|
||
AND `+fmt.Sprintf(epochFence, 4, 5), instance, ownerJobID, now.UTC(), attempt.Epoch, attempt.Owner)
|
||
if err != nil {
|
||
return fmt.Errorf("release instance maintenance (guarded): %w", err)
|
||
}
|
||
if tag.RowsAffected() == 0 {
|
||
if s.releasedByThisJob(ctx, "library_instance_maintenance", "instance", instance, ownerJobID) {
|
||
return ErrMaintenanceReleased
|
||
}
|
||
return s.fencedWriteError(ctx, attempt, "release instance maintenance")
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// UpdateLibraryMaintenanceStateGuarded / UpdateInstanceMaintenanceStateGuarded 同理:
|
||
// 失租代次不能把窗口改成 needs_restore / verified 去影响当前代次的判断。
|
||
func (s *Store) UpdateLibraryMaintenanceStateGuarded(ctx context.Context, scope, ownerJobID, state, note string,
|
||
attempt governance.LibraryAttempt, now time.Time) error {
|
||
tag, err := s.db.Exec(ctx, `
|
||
UPDATE library_maintenance SET state=$3, note=$4, updated_at=$5
|
||
WHERE scope=$1 AND owner_job_id=$2 AND released_at IS NULL
|
||
AND `+fmt.Sprintf(epochFence, 6, 7), scope, ownerJobID, state, note, now.UTC(), attempt.Epoch, attempt.Owner)
|
||
if err != nil {
|
||
return fmt.Errorf("update library maintenance (guarded): %w", err)
|
||
}
|
||
if tag.RowsAffected() == 0 {
|
||
if s.releasedByThisJob(ctx, "library_maintenance", "scope", scope, ownerJobID) {
|
||
return ErrMaintenanceReleased
|
||
}
|
||
return s.fencedWriteError(ctx, attempt, "update library maintenance")
|
||
}
|
||
return nil
|
||
}
|
||
|
||
func (s *Store) UpdateInstanceMaintenanceStateGuarded(ctx context.Context, instance, ownerJobID, state, note string,
|
||
attempt governance.LibraryAttempt, now time.Time) error {
|
||
tag, err := s.db.Exec(ctx, `
|
||
UPDATE library_instance_maintenance SET state=$3, note=$4, updated_at=$5
|
||
WHERE instance=$1 AND owner_job_id=$2 AND released_at IS NULL
|
||
AND `+fmt.Sprintf(epochFence, 6, 7), instance, ownerJobID, state, note, now.UTC(), attempt.Epoch, attempt.Owner)
|
||
if err != nil {
|
||
return fmt.Errorf("update instance maintenance (guarded): %w", err)
|
||
}
|
||
if tag.RowsAffected() == 0 {
|
||
if s.releasedByThisJob(ctx, "library_instance_maintenance", "instance", instance, ownerJobID) {
|
||
return ErrMaintenanceReleased
|
||
}
|
||
return s.fencedWriteError(ctx, attempt, "update instance maintenance")
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// fencedWriteError 区分"作业不存在"与"代次已过期":两者都要停下,但文案不能误导运维。
|
||
func (s *Store) fencedWriteError(ctx context.Context, attempt governance.LibraryAttempt, action string) error {
|
||
var epoch int
|
||
var owner string
|
||
err := s.db.QueryRow(ctx, `SELECT attempt_epoch, lease_owner FROM library_jobs WHERE id=$1`,
|
||
attempt.JobID).Scan(&epoch, &owner)
|
||
if errors.Is(err, pgx.ErrNoRows) {
|
||
return fmt.Errorf("%s:作业 %s 不存在", action, attempt.JobID)
|
||
}
|
||
if err != nil {
|
||
return fmt.Errorf("%s:读不到作业代次:%w", action, err)
|
||
}
|
||
return fmt.Errorf("%w(%s:本代次 %d/%s,当前 %d/%s)", governance.ErrLibraryEpochStale,
|
||
action, attempt.Epoch, attempt.Owner, epoch, owner)
|
||
}
|
||
|
||
func (s *Store) SetInstanceMaintenanceIngressGuarded(ctx context.Context, instance, ownerJobID, state, note string,
|
||
attempt governance.LibraryAttempt, now time.Time) error {
|
||
if state != "closed" && state != "open" {
|
||
return errors.New("invalid ingress state")
|
||
}
|
||
tag, err := s.db.Exec(ctx, `
|
||
UPDATE library_instance_maintenance SET ingress_state=$3, note=$4, updated_at=$5
|
||
WHERE instance=$1 AND owner_job_id=$2 AND released_at IS NULL
|
||
AND `+fmt.Sprintf(epochFence, 6, 7), instance, ownerJobID, state, note, now.UTC(), attempt.Epoch, attempt.Owner)
|
||
if err != nil {
|
||
return fmt.Errorf("update instance maintenance ingress (guarded): %w", err)
|
||
}
|
||
if tag.RowsAffected() == 0 {
|
||
if s.releasedByThisJob(ctx, "library_instance_maintenance", "instance", instance, ownerJobID) {
|
||
return ErrMaintenanceReleased
|
||
}
|
||
return s.fencedWriteError(ctx, attempt, "update instance maintenance ingress")
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// SetLibraryMaintenanceIngressGuarded 记录入口状态也需要代次守卫:
|
||
// "入口已关"是隔离证据,失租代次写它等于伪造证据。
|
||
func (s *Store) SetLibraryMaintenanceIngressGuarded(ctx context.Context, scope, ownerJobID, state, note string,
|
||
attempt governance.LibraryAttempt, now time.Time) error {
|
||
if state != "closed" && state != "open" {
|
||
return errors.New("invalid ingress state")
|
||
}
|
||
tag, err := s.db.Exec(ctx, `
|
||
UPDATE library_maintenance SET ingress_state=$3, note=$4, updated_at=$5
|
||
WHERE scope=$1 AND owner_job_id=$2 AND released_at IS NULL
|
||
AND `+fmt.Sprintf(epochFence, 6, 7), scope, ownerJobID, state, note, now.UTC(), attempt.Epoch, attempt.Owner)
|
||
if err != nil {
|
||
return fmt.Errorf("update library maintenance ingress (guarded): %w", err)
|
||
}
|
||
if tag.RowsAffected() == 0 {
|
||
if s.releasedByThisJob(ctx, "library_maintenance", "scope", scope, ownerJobID) {
|
||
return ErrMaintenanceReleased
|
||
}
|
||
return s.fencedWriteError(ctx, attempt, "update library maintenance ingress")
|
||
}
|
||
return nil
|
||
}
|