@tokamakdev/plugin-location 0.1.0-beta.102 → 0.1.0-beta.104

package/apple/LocationEvents.swift

@@ -0,0 +1,149 @@
+import CoreLocation
+import Foundation
+
+/// How long the Worker's listeners have for an event, within the few seconds
+/// the system gives an app it launches for one.
+private let eventDeadline: TimeInterval = 8
+
+/// The listener methods, which receive the Worker's events.
+private let listenerMethods: Set = [
+  "onLocationUpdate", "onRegionTransition", "onVisit", "onLocationError",
+]
+
+/// Delivers the plugin's events to the Worker's listeners and the page's. Use
+/// it on the main thread.
+final class TokamakLocationEvents {
+  private let host: TokamakHost
+  private var listeners: [String: [UUID: TokamakPluginReply]] = [:]
+  /// Positions that arrived while the Worker handled the previous update.
+  private var positions: [[String: Any]] = []
+  private var stationary: Bool?
+  private var updating = false
+  /// The messages of the problems last reported, by region id, or nil for
+  /// updates.
+  private var problems: [String?: Set<String>] = [:]
+
+  init(host: TokamakHost) {
+    self.host = host
+  }
+
+  /// Adds a page's or Worker's listener of `method`, returning its removal.
+  func listen(_ method: String, _ reply: @escaping TokamakPluginReply) -> (() -> Void)? {
+    guard listenerMethods.contains(method) else { return nil }
+    let key = UUID()
+    listeners[method, default: [:]][key] = reply
+    return { [weak self] in
+      self?.listeners[method]?.removeValue(forKey: key)
+    }
+  }
+
+  /// Delivers `location`, with Apple's `stationary` flag when the system
+  /// reports it. Positions that arrive while the Worker handles an update
+  /// reach it together as the next.
+  func update(_ location: CLLocation?, stationary: Bool? = nil) {
+    positions += location.map { [Self.position($0)] } ?? []
+    if let stationary {
+      self.stationary = stationary
+    }
+    if !updating {
+      sendUpdate()
+    }
+  }
+
+  private func sendUpdate() {
+    guard !positions.isEmpty || stationary == true else {
+      updating = false
+      return
+    }
+    var event: [String: Any] = ["positions": positions]
+    event["stationary"] = stationary
+    positions = []
+    stationary = nil
+    updating = true
+    send("onLocationUpdate", "update", event) { self.sendUpdate() }
+  }
+
+  func transition(_ id: String, entered: Bool, at date: Date) {
+    let event: [String: Any] = [
+      "id": id, "transition": entered ? "enter" : "exit", "timestamp": Self.milliseconds(date),
+    ]
+    send("onRegionTransition", "region", event)
+  }
+
+  func visit(_ visit: CLVisit) {
+    let event: [String: Any] = [
+      "latitude": visit.coordinate.latitude,
+      "longitude": visit.coordinate.longitude,
+      "accuracy": visit.horizontalAccuracy,
+      "arrival": visit.arrivalDate == .distantPast
+        ? NSNull() : Self.milliseconds(visit.arrivalDate),
+      "departure": visit.departureDate == .distantFuture
+        ? NSNull() : Self.milliseconds(visit.departureDate),
+    ]
+    send("onVisit", "visit", event)
+  }
+
+  /// Reports each of `problems` that updates, or the region `id`, did not
+  /// report last time.
+  func report(_ problems: [TokamakPluginError], region id: String? = nil) {
+    let previous = self.problems[id] ?? []
+    for problem in problems where !previous.contains(problem.message) {
+      fail(problem, region: id)
+    }
+    self.problems[id] = Set(problems.map(\.message))
+  }
+
+  /// Reports a background service's failure, which concerns the region `id`
+  /// when given.
+  func fail(_ error: TokamakPluginError, region id: String? = nil) {
+    var event: [String: Any] = ["name": error.name, "message": error.message]
+    event["id"] = id
+    send("onLocationError", "error", event)
+  }
+
+  private func send(
+    _ method: String, _ name: String, _ event: [String: Any], completion: @escaping () -> Void = {}
+  ) {
+    for reply in (listeners[method] ?? [:]).values {
+      reply(.success(event))
+    }
+    host.emit(name, event: event, timeout: eventDeadline) { result in
+      if case .failure(let error) = result {
+        print("location \(name) failed: \(error)")
+      }
+      completion()
+    }
+  }
+
+  /// `location` as the page's `Position`.
+  static func position(_ location: CLLocation) -> [String: Any] {
+    let coordinates = location.coordinate
+    return [
+      "coords": [
+        "latitude": coordinates.latitude,
+        "longitude": coordinates.longitude,
+        "accuracy": location.horizontalAccuracy,
+        "altitude": nullable(location.verticalAccuracy >= 0, location.altitude),
+        "altitudeAccuracy": nullable(location.verticalAccuracy >= 0, location.verticalAccuracy),
+        "heading": nullable(location.course >= 0, location.course),
+        "speed": nullable(location.speed >= 0, location.speed),
+      ],
+      "timestamp": milliseconds(location.timestamp),
+    ]
+  }
+
+  private static func nullable(_ available: Bool, _ value: Double) -> Any {
+    available ? value : NSNull()
+  }
+
+  private static func milliseconds(_ date: Date) -> Double {
+    date.timeIntervalSince1970 * 1000
+  }
+}
+
+extension TokamakPluginError {
+  /// Location could not be found, as `message` says.
+  static func locationUnavailable(_ message: String) -> Self {
+    Self(name: "NotReadableError", message: message)
+  }
+}

package/apple/LocationPlugin.swift

@@ -1,6 +1,19 @@
 import CoreLocation
 import Foundation
 
+#if os(iOS)
+  import UIKit
+#else
+  import AppKit
+#endif
+
+/// The JSON of the configuration `setup` last applied.
+private let setupKey = "tokamak.location.setup"
+/// Whether the plugin asked for Always permission, which iOS asks once.
+private let askedForAlwaysKey = "tokamak.location.askedForAlways"
+/// How long an authorization change may take to arrive after the app is active again.
+private let authorizationChangeDelay: TimeInterval = 1
+
 final class TokamakLocationPlugin: NSObject, TokamakPlugin,
   CLLocationManagerDelegate
 {
@@ -23,21 +36,62 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     var timer: DispatchWorkItem?
   }
 
+  /// A `requestPermission` waiting for the user to answer a prompt.
+  private struct Prompt {
+    /// The purpose key of the temporary precise location to ask for next.
+    let purpose: String?
+    let reply: TokamakPluginReply
+  }
+
   private let host: TokamakHost
-  /// Updates watchers.
-  private let updates = CLLocationManager()
+  private let defaults = UserDefaults.standard
+  /// Locates for watchers, and asks for permission.
+  private let watching = CLLocationManager()
   /// Takes single fixes for current position requests, apart from watching.
   private let fixes = CLLocationManager()
+  /// Delivers the significant changes and visits `setup` names.
+  private let monitoring = CLLocationManager()
   private var current: [UUID: Request] = [:]
   private var watchers: [UUID: TokamakPluginReply] = [:]
+  private var prompts: [UUID: Prompt] = [:]
+  /// The prompts waiting when the app resigned active, as a prompt showing
+  /// makes it.
+  private var shown: [UUID] = []
+  private let events: TokamakLocationEvents
+  private let updates: TokamakLocationUpdates
+  private let regions: TokamakLocationRegions
+  #if os(iOS)
+    /// The `CLServiceSession` iOS 18 needs for updates and regions to reach an
+    /// app that is not in use, held while the app has Always permission.
+    private var alwaysSession: AnyObject?
+  #endif
 
+  /// Resumes what ran when the app last ended, before launch finishes.
   init(host: TokamakHost) {
     self.host = host
+    events = TokamakLocationEvents(host: host)
+    updates = TokamakLocationUpdates(events: events)
+    regions = TokamakLocationRegions(events: events)
     super.init()
-    for manager in [updates, fixes] {
+    for manager in [watching, fixes] {
       manager.delegate = self
       manager.desiredAccuracy = kCLLocationAccuracyBest
     }
+    monitoring.delegate = self
+    if let stored = defaults.data(forKey: setupKey),
+      let config = try? JSONSerialization.jsonObject(with: stored) as? [String: Any]
+    {
+      apply(config)
+    }
+    #if os(iOS)
+      NotificationCenter.default.addObserver(
+        self, selector: #selector(willResignActive),
+        name: UIApplication.willResignActiveNotification, object: nil)
+      NotificationCenter.default.addObserver(
+        self, selector: #selector(didBecomeActive),
+        name: UIApplication.didBecomeActiveNotification, object: nil)
+    #endif
+    updates.resume()
   }
 
   func call(
@@ -45,17 +99,77 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     arguments: Any,
     reply: @escaping TokamakPluginReply
   ) {
-    guard method == "getCurrentPosition" else {
-      reply(.failure(.notSupported("\(id).\(method) is not supported")))
-      return
-    }
     let options = arguments as? [String: Any] ?? [:]
-    current[UUID()] = Request(
-      reply: reply,
-      maximumAge: (options["maximumAge"] as? Double ?? 0) / 1000,
-      timeout: (options["timeout"] as? Double ?? Double(UInt32.max)) / 1000
-    )
-    start()
+    do throws(TokamakPluginError) {
+      switch method {
+      case "setup":
+        if options["significantChanges"] as? Bool == true
+          && !CLLocationManager.significantLocationChangeMonitoringAvailable()
+        {
+          throw .notSupported("The device cannot monitor significant changes of location")
+        }
+        apply(options)
+        defaults.set(try? JSONSerialization.data(withJSONObject: options), forKey: setupKey)
+        reply(.success(nil))
+      case "getCurrentPosition":
+        current[UUID()] = Request(
+          reply: reply,
+          maximumAge: (options["maximumAge"] as? Double ?? 0) / 1000,
+          timeout: (options["timeout"] as? Double ?? Double(UInt32.max)) / 1000
+        )
+        start()
+      case "permission":
+        reply(.success(permission()))
+      case "requestPermission":
+        try requestPermission(options, reply)
+      case "servicesEnabled":
+        DispatchQueue.global(qos: .userInitiated).async {
+          reply(.success(CLLocationManager.locationServicesEnabled()))
+        }
+      case "openSettings":
+        try host.requireUI()
+        openSettings(reply)
+      case "startUpdates":
+        // A new background activity session starts only on screen.
+        try host.requireUI()
+        try requirePermission()
+        try updates.start(options)
+        reply(.success(nil))
+      case "stopUpdates":
+        updates.stop()
+        reply(.success(nil))
+      case "getUpdates":
+        reply(.success(updates.options))
+      case "addRegion":
+        try requirePermission()
+        guard watching.accuracyAuthorization == .fullAccuracy else {
+          throw TokamakPluginError(
+            name: "NotAllowedError", message: "Regions need precise location")
+        }
+        Task { @MainActor in
+          do throws(TokamakPluginError) {
+            try await regions.add(options)
+            reply(.success(nil))
+          } catch {
+            reply(.failure(error))
+          }
+        }
+      case "getRegions":
+        Task { @MainActor in reply(.success(await regions.all())) }
+      case "removeRegion":
+        guard let id = options["id"] as? String else {
+          throw TokamakPluginError(name: "TypeError", message: "id must be a string")
+        }
+        Task { @MainActor in
+          await regions.remove(id)
+          reply(.success(nil))
+        }
+      default:
+        throw .notSupported("\(id).\(method) is not supported")
+      }
+    } catch {
+      reply(.failure(error))
+    }
   }
 
   func subscribe(
@@ -63,6 +177,9 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     arguments: Any,
     reply: @escaping TokamakPluginReply
   ) throws(TokamakPluginError) -> (() -> Void) {
+    if let remove = events.listen(method, reply) {
+      return remove
+    }
     guard method == "watchPosition" else {
       throw .notSupported("\(id).\(method) is not supported")
     }
@@ -72,26 +189,38 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     return { [weak self] in
       self?.watchers.removeValue(forKey: subscription)
       if self?.watchers.isEmpty == true {
-        self?.updates.stopUpdatingLocation()
+        self?.watching.stopUpdatingLocation()
       }
     }
   }
 
   /// Also called when each manager is created, before anything asks for a
-  /// position. Both managers report the app's one authorization.
+  /// position. Every manager reports the app's one authorization, which
+  /// `watching`'s calls handle.
   func locationManagerDidChangeAuthorization(
     _ manager: CLLocationManager
   ) {
-    guard manager === updates, !current.isEmpty || !watchers.isEmpty else { return }
-    serve(manager.authorizationStatus)
+    guard manager === watching else { return }
+    holdAlwaysSession()
+    guard manager.authorizationStatus != .notDetermined else { return }
+    answer(Array(prompts.keys))
+    if !current.isEmpty || !watchers.isEmpty {
+      serve(manager.authorizationStatus)
+    }
   }
 
   func locationManager(
     _ manager: CLLocationManager,
     didUpdateLocations locations: [CLLocation]
   ) {
+    if manager === monitoring {
+      for location in locations {
+        events.update(location)
+      }
+      return
+    }
     guard let location = locations.last else { return }
-    deliver(.success(position(location)), from: manager)
+    deliver(.success(TokamakLocationEvents.position(location)), from: manager)
   }
 
   /// A fix that is not yet available is taken again; updates continue.
@@ -99,12 +228,37 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     _ manager: CLLocationManager,
     didFailWithError error: Error
   ) {
-    guard (error as NSError).code == CLError.Code.locationUnknown.rawValue else {
+    if (error as NSError).code == CLError.Code.locationUnknown.rawValue {
+      if manager === fixes && !current.isEmpty {
+        fixes.requestLocation()
+      }
+    } else if manager === monitoring {
+      events.fail(locationError(error))
+    } else {
       deliver(.failure(locationError(error)), from: manager)
-      return
     }
-    if manager === fixes && !current.isEmpty {
-      fixes.requestLocation()
+  }
+
+  /// Core Location delivers each visit to every manager's delegate.
+  func locationManager(_ manager: CLLocationManager, didVisit visit: CLVisit) {
+    if manager === monitoring {
+      events.visit(visit)
+    }
+  }
+
+  /// Starts the significant changes and visits `config` names, and stops the
+  /// others. After a launch for one of their events, starting them again
+  /// delivers it.
+  private func apply(_ config: [String: Any]) {
+    if config["significantChanges"] as? Bool == true {
+      monitoring.startMonitoringSignificantLocationChanges()
+    } else {
+      monitoring.stopMonitoringSignificantLocationChanges()
+    }
+    if config["visits"] as? Bool == true {
+      monitoring.startMonitoringVisits()
+    } else {
+      monitoring.stopMonitoringVisits()
     }
   }
 
@@ -118,17 +272,17 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
 
   private func start(servicesEnabled: Bool) {
     guard servicesEnabled else {
-      fail(unavailable("Location services are disabled"))
+      fail(.locationUnavailable("Location services are disabled"))
       return
     }
-    let status = updates.authorizationStatus
+    let status = watching.authorizationStatus
     guard status == .notDetermined else {
       serve(status)
       return
     }
     do throws(TokamakPluginError) {
       try host.requireUI()
-      updates.requestWhenInUseAuthorization()
+      watching.requestWhenInUseAuthorization()
     } catch {
       fail(error)
     }
@@ -140,7 +294,7 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     switch status {
     case .authorizedAlways, .authorizedWhenInUse:
       if !watchers.isEmpty {
-        updates.startUpdatingLocation()
+        watching.startUpdatingLocation()
       }
       locate()
     case .denied, .restricted:
@@ -157,7 +311,7 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
   private func locate() {
     for (key, request) in current where request.timer == nil {
       if let fix = fixes.location, -fix.timestamp.timeIntervalSinceNow <= request.maximumAge {
-        finish(key, .success(position(fix)))
+        finish(key, .success(TokamakLocationEvents.position(fix)))
         continue
       }
       let timer = DispatchWorkItem { [weak self] in self?.finish(key, .failure(Self.timedOut)) }
@@ -185,7 +339,7 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
 
   private func fail(_ error: TokamakPluginError) {
     deliver(.failure(error), from: fixes)
-    deliver(.failure(error), from: updates)
+    deliver(.failure(error), from: watching)
   }
 
   private func finish(_ key: UUID, _ result: Result<Any?, TokamakPluginError>) {
@@ -197,40 +351,180 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     }
   }
 
-  private func locationError(_ error: Error) -> TokamakPluginError {
-    if (error as NSError).code == CLError.Code.denied.rawValue {
-      return Self.permissionDenied
+  /// The app's in-use and background permission, and the precision it gets.
+  private func permission() -> [String: Any] {
+    let status = watching.authorizationStatus
+    return [
+      "inUse": Self.state(status),
+      "background": backgroundPermission(status),
+      "precision": watching.accuracyAuthorization == .reducedAccuracy ? "approximate" : "precise",
+    ]
+  }
+
+  private func backgroundPermission(_ status: CLAuthorizationStatus) -> String {
+    if status == .authorizedAlways { return "granted" }
+    let asks = status == .notDetermined ? Self.declaresAlways : canUpgradeToAlways(status)
+    return asks ? "prompt" : "denied"
+  }
+
+  /// Whether asking for Always shows a prompt: once, from When In Use, on iOS.
+  private func canUpgradeToAlways(_ status: CLAuthorizationStatus) -> Bool {
+    #if os(iOS)
+      status == .authorizedWhenInUse && Self.declaresAlways && !askedForAlways
+    #else
+      false
+    #endif
+  }
+
+  private var hasPermission: Bool {
+    ![.notDetermined, .denied, .restricted].contains(watching.authorizationStatus)
+  }
+
+  /// Throws `NotAllowedError` unless the app has location permission.
+  private func requirePermission() throws(TokamakPluginError) {
+    guard hasPermission else {
+      throw TokamakPluginError(
+        name: "NotAllowedError", message: "Location permission has not been granted")
     }
-    return unavailable(error.localizedDescription)
   }
 
-  private func unavailable(_ message: String) -> TokamakPluginError {
-    TokamakPluginError(name: "NotReadableError", message: message)
+  private func holdAlwaysSession() {
+    #if os(iOS)
+      guard #available(iOS 18, *) else { return }
+      let always = watching.authorizationStatus == .authorizedAlways
+      if always && alwaysSession == nil {
+        alwaysSession = CLServiceSession(authorization: .always)
+      } else if !always {
+        (alwaysSession as? CLServiceSession)?.invalidate()
+        alwaysSession = nil
+      }
+    #endif
   }
 
-  private func position(_ location: CLLocation) -> [String: Any] {
-    let coordinates = location.coordinate
-    return [
-      "coords": [
-        "latitude": coordinates.latitude,
-        "longitude": coordinates.longitude,
-        "accuracy": location.horizontalAccuracy,
-        "altitude": nullable(
-          location.verticalAccuracy >= 0,
-          location.altitude
-        ),
-        "altitudeAccuracy": nullable(
-          location.verticalAccuracy >= 0,
-          location.verticalAccuracy
-        ),
-        "heading": nullable(location.course >= 0, location.course),
-        "speed": nullable(location.speed >= 0, location.speed),
-      ],
-      "timestamp": location.timestamp.timeIntervalSince1970 * 1000,
-    ]
+  private static func state(_ status: CLAuthorizationStatus) -> String {
+    switch status {
+    case .notDetermined: "prompt"
+    case .denied, .restricted: "denied"
+    default: "granted"
+    }
+  }
+
+  /// Whether the Info.plist declares Always permission, as the `background`
+  /// build setting does on iOS and every macOS build does.
+  private static let declaresAlways =
+    Bundle.main.object(forInfoDictionaryKey: "NSLocationAlwaysAndWhenInUseUsageDescription") != nil
+
+  private var askedForAlways: Bool {
+    defaults.bool(forKey: askedForAlwaysKey)
   }
 
-  private func nullable(_ available: Bool, _ value: Double) -> Any {
-    available ? value : NSNull()
+  /// Asks for in-use permission while the user has not answered, or for
+  /// Always permission once from When In Use, then for temporary precise
+  /// location when `options` name a purpose.
+  private func requestPermission(
+    _ options: [String: Any], _ reply: @escaping TokamakPluginReply
+  ) throws(TokamakPluginError) {
+    let always = options["background"] as? Bool == true
+    if always && !Self.declaresAlways {
+      throw .notSupported(
+        "Background location needs the location plugin's background build setting")
+    }
+    let prompt = Prompt(purpose: try Self.purpose(options), reply: reply)
+    let status = watching.authorizationStatus
+    let upgrades = always && canUpgradeToAlways(status)
+    guard status == .notDetermined || upgrades else {
+      respond(to: prompt)
+      return
+    }
+    try host.requireUI()
+    prompts[UUID()] = prompt
+    if always {
+      defaults.set(true, forKey: askedForAlwaysKey)
+      watching.requestAlwaysAuthorization()
+    } else {
+      watching.requestWhenInUseAuthorization()
+    }
+  }
+
+  /// The purpose key of the temporary precise location `options` ask for.
+  private static func purpose(_ options: [String: Any]) throws(TokamakPluginError) -> String? {
+    guard options["precision"] as? String == "precise" else { return nil }
+    let purposes =
+      Bundle.main.object(forInfoDictionaryKey: "NSLocationTemporaryUsageDescriptionDictionary")
+      as? [String: Any]
+    guard let purpose = options["purpose"] as? String, purposes?[purpose] != nil else {
+      throw TokamakPluginError(
+        name: "TypeError",
+        message: "precise location needs a purpose from the accuracy-purposes build setting")
+    }
+    return purpose
+  }
+
+  #if os(iOS)
+    @objc private func willResignActive() {
+      shown = Array(prompts.keys)
+    }
+
+    /// Answers the prompts that were showing, as the system reports no change
+    /// when the user keeps When In Use.
+    @objc private func didBecomeActive() {
+      let answered = shown
+      shown = []
+      guard !answered.isEmpty else { return }
+      DispatchQueue.main.asyncAfter(deadline: .now() + authorizationChangeDelay) {
+        self.answer(answered)
+      }
+    }
+  #endif
+
+  /// Answers the prompts `keys` that still wait.
+  private func answer(_ keys: [UUID]) {
+    for key in keys {
+      if let prompt = prompts.removeValue(forKey: key) {
+        respond(to: prompt)
+      }
+    }
+  }
+
+  /// Replies to `prompt` with the app's permission, first asking for temporary
+  /// precise location for its purpose when the app has approximate location.
+  private func respond(to prompt: Prompt) {
+    guard let purpose = prompt.purpose, hasPermission,
+      watching.accuracyAuthorization == .reducedAccuracy
+    else {
+      prompt.reply(.success(permission()))
+      return
+    }
+    do throws(TokamakPluginError) {
+      try host.requireUI()
+    } catch {
+      prompt.reply(.failure(error))
+      return
+    }
+    watching.requestTemporaryFullAccuracyAuthorization(withPurposeKey: purpose) { _ in
+      DispatchQueue.main.async { prompt.reply(.success(self.permission())) }
+    }
+  }
+
+  /// Opens the app's page of the system settings on iOS, and Location Services on macOS.
+  private func openSettings(_ reply: @escaping TokamakPluginReply) {
+    let notOpened = TokamakPluginError(
+      name: "OperationError", message: "The location settings could not be opened")
+    #if os(iOS)
+      UIApplication.shared.open(URL(string: UIApplication.openSettingsURLString)!) { opened in
+        reply(opened ? .success(nil) : .failure(notOpened))
+      }
+    #else
+      let page = "com.apple.preference.security?Privacy_LocationServices"
+      let opened = URL(string: "x-apple.systempreferences:\(page)").map(NSWorkspace.shared.open)
+      reply(opened == true ? .success(nil) : .failure(notOpened))
+    #endif
+  }
+
+  private func locationError(_ error: Error) -> TokamakPluginError {
+    if (error as NSError).code == CLError.Code.denied.rawValue {
+      return Self.permissionDenied
+    }
+    return .locationUnavailable(error.localizedDescription)
   }
 }