RadrootsTelemetry.swift (12353B)
1 import Foundation 2 3 public enum RadrootsTelemetryError: Error, Equatable, Sendable { 4 case invalidRequest 5 } 6 7 extension RadrootsTelemetryError: LocalizedError { 8 public var errorDescription: String? { "The telemetry request is invalid." } 9 } 10 11 public enum RadrootsTelemetryLevel: String, Sendable, Equatable, Hashable, CaseIterable, Comparable 12 { 13 case trace 14 case debug 15 case info 16 case notice 17 case warning 18 case error 19 case critical 20 21 public static func < (lhs: Self, rhs: Self) -> Bool { 22 lhs.severity < rhs.severity 23 } 24 25 public var severity: Int { 26 switch self { 27 case .trace: 28 0 29 case .debug: 30 1 31 case .info: 32 2 33 case .notice: 34 3 35 case .warning: 36 4 37 case .error: 38 5 39 case .critical: 40 6 41 } 42 } 43 } 44 45 public enum RadrootsTelemetryFieldValue: Sendable, Equatable, Hashable { 46 case string(String) 47 case integer(Int64) 48 case double(Double) 49 case bool(Bool) 50 case stringList([String]) 51 52 public var renderedValue: String { 53 switch self { 54 case .string(let value): 55 value 56 case .integer(let value): 57 String(value) 58 case .double(let value): 59 String(value) 60 case .bool(let value): 61 value ? "true" : "false" 62 case .stringList(let value): 63 value.joined(separator: ",") 64 } 65 } 66 67 fileprivate func redacted( 68 key: String, 69 policy: RadrootsTelemetryRedactionPolicy 70 ) -> RadrootsTelemetryFieldValue { 71 switch self { 72 case .string(let value): 73 return .string(policy.redactedString(value, key: key)) 74 case .integer, .double, .bool: 75 return policy.shouldRedactKey(key) ? .string(policy.replacement) : self 76 case .stringList(let values): 77 if policy.shouldRedactKey(key) { 78 return .string(policy.replacement) 79 } 80 return .stringList(values.map { policy.redactedString($0, key: key) }) 81 } 82 } 83 } 84 85 public struct RadrootsTelemetryField: Sendable, Equatable, Hashable { 86 public let key: String 87 public let value: RadrootsTelemetryFieldValue 88 89 public init(key: String, value: RadrootsTelemetryFieldValue) throws { 90 let normalizedKey = try RadrootsTelemetryValidation.normalizedIdentifier( 91 key, 92 field: "telemetry field key", 93 maximumLength: 80 94 ) 95 try RadrootsTelemetryValidation.validate(value) 96 self.key = normalizedKey 97 self.value = value 98 } 99 100 public static func string(_ key: String, _ value: String) throws -> Self { 101 try Self(key: key, value: .string(value)) 102 } 103 104 public static func integer(_ key: String, _ value: Int) throws -> Self { 105 try Self(key: key, value: .integer(Int64(value))) 106 } 107 108 public static func integer(_ key: String, _ value: Int64) throws -> Self { 109 try Self(key: key, value: .integer(value)) 110 } 111 112 public static func double(_ key: String, _ value: Double) throws -> Self { 113 try Self(key: key, value: .double(value)) 114 } 115 116 public static func bool(_ key: String, _ value: Bool) throws -> Self { 117 try Self(key: key, value: .bool(value)) 118 } 119 120 public static func stringList(_ key: String, _ value: [String]) throws -> Self { 121 try Self(key: key, value: .stringList(value)) 122 } 123 124 fileprivate init(validatedKey: String, value: RadrootsTelemetryFieldValue) { 125 key = validatedKey 126 self.value = value 127 } 128 129 fileprivate func redacted(policy: RadrootsTelemetryRedactionPolicy) -> Self { 130 Self(validatedKey: key, value: value.redacted(key: key, policy: policy)) 131 } 132 } 133 134 public struct RadrootsTelemetryEvent: Sendable, Equatable, Hashable { 135 public let name: String 136 public let category: String 137 public let level: RadrootsTelemetryLevel 138 public let message: String? 139 public let fields: [RadrootsTelemetryField] 140 public let occurredAt: Date 141 142 public init( 143 name: String, 144 category: String = "app", 145 level: RadrootsTelemetryLevel = .info, 146 message: String? = nil, 147 fields: [RadrootsTelemetryField] = [], 148 occurredAt: Date = Date() 149 ) throws { 150 let normalizedName = try RadrootsTelemetryValidation.normalizedIdentifier( 151 name, 152 field: "telemetry event name", 153 maximumLength: 120 154 ) 155 let normalizedCategory = try RadrootsTelemetryValidation.normalizedIdentifier( 156 category, 157 field: "telemetry event category", 158 maximumLength: 80 159 ) 160 let normalizedMessage = try RadrootsTelemetryValidation.normalizedMessage(message) 161 guard RadrootsAppleTimeConversion.unixMilliseconds(occurredAt) != nil else { 162 throw RadrootsTelemetryError.invalidRequest 163 } 164 let duplicateFieldKeys = Set(fields.map(\.key)).count != fields.count 165 guard !duplicateFieldKeys else { 166 throw RadrootsTelemetryError.invalidRequest 167 } 168 self.name = normalizedName 169 self.category = normalizedCategory 170 self.level = level 171 self.message = normalizedMessage 172 self.fields = fields 173 self.occurredAt = occurredAt 174 } 175 176 fileprivate init( 177 validatedName: String, 178 validatedCategory: String, 179 level: RadrootsTelemetryLevel, 180 message: String?, 181 fields: [RadrootsTelemetryField], 182 occurredAt: Date 183 ) { 184 name = validatedName 185 category = validatedCategory 186 self.level = level 187 self.message = message 188 self.fields = fields 189 self.occurredAt = occurredAt 190 } 191 } 192 193 public struct RadrootsTelemetryRedactionPolicy: Sendable, Equatable, Hashable { 194 public let replacement: String 195 public let maximumStringLength: Int 196 197 public init( 198 replacement: String = "[redacted]", 199 maximumStringLength: Int = 160 200 ) { 201 let normalizedReplacement = replacement.trimmingCharacters(in: .whitespacesAndNewlines) 202 self.replacement = normalizedReplacement.isEmpty ? "[redacted]" : normalizedReplacement 203 self.maximumStringLength = max(32, maximumStringLength) 204 } 205 206 public static let `default` = RadrootsTelemetryRedactionPolicy() 207 208 public func redacted(_ event: RadrootsTelemetryEvent) -> RadrootsTelemetryEvent { 209 RadrootsTelemetryEvent( 210 validatedName: redactedIdentifier(event.name, fallback: "redacted"), 211 validatedCategory: redactedIdentifier(event.category, fallback: "redacted"), 212 level: event.level, 213 message: event.message.map { redactedString($0, key: "message") }, 214 fields: event.fields.map { $0.redacted(policy: self) }, 215 occurredAt: event.occurredAt 216 ) 217 } 218 219 public func redactedString(_ value: String, key: String? = nil) -> String { 220 if let key, shouldRedactKey(key) { 221 return replacement 222 } 223 let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines) 224 guard !trimmed.isEmpty else { 225 return trimmed 226 } 227 guard !containsUnsafeValue(trimmed) else { 228 return replacement 229 } 230 guard trimmed.count > maximumStringLength else { 231 return trimmed 232 } 233 return String(trimmed.prefix(maximumStringLength)) 234 } 235 236 public func shouldRedactKey(_ key: String) -> Bool { 237 let normalized = key.lowercased() 238 let unsafeFragments = [ 239 "absolute_path", 240 "body", 241 "content", 242 "document", 243 "file_name", 244 "filename", 245 "keychain", 246 "nsec", 247 "password", 248 "path", 249 "private", 250 "secret", 251 "selected_secret", 252 "text", 253 "token", 254 ] 255 return unsafeFragments.contains { normalized.contains($0) } 256 } 257 258 public func containsUnsafeValue(_ value: String) -> Bool { 259 let normalized = value.lowercased() 260 if normalized.contains("nsec") { 261 return true 262 } 263 let unsafePathFragments = [ 264 "/users/", 265 "/private/var/", 266 "/var/mobile/containers/", 267 "/var/folders/", 268 "file:///", 269 ] 270 if unsafePathFragments.contains(where: { normalized.contains($0) }) { 271 return true 272 } 273 return normalized.range(of: "[a-f0-9]{64}", options: .regularExpression) != nil 274 } 275 276 private func redactedIdentifier(_ value: String, fallback: String) -> String { 277 let redacted = redactedString(value) 278 return redacted == replacement ? fallback : redacted 279 } 280 } 281 282 public protocol RadrootsTelemetry: Sendable { 283 func record(_ event: RadrootsTelemetryEvent) async 284 } 285 286 public struct RadrootsNoopTelemetry: RadrootsTelemetry, Sendable { 287 public init() {} 288 289 public func record(_: RadrootsTelemetryEvent) async {} 290 } 291 292 public struct RadrootsRedactingTelemetry: RadrootsTelemetry, Sendable { 293 private let sink: any RadrootsTelemetry 294 private let policy: RadrootsTelemetryRedactionPolicy 295 296 public init( 297 sink: any RadrootsTelemetry, 298 policy: RadrootsTelemetryRedactionPolicy = .default 299 ) { 300 self.sink = sink 301 self.policy = policy 302 } 303 304 public func record(_ event: RadrootsTelemetryEvent) async { 305 await sink.record(policy.redacted(event)) 306 } 307 } 308 309 public struct RadrootsMultiplexTelemetry: RadrootsTelemetry, Sendable { 310 private let sinks: [any RadrootsTelemetry] 311 312 public init(_ sinks: [any RadrootsTelemetry]) { 313 self.sinks = sinks 314 } 315 316 public func record(_ event: RadrootsTelemetryEvent) async { 317 for sink in sinks { 318 await sink.record(event) 319 } 320 } 321 } 322 323 public enum RadrootsTelemetryValidation { 324 public static func normalizedIdentifier( 325 _ value: String, 326 field: String, 327 maximumLength: Int 328 ) throws -> String { 329 let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines) 330 guard !trimmed.isEmpty else { 331 throw RadrootsTelemetryError.invalidRequest 332 } 333 guard trimmed.count <= maximumLength else { 334 throw RadrootsTelemetryError.invalidRequest 335 } 336 guard 337 trimmed.range( 338 of: "^[a-z][a-z0-9._-]*$", 339 options: .regularExpression 340 ) != nil 341 else { 342 throw RadrootsTelemetryError.invalidRequest 343 } 344 return trimmed 345 } 346 347 public static func normalizedMessage(_ value: String?) throws -> String? { 348 guard let value else { 349 return nil 350 } 351 let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines) 352 guard !trimmed.isEmpty else { 353 return nil 354 } 355 guard doesNotContainControlCharacters(trimmed) else { 356 throw RadrootsTelemetryError.invalidRequest 357 } 358 guard trimmed.count <= 500 else { 359 throw RadrootsTelemetryError.invalidRequest 360 } 361 return trimmed 362 } 363 364 public static func validate(_ value: RadrootsTelemetryFieldValue) throws { 365 switch value { 366 case .string(let string): 367 try validateStringValue(string) 368 case .integer: 369 return 370 case .double(let double): 371 guard double.isFinite else { 372 throw RadrootsTelemetryError.invalidRequest 373 } 374 case .bool: 375 return 376 case .stringList(let values): 377 guard values.count <= 24 else { 378 throw RadrootsTelemetryError.invalidRequest 379 } 380 for value in values { 381 try validateStringValue(value) 382 } 383 } 384 } 385 386 private static func validateStringValue(_ value: String) throws { 387 guard doesNotContainControlCharacters(value) else { 388 throw RadrootsTelemetryError.invalidRequest 389 } 390 guard value.count <= 500 else { 391 throw RadrootsTelemetryError.invalidRequest 392 } 393 } 394 395 private static func doesNotContainControlCharacters(_ value: String) -> Bool { 396 value.unicodeScalars.allSatisfy { !CharacterSet.controlCharacters.contains($0) } 397 } 398 }