@tokamakdev/plugin-location 0.1.0-beta.100

package/README.md

@@ -0,0 +1,43 @@
+# @tokamakdev/plugin-location
+
+Location for Tokamak applications and the web.
+
+Add it to your project's dependencies:
+
+```sh
+npm install @tokamakdev/plugin-location
+```
+
+```ts
+import { location } from "@tokamakdev/plugin-location";
+
+const position = await location.getCurrentPosition();
+
+const stop = location.watchPosition(
+  (next) => console.log(next.coords.latitude, next.coords.longitude),
+  console.error,
+);
+```
+
+`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.
+
+## Off screen
+
+The plugin asks for location while the app is in use only. While the app is
+off screen on iOS or Android, as when Worker code runs in the background, a
+call that would ask the user for permission rejects with `NeedsUIError`. With
+permission granted, the platforms stop locating an app that is off screen
+without background location permission, which the plugin does not request, so
+`getCurrentPosition` rejects with `NotAllowedError` there. iOS still locates
+the app for a few seconds after it leaves the screen.
+
+## Platforms
+
+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
+location support throws `NotSupportedError`.

package/android/AndroidManifest.xml

@@ -0,0 +1,4 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+</manifest>

package/android/LocationPlugin.kt

@@ -0,0 +1,191 @@
+package com.tokamak.plugins.location
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.location.Location
+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,
+) : TokamakPlugin {
+    override val id = "location"
+
+    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(options, reply) else reply(permissionDenied())
+        }
+    }
+
+    override fun subscribe(
+        method: String,
+        arguments: Any?,
+        reply: TokamakPluginReply,
+    ): () -> Unit {
+        if (method != "watchPosition") return super.subscribe(method, arguments, reply)
+        var cancelled = false
+        var stop = {}
+        withPermission { granted ->
+            if (!granted) {
+                reply(permissionDenied())
+            } else if (!cancelled) {
+                stop = watchPosition(reply)
+            }
+        }
+        return {
+            cancelled = true
+            stop()
+        }
+    }
+
+    /**
+     * Passes [action] whether the app may read fine or coarse location, asking when it may not.
+     * Throws `NeedsUIError` when asking would show UI while the app is in the background.
+     */
+    private fun withPermission(action: (Boolean) -> Unit) {
+        if (PERMISSIONS.any { context.checkSelfPermission(it) == PackageManager.PERMISSION_GRANTED }) {
+            action(true)
+            return
+        }
+        host.requestPermissions(PERMISSIONS) { granted -> action(granted.containsValue(true)) }
+    }
+
+    /**
+     * 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,
+                cancellation,
+                context.mainExecutor,
+            ) { location ->
+                handler.removeCallbacks(timeout)
+                reply(if (location == null) missingFix() else Result.success(position(location)))
+            }
+        }.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 {
+            override fun onLocationChanged(location: Location) {
+                reply(Result.success(position(location)))
+            }
+
+            override fun onProviderDisabled(provider: String) {
+                reply(unavailable("Location provider is unavailable"))
+            }
+
+            override fun onStatusChanged(provider: String?, status: Int, extras: Bundle?) = Unit
+        }
+        runCatching {
+            manager.requestLocationUpdates(provider, 1000, 0F, listener, Looper.getMainLooper())
+        }.onFailure {
+            reply(locationFailure(it))
+            return {}
+        }
+        return { manager.removeUpdates(listener) }
+    }
+
+    /** The provider to use, or null once [reply] has the reason there is none. */
+    private fun availableProvider(reply: TokamakPluginReply): String? {
+        val provider = runCatching(::provider).getOrElse {
+            reply(locationFailure(it))
+            return null
+        }
+        if (provider == null) reply(unavailable("No location provider is available"))
+        return provider
+    }
+
+    private fun provider(): String? =
+        listOf(
+            LocationManager.GPS_PROVIDER,
+            LocationManager.NETWORK_PROVIDER,
+            LocationManager.FUSED_PROVIDER,
+        ).firstOrNull(manager::isProviderEnabled)
+            ?: manager.getProviders(true).firstOrNull()
+
+    private fun position(location: Location): Map<String, Any?> =
+        mapOf(
+            "coords" to
+                mapOf(
+                    "latitude" to location.latitude,
+                    "longitude" to location.longitude,
+                    "accuracy" to location.accuracy.toDouble(),
+                    "altitude" to location.altitude.takeIf { location.hasAltitude() },
+                    "altitudeAccuracy" to
+                        location.verticalAccuracyMeters.toDouble()
+                            .takeIf { location.hasVerticalAccuracy() },
+                    "heading" to location.bearing.toDouble().takeIf { location.hasBearing() },
+                    "speed" to location.speed.toDouble().takeIf { location.hasSpeed() },
+                ),
+            "timestamp" to location.time,
+        )
+
+    private fun permissionDenied(): Result<Any?> =
+        Result.failure(TokamakPluginError("NotAllowedError", "Location permission was denied"))
+
+    /** Why no fix came: Android gives none in the background without background location permission. */
+    private fun missingFix(): Result<Any?> =
+        if (host.isInForeground || context.checkSelfPermission(BACKGROUND) == PackageManager.PERMISSION_GRANTED) {
+            unavailable("Location is unavailable")
+        } else {
+            Result.failure(TokamakPluginError("NotAllowedError", "Location permission does not cover the background"))
+        }
+
+    private fun unavailable(message: String): Result<Any?> =
+        Result.failure(TokamakPluginError("NotReadableError", message))
+
+    private fun locationFailure(error: Throwable): Result<Any?> =
+        if (error is SecurityException) permissionDenied()
+        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)
+        const val BACKGROUND = Manifest.permission.ACCESS_BACKGROUND_LOCATION
+    }
+}

package/apple/LocationPlugin.swift

@@ -0,0 +1,236 @@
+import CoreLocation
+import Foundation
+
+final class TokamakLocationPlugin: NSObject, TokamakPlugin,
+  CLLocationManagerDelegate
+{
+  let id = "location"
+
+  private static let permissionDenied = TokamakPluginError(
+    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 host: TokamakHost
+  /// 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) {
+    self.host = host
+    super.init()
+    for manager in [updates, fixes] {
+      manager.delegate = self
+      manager.desiredAccuracy = kCLLocationAccuracyBest
+    }
+  }
+
+  func call(
+    method: String,
+    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()
+  }
+
+  func subscribe(
+    method: String,
+    arguments: Any,
+    reply: @escaping TokamakPluginReply
+  ) throws(TokamakPluginError) -> (() -> Void) {
+    guard method == "watchPosition" else {
+      throw .notSupported("\(id).\(method) is not supported")
+    }
+    let subscription = UUID()
+    watchers[subscription] = reply
+    start()
+    return { [weak self] in
+      self?.watchers.removeValue(forKey: subscription)
+      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
+  ) {
+    guard manager === updates, !current.isEmpty || !watchers.isEmpty else { return }
+    serve(manager.authorizationStatus)
+  }
+
+  func locationManager(
+    _ manager: CLLocationManager,
+    didUpdateLocations locations: [CLLocation]
+  ) {
+    guard let location = locations.last else { return }
+    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
+  ) {
+    guard (error as NSError).code == CLError.Code.locationUnknown.rawValue else {
+      deliver(.failure(locationError(error)), from: manager)
+      return
+    }
+    if manager === fixes && !current.isEmpty {
+      fixes.requestLocation()
+    }
+  }
+
+  /// Checks location services off the main thread, which the check can block.
+  private func start() {
+    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 = updates.authorizationStatus
+    guard status == .notDetermined else {
+      serve(status)
+      return
+    }
+    do throws(TokamakPluginError) {
+      try host.requireUI()
+      updates.requestWhenInUseAuthorization()
+    } catch {
+      fail(error)
+    }
+  }
+
+  /// 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:
+      if !watchers.isEmpty {
+        updates.startUpdatingLocation()
+      }
+      locate()
+    case .denied, .restricted:
+      fail(Self.permissionDenied)
+    case .notDetermined:
+      break
+    @unknown default:
+      fail(.notSupported("Location authorization is not supported"))
+    }
+  }
+
+  /// 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), from: fixes)
+    deliver(.failure(error), from: updates)
+  }
+
+  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()
+    }
+  }
+
+  private func locationError(_ error: Error) -> TokamakPluginError {
+    if (error as NSError).code == CLError.Code.denied.rawValue {
+      return Self.permissionDenied
+    }
+    return unavailable(error.localizedDescription)
+  }
+
+  private func unavailable(_ message: String) -> TokamakPluginError {
+    TokamakPluginError(name: "NotReadableError", message: message)
+  }
+
+  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 func nullable(_ available: Bool, _ value: Double) -> Any {
+    available ? value : NSNull()
+  }
+}

package/apple/ios/Info.plist

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>NSLocationWhenInUseUsageDescription</key>
+	<string>This app uses your location when you request location features.</string>
+</dict>
+</plist>

package/apple/macos/Info.plist

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>NSLocationUsageDescription</key>
+	<string>This app uses your location when you request location features.</string>
+</dict>
+</plist>

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@tokamakdev/plugin-location",
+  "version": "0.1.0-beta.100",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mantty/tokamak.git",
+    "directory": "plugins/location"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "@tokamakdev/plugin": "0.1.0-beta.100"
+  },
+  "files": [
+    "android",
+    "apple",
+    "src",
+    "web",
+    "tokamak-plugin.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+import { Plugin } from "@tokamakdev/plugin";
+import * as web from "../web/index.js";
+
+export interface Coordinates {
+  readonly latitude: number;
+  readonly longitude: number;
+  readonly accuracy: number;
+  readonly altitude: number | null;
+  readonly altitudeAccuracy: number | null;
+  readonly heading: number | null;
+  readonly speed: number | null;
+}
+
+export interface Position {
+  readonly coords: Coordinates;
+  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;
+
+class Location extends Plugin {
+  constructor() {
+    super("location");
+  }
+
+  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 {
+    if (!this.hasNativeTransport) return web.watchPosition(next, error);
+    return this.listen("watchPosition", next, error);
+  }
+}
+
+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/tokamak-plugin.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 1,
+  "id": "location",
+  "platforms": {
+    "macos": {
+      "class": "TokamakLocationPlugin",
+      "sources": ["apple/LocationPlugin.swift"],
+      "plist": "apple/macos/Info.plist"
+    },
+    "ios": {
+      "class": "TokamakLocationPlugin",
+      "sources": ["apple/LocationPlugin.swift"],
+      "plist": "apple/ios/Info.plist"
+    },
+    "android": {
+      "class": "com.tokamak.plugins.location.TokamakLocationPlugin",
+      "sources": ["android/LocationPlugin.kt"],
+      "manifest": "android/AndroidManifest.xml"
+    }
+  }
+}

package/web/index.ts

@@ -0,0 +1,71 @@
+import type {
+  Position,
+  PositionCallback,
+  PositionErrorCallback,
+  PositionOptions,
+} from "../src/index.js";
+
+export function getCurrentPosition(options: PositionOptions): Promise<Position> {
+  return new Promise((resolve, reject) => {
+    const browserLocation = browserLocationApi();
+    browserLocation.getCurrentPosition(
+      (position) => {
+        resolve(copyPosition(position));
+      },
+      (error) => {
+        reject(positionError(error));
+      },
+      options,
+    );
+  });
+}
+
+export function watchPosition(
+  next: PositionCallback,
+  error: PositionErrorCallback,
+): () => void {
+  const browserLocation = browserLocationApi();
+  const id = browserLocation.watchPosition(
+    (position) => {
+      next(copyPosition(position));
+    },
+    (failure) => {
+      error(positionError(failure));
+    },
+  );
+  return () => {
+    browserLocation.clearWatch(id);
+  };
+}
+
+function browserLocationApi(): Geolocation {
+  const root: { navigator?: { geolocation?: Geolocation } } = globalThis;
+  const browserLocation = root.navigator?.geolocation;
+  if (browserLocation) return browserLocation;
+  throw new DOMException("Location is unavailable", "NotSupportedError");
+}
+
+function copyPosition(position: GeolocationPosition): Position {
+  const { coords } = position;
+  return {
+    coords: {
+      latitude: coords.latitude,
+      longitude: coords.longitude,
+      accuracy: coords.accuracy,
+      altitude: coords.altitude,
+      altitudeAccuracy: coords.altitudeAccuracy,
+      heading: coords.heading,
+      speed: coords.speed,
+    },
+    timestamp: position.timestamp,
+  };
+}
+
+function positionError(error: GeolocationPositionError): DOMException {
+  const name = {
+    [error.PERMISSION_DENIED]: "NotAllowedError",
+    [error.POSITION_UNAVAILABLE]: "NotReadableError",
+    [error.TIMEOUT]: "TimeoutError",
+  }[error.code];
+  return new DOMException(error.message, name ?? "UnknownError");
+}