Skip to content

Colota - Android GPS Location tracker

13.9 KB
Raw Blame
/**
 * Copyright (C) 2026 Max Dietrich
 * Licensed under the GNU AGPLv3. See LICENSE in the project root for details.
 */

import { useState, useEffect, useRef, useCallback } from "react"
import { AppState, NativeEventEmitter, NativeModules } from "react-native"
import NativeLocationService from "../services/NativeLocationService"
import { showAlert } from "../services/modalService"
import { LocationCoords, Settings, LocationTrackingResult } from "../types/global"
import { ensurePermissions, checkPermissions } from "../services/LocationServicePermission"
import { SERVICE_RESTART_DELAY_MS, RESTART_DEBOUNCE_MS } from "../constants"
import { logger } from "../utils/logger"
import { t } from "../i18n/t"

const { LocationServiceModule } = NativeModules
const locationEventEmitter = new NativeEventEmitter(LocationServiceModule)

/**
 * Hook for managing native location tracking.
 *
 * Acts as a bridge between React Native UI and Android Foreground Service.
 *
 * Features:
 * - Permission guards
 * - Native event subscription
 * - State hydration from SQLite
 * - Service restart logic with proper delays
 *
 * @param settings Initial tracking configuration
 * @param settingsHydrated Whether `settings` has been read back from SQLite yet
 * @returns Control interface for location tracking
 */
export function useLocationTracking(settings: Settings, settingsHydrated: boolean): LocationTrackingResult {
  // State
  const [coords, setCoords] = useState<LocationCoords | null>(null)
  const [tracking, setTracking] = useState(false)
  const [isRestarting, setIsRestarting] = useState(false)

  // Refs for synchronous checks
  const settingsRef = useRef<Settings>(settings)
  const isTrackingRef = useRef(false)
  const restartingRef = useRef(false)
  const revivingRef = useRef(false)
  const restartQueuedRef = useRef(false)
  const listenerRef = useRef<any>(null)

  // Sync refs with state
  useEffect(() => {
    settingsRef.current = settings
  }, [settings])

  useEffect(() => {
    isTrackingRef.current = tracking
  }, [tracking])

  /**
   * Fetches last known location from SQLite on mount
   * Prevents UI flicker before first GPS fix
   */
  useEffect(() => {
    const syncInitialLocation = async () => {
      if (!coords && (tracking || isRestarting)) {
        try {
          const latest = await NativeLocationService.getMostRecentLocation()
          if (latest) {
            setCoords({
              latitude: latest.latitude,
              longitude: latest.longitude,
              accuracy: latest.accuracy,
              altitude: latest.altitude ?? 0,
              speed: latest.speed ?? 0,
              bearing: latest.bearing ?? 0,
              timestamp: latest.timestamp ?? Math.floor(Date.now() / 1000),
              battery: latest.battery,
              battery_status: latest.batteryStatus
            })
          }
        } catch (err) {
          logger.error("[useLocationTracking] Failed to fetch initial location:", err)
        }
      }
    }

    syncInitialLocation()
  }, [tracking, isRestarting, coords])

  /**
   * Subscribes to real-time location updates from native service
   */
  useEffect(() => {
    if (tracking && !listenerRef.current) {
      logger.debug("[useLocationTracking] Attaching native listener")
      listenerRef.current = locationEventEmitter.addListener("onLocationUpdate", (event: any) => {
        setCoords({
          latitude: event.latitude,
          longitude: event.longitude,
          accuracy: event.accuracy,
          altitude: event.altitude,
          speed: event.speed,
          bearing: event.bearing,
          timestamp: Math.floor(event.timestamp / 1000),
          battery: event.battery,
          battery_status: event.batteryStatus
        })
      })
    }

    return () => {
      if (listenerRef.current) {
        logger.debug("[useLocationTracking] Removing JS event listener (foreground service unaffected)")
        listenerRef.current.remove()
        listenerRef.current = null
      }
    }
  }, [tracking])

  /**
   * Listens for unexpected tracking stops (e.g. battery critical)
   */
  useEffect(() => {
    const sub = locationEventEmitter.addListener("onTrackingStopped", (event: any) => {
      const { reason } = event as { reason: string }
      logger.warn(`[useLocationTracking] Tracking stopped by native: ${reason}`)
      if (listenerRef.current) {
        listenerRef.current.remove()
        listenerRef.current = null
      }
      setTracking(false)
    })
    return () => sub.remove()
  }, [])

  /**
   * Listens for tracking starts initiated outside JS (e.g. automation intent)
   */
  useEffect(() => {
    const sub = locationEventEmitter.addListener("onTrackingStarted", (event: any) => {
      const { reason } = event as { reason: string }
      logger.info(`[useLocationTracking] Tracking started by native: ${reason}`)
      setTracking(true)
    })
    return () => sub.remove()
  }, [])

  /**
   * Listens for sync errors from native service
   */
  useEffect(() => {
    const sub = locationEventEmitter.addListener("onSyncError", (event: any) => {
      const { message, queuedCount } = event as { message: string; queuedCount: number }
      logger.warn(`[useLocationTracking] Sync error: ${message} (${queuedCount} queued)`)
    })
    return () => sub.remove()
  }, [])

  /**
   * Starts location tracking
   * @param overrideSettings Optional one-time settings override
   */
  const startTracking = useCallback(async (overrideSettings?: Settings) => {
    if (isTrackingRef.current) {
      logger.debug("[useLocationTracking] Already tracking")
      return
    }

    const effectiveSettings: Settings = {
      ...settingsRef.current,
      ...overrideSettings
    }

    const granted = await ensurePermissions()
    if (!granted) {
      showAlert(t("permission.required.title"), t("permission.required.message"), "warning")
      return
    }

    setTracking(true)

    try {
      await NativeLocationService.start(effectiveSettings)
      logger.debug(`[useLocationTracking] Service started (offline: ${effectiveSettings.isOfflineMode})`)
    } catch (error) {
      setTracking(false)
      logger.error("[useLocationTracking] Failed to start:", error)
      showAlert(t("common.error"), t("permission.startFailed"), "error")
    }
  }, [])

  /**
   * Stops location tracking and cleans up
   */
  const stopTracking = useCallback(() => {
    if (!isTrackingRef.current) {
      logger.debug("[useLocationTracking] Not tracking")
      return
    }

    logger.debug("[useLocationTracking] Stopping service")

    if (listenerRef.current) {
      listenerRef.current.remove()
      listenerRef.current = null
    }

    NativeLocationService.stop()
    setTracking(false)
  }, [])

  /**
   * Restarts the service with new settings
   * Includes delay for Android to release foreground service resources
   * @param newSettings Settings for the new service instance
   */
  /** False when nothing was cycled: tracking was off, or a restart was already in flight. */
  const restartTracking = useCallback(
    async (newSettings?: Settings): Promise<boolean> => {
      // Only restart if tracking is active - settings are persisted separately,
      // so they'll be picked up when the user starts tracking later.
      if (!isTrackingRef.current) {
        logger.debug("[useLocationTracking] Not tracking, skip restart (settings saved separately)")
        return false
      }

      if (restartingRef.current) {
        logger.debug("[useLocationTracking] Restart already in progress, queuing")
        restartQueuedRef.current = true
        return false
      }

      logger.debug("[useLocationTracking] Restarting service")
      setIsRestarting(true)
      restartingRef.current = true

      try {
        stopTracking()

        // Android requires delay to fully release foreground service
        await new Promise<void>((resolve) => setTimeout(resolve, SERVICE_RESTART_DELAY_MS))

        await startTracking(newSettings ?? settingsRef.current)
        return true
      } finally {
        restartingRef.current = false
        setIsRestarting(false)

        // Process queued restart if any
        if (restartQueuedRef.current) {
          restartQueuedRef.current = false
          logger.debug("[useLocationTracking] Processing queued restart")
          setTimeout(() => restartTracking(settingsRef.current), RESTART_DEBOUNCE_MS)
        }
      }
    },
    [startTracking, stopTracking]
  )

  /**
   * Restarts the service when the user wants tracking but no started service is alive.
   *
   * Deliberately skips ensurePermissions: the disclosure is already gated on the location
   * grants, but the notification request and the battery-exemption dialog are not, so
   * reusing it would pop system dialogs every time the app is foregrounded.
   */
  const reviveIfDead = useCallback(async (startSettings: Settings) => {
    // Hydration and the foreground handler both reach here on app open, and both would see
    // the service still down while the first start is in flight.
    if (revivingRef.current) return
    revivingRef.current = true

    try {
      const running = await NativeLocationService.isServiceRunning()
      if (running !== false) return // null = unknown, not dead

      const perms = await checkPermissions()
      if (!perms.location) {
        logger.warn("[useLocationTracking] Service is dead and location permission is gone - clearing tracking state")
        await NativeLocationService.saveSetting("tracking_enabled", "false")
        if (listenerRef.current) {
          listenerRef.current.remove()
          listenerRef.current = null
        }
        setTracking(false)
        return
      }

      logger.warn("[useLocationTracking] Tracking is on but the service is not running - restarting")
      await NativeLocationService.start(startSettings)
    } catch (error) {
      logger.error("[useLocationTracking] Restart of a dead service failed:", error)
    } finally {
      revivingRef.current = false
    }
  }, [])

  /**
   * Reconnects React state to a native service that should be running.
   * Used after app restart when tracking_enabled is true in the DB.
   * Does NOT request permissions, but does restart the service if it died.
   */
  const reconnect = useCallback(
    async (startSettings?: Settings) => {
      if (isTrackingRef.current) {
        logger.debug("[useLocationTracking] Already tracking, skip reconnect")
        return
      }

      logger.debug("[useLocationTracking] Reconnecting to active service")
      setTracking(true)

      await reviveIfDead(startSettings ?? settingsRef.current)

      try {
        const latest = await NativeLocationService.getMostRecentLocation()
        if (latest) {
          setCoords({
            latitude: latest.latitude,
            longitude: latest.longitude,
            accuracy: latest.accuracy,
            altitude: latest.altitude ?? 0,
            speed: latest.speed ?? 0,
            bearing: latest.bearing ?? 0,
            timestamp: latest.timestamp ?? Math.floor(Date.now() / 1000),
            battery: latest.battery,
            battery_status: latest.batteryStatus
          })
        }
      } catch (err) {
        logger.error("[useLocationTracking] Failed to fetch location on reconnect:", err)
      }
    },
    [reviveIfDead]
  )

  /**
   * Syncs tracking state and coords when app returns to foreground.
   * Detects external start/stop (e.g. app shortcuts) by comparing UI state
   * against the DB's tracking_enabled flag, and restarts a service the system killed.
   */
  useEffect(() => {
    // Until hydration settingsRef holds DEFAULT_SETTINGS and a revive from here would start the service on them.
    if (!settingsHydrated) return

    const subscription = AppState.addEventListener("change", async (nextState) => {
      if (nextState !== "active") return

      const serviceActive = await NativeLocationService.isTrackingActive().catch(() => null)
      if (serviceActive === null) return

      if (!isTrackingRef.current && serviceActive) {
        // Service was started externally (e.g. start shortcut) - reconnect UI
        logger.debug("[useLocationTracking] External start detected, reconnecting")
        reconnect()
      } else if (isTrackingRef.current && !serviceActive) {
        // Service was stopped externally (e.g. stop shortcut) - update UI
        logger.debug("[useLocationTracking] External stop detected, updating UI")
        if (listenerRef.current) {
          listenerRef.current.remove()
          listenerRef.current = null
        }
        setTracking(false)
      } else if (isTrackingRef.current && serviceActive) {
        // Intent and UI agree, but the service itself may have been killed meanwhile
        await reviveIfDead(settingsRef.current)

        // Refresh coords since events are suppressed while backgrounded
        NativeLocationService.getMostRecentLocation()
          .then((latest) => {
            if (latest) {
              setCoords({
                latitude: latest.latitude,
                longitude: latest.longitude,
                accuracy: latest.accuracy,
                altitude: latest.altitude ?? 0,
                speed: latest.speed ?? 0,
                bearing: latest.bearing ?? 0,
                timestamp: latest.timestamp ?? Math.floor(Date.now() / 1000),
                battery: latest.battery,
                battery_status: latest.batteryStatus
              })
            }
          })
          .catch((err) => {
            logger.error("[useLocationTracking] Failed to fetch location on resume:", err)
          })
      }
    })

    return () => subscription.remove()
  }, [settingsHydrated, reconnect, reviveIfDead])

  /**
   * Cleanup on unmount
   * NOTE: Does NOT stop tracking - service continues in background
   */
  useEffect(() => {
    return () => {
      logger.debug("[useLocationTracking] React component unmounted (foreground service still running)")
      restartQueuedRef.current = false
      restartingRef.current = false
    }
  }, [])

  return {
    coords,
    tracking: tracking || isRestarting,
    startTracking,
    stopTracking,
    restartTracking,
    reconnect,
    settings
  }
}