@tokamakdev/plugin-location 0.1.0-beta.127 → 0.1.0-beta.129

package/apple/LocationPlugin.swift

@@ -18,19 +18,15 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
   CLLocationManagerDelegate
 {
   let id = "location"
+  let host: TokamakHost
 
-  private static let permissionDenied = TokamakPluginError(
-    name: "NotAllowedError",
-    message: "Location permission was denied"
-  )
   /// 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
+    let answer: CheckedContinuation<LocationPermission, Error>
   }
 
-  private let host: TokamakHost
   private let defaults = UserDefaults.standard
   /// Reports the app's authorization, and asks for permission.
   private let authorization = CLLocationManager()
@@ -59,7 +55,7 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     authorization.delegate = self
     monitoring.delegate = self
     if let stored = defaults.data(forKey: setupKey),
-      let config = try? JSONSerialization.jsonObject(with: stored) as? [String: Any]
+      let config = try? JSONDecoder().decode(SetupConfig.self, from: stored)
     {
       apply(config)
     }
@@ -74,87 +70,148 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     updates.resume()
   }
 
-  func call(
-    method: String,
-    arguments: Any,
-    reply: @escaping TokamakPluginReply
-  ) -> (() -> Void)? {
-    let options = arguments as? [String: Any] ?? [:]
-    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 "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 authorization.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")
+  /// Applies long-term location awareness, which the plugin applies again at each start.
+  func setup(_ config: SetupConfig) throws(TokamakPluginError) {
+    if config.significantChanges == true
+      && !CLLocationManager.significantLocationChangeMonitoringAvailable()
+    {
+      throw .notSupported("The device cannot monitor significant changes of location")
+    }
+    apply(config)
+    defaults.set(try? JSONEncoder().encode(config), forKey: setupKey)
+  }
+
+  /// Core Location's latest position when it is no older than `maximumAge`
+  /// milliseconds, or nil.
+  func recentPosition(maximumAge: Double) -> Position? {
+    guard let recent = authorization.location,
+      -recent.timestamp.timeIntervalSinceNow <= maximumAge / 1000
+    else { return nil }
+    return Position(recent)
+  }
+
+  /// A new fix, from a location manager that the call owns until it ends.
+  @MainActor
+  func currentPosition() async throws -> Position {
+    for try await position in TokamakLocationPositions.stream(watching: false) {
+      return position
+    }
+    throw CancellationError()
+  }
+
+  func watchPosition() -> AsyncThrowingStream<Position, Error> {
+    TokamakLocationPositions.stream(watching: true)
+  }
+
+  func permission() -> LocationPermission {
+    let status = authorization.authorizationStatus
+    return LocationPermission(
+      inUse: Self.state(status),
+      background: backgroundPermission(status),
+      precision: authorization.accuracyAuthorization == .reducedAccuracy ? .approximate : .precise
+    )
+  }
+
+  /// 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 `request` names a purpose.
+  @MainActor
+  func requestPermission(_ request: PermissionRequest?) async throws -> LocationPermission {
+    let always = request?.background == true
+    if always && !Self.declaresAlways {
+      throw TokamakPluginError.notSupported(
+        "Background location needs the location plugin's background build setting")
+    }
+    let purpose = try Self.purpose(request)
+    let status = authorization.authorizationStatus
+    guard status == .notDetermined || always && canUpgradeToAlways(status) else {
+      return try await respond(purpose: purpose)
+    }
+    try host.requireUI()
+    return try await withCheckedThrowingContinuation { answer in
+      prompts[UUID()] = Prompt(purpose: purpose, answer: answer)
+      if always {
+        defaults.set(true, forKey: askedForAlwaysKey)
+        authorization.requestAlwaysAuthorization()
+      } else {
+        authorization.requestWhenInUseAuthorization()
       }
-    } catch {
-      reply(.failure(error))
     }
-    return nil
   }
 
-  func subscribe(
-    method: String,
-    arguments: Any,
-    reply: @escaping TokamakPluginReply
-  ) throws(TokamakPluginError) -> (() -> Void) {
-    guard let remove = events.listen(method, reply) else {
-      throw .notSupported("\(id).\(method) is not supported")
+  /// Whether location services are on, which Core Location reports off the
+  /// main thread.
+  func servicesEnabled() async -> Bool {
+    CLLocationManager.locationServicesEnabled()
+  }
+
+  /// Opens the app's page of the system settings on iOS, and Location Services on macOS.
+  @MainActor
+  func openSettings() async throws {
+    try host.requireUI()
+    #if os(iOS)
+      let opened = await UIApplication.shared.open(
+        URL(string: UIApplication.openSettingsURLString)!)
+    #else
+      let page = "com.apple.preference.security?Privacy_LocationServices"
+      let opened =
+        URL(string: "x-apple.systempreferences:\(page)").map(NSWorkspace.shared.open) == true
+    #endif
+    guard opened else {
+      throw TokamakPluginError(
+        name: "OperationError", message: "The location settings could not be opened")
+    }
+  }
+
+  /// Starts continuous updates, which a new background activity session
+  /// allows only on screen.
+  func startUpdates(_ options: UpdateOptions?) throws(TokamakPluginError) {
+    try host.requireUI()
+    try requirePermission()
+    try updates.start(options ?? UpdateOptions(activity: nil))
+  }
+
+  func stopUpdates() {
+    updates.stop()
+  }
+
+  func getUpdates() -> UpdateOptions? {
+    updates.options
+  }
+
+  @MainActor
+  func addRegion(_ region: Region) async throws {
+    try requirePermission()
+    guard authorization.accuracyAuthorization == .fullAccuracy else {
+      throw TokamakPluginError(name: "NotAllowedError", message: "Regions need precise location")
     }
-    return remove
+    try await regions.add(region)
+  }
+
+  @MainActor
+  func getRegions() async -> [MonitoredRegion] {
+    await regions.all()
+  }
+
+  @MainActor
+  func removeRegion(_ id: String) async {
+    await regions.remove(id)
+  }
+
+  func onLocationUpdate() -> AsyncStream<LocationUpdate> {
+    events.updates.stream()
+  }
+
+  func onRegionTransition() -> AsyncStream<RegionTransition> {
+    events.transitions.stream()
+  }
+
+  func onVisit() -> AsyncStream<Visit> {
+    events.visits.stream()
+  }
+
+  func onLocationError() -> AsyncStream<LocationErrorEvent> {
+    events.errors.stream()
   }
 
   /// Also called when each manager is created. Every manager reports the
@@ -185,7 +242,7 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
   ) {
     guard manager === monitoring, (error as NSError).code != CLError.Code.locationUnknown.rawValue
     else { return }
-    events.fail(locationError(error))
+    events.fail(.location(error))
   }
 
   /// Core Location delivers each visit to every manager's delegate.
@@ -198,34 +255,23 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
   /// 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 {
+  private func apply(_ config: SetupConfig) {
+    if config.significantChanges == true {
       monitoring.startMonitoringSignificantLocationChanges()
     } else {
       monitoring.stopMonitoringSignificantLocationChanges()
     }
-    if config["visits"] as? Bool == true {
+    if config.visits == true {
       monitoring.startMonitoringVisits()
     } else {
       monitoring.stopMonitoringVisits()
     }
   }
 
-  /// The app's in-use and background permission, and the precision it gets.
-  private func permission() -> [String: Any] {
-    let status = authorization.authorizationStatus
-    return [
-      "inUse": Self.state(status),
-      "background": backgroundPermission(status),
-      "precision": authorization.accuracyAuthorization == .reducedAccuracy
-        ? "approximate" : "precise",
-    ]
-  }
-
-  private func backgroundPermission(_ status: CLAuthorizationStatus) -> String {
-    if status == .authorizedAlways { return "granted" }
+  private func backgroundPermission(_ status: CLAuthorizationStatus) -> Permission {
+    if status == .authorizedAlways { return .granted }
     let asks = status == .notDetermined ? Self.declaresAlways : canUpgradeToAlways(status)
-    return asks ? "prompt" : "denied"
+    return asks ? .prompt : .denied
   }
 
   /// Whether asking for Always shows a prompt: once, from When In Use, on iOS.
@@ -262,11 +308,11 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     #endif
   }
 
-  private static func state(_ status: CLAuthorizationStatus) -> String {
+  private static func state(_ status: CLAuthorizationStatus) -> Permission {
     switch status {
-    case .notDetermined: "prompt"
-    case .denied, .restricted: "denied"
-    default: "granted"
+    case .notDetermined: .prompt
+    case .denied, .restricted: .denied
+    default: .granted
     }
   }
 
@@ -279,41 +325,13 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     defaults.bool(forKey: askedForAlwaysKey)
   }
 
-  /// 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 = authorization.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)
-      authorization.requestAlwaysAuthorization()
-    } else {
-      authorization.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 }
+  /// The purpose key of the temporary precise location `request` asks for.
+  private static func purpose(_ request: PermissionRequest?) throws(TokamakPluginError) -> String? {
+    guard request?.precision == .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 {
+    guard let purpose = request?.purpose, purposes?[purpose] != nil else {
       throw TokamakPluginError(
         name: "TypeError",
         message: "precise location needs a purpose from the accuracy-purposes build setting")
@@ -341,51 +359,29 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
   /// 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)
-      }
+      guard let prompt = prompts.removeValue(forKey: key) else { continue }
+      Task { @MainActor in await answer(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,
-      authorization.accuracyAuthorization == .reducedAccuracy
-    else {
-      prompt.reply(.success(permission()))
-      return
-    }
-    do throws(TokamakPluginError) {
-      try host.requireUI()
+  @MainActor
+  private func answer(_ prompt: Prompt) async {
+    do {
+      prompt.answer.resume(returning: try await respond(purpose: prompt.purpose))
     } catch {
-      prompt.reply(.failure(error))
-      return
+      prompt.answer.resume(throwing: error)
     }
-    authorization.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
+  /// The app's permission, after asking for temporary precise location for
+  /// `purpose` when the app has approximate location.
+  @MainActor
+  private func respond(purpose: String?) async throws -> LocationPermission {
+    if let purpose, hasPermission, authorization.accuracyAuthorization == .reducedAccuracy {
+      try host.requireUI()
+      _ = try? await authorization.requestTemporaryFullAccuracyAuthorization(
+        withPurposeKey: purpose)
     }
-    return .locationUnavailable(error.localizedDescription)
+    return permission()
   }
 }

package/apple/LocationPositions.swift

@@ -0,0 +1,59 @@
+import CoreLocation
+import Foundation
+
+/// Positions from a location manager of its own, for one `currentPosition`
+/// or `watchPosition`. Use it on the main thread, where the end of its stream
+/// stops it.
+final class TokamakLocationPositions: NSObject, CLLocationManagerDelegate, @unchecked Sendable {
+  private let manager = CLLocationManager()
+  private let continuation: AsyncThrowingStream<TokamakLocationPlugin.Position, Error>.Continuation
+  private let watching: Bool
+
+  /// A new fix, or each position as the device moves when `watching`, until
+  /// the stream ends.
+  static func stream(watching: Bool) -> AsyncThrowingStream<TokamakLocationPlugin.Position, Error> {
+    AsyncThrowingStream { continuation in
+      let positions = TokamakLocationPositions(continuation, watching: watching)
+      // The stream owns the location manager until it ends.
+      continuation.onTermination = { _ in
+        DispatchQueue.main.async { positions.manager.stopUpdatingLocation() }
+      }
+      if watching {
+        positions.manager.startUpdatingLocation()
+      } else {
+        positions.manager.requestLocation()
+      }
+    }
+  }
+
+  private init(
+    _ continuation: AsyncThrowingStream<TokamakLocationPlugin.Position, Error>.Continuation,
+    watching: Bool
+  ) {
+    self.continuation = continuation
+    self.watching = watching
+    super.init()
+    manager.delegate = self
+    manager.desiredAccuracy = kCLLocationAccuracyBest
+  }
+
+  func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
+    for location in watching ? locations : locations.suffix(1) {
+      continuation.yield(TokamakLocationPlugin.Position(location))
+    }
+    if !watching {
+      continuation.finish()
+    }
+  }
+
+  /// Asks again, or keeps watching, while Core Location does not know the
+  /// position yet.
+  func locationManager(_ manager: CLLocationManager, didFailWithError error: Error) {
+    guard (error as NSError).code == CLError.Code.locationUnknown.rawValue else {
+      return continuation.finish(throwing: TokamakPluginError.location(error))
+    }
+    if !watching {
+      manager.requestLocation()
+    }
+  }
+}

package/apple/LocationRegions.swift

@@ -5,7 +5,7 @@ import Foundation
   import UIKit
 #endif
 
-/// The JSON of each monitored region, as `addRegion` received it, by id.
+/// The JSON of each monitored region, by id.
 private let regionsKey = "tokamak.location.regions"
 /// The ids of the regions whose last transition was an entry.
 private let insideKey = "tokamak.location.inside"
@@ -30,26 +30,23 @@ final class TokamakLocationRegions {
       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))
+    events.task { [weak self] in
+      for try await event in await monitor.value.events {
+        self?.receive(event)
       }
     }
   }
 
   /// The regions, by id.
-  private var regions: [String: [String: Any]] {
+  private var regions: [String: TokamakLocationPlugin.Region] {
     get {
       defaults.data(forKey: regionsKey)
-        .flatMap { try? JSONSerialization.jsonObject(with: $0) as? [String: [String: Any]] } ?? [:]
+        .flatMap {
+          try? JSONDecoder().decode([String: TokamakLocationPlugin.Region].self, from: $0)
+        } ?? [:]
     }
     set {
-      defaults.set(try? JSONSerialization.data(withJSONObject: newValue), forKey: regionsKey)
+      defaults.set(try? JSONEncoder().encode(newValue), forKey: regionsKey)
     }
   }
 
@@ -58,17 +55,12 @@ final class TokamakLocationRegions {
     set { defaults.set(Array(newValue), forKey: insideKey) }
   }
 
-  /// 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. `CLMonitor` keeps the state of a condition added again under its
-  /// identifier, so the old condition is removed first.
-  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")
-    }
+  /// Monitors `region`, replacing one with the same id. It starts outside, so
+  /// a device already inside reports an entry, as on Android. `CLMonitor`
+  /// keeps the state of a condition added again under its identifier, so the
+  /// old condition is removed first.
+  func add(_ region: TokamakLocationPlugin.Region) async throws(TokamakPluginError) {
+    let id = region.id
     let monitor = await monitor.value
     let monitored = await monitor.identifiers
     guard monitored.count < regionLimit || monitored.contains(id) else {
@@ -76,8 +68,8 @@ final class TokamakLocationRegions {
         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)
+    let center = CLLocationCoordinate2D(latitude: region.latitude, longitude: region.longitude)
+    let condition = CLMonitor.CircularGeographicCondition(center: center, radius: region.radius)
     regions[id] = region
     inside.remove(id)
     await monitor.remove(id)
@@ -92,19 +84,22 @@ final class TokamakLocationRegions {
   }
 
   /// The monitored regions, each with whether the device is inside it.
-  func all() async -> [[String: Any]] {
+  func all() async -> [TokamakLocationPlugin.MonitoredRegion] {
     let monitor = await monitor.value
     let regions = regions
-    var all: [[String: Any]] = []
+    var all: [TokamakLocationPlugin.MonitoredRegion] = []
     for id in await monitor.identifiers {
-      guard var region = regions[id] else { continue }
-      region["state"] =
+      guard let region = regions[id] else { continue }
+      let state: TokamakLocationPlugin.RegionState =
         switch await monitor.record(for: id)?.lastEvent.state {
-        case .satisfied: "inside"
-        case .unsatisfied: "outside"
-        default: "unknown"
+        case .satisfied: .inside
+        case .unsatisfied: .outside
+        default: .unknown
         }
-      all.append(region)
+      all.append(
+        TokamakLocationPlugin.MonitoredRegion(
+          id: id, latitude: region.latitude, longitude: region.longitude, radius: region.radius,
+          onEntry: region.onEntry ?? true, onExit: region.onExit ?? true, state: state))
     }
     return all
   }
@@ -121,7 +116,7 @@ final class TokamakLocationRegions {
     let entered = event.state == .satisfied
     guard entered != inside.contains(id) else { return }
     inside = entered ? inside.union([id]) : inside.subtracting([id])
-    if region[entered ? "onEntry" : "onExit"] as? Bool != false {
+    if (entered ? region.onEntry : region.onExit) != false {
       events.transition(id, entered: entered, at: event.date)
     }
   }