Files
knowledge-governance/internal/libraryrelease/index_restore_dispatch.go
T
姚章浩 245cefd6b0 fix(library): 收紧 DS01 派发租约/投递/治理身份与绑定冲突
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 仍可确认。
2026-11-02 20:36:36 +08:00

202 lines
8.9 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 覆盖**逻辑 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)
}