Files
knowledge-governance/internal/libraryrelease/index_restore_dispatch.go
T
姚章浩 513aa9e6f5
build / build (push) Has been cancelled
fix(library): 收紧恢复派发真实绑定与同事务授权
为什么:Astra 复核证实五组实现缺陷——正式装配缺 scope/快照且来源与 before-image
混用;激活撤销不在 CAS 事务内、lease 用事务起始时间;激活只接受任意字符串且撤销可
被 SQL 重置/删除;准入忽略绑定冲突与 prepared 矛盾、收尾只看当前 plan;prepared 已
提交但 mark-intent 未落盘时被误判 legacy。

改了什么:
- 绑定来自原锚点(scope/来源快照/backup/实例/目标指纹/索引 UUID/恢复投递),每次
  重建都实时重读目标身份并与冻结值比较;
- activation 行锁与 CAS 同事务,lease 用 clock_timestamp(),同事务核对 job/operation/
  attempt/维护窗口/恢复 queue 与 operation,同 effect 换 plan 摘要拒绝;
- 激活消费带摘要的证据文件(writer 退出+排空、目标/治理库身份、有效期),撤销终局,
  down 在 activation 有行时拒绝;
- 前置/收尾共用权威窗口全集,绑定冲突与 prepared 矛盾零写 held,合法 dispatching+
  精确 marker 仍可确认;
- prepared 无 mark-intent 仅在绑定一致且无矛盾时补同内容意图,旧无台账意图仍 held。

验证:真 PG 锁等待覆盖撤销先胜/CAS 先胜/等锁跨租约/错锚点/plan 别名/恢复投递;
COMMIT 已到服务端但回包丢失与未决事务分别读回;真 ES+PG+对象存储的 DS01 用例全部
通过;go test ./... 全绿。未迁移正式库、未部署、未激活。
2026-11-02 18:09:26 +08:00

193 lines
8.1 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 libraryrelease
import (
"context"
"crypto/sha256"
"encoding/hex"
"errors"
"fmt"
"strings"
)
// 恢复标记派发协议(DS01 窄协议)。
//
// 这里定义的唯一持久事实是:某个固定的删除型恢复 effect 是否已经有人拿到过
// "向索引发送一次 `_create`"的许可。它不是"ES 历史上从未有人写过这个 ID"的证明,
// 也不是目标端 fence。判据是单调的持久状态,不是 missing、stats 或内存布尔值。
const (
// RestoreMarkerPhaseCreate 是恢复期独占 create(删除型文档的原文标记)的唯一相位。
// 其它相位(apply create、compensation DELETE、clean CAS)不得借用它取得发送许可。
RestoreMarkerPhaseCreate = "restore-marker-create"
RestoreDispatchPrepared = "prepared"
RestoreDispatchDispatching = "dispatching"
RestoreDispatchMarkerConfirmed = "marker_confirmed"
)
var (
ErrRestoreDispatchHeld = errors.New("restore marker dispatch is held")
ErrRestorePermitSpent = errors.New("restore send permit already used")
ErrRestorePermitMismatch = errors.New("restore send permit bound to another effect")
ErrRestoreDispatchUnavailable = errors.New("restore marker dispatch protocol is not activated for this target")
)
// RestoreMarkerKey 是"同一个逻辑恢复 effect"的身份。epoch、恢复队列 ID、恢复作业 ID
// 都不在 key 里:接管与重试必须落到同一行,不能靠换 key 绕开旧的 dispatching。
type RestoreMarkerKey struct {
TargetIdentity string `json:"target_identity"`
OperationID string `json:"operation_id"`
WindowJobID string `json:"window_job_id"`
PlanDigest string `json:"plan_digest"`
Index string `json:"index"`
DocumentID string `json:"document_id"`
Phase string `json:"phase"`
}
func (k RestoreMarkerKey) Validate() error {
for name, value := range map[string]string{
"target": k.TargetIdentity, "operation": k.OperationID, "window job": k.WindowJobID,
"plan": k.PlanDigest, "index": k.Index, "document": k.DocumentID, "phase": k.Phase,
} {
if strings.TrimSpace(value) == "" {
return fmt.Errorf("restore marker key lacks %s", name)
}
}
if k.Phase != RestoreMarkerPhaseCreate {
return fmt.Errorf("restore marker key phase %q is not the single create phase", k.Phase)
}
return nil
}
// RestoreMarkerBinding 是派发许可的不可变绑定。目标、快照、计划、变更体与标记体任一
// 变化都必须 held,不能另起一行继续写。
//
// SourceSnapshot 是发布基线(原作业要同步到的那份来源),BackupSnapshot 是本次失败
// 写集的写前镜像;两者必须来自原持久锚点且不能互相代替。TargetInstance /
// TargetFingerprint / IndexUUID 冻结"实际目标",用于识别目标被同名字替换;它们不证明
// 历史上没有发送过任何请求。
type RestoreMarkerBinding struct {
Key RestoreMarkerKey `json:"key"`
Scope string `json:"scope"`
SourceSnapshot string `json:"source_snapshot"`
BackupSnapshot string `json:"backup_snapshot"`
TargetInstance string `json:"target_instance"`
TargetFingerprint string `json:"target_fingerprint"`
IndexUUID string `json:"index_uuid"`
RecoveryJobID string `json:"recovery_job_id,omitempty"`
RecoveryOperationID string `json:"recovery_operation_id,omitempty"`
ChangeDigest string `json:"change_digest"`
MarkerDigest string `json:"marker_digest"`
RequestDigest string `json:"request_digest"`
Owner string `json:"owner"`
Epoch int64 `json:"epoch"`
}
func (b RestoreMarkerBinding) Validate() error {
if err := b.Key.Validate(); err != nil {
return err
}
for name, value := range map[string]string{
"scope": b.Scope, "source snapshot": b.SourceSnapshot, "backup snapshot": b.BackupSnapshot,
"target instance": b.TargetInstance, "target fingerprint": b.TargetFingerprint,
"index uuid": b.IndexUUID, "change digest": b.ChangeDigest, "marker digest": b.MarkerDigest,
"request digest": b.RequestDigest, "owner": b.Owner,
} {
if strings.TrimSpace(value) == "" {
return fmt.Errorf("restore marker binding lacks %s", name)
}
}
if b.SourceSnapshot == b.BackupSnapshot {
return errors.New("restore marker binding uses the source snapshot as the backup image")
}
if b.RecoveryJobID == "" != (b.RecoveryOperationID == "") {
return errors.New("restore marker binding has a partial recovery delivery identity")
}
if b.Epoch <= 0 {
return errors.New("restore marker binding lacks a positive attempt epoch")
}
return nil
}
// Digest 覆盖全部不可变字段;台账用它拒绝"同 key 换绑定"。
func (b RestoreMarkerBinding) Digest() (string, error) {
if err := b.Validate(); err != nil {
return "", err
}
joined := strings.Join([]string{
"v2", b.Key.TargetIdentity, b.Key.OperationID, b.Key.WindowJobID, b.Key.PlanDigest,
b.Key.Index, b.Key.DocumentID, b.Key.Phase, b.Scope, b.SourceSnapshot, b.BackupSnapshot,
b.TargetInstance, b.TargetFingerprint, b.IndexUUID, b.RecoveryJobID, b.RecoveryOperationID,
b.ChangeDigest, b.MarkerDigest, b.RequestDigest,
}, "\x00")
sum := sha256.Sum256([]byte(joined))
return hex.EncodeToString(sum[:]), nil
}
// RestoreDispatchStatus 是纯读分类结果。Held 为真时永远不能发送。
type RestoreDispatchStatus struct {
State string `json:"state"`
Held bool `json:"held"`
Reason string `json:"reason,omitempty"`
}
// RestoreSendPermit 是"这一次调用、这一个 effect、这一次发送"的许可。
//
// 它不是可复用凭证:Store 只在 dispatching 明确 commit 之后返回它;消费一次即作废。
// 不能从 Load/Get/JSON/重启重建——那正是本协议要排除的"从外观推断未派发"。
type RestoreSendPermit struct {
key RestoreMarkerKey
binding string
nonce string
used bool
}
// IssueRestoreSendPermit 只允许实现 RestoreMarkerGate 的存储层调用。许可的权威性来自
// 数据库 CAS 与提交,不来自这个构造函数;这里只保证调用栈内一次性。
func IssueRestoreSendPermit(key RestoreMarkerKey, bindingDigest, nonce string) *RestoreSendPermit {
return &RestoreSendPermit{key: key, binding: bindingDigest, nonce: nonce}
}
func (p *RestoreSendPermit) Nonce() string {
if p == nil {
return ""
}
return p.nonce
}
// Consume 校验 effect/绑定并作废许可。绑定不符时不消耗许可(避免被一次误用烧掉)。
func (p *RestoreSendPermit) Consume(key RestoreMarkerKey, bindingDigest string) error {
if p == nil {
return ErrRestorePermitMismatch
}
if p.used {
return ErrRestorePermitSpent
}
if p.key != key || p.binding != bindingDigest {
return ErrRestorePermitMismatch
}
p.used = true
return nil
}
// RestoreDispatchRecord 是权威台账里"这个原 window 还有哪些未决 effect"的一条。
// 收尾与前置都查同一份记录集,不能只遍历当前 plan 的文档列表。
type RestoreDispatchRecord struct {
PlanDigest string `json:"plan_digest"`
Index string `json:"index"`
DocumentID string `json:"document_id"`
State string `json:"state"`
}
// RestoreMarkerGate 是唯一能授予恢复标记 create 发送权的接口。
//
// Inspect 纯读、不返回许可;Prepare 只建立 prepared;Acquire 在独立短事务里做
// prepared→dispatching 的 CAS,只有明确提交后才返回许可;Confirm 只记录真实回执;
// UnresolvedRestoreDispatches 返回原 window 的权威未决全集(跨 plan,只读)。
type RestoreMarkerGate interface {
InspectRestoreMarker(ctx context.Context, b RestoreMarkerBinding) (RestoreDispatchStatus, bool, error)
PrepareRestoreMarker(ctx context.Context, b RestoreMarkerBinding) (RestoreDispatchStatus, error)
AcquireRestoreMarker(ctx context.Context, b RestoreMarkerBinding) (*RestoreSendPermit, RestoreDispatchStatus, error)
ConfirmRestoreMarker(ctx context.Context, b RestoreMarkerBinding, receipt []byte) error
UnresolvedRestoreDispatches(ctx context.Context, targetIdentity, operationID, windowJobID string) ([]RestoreDispatchRecord, error)
}