Files
ShadowsocksX-NG/ShadowsocksX-NG2/Tests/RuntimeFileStoreTests.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

160 lines
6.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 XCTest
@testable import ShadowsocksX_NG2
/// 运行时文件存取(spec #21 D5,issue #27):0700/0600 权限基线、原子替换、
/// 读取侧判定与显式停止清理。
final class RuntimeFileStoreTests: XCTestCase {
private var runtime: ProxyRuntimeFixture.TemporaryV2!
private var store: RuntimeFileStore!
override func setUpWithError() throws {
try super.setUpWithError()
runtime = ProxyRuntimeFixture.makeTemporaryV2()
store = RuntimeFileStore(fileURL: runtime.contract)
}
override func tearDownWithError() throws {
try? FileManager.default.removeItem(at: runtime.directory)
try super.tearDownWithError()
}
private func permissions(of url: URL) throws -> Int {
let attributes = try FileManager.default.attributesOfItem(atPath: url.path)
return try XCTUnwrap(attributes[.posixPermissions] as? Int)
}
// MARK: 权限基线(D5)
func testWriteCreatesDirectoryWith0700AndFileWith0600() throws {
try store.write(ProxyRuntimeFixture.makeDocument())
XCTAssertEqual(try permissions(of: runtime.directory), 0o700, "runtime/ 目录 0700")
XCTAssertEqual(try permissions(of: runtime.contract), 0o600, "契约文件 0600")
}
func testWriteHealsDirectoryPermissionBaseline() throws {
try FileManager.default.createDirectory(
at: runtime.directory, withIntermediateDirectories: true)
try FileManager.default.setAttributes(
[.posixPermissions: 0o755], ofItemAtPath: runtime.directory.path)
try store.write(ProxyRuntimeFixture.makeDocument())
XCTAssertEqual(try permissions(of: runtime.directory), 0o700, "目录权限自愈回 0700")
}
func testAtomicReplaceKeepsFileAt0600() throws {
try store.write(ProxyRuntimeFixture.makeDocument(localPort: 1086))
try store.write(ProxyRuntimeFixture.makeDocument(localPort: 2086))
XCTAssertEqual(try permissions(of: runtime.contract), 0o600, "替换后仍 0600")
let document = try XCTUnwrap(store.loadDocument())
XCTAssertEqual(document.localPort, 2086, "内容已被原子替换")
}
func testWriteLeavesNoTemporaryFilesBehind() throws {
try store.write(ProxyRuntimeFixture.makeDocument())
try store.write(ProxyRuntimeFixture.makeDocument(localPort: 2087))
let residue = try FileManager.default.contentsOfDirectory(atPath: runtime.directory.path)
.filter { $0.hasPrefix(".sslocal-active.json.tmp-") }
XCTAssertTrue(residue.isEmpty, "临时文件不应残留,实际 \(residue)")
}
// MARK: 读取侧判定
func testLoadDocumentRoundTripsWrittenDocument() throws {
let document = ProxyRuntimeFixture.makeDocument()
try store.write(document)
XCTAssertEqual(try store.loadDocument(), document)
XCTAssertEqual(try store.readData(), try document.jsonData())
}
func testLoadDocumentReturnsNilForMissingFile() throws {
XCTAssertNil(try store.loadDocument())
XCTAssertNil(try store.readData())
}
func testLoadDocumentReturnsNilForCorruptJSON() throws {
try Data("not json {".utf8).write(to: runtime.contract)
XCTAssertNil(try store.loadDocument())
}
func testLoadDocumentReturnsNilForStructurallyInvalidDocument() throws {
try store.write(
SslocalRuntimeDocument(
servers: [], localAddress: "127.0.0.1", localPort: 1086, inboundProtocol: "socks",
mode: "tcp_only"))
XCTAssertNil(try store.loadDocument(), "空 servers 属结构性无效(读取侧防御)")
}
// MARK: 显式停止清理
func testDeleteRuntimeFilesRemovesContractPidAndStaleTemporaries() throws {
try store.write(ProxyRuntimeFixture.makeDocument())
try Data("1086".utf8).write(to: runtime.pidFile)
let staleTemporary = runtime.directory.appendingPathComponent(".sslocal-active.json.tmp-stale")
try Data("partial".utf8).write(to: staleTemporary)
store.deleteRuntimeFiles()
XCTAssertFalse(FileManager.default.fileExists(atPath: runtime.contract.path))
XCTAssertFalse(FileManager.default.fileExists(atPath: runtime.pidFile.path))
XCTAssertFalse(FileManager.default.fileExists(atPath: staleTemporary.path))
}
func testDeleteRuntimeFilesIsHarmlessWhenNothingExists() throws {
store.deleteRuntimeFiles()
store.deleteRuntimeFiles()
XCTAssertTrue(true, "重复清理不抛错")
}
// MARK: 文档校验与监听指纹
func testWellFormedValidationRejectsStructuralGarbage() {
func document(
localPort: Int = 1086,
servers: [SslocalServerDocument]
) -> SslocalRuntimeDocument {
SslocalRuntimeDocument(
servers: servers, localAddress: "127.0.0.1", localPort: localPort,
inboundProtocol: "socks", mode: "tcp_only")
}
func server(
id: String = "s", address: String = "203.0.113.7", port: Int = 8388,
method: String = "aes-256-gcm"
) -> SslocalServerDocument {
SslocalServerDocument(
id: id, remarks: "", server: address, serverPort: port, password: "pw",
method: method, plugin: nil, pluginOpts: nil)
}
XCTAssertTrue(document(servers: [server()]).isWellFormed)
XCTAssertFalse(document(servers: []).isWellFormed, "空 servers 无效")
XCTAssertFalse(document(localPort: 0, servers: [server()]).isWellFormed)
XCTAssertFalse(document(localPort: 65_536, servers: [server()]).isWellFormed)
XCTAssertFalse(document(servers: [server(port: 0)]).isWellFormed)
XCTAssertFalse(document(servers: [server(address: "")]).isWellFormed)
XCTAssertFalse(document(servers: [server(method: "")]).isWellFormed)
XCTAssertFalse(document(servers: [server(id: "")]).isWellFormed)
}
func testListenFingerprintIgnoresServerChangesAndTracksListenFields() {
let base = ProxyRuntimeFixture.makeDocument()
let serverChanged = ProxyRuntimeFixture.makeDocument(serverAddress: "198.51.100.9")
let listenChanged = ProxyRuntimeFixture.makeDocument(localPort: 2088)
XCTAssertEqual(
base.listenFingerprint, serverChanged.listenFingerprint,
"仅服务器列表变化不影响监听指纹(走 SIGUSR1 热重载)")
XCTAssertNotEqual(
base.listenFingerprint, listenChanged.listenFingerprint,
"监听端口变化改变指纹(走优雅重启)")
}
}