Colota - Android GPS Location tracker
/**
* Copyright (C) 2026 Max Dietrich
* Licensed under the GNU AGPLv3. See LICENSE in the project root for details.
*/
import React, { createContext, useContext, useState, useEffect, useMemo, useCallback, useRef } from "react"
import { DeviceEventEmitter } from "react-native"
import { Settings, DEFAULT_SETTINGS, LocationCoords, ApiTemplateName, HttpMethod, DawarichMode } from "../types/global"
import { useLocationTracking } from "../hooks/useLocationTracking"
import NativeLocationService from "../services/NativeLocationService"
import SettingsService from "../services/SettingsService"
import { parsePositiveInt } from "../utils/settingsValidation"
import { LocationDisclosureModal } from "../components/ui/LocationDisclosureModal"
import { LocalNetworkDisclosureModal } from "../components/ui/LocalNetworkDisclosureModal"
import { AppModal } from "../components/ui/AppModal"
import { checkPermissions } from "../services/LocationServicePermission"
import { logger } from "../utils/logger"
type TrackingContextType = {
settings: Settings
setSettings: (s: Settings) => Promise<void>
updateSettingsLocal: (s: Settings) => void
tracking: boolean
isLoading: boolean
settingsHydrated: boolean
error: Error | null
activeProfileName: string | null
activeProfileId: number | null
startTracking: () => Promise<void>
stopTracking: () => void
restartTracking: (newSettings?: Settings) => Promise<boolean>
}
const TrackingContext = createContext<TrackingContextType | null>(null)
const CoordsContext = createContext<LocationCoords | null>(null)
function parseJsonOr<T>(raw: string | undefined, fallback: T, key: string): T {
if (!raw) return fallback
try {
return JSON.parse(raw)
} catch (err) {
logger.warn(`[TrackingContext] Corrupted ${key}, using defaults:`, err)
return fallback
}
}
/**
* Parses raw SQLite settings (all strings) into typed Settings object
*/
export function parseRawSettings(allRaw: Record<string, string>): Settings {
return {
...DEFAULT_SETTINGS,
// Convert Android milliseconds back to seconds (UNIX-Timestamp)
interval: allRaw.interval ? parseInt(allRaw.interval, 10) / 1000 : DEFAULT_SETTINGS.interval,
distance: allRaw.minUpdateDistance ? parseFloat(allRaw.minUpdateDistance) : DEFAULT_SETTINGS.distance,
syncInterval: allRaw.syncInterval ? parseInt(allRaw.syncInterval, 10) : DEFAULT_SETTINGS.syncInterval,
retryInterval: allRaw.retryInterval ? parseInt(allRaw.retryInterval, 10) : DEFAULT_SETTINGS.retryInterval,
accuracyThreshold: allRaw.accuracyThreshold
? parseFloat(allRaw.accuracyThreshold)
: DEFAULT_SETTINGS.accuracyThreshold,
// Older installs have no stored key; anything unrecognised falls back to High. Match the native
// LocationAccuracy.fromWire: trim + case-insensitive, so the two never disagree on a hand-edited value.
accuracyMode: allRaw.accuracyMode?.trim().toLowerCase() === "balanced" ? "balanced" : DEFAULT_SETTINGS.accuracyMode,
isOfflineMode: allRaw.isOfflineMode === "true",
syncCondition:
(allRaw.syncCondition as any) ?? (allRaw.isWifiOnlySync === "true" ? "wifi_any" : DEFAULT_SETTINGS.syncCondition),
syncSsid: allRaw.syncSsid ?? DEFAULT_SETTINGS.syncSsid,
endpoint: allRaw.endpoint ?? DEFAULT_SETTINGS.endpoint,
syncPreset: (allRaw.syncPreset as any) ?? DEFAULT_SETTINGS.syncPreset,
filterInaccurateLocations: allRaw.filterInaccurateLocations === "true",
fieldMap: parseJsonOr(allRaw.fieldMap, DEFAULT_SETTINGS.fieldMap, "fieldMap"),
customFields: parseJsonOr(allRaw.customFields, DEFAULT_SETTINGS.customFields, "customFields"),
apiTemplate: (allRaw.apiTemplate as ApiTemplateName) ?? DEFAULT_SETTINGS.apiTemplate,
httpMethod: (allRaw.httpMethod as HttpMethod) ?? DEFAULT_SETTINGS.httpMethod,
dawarichMode: (allRaw.dawarichMode as DawarichMode) ?? DEFAULT_SETTINGS.dawarichMode,
overlandBatchSize: parsePositiveInt(allRaw.overlandBatchSize ?? "", DEFAULT_SETTINGS.overlandBatchSize),
hasCompletedSetup: allRaw.hasCompletedSetup === "true"
}
}
/**
* Global state management for location tracking, device coordinates, and application settings.
*
* This context serves as the "Single Source of Truth" for the entire Colota application,
* bridging the gap between the persistent SQLite storage on Android and the React Native UI.
*
* **Core Responsibilities:**
* 1. **Hydration:** On mount, it fetches raw settings from Native storage and transforms
* them into a typed {@link Settings} object.
* 2. **Persistence:** Synchronizes state changes back to the Native {@link SettingsService}
* to ensure tracking behavior survives app restarts.
* 3. **Tracking Control:** Provides unified methods to start, stop, and restart the
* underlying GPS foreground service.
*/
export function TrackingProvider({ children }: { children: React.ReactNode }) {
const [settings, setSettingsState] = useState<Settings>(DEFAULT_SETTINGS)
// Distinct from isLoading, which the safety timeout below flips without ever filling settings.
const [hydrated, setHydrated] = useState(false)
const [isLoading, setIsLoading] = useState(true)
const [error, setError] = useState<Error | null>(null)
const [activeProfileName, setActiveProfileName] = useState<string | null>(null)
const [activeProfileId, setActiveProfileId] = useState<number | null>(null)
// Ref to track if component is mounted (prevents state updates after unmount)
const isMountedRef = useRef(true)
// Ref to track if initialization has been done (prevents re-running on dependency changes)
const hasInitializedRef = useRef(false)
const settingsReadRef = useRef(false)
/**
* Batch updates settings across both UI state and Native storage.
* Wrapped in useCallback to maintain referential equality.
*/
const setSettings = useCallback(async (newSettings: Settings) => {
// State holds DEFAULT_SETTINGS until the read lands, so a save before then overwrites the stored ones.
if (!settingsReadRef.current) {
const err = new Error("Settings are not loaded, so nothing was saved")
logger.error("[TrackingContext] Save blocked, settings not loaded")
if (isMountedRef.current) setError(err)
throw err
}
try {
logger.debug("[TrackingContext] Batch syncing to Native storage...")
// SettingsService handles unit conversion (seconds -> ms)
await SettingsService.updateMultiple(newSettings)
if (isMountedRef.current) {
setSettingsState(newSettings)
setError(null) // Clear any previous errors
}
} catch (err) {
logger.error("[TrackingContext] Persistence failed:", err)
if (isMountedRef.current) {
setError(err instanceof Error ? err : new Error(String(err)))
}
throw err // Re-throw to allow caller to handle
}
}, [])
const {
coords,
tracking,
startTracking: internalStart,
stopTracking: internalStop,
restartTracking: internalRestart,
reconnect: internalReconnect
} = useLocationTracking(settings, hydrated)
/**
* Initial Hydration Effect.
* Performs a "Type Conversion Bridge" where SQLite results (which are always strings)
* are parsed into their respective JS types (Numbers, Booleans, and JSON objects).
*/
useEffect(() => {
if (hasInitializedRef.current) return
const init = async () => {
try {
logger.debug("[TrackingContext] Hydrating settings and state...")
const allRaw = await NativeLocationService.getAllSettings()
settingsReadRef.current = true
if (!isMountedRef.current) return
// Initialize DB with defaults if empty
if (Object.keys(allRaw).length === 0) {
logger.debug("[TrackingContext] Initializing DB with defaults")
// The table is empty either way, so the defaults on screen are the truth even unwritten.
await setSettings(DEFAULT_SETTINGS).catch((err) =>
logger.error("[TrackingContext] Seeding defaults failed:", err)
)
if (isMountedRef.current) setHydrated(true)
return
}
// Parse settings from raw SQLite data
const mergedSettings = parseRawSettings(allRaw)
if (!isMountedRef.current) return
setSettingsState(mergedSettings)
setHydrated(true)
// Auto-reconnect UI if tracking was active
const isTrackingActive = allRaw.tracking_enabled === "true"
if (isTrackingActive) {
// Verify permission is still granted. Android kills the process
// when permission is revoked, leaving tracking_enabled stale
const perms = await checkPermissions()
if (!perms.location) {
logger.warn("[TrackingContext] Location permission lost, clearing stale tracking state")
await NativeLocationService.saveSetting("tracking_enabled", "false")
return
}
logger.debug("[TrackingContext] Re-syncing UI with active background service")
// Pass the settings we just parsed: the hook's ref still holds the defaults until
// the next render, and a restart from here would start the service configured wrong.
internalReconnect(mergedSettings)
// Restore the active profile from the running service
const profile = await NativeLocationService.getActiveProfile()
logger.debug(`[TrackingContext] Active profile on reconnect: ${profile?.name ?? "(default)"}`)
if (isMountedRef.current) {
setActiveProfileName(profile?.name ?? null)
setActiveProfileId(profile?.id ?? null)
}
}
} catch (err) {
logger.error("[TrackingContext] Hydration failed:", err)
if (isMountedRef.current) {
setError(err instanceof Error ? err : new Error(String(err)))
}
} finally {
if (isMountedRef.current) {
setIsLoading(false)
}
hasInitializedRef.current = true
}
}
init()
// Safety timeout: force isLoading=false if init hangs
const timeout = setTimeout(() => {
if (isMountedRef.current && !hasInitializedRef.current) {
logger.error("[TrackingContext] Initialization timed out after 5s, forcing ready state")
setIsLoading(false)
hasInitializedRef.current = true
}
}, 5000)
// Cleanup function
return () => {
isMountedRef.current = false
clearTimeout(timeout)
}
}, [internalReconnect, setSettings])
// Listen for profile switch events from the native service
useEffect(() => {
const listener = DeviceEventEmitter.addListener("onProfileSwitch", (event) => {
if (isMountedRef.current) {
setActiveProfileName(event?.profileName ?? null)
setActiveProfileId(event?.profileId ?? null)
}
})
return () => listener.remove()
}, [])
/**
* Wrapped tracking controls with useCallback for stable references
*/
const startTracking = useCallback(async () => {
// Same latch as setSettings: an unhydrated start would run the service on DEFAULT_SETTINGS.
if (!settingsReadRef.current) {
const err = new Error("Settings are not loaded, so tracking was not started")
logger.error("[TrackingContext] Start blocked, settings not loaded")
if (isMountedRef.current) setError(err)
throw err
}
try {
await internalStart(settings)
if (isMountedRef.current) {
setError(null)
}
} catch (err) {
logger.error("[TrackingContext] Failed to start tracking:", err)
if (isMountedRef.current) {
setError(err instanceof Error ? err : new Error(String(err)))
}
throw err
}
}, [settings, internalStart])
const stopTracking = useCallback(() => {
try {
internalStop()
if (isMountedRef.current) {
setActiveProfileName(null)
setActiveProfileId(null)
setError(null)
}
} catch (err) {
logger.error("[TrackingContext] Failed to stop tracking:", err)
if (isMountedRef.current) {
setError(err instanceof Error ? err : new Error(String(err)))
}
}
}, [internalStop])
const restartTracking = useCallback(
async (newSettings?: Settings) => {
try {
const restarted = await internalRestart(newSettings || settings)
if (isMountedRef.current) {
setError(null)
}
return restarted
} catch (err) {
logger.error("[TrackingContext] Failed to restart tracking:", err)
if (isMountedRef.current) {
setError(err instanceof Error ? err : new Error(String(err)))
}
throw err
}
},
[settings, internalRestart]
)
/**
* Memoized context value to prevent unnecessary re-renders of consuming components.
* Only updates when the actual values change.
*/
const value = useMemo(
() => ({
settings,
setSettings,
updateSettingsLocal: setSettingsState,
tracking,
isLoading,
settingsHydrated: hydrated,
error,
activeProfileName,
activeProfileId,
startTracking,
stopTracking,
restartTracking
}),
[
settings,
tracking,
isLoading,
hydrated,
error,
activeProfileName,
activeProfileId,
setSettings,
startTracking,
stopTracking,
restartTracking
]
)
return (
<TrackingContext.Provider value={value}>
<CoordsContext.Provider value={coords}>
<LocationDisclosureModal />
<LocalNetworkDisclosureModal />
<AppModal />
{children}
</CoordsContext.Provider>
</TrackingContext.Provider>
)
}
/**
* Custom hook to access tracking state and controls.
* @throws {Error} If used outside of a {@link TrackingProvider}.
* @returns {TrackingContextType} Current tracking state and controller functions.
*/
export function useTracking(): TrackingContextType {
const context = useContext(TrackingContext)
if (!context) {
throw new Error("useTracking must be used within TrackingProvider")
}
return context
}
export function useCoords(): LocationCoords | null {
return useContext(CoordsContext)
}