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 "" } 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 } } }