Files
ShadowsocksX-NG/ShadowsocksX-NG2/App/LaunchAgentService.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

42 lines
1.1 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 ServiceManagement
/// LaunchAgent 管理缝(spec #21 D2):控制器经此协议启停 agent,单元测试以
/// fake 替换(真实 SMAppService 注册会改动用户登录项,不进单测)。
protocol LaunchAgentControlling {
var status: LaunchAgentStatus { get }
func register() throws
func unregister() throws
}
/// 生产实现:plist 必须位于 app bundle `Contents/Library/LaunchAgents/`,
/// ProgramArguments 为 bundle 相对路径(launchd 按注册 app 的 bundle 解析)。
struct SMAppLaunchAgentService: LaunchAgentControlling {
static let plistName = "com.qiuyuzhou.ShadowsocksX-NG.agent.plist"
private let service = SMAppService.agent(plistName: Self.plistName)
var status: LaunchAgentStatus {
switch service.status {
case .notRegistered:
return .notRegistered
case .enabled:
return .registered
case .requiresApproval:
return .requiresApproval
case .notFound:
return .notFound
@unknown default:
return .notFound
}
}
func register() throws {
try service.register()
}
func unregister() throws {
try service.unregister()
}
}