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 覆盖**逻辑 effect 的不可变绑定**;台账用它拒绝"同 key 换绑定"。 // owner/epoch 与 recovery queue/operation 是执行/投递锚点,不进摘要:自动回滚与 // 随后的 recovery worker 必须落到同一个 effect 身份,但它们的投递身份不同。 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.ChangeDigest, b.MarkerDigest, b.RequestDigest, }, "\x00") sum := sha256.Sum256([]byte(joined)) return hex.EncodeToString(sum[:]), nil } // RestoreDispatchStatus 是纯读分类结果。Held 为真时永远不能发送。 // // BindingConflict 是与 Held 不同的**类型化**分类:Held 只说"这次不能再 create" // (prepared 冲突、dispatching 结果未知、marker 已确认都可能是合法的不可重发), // 而 BindingConflict 说明台账行的不可变绑定与本次绑定不是同一个 effect。绑定冲突 // 在**任何状态**下都必须拒绝,包括已完成 clean 的 marker_confirmed;否则"只允许原 // 确认分支继续"会变成放行一份不属于本计划的写入。 type RestoreDispatchStatus struct { State string `json:"state"` Held bool `json:"held"` BindingConflict bool `json:"binding_conflict,omitempty"` 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) }