Colota - Android GPS Location tracker
/**
* 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
}
}