Files
knowledge-governance/internal/libraryrelease/index_restore_dispatch.go
T
姚章浩 fad26166a4 feat(library): 新增恢复标记派发台账与一次性许可
为什么:删除型恢复的独占 create 在 ES 侧没有"从未写过"的持久证据,
missing/stats/内存计数都不能当未派发证明。改成为每个固定 effect 维护
单调台账:prepared -> dispatching -> marker_confirmed,绑定换不了、
状态回退不了、行删不掉。

许可只在独立短事务里 CAS 并 COMMIT 明确成功后返回,消费一次即作废;
提交结果不明时不发许可。激活登记是配置之外的第二个条件。

验证:真实 PG(隔离 schema)覆盖并发唯一赢家、旧 epoch 拒绝、
单调/绑定/删行拒绝、提交不明零许可、无激活 fail closed、down 拒绝抹证据。
2026-11-02 16:27:49 +08:00

164 lines
6.3 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,不能另起一行继续写。
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
}