fad26166a4
为什么:删除型恢复的独占 create 在 ES 侧没有"从未写过"的持久证据, missing/stats/内存计数都不能当未派发证明。改成为每个固定 effect 维护 单调台账:prepared -> dispatching -> marker_confirmed,绑定换不了、 状态回退不了、行删不掉。 许可只在独立短事务里 CAS 并 COMMIT 明确成功后返回,消费一次即作废; 提交结果不明时不发许可。激活登记是配置之外的第二个条件。 验证:真实 PG(隔离 schema)覆盖并发唯一赢家、旧 epoch 拒绝、 单调/绑定/删行拒绝、提交不明零许可、无激活 fail closed、down 拒绝抹证据。
164 lines
6.3 KiB
Go
164 lines
6.3 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,不能另起一行继续写。
|
||
type RestoreMarkerBinding struct {
|
||
Key RestoreMarkerKey `json:"key"`
|
||
Scope string `json:"scope"`
|
||
SourceSnapshot string `json:"source_snapshot"`
|
||
BackupSnapshot string `json:"backup_snapshot"`
|
||
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,
|
||
"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.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{
|
||
"v1", 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.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
|
||
}
|
||
|
||
// RestoreMarkerGate 是唯一能授予恢复标记 create 发送权的接口。
|
||
//
|
||
// Inspect 纯读、不返回许可;Prepare 只建立 prepared;Acquire 在独立短事务里做
|
||
// prepared→dispatching 的 CAS,只有明确提交后才返回许可;Confirm 只记录真实回执。
|
||
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
|
||
}
|