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

package/android/LocationReceiver.kt

@@ -0,0 +1,27 @@
+package com.tokamak.plugins.location
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import com.tokamak.runtime.tokamakPlugin
+
+/** Receives updates and region transitions, which Android sends even after the app's process ended. */
+class TokamakLocationReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        val plugin = context.tokamakPlugin("location") as? TokamakLocationPlugin ?: return
+        val pending = goAsync()
+        plugin.receive(intent) { pending.finish() }
+    }
+}
+
+/** Requests updates and regions again after a restart or an app update, which remove update requests. */
+class TokamakLocationBootReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        if (intent.action !in ACTIONS) return
+        (context.tokamakPlugin("location") as? TokamakLocationPlugin)?.restore(updatesRemoved = true)
+    }
+
+    private companion object {
+        val ACTIONS = setOf(Intent.ACTION_BOOT_COMPLETED, Intent.ACTION_MY_PACKAGE_REPLACED)
+    }
+}

package/android/LocationRegions.kt

@@ -0,0 +1,73 @@
+package com.tokamak.plugins.location
+
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import android.location.LocationManager
+import org.json.JSONObject
+
+/** The JSON of each monitored region, as `addRegion` received it, by id. */
+private const val PREFERENCES = "tokamak.location.regions"
+
+/**
+ * Circular regions, as proximity alerts that `LocationManager` sends to [TokamakLocationReceiver]
+ * through a `PendingIntent` per region, starting the app's process when it has ended. The regions
+ * persist until [remove], and [restore] adds them again where Android removed them. Use it on the
+ * main thread.
+ */
+internal class LocationRegions(private val context: Context) {
+    private val manager = context.getSystemService(LocationManager::class.java)
+    private val preferences = context.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE)
+
+    fun all(): List<JSONObject> = preferences.all.values.map { JSONObject(it as String) }
+
+    fun get(id: String): JSONObject? = preferences.getString(id, null)?.let(::JSONObject)
+
+    /**
+     * Monitors [region], replacing one with the same id. It starts in an unknown state, so a device
+     * already inside reports an entry. Throws `SecurityException` without precise location.
+     */
+    fun add(region: JSONObject) {
+        val id = region.getString("id")
+        val alert = checkNotNull(pendingIntent(id, PendingIntent.FLAG_UPDATE_CURRENT))
+        manager.removeProximityAlert(alert)
+        manager.addProximityAlert(
+            region.getDouble("latitude"),
+            region.getDouble("longitude"),
+            region.getDouble("radius").toFloat(),
+            -1,
+            alert,
+        )
+        preferences.edit().putString(id, region.toString()).apply()
+    }
+
+    fun remove(id: String) {
+        preferences.edit().remove(id).apply()
+        pendingIntent(id, PendingIntent.FLAG_NO_CREATE)?.let {
+            manager.removeProximityAlert(it)
+            it.cancel()
+        }
+    }
+
+    /**
+     * Adds the regions whose `PendingIntent` no longer exists again, as after a restart or Android
+     * 15's force stop. Adding one resets its state. Throws `SecurityException` without precise
+     * location.
+     */
+    fun restore() {
+        all().filter { pendingIntent(it.getString("id"), PendingIntent.FLAG_NO_CREATE) == null }.forEach(::add)
+    }
+
+    /** The region [id]'s `PendingIntent`, mutable so `LocationManager` adds whether the device entered. */
+    private fun pendingIntent(id: String, flags: Int): PendingIntent? =
+        PendingIntent.getBroadcast(
+            context,
+            0,
+            Intent(context, TokamakLocationReceiver::class.java).setAction(REGION_ACTION).setIdentifier(id),
+            flags or PendingIntent.FLAG_MUTABLE,
+        )
+
+    companion object {
+        const val REGION_ACTION = "com.tokamak.plugins.location.REGION"
+    }
+}

package/android/LocationService.kt

@@ -0,0 +1,64 @@
+package com.tokamak.plugins.location
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.app.Service
+import android.content.Intent
+import android.content.pm.ServiceInfo
+import android.os.IBinder
+import org.json.JSONObject
+
+private const val CHANNEL = "tokamak.location"
+private const val NOTIFICATION_ID = 1
+
+/**
+ * Runs while updates have a `foregroundService`. Android neither throttles location for an app with
+ * a location foreground service nor withholds it off screen. The service requests no location
+ * itself, and Android restarts it after ending it for memory.
+ */
+class TokamakLocationService : Service() {
+    override fun onBind(intent: Intent?): IBinder? = null
+
+    /** Shows the notification the start [intent] carries, or on a restart, the running updates'. */
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        val content =
+            intent?.getStringExtra(NOTIFICATION_EXTRA)?.let(::JSONObject)
+                ?: LocationUpdates(this).options?.optJSONObject("foregroundService")
+        if (content == null) {
+            stopSelf()
+            return START_NOT_STICKY
+        }
+        startForeground(NOTIFICATION_ID, notification(content), ServiceInfo.FOREGROUND_SERVICE_TYPE_LOCATION)
+        return START_STICKY
+    }
+
+    /** The notification [content] describes, in the location channel it names, opening the app. */
+    private fun notification(content: JSONObject): Notification {
+        val channel = NotificationChannel(CHANNEL, content.getString("channel"), NotificationManager.IMPORTANCE_LOW)
+        getSystemService(NotificationManager::class.java).createNotificationChannel(channel)
+        val open =
+            packageManager.getLaunchIntentForPackage(packageName)?.let {
+                PendingIntent.getActivity(this, 0, it, PendingIntent.FLAG_IMMUTABLE)
+            }
+        return Notification.Builder(this, CHANNEL)
+            .setSmallIcon(icon())
+            .setContentTitle(content.getString("title"))
+            .setContentText(content.getString("body"))
+            .setContentIntent(open)
+            .setOngoing(true)
+            .build()
+    }
+
+    /** The app's monochrome `drawable/tokamak_notification`, or its launcher icon. */
+    private fun icon(): Int =
+        resources.getIdentifier("tokamak_notification", "drawable", packageName).takeIf { it != 0 }
+            ?: applicationInfo.icon.takeIf { it != 0 }
+            ?: android.R.drawable.sym_def_app_icon
+
+    companion object {
+        /** The start intent's notification, as JSON. */
+        const val NOTIFICATION_EXTRA = "com.tokamak.plugins.location.NOTIFICATION"
+    }
+}

package/android/LocationUpdates.kt

@@ -0,0 +1,120 @@
+package com.tokamak.plugins.location
+
+import android.app.ActivityManager
+import android.app.ApplicationExitInfo
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import android.location.LocationManager
+import android.location.LocationRequest
+import org.json.JSONObject
+
+private const val PREFERENCES = "tokamak.location"
+
+/** The JSON of the running updates' options, as `startUpdates` received them. */
+private const val UPDATES = "updates"
+private const val UPDATES_ACTION = "com.tokamak.plugins.location.UPDATES"
+private const val DEFAULT_INTERVAL_MILLIS = 10_000L
+
+private val QUALITIES =
+    mapOf(
+        "high" to LocationRequest.QUALITY_HIGH_ACCURACY,
+        "balanced" to LocationRequest.QUALITY_BALANCED_POWER_ACCURACY,
+        "low" to LocationRequest.QUALITY_LOW_POWER,
+    )
+
+/**
+ * Continuous updates, which `LocationManager` sends to [TokamakLocationReceiver] through a
+ * `PendingIntent`, starting the app's process when it has ended, with [TokamakLocationService] when
+ * their options name a `foregroundService`. The options persist until [stop], and [restore] requests
+ * them again where Android removed the request. Use it on the main thread.
+ */
+internal class LocationUpdates(private val context: Context) {
+    private val manager = context.getSystemService(LocationManager::class.java)
+    private val preferences = context.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE)
+
+    /** The options of the running updates, or null. */
+    val options: JSONObject?
+        get() = preferences.getString(UPDATES, null)?.let(::JSONObject)
+
+    /**
+     * Starts updates with [options], replacing any running, in the foreground service when they name
+     * one, which stops otherwise. Throws `SecurityException` without permission.
+     */
+    fun start(options: JSONObject) {
+        val notification = options.optJSONObject("foregroundService")
+        if (notification == null) stopService() else startService(notification)
+        request(options)
+        preferences.edit().putString(UPDATES, options.toString()).apply()
+    }
+
+    fun stop() {
+        preferences.edit().remove(UPDATES).apply()
+        stopService()
+        pendingIntent(PendingIntent.FLAG_NO_CREATE)?.let {
+            manager.removeUpdates(it)
+            it.cancel()
+        }
+    }
+
+    /** Starts the running updates' foreground service, if they have one. */
+    fun startService() {
+        options?.optJSONObject("foregroundService")?.let(::startService)
+    }
+
+    private fun startService(notification: JSONObject) {
+        val start =
+            Intent(context, TokamakLocationService::class.java)
+                .putExtra(TokamakLocationService.NOTIFICATION_EXTRA, notification.toString())
+        context.startForegroundService(start)
+    }
+
+    private fun stopService() {
+        context.stopService(Intent(context, TokamakLocationService::class.java))
+    }
+
+    /**
+     * Requests the running updates again when Android [removed] the request, when their
+     * `PendingIntent` no longer exists, or after a force stop, which removes the request on Android
+     * 14. Throws `SecurityException` when the app no longer has permission.
+     */
+    fun restore(removed: Boolean) {
+        val options = options ?: return
+        if (removed || forceStopped() || pendingIntent(PendingIntent.FLAG_NO_CREATE) == null) request(options)
+    }
+
+    /** Whether the app's process last ended by the user's force stop. */
+    private fun forceStopped(): Boolean =
+        context.getSystemService(ActivityManager::class.java)
+            .getHistoricalProcessExitReasons(null, 0, 1)
+            .firstOrNull()
+            ?.reason == ApplicationExitInfo.REASON_USER_REQUESTED
+
+    private fun request(options: JSONObject) {
+        val accuracy = options.optString("accuracy", "high")
+        val request =
+            LocationRequest.Builder(options.optLong("interval", DEFAULT_INTERVAL_MILLIS))
+                .setQuality(QUALITIES[accuracy] ?: LocationRequest.QUALITY_HIGH_ACCURACY)
+                .setMinUpdateDistanceMeters(options.optDouble("distance", 0.0).toFloat())
+                .build()
+        val updates = checkNotNull(pendingIntent(PendingIntent.FLAG_UPDATE_CURRENT))
+        manager.requestLocationUpdates(provider(accuracy), request, updates)
+    }
+
+    /** The fused provider when the device has one, and otherwise GPS for high accuracy and the network for less. */
+    private fun provider(accuracy: String): String =
+        when {
+            manager.hasProvider(LocationManager.FUSED_PROVIDER) -> LocationManager.FUSED_PROVIDER
+            accuracy == "high" -> LocationManager.GPS_PROVIDER
+            else -> LocationManager.NETWORK_PROVIDER
+        }
+
+    /** The updates' `PendingIntent`, mutable so `LocationManager` adds the locations. */
+    private fun pendingIntent(flags: Int): PendingIntent? =
+        PendingIntent.getBroadcast(
+            context,
+            0,
+            Intent(context, TokamakLocationReceiver::class.java).setAction(UPDATES_ACTION),
+            flags or PendingIntent.FLAG_MUTABLE,
+        )
+}

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)
+  }
+}