Files
ShadowsocksX-NG/ShadowsocksX-NG2/App/Application/CatalogWorkflow/CatalogWorkflow.swift
T

443 lines
20 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 Combine
import Foundation
/// 目录工作流 module(深化为 application module):主窗口与
/// 配置 UI 的唯一 UI-facing seam。隐藏配置目录、凭据存储、订阅快照、Legacy
/// 导入细节、持久化协调与运行时收敛,向 UI 提供不含秘密值的树/详情/订阅
/// projection、opaque 节点身份查询、typed command、typed error 与 structured
/// outcome。选择、pane、sheet、alert 等窗口状态仍由 UI 持有;本类不生成
/// 用户可见文案。
///
/// 内部沿用既有深 module:`ConfigurationCatalog` 的结构约束、
/// `ActivationStateMachine` 经 `CatalogCommitCoordinator` 的激活语义与目录
/// 持久化/runtime sync 协调,以及既有凭据、订阅获取与 Legacy 导入缝。
/// 「目录已提交」与「运行时已收敛」是分离的观察面:提交在
/// 持久化成功即完成,`runtimeSync` 单独呈现收敛阶段,失败不回滚目录。
/// 实现 adapter 全部经组合根注入的 `CatalogWorkflowDependencies` 装配;
/// 本类不自行创建生产默认实现。
@MainActor
final class CatalogWorkflow: ObservableObject {
/// 目录树 projection(侧栏、级联、移动目的地、删除确认共用)。
@Published private(set) var tree: CatalogTreeSnapshot
@Published private(set) var favoriteIDs: [NodeID]
/// 订阅卡片 projection(非敏感)。
@Published private(set) var subscriptions: [SubscriptionSummary] = []
/// 正在刷新的订阅身份(并发守卫的只读观察面)。
@Published private(set) var refreshingSubscriptionIDs: Set<NodeID> = []
/// 当前会话的刷新结果;不从持久化状态重建,供各入口共用结束时间。
@Published private(set) var subscriptionRefreshCompletions:
[NodeID: SubscriptionRefreshCompletion] = [:]
/// 最近一次订阅刷新失败的 transient projection。这里保留完整凭据回滚
/// outcome;持久化目录只保存安全的 typed failure facts。
@Published private(set) var subscriptionRefreshFailures:
[NodeID: SubscriptionRefreshFailureResult] = [:]
/// 最近一次提交的运行时收敛阶段(与目录提交成功分离)。存储与
/// 发布单点在提交协调器,此处只透传读面;需要实时更新的表面订阅
/// `runtimeSyncChanges`(`.onReceive` 消费),不经本类 objectWillChange——
/// App 侧目前无视图消费者,避免每次提交徒劳失效全部目录观察者。
var runtimeSync: RuntimeSyncStatus { dependencies.coordinator.syncStatus }
/// 收敛阶段变化通道(didChange 语义,值即当前阶段)。
var runtimeSyncChanges: AnyPublisher<RuntimeSyncStatus, Never> {
dependencies.coordinator.syncStatusChanges.eraseToAnyPublisher()
}
/// Legacy 快照发现与一次性完成标记。
@Published private(set) var legacyImportState = LegacyImportAvailability(
snapshotFound: false, completed: false)
/// 组合根与测试装配的全部实现 adapter:coordinator、凭据、
/// 插件、订阅获取、Legacy 导入服务、导入后回调与激活缝只经此束持有,
/// 不再作为 workflow 属性暴露。仅供组合根与测试构造;视图不得访问——
/// 独立 target 拆分前由 architecture deletion check 守护残余可见性。
var connectivity: ServerConnectivity?
let dependencies: CatalogWorkflowDependencies
/// 启动时发现的 Legacy 快照(导入编排用;秘密值不进 projection)。
var discoveredLegacySnapshot: LegacySnapshot?
/// 组合根注入依赖束;workflow 不自行创建任何生产 adapter。
init(dependencies: CatalogWorkflowDependencies) {
self.dependencies = dependencies
let coordinator = dependencies.coordinator
favoriteIDs = coordinator.committedFavoriteIDs
tree = .build(
from: coordinator.committedCatalog,
credentials: dependencies.credentials, plugins: dependencies.plugins)
subscriptions = Self.subscriptionSummaries(
coordinator.committedSubscriptions, catalog: coordinator.committedCatalog,
credentials: dependencies.credentials)
refreshLegacyImportState()
}
/// Successful subscription commits, including unchanged references with new secrets.
private let subscriptionServerRefreshSubject = PassthroughSubject<Set<NodeID>, Never>()
var subscriptionServerRefreshes: AnyPublisher<Set<NodeID>, Never> {
subscriptionServerRefreshSubject.eraseToAnyPublisher()
}
private let serverUpdateSubject = PassthroughSubject<Set<NodeID>, Never>()
/// 成功保存或订阅刷新后装载详情参数,包括只改变凭据而树值不变的提交。
var serverDetailChanges: AnyPublisher<Set<NodeID>, Never> {
subscriptionServerRefreshSubject.merge(with: serverUpdateSubject).eraseToAnyPublisher()
}
func publishSubscriptionServerRefresh(_ id: NodeID) {
guard let summary = subscriptions.first(where: { $0.id == id }),
let group = tree.node(withID: summary.groupID)
else { return }
subscriptionServerRefreshSubject.send(group.subtreeIDs)
}
// MARK: - 查询面
/// 行显示名(导航标题、重命名预填等);节点不存在为空串。
func displayName(for id: NodeID) -> String {
dependencies.coordinator.committedCatalog.entry(for: id)?.displayName ?? ""
}
/// 有序平面收藏;配置组只返回自身,详情仍使用同一个节点身份。
var favorites: [CatalogTreeNode] {
favoriteIDs.compactMap { tree.node(withID: $0) }
}
func isFavorite(_ id: NodeID) -> Bool { favoriteIDs.contains(id) }
func setFavorite(_ id: NodeID, isFavorite: Bool) throws {
guard tree.containsNode(id) else { throw CatalogError.nodeNotFound(id) }
var updated = favoriteIDs
if isFavorite {
if !updated.contains(id) { updated.append(id) }
} else {
updated.removeAll { $0 == id }
}
try dependencies.coordinator.commitFavorites(updated)
favoriteIDs = dependencies.coordinator.committedFavoriteIDs
}
/// 将收藏移至指定收藏前;nil 表示末尾,不接受未收藏的节点。
func moveFavorite(_ id: NodeID, before target: NodeID?) throws {
guard favoriteIDs.contains(id) else { throw CatalogError.nodeNotFound(id) }
if let target, !favoriteIDs.contains(target) { throw CatalogError.nodeNotFound(target) }
guard id != target else { return }
var updated = favoriteIDs.filter { $0 != id }
let index = target.flatMap { updated.firstIndex(of: $0) } ?? updated.endIndex
updated.insert(id, at: index)
try dependencies.coordinator.commitFavorites(updated)
favoriteIDs = dependencies.coordinator.committedFavoriteIDs
}
/// 服务器叶子的已知阻塞原因(typed;编辑面「激活状态」区)。
func serverInvalidReasons(for id: NodeID) -> [LeafInvalidationReason] {
tree.node(withID: id)?.invalidReasons ?? []
}
/// Rendering reads metadata only, never credentials or form baselines.
func serverFormPresentation(for id: NodeID) -> ServerFormPresentation? {
guard let entry = dependencies.coordinator.committedCatalog.entry(for: id),
case .server(let fields) = entry.kind
else { return nil }
return ServerFormPresentation(
isEditable: entry.source == .manual, plugin: pluginPresentation(for: fields))
}
/// 已保存详情事实;普通渲染不读取密码或参数。
func serverDetailPresentation(for id: NodeID) -> ServerDetailPresentation? {
guard let entry = dependencies.coordinator.committedCatalog.entry(for: id),
case .server(let fields) = entry.kind
else { return nil }
return ServerDetailPresentation(
name: entry.displayName, address: fields.address, port: fields.port,
encryptionMethod: fields.encryptionMethod, plugin: pluginPresentation(for: fields))
}
/// 详情参数装载独立于密码和插件可用性;未知插件仍可核对原文。
func serverDetailPluginOptions(for id: NodeID) throws -> String {
guard let entry = dependencies.coordinator.committedCatalog.entry(for: id),
case .server(let fields) = entry.kind
else { throw ServerFormLoadError.notFound }
guard let reference = fields.pluginOptionsRef else { return "" }
return try requiredServerSecret(reference)
}
/// 服务器编辑面(显式命令):解析密码与目录中的具名插件参数明文。
/// 节点不存在或不是服务器叶子为 `nil`。
func serverEditForm(for id: NodeID) throws -> ServerEditForm? {
guard let entry = dependencies.coordinator.committedCatalog.entry(for: id),
case .server(let fields) = entry.kind
else { return nil }
let password = try requiredServerSecret(fields.passwordRef)
return ServerEditForm(
address: fields.address,
port: fields.port,
encryptionMethod: fields.encryptionMethod,
password: password,
remark: fields.remark,
plugin: try loadedPluginState(for: fields),
isEditable: entry.source == .manual)
}
/// An absent referenced secret is a load failure, never an empty saved baseline.
private func requiredServerSecret(_ reference: CredentialReference) throws -> String {
do {
guard let value = try dependencies.credentials.secret(for: reference) else {
throw ServerFormLoadError.credentialsUnavailable
}
return value
} catch {
throw ServerFormLoadError.credentialsUnavailable
}
}
/// 插件区状态:集内引用给可执行文件存在性事实与参数明文;集外引用
/// 以显式 unknown 呈现(原样保留,激活语义由状态机点名拒绝)。
private func pluginPresentation(for fields: ServerFields) -> PluginSectionState {
let snapshot = dependencies.plugins.catalogSnapshot()
let selection: PluginSelection
if let program = fields.pluginProgram {
selection =
snapshot.entry(for: program) != nil
? .named(program: program) : .unknown(program: program)
} else {
selection = .none
}
return pluginSection(
selection: selection, snapshot: snapshot,
optionsPresent: fields.pluginOptionsRef != nil)
}
private func loadedPluginState(for fields: ServerFields) throws -> PluginSectionState {
var facts = pluginPresentation(for: fields)
if case .named = facts.selection, let reference = fields.pluginOptionsRef {
facts.options = try requiredServerSecret(reference)
}
return facts
}
func newFormPluginSection(selection: PluginSelection) -> PluginSectionState {
pluginSection(
selection: selection, snapshot: dependencies.plugins.catalogSnapshot(),
optionsPresent: false)
}
private func pluginSection(
selection: PluginSelection, snapshot: PluginCatalogSnapshot, optionsPresent: Bool
) -> PluginSectionState {
PluginSectionState(
selection: selection,
programs: snapshot.entries.map {
PluginSectionState.Program(
program: $0.program, source: $0.source,
availability: $0.availability)
},
mappingsUnreadable: snapshot.mappingsUnreadable,
optionsPresent: optionsPresent, options: "")
}
/// 添加落点:选中手动分组 → 组内;选中服务器 → 其父组(仅手动);其余 → 根。
func importTargetParent(for selection: NodeID?) -> NodeID? {
let catalog = dependencies.coordinator.committedCatalog
guard let selection, let entry = catalog.entry(for: selection) else { return nil }
switch entry.kind {
case .group:
return entry.source == .manual ? selection : nil
case .server:
guard let parent = (try? catalog.parentID(of: selection)) ?? nil else { return nil }
return catalog.entry(for: parent)?.source == .manual ? parent : nil
}
}
// MARK: - 手动服务器/分组命令
/// 表单新建手动服务器:校验与提交语义与编辑对称——表单校验在建 journal
/// 前失败保持裸 `ServerFormError`;密码与可选插件参数和目录作为一个逻辑
/// 变更提交,持久化失败经 journal 回滚并以 `CommitError` 报出。新身份恒
/// 全新 UUID,不按内容去重(GLOSSARY.md 不变量);返回新节点身份供选中。
@discardableResult
func createServer(_ draft: ServerEditDraft, into parent: NodeID?) async throws -> NodeID {
let draft = try prepareServerDraft(draft)
var journal = CredentialWriteJournal(credentials: dependencies.credentials)
do {
return try commit { [self] catalog in
let now = Date()
let passwordRef = CredentialReference.fresh()
try journal.save(draft.password, for: passwordRef)
var fields = ServerFields(
address: draft.address, port: draft.port, encryptionMethod: draft.encryptionMethod,
passwordRef: passwordRef,
remark: draft.remark)
try Self.applyPluginSelection(
draft.plugin, options: draft.pluginOptions, to: &fields,
credentials: dependencies.credentials, journal: &journal)
return try catalog.addServer(fields, to: parent, now: now)
}
} catch {
throw CommitError(underlying: error, credentialRollback: journal.rollback())
}
}
/// 新建空手动分组;返回新分组身份。
@discardableResult
func createGroup(named name: String, into parent: NodeID?) async throws -> NodeID {
let trimmed = name.trimmingCharacters(in: .whitespaces)
guard !trimmed.isEmpty else { throw ServerFormError.emptyName }
return try commit { catalog in
try catalog.addGroup(trimmed, to: parent, now: Date())
}
}
/// 重命名手动分组:identity、父级与子项顺序不变。
func renameGroup(_ id: NodeID, to name: String) async throws {
let trimmed = name.trimmingCharacters(in: .whitespaces)
guard !trimmed.isEmpty else { throw ServerFormError.emptyName }
try commit { catalog in
try catalog.renameGroup(id, to: trimmed, now: Date())
}
}
/// 拖拽/移动菜单落点:跨来源、共享父级、成环由领域拒绝,
/// typed error 原样上抛。
func move(_ id: NodeID, to parent: NodeID?) async throws {
try commit { catalog in
try catalog.move(id, to: parent, now: Date())
}
}
/// 删除条目(手动分组递归删整棵子树):尽力清理被删节点的
/// Keychain 秘密;返回被删身份集合供 UI 清除失效选择。
func remove(_ id: NodeID) async throws -> RemovalOutcome {
let removed: [CatalogEntry] = try commit { catalog in
try catalog.remove(id, now: Date())
}
for ref in Self.credentialRefs(of: removed) {
try? dependencies.credentials.delete(ref)
}
return RemovalOutcome(removedNodeIDs: Set(removed.map(\.id)))
}
/// 服务器编辑提交:配置与凭据作为一个逻辑变更;凭据写入经
/// journal 记录原值,提交失败时全部恢复旧秘密,恢复结果经
/// `CommitError.credentialRollback` 报出。插件选择遵循目录工作流规则
/// 落盘(「无」整体清除、具名选择写程序名与参数、集外引用原样保留)。
func updateServer(_ id: NodeID, draft: ServerEditDraft) async throws {
let draft = try prepareServerDraft(draft)
var journal = CredentialWriteJournal(credentials: dependencies.credentials)
do {
try commit { [self] catalog in
guard let entry = catalog.entry(for: id), case .server(var fields) = entry.kind else {
throw CatalogError.notAServer(id)
}
try journal.save(draft.password, for: fields.passwordRef)
fields.address = draft.address
fields.port = draft.port
fields.encryptionMethod = draft.encryptionMethod
fields.remark = draft.remark
try Self.applyPluginSelection(
draft.plugin, options: draft.pluginOptions, to: &fields,
credentials: dependencies.credentials, journal: &journal)
try catalog.updateServer(id, with: fields, now: Date())
}
serverUpdateSubject.send([id])
} catch {
throw CommitError(underlying: error, credentialRollback: journal.rollback())
}
}
/// 新建与编辑共享的草稿准备:校验在凭据 journal 与目录提交之前完成。
/// 仅手动表单拒绝空名称;导入通过 ServerFields 的构造规则补名。
private func prepareServerDraft(_ input: ServerEditDraft) throws -> ServerEditDraft {
var draft = input
draft.address = draft.address.trimmingCharacters(in: .whitespaces)
guard !draft.address.isEmpty else { throw ServerFormError.invalidAddress }
guard (1...65_535).contains(draft.port) else { throw ServerFormError.invalidPort }
draft.encryptionMethod = draft.encryptionMethod.trimmingCharacters(in: .whitespacesAndNewlines)
guard !draft.encryptionMethod.isEmpty else { throw ServerFormError.missingEncryptionMethod }
guard EncryptionMethodCatalog.isSupported(draft.encryptionMethod) else {
throw ServerFormError.unsupportedEncryptionMethod(draft.encryptionMethod)
}
guard !draft.password.isEmpty else { throw ServerFormError.invalidPassword }
if case .named(let program) = draft.plugin,
dependencies.plugins.catalogSnapshot().entry(for: program) == nil
{
throw ServerFormError.pluginUnknown(program)
}
draft.remark = draft.remark.trimmingCharacters(in: .whitespacesAndNewlines)
guard !draft.remark.isEmpty else { throw ServerFormError.emptyName }
return draft
}
// MARK: - 提交管线(module 内部;UI 不得调用,独立 target 拆分前靠 deletion check)
/// 仅目录变更的提交便捷入口(module 内部扩展共用,同 `commitSubscriptionDocument`
/// 的窄缝口径)。
func commit<T>(
_ mutate: (inout ConfigurationCatalog) throws -> T
) throws -> T {
try commitDocument { catalog, _ in
try mutate(&catalog)
}
}
/// 副本变更 → 协调器落盘 → 重新发布 projection;任一步失败则已发布状态
/// 不动。运行时收敛由协调器异步调度,不阻塞也不回滚本提交。
private func commitDocument<T>(
_ mutate: (inout ConfigurationCatalog, inout [SubscriptionRecord]) throws -> T
) throws -> T {
let result = try dependencies.coordinator.commit(mutate)
republishCommittedState()
return result
}
/// 订阅扩展的唯一写路径(module 内部窄缝,替代直接摸 `commitDocument`)。
func commitSubscriptionDocument<T>(
_ mutate: (inout ConfigurationCatalog, inout [SubscriptionRecord]) throws -> T
) throws -> T {
try commitDocument(mutate)
}
/// 提交成功后的 projection 重建(树 + 订阅卡片)。
func republishCommittedState() {
connectivity?.configurationsChanged()
let coordinator = dependencies.coordinator
favoriteIDs = coordinator.committedFavoriteIDs
tree = .build(
from: coordinator.committedCatalog,
credentials: dependencies.credentials, plugins: dependencies.plugins)
subscriptions = Self.subscriptionSummaries(
coordinator.committedSubscriptions, catalog: coordinator.committedCatalog,
credentials: dependencies.credentials)
}
// MARK: - module 内部发布缝(扩展文件经此更新只读投影,setter 保持 private)
func publishLegacyImportState(_ state: LegacyImportAvailability) {
legacyImportState = state
}
/// 订阅刷新并发守卫的写入口(集合对外只读)。
func setRefreshInFlight(_ id: NodeID, _ inFlight: Bool) {
if inFlight {
refreshingSubscriptionIDs.insert(id)
} else {
refreshingSubscriptionIDs.remove(id)
}
}
func setSubscriptionRefreshCompletion(
_ completion: SubscriptionRefreshCompletion?, for id: NodeID
) {
subscriptionRefreshCompletions[id] = completion
}
func setSubscriptionRefreshFailure(
_ result: SubscriptionRefreshFailureResult?, for id: NodeID
) {
if let result {
subscriptionRefreshFailures[id] = result
} else {
subscriptionRefreshFailures.removeValue(forKey: id)
}
}
}