Files
ShadowsocksX-NG/ShadowsocksX-NG2/App/ProxyRuntimeController.swift
T
Qiu Yuzhou 6bfd3c0d35 feat(ng2): proxy runtime LaunchAgent, wrapper and sslocal lifecycle (#27)
GUI → LaunchAgent → wrapper → sslocal full chain (spec #21 D2/D5):

- ShadowsocksX-NG2Agent: Swift BundleProgram tool target embedded at
  Contents/MacOS, supervised by launchd via SMAppService agent plist
  (Contents/Library/LaunchAgents, bundle-relative ProgramArguments,
  KeepAlive={SuccessfulExit:false}). Wrapper reads the cross-process
  contract v2/sslocal-active.json, spawns sslocal -c <absolute path>
  and supervises it: SIGTERM chain stop, SIGUSR1 forward for
  server-only changes vs graceful restart on listen fingerprint
  changes, non-zero exit on unexpected child loss for KeepAlive
  replay, invalid/missing contract → clean exit with plain unlink.
- Runtime file protocol: RuntimeFileStore reuses AtomicFileWriter
  (0700 dir self-heal, 0600 temp at creation, atomic replace);
  explicit-stop cleanup unlinks contract, agent pid file and stale
  temporaries. Shared read-side validation via
  SslocalRuntimeDocument.decodeValidated so GUI and wrapper cannot
  drift. Wrapper pid file bridges SMAppService's missing pid.
- GUI: ProxyRuntimeController consumes ActivationStateMachine effects
  through pure ProxyRuntimePlan decision table (ordered actions,
  idempotent skip of identical contract); proxy toggle and launch
  failure presentation (naming endpoint:port) in the status menu;
  launch resync reconciles agent registration, wrapper liveness and
  on-disk contract; catalog commits re-expand immediately.
- Log sanitization baseline: closed RuntimeLogEvent enum plus Redactor,
  wrapper/sslocal output converged to a 0600 agent.log with RUST_LOG
  defaulting to warn.

Tests (126 total, all green): stub-sslocal driven wrapper lifecycle
(start/stop order, SIGTERM chain, crash replay, cleanup, reload
protocol), real sslocal smoke (SOCKS port binding + full SOCKS5
handshake), plan decision table, controller flows with fakes,
runtime file permissions/atomic replace, endpoint probe, redaction.

Manual release-gate items (real launchd/SMAppService): agent
registration approval flow, GUI-quit persistence, bootout behaviors.

Closes #27
2026-09-20 20:26:54 +08:00

352 lines
13 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
import SwiftUI
/// 端点探测缝:注入以便控制器单测(真实探测走 EndpointHealthProbe)。
protocol EndpointProbing: Sendable {
func probe(host: String, port: Int, timeout: TimeInterval) -> EndpointHealthProbe.Outcome
}
struct SystemEndpointProbe: EndpointProbing {
func probe(host: String, port: Int, timeout: TimeInterval) -> EndpointHealthProbe.Outcome {
EndpointHealthProbe.probe(host: host, port: port, timeout: timeout)
}
}
/// 代理运行时控制器(spec #21 D2/D5,issue #27):把激活状态机的产出接到
/// 「GUI → LaunchAgent → wrapper → sslocal」链路。决策全部在纯域
/// `ProxyRuntimePlan`,本类按序执行动作并负责健康呈现;GUI 退出不影响任何
/// 一侧(agent 由 launchd 持有,构造上成立)。
@MainActor
final class ProxyRuntimeController: ObservableObject {
enum ProxyState: Equatable {
case off
case starting
case running
/// 启动失败:携带点名端点与端口的事实(D8;端口语义细节 #30 接线)。
case launchFailed(detail: String)
/// 激活失败或活动目标清除(无静默回退族的呈现面)。
case activationFailed(reason: String)
/// 需要用户在系统设置-登录项中允许后台项。
case requiresApproval
/// 服务管理或运行时文件本身失败。
case serviceFailed(detail: String)
}
@Published private(set) var state: ProxyState = .off
private(set) var machine: ActivationStateMachine
private var catalog: ConfigurationCatalog
private let catalogFileStore: CatalogFileStore
private let activationFileStore: ActivationStateFileStore
private let runtimeFileStore: RuntimeFileStore
private let credentials: CredentialStoring
private let plugins: ManagedPluginProviding
private let listen: SslocalListenSettings
private let agent: LaunchAgentControlling
private let probe: EndpointProbing
/// 信号发送缝(默认 kill),单测观测 SIGUSR1 投递。
private let sendSignal: @Sendable (Int32, Int32) -> Int32
/// 并发流代际:停止请求可使进行中的启动探测立即失效。
private var flowGeneration = 0
init(
catalogFileStore: CatalogFileStore = CatalogFileStore(
fileURL: CatalogFileStore.defaultFileURL()),
activationFileStore: ActivationStateFileStore = ActivationStateFileStore(
fileURL: ActivationStateFileStore.defaultFileURL()),
runtimeFileStore: RuntimeFileStore = RuntimeFileStore(),
credentials: CredentialStoring = KeychainCredentialStore(),
plugins: ManagedPluginProviding = NoManagedPluginProvider(),
listen: SslocalListenSettings = SslocalListenSettings(),
agent: LaunchAgentControlling = SMAppLaunchAgentService(),
probe: EndpointProbing = SystemEndpointProbe(),
sendSignal: @escaping @Sendable (Int32, Int32) -> Int32 = { kill($0, $1) }
) {
self.catalogFileStore = catalogFileStore
self.activationFileStore = activationFileStore
self.runtimeFileStore = runtimeFileStore
self.credentials = credentials
self.plugins = plugins
self.listen = listen
self.agent = agent
self.probe = probe
self.sendSignal = sendSignal
catalog = (try? catalogFileStore.load()) ?? ConfigurationCatalog()
let persistedTarget = try? activationFileStore.loadActiveTargetID()
machine = ActivationStateMachine(activeTargetID: persistedTarget)
}
var isActiveTargetPresent: Bool { machine.activeTargetID != nil }
/// 无活动目标时启用代理的点名原因(无静默回退族的呈现面)。
private static let noActiveTargetReason = "尚未激活任何服务器或分组,请先在主窗口激活后再启动代理"
// MARK: - 用户意图
/// 激活一个服务器或分组目标(目录 UI 工单复用入口):持久化目标;代理
/// 开启时立即把新档推到运行时。激活原子失败时状态完全不动(D3)。
func activate(_ target: NodeID) async {
reloadCatalog()
do {
let configuration = try machine.activate(
target, in: catalog, credentials: credentials, plugins: plugins, listen: listen)
do {
try activationFileStore.save(activeTargetID: target)
} catch {
state = .serviceFailed(detail: String(describing: error))
return
}
if state != .off {
await deploy(configuration.document)
}
} catch let failure as ActivationFailure {
state = .activationFailed(reason: failure.presentedReason)
} catch {
state = .serviceFailed(detail: String(describing: error))
}
}
/// 代理开关。
func setProxyEnabled(_ enabled: Bool) async {
if enabled {
await enable()
} else {
await execute(.stop, document: nil)
state = .off
}
}
/// 目录已提交变更后的立即重展开(D3/D5):有效非空且代理开启 → 原子更新
/// 运行时;目标失效 → 清除目标并停止代理。目录以磁盘为事实来源重载。
func catalogDidCommit() async {
reloadCatalog()
switch reexpand() {
case .deployed(let configuration):
if state != .off {
await deploy(configuration.document)
}
case .clearedAndStopped(let failure):
await handleCleared(failure)
case nil:
break
}
}
/// GUI 启动重同步(D5「GUI 下次启动重新校验同步」):注册态是代理意图的
/// 事实来源——注册过即视为开启并重校验;随后与磁盘契约对齐(相同内容跳
/// 过写入)。GUI 崩溃期间 agent 与 wrapper 均不受影响。
func resyncOnLaunch() async {
reloadCatalog()
switch reexpand() {
case .deployed(let configuration):
let status = agent.status
if status == .registered || status == .requiresApproval {
await deploy(configuration.document)
} else {
// 未注册但可能残留运行时文件(上次异常退出):清理残留,保持停止态。
runtimeFileStore.deleteRuntimeFiles()
RuntimeLog.emit(.runtimeFilesDeleted)
state = .off
}
case .clearedAndStopped(let failure):
await handleCleared(failure)
case nil:
// 无活动目标:只剩清理残留(计划层只在已注册时注销)。
await execute(.stop, document: nil)
state = .off
}
}
// MARK: - 动作执行
private func enable() async {
guard machine.activeTargetID != nil else {
presentNoActiveTarget()
return
}
reloadCatalog()
switch reexpand() {
case .deployed(let configuration):
await deploy(configuration.document)
case .clearedAndStopped(let failure):
await handleCleared(failure)
case nil:
presentNoActiveTarget()
}
}
private func presentNoActiveTarget() {
RuntimeLog.emit(.activationFailed(reason: Self.noActiveTargetReason))
state = .activationFailed(reason: Self.noActiveTargetReason)
}
/// 把「运行定义档」意图推到运行时:计划动作 → 顺序执行 → 端点健康呈现。
private func deploy(_ document: SslocalRuntimeDocument) async {
if await execute(.run(document), document: document) {
state = .starting
await presentLaunchHealth(document)
}
}
private func handleCleared(_ failure: ActivationFailure) async {
RuntimeLog.emit(.activationFailed(reason: failure.presentedReason))
do {
try activationFileStore.save(activeTargetID: nil)
} catch {
// 清目标失败不阻断停止:下次重同步会再次收敛(目标已不在状态机中)。
RuntimeLog.emit(.runtimePersistFailed(detail: String(describing: error)))
}
await execute(.stop, document: nil)
state = .activationFailed(reason: failure.presentedReason)
}
/// 按计划顺序执行动作;返回 false 表示中途失败、状态已呈现(后续动作与
/// 健康探测都不应继续)。
private func execute(_ intent: RuntimeIntent, document: SslocalRuntimeDocument?) async -> Bool {
flowGeneration += 1
let actions = ProxyRuntimePlan.actions(
intent: intent,
agentStatus: agent.status,
wrapper: wrapperState(),
contractOnDisk: runtimeFileStore.readData())
if case .run = intent, actions.isEmpty {
RuntimeLog.emit(.contractUnchanged)
}
for action in actions {
guard await perform(action, document: document) else { return false }
}
return true
}
/// 执行单个动作;返回 false 表示应终止后续动作(状态已呈现)。
private func perform(_ action: RuntimeAction, document: SslocalRuntimeDocument?) async -> Bool {
switch action {
case .writeContract:
guard let document else {
state = .serviceFailed(detail: "缺少运行时文档")
return false
}
do {
try runtimeFileStore.write(document)
RuntimeLog.emit(.contractWritten(serverCount: document.servers.count))
} catch {
state = .serviceFailed(detail: String(describing: error))
return false
}
case .registerAgent:
do {
try agent.register()
} catch {
RuntimeLog.emit(.agentRegisterFailed(detail: describe(error)))
if agent.status == .requiresApproval {
// 注册请求已被系统接收,等待用户在登录项中批准。
state = .requiresApproval
return false
}
if agent.status != .registered {
state = .serviceFailed(detail: describe(error))
return false
}
// 注册与状态读取之间的竞态:已注册即达意图,不视为失败。
}
RuntimeLog.emit(.agentRegistered)
if agent.status == .requiresApproval {
state = .requiresApproval
return false
}
case .unregisterAgent:
do {
try agent.unregister()
} catch {
// 未注册竞态可忽略;其余错误记录后继续清理(尽力而为)。
RuntimeLog.emit(.agentUnregisterFailed(detail: describe(error)))
}
RuntimeLog.emit(.agentUnregistered)
await waitForWrapperExit()
case .signalReload(let pid):
_ = sendSignal(pid, SIGUSR1)
case .deleteRuntimeFiles:
runtimeFileStore.deleteRuntimeFiles()
RuntimeLog.emit(.runtimeFilesDeleted)
}
return true
}
/// 启动健康呈现(D2/D8):以 TCP 连接确认 sslocal 实际绑定;超时即呈现
/// 「启动失败」,点名端点与端口(端口语义细节 #30 接线,这里给原始事实)。
private func presentLaunchHealth(_ document: SslocalRuntimeDocument) async {
let generation = flowGeneration
let deadline = Date().addingTimeInterval(15)
var outcome = EndpointHealthProbe.Outcome.timedOut
while Date() < deadline {
if generation != flowGeneration { return }
outcome = await probeAsync(
host: document.localAddress, port: document.localPort, timeout: 1.5)
if outcome == .reachable {
state = .running
return
}
try? await Task.sleep(nanoseconds: 200_000_000)
}
if generation != flowGeneration { return }
let detail: String
switch outcome {
case .reachable:
detail = "已连通"
case .refused(let reason):
detail = reason
case .timedOut:
detail = "连接超时"
}
RuntimeLog.emit(
.endpointProbeFailed(host: document.localAddress, port: document.localPort, detail: detail))
state = .launchFailed(
detail: "本地代理端点 \(document.localAddress):\(document.localPort) 未就绪(\(detail))")
}
private func probeAsync(host: String, port: Int, timeout: TimeInterval) async
-> EndpointHealthProbe.Outcome
{
let probe = probe
return await Task.detached(priority: .utility) {
probe.probe(host: host, port: port, timeout: timeout)
}.value
}
/// 显式停止协议次序(D2):注销(SIGTERM wrapper → wrapper 停 sslocal 并
/// 等待)完成后才允许后续删文件动作。最多等 5 秒,超时也继续(launchd 会
/// 兜底结束进程)。
private func waitForWrapperExit() async {
let deadline = Date().addingTimeInterval(5)
while wrapperState() != .notRunning && Date() < deadline {
try? await Task.sleep(nanoseconds: 100_000_000)
}
}
private func wrapperState() -> WrapperProcessState {
guard
let data = try? Data(contentsOf: runtimeFileStore.pidFileURL),
let text = String(data: data, encoding: .utf8)?.trimmingCharacters(
in: .whitespacesAndNewlines),
let pid = Int32(text)
else { return .notRunning }
guard sendSignal(pid, 0) == 0 else { return .notRunning }
return .running(pid: pid)
}
// MARK: - 目录同步
private func reloadCatalog() {
catalog = (try? catalogFileStore.load()) ?? catalog
}
private func reexpand() -> ActivationEffect? {
machine.catalogDidCommit(
catalog, credentials: credentials, plugins: plugins, listen: listen)
}
private func describe(_ error: Error) -> String {
(error as? ActivationFailure)?.presentedReason ?? String(describing: error)
}
}