History replay improvements (#4342)

* vk-NAVIOS-841-history-replay: exposed PushRecoirdHistoryEvent publicly to allow history parser to show this event to users; modified ReplayLocationManager to be able to replay history events in chronological order, including listening to the events; added default history events listener to MapboxNavigationService that will also set route updates from history to router; breaking changes accepted; renamed PushRecordHistoryEvent to UserPushedHistoryEvent

Author: Udumft

.breakage-allowlist

@@ -1 +1,2 @@
-Func CarPlayManagerDelegate.carPlayManagerDidCancelPreview(_:) has been added as a protocol requirement
+Func CarPlayManagerDelegate.carPlayManagerDidCancelPreview(_:) has been added as a protocol requirement
+Constructor MapboxNavigationService.init(history:customRoutingProvider:credentials:eventsManagerType:routerType:customActivityType:) has been removed

Sources/MapboxCoreNavigation/HistoryEvent.swift

@@ -49,14 +49,21 @@ internal class StatusUpdateHistoryEvent: UnknownHistoryEvent {
     }
 }
 
-internal class PushRecordHistoryEvent: UnknownHistoryEvent {
-    let type: String
-    let properties: String
+/// History event being pushed by the user
+///
+/// Such events are created by calling `HistoryRecording.pushHistoryEvent(type:jsonData:)`.
+public struct UserPushedHistoryEvent: HistoryEvent {
+    public let timestamp: TimeInterval
+    /// The event type specified for this custom event.
+    public let type: String
+    /// The data value that contains a valid JSON attached to the event.
+    ///
+    /// This value was provided by user with `HistoryRecording.pushHistoryEvent` method's `dictionary` argument.
+    public let properties: String
 
     init(timestamp: TimeInterval, type: String, properties: String) {
         self.type = type
         self.properties = properties
-    
-        super.init(timestamp: timestamp)
+        self.timestamp = timestamp
     }
 }

Sources/MapboxCoreNavigation/HistoryReader.swift

@@ -21,6 +21,16 @@ public struct History {
             return ($0 as? LocationUpdateHistoryEvent)?.location
         }
     }
+    
+    func rawLocationsShiftedToPresent() -> [CLLocation] {
+        return self.rawLocations.enumerated().map { CLLocation(coordinate: $0.element.coordinate,
+                                                               altitude: $0.element.altitude,
+                                                               horizontalAccuracy: $0.element.horizontalAccuracy,
+                                                               verticalAccuracy: $0.element.verticalAccuracy,
+                                                               course: $0.element.course,
+                                                               speed: $0.element.speed,
+                                                               timestamp: Date() + TimeInterval($0.offset)) }
+    }
 }
 
 /// Provides event-by-event access to history files contents.
@@ -78,7 +88,7 @@ public struct HistoryReader: Sequence {
                                                 status: event.result)
             case .pushHistory:
                 guard let event = record.pushHistory else { break }
-                return PushRecordHistoryEvent(timestamp: timestamp,
+                return UserPushedHistoryEvent(timestamp: timestamp,
                                               type: event.type,
                                               properties: event.properties)
             @unknown default:

Sources/MapboxCoreNavigation/NavigationService.swift

@@ -476,13 +476,15 @@ public class MapboxNavigationService: NSObject, NavigationService {
      Intializes a new `NavigationService` for replaying a session from provided `History`.
 
      - parameter history: `History` object, containing initial route and location trace to be replayed.
+     - parameter customHistoryEventsListener: Custom `ReplayManagerHistoryEventsListener` which will be used to handle replay events. Default value (`nil`)  will also loop route assignment events to update the `Router`.
      - parameter customRoutingProvider: Custom `RoutingProvider`, used to create a route during refreshing or rerouting.
      - parameter credentials: Credentials to authorize additional data requests throughout the route.
      - parameter eventsManagerType: An optional events manager type to use while tracking the route.
      - parameter routerType: An optional router type to use for traversing the route.
      - returns `nil` if provided `historyFileDump` does not contain valid initial route.
      */
     public convenience init?(history: History,
+                             customHistoryEventsListener: ReplayManagerHistoryEventsListener? = nil,
                              customRoutingProvider: RoutingProvider? = nil,
                              credentials: Credentials,
                              eventsManagerType: NavigationEventsManager.Type? = nil,
@@ -491,13 +493,20 @@ public class MapboxNavigationService: NSObject, NavigationService {
         guard let routeResponse = history.initialRoute else {
             return nil
         }
+        
+        let replayLocationManager = ReplayLocationManager(history: history,
+                                                          listener: customHistoryEventsListener)
         self.init(indexedRouteResponse: routeResponse,
                   customRoutingProvider: customRoutingProvider,
                   credentials: credentials,
-                  locationSource: ReplayLocationManager(history: history),
+                  locationSource: replayLocationManager,
                   eventsManagerType: eventsManagerType,
                   routerType: routerType,
                   customActivityType: customActivityType)
+        
+        if customHistoryEventsListener == nil {
+            replayLocationManager.eventsListener = self
+        }
     }
 
     init(indexedRouteResponse: IndexedRouteResponse,
@@ -829,6 +838,17 @@ extension MapboxNavigationService {
     }
 }
 
+extension MapboxNavigationService: ReplayManagerHistoryEventsListener {
+    public func replyLocationManager(_ manager: ReplayLocationManager, published event: HistoryEvent) {
+        // handling `RouteAssignmentHistoryEvent` to replay route updates from user/reroutes/etc.
+        if let setRouteEvent = event as? RouteAssignmentHistoryEvent {
+            updateRoute(with: setRouteEvent.routeResponse,
+                        routeOptions: nil,
+                        completion: nil)
+        }
+    }
+}
+
 private extension Double {
     var dispatchInterval: DispatchTimeInterval {
         let milliseconds = self * 1000.0 //milliseconds per second

Sources/MapboxCoreNavigation/ReplayLocationManager.swift

@@ -22,9 +22,17 @@ open class ReplayLocationManager: NavigationLocationManager {
         didSet {
             currentIndex = 0
             verifyParameters()
+            self.events = locations.map { ReplayEvent(from: $0) }
         }
     }
 
+    private(set) var events: [ReplayEvent]
+    
+    /**
+     Events listener that will receive history events if replaying a `History`.
+     */
+    public weak var eventsListener: ReplayManagerHistoryEventsListener? = nil
+    
     /**
      `simulatesLocation` used to indicate whether the location manager is providing simulated locations.
      - seealso: `NavigationMapView.simulatesLocation`
@@ -64,12 +72,19 @@ open class ReplayLocationManager: NavigationLocationManager {
 
     public init(locations: [CLLocation]) {
         self.locations = locations.sorted { $0.timestamp < $1.timestamp }
+        self.events = locations.map { ReplayEvent(from: $0) }
         super.init()
         verifyParameters()
     }
 
     public convenience init(history: History) {
-        self.init(locations: history.rawLocations)
+        self.init(locations: history.rawLocationsShiftedToPresent())
+        self.events = history.events.map { ReplayEvent(from: $0) }
+    }
+    
+    public convenience init(history: History, listener: ReplayManagerHistoryEventsListener?) {
+        self.init(history: history)
+        self.eventsListener = listener
     }
 
     deinit {
@@ -90,11 +105,16 @@ open class ReplayLocationManager: NavigationLocationManager {
     @objc internal func tick() {
         guard let startDate = startDate else { return }
 
-        func sendTick(with location: CLLocation) {
-            synthesizedLocation = location
-            delegate?.locationManager?(self, didUpdateLocations: [location])
-            onTick?(currentIndex, location)
-            nextTickWorkItem?.cancel()
+        func sendTick(_ event: ReplayEvent) {
+            switch event.kind {
+            case .location(let location):
+                synthesizedLocation = location
+                delegate?.locationManager?(self, didUpdateLocations: [location])
+                onTick?(currentIndex, location)
+                nextTickWorkItem?.cancel()
+            case .historyEvent(let historyEvent):
+                eventsListener?.replyLocationManager(self, published: historyEvent)
+            }
         }
 
         func scheduleNextTick(afterDelay delay: TimeInterval) {
@@ -105,35 +125,36 @@ open class ReplayLocationManager: NavigationLocationManager {
             DispatchQueue.main.asyncAfter(deadline: .now() + delay, execute: nextTickWorkItem)
         }
 
-        guard locations.count > 1 else {
-            sendTick(with: locations[0])
+        guard events.count > 1 else {
+            sendTick(events[0])
+            
             let startFromBeginning = replayCompletionHandler?(self) ?? false
             if startFromBeginning {
-                advanceLocationsForNextLoop()
+                advanceEventsForNextLoop()
                 scheduleNextTick(afterDelay: 1 / speedMultiplier)
             }
             return
         }
 
-        let location = locations[currentIndex]
-        sendTick(with: location)
+        let event = events[currentIndex]
+        sendTick(event)
 
         var nextIndex = currentIndex + 1
-        if nextIndex == locations.count {
+        if nextIndex == events.count {
             let startFromBeginning = replayCompletionHandler?(self) ?? false
             if startFromBeginning {
-                advanceLocationsForNextLoop()
+                advanceEventsForNextLoop()
                 nextIndex = 0
             }
             else {
                 return
             }
         }
 
-        let nextLocation = locations[nextIndex]
-        let interval = nextLocation.timestamp.timeIntervalSince(location.timestamp) / TimeInterval(speedMultiplier)
+        let nextEvent = events[nextIndex]
+        let interval = nextEvent.date.timeIntervalSince(event.date) / TimeInterval(speedMultiplier)
         let intervalSinceStart = Date().timeIntervalSince(startDate)+interval
-        let actualInterval = nextLocation.timestamp.timeIntervalSince(locations.first!.timestamp)
+        let actualInterval = nextEvent.date.timeIntervalSince(events.first!.date)
         let diff = min(max(0, intervalSinceStart-actualInterval), 0.9) // Don't try to resync more than 0.9 seconds per location update
         let syncedInterval = interval-diff
 
@@ -145,19 +166,83 @@ open class ReplayLocationManager: NavigationLocationManager {
         precondition(!locations.isEmpty)
     }
 
-    /// Shift `locations` so that sent locations always have increasing timestamps, taking into account location deltas.
-    private func advanceLocationsForNextLoop() {
+    /// Shift `events` and  `locations` so that sent locations always have increasing timestamps, taking into account event deltas.
+    private func advanceEventsForNextLoop() {
         /// Previous location that is used to calculate deltas between locations.
-        var previousOldLocation: CLLocation = locations.last!
+        var previousOldLocation = events.last!
         /// Previous timestamp that is used to advance timestamps.
-        var previousNewLocationTimestamp = previousOldLocation.timestamp
+        var previousNewLocationTimestamp = previousOldLocation.date
 
-        for (idx, location) in locations.enumerated() {
-            let delta: TimeInterval = idx == 0 ? 1 : location.timestamp.timeIntervalSince(previousOldLocation.timestamp)
+        var advancedLocations: [CLLocation] = []
+        
+        for (idx, event) in events.enumerated() {
+            let delta: TimeInterval = idx == 0 ? 1 : event.date.timeIntervalSince(previousOldLocation.date)
             let newTimestamp = previousNewLocationTimestamp.addingTimeInterval(delta)
-            previousOldLocation = location
-            locations[idx] = location.shifted(to: newTimestamp)
+            previousOldLocation = event
+            let shiftedEvent = event.shifted(to: newTimestamp)
+            events[idx] = shiftedEvent
+            
+            if case let .location(location) = shiftedEvent.kind {
+                advancedLocations.append(location)
+            } else if case let .historyEvent(historyEvent) = shiftedEvent.kind,
+                let locationEvent = historyEvent as? LocationUpdateHistoryEvent {
+                advancedLocations.append(locationEvent.location)
+            }
+            
             previousNewLocationTimestamp = newTimestamp
         }
+        self.locations = advancedLocations
+    }
+}
+
+/**
+ `ReplayLocationManager`'s listener that will receive events feed when it is replaying a `History` data.
+ */
+public protocol ReplayManagerHistoryEventsListener: AnyObject {
+    func replyLocationManager(_ manager: ReplayLocationManager, published event: HistoryEvent)
+}
+
+
+struct ReplayEvent {
+    var date: Date
+    
+    enum Kind {
+        case location(CLLocation)
+        case historyEvent(HistoryEvent)
+    }
+    var kind: Kind
+    
+    func shifted(to date: Date) -> ReplayEvent {
+        switch kind {
+        case .location(let location):
+            return ReplayEvent(from: location.shifted(to: date))
+        case .historyEvent(let historyEvent):
+            switch historyEvent {
+            case let event as LocationUpdateHistoryEvent:
+                return ReplayEvent(from: LocationUpdateHistoryEvent(timestamp: date.timeIntervalSince1970,
+                                                                    location: event.location.shifted(to: date)))
+            case let event as RouteAssignmentHistoryEvent:
+                return ReplayEvent(from: RouteAssignmentHistoryEvent(timestamp: date.timeIntervalSince1970,
+                                                                     routeResponse: event.routeResponse))
+            case let event as UserPushedHistoryEvent:
+                return ReplayEvent(from: UserPushedHistoryEvent(timestamp: date.timeIntervalSince1970,
+                                                                type: event.type,
+                                                                properties: event.properties))
+            case is UnknownHistoryEvent:
+                fallthrough
+            default:
+                return ReplayEvent(from: UnknownHistoryEvent(timestamp: date.timeIntervalSince1970))
+            }
+        }
+    }
+    
+    init(from location: CLLocation) {
+        self.date = location.timestamp
+        self.kind = .location(location)
+    }
+    
+    init(from historyEvent: HistoryEvent) {
+        self.date = Date(timeIntervalSince1970: historyEvent.timestamp)
+        self.kind = .historyEvent(historyEvent)
     }
 }