Files
ShadowsocksX-NG/ShadowsocksX-NG2/Domain/CatalogFileStore.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

96 lines
3.4 KiB
Swift
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.
import Foundation
/// 配置树磁盘持久化(spec #21 D5):落盘 `~/Library/Application Support/
/// ShadowsocksX-NG/v2/catalog.json`,`v2/` 权限 0700、文件 0600;写临时文件
/// (创建即 0600)后原子替换。文件只含结构化目录与凭据引用,永不落秘密明文。
struct CatalogFileStore {
enum PersistenceError: Error, Equatable {
/// 文件存在但不是本模型可接受的目录文档:JSON 损坏、版本未知、结构不一致。
case corrupt(detail: String)
/// 读取或写入时的文件系统错误。
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/catalog.json`。
static func defaultFileURL() -> URL {
let support = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[
0]
return support.appendingPathComponent("ShadowsocksX-NG/v2/catalog.json")
}
/// 文件缺失 → 全新空目录;存在但损坏/版本未知/结构不一致 → `.corrupt`。
func load() throws -> ConfigurationCatalog {
guard FileManager.default.fileExists(atPath: fileURL.path) else {
return ConfigurationCatalog()
}
let data: Data
do {
data = try Data(contentsOf: fileURL)
} catch {
throw PersistenceError.ioFailure(detail: String(describing: error))
}
return try decode(data)
}
/// 整体重写并原子替换;失败时保留原文件。目录按 D5 基线强制 0700(含自愈)。
func save(_ catalog: ConfigurationCatalog) throws {
let payload = CatalogFilePayload(
version: Self.currentVersion,
rootChildren: catalog.rootChildren,
entries: catalog.entries.values.sorted { $0.id.rawValue < $1.id.rawValue }
)
let data: Data
do {
data = try Self.jsonEncoder.encode(payload)
} catch {
throw PersistenceError.ioFailure(detail: String(describing: error))
}
do {
try AtomicFileWriter.write(data, to: fileURL)
} catch {
throw PersistenceError.ioFailure(detail: String(describing: error))
}
}
private func decode(_ data: Data) throws -> ConfigurationCatalog {
let payload: CatalogFilePayload
do {
payload = try JSONDecoder().decode(CatalogFilePayload.self, from: data)
} catch {
throw PersistenceError.corrupt(detail: String(describing: error))
}
guard payload.version == Self.currentVersion else {
throw PersistenceError.corrupt(detail: "unsupported version \(payload.version)")
}
var entries: [NodeID: CatalogEntry] = [:]
for entry in payload.entries {
guard entries[entry.id] == nil else {
throw PersistenceError.corrupt(detail: "duplicate node id \(entry.id.rawValue)")
}
entries[entry.id] = entry
}
do {
return try ConfigurationCatalog.validated(
rootChildren: payload.rootChildren, entries: entries)
} catch let error as CatalogError {
throw PersistenceError.corrupt(detail: String(describing: error))
}
}
}
/// 落盘文档形态:版本号 + 根子序 + 全量节点表(顺序语义在根序与分组显子序中)。
private struct CatalogFilePayload: Codable {
var version: Int
var rootChildren: [NodeID]
var entries: [CatalogEntry]
}