crossmate

DebuggingMonitors.swift (17997B)

---

 import CloudKit
 import Foundation
 import Observation
 import os
 
 struct PerformanceDiagnosticEntry: Identifiable, Sendable {
     let id = UUID()
     let timestamp: Date
     let name: String
     let durationMS: Double
     let detail: String
 }
 
 @MainActor
 @Observable
 final class PerformanceMonitor {
     private(set) var entries: [PerformanceDiagnosticEntry] = []
     private(set) var totalEvents = 0
     private(set) var suppressedEvents = 0
 
     private let maxEntries = 120
     private var nextRenderProbeID = 1
     private var pendingRenderProbes: [Int: RenderProbe] = [:]
     @ObservationIgnored private var viewBodyCounts: [String: Int] = [:]
     @ObservationIgnored private var viewBodyDetails: [String: String] = [:]
     @ObservationIgnored private var scheduledViewBodyReports: Set<String> = []
 
     private struct RenderProbe {
         let name: String
         let position: GridPosition
         let expectedEntry: String
         let startedAt: ContinuousClock.Instant
         let detail: String
     }
 
     func record(
         _ name: String,
         durationMS: Double,
         detail: String = "",
         thresholdMS: Double = 8
     ) {
         totalEvents += 1
         guard durationMS >= thresholdMS else {
             suppressedEvents += 1
             return
         }
         entries.append(PerformanceDiagnosticEntry(
             timestamp: Date(),
             name: name,
             durationMS: durationMS,
             detail: detail
         ))
         if entries.count > maxEntries {
             entries.removeFirst(entries.count - maxEntries)
         }
     }
 
     func note(_ name: String, detail: String = "") {
         entries.append(PerformanceDiagnosticEntry(
             timestamp: Date(),
             name: name,
             durationMS: 0,
             detail: detail
         ))
         if entries.count > maxEntries {
             entries.removeFirst(entries.count - maxEntries)
         }
     }
 
     func clear() {
         entries.removeAll()
         totalEvents = 0
         suppressedEvents = 0
         pendingRenderProbes.removeAll()
         viewBodyCounts.removeAll()
         viewBodyDetails.removeAll()
         scheduledViewBodyReports.removeAll()
     }
 
     func beginRenderProbe(
         name: String,
         position: GridPosition,
         expectedEntry: String,
         detail: String = ""
     ) -> Int {
         let id = nextRenderProbeID
         nextRenderProbeID += 1
         pendingRenderProbes[id] = RenderProbe(
             name: name,
             position: position,
             expectedEntry: expectedEntry,
             startedAt: .now,
             detail: detail
         )
         return id
     }
 
     func renderProbeDetailPrefix(for id: Int) -> String? {
         guard let probe = pendingRenderProbes[id] else { return nil }
         return "probe=\(id) row=\(probe.position.row) col=\(probe.position.col)"
     }
 
     func completeRenderProbe(id: Int, position: GridPosition, entry: String) {
         guard let probe = pendingRenderProbes[id],
               probe.position == position,
               probe.expectedEntry == entry
         else { return }
         pendingRenderProbes.removeValue(forKey: id)
         let duration = probe.startedAt.duration(to: .now)
         let milliseconds = Double(duration.components.seconds) * 1000
             + Double(duration.components.attoseconds) / 1_000_000_000_000_000
         let baseDetail = "probe=\(id) row=\(probe.position.row) col=\(probe.position.col)"
         let detail = probe.detail.isEmpty ? baseDetail : "\(baseDetail) \(probe.detail)"
         record(
             probe.name,
             durationMS: milliseconds,
             detail: detail,
             thresholdMS: 6
         )
     }
 
     func recordDeferred(
         _ name: String,
         start: ContinuousClock.Instant,
         detail: String = "",
         thresholdMS: Double = 8
     ) {
         let milliseconds = Self.milliseconds(from: start.duration(to: .now))
         guard milliseconds >= thresholdMS else { return }
         Task { @MainActor [weak self] in
             self?.record(
                 name,
                 durationMS: milliseconds,
                 detail: detail,
                 thresholdMS: thresholdMS
             )
         }
     }
 
     func markViewBodyDeferred(
         _ name: String,
         key: String = "",
         detail: String = ""
     ) {
         Task { @MainActor [weak self] in
             self?.markViewBody(name, key: key, detail: detail)
         }
     }
 
     private func markViewBody(_ name: String, key: String, detail: String) {
         let reportKey = key.isEmpty ? name : "\(name)|\(key)"
         viewBodyCounts[reportKey, default: 0] += 1
         viewBodyDetails[reportKey] = detail
 
         guard !scheduledViewBodyReports.contains(reportKey) else { return }
         scheduledViewBodyReports.insert(reportKey)
         Task { @MainActor [weak self] in
             try? await Task.sleep(for: .milliseconds(50))
             self?.flushViewBodyReport(name: name, reportKey: reportKey)
         }
     }
 
     private func flushViewBodyReport(name: String, reportKey: String) {
         scheduledViewBodyReports.remove(reportKey)
         let count = viewBodyCounts.removeValue(forKey: reportKey) ?? 0
         guard count > 0 else { return }
         let detail = viewBodyDetails.removeValue(forKey: reportKey) ?? ""
         let countDetail = detail.isEmpty ? "count=\(count)" : "count=\(count) \(detail)"
         note("\(name).body", detail: countDetail)
     }
 
     private static func milliseconds(from duration: Duration) -> Double {
         Double(duration.components.seconds) * 1000
             + Double(duration.components.attoseconds) / 1_000_000_000_000_000
     }
 }
 
 struct EventLogEntry: Identifiable, Sendable, Codable {
     var id = UUID()
     let timestamp: Date
     let level: String
     let message: String
 }
 
 /// Truncates identifiers before they land in the event log, so a shared
 /// diagnostics dump can't expose a complete game UUID, CloudKit user/device
 /// record name, or share-link token. The first eight characters survive —
 /// enough to correlate lines within one log (matching the existing
 /// `PlayerRoster[0A5207B4]` and truncated-APNs-token conventions) without
 /// reconstructing the real identifier.
 ///
 /// Main-actor-confined because `Regex` is not `Sendable`; both producers
 /// (`EventLog`, `SyncMonitor`) already live on the main actor.
 @MainActor
 enum LogScrubber {
     private static let uuid =
         /[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}/
     /// CloudKit user record names are `_` + 32 hex; device IDs inside ping
     /// record names are bare 32-hex. `{32,}` swallows anything longer (e.g. a
     /// full APNs token) in one match rather than leaving a usable tail.
     /// Sentinels like `__defaultOwner__` contain non-hex letters and pass
     /// through untouched.
     private static let hexToken = /_?[0-9A-Fa-f]{32,}/
     /// An iCloud share URL's path token is a bearer credential — anyone
     /// holding the full link can join the game — so only a stub survives.
     private static let shareURLToken = /(icloud\.com\/share\/)([A-Za-z0-9._~-]{9,})/
 
     static func scrub(_ message: String) -> String {
         var result = message
         result = result.replacing(uuid) { "\($0.output.prefix(8))…" }
         result = result.replacing(hexToken) { match in
             let keep = match.output.hasPrefix("_") ? 9 : 8
             return "\(match.output.prefix(keep))…"
         }
         result = result.replacing(shareURLToken) { "\($0.output.1)\($0.output.2.prefix(8))…" }
         return result
     }
 }
 
 /// Off-main durable backing for `EventLog`. Owns a single atomically-rewritten
 /// snapshot file in Application Support — chosen over Caches, which iOS can
 /// purge under storage pressure, exactly when a tester needs the log most.
 /// The file survives termination, so a collaborator can still share their
 /// diagnostics hours after the activity, long after their app was suspended.
 actor EventLogStore {
     private let fileURL: URL
 
     init(filename: String = "event-log.json") {
         let dir = FileManager.default
             .urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
         try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
         self.fileURL = dir.appendingPathComponent(filename)
     }
 
     func load() -> [EventLogEntry] {
         guard let data = try? Data(contentsOf: fileURL),
               let entries = try? JSONDecoder().decode([EventLogEntry].self, from: data)
         else { return [] }
         return entries
     }
 
     /// Rewrites the file from the already-pruned in-memory snapshot. Called
     /// coalesced (debounced after a burst, and on backgrounding) rather than
     /// per-append, so the O(n) encode stays rare even during an intense
     /// ~5/sec co-solve.
     func persist(_ entries: [EventLogEntry]) {
         guard let data = try? JSONEncoder().encode(entries) else { return }
         try? data.write(to: fileURL, options: .atomic)
     }
 }
 
 /// Generic in-app event log. Anything that wants to leave a breadcrumb the
 /// user can read in the diagnostics screen calls `note(_:)`. SyncMonitor and
 /// other producers compose this — they don't subclass it.
 ///
 /// Backed by `EventLogStore` so the buffer outlives the process: `loadPersisted`
 /// hydrates the in-memory view on launch, and a debounced flush mirrors live
 /// breadcrumbs back to disk. That durability is what lets a quiet-overnight
 /// device still surface a collaborator's hours-old session the next morning.
 @MainActor
 @Observable
 final class EventLog {
     private(set) var entries: [EventLogEntry] = []
 
     /// How far back the log reaches. A time window — rather than a fixed entry
     /// count — guarantees the buffer always spans a known wall-clock duration
     /// regardless of how chatty the session is. During an intense co-solve the
     /// log churns at ~5 events/sec, so a count cap of a few thousand only holds
     /// a couple of minutes and evicts the start of the session before anyone
     /// can grab it. A day comfortably spans a collaborator's evening session
     /// plus a quiet night before someone collects the log in the morning, while
     /// staying cheap on an idle device (a quiet night writes a handful of rows).
     private let retention: TimeInterval = 60 * 60 * 24
 
     /// Hard ceiling so a runaway producer (e.g. a tight error-retry loop) can't
     /// grow the buffer without bound inside the retention window. Sized well
     /// above an hour of normal+intense traffic (~18k entries) so the time
     /// window stays the governing limit in practice; this only trips on a fault.
     private let maxEntries = 30_000
 
     private let store: EventLogStore
 
     /// Mirror of every breadcrumb into the unified system log. The file-backed
     /// buffer remains the system of record for TestFlight shares; this mirror
     /// adds live streaming in Xcode/Console.app on tethered runs, capture in
     /// sysdiagnoses, and crash resilience — a hard crash loses up to 2s of
     /// tail to the debounced file flush, but the system log keeps it.
     /// Interpolation is `.public` because these messages are already exposed
     /// verbatim through the diagnostics share sheet.
     @ObservationIgnored private let systemLog = Logger(
         subsystem: Bundle.main.bundleIdentifier ?? "Crossmate",
         category: "events"
     )
 
     /// Until the on-disk history has been merged in, appends must not flush:
     /// a flush before `loadPersisted` would clobber the file with a partial,
     /// pre-hydration snapshot and lose the very overnight history we're after.
     private var hydrated = false
     private var flushTask: Task<Void, Never>?
 
     init(store: EventLogStore = EventLogStore()) {
         self.store = store
     }
 
     /// Merges the persisted history into the in-memory view. Call once, early
     /// in launch. Any breadcrumbs noted before hydration are kept and ordered
     /// in by timestamp, so nothing recorded during startup is lost.
     func loadPersisted() async {
         let persisted = await store.load()
         entries = (persisted + entries).sorted { $0.timestamp < $1.timestamp }
         prune(now: Date())
         hydrated = true
         scheduleFlush()
     }
 
     func note(_ message: String, level: String = "info") {
         append(level: level, message)
     }
 
     fileprivate func append(level: String, _ message: String) {
         let message = LogScrubber.scrub(message)
         switch level {
         case "error":
             systemLog.error("\(message, privacy: .public)")
         case "warn":
             systemLog.warning("\(message, privacy: .public)")
         default:
             systemLog.info("\(message, privacy: .public)")
         }
         let now = Date()
         entries.append(EventLogEntry(timestamp: now, level: level, message: message))
         prune(now: now)
         scheduleFlush()
     }
 
     /// Coalesce writes: one persist a couple of seconds after the last append,
     /// not one per breadcrumb. A fresh append cancels the pending write and
     /// re-arms it, so a steady burst collapses into a single trailing flush.
     private func scheduleFlush() {
         guard hydrated else { return }
         flushTask?.cancel()
         flushTask = Task { [weak self] in
             try? await Task.sleep(for: .seconds(2))
             guard !Task.isCancelled, let self else { return }
             await self.store.persist(self.entries)
         }
     }
 
     /// Persist immediately, bypassing the debounce. Call on backgrounding so an
     /// imminent suspend keeps the tail that the timer hasn't written yet.
     func flush() async {
         guard hydrated else { return }
         flushTask?.cancel()
         await store.persist(entries)
     }
 
     /// Drops entries older than the retention window, then enforces the count
     /// ceiling. Entries are appended in timestamp order, so the expired ones are
     /// always a prefix — `firstIndex` stops at the first fresh entry, making the
     /// scan proportional to how many just aged out (typically zero or one per
     /// append), not to the buffer size. The entry just appended carries `now`,
     /// so at least one entry always survives the cutoff.
     private func prune(now: Date) {
         let cutoff = now.addingTimeInterval(-retention)
         if let firstFresh = entries.firstIndex(where: { $0.timestamp >= cutoff }), firstFresh > 0 {
             entries.removeFirst(firstFresh)
         }
         if entries.count > maxEntries {
             entries.removeFirst(entries.count - maxEntries)
         }
     }
 }
 
 @MainActor
 @Observable
 final class SyncMonitor {
     private(set) var lastSuccessAt: Date?
     private(set) var lastErrorPhase: String?
     private(set) var lastErrorDomain: String?
     private(set) var lastErrorCode: Int?
     private(set) var lastErrorDescription: String?
     private(set) var snapshot: SyncEngine.DiagnosticSnapshot?
 
     private let log: EventLog
 
     init(log: EventLog) {
         self.log = log
     }
 
     func recordStart(_ phase: String) {
         log.append(level: "info", "starting \(phase)")
     }
 
     func recordSuccess(_ phase: String) {
         lastSuccessAt = Date()
         // Once the phase that last errored runs to completion, the stored
         // error is stale — the engine has recovered. Clear it so the
         // diagnostics panel reflects current health instead of pinning to
         // a transient failure (e.g. an OpLock that retried successfully).
         if lastErrorPhase == phase {
             clearLastError()
         }
         log.append(level: "info", "\(phase) succeeded")
     }
 
     func recordError(_ phase: String, _ error: Error) {
         let nsError = error as NSError
         lastErrorPhase = phase
         lastErrorDomain = nsError.domain
         lastErrorCode = nsError.code
         // Scrub at storage, not display: this string surfaces both in the
         // diagnostics view and in the shared dump's header, and CloudKit
         // error text can embed full record and zone names.
         lastErrorDescription = LogScrubber.scrub(nsError.localizedDescription)
         let userInfoSummary = nsError.userInfo
             .map { "\($0.key)=\($0.value)" }
             .joined(separator: " | ")
         let message = "\(phase) failed: domain=\(nsError.domain) code=\(nsError.code) \(nsError.localizedDescription) | userInfo: \(userInfoSummary)"
         log.append(level: "error", message)
     }
 
     func note(_ message: String) {
         log.note(message)
     }
 
     /// Bumps `lastSuccessAt` without writing a `succeeded` log line. Used by
     /// the CKSyncEngine delegate handlers so that auto-drained sends and
     /// framework-initiated fetches — which never go through `run(_:_:)` —
     /// still count as "the engine is alive and round-tripping with the
     /// server". Without this the timestamp pins to whichever instrumented
     /// phase last ran and silently lies about engine health when only
     /// auto-drain activity is happening.
     func noteSuccess() {
         lastSuccessAt = Date()
         clearLastError()
     }
 
     func updateSnapshot(_ snapshot: SyncEngine.DiagnosticSnapshot) {
         self.snapshot = snapshot
     }
 
     func clearLastError() {
         lastErrorPhase = nil
         lastErrorDomain = nil
         lastErrorCode = nil
         lastErrorDescription = nil
     }
 
     func run(_ phase: String, _ body: @Sendable () async throws -> Void) async {
         recordStart(phase)
         do {
             try await body()
             recordSuccess(phase)
         } catch {
             recordError(phase, error)
         }
     }
 
     func run<T: Sendable>(_ phase: String, _ body: @Sendable () async throws -> T) async -> T? {
         recordStart(phase)
         do {
             let result = try await body()
             recordSuccess(phase)
             return result
         } catch {
             recordError(phase, error)
             return nil
         }
     }
 }