@tokamakdev/plugin-location 0.1.0-beta.76 → 0.1.0-beta.80

package/README.md

@@ -19,6 +19,12 @@ const stop = location.watchPosition(
 );
 ```
 
+`getCurrentPosition` takes the Geolocation API's `maximumAge` and `timeout`
+options. It resolves with a recent position no older than `maximumAge`
+milliseconds, 0 by default, or takes a new one, and rejects with
+`TimeoutError` when none arrives within `timeout` milliseconds, unlimited by
+default. The timeout starts once the user allows location.
+
 The web implementation uses `navigator.geolocation`. Native Tokamak builds use
 Core Location on Apple platforms, `LocationManager` on Android, and WebView2's
 location implementation on Windows. Calling the API on a platform without

package/android/LocationPlugin.kt

@@ -8,11 +8,14 @@ import android.location.LocationListener
 import android.location.LocationManager
 import android.os.Bundle
 import android.os.CancellationSignal
+import android.os.Handler
 import android.os.Looper
+import android.os.SystemClock
 import com.tokamak.runtime.TokamakHost
 import com.tokamak.runtime.TokamakPlugin
 import com.tokamak.runtime.TokamakPluginError
 import com.tokamak.runtime.TokamakPluginReply
+import org.json.JSONObject
 
 class TokamakLocationPlugin(
     private val host: TokamakHost,
@@ -22,14 +25,16 @@ class TokamakLocationPlugin(
     private val context = host.context
     private val manager =
         context.getSystemService(Context.LOCATION_SERVICE) as LocationManager
+    private val handler = Handler(Looper.getMainLooper())
 
     override fun call(method: String, arguments: Any?, reply: TokamakPluginReply) {
         if (method != "getCurrentPosition") {
             super.call(method, arguments, reply)
             return
         }
+        val options = arguments as? JSONObject
         withPermission { granted ->
-            if (granted) currentPosition(reply) else reply(permissionDenied())
+            if (granted) currentPosition(options, reply) else reply(permissionDenied())
         }
     }
 
@@ -63,20 +68,43 @@ class TokamakLocationPlugin(
         host.requestPermissions(PERMISSIONS) { granted -> action(granted.containsValue(true)) }
     }
 
-    private fun currentPosition(reply: TokamakPluginReply) {
+    /**
+     * Replies with a fix no older than the `maximumAge` option, taking a new one when there is
+     * none, or fails after the `timeout` option.
+     */
+    private fun currentPosition(options: JSONObject?, reply: TokamakPluginReply) {
         val provider = availableProvider(reply) ?: return
+        val maximumAge = options?.optLong("maximumAge", 0) ?: 0
+        val recent = runCatching { manager.getLastKnownLocation(provider) }.getOrNull()
+        if (recent != null && ageMillis(recent) <= maximumAge) {
+            reply(Result.success(position(recent)))
+            return
+        }
+        val cancellation = CancellationSignal()
+        val timeout = Runnable {
+            cancellation.cancel()
+            reply(Result.failure(TokamakPluginError("TimeoutError", "Location was not found in time")))
+        }
+        handler.postDelayed(timeout, options?.optLong("timeout", UNLIMITED) ?: UNLIMITED)
         runCatching {
             manager.getCurrentLocation(
                 provider,
-                CancellationSignal(),
+                cancellation,
                 context.mainExecutor,
             ) { location ->
+                handler.removeCallbacks(timeout)
                 if (location == null) reply(unavailable("Location is unavailable"))
                 else reply(Result.success(position(location)))
             }
-        }.onFailure { reply(locationFailure(it)) }
+        }.onFailure {
+            handler.removeCallbacks(timeout)
+            reply(locationFailure(it))
+        }
     }
 
+    private fun ageMillis(location: Location): Long =
+        (SystemClock.elapsedRealtimeNanos() - location.elapsedRealtimeNanos) / 1_000_000
+
     private fun watchPosition(reply: TokamakPluginReply): () -> Unit {
         val provider = availableProvider(reply) ?: return {}
         val listener = object : LocationListener {
@@ -145,6 +173,8 @@ class TokamakLocationPlugin(
         else unavailable(error.message ?: "Location is unavailable")
 
     private companion object {
+        /** The `timeout` that never expires, as the page sends it. */
+        const val UNLIMITED = 0xffffffffL
         val PERMISSIONS = setOf(Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION)
     }
 }

package/apple/LocationPlugin.swift

@@ -10,15 +10,32 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     name: "NotAllowedError",
     message: "Location permission was denied"
   )
+  private static let timedOut = TokamakPluginError(
+    name: "TimeoutError",
+    message: "Location was not found in time"
+  )
+
+  /// A current position request, timed from when locating starts.
+  private struct Request {
+    let reply: TokamakPluginReply
+    let maximumAge: TimeInterval
+    let timeout: TimeInterval
+    var timer: DispatchWorkItem?
+  }
 
-  private let manager = CLLocationManager()
-  private var current: [TokamakPluginReply] = []
+  /// Updates watchers.
+  private let updates = CLLocationManager()
+  /// Takes single fixes for current position requests, apart from watching.
+  private let fixes = CLLocationManager()
+  private var current: [UUID: Request] = [:]
   private var watchers: [UUID: TokamakPluginReply] = [:]
 
   init(host: TokamakHost) {
     super.init()
-    manager.delegate = self
-    manager.desiredAccuracy = kCLLocationAccuracyBest
+    for manager in [updates, fixes] {
+      manager.delegate = self
+      manager.desiredAccuracy = kCLLocationAccuracyBest
+    }
   }
 
   func call(
@@ -30,7 +47,12 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
       reply(.failure(.notSupported("\(id).\(method) is not supported")))
       return
     }
-    current.append(reply)
+    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()
   }
 
@@ -48,14 +70,19 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     start()
     return { [weak self] in
       self?.watchers.removeValue(forKey: subscription)
-      self?.stopIfIdle()
+      if self?.watchers.isEmpty == true {
+        self?.updates.stopUpdatingLocation()
+      }
     }
   }
 
+  /// Also called when each manager is created, before anything asks for a
+  /// position. Both managers report the app's one authorization.
   func locationManagerDidChangeAuthorization(
     _ manager: CLLocationManager
   ) {
-    startIfAuthorized(manager.authorizationStatus)
+    guard manager === updates, !current.isEmpty || !watchers.isEmpty else { return }
+    serve(manager.authorizationStatus)
   }
 
   func locationManager(
@@ -63,38 +90,53 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     didUpdateLocations locations: [CLLocation]
   ) {
     guard let location = locations.last else { return }
-    deliver(.success(position(location)))
+    deliver(.success(position(location)), from: manager)
   }
 
+  /// A fix that is not yet available is taken again; updates continue.
   func locationManager(
     _ manager: CLLocationManager,
     didFailWithError error: Error
   ) {
-    if (error as NSError).code == CLError.Code.locationUnknown.rawValue {
+    guard (error as NSError).code == CLError.Code.locationUnknown.rawValue else {
+      deliver(.failure(locationError(error)), from: manager)
       return
     }
-    fail(locationError(error))
+    if manager === fixes && !current.isEmpty {
+      fixes.requestLocation()
+    }
   }
 
+  /// Checks location services off the main thread, which the check can block.
   private func start() {
-    guard CLLocationManager.locationServicesEnabled() else {
+    DispatchQueue.global(qos: .userInitiated).async {
+      let enabled = CLLocationManager.locationServicesEnabled()
+      DispatchQueue.main.async { self.start(servicesEnabled: enabled) }
+    }
+  }
+
+  private func start(servicesEnabled: Bool) {
+    guard servicesEnabled else {
       fail(unavailable("Location services are disabled"))
       return
     }
-    let status = manager.authorizationStatus
+    let status = updates.authorizationStatus
     if status == .notDetermined {
-      manager.requestWhenInUseAuthorization()
+      updates.requestWhenInUseAuthorization()
     } else {
-      startIfAuthorized(status)
+      serve(status)
     }
   }
 
-  /// Starts updates when `status` allows them and fails every request when it
-  /// forbids them.
-  private func startIfAuthorized(_ status: CLAuthorizationStatus) {
+  /// Locates for the waiting requests and watchers when `status` allows it,
+  /// and fails them when it forbids it.
+  private func serve(_ status: CLAuthorizationStatus) {
     switch status {
     case .authorizedAlways, .authorizedWhenInUse:
-      manager.startUpdatingLocation()
+      if !watchers.isEmpty {
+        updates.startUpdatingLocation()
+      }
+      locate()
     case .denied, .restricted:
       fail(Self.permissionDenied)
     case .notDetermined:
@@ -104,19 +146,49 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     }
   }
 
+  /// Answers each new request with a fix no older than its `maximumAge`, and
+  /// takes a fix for the rest, each failing after its `timeout`.
+  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)))
+        continue
+      }
+      let timer = DispatchWorkItem { [weak self] in self?.finish(key, .failure(Self.timedOut)) }
+      current[key]?.timer = timer
+      DispatchQueue.main.asyncAfter(deadline: .now() + request.timeout, execute: timer)
+    }
+    if !current.isEmpty {
+      fixes.requestLocation()
+    }
+  }
+
+  /// Answers the waiting requests with a fix, or the watchers with an update.
+  private func deliver(_ result: Result<Any?, TokamakPluginError>, from manager: CLLocationManager)
+  {
+    guard manager === fixes else {
+      for reply in watchers.values {
+        reply(result)
+      }
+      return
+    }
+    for key in current.keys {
+      finish(key, result)
+    }
+  }
+
   private func fail(_ error: TokamakPluginError) {
-    deliver(.failure(error))
+    deliver(.failure(error), from: fixes)
+    deliver(.failure(error), from: updates)
   }
 
-  /// Replies to the waiting requests and every watcher, then stops when none
-  /// remain.
-  private func deliver(_ result: Result<Any?, TokamakPluginError>) {
-    let replies = current + Array(watchers.values)
-    current.removeAll()
-    for reply in replies {
-      reply(result)
+  private func finish(_ key: UUID, _ result: Result<Any?, TokamakPluginError>) {
+    guard let request = current.removeValue(forKey: key) else { return }
+    request.timer?.cancel()
+    request.reply(result)
+    if current.isEmpty {
+      fixes.stopUpdatingLocation()
     }
-    stopIfIdle()
   }
 
   private func locationError(_ error: Error) -> TokamakPluginError {
@@ -130,12 +202,6 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     TokamakPluginError(name: "NotReadableError", message: message)
   }
 
-  private func stopIfIdle() {
-    if current.isEmpty && watchers.isEmpty {
-      manager.stopUpdatingLocation()
-    }
-  }
-
   private func position(_ location: CLLocation) -> [String: Any] {
     let coordinates = location.coordinate
     return [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamakdev/plugin-location",
-  "version": "0.1.0-beta.76",
+  "version": "0.1.0-beta.80",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mantty/tokamak.git",
@@ -11,7 +11,7 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@tokamakdev/plugin": "0.1.0-beta.76"
+    "@tokamakdev/plugin": "0.1.0-beta.80"
   },
   "files": [
     "android",

package/src/index.ts

@@ -16,6 +16,14 @@ export interface Position {
   readonly timestamp: number;
 }
 
+/** Options for `getCurrentPosition`, as the Geolocation API reads them. */
+export interface PositionOptions {
+  /** The age in milliseconds of a recent position to accept instead of a new one; 0 by default. */
+  readonly maximumAge?: number;
+  /** Milliseconds to wait for a position before rejecting with `TimeoutError`; unlimited by default. */
+  readonly timeout?: number;
+}
+
 export type PositionCallback = (position: Position) => void;
 export type PositionErrorCallback = (error: DOMException) => void;
 
@@ -24,8 +32,12 @@ class Location extends FrontendPlugin {
     super("location");
   }
 
-  getCurrentPosition(): Promise<Position> {
-    return this.hasNativeTransport ? this.call("getCurrentPosition") : web.getCurrentPosition();
+  getCurrentPosition(options: PositionOptions = {}): Promise<Position> {
+    if (!this.hasNativeTransport) return web.getCurrentPosition(options);
+    return this.call("getCurrentPosition", {
+      maximumAge: milliseconds(options.maximumAge ?? 0),
+      timeout: milliseconds(options.timeout ?? unlimited),
+    });
   }
 
   watchPosition(next: PositionCallback, error: PositionErrorCallback): () => void {
@@ -34,4 +46,11 @@ class Location extends FrontendPlugin {
   }
 }
 
+const unlimited = 0xffffffff;
+
+/** `value` clamped to whole milliseconds, as the Geolocation API reads its options. */
+function milliseconds(value: number): number {
+  return Number.isNaN(value) ? 0 : Math.min(Math.max(Math.round(value), 0), unlimited);
+}
+
 export const location = new Location();

package/web/index.ts

@@ -1,6 +1,11 @@
-import type { Position, PositionCallback, PositionErrorCallback } from "../src/index.js";
+import type {
+  Position,
+  PositionCallback,
+  PositionErrorCallback,
+  PositionOptions,
+} from "../src/index.js";
 
-export function getCurrentPosition(): Promise<Position> {
+export function getCurrentPosition(options: PositionOptions): Promise<Position> {
   return new Promise((resolve, reject) => {
     const browserLocation = browserLocationApi();
     browserLocation.getCurrentPosition(
@@ -10,6 +15,7 @@ export function getCurrentPosition(): Promise<Position> {
       (error) => {
         reject(positionError(error));
       },
+      options,
     );
   });
 }