Skip to main content

utz_build/
loader.rs

1//! This module loads the source data. The source is OSM
2//! timezone-boundary-builder; datasets pick ocean cover (with-oceans or
3//! land-only) and the zone set: `now` (64 zones, default), `1970`
4//! (304 zones), or `all` (444 zones).
5//!
6//! The flow downloads the `GeoJSON` zip (with a conditional GET) and
7//! parses it.
8
9use std::io::{BufReader, Read as _};
10use std::path::Path;
11
12use serde::Deserialize;
13
14use crate::{Dataset, Error, Feat, download};
15use utz_encode::{Poly, Ring};
16
17const REPO: &str = "https://github.com/evansiroky/timezone-boundary-builder";
18
19/// Resolves the tag `releases/latest` points at by reading its redirect
20/// (`…/releases/tag/<tag>`), so no API and no auth are needed. The tag is
21/// cached in `<cache_dir>/tzbb-release.tag` so offline regeneration keeps
22/// it, and `UTZ_TZBB_RELEASE` pins a tag explicitly (skipping the probe).
23/// With no network and no cached tag, the function falls back to `"dev"`
24/// with a warning; the per-release zip cache (`tzbb/<release>/`) will
25/// then be empty, so a first-ever offline run fails at download rather
26/// than serving mislabeled bytes.
27///
28/// # Errors
29/// Returns an error only for an I/O failure while caching the freshly
30/// probed tag (probe failures themselves fall back to the cached tag or
31/// `"dev"`).
32pub fn resolve_release(cache_dir: &Path) -> crate::Result<String> {
33    if let Ok(tag) = std::env::var("UTZ_TZBB_RELEASE")
34        && !tag.is_empty()
35    {
36        return Ok(tag);
37    }
38    let tag_file = cache_dir.join("tzbb-release.tag");
39    let probed: crate::Result<String> = (|| {
40        let agent: ureq::Agent = ureq::Agent::config_builder()
41            .max_redirects(0)
42            .build()
43            .into();
44        let response = agent.get(format!("{REPO}/releases/latest")).call()?;
45        response
46            .headers()
47            .get("location")
48            .and_then(|value| value.to_str().ok())
49            .and_then(|location| location.split_once("/releases/tag/"))
50            .map(|(_, tag)| tag.trim_matches('/').to_string())
51            .filter(|tag| !tag.is_empty())
52            .ok_or_else(|| Error::NoReleaseRedirect {
53                status: response.status().as_u16(),
54            })
55    })();
56    match probed {
57        Ok(tag) => {
58            std::fs::create_dir_all(cache_dir)?;
59            std::fs::write(&tag_file, &tag)?;
60            Ok(tag)
61        }
62        Err(error) => {
63            if let Some(tag) = std::fs::read_to_string(&tag_file)
64                .ok()
65                .map(|contents| contents.trim().to_string())
66                .filter(|tag| !tag.is_empty())
67            {
68                eprintln!(
69                    "warning: resolving latest TZBB release failed ({error}); using cached tag {tag}"
70                );
71                return Ok(tag);
72            }
73            eprintln!(
74                "warning: resolving latest TZBB release failed ({error}); tagging asset \"dev\""
75            );
76            Ok("dev".into())
77        }
78    }
79}
80
81/// Builds the URL of the TZBB release asset for a dataset, pinned to
82/// `release` (so the bytes and the header tag can't skew). In TZBB
83/// naming, the unsuffixed release is the "Comprehensive" set (μTZ `all`),
84/// the `-1970` suffix is "Same since 1970", `-now` is "Same since now",
85/// and `with-oceans` selects ocean cover.
86#[must_use]
87pub fn dataset_url(dataset: Dataset, release: &str) -> String {
88    let oceans = if dataset.oceans() { "-with-oceans" } else { "" };
89    let zone_set = match dataset.zone_set() {
90        "all" => "",
91        set_name => &format!("-{set_name}"),
92    };
93    format!("{REPO}/releases/download/{release}/timezones{oceans}{zone_set}.geojson.zip")
94}
95
96/// Downloads (revalidating) and parses a dataset into `Feat`s, returning
97/// the features plus the TZBB release tag they came from.
98///
99/// # Errors
100/// Returns any release-tag caching, download, or zip/`GeoJSON` parse
101/// failure.
102pub fn load_tzbb(dataset: Dataset, cache_dir: &Path) -> crate::Result<(Vec<Feat>, String)> {
103    let release = resolve_release(cache_dir)?;
104    // key the download by release: TZBB asset basenames are
105    // release-independent, and a flat cache would serve one release's
106    // bytes under another's tag when offline
107    let release_dir = cache_dir.join("tzbb").join(&release);
108    let zip_path = download::fetch(&dataset_url(dataset, &release), &release_dir)?;
109    Ok((load_geojson_zip(&zip_path)?, release))
110}
111
112/// Parses the first `.json`/`.geojson` entry of a TZBB release zip.
113///
114/// # Errors
115/// Returns an I/O or zip-archive failure, an error when the zip has no
116/// `.json`/`.geojson` entry, or a `GeoJSON` parse failure.
117pub fn load_geojson_zip(path: &Path) -> crate::Result<Vec<Feat>> {
118    let file = std::fs::File::open(path)?;
119    let mut zip = zip::ZipArchive::new(BufReader::new(file))?;
120    let name = (0..zip.len())
121        .map(|i| zip.name_for_index(i).unwrap_or("").to_string())
122        .find(|entry_name| {
123            Path::new(entry_name).extension().is_some_and(|extension| {
124                extension.eq_ignore_ascii_case("json") || extension.eq_ignore_ascii_case("geojson")
125            })
126        })
127        .ok_or_else(|| Error::NoGeojsonEntry { path: path.into() })?;
128    let mut bytes = Vec::new();
129    zip.by_name(&name)?.read_to_end(&mut bytes)?;
130    parse_geojson(&bytes)
131}
132
133// Typed mirror of the TZBB FeatureCollection: serde deserializes coordinates
134// straight into f64 pairs (no Value DOM — the -now file alone is ~150 MB).
135#[derive(Deserialize)]
136struct Fc {
137    features: Vec<GjFeature>,
138}
139#[derive(Deserialize)]
140struct GjFeature {
141    properties: Props,
142    geometry: Geom,
143}
144#[derive(Deserialize)]
145struct Props {
146    tzid: Option<String>,
147}
148#[derive(Deserialize)]
149#[serde(tag = "type")]
150enum Geom {
151    Polygon {
152        coordinates: Vec<Vec<[f64; 2]>>,
153    },
154    MultiPolygon {
155        coordinates: Vec<Vec<Vec<[f64; 2]>>>,
156    },
157}
158
159/// Deserializes a TZBB `GeoJSON` `FeatureCollection` into `Feat`s.
160///
161/// # Errors
162/// Returns an error for JSON that doesn't deserialize as a
163/// Polygon/`MultiPolygon` `FeatureCollection`.
164pub fn parse_geojson(bytes: &[u8]) -> crate::Result<Vec<Feat>> {
165    let collection: Fc = serde_json::from_slice(bytes)?;
166    Ok(collection
167        .features
168        .into_iter()
169        .map(|feature| {
170            let polys: Vec<Poly> = match feature.geometry {
171                Geom::Polygon { coordinates } => vec![rings_of(coordinates)],
172                Geom::MultiPolygon { coordinates } => {
173                    coordinates.into_iter().map(rings_of).collect()
174                }
175            };
176            Feat {
177                offset: 0.0,
178                tzid: feature.properties.tzid,
179                polys,
180            }
181        })
182        .collect())
183}
184
185fn rings_of(rings: Vec<Vec<[f64; 2]>>) -> Poly {
186    rings
187        .into_iter()
188        .map(|ring| strip_close(ring.into_iter().map(|[x, y]| (x, y)).collect()))
189        .collect()
190}
191
192fn strip_close(mut ring: Ring) -> Ring {
193    if ring.len() > 1 && ring.first() == ring.last() {
194        ring.pop();
195    }
196    ring
197}