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

89 lines
3.6 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
/// LaunchAgent 注册态(GUI 视角,spec #21 D2):SMAppService.Status 的纯域
/// 映射。SMAppService 不暴露运行中 agent 的 pid,wrapper 活性另由
/// `WrapperProcessState` 表达。
enum LaunchAgentStatus: Equatable, Sendable {
case notRegistered
/// 已注册(无论 wrapper 进程当前是否在运行)。
case registered
/// 需要用户在系统设置的登录项中批准。
case requiresApproval
/// 注册清单缺失(bundle 内 plist 不在)。
case notFound
}
/// wrapper 进程活性:GUI 读 `v2/agent.pid` 并以 `kill(pid, 0)` 判定(D2)。
enum WrapperProcessState: Equatable, Sendable {
case notRunning
case running(pid: Int32)
}
/// GUI 对代理运行时的意图:运行给定义档,或停止并清理。
enum RuntimeIntent: Equatable {
case run(SslocalRuntimeDocument)
case stop
}
/// 控制器按序执行的动作(spec #21 D2/D5)。
enum RuntimeAction: Equatable, Sendable {
/// 原子写契约文件(权限与替换基线由 RuntimeFileStore 保证)。
case writeContract
/// 注册 LaunchAgent;launchd 随即拉起 wrapper,wrapper 启动时读契约。
case registerAgent
/// 注销 LaunchAgent:launchd 以 SIGTERM 结束 wrapper,触发显式停止协议
/// (wrapper 停 sslocal 并等待退出)。
case unregisterAgent
/// 通知运行中的 wrapper 重读契约;热重载或优雅重启由 wrapper 按监听
/// 指纹判定(D5 变更协议)。
case signalReload(pid: Int32)
/// 删除运行时文件(契约、pid 文件与残留临时文件)。
case deleteRuntimeFiles
}
/// 纯决策层(spec #21 D2/D5):把「代理意图 + launchd 注册态 + wrapper 活性
/// + 磁盘契约」推到有序动作序列。GUI 启动重同步、目录提交重展开与代理开关
/// 共用同一决策;相同契约内容跳过写入,兑现激活状态机的幂等注记。
enum ProxyRuntimePlan {
static func actions(
intent: RuntimeIntent,
agentStatus: LaunchAgentStatus,
wrapper: WrapperProcessState,
contractOnDisk: Data?
) -> [RuntimeAction] {
switch intent {
case .run(let document):
switch agentStatus {
case .notRegistered, .notFound, .requiresApproval:
// 首次启用或从未注册:写盘后注册,launchd 拉起的 wrapper 直接读新档。
return [.writeContract, .registerAgent]
case .registered:
switch wrapper {
case .running(let pid):
// 相同内容跳过写入(幂等优化);内容比较本身失败时宁可重写——
// 写入侧会如实呈现错误,不静默跳过部署。
if let onDisk = contractOnDisk, let desiredData = try? document.jsonData(),
desiredData == onDisk
{
return []
}
return [.writeContract, .signalReload(pid: pid)]
case .notRunning:
// 已注册但 wrapper 已干净退出(如契约曾被清理):强制重新拉起。
// SMAppService 对已注册服务重复 register 不保证重跑,先注销再注册。
return [.writeContract, .unregisterAgent, .registerAgent]
}
}
case .stop:
switch agentStatus {
case .registered:
// 显式停止协议次序(D2):注销即 SIGTERM wrapper → wrapper 停 sslocal
// 并等待 → 控制器确认 wrapper 退出后才删文件(执行侧保证次序)。
return [.unregisterAgent, .deleteRuntimeFiles]
case .notRegistered, .requiresApproval, .notFound:
return [.deleteRuntimeFiles]
}
}
}
}