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