crossmate

MoveBuffer.swift (10825B)

---

 import CoreData
 import Foundation
 
 /// In-memory staging area for cell edits. Collapses rapid same-cell edits
 /// down to one move, assigns lamports at flush time from the game's
 /// `lamportHighWater`, writes `MoveEntity` rows, and updates the local
 /// `CellEntity` cache in a single background transaction. Flushed moves are
 /// handed to an injected sink — wired to `CKSyncEngine` in production,
 /// stubbed in tests.
 ///
 /// Flush triggers:
 /// - trailing-edge debounce (the user has stopped typing);
 /// - cell change (focus moves to a different cell, so the previous cell's
 ///   final value gets a lamport before new edits start accumulating);
 /// - explicit `flush()` (app background, game completion, tests).
 actor MoveBuffer {
     private struct Key: Hashable {
         let gameID: UUID
         let row: Int
         let col: Int
     }
 
     private struct Pending {
         var letter: String
         var markKind: Int16
         var checkedWrong: Bool
         var authorID: String?
         var enqueuedAt: Date
     }
 
     private let debounceInterval: Duration
     private let sessionPingStaleInterval: TimeInterval
     private let persistence: PersistenceController
     private let sink: @Sendable ([Move]) async -> Void
     private let afterFlush: (@Sendable (Set<UUID>) async -> Void)?
     private let sessionPingSink: (@Sendable (UUID, String) async -> Void)?
 
     private var buffer: [Key: Pending] = [:]
     /// Insertion order so that lamports within a single flush are assigned
     /// in the order edits were made rather than whatever the dictionary
     /// happens to iterate.
     private var order: [Key] = []
     /// The cell most recently enqueued. A subsequent enqueue targeting a
     /// different cell flushes first; subsequent enqueues for the same cell
     /// replace the pending value without flushing.
     private var lastCell: Key?
     private var debounceTask: Task<Void, Never>?
     /// Per-game timestamp of the last session ping fired. The first
     /// `enqueue` for a game with no entry — or one stale beyond
     /// `sessionPingStaleInterval` — counts as a new session and fires a ping.
     private var lastSessionPingAt: [UUID: Date] = [:]
 
     init(
         debounceInterval: Duration = .milliseconds(1500),
         sessionPingStaleInterval: TimeInterval = 20 * 60,
         persistence: PersistenceController,
         sink: @escaping @Sendable ([Move]) async -> Void,
         afterFlush: (@Sendable (Set<UUID>) async -> Void)? = nil,
         sessionPingSink: (@Sendable (UUID, String) async -> Void)? = nil
     ) {
         self.debounceInterval = debounceInterval
         self.sessionPingStaleInterval = sessionPingStaleInterval
         self.persistence = persistence
         self.sink = sink
         self.afterFlush = afterFlush
         self.sessionPingSink = sessionPingSink
     }
 
     /// Registers a cell edit. If the edit targets a different cell than the
     /// previous enqueue, the previous cell is flushed first so the resulting
     /// lamport order matches the user's editing order.
     ///
     /// `authorID` is the cell-effective author that gets persisted on the
     /// `MoveEntity` and `CellEntity`. `actingAuthorID` is the user who
     /// performed the action — usually the same value, but a same-letter
     /// rewrite or a reveal-of-correct preserves the cell's original author
     /// while the acting user is the typist. Session pings fire on the acting
     /// user so presence reflects who is actually live in the game.
     func enqueue(
         gameID: UUID,
         row: Int,
         col: Int,
         letter: String,
         markKind: Int16,
         checkedWrong: Bool,
         authorID: String?,
         actingAuthorID: String? = nil
     ) async {
         let key = Key(gameID: gameID, row: row, col: col)
 
         if let lastCell, lastCell != key {
             await performFlush()
         }
 
         if buffer[key] == nil {
             order.append(key)
         }
         buffer[key] = Pending(
             letter: letter,
             markKind: markKind,
             checkedWrong: checkedWrong,
             authorID: authorID,
             enqueuedAt: Date()
         )
         lastCell = key
         scheduleDebounce()
 
         let pingAuthorID = actingAuthorID ?? authorID
         if let pingAuthorID, !pingAuthorID.isEmpty {
             await maybeFireSessionPing(gameID: gameID, authorID: pingAuthorID)
         }
     }
 
     /// Resets session-ping tracking for `gameID`. Called from the puzzle
     /// view's teardown so re-entry counts as a fresh session.
     func noteSessionEnded(gameID: UUID) {
         lastSessionPingAt.removeValue(forKey: gameID)
     }
 
     private func maybeFireSessionPing(gameID: UUID, authorID: String) async {
         let now = Date()
         if let last = lastSessionPingAt[gameID],
            now.timeIntervalSince(last) < sessionPingStaleInterval {
             return
         }
         lastSessionPingAt[gameID] = now
         if let sessionPingSink {
             await sessionPingSink(gameID, authorID)
         }
     }
 
     /// Flushes any pending edits immediately and cancels the debounce. Safe
     /// to call when the buffer is empty.
     func flush() async {
         debounceTask?.cancel()
         debounceTask = nil
         await performFlush()
     }
 
     private func scheduleDebounce() {
         debounceTask?.cancel()
         let interval = debounceInterval
         debounceTask = Task { [weak self] in
             try? await Task.sleep(for: interval)
             if Task.isCancelled { return }
             await self?.debouncedFlush()
         }
     }
 
     private func debouncedFlush() async {
         debounceTask = nil
         await performFlush()
     }
 
     private func performFlush() async {
         guard !buffer.isEmpty else { return }
 
         let snapshot = buffer
         let snapshotOrder = order
         buffer.removeAll(keepingCapacity: true)
         order.removeAll(keepingCapacity: true)
         lastCell = nil
 
         let moves = persistAndAssignLamports(
             snapshot: snapshot,
             order: snapshotOrder
         )
         guard !moves.isEmpty else { return }
         await sink(moves)
         if let afterFlush {
             await afterFlush(Set(moves.map { $0.gameID }))
         }
     }
 
     /// Allocates lamports from each game's `lamportHighWater`, writes
     /// `MoveEntity` rows, and bumps the high-water — all inside a single
     /// background-context transaction so a crash can't leave the high-water
     /// out of sync with the written moves.
     private func persistAndAssignLamports(
         snapshot: [Key: Pending],
         order: [Key]
     ) -> [Move] {
         let context = persistence.container.newBackgroundContext()
         return context.performAndWait {
             var moves: [Move] = []
             var gamesByID: [UUID: GameEntity] = [:]
             var cellsByGameID: [UUID: [GridPosition: CellEntity]] = [:]
 
             for key in order {
                 guard let pending = snapshot[key] else { continue }
 
                 let game: GameEntity
                 if let cached = gamesByID[key.gameID] {
                     game = cached
                 } else {
                     let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
                     request.predicate = NSPredicate(format: "id == %@", key.gameID as CVarArg)
                     request.fetchLimit = 1
                     guard let found = try? context.fetch(request).first else { continue }
                     gamesByID[key.gameID] = found
                     game = found
                 }
                 if cellsByGameID[key.gameID] == nil {
                     cellsByGameID[key.gameID] = Self.cellCacheMap(for: game)
                 }
 
                 let lamport = game.lamportHighWater + 1
                 game.lamportHighWater = lamport
                 if game.updatedAt.map({ $0 < pending.enqueuedAt }) ?? true {
                     game.updatedAt = pending.enqueuedAt
                 }
 
                 let entity = MoveEntity(context: context)
                 entity.game = game
                 entity.lamport = lamport
                 entity.row = Int16(key.row)
                 entity.col = Int16(key.col)
                 entity.letter = pending.letter
                 entity.markKind = pending.markKind
                 entity.checkedWrong = pending.checkedWrong
                 entity.authorID = pending.authorID
                 entity.createdAt = pending.enqueuedAt
                 entity.ckRecordName = RecordSerializer.recordName(
                     forMoveInGame: key.gameID,
                     lamport: lamport
                 )
 
                 Self.updateCellCache(
                     for: game,
                     key: key,
                     pending: pending,
                     cells: &cellsByGameID[key.gameID, default: [:]],
                     in: context
                 )
 
                 moves.append(Move(
                     gameID: key.gameID,
                     lamport: lamport,
                     row: key.row,
                     col: key.col,
                     letter: pending.letter,
                     markKind: pending.markKind,
                     checkedWrong: pending.checkedWrong,
                     authorID: pending.authorID,
                     createdAt: pending.enqueuedAt
                 ))
             }
 
             if context.hasChanges {
                 do {
                     try context.save()
                 } catch {
                     print("MoveBuffer: failed to save context: \(error)")
                 }
             }
             return moves
         }
     }
 
     private nonisolated static func cellCacheMap(for game: GameEntity) -> [GridPosition: CellEntity] {
         let cellEntities = (game.cells as? Set<CellEntity>) ?? []
         var cells: [GridPosition: CellEntity] = [:]
         cells.reserveCapacity(cellEntities.count)
         for cell in cellEntities {
             cells[GridPosition(row: Int(cell.row), col: Int(cell.col))] = cell
         }
         return cells
     }
 
     private nonisolated static func updateCellCache(
         for game: GameEntity,
         key: Key,
         pending: Pending,
         cells: inout [GridPosition: CellEntity],
         in context: NSManagedObjectContext
     ) {
         let position = GridPosition(row: key.row, col: key.col)
         let cell: CellEntity
         if let existing = cells[position] {
             cell = existing
         } else {
             cell = CellEntity(context: context)
             cell.game = game
             cell.row = Int16(key.row)
             cell.col = Int16(key.col)
             cells[position] = cell
         }
         cell.letter = pending.letter
         cell.markKind = pending.markKind
         cell.checkedWrong = pending.checkedWrong
         cell.letterAuthorID = pending.authorID
     }
 }