245cefd6b0
F2.a:Acquire/Confirm 在取得 effect 行锁后用数据库时钟重核 job/attempt/ 恢复投递租约,等锁跨过到期零许可且状态保持 prepared。 F2.b:同一 CAS 事务锁 recovery queue 与 operation,复核 window/scope、 idempotency、owner/attempt/lease,并按原 window 锚点重算恢复请求摘要。 F3.identity:激活证据 v3 携带 PG 集群 system_identifier + 库 OID、完整构建 SHA 与协议批次;激活与使用点都现场重读并拒绝同名异域/副本/unknown/不兼容 SHA。 F4.binding:区分绑定冲突与仅禁止重发的 Held,准入/确认/续作/收尾在所有状态 拒绝冲突,合法 dispatching + 精确 marker 仍可确认。
202 lines
8.9 KiB
Go
202 lines
8.9 KiB
Go
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)
|
||
}
|