← All repositories

crossmate

A collaborative crossword app for iPhone and iPad

git clone https://code.inqk.net/crossmate.git


Crossmate/Sync/PlayerSelectionPublisher.swift (11534B)

1import CoreData
2import Foundation
3
4/// Debounced writer for the local player's cursor track. Updates the
5/// `PlayerEntity` row for `(gameID, authorID)` with the new `selRow`/`selCol`/
6/// `selDir` and asks the sync engine to push the Player record. Cursor-track
7/// edits don't go through `MovesUpdater` because they aren't cell edits — they
8/// live on `PlayerEntity` with last-writer-wins semantics.
9actor PlayerSelectionPublisher {
10    /// How long to wait before flushing the durable cursor write for `gameID`.
11    /// Injected (rather than a fixed `Duration`) so the caller can lengthen it
12    /// while an engagement room is live: the live websocket already carries the
13    /// cursor to the peer, so the durable PlayerEntity/CloudKit write is only a
14    /// post-disconnect fallback and can lag well behind. A longer interval there
15    /// cuts the bulk of the Player-record traffic during co-solving, while the
16    /// trailing flush still lands a resting position on each pause so the
17    /// fallback stays usable. Defaults to a flat 500 ms so tests and
18    /// non-collaborative contexts keep the prior single-interval behaviour.
19    /// `@MainActor` so the provider can read main-actor state (the engagement
20    /// liveness flag) directly; the `await` at the call site does the hop.
21    private let debounceInterval: @MainActor @Sendable (UUID) async -> Duration
22    private let persistence: PersistenceController
23    /// Pushes the local Player record. The `Bool` is `drain`: `true` forces an
24    /// immediate CKSyncEngine send (live cursor updates), `false` enqueues
25    /// durably and lets the engine ship on its own schedule — used by the
26    /// leave-path clear, which mustn't race the suspension budget.
27    private let sink: @Sendable (UUID, String, Bool) async -> Void
28    /// Returns `true` if any non-local peer currently has a fresh cursor track.
29    /// When the predicate returns `false` the publisher still writes the local
30    /// PlayerEntity row but skips the CloudKit enqueue — the cursor track is
31    /// presence data nobody is watching for. Defaults to "always present" so
32    /// callers that don't care about the gate (tests, contexts without peer
33    /// info) get the pre-gate behaviour.
34    private let peerPresent: @Sendable (UUID) async -> Bool
35    /// Sleep primitive used by the debounce timer. Injected so tests can
36    /// drive flushes deterministically instead of racing against wall-clock
37    /// `Task.sleep` from the actor's own task queue. Mirrors the pattern in
38    /// `MovesUpdater`.
39    private let sleep: @Sendable (Duration) async throws -> Void
40
41    private var pending: PlayerSelection?
42    private var lastPublished: PlayerSelection?
43    private var debounceTask: Task<Void, Never>?
44    private var gameID: UUID?
45    private var authorID: String?
46    /// The local user's display name at session start. Used as a fallback
47    /// when `write` has to insert a fresh `PlayerEntity` row before
48    /// `PlayerNamePublisher` has fanned out — without it the row would have no
49    /// name and the SyncEngine would refuse to build a CKRecord, dropping
50    /// the cursor on the floor.
51    private var fallbackName: String = ""
52
53    init(
54        debounceInterval: @escaping @MainActor @Sendable (UUID) async -> Duration = { _ in .milliseconds(500) },
55        persistence: PersistenceController,
56        sink: @escaping @Sendable (UUID, String, Bool) async -> Void,
57        peerPresent: @escaping @Sendable (UUID) async -> Bool = { _ in true },
58        sleep: @escaping @Sendable (Duration) async throws -> Void = { try await Task.sleep(for: $0) }
59    ) {
60        self.debounceInterval = debounceInterval
61        self.persistence = persistence
62        self.sink = sink
63        self.peerPresent = peerPresent
64        self.sleep = sleep
65    }
66
67    /// Starts publishing for a new puzzle session. Resets dedupe state so the
68    /// first selection from the new session always flushes. `currentName` is
69    /// the local user's display name at the time the puzzle was opened — used
70    /// only when no PlayerEntity row exists yet for this (game, author).
71    func begin(gameID: UUID, authorID: String, currentName: String) {
72        self.gameID = gameID
73        self.authorID = authorID
74        fallbackName = currentName
75        pending = nil
76        lastPublished = nil
77        debounceTask?.cancel()
78        debounceTask = nil
79    }
80
81    /// Registers a new cursor track. Coalesces with any prior pending value
82    /// and schedules a trailing-edge flush. Repeated identical tracks are
83    /// dropped.
84    func publish(_ selection: PlayerSelection) {
85        guard gameID != nil, authorID != nil else { return }
86        if pending == selection || (pending == nil && lastPublished == selection) {
87            return
88        }
89        pending = selection
90        scheduleDebounce()
91    }
92
93    /// Records a "no cursor track" — used on puzzle teardown so the peer's
94    /// overlay disappears promptly instead of waiting for staleness. Awaits
95    /// the flush so callers can sequence work that depends on the cleared
96    /// state being visible to the sink (and so tests don't have to race a
97    /// detached Task).
98    func clear() async {
99        guard gameID != nil, authorID != nil else { return }
100        pending = nil
101        debounceTask?.cancel()
102        debounceTask = nil
103        await flushClear()
104    }
105
106    /// Flushes any pending selection immediately and cancels the debounce.
107    func flush() async {
108        debounceTask?.cancel()
109        debounceTask = nil
110        await performFlush()
111    }
112
113    /// Publishes `selection` synchronously, skipping the trailing-edge
114    /// debounce and discarding any pending debounce. Used by the
115    /// puzzle-open path so the initial cursor track ships in the same
116    /// CKSyncEngine drain as the read cursor and name-open enqueues
117    /// instead of arriving ~500 ms later.
118    func publishImmediately(_ selection: PlayerSelection) async {
119        guard let gameID, let authorID else { return }
120        if selection == lastPublished { return }
121        debounceTask?.cancel()
122        debounceTask = nil
123        pending = nil
124        lastPublished = selection
125        await write(gameID: gameID, authorID: authorID, selection: selection)
126        await sink(gameID, authorID, true)
127    }
128
129    private func scheduleDebounce() {
130        debounceTask?.cancel()
131        guard let gameID else { return }
132        let resolveInterval = debounceInterval
133        let sleep = self.sleep
134        debounceTask = Task { [weak self] in
135            let interval = await resolveInterval(gameID)
136            if Task.isCancelled { return }
137            try? await sleep(interval)
138            if Task.isCancelled { return }
139            await self?.debouncedFlush()
140        }
141    }
142
143    private func debouncedFlush() async {
144        debounceTask = nil
145        await performFlush()
146    }
147
148    private func performFlush() async {
149        guard let gameID, let authorID, let selection = pending else { return }
150        if selection == lastPublished { return }
151        // Always keep the local PlayerEntity row in sync — that's the
152        // source of truth for the eventual outbound CKRecord, so the row
153        // must reflect the latest selection whether or not we're shipping
154        // it right now.
155        await write(gameID: gameID, authorID: authorID, selection: selection)
156        // If no peer is currently in the puzzle, hold the send. Keep
157        // `pending` set (and don't advance `lastPublished`) so that a peer
158        // joining later triggers a flush of the latest value.
159        if !(await peerPresent(gameID)) { return }
160        pending = nil
161        lastPublished = selection
162        await sink(gameID, authorID, true)
163    }
164
165    /// Called when peer-presence state may have changed (e.g. an inbound
166    /// Player record updated a peer's cursor track). Re-evaluates the gate
167    /// and ships any held `pending` selection. `gameIDs`, if provided, scopes
168    /// the call to player records in those games — a no-op if the active
169    /// session isn't one of them.
170    ///
171    /// Only resumes when no debounce is currently scheduled — i.e. the
172    /// pending selection is being held by the gate, not by the normal
173    /// trailing-edge debounce. Otherwise a co-solving partner whose own
174    /// cursor updates pre-empt every one of our debounce windows would
175    /// pressure us into one CloudKit write per partner-move instead of the
176    /// 500 ms-throttled cadence.
177    func peerPresenceMayHaveChanged(gameIDs: Set<UUID>? = nil) async {
178        guard let gameID, pending != nil, debounceTask == nil else { return }
179        if let gameIDs, !gameIDs.contains(gameID) { return }
180        await performFlush()
181    }
182
183    private func flushClear() async {
184        guard let gameID, let authorID else { return }
185        if lastPublished == nil { return }
186        lastPublished = nil
187        await write(gameID: gameID, authorID: authorID, selection: nil)
188        // Leave-path clear: enqueue durably but don't force a drain that would
189        // race the suspension budget. The peer's live overlay is already gone
190        // via the socket tear-down; this is the durable cleanup.
191        await sink(gameID, authorID, false)
192    }
193
194    private func write(
195        gameID: UUID,
196        authorID: String,
197        selection: PlayerSelection?
198    ) async {
199        let context = persistence.container.newBackgroundContext()
200        context.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
201        let now = Date()
202        let fallbackName = self.fallbackName
203        await context.perform {
204            let recordName = RecordSerializer.recordName(forPlayerInGame: gameID, authorID: authorID)
205            let req = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
206            req.predicate = NSPredicate(format: "ckRecordName == %@", recordName)
207            req.fetchLimit = 1
208            let entity: PlayerEntity
209            if let existing = try? context.fetch(req).first {
210                entity = existing
211                // Don't overwrite a name that PlayerNamePublisher has set; only
212                // backfill if it's missing or empty so the outgoing record is
213                // never `name=""`.
214                if (entity.name ?? "").isEmpty, !fallbackName.isEmpty {
215                    entity.name = fallbackName
216                }
217            } else {
218                let gameReq = NSFetchRequest<GameEntity>(entityName: "GameEntity")
219                gameReq.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
220                gameReq.fetchLimit = 1
221                guard let game = try? context.fetch(gameReq).first else { return }
222                entity = PlayerEntity(context: context)
223                entity.game = game
224                entity.ckRecordName = recordName
225                entity.authorID = authorID
226                if !fallbackName.isEmpty {
227                    entity.name = fallbackName
228                }
229            }
230            entity.updatedAt = now
231            if let selection {
232                entity.selRow = NSNumber(value: Int64(selection.row))
233                entity.selCol = NSNumber(value: Int64(selection.col))
234                entity.selDir = NSNumber(value: Int64(selection.direction.rawValue))
235            } else {
236                entity.selRow = nil
237                entity.selCol = nil
238                entity.selDir = nil
239            }
240            if context.hasChanges {
241                try? context.save()
242            }
243        }
244    }
245}