233 lines
9.7 KiB
Go
233 lines
9.7 KiB
Go
package transaction
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"log/slog"
|
|
)
|
|
|
|
// InspectionStatus 表示外部系统中某一步的实际结果。
|
|
//
|
|
// 它是 Operation.Inspect 的核对结论，Coordinator 据此判断副作用是否真实发生，
|
|
// 从而决定步骤的最终状态。UNKNOWN 表示暂时无法确认，必须保留意图等待恢复。
|
|
type InspectionStatus string
|
|
|
|
const (
|
|
InspectionApplied InspectionStatus = "APPLIED" // 外部副作用已确认发生。
|
|
InspectionNotApplied InspectionStatus = "NOT_APPLIED" // 外部副作用已确认未发生。
|
|
InspectionUnknown InspectionStatus = "UNKNOWN" // 无法确认副作用是否发生。
|
|
)
|
|
|
|
// Inspection 执行器通过 inspect、摘要、健康检查等方式得到的实际状态。
|
|
//
|
|
// 它把对外的状态核对结果封装为统一结构：Status 给出确定/不确定的结论，Result
|
|
// 保存核对得到的原始证据，用于在步骤成功时持久化。
|
|
type Inspection struct {
|
|
Status InspectionStatus // 核对结论。
|
|
Result json.RawMessage // 核对得到的原始结果载荷，可为空。
|
|
}
|
|
|
|
// Operation 一个可核对实际结果的外部副作用。
|
|
//
|
|
// 实现者负责实际执行外部操作（Apply）并提供事后核对（Inspect）。Apply 返回
|
|
// 成功只代表调用完成，副作用是否真正生效必须由 Inspect 确认，因此调用方在
|
|
// Apply 之后无论成功与否都要再次 Inspect，以精确判定外部状态。
|
|
type Operation interface {
|
|
Apply(context.Context) error
|
|
Inspect(context.Context) (Inspection, error)
|
|
}
|
|
|
|
// UncertainStepError 表示当前无法确认外部副作用是否已经发生。
|
|
//
|
|
// 这种错误必须保留 INTENT_RECORDED，等待恢复流程再次核对。它携带事务与步骤
|
|
// 定位信息及根本原因（Cause），并通过 Unwrap 暴露 Cause 供调用方溯源。
|
|
type UncertainStepError struct {
|
|
TransactionID string // 所属事务 ID。
|
|
StepKey string // 关联步骤键。
|
|
Cause error // 导致无法确认的根本原因。
|
|
}
|
|
|
|
// Error 返回带事务、步骤与原因的无法确认错误描述。
|
|
func (e *UncertainStepError) Error() string {
|
|
return fmt.Sprintf("external step result is uncertain: transaction=%s step=%s: %v", e.TransactionID, e.StepKey, e.Cause)
|
|
}
|
|
|
|
// Unwrap 返回根本原因 Cause，支持 errors.Is/errors.As 溯源。
|
|
func (e *UncertainStepError) Unwrap() error {
|
|
return e.Cause
|
|
}
|
|
|
|
// Coordinator 串行化单机更新，并实现“先记录意图、再执行、最后 inspect”的步骤协议。
|
|
//
|
|
// 它通过容量为 1 的 permit 通道保证同一时刻进程内最多只有一个完整更新流程在
|
|
// 执行区运行，从而简化外部副作用与数据库状态的一致性推理。所有对外部副作用的
|
|
// 操作都必须经过 ExecuteStep，以确保意图先落库、结果可核对、崩溃可恢复。
|
|
type Coordinator struct {
|
|
store *Store // 持久化存储，记录事务、步骤与事件。
|
|
logger *slog.Logger // 结构化日志记录器。
|
|
permit chan struct{} // 容量为 1 的信号量，串行化进入执行区。
|
|
}
|
|
|
|
// NewCoordinator 创建并初始化事务协调器。
|
|
//
|
|
// 参数 store 为必填的事务存储，logger 可选，传入 nil 时回退到 slog.Default。
|
|
// 初始化时向 permit 通道放入一个令牌，表示执行区当前空闲。返回错误仅发生在
|
|
// store 为 nil 时。
|
|
func NewCoordinator(store *Store, logger *slog.Logger) (*Coordinator, error) {
|
|
if store == nil {
|
|
return nil, errors.New("transaction store is required")
|
|
}
|
|
if logger == nil {
|
|
logger = slog.Default()
|
|
}
|
|
permit := make(chan struct{}, 1)
|
|
permit <- struct{}{}
|
|
return &Coordinator{store: store, logger: logger, permit: permit}, nil
|
|
}
|
|
|
|
// RunExclusive 在一个进程内只允许一个完整更新流程进入执行区。
|
|
//
|
|
// 参数 run 是独占执行的更新函数，返回其执行结果；若 run 为 nil 或 ctx 在获得
|
|
// 执行令牌前已取消，则直接返回相应错误。该方法通过 acquire 令牌、defer 释放
|
|
// 令牌实现互斥，释放与获取均不阻塞超过令牌容量，因此不存在死锁。返回值为
|
|
// run 的返回值，或在等待令牌时 ctx 取消导致的错误。
|
|
func (c *Coordinator) RunExclusive(ctx context.Context, run func(context.Context) error) error {
|
|
if run == nil {
|
|
return errors.New("exclusive update function is required")
|
|
}
|
|
select {
|
|
case <-ctx.Done():
|
|
return ctx.Err()
|
|
case <-c.permit:
|
|
}
|
|
defer func() { c.permit <- struct{}{} }()
|
|
return run(ctx)
|
|
}
|
|
|
|
// ExecuteStep 执行或恢复一个外部步骤。
|
|
//
|
|
// 参数 transactionID 是所属事务，intent 描述要执行的外部副作用，operation 提供
|
|
// 实际执行与核对能力。返回值为该步骤的最终持久化快照以及可能的错误。协议要点：
|
|
// 相同 step key 再次调用时先核对现场，禁止直接重复 Apply；若意图已成功则直接
|
|
// 返回；若已失败则依据 inspect 结论决定补记成功或重新打开；若为未执行过的新
|
|
// 意图，则先记录意图、Apply 后再 Inspect，依据核对结果落库成功或失败。当核对
|
|
// 结果为 UNKNOWN 或 Inspect 本身出错时，返回 UncertainStepError 并保留
|
|
// INTENT_RECORDED 等待后续恢复。
|
|
func (c *Coordinator) ExecuteStep(ctx context.Context, transactionID string, intent StepIntent, operation Operation) (Step, error) {
|
|
if operation == nil {
|
|
return Step{}, errors.New("external operation is required")
|
|
}
|
|
step, created, err := c.store.RecordStepIntent(ctx, transactionID, intent)
|
|
if err != nil {
|
|
return Step{}, err
|
|
}
|
|
if step.Status == StepSucceeded {
|
|
return step, nil
|
|
}
|
|
if step.Status == StepFailed {
|
|
inspection, inspectErr := operation.Inspect(ctx)
|
|
if inspectErr != nil {
|
|
return step, c.uncertain(ctx, transactionID, intent.Key, fmt.Errorf("inspect failed step: %w", inspectErr))
|
|
}
|
|
switch inspection.Status {
|
|
case InspectionApplied:
|
|
if _, err := c.store.ReopenFailedStep(ctx, transactionID, intent.Key, "manual resume found failed step applied"); err != nil {
|
|
return step, err
|
|
}
|
|
return c.completeApplied(ctx, transactionID, intent.Key, inspection)
|
|
case InspectionNotApplied:
|
|
reopened, err := c.store.ReopenFailedStep(ctx, transactionID, intent.Key, "manual resume found failed step not applied")
|
|
if err != nil {
|
|
return step, err
|
|
}
|
|
step = reopened
|
|
created = true
|
|
case InspectionUnknown:
|
|
return step, c.uncertain(ctx, transactionID, intent.Key, errors.New("inspect failed step returned UNKNOWN"))
|
|
default:
|
|
return step, c.uncertain(ctx, transactionID, intent.Key, fmt.Errorf("inspect failed step returned invalid status %q", inspection.Status))
|
|
}
|
|
}
|
|
|
|
if !created {
|
|
inspection, err := operation.Inspect(ctx)
|
|
if err != nil {
|
|
return step, c.uncertain(ctx, transactionID, intent.Key, err)
|
|
}
|
|
switch inspection.Status {
|
|
case InspectionApplied:
|
|
return c.completeApplied(ctx, transactionID, intent.Key, inspection)
|
|
case InspectionUnknown:
|
|
return step, c.uncertain(ctx, transactionID, intent.Key, errors.New("inspect returned UNKNOWN"))
|
|
case InspectionNotApplied:
|
|
// 现场明确未发生副作用后，才允许恢复流程重新 Apply。
|
|
default:
|
|
return step, c.uncertain(ctx, transactionID, intent.Key, fmt.Errorf("inspect returned invalid status %q", inspection.Status))
|
|
}
|
|
}
|
|
|
|
c.logger.InfoContext(ctx, "external step apply started",
|
|
"transaction_id", transactionID,
|
|
"step_key", intent.Key,
|
|
"step_name", intent.Name,
|
|
)
|
|
applyErr := operation.Apply(ctx)
|
|
inspection, inspectErr := operation.Inspect(ctx)
|
|
if inspectErr != nil {
|
|
return step, c.uncertain(ctx, transactionID, intent.Key, errors.Join(applyErr, inspectErr))
|
|
}
|
|
switch inspection.Status {
|
|
case InspectionApplied:
|
|
completed, err := c.completeApplied(ctx, transactionID, intent.Key, inspection)
|
|
if err == nil {
|
|
c.logger.InfoContext(ctx, "external step applied",
|
|
"transaction_id", transactionID,
|
|
"step_key", intent.Key,
|
|
)
|
|
}
|
|
return completed, err
|
|
case InspectionUnknown:
|
|
return step, c.uncertain(ctx, transactionID, intent.Key, errors.Join(applyErr, errors.New("inspect returned UNKNOWN")))
|
|
case InspectionNotApplied:
|
|
failure := applyErr
|
|
if failure == nil {
|
|
failure = errors.New("operation completed without reaching the expected external state")
|
|
}
|
|
completed, err := c.store.CompleteStep(ctx, transactionID, intent.Key, StepFailed, inspection.Result, failure.Error())
|
|
if err != nil {
|
|
return Step{}, errors.Join(failure, err)
|
|
}
|
|
c.logger.ErrorContext(ctx, "external step failed",
|
|
"transaction_id", transactionID,
|
|
"step_key", intent.Key,
|
|
"error", failure,
|
|
)
|
|
return completed, failure
|
|
default:
|
|
return step, c.uncertain(ctx, transactionID, intent.Key, fmt.Errorf("inspect returned invalid status %q", inspection.Status))
|
|
}
|
|
}
|
|
|
|
// completeApplied 将已确认生效的步骤原子落库为 SUCCEEDED。
|
|
//
|
|
// 参数 transactionID 与 stepKey 定位目标步骤，inspection.Result 作为成功结果
|
|
// 写入。返回更新后的步骤快照及可能的存储错误。
|
|
func (c *Coordinator) completeApplied(ctx context.Context, transactionID, stepKey string, inspection Inspection) (Step, error) {
|
|
return c.store.CompleteStep(ctx, transactionID, stepKey, StepSucceeded, inspection.Result, "")
|
|
}
|
|
|
|
// uncertain 记录无法确认外部副作用结果的告警日志并构造 UncertainStepError。
|
|
//
|
|
// 参数 transactionID 与 stepKey 用于定位，cause 为根本原因。该方法不改变存储
|
|
// 状态，仅记录日志并返回错误，交由上层决定是否保留意图等待恢复。
|
|
func (c *Coordinator) uncertain(ctx context.Context, transactionID, stepKey string, cause error) error {
|
|
c.logger.WarnContext(ctx, "external step result is uncertain",
|
|
"transaction_id", transactionID,
|
|
"step_key", stepKey,
|
|
"error", cause,
|
|
)
|
|
return &UncertainStepError{TransactionID: transactionID, StepKey: stepKey, Cause: cause}
|
|
}
|