Files
ShadowsocksX-NG/ShadowsocksX-NG2/Domain/ActivationStateFileStore.swift
T
Qiu Yuzhou 9439e597e2 feat(ng2): activation semantics and runtime config derivation (#26)
激活状态机与派生层(spec #21 D3 激活族 + D5 派生):

- ActivationStateMachine:持久化活动目标(服务器或分组);激活原子成功
  或点名失败(保留原目标与运行状态);目录提交后立即重展开,失效即清除
  并发出停止意图(删除/禁用/变空/无效叶子各路径,无静默回退)
- 组激活按显式子序递归展开有效启用叶子;组目标保持组 UUID
- SslocalRuntimeDocument:完整 sslocal JSON 契约文档,凭据派生时解析,
  插件字段无插件时整体省略;ManagedPluginProviding 缝按「未提供」参与
  无效判定(真实受管集 #38 接通)
- ActivationStateFileStore:activation.json 持久化(0700/0600、原子替换,
  损坏按安全侧恢复为无活动目标);与 CatalogFileStore 共享 AtomicFileWriter
2026-09-20 18:50:58 +08:00

65 lines
2.4 KiB
Swift

import Foundation
/// 活动目标持久化(spec #21 D3/D5):落盘 `~/Library/Application Support/
/// ShadowsocksX-NG/v2/activation.json`,权限与原子替换基线同 catalog.json。
/// 只含目标身份,永不落秘密明文。损坏或版本未知按安全侧恢复为「无活动目标」
/// (代理保持停止,由状态机重校验同步);文件系统级错误仍抛出。
struct ActivationStateFileStore {
enum PersistenceError: Error, Equatable {
/// 读取或写入时的文件系统错误。
case ioFailure(detail: String)
}
private static let currentVersion = 1
private static let jsonEncoder: JSONEncoder = {
let encoder = JSONEncoder()
encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
return encoder
}()
let fileURL: URL
/// 默认位置:`~/Library/Application Support/ShadowsocksX-NG/v2/activation.json`。
static func defaultFileURL() -> URL {
let support = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[
0]
return support.appendingPathComponent("ShadowsocksX-NG/v2/activation.json")
}
/// 文件缺失/损坏/版本未知 → `nil`(安全侧:无活动目标)。
func loadActiveTargetID() throws -> NodeID? {
guard FileManager.default.fileExists(atPath: fileURL.path) else { return nil }
let data: Data
do {
data = try Data(contentsOf: fileURL)
} catch {
throw PersistenceError.ioFailure(detail: String(describing: error))
}
let payload = try? JSONDecoder().decode(ActivationStatePayload.self, from: data)
guard let payload, payload.version == Self.currentVersion else { return nil }
return payload.activeTargetID
}
/// 整体重写并原子替换;失败时保留原文件。目录按 D5 基线强制 0700(含自愈)。
func save(activeTargetID: NodeID?) throws {
let data: Data
do {
data = try Self.jsonEncoder.encode(
ActivationStatePayload(version: Self.currentVersion, activeTargetID: activeTargetID))
} catch {
throw PersistenceError.ioFailure(detail: String(describing: error))
}
do {
try AtomicFileWriter.write(data, to: fileURL)
} catch {
throw PersistenceError.ioFailure(detail: String(describing: error))
}
}
}
/// 落盘文档形态:版本号 + 活动目标身份(可为 null)。
private struct ActivationStatePayload: Codable {
var version: Int
var activeTargetID: NodeID?
}