From ec09d79399d5edcc96fd2612a32c786f7a6888d8 Mon Sep 17 00:00:00 2001 From: Qiu Yuzhou Date: Tue, 20 Oct 2026 11:05:26 +0800 Subject: [PATCH] feat(runtime): route runtime events to the unified log Emit every RuntimeLogEvent to os.Logger under a shared subsystem with per-event category and level, so GUI and wrapper output can be filtered in Console.app. Public text is split from private detail (free-form error text and connectivity measurement content) on the closed enum, keeping server addresses out of the public log surface. The stderr line and the event sink stay unchanged. Add the system log glossary term. --- GLOSSARY.md | 4 + .../Domain/Runtime/RuntimeLog.swift | 97 ++++++++++++++++- .../RuntimeLogSystemLogRouteTests.swift | 101 ++++++++++++++++++ 3 files changed, 197 insertions(+), 5 deletions(-) create mode 100644 ShadowsocksX-NG2/Tests/Runtime/RuntimeLogSystemLogRouteTests.swift diff --git a/GLOSSARY.md b/GLOSSARY.md index a5c520eb..8e662955 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -291,5 +291,9 @@ _避免用词_:菜单栏形态(Menu bar form,应用形态并非恒定) **诊断日志视图(Diagnostic log view)**: 用户明确查看或复制界面事件与后台服务原始日志的入口,所展示的原始日志不属于诊断报告。 +**系统日志(System log)**: +本应用图形界面与后台服务写入 macOS 统一日志系统、供用户在 Console.app 中按来源与类别过滤查看的本地事件流。它面向本地排错,不是诊断报告的内容来源,也不替代诊断日志视图的显式查看与复制。 +_避免用词_:os_log 输出(实现机制名,不是领域概念)。 + **诊断事实(Diagnostic facts)**: 可供诊断报告使用的配置目录与代理服务汇总事实,已经脱敏,且不暴露配置条目或敏感信息。 diff --git a/ShadowsocksX-NG2/Domain/Runtime/RuntimeLog.swift b/ShadowsocksX-NG2/Domain/Runtime/RuntimeLog.swift index 72ef1bc5..32977b81 100644 --- a/ShadowsocksX-NG2/Domain/Runtime/RuntimeLog.swift +++ b/ShadowsocksX-NG2/Domain/Runtime/RuntimeLog.swift @@ -1,4 +1,5 @@ import Foundation +import os /// 运行时日志基线:事件是封闭枚举,脱敏由构造保证——永不 /// 携带密码、插件参数、Keychain 值、完整订阅 URL 及其 token 或运行时 JSON @@ -113,9 +114,84 @@ enum RuntimeLogEvent: Equatable, CustomStringConvertible, Sendable { } } +/// 系统日志路由(统一日志,Console.app 可按 subsystem/category 过滤): +/// level 三分(失败类 error、里程碑 default、冗长测量 info)、category 五分 +/// (runtime / supervision / system-proxy / connectivity / diagnostics)。 +/// 拆分规则:`text` + `privateDetail` == `description`;自由错误 detail 与 +/// 连通性测量内容(含探测目标 IP)拆出由发射缝标 private,公开文本由 +/// description 尾部裁切派生,不手抄前缀。穷举 switch:新事件漏路由无法编译。 +extension RuntimeLogEvent { + var systemLogRoute: SystemLogRoute { + switch self { + case .contractWritten, .contractUnchanged, .runtimeFilesDeleted: + return SystemLogRoute( + level: .default, category: "runtime", text: description, privateDetail: nil) + case .contractMissing, .contractInvalid, .activationFailed: + return SystemLogRoute( + level: .error, category: "runtime", text: description, privateDetail: nil) + case .runtimePersistFailed(let detail): + return SystemLogRoute( + level: .error, category: "runtime", text: String(description.dropLast(detail.count)), + privateDetail: detail) + case .settingsUnreadable(let detail): + return SystemLogRoute( + level: .error, category: "runtime", + text: String(description.dropLast(detail.count)), privateDetail: detail) + case .agentRegistered, .agentUnregistered, .sslocalSpawned, .sslocalStopRequested, + .reloadForwarded, .reloadDeferred, .reloadRestarted: + return SystemLogRoute( + level: .default, category: "supervision", text: description, privateDetail: nil) + case .sslocalSpawnFailed, .sslocalExitedUnexpectedly, .listenNotEstablished: + return SystemLogRoute( + level: .error, category: "supervision", text: description, privateDetail: nil) + case .agentRegisterFailed(let detail): + return SystemLogRoute( + level: .error, category: "supervision", + text: String(description.dropLast(detail.count)), privateDetail: detail) + case .agentUnregisterFailed(let detail): + return SystemLogRoute( + level: .error, category: "supervision", + text: String(description.dropLast(detail.count)), privateDetail: detail) + case .systemProxyUnchanged: + return SystemLogRoute( + level: .default, category: "system-proxy", text: description, privateDetail: nil) + case .systemProxyHelperRegisterFailed(let detail): + return SystemLogRoute( + level: .error, category: "system-proxy", + text: String(description.dropLast(detail.count)), privateDetail: detail) + case .systemProxyWriteFailed(let detail): + return SystemLogRoute( + level: .error, category: "system-proxy", + text: String(description.dropLast(detail.count)), privateDetail: detail) + case .endpointProbeFailed(_, _, let detail): + return SystemLogRoute( + level: .error, category: "connectivity", + text: String(description.dropLast(detail.count)), privateDetail: detail) + case .connectivityMeasurement(_, let entry): + // 测量内容含探测目标 IP,整段标 private(普通日志不进服务器地址)。 + return SystemLogRoute( + level: .info, category: "connectivity", + text: String(description.dropLast(entry.description.count)), + privateDetail: entry.description) + case .diagnosticsExported: + return SystemLogRoute( + level: .default, category: "diagnostics", text: description, privateDetail: nil) + } + } +} + +/// 系统日志路由事实:发射缝按此构造统一日志消息。`text` 已含与 +/// `privateDetail` 之间的分隔符,两者拼接等于事件的 `description`。 +struct SystemLogRoute: Sendable { + var level: OSLogType + var category: String + var text: String + var privateDetail: String? +} + /// 事件接收缝:GUI 进程把事件接入 RuntimeEventStore(内存环形 -/// 缓冲),供主窗口日志查看器实时呈现与诊断导出取用;wrapper 进程不注册, -/// 仅走 stderr → agent.log 收敛。接收方拿到的是封闭枚举原值,渲染发生在 +/// 缓冲),供主窗口日志查看器实时呈现与诊断导出取用;wrapper 进程不注册 +/// (stderr 收敛进 agent.log)。接收方拿到的是封闭枚举原值,渲染发生在 /// 呈现边缘(诊断报告的白名单清洗只可能作用于原值)。 protocol RuntimeEventSink: Sendable { func append(event: RuntimeLogEvent, timestamp: Date) @@ -135,18 +211,29 @@ enum Redactor { } -/// 事件发射缝:wrapper 与 GUI 共用 stderr 行式输出(wrapper 侧由 launchd/ -/// agent.log 收敛,GUI 侧进系统日志);GUI 启动时另注册接收缝接入事件缓冲。 +/// 事件发射缝:wrapper 与 GUI 共用 stderr 行式输出(wrapper 侧收敛进 +/// agent.log)与系统日志输出(统一 subsystem,Console.app 按 category 过滤, +/// 拆出的 detail 段标 private);GUI 启动时另注册接收缝接入事件缓冲。 enum RuntimeLog { + /// 系统日志 subsystem:各进程共用一个名字,Console.app 一条过滤全看。 + static let subsystem = "com.qiuyuzhou.ShadowsocksX-NG2" + private static let sinkHolder = SinkHolder() - /// 注册/替换事件接收缝;传 nil 恢复纯 stderr(测试隔离用)。 + /// 注册/替换事件接收缝;传 nil 移除接收缝(测试隔离用)。 static func setSink(_ sink: (any RuntimeEventSink)?) { sinkHolder.set(sink) } static func emit(_ event: RuntimeLogEvent) { if let line = event.standardErrorLine { FileHandle.standardError.write(Data(line.utf8)) } + let route = event.systemLogRoute + let logger = Logger(subsystem: subsystem, category: route.category) + if let detail = route.privateDetail { + logger.log(level: route.level, "\(route.text, privacy: .public)\(detail, privacy: .private)") + } else { + logger.log(level: route.level, "\(route.text, privacy: .public)") + } sinkHolder.current?.append(event: event, timestamp: Date()) } diff --git a/ShadowsocksX-NG2/Tests/Runtime/RuntimeLogSystemLogRouteTests.swift b/ShadowsocksX-NG2/Tests/Runtime/RuntimeLogSystemLogRouteTests.swift new file mode 100644 index 00000000..2a5c0d67 --- /dev/null +++ b/ShadowsocksX-NG2/Tests/Runtime/RuntimeLogSystemLogRouteTests.swift @@ -0,0 +1,101 @@ +import Foundation +import Testing +import os + +@testable import ShadowsocksX_NG2 + +/// 系统日志路由基线:level 三分(失败 error / 里程碑 default / 冗长测量 +/// info)、category 五分、公开文本与 private detail 的拆分。映射是封闭枚举 +/// 上的纯数据,测数据不测转发。 +@Suite struct RuntimeLogSystemLogRouteTests { + private let detail = "SECRET-DETAIL" + + private struct Expectation { + var event: RuntimeLogEvent + var level: OSLogType + var category: String + var detail: String? + } + + /// 全部事件的路由事实;新增事件漏路由由穷举 switch 兜底,本表锁定 + /// level / category / detail 拆分不随重构漂移。 + private var expectations: [Expectation] { + let trace = ConnectivityTrace(phase: .sample, status: .success) + return [ + Expectation( + event: .contractWritten(serverCount: 2), level: .default, category: "runtime", detail: nil), + Expectation(event: .contractUnchanged, level: .default, category: "runtime", detail: nil), + Expectation(event: .runtimeFilesDeleted, level: .default, category: "runtime", detail: nil), + Expectation(event: .contractMissing, level: .error, category: "runtime", detail: nil), + Expectation(event: .contractInvalid, level: .error, category: "runtime", detail: nil), + Expectation( + event: .activationFailed(reason: "no usable server"), level: .error, category: "runtime", + detail: nil), + Expectation( + event: .runtimePersistFailed(detail: detail), level: .error, category: "runtime", + detail: detail), + Expectation( + event: .settingsUnreadable(detail: detail), level: .error, category: "runtime", + detail: detail), + Expectation(event: .agentRegistered, level: .default, category: "supervision", detail: nil), + Expectation(event: .agentUnregistered, level: .default, category: "supervision", detail: nil), + Expectation( + event: .sslocalSpawned(pid: 1), level: .default, category: "supervision", detail: nil), + Expectation( + event: .sslocalStopRequested, level: .default, category: "supervision", detail: nil), + Expectation(event: .reloadForwarded, level: .default, category: "supervision", detail: nil), + Expectation(event: .reloadDeferred, level: .default, category: "supervision", detail: nil), + Expectation(event: .reloadRestarted, level: .default, category: "supervision", detail: nil), + Expectation(event: .sslocalSpawnFailed, level: .error, category: "supervision", detail: nil), + Expectation( + event: .sslocalExitedUnexpectedly(status: 1), level: .error, category: "supervision", + detail: nil), + Expectation( + event: .listenNotEstablished(detail: "socks 127.0.0.1:11086"), + level: .error, category: "supervision", detail: nil), + Expectation( + event: .agentRegisterFailed(detail: detail), level: .error, category: "supervision", + detail: detail), + Expectation( + event: .agentUnregisterFailed(detail: detail), level: .error, category: "supervision", + detail: detail), + Expectation( + event: .systemProxyUnchanged, level: .default, category: "system-proxy", detail: nil), + Expectation( + event: .systemProxyHelperRegisterFailed(detail: detail), + level: .error, category: "system-proxy", detail: detail), + Expectation( + event: .systemProxyWriteFailed(detail: detail), level: .error, category: "system-proxy", + detail: detail), + Expectation( + event: .connectivityMeasurement(id: UUID(), entry: trace), + level: .info, category: "connectivity", detail: trace.description), + Expectation( + event: .endpointProbeFailed(host: "127.0.0.1", port: 11086, detail: detail), + level: .error, category: "connectivity", detail: detail), + Expectation( + event: .diagnosticsExported, level: .default, category: "diagnostics", detail: nil), + ] + } + + @Test func everyEventRoutesToLevelCategoryAndPrivacySplit() { + for row in expectations { + let route = row.event.systemLogRoute + #expect(route.level == row.level, "level 漂移:\(row.event)") + #expect(route.category == row.category, "category 漂移:\(row.event)") + #expect(route.privateDetail == row.detail, "detail 拆分漂移:\(row.event)") + } + } + + @Test func publicTextPlusPrivateDetailMatchesDescription() { + for row in expectations { + let route = row.event.systemLogRoute + // 公开文本只到分隔符为止;detail(含连通性测量的目标 IP)只进 private 段。 + #expect( + route.text + (route.privateDetail ?? "") == row.event.description, "公开文本漂移:\(row.event)") + if let detail = route.privateDetail { + #expect(!route.text.contains(detail), "公开文本不得携带 private detail:\(row.event)") + } + } + } +}