ShadowsocksX-NG/ShadowsocksX-NG2/App/ProxyRuntimeController+Convergence.swift

import Foundation

/// 一次计划执行的结果:动作是否全部按序成功,以及本次执行占用的并发流
/// 代际。占用代际供收敛票据推进 flow 分量,取代调用方对 execute 内部
/// 「恰好自增一次」时序的依赖(原 `flowGeneration + 1` 手算)。
struct RuntimeExecutionOutcome {
  /// 本次执行占用的 `flowGeneration`。
  let flow: Int
  /// 全部计划动作是否按序成功。
  let succeeded: Bool
}

/// 收敛票据:运行时收敛操作的代际快照。入口捕获三个并发代际,之后每步
/// 推进用它判定「从入口到现在,并发流 / 模式切换 / 运行时派生是否前进了,
/// 会话内 agent 意图是否仍开启」;被更新提交或新意图取代的旧收敛不得再
/// 变更运行时状态或写契约。
///
/// 四项失效事实由票据恒全查,不随调用路径增减——「什么会使一次收敛失效」
/// 是票据的固有语义(逐路径手选子集曾让 agent 关闭在 mode 切换的健康门
/// await 窗口内被误分类为失败并触发复活性的 restore)。各路径只负责捕获
/// 与推进时机:flow 分量在 execute 后以实际占用值推进,mode 切换路径在
/// 派生后推进 preparation 分量(派生自身会推进它),rules 部署在推进 mode
/// 代际之后捕获。
struct ConvergenceTicket: Equatable {
  /// 并发流代际;每次 execute 之后由调用方以实际占用值推进。
  var flow: Int
  /// 模式切换代际;捕获后不再变化。
  let mode: Int
  /// 运行时文档派生代际;每次派生之后由调用方以当前值推进。
  var preparation: Int
}

extension ProxyRuntimeController {
  /// 以当前代际捕获收敛票据。
  func convergenceTicket() -> ConvergenceTicket {
    ConvergenceTicket(
      flow: flowGeneration, mode: modeChangeGeneration,
      preparation: runtimePreparationGeneration)
  }

  /// 票据是否仍代表当前收敛:并发流 / 模式切换 / 派生三个代际均未前进,
  /// 且会话内 agent 意图仍开启。
  func convergenceIsCurrent(_ ticket: ConvergenceTicket) -> Bool {
    ticket.flow == flowGeneration && ticket.mode == modeChangeGeneration
      && ticket.preparation == runtimePreparationGeneration
      && settings.agentEnabled
  }

  /// 派生文档对当前运行时是否无事可做（CONTEXT.md「有效值未变的提交不做
  /// 运行时收敛」）：磁盘契约与派生字节逐位相同、agent 已注册且 wrapper
  /// 存活、控制器处于健康运行态——计划层动作序列为空即幂等跳过。判定在
  /// 置 `starting` 之前进行，跳过路径不闪状态、不重走健康门；磁盘漂移或
  /// wrapper 失踪时动作序列自然非空，走完整 deploy 自愈。
  func convergencePlanIsEmpty(
    _ document: SslocalRuntimeDocument, preparedContract: PreparedRuntimeContract?
  ) -> Bool {
    switch state {
    case .running, .firewallBlocked:
      break
    case .off, .starting, .launchFailed, .requiresApproval, .serviceFailed:
      return false
    }
    let actions = ProxyRuntimePlan.actions(
      intent: .run(document),
      agentStatus: agent.status,
      wrapper: wrapperState(),
      contractOnDisk: runtimeFileStore.readData(), preparedContract: preparedContract)
    return actions.isEmpty
  }

  /// 统一的设置持久化 epilogue：保存失败不静默偏离持久化事实——记录日志、
  /// 呈现 `serviceFailed(.persistence)`，调用方放弃本次收敛。
  func persistSettings(_ proposed: ProxySettings) -> Bool {
    do {
      try settingsStore.save(proposed)
      return true
    } catch {
      RuntimeLog.emit(.runtimePersistFailed(detail: String(describing: error)))
      state = .serviceFailed(.persistence)
      return false
    }
  }

  /// reexpand 三-case 开关的收敛主体（显式收敛、设置保存、启动重同步共用）：
  /// deployed → 部署派生文档；目标失效 → 清除并按意图收敛；无目标 → 空监听。
  /// 幂等跳过由 apply 层的 plan 空判定承担；目录重校验（跳过名单、目标失效
  /// 清除）已在 `reexpand` 完成，不受其影响。
  func convergeToReexpanded(_ catalog: ConfigurationCatalog) async {
    switch reexpand(in: catalog) {
    case .deployed(let configuration):
      await deploy(configuration.document)
    case .clearedAndStopped(let failure):
      await handleCleared(failure)
    case nil:
      await deployListeningWithoutTarget()
    }
  }

  /// 收敛脊柱 apply 层的结果。
  enum ConvergenceResult {
    /// 部署已执行且启动健康通过。
    case applied
    /// 派生契约与运行中运行时逐字节相同：不写契约、不发信号、不闪
    /// starting、不重走健康门与系统代理收敛（幂等跳过）。
    case unchanged
    /// 执行或健康门失败；回滚由调用方按 RollbackPlan 处理。
    case failed
    /// 被更新的收敛取代：不得再变更任何状态。
    case superseded
  }

  /// 成功收敛后的系统代理收尾方式。
  enum ProxyConvergenceTail {
    /// 强制重收敛（mode 切换：系统代理值随模式 ACL 变化）。
    case forceApply
    /// 常规收敛（rules 提交）。
    case converge
    /// 无需收尾（deploy 路径由健康门自身的 convergeProxyOnSuccess 收敛）。
    case none
  }

  /// 收敛脊柱 apply 层：把一个已派生的运行时定义推到运行时——幂等跳过、
  /// 计划执行、启动健康门、成功后按参数收敛系统代理。失败不在此回滚：
  /// 返回 `.failed` 由调用方按 RollbackPlan 整体恢复。
  ///
  /// 票据 inout 传参：execute / 派生后的代际推进对调用方可见，调用方
  /// 在 apply 之后的时效检查使用的是推进过的票据。
  ///
  /// `starting` 在 execute 之前置位：`.run` 计划的动作全部同步执行，二者
  /// 之间不存在可见的挂起点，与旧路径「deploy 后置位」不可区分。
  func apply(
    _ document: SslocalRuntimeDocument,
    ticket: inout ConvergenceTicket,
    requiresReceipt: Bool,
    convergeProxyOnSuccess: Bool,
    preserveProxyOnFailure: Bool,
    proxyTail: ProxyConvergenceTail,
    rollback: RollbackPlan?
  ) async -> ConvergenceResult {
    let contract = try? PreparedRuntimeContract(document)
    if convergencePlanIsEmpty(document, preparedContract: contract) {
      RuntimeLog.emit(.contractUnchanged)
      ruleApplicationFailure = nil
      return .unchanged
    }
    guard convergenceIsCurrent(ticket) else { return .superseded }
    lastDocument = document
    state = .starting
    let execution = await execute(.run(document), document: document, preparedContract: contract)
    ticket.flow = execution.flow
    guard convergenceIsCurrent(ticket) else { return .superseded }
    guard execution.succeeded else { return .failed }
    let healthy = await presentLaunchHealth(
      document,
      requiresReceipt: requiresReceipt,
      convergeProxyOnSuccess: convergeProxyOnSuccess,
      preserveProxyOnFailure: preserveProxyOnFailure, preparedContract: contract)
    guard convergenceIsCurrent(ticket) else { return .superseded }
    guard healthy else { return .failed }
    lastDocument = document
    ruleApplicationFailure = nil
    switch proxyTail {
    case .forceApply: await systemProxyObserver.convergeSystemProxy(forceApply: true)
    case .converge: await systemProxyObserver.convergeSystemProxy()
    case .none: break
    }
    return .applied
  }

  /// 按回滚计划整体恢复:先查时效(票据含会话内 agent 意图)再动任何事实——
  /// 被取代或 agent 已被用户关闭的回滚不得把旧载荷写回持久层、也不得把
  /// 旧文档重新拉起;随后重持久化载荷 → 计划执行拉回旧文档(含按需拉起,
  /// 由计划层对注销/信号/注册的裁决保证与旧 restore 例程等价)→ 启动健康
  /// 门。载荷持久化失败不阻断文档恢复;文档恢复失败或健康不过即撤下系统
  /// 代理意图。
  func restore(_ plan: RollbackPlan, ticket: inout ConvergenceTicket) async -> RestoreReport {
    guard convergenceIsCurrent(ticket) else {
      return RestoreReport(payloadFailureDescription: nil, runtimeHealthy: nil)
    }
    var payloadFailureDescription: String?
    var restoredSettingsForMemory: ProxySettings?
    var restoredMode: ProxyMode?
    switch plan.payload {
    case .modeTransition(let mode, let ruleDefaultAction):
      // 按快照还原偏好（模式与子选项回退，其余字段保留当前值）。
      var restored = settings
      restored.preferredMode = mode.kind
      restored.ruleDefaultAction = ruleDefaultAction
      do {
        try settingsStore.save(restored)
      } catch {
        payloadFailureDescription = String(describing: error)
        RuntimeLog.emit(.runtimePersistFailed(detail: String(describing: error)))
      }
      restoredSettingsForMemory = restored
      restoredMode = mode
    case .runtimeOnly:
      break
    }
    func report(_ healthy: Bool?) -> RestoreReport {
      RestoreReport(
        payloadFailureDescription: payloadFailureDescription, runtimeHealthy: healthy)
    }
    if let restoredSettingsForMemory { settings = restoredSettingsForMemory }
    if let restoredMode { proxyMode = restoredMode }
    lastDocument = plan.document
    state = .starting
    let contract = try? PreparedRuntimeContract(plan.document)
    let execution = await execute(
      .run(plan.document), document: plan.document, preparedContract: contract)
    ticket.flow = execution.flow
    guard convergenceIsCurrent(ticket) else { return report(nil) }
    guard execution.succeeded else {
      await systemProxyObserver.holdSystemProxyIntent()
      return report(false)
    }
    let healthy = await presentLaunchHealth(
      plan.document, requiresReceipt: true, convergeProxyOnSuccess: false,
      preparedContract: contract)
    guard convergenceIsCurrent(ticket) else { return report(nil) }
    if healthy {
      if plan.convergeProxyOnIntentChange,
        settings.systemProxyEnabled != plan.systemProxyIntentAtCapture
      {
        await systemProxyObserver.convergeSystemProxy(forceApply: true)
      } else {
        state = plan.state
      }
    } else {
      await systemProxyObserver.holdSystemProxyIntent()
    }
    return report(healthy)
  }
}

/// 收敛失败时的整体回滚计划：恢复到哪个运行时文档、健康通过后呈现哪个
/// 状态、以及除文档外还要重持久化的载荷。
struct RollbackPlan {
  /// 回滚载荷：除运行时文档外还要恢复的持久化事实。
  enum Payload {
    /// mode 切换：设置快照的模式与规则子选项回退（其余字段保留当前值），
    /// 会话内 proxyMode 一并还原。
    case modeTransition(mode: ProxyMode, ruleDefaultAction: RuleDefaultAction)
    /// Rule application restores only the previous runtime, never saved intent.
    case runtimeOnly
  }

  /// 回滚目标文档（调用方已用当次加载值补齐）。
  let document: SslocalRuntimeDocument
  /// 健康通过后呈现的状态（收敛开始前捕获）。
  let state: ProxyRuntimeController.AgentRunState
  let payload: Payload
  /// 捕获时的系统代理意图：恢复健康后若当前意图已变化，强制重收敛一次。
  let systemProxyIntentAtCapture: Bool
  /// 是否在意图变化时强制重收敛（mode 切换路径；rules 路径为 false）。
  let convergeProxyOnIntentChange: Bool
}

/// 回滚报告：载荷重持久化与旧运行时恢复的结果。
struct RestoreReport {
  /// 载荷持久化失败的点名描述；nil = 成功。
  let payloadFailureDescription: String?
  /// 旧运行时是否恢复到健康；nil = 恢复未尝试（被弃权或被取代）。
  let runtimeHealthy: Bool?
}