apple_kit

Apple-native services for Radroots iOS and macOS apps
git clone https://radroots.dev/git/apple_kit.git
Log | Files | Refs | README | LICENSE

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 }