Files
ShadowsocksX-NG/ShadowsocksX-NG2/Domain/Runtime/RuntimeLog.swift
T
Qiu Yuzhou 856d6b4272 refactor(domain): 按主题重组 Domain/ 源码目录
Domain/ 根目录原有 62 个平铺源文件,无法从目录读出主题划分。

按「目录即主题」重组为 11 个目录(Rules/Custom 为嵌套子目录):Catalog /
Subscription / Rules / Runtime / Activation / Settings / SystemProxy /
Plugin / Credentials / LegacyImport / Diagnostics。纯移动:类型名、模块名
与 import 均未改动,Domain/ 根下不再有散落文件。目录口径取自
GLOSSARY.md 的章节划分(配置与订阅、代理规则、代理控制与网络、设置、
凭据与诊断),而非新造分类。

配套改动:

- project.yml:wrapper 与 helper 两个 target 按文件引用的 15 条显式路径
  随目录改名,并补注释固定这一约定——这 15 条指向不存在的文件时,
  xcodegen generate 以 "missing source directory" 直接失败(实测,不静默)。
- SkeletonTests 新增 DomainLayoutTests:断言 Domain/ 根下无平铺 .swift、
  树下只有 .swift。后者防的是与 App/ 同源的坑——Domain/ 整目录是 app 与
  Core 的 source path,任何非源码文件都会被 XcodeGen 收进 Resources 阶段
  并封进签名后的 bundle。
- README 工程结构说明同步;docs/design 与 docs/research 属历史文档不改。

验证:xcodegen generate 后 app 164 / Core 163 源文件数与整理前一致;Agent
恰好 9 个、Helper 恰好 6 个 Domain 文件(无缺失无多出);app 与 Core 各覆盖
全部 62 个。clean build 0 error;task test 1024 用例全通过(整理前 1022,
+2 为新增守卫);task format 未改写任何被移动文件(证明纯移动);task lint
与整理前同为 21 条内容型 warning;packaging-gate.sh ALL CHECKS PASSED。

布局守卫已做变异验证:临时投放松散 .swift 与非 .swift 文件时两个用例均
失败并点名违规文件,清理后复验为绿。
2026-10-05 20:13:35 +08:00

166 lines
7.2 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
/// 运行时日志基线(spec #21 D5):事件是封闭枚举,脱敏由构造保证——永不
/// 携带密码、插件参数、Keychain 值、完整订阅 URL、URL token 或运行时 JSON
/// 内容;服务器地址与备注默认不进普通日志(端点探测失败点名的 host:port
/// 是本机监听端点,属 D8 要求呈现的事实字段,不受此限)。日志查看与诊断
/// 导出由 #34 在本事件流上接出。
enum RuntimeLogEvent: Equatable, CustomStringConvertible, Sendable {
/// 契约文件已原子写入(只携带数量元数据,非内容)。
case contractWritten(serverCount: Int)
/// 契约内容与磁盘一致,跳过写入(幂等)。
case contractUnchanged
/// 系统代理期望值与系统当前应用值语义等价,跳过写入(零授权,issue #70)。
case systemProxyUnchanged
/// 特权系统代理 helper 的 SMAppService 注册失败(issue #71;不含内容)。
case systemProxyHelperRegisterFailed(detail: String)
/// 系统代理写入/清除请求失败(issue #71;detail 为 XPC 或 helper 错误文本)。
case systemProxyWriteFailed(detail: String)
/// 运行时文件已清理。
case runtimeFilesDeleted
/// 激活状态等运行时元数据落盘失败(不含内容)。
case runtimePersistFailed(detail: String)
case agentRegistered
case agentRegisterFailed(detail: String)
case agentUnregistered
case agentUnregisterFailed(detail: String)
/// wrapper 侧 sslocal 监管事件。
case sslocalSpawned(pid: Int32)
case sslocalSpawnFailed
case sslocalExitedUnexpectedly(status: Int32)
case sslocalStopRequested
/// sslocal 拉起后限时内未完成本地监听绑定(D10「3 秒未建立监听 → error
/// 日志」;监管继续,GUI 健康门负责呈现,端点为本机监听端点不受脱敏限制)。
case listenNotEstablished(detail: String)
case contractMissing
case contractInvalidRemoved
case reloadForwarded
case reloadDeferred
case reloadRestarted
/// 本机代理端点启动后未就绪(点名端点与端口,D8)。
case endpointProbeFailed(host: String, port: Int, detail: String)
/// 激活失败或活动目标清除(原因枚举已点名且不含秘密)。
case activationFailed(reason: String)
/// 用户显式触发的脱敏诊断导出已完成(不携带导出路径)。
case diagnosticsExported
/// 监听设置持久化读取失败,已回落出厂默认(D8:不静默改端口——事件进
/// 诊断日志供 #34 查看器呈现,完整呈现面在 #33)。
case listenSettingsUnreadable(detail: String)
var description: String {
switch self {
case .contractWritten(let serverCount):
return "contract written (servers=\(serverCount))"
case .contractUnchanged:
return "contract unchanged, write skipped"
case .systemProxyUnchanged:
return "system proxy values unchanged, write skipped"
case .systemProxyHelperRegisterFailed(let detail):
return "system proxy helper register failed: \(detail)"
case .systemProxyWriteFailed(let detail):
return "system proxy write failed: \(detail)"
case .runtimeFilesDeleted:
return "runtime files deleted"
case .runtimePersistFailed(let detail):
return "runtime metadata persist failed: \(detail)"
case .agentRegistered:
return "launch agent registered"
case .agentRegisterFailed(let detail):
return "launch agent register failed: \(detail)"
case .agentUnregistered:
return "launch agent unregistered"
case .agentUnregisterFailed(let detail):
return "launch agent unregister failed: \(detail)"
case .sslocalSpawned(let pid):
return "sslocal spawned (pid=\(pid))"
case .sslocalSpawnFailed:
return "sslocal spawn failed"
case .sslocalExitedUnexpectedly(let status):
return "sslocal exited unexpectedly (status=\(status))"
case .sslocalStopRequested:
return "sslocal stop requested"
case .listenNotEstablished(let detail):
return "listen not established within deadline: \(detail)"
case .contractMissing:
return "contract missing"
case .contractInvalidRemoved:
return "contract invalid, removed"
case .reloadForwarded:
return "reload forwarded to sslocal"
case .reloadDeferred:
return "reload deferred until listeners are ready"
case .reloadRestarted:
return "reload: listen change, restarting sslocal"
case .endpointProbeFailed(let host, let port, let detail):
return "endpoint \(host):\(port) not ready: \(detail)"
case .activationFailed(let reason):
return "activation failed: \(reason)"
case .diagnosticsExported:
return "diagnostics report exported (redacted)"
case .listenSettingsUnreadable(let detail):
return "listen settings unreadable, falling back to factory defaults: \(detail)"
}
}
}
/// 事件接收缝(issue #34):GUI 进程把事件接入 RuntimeEventStore(内存环形
/// 缓冲),供主窗口日志查看器实时呈现与诊断导出取用;wrapper 进程不注册,
/// 仅走 stderr → agent.log 收敛。接收方拿到的是封闭枚举原值,渲染发生在
/// 呈现边缘(诊断报告的白名单清洗只可能作用于原值,issue #43)。
protocol RuntimeEventSink: Sendable {
func append(event: RuntimeLogEvent, timestamp: Date)
}
/// 敏感信息脱敏工具(D5「敏感信息」定义的读取面)。
enum Redactor {
/// 非空远程 URL 只保留 scheme+host:路径、查询与片段全部略去,完整订阅
/// URL 与 URL token 永不入日志。解析失败一律归并为占位符。
static func remoteURL(_ url: String) -> String {
guard let parsed = URL(string: url), let host = parsed.host(), !host.isEmpty else {
return "<redacted-url>"
}
return "\(parsed.scheme ?? "https")://\(host)/…"
}
/// 运行时文档只允许暴露数量与模式元数据。
static func documentSummary(_ document: SslocalRuntimeDocument) -> String {
let protocols = document.locals.map(\.inboundProtocol).joined(separator: ",")
return "servers=\(document.servers.count) protocols=\(protocols) mode=\(document.socksMode)"
}
}
/// 事件发射缝:wrapper 与 GUI 共用 stderr 行式输出(wrapper 侧由 launchd/
/// agent.log 收敛,GUI 侧进系统日志);GUI 启动时另注册接收缝接入事件缓冲。
enum RuntimeLog {
private static let sinkHolder = SinkHolder()
/// 注册/替换事件接收缝;传 nil 恢复纯 stderr(测试隔离用)。
static func setSink(_ sink: (any RuntimeEventSink)?) {
sinkHolder.set(sink)
}
static func emit(_ event: RuntimeLogEvent) {
let line = "ssxng: \(event.description)\n"
FileHandle.standardError.write(Data(line.utf8))
sinkHolder.current?.append(event: event, timestamp: Date())
}
/// 可变静态的锁保护持有者:emit 可能来自任意线程。
private final class SinkHolder: @unchecked Sendable {
private let lock = NSLock()
private var sink: (any RuntimeEventSink)?
var current: (any RuntimeEventSink)? {
lock.lock()
defer { lock.unlock() }
return sink
}
func set(_ value: (any RuntimeEventSink)?) {
lock.lock()
defer { lock.unlock() }
sink = value
}
}
}