Skip to content

Colota - Android GPS Location tracker

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

import { OfflineManager, type OfflinePack } from "@maplibre/maplibre-react-native"
import { MAP_STYLE_URL_LIGHT as MAP_STYLE_URL } from "../../../constants"
import NativeLocationService from "../../../services/NativeLocationService"
import { logger } from "../../../utils/logger"
import { formatBytes, formatDecimal } from "../../../utils/format"
import { t } from "../../../i18n/t"

const MIN_ZOOM = 8
const MAX_ZOOM = 14 // mxd.codes / OpenFreeMap caps vector tiles at z14
const TILE_COUNT_LIMIT = 100_000

// Per-zoom size buckets based on observed mxd.codes vector tile sizes.
// Low-zoom tiles contain fewer features; high-zoom tiles grow significantly.
function bytesPerTile(z: number): number {
  if (z < 10) return 10 * 1024
  if (z < 14) return 25 * 1024
  return 50 * 1024
}

// state values from MapLibre's OfflinePackDownloadState (v11 uses string literals)
export const DOWNLOAD_STATE = {
  INACTIVE: "inactive",
  ACTIVE: "active",
  COMPLETE: "complete"
} as const

export interface OfflinePackStatus {
  state: string
  percentage: number
  completedResourceCount: number
  requiredResourceCount: number
  completedResourceSize: number
}

export interface OfflineAreaInfo {
  name: string
  /** Null when the pack's status could not be read, which is not the same as an empty pack. */
  sizeBytes: number | null
  isComplete: boolean
  isActive: boolean
  /** `[west, south, east, north]` as the pack stores it; null only when native gave none. */
  bounds: [number, number, number, number] | null
}

function boundsOf(pack: OfflinePack): OfflineAreaInfo["bounds"] {
  const b = pack.bounds as unknown
  return Array.isArray(b) && b.length === 4 && b.every((n) => typeof n === "number")
    ? (b as [number, number, number, number])
    : null
}

/** Only the terminal state is worth a line; progress fires continuously. */
function progressListener(name: string, onProgress: (status: OfflinePackStatus) => void) {
  return (_pack: unknown, status: unknown) => {
    const s = status as OfflinePackStatus
    if (s.state === DOWNLOAD_STATE.COMPLETE) {
      logger.info(`[OfflinePackManager] Download complete: '${name}', ${formatBytes(s.completedResourceSize ?? 0)}`)
    }
    onProgress(s)
  }
}

function lonToTileX(lon: number, z: number): number {
  return Math.floor(((lon + 180) / 360) * 2 ** z)
}

function latToTileY(lat: number, z: number): number {
  const latRad = (lat * Math.PI) / 180
  return Math.floor(((1 - Math.log(Math.tan(latRad) + 1 / Math.cos(latRad)) / Math.PI) / 2) * 2 ** z)
}

function estimateTileCount(ne: [number, number], sw: [number, number]): number {
  const [eLon, nLat] = ne
  const [wLon, sLat] = sw
  let total = 0
  for (let z = MIN_ZOOM; z <= MAX_ZOOM; z++) {
    const xMin = lonToTileX(wLon, z)
    const xMax = lonToTileX(eLon, z)
    const yMin = latToTileY(nLat, z)
    const yMax = latToTileY(sLat, z)
    total += (xMax - xMin + 1) * (yMax - yMin + 1)
  }
  return total
}

/** Returns true if the area would hit the tile count cap, meaning coverage will be incomplete. */
export function willExceedTileLimit(ne: [number, number], sw: [number, number]): boolean {
  return estimateTileCount(ne, sw) >= TILE_COUNT_LIMIT
}

/** Returns the estimated download size in bytes, using per-zoom tile size buckets. */
export function estimateSizeBytes(ne: [number, number], sw: [number, number]): number {
  const [eLon, nLat] = ne
  const [wLon, sLat] = sw
  let remainingTiles = TILE_COUNT_LIMIT
  let totalBytes = 0
  for (let z = MIN_ZOOM; z <= MAX_ZOOM; z++) {
    const tilesAtZ = Math.min(
      (lonToTileX(eLon, z) - lonToTileX(wLon, z) + 1) * (latToTileY(sLat, z) - latToTileY(nLat, z) + 1),
      remainingTiles
    )
    totalBytes += tilesAtZ * bytesPerTile(z)
    remainingTiles -= tilesAtZ
    if (remainingTiles <= 0) break
  }
  return totalBytes
}

/** Returns a human-readable estimated download size string (e.g. "~45 MB"). */
export function estimateSizeLabel(ne: [number, number], sw: [number, number]): string {
  const mb = estimateSizeBytes(ne, sw) / (1024 * 1024)
  if (mb < 1) return `~${formatDecimal(mb * 1024, 0)} ${t("unit.KB")}`
  if (mb >= 1000) return `~${formatDecimal(mb / 1024, 1)} ${t("unit.GB")}`
  return `~${formatDecimal(mb, 0)} ${t("unit.MB")}`
}

/** Finds a pack by its stored metadata.name (packs are identified by UUID in v11). */
async function findPackByName(name: string): Promise<OfflinePack | null> {
  const packs = await OfflineManager.getPacks()
  return packs.find((p) => (p.metadata as { name?: string })?.name === name) ?? null
}

export async function createOfflinePack(
  name: string,
  ne: [number, number],
  sw: [number, number],
  onProgress: (status: OfflinePackStatus) => void,
  onError: (err: unknown) => void
): Promise<void> {
  const existing = await findPackByName(name)
  if (existing) throw new Error(`An offline area named "${name}" already exists`)

  const customStyleUrl = await NativeLocationService.getSetting("mapStyleUrlLight")
  const mapStyle = customStyleUrl || MAP_STYLE_URL

  OfflineManager.setTileCountLimit(TILE_COUNT_LIMIT)

  logger.info(`[OfflinePackManager] Downloading '${name}': z${MIN_ZOOM}-${MAX_ZOOM}, ${estimateSizeLabel(ne, sw)}`)

  await OfflineManager.createPack(
    {
      mapStyle,
      minZoom: MIN_ZOOM,
      maxZoom: MAX_ZOOM,
      bounds: [sw[0], sw[1], ne[0], ne[1]],
      metadata: { name }
    },
    progressListener(name, onProgress),
    (_pack, err) => onError(err)
  )
}

/**
 * Re-attaches to a download this JS instance did not start, and returns where it stands. Observing
 * a pack sets it active natively, so this is only for a pack native already reports as active: on
 * anything else it would start a download nobody asked for.
 */
export async function subscribeOfflinePack(
  name: string,
  onProgress: (status: OfflinePackStatus) => void,
  onError: (err: unknown) => void
): Promise<OfflinePackStatus | null> {
  const pack = await findPackByName(name)
  if (!pack) return null
  const status = (await pack.status()) as OfflinePackStatus
  await OfflineManager.addListener(pack.id, progressListener(name, onProgress), (_pack, err) => onError(err))
  logger.info(`[OfflinePackManager] Re-attached to '${name}' at ${Math.round(status.percentage)}%`)
  return status
}

export async function loadOfflineAreas(): Promise<OfflineAreaInfo[]> {
  const packs = await OfflineManager.getPacks()

  const results = await Promise.all(
    packs.map(async (pack): Promise<OfflineAreaInfo | null> => {
      const name = (pack.metadata as { name?: string })?.name
      if (!name) return null
      try {
        const status = await pack.status()
        return {
          name,
          sizeBytes: status?.completedResourceSize ?? null,
          isComplete: status?.state === DOWNLOAD_STATE.COMPLETE,
          isActive: status?.state === DOWNLOAD_STATE.ACTIVE,
          bounds: boundsOf(pack)
        }
      } catch (err) {
        logger.warn(`[OfflinePackManager] Status unreadable for pack '${name}':`, err)
        return { name, sizeBytes: null, isComplete: false, isActive: false, bounds: boundsOf(pack) }
      }
    })
  )
  return results.filter((r): r is OfflineAreaInfo => r !== null)
}

/** Stops any active download for the pack and removes it and its tiles from disk. */
export async function deleteOfflineArea(name: string): Promise<void> {
  const pack = await findPackByName(name)
  if (pack) {
    OfflineManager.removeListener(pack.id)
    try {
      await pack.pause()
    } catch {
      // pack may already be inactive - proceed to delete
    }
    await OfflineManager.deletePack(pack.id)
    logger.info(`[OfflinePackManager] Deleted offline area '${name}'`)
  } else {
    logger.debug(`[OfflinePackManager] No pack named '${name}' to delete`)
  }

  // SQLite does not shrink the database file when rows are deleted - freed pages
  // stay allocated until the database is recreated. If this was the last pack,
  // reset the database so the OS reclaims the storage space.
  const remaining = await OfflineManager.getPacks()
  if (remaining.length === 0) {
    logger.info("[OfflinePackManager] Last area removed, resetting the tile database to reclaim space")
    await OfflineManager.resetDatabase()
  }
}

export async function unsubscribeOfflinePack(name: string): Promise<void> {
  const pack = await findPackByName(name)
  if (pack) OfflineManager.removeListener(pack.id)
}

// ---------------------------------------------------------------------------
// Bounds persistence - stored as JSON in the settings table
// ---------------------------------------------------------------------------

const BOUNDS_KEY = "offline_area_bounds"

export interface OfflineAreaBounds {
  name: string
  ne: [number, number] // [lon, lat]
  sw: [number, number] // [lon, lat]
  styleUrl?: string
  downloadedAt?: number // Unix ms, set when the download completes
}

/** Reads the stored list. Throws when it cannot be read, so a writer can tell empty from failed. */
async function readOfflineAreaBoundsOrThrow(): Promise<OfflineAreaBounds[]> {
  // A rejection here means the value is intact but unreachable, so a writer must not overwrite it.
  const json = await NativeLocationService.getSetting(BOUNDS_KEY, "[]")

  let parsed: unknown[]
  try {
    parsed = JSON.parse(json ?? "[]") as unknown[]
  } catch (err) {
    // Unrecoverable either way, so refusing would leave the key unwritable for good. Repair it.
    logger.warn("[OfflinePackManager] Stored area bounds are malformed, starting a fresh list:", err)
    return []
  }
  // Filter out entries from the old schema (lat/lon/radiusMeters) that lack ne/sw
  return parsed.filter(
    (b): b is OfflineAreaBounds =>
      typeof b === "object" &&
      b !== null &&
      "ne" in b &&
      "sw" in b &&
      Array.isArray((b as OfflineAreaBounds).ne) &&
      Array.isArray((b as OfflineAreaBounds).sw)
  )
}

/** Display path: an unreadable list shows as empty, since there is nothing to render either way. */
export async function loadOfflineAreaBounds(): Promise<OfflineAreaBounds[]> {
  try {
    return await readOfflineAreaBoundsOrThrow()
  } catch (err) {
    logger.error("[OfflinePackManager] Failed to read saved area bounds:", err)
    return []
  }
}

export async function saveOfflineAreaBounds(entry: OfflineAreaBounds): Promise<void> {
  let existing: OfflineAreaBounds[]
  try {
    existing = await readOfflineAreaBoundsOrThrow()
  } catch (err) {
    logger.error(
      `[OfflinePackManager] Not saving bounds for '${entry.name}': stored list unreadable, so the area will not be re-downloadable after a restart:`,
      err
    )
    return
  }
  const updated = [...existing.filter((b) => b.name !== entry.name), entry]
  await NativeLocationService.saveSetting(BOUNDS_KEY, JSON.stringify(updated))
}

export async function removeOfflineAreaBounds(name: string): Promise<void> {
  let existing: OfflineAreaBounds[]
  try {
    existing = await readOfflineAreaBoundsOrThrow()
  } catch (err) {
    logger.error(`[OfflinePackManager] Not removing bounds for '${name}', stored list unreadable:`, err)
    return
  }
  const updated = existing.filter((b) => b.name !== name)
  await NativeLocationService.saveSetting(BOUNDS_KEY, JSON.stringify(updated))
}

/** Drops entries whose pack is gone, in one write, so a list of orphans cannot race itself. */
export async function pruneOfflineAreaBounds(keep: ReadonlySet<string>): Promise<void> {
  let existing: OfflineAreaBounds[]
  try {
    existing = await readOfflineAreaBoundsOrThrow()
  } catch (err) {
    logger.error("[OfflinePackManager] Not pruning bounds, stored list unreadable:", err)
    return
  }
  const kept = existing.filter((b) => keep.has(b.name))
  if (kept.length === existing.length) return
  await NativeLocationService.saveSetting(BOUNDS_KEY, JSON.stringify(kept))
}