@tokamakdev/plugin-location 0.1.0-beta.101 → 0.1.0-beta.103

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,34 @@ 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()
+  }
+
+  func locationManager(_ manager: CLLocationManager, didVisit visit: CLVisit) {
+    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 +269,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 +291,7 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     switch status {
     case .authorizedAlways, .authorizedWhenInUse:
       if !watchers.isEmpty {
-        updates.startUpdatingLocation()
+        watching.startUpdatingLocation()
       }
       locate()
     case .denied, .restricted:
@@ -157,7 +308,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 +336,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 +348,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)
   }
 }

package/apple/LocationRegions.swift

@@ -0,0 +1,154 @@
+import CoreLocation
+import Foundation
+
+#if os(iOS)
+  import UIKit
+#endif
+
+/// The JSON of each monitored region, as `addRegion` received it, by id.
+private let regionsKey = "tokamak.location.regions"
+/// `CLMonitor` monitors at most 20 conditions for an app, and reports no
+/// error beyond them.
+private let regionLimit = 20
+/// The monitor's name, which must be alphanumeric.
+private let monitorName = "TokamakLocation"
+
+/// Circular regions in one `CLMonitor`, which the plugin creates at launch
+/// and reads events from for the life of the process. The system launches the
+/// app for their events on iOS. Use it on the main thread.
+final class TokamakLocationRegions {
+  private let events: TokamakLocationEvents
+  private let defaults = UserDefaults.standard
+  private let monitor: Task<CLMonitor, Never>
+
+  init(events: TokamakLocationEvents) {
+    self.events = events
+    let monitor = Task { @MainActor in
+      await Self.protectedData()
+      return await CLMonitor(monitorName)
+    }
+    self.monitor = monitor
+    Task { @MainActor [weak self] in
+      do {
+        for try await event in await monitor.value.events {
+          self?.receive(event)
+        }
+      } catch {
+        self?.events.fail(
+          .locationUnavailable(error.localizedDescription))
+      }
+    }
+  }
+
+  /// The regions, by id.
+  private var regions: [String: [String: Any]] {
+    get {
+      defaults.data(forKey: regionsKey)
+        .flatMap { try? JSONSerialization.jsonObject(with: $0) as? [String: [String: Any]] } ?? [:]
+    }
+    set {
+      defaults.set(try? JSONSerialization.data(withJSONObject: newValue), forKey: regionsKey)
+    }
+  }
+
+  /// Monitors the region `region` describes, replacing one with the same id.
+  /// It starts outside, so a device already inside reports an entry, as on
+  /// Android.
+  func add(_ region: [String: Any]) async throws(TokamakPluginError) {
+    guard let id = region["id"] as? String, let radius = region["radius"] as? Double,
+      let latitude = region["latitude"] as? Double, let longitude = region["longitude"] as? Double
+    else {
+      throw TokamakPluginError(
+        name: "TypeError", message: "region must have an id, latitude, longitude and radius")
+    }
+    let monitor = await monitor.value
+    let monitored = await monitor.identifiers
+    guard monitored.count < regionLimit || monitored.contains(id) else {
+      throw TokamakPluginError(
+        name: "QuotaExceededError",
+        message: "The app monitors \(regionLimit) regions, the most the system allows")
+    }
+    let center = CLLocationCoordinate2D(latitude: latitude, longitude: longitude)
+    let condition = CLMonitor.CircularGeographicCondition(center: center, radius: radius)
+    regions[id] = region
+    await monitor.add(condition, identifier: id, assuming: .unsatisfied)
+  }
+
+  func remove(_ id: String) async {
+    regions[id] = nil
+    events.report([], region: id)
+    await monitor.value.remove(id)
+  }
+
+  /// The monitored regions, each with whether the device is inside it.
+  func all() async -> [[String: Any]] {
+    let monitor = await monitor.value
+    let regions = regions
+    var all: [[String: Any]] = []
+    for id in await monitor.identifiers {
+      guard var region = regions[id] else { continue }
+      region["state"] =
+        switch await monitor.record(for: id)?.lastEvent.state {
+        case .satisfied: "inside"
+        case .unsatisfied: "outside"
+        default: "unknown"
+        }
+      all.append(region)
+    }
+    return all
+  }
+
+  private func receive(_ event: CLMonitor.Event) {
+    let id = event.identifier
+    if #available(iOS 18, macOS 15, *) {
+      events.report(Self.problems(event), region: id)
+    }
+    guard let region = regions[id] else { return }
+    switch event.state {
+    case .satisfied where region["onEntry"] as? Bool != false:
+      events.transition(id, entered: true, at: event.date)
+    case .unsatisfied where region["onExit"] as? Bool != false:
+      events.transition(id, entered: false, at: event.date)
+    default:
+      break
+    }
+  }
+
+  /// The problems that stop monitoring the region, which `event` names.
+  @available(iOS 18, macOS 15, *)
+  private static func problems(_ event: CLMonitor.Event) -> [TokamakPluginError] {
+    let flags = [
+      (event.authorizationDenied, "NotAllowedError", "Location permission was denied"),
+      (event.authorizationDeniedGlobally, "NotAllowedError", "Location services are off"),
+      (event.authorizationRestricted, "NotAllowedError", "Location is restricted on this device"),
+      (
+        event.insufficientlyInUse, "NotAllowedError",
+        "Regions need the app in use, or Always permission"
+      ),
+      (event.accuracyLimited, "NotAllowedError", "Regions need precise location"),
+      (event.conditionUnsupported, "NotSupportedError", "The device cannot monitor the region"),
+      (
+        event.conditionLimitExceeded, "QuotaExceededError",
+        "The app monitors the most regions the system allows"
+      ),
+      (
+        event.persistenceUnavailable, "NotReadableError",
+        "Regions are unavailable until the device is first unlocked"
+      ),
+    ]
+    return flags.filter(\.0).map { TokamakPluginError(name: $0.1, message: $0.2) }
+  }
+
+  /// Returns once protected data is available, which `CLMonitor` needs.
+  @MainActor
+  private static func protectedData() async {
+    #if os(iOS)
+      guard !UIApplication.shared.isProtectedDataAvailable else { return }
+      let available = NotificationCenter.default.notifications(
+        named: UIApplication.protectedDataDidBecomeAvailableNotification)
+      for await _ in available {
+        return
+      }
+    #endif
+  }
+}