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 }