flatland_client_lib/
assets.rs

1//! Gfx sprite bundle sync for installed clients (Firebase Storage / GCS).
2
3use std::collections::BTreeMap;
4use std::io::Read;
5use std::path::{Path, PathBuf};
6
7use serde::{Deserialize, Serialize};
8use sha2::{Digest, Sha256};
9
10pub const DEFAULT_FIREBASE_BUCKET: &str = "flatland-8911e.appspot.com";
11pub const ASSETS_INDEX_OBJECT: &str = "flatland3/client-assets/latest.json";
12
13#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
14pub struct AssetFileEntry {
15    pub sha256: String,
16    pub size: u64,
17}
18
19#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
20pub struct AssetBundleIndex {
21    /// Stable revision from `assets/.content-publish.json` (not process-local `content_rev`).
22    pub publish_rev: u64,
23    pub published_at: String,
24    pub files: BTreeMap<String, AssetFileEntry>,
25}
26
27#[derive(Debug, Clone, Serialize, Deserialize, Default)]
28pub struct LocalAssetState {
29    pub publish_rev: u64,
30    pub sprites_dir: PathBuf,
31}
32
33pub fn assets_root_dir() -> anyhow::Result<PathBuf> {
34    let base = dirs::home_dir().ok_or_else(|| anyhow::anyhow!("home directory not found"))?;
35    Ok(base.join(".flatland3").join("assets"))
36}
37
38pub fn local_state_path() -> anyhow::Result<PathBuf> {
39    Ok(assets_root_dir()?.join("state.json"))
40}
41
42pub fn read_local_state() -> Option<LocalAssetState> {
43    let path = local_state_path().ok()?;
44    let bytes = std::fs::read(path).ok()?;
45    serde_json::from_slice(&bytes).ok()
46}
47
48pub fn write_local_state(state: &LocalAssetState) -> anyhow::Result<()> {
49    let path = local_state_path()?;
50    if let Some(parent) = path.parent() {
51        std::fs::create_dir_all(parent)?;
52    }
53    std::fs::write(path, serde_json::to_vec_pretty(state)?)?;
54    Ok(())
55}
56
57pub fn sprites_dir_for_rev(publish_rev: u64) -> anyhow::Result<PathBuf> {
58    Ok(assets_root_dir()?.join(format!("rev-{publish_rev}")))
59}
60
61pub fn current_symlink_path() -> anyhow::Result<PathBuf> {
62    Ok(assets_root_dir()?.join("current"))
63}
64
65pub fn activate_rev_dir(rev_dir: &Path) -> anyhow::Result<()> {
66    let link = current_symlink_path()?;
67    if link.exists() {
68        std::fs::remove_file(&link).or_else(|_| std::fs::remove_dir_all(&link))?;
69    }
70    #[cfg(unix)]
71    {
72        std::os::unix::fs::symlink(rev_dir, &link)?;
73    }
74    #[cfg(not(unix))]
75    {
76        // Windows: record the active rev path beside `current` (no symlink required).
77        let marker = link.with_extension("path");
78        std::fs::write(&marker, rev_dir.to_string_lossy().as_bytes())?;
79        let _ = std::fs::create_dir_all(&link);
80        let _ = std::fs::copy(rev_dir.join("manifest.yaml"), link.join("manifest.yaml"));
81    }
82    Ok(())
83}
84
85pub fn find_repo_sprites_dir() -> Option<PathBuf> {
86    let mut dir = std::env::current_dir().ok()?;
87    for _ in 0..8 {
88        let candidate = dir.join("assets/gfx/sprites");
89        if candidate.join("manifest.yaml").is_file() {
90            return Some(candidate);
91        }
92        if !dir.pop() {
93            break;
94        }
95    }
96    None
97}
98
99/// True when the checkout sprites should win over a synced `~/.flatland3` cache.
100pub(crate) fn repo_sprites_outrank_cache(repo_rev: Option<u64>, local_rev: Option<u64>) -> bool {
101    match (repo_rev, local_rev) {
102        (Some(rr), Some(lr)) => rr >= lr,
103        (Some(_), None) => true,
104        _ => false,
105    }
106}
107
108/// Prefer the repo checkout when it is at least as new as the synced cache.
109///
110/// Local play often has a stale `~/.flatland3/assets/rev-N` from an older sync.
111/// `needs_asset_sync` already treats a matching repo as up to date, but loading
112/// still went through the stale cache — so new sheets (e.g. lodging) fell back
113/// to `other.default` after publish.
114pub fn resolve_sprites_dir() -> Option<PathBuf> {
115    if let Ok(p) = std::env::var("FLATLAND_SPRITES_DIR") {
116        let path = PathBuf::from(p);
117        if path.join("manifest.yaml").is_file() {
118            return Some(path);
119        }
120    }
121
122    let repo = find_repo_sprites_dir();
123    let repo_rev = read_repo_publish_rev();
124    let local = read_local_state().filter(|s| s.sprites_dir.join("manifest.yaml").is_file());
125    let local_rev = local.as_ref().map(|s| s.publish_rev);
126
127    if repo_sprites_outrank_cache(repo_rev, local_rev) {
128        if let Some(repo_dir) = repo {
129            return Some(repo_dir);
130        }
131    }
132    if let Some(local) = local {
133        return Some(local.sprites_dir);
134    }
135    if let Some(repo_dir) = repo {
136        return Some(repo_dir);
137    }
138
139    let current = current_symlink_path().ok()?;
140    if current.join("manifest.yaml").is_file() {
141        return Some(current);
142    }
143    None
144}
145
146pub fn assets_index_url() -> String {
147    std::env::var("FLATLAND_ASSETS_INDEX_URL").unwrap_or_else(|_| {
148        firebase_download_url(DEFAULT_FIREBASE_BUCKET, ASSETS_INDEX_OBJECT)
149    })
150}
151
152pub fn firebase_download_url(bucket: &str, object_path: &str) -> String {
153    let encoded = urlencoding_encode(object_path);
154    format!(
155        "https://firebasestorage.googleapis.com/v0/b/{bucket}/o/{encoded}?alt=media"
156    )
157}
158
159pub fn assets_storage_prefix() -> String {
160    std::env::var("FLATLAND_ASSETS_PREFIX")
161        .unwrap_or_else(|_| "flatland3/client-assets".to_string())
162}
163
164pub fn firebase_object_path_for_prefix(prefix: &str, publish_rev: u64, relative: &str) -> String {
165    format!("{prefix}/rev-{publish_rev}/{relative}")
166}
167
168pub fn firebase_object_path(publish_rev: u64, relative: &str) -> String {
169    firebase_object_path_for_prefix(&assets_storage_prefix(), publish_rev, relative)
170}
171
172fn urlencoding_encode(path: &str) -> String {
173    path.bytes()
174        .map(|b| match b {
175            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
176                (b as char).to_string()
177            }
178            _ => format!("%{b:02X}"),
179        })
180        .collect()
181}
182
183pub fn sha256_file(path: &Path) -> anyhow::Result<String> {
184    let mut file = std::fs::File::open(path)?;
185    let mut hasher = Sha256::new();
186    let mut buf = [0u8; 8192];
187    loop {
188        let n = file.read(&mut buf)?;
189        if n == 0 {
190            break;
191        }
192        hasher.update(&buf[..n]);
193    }
194    Ok(hex::encode(hasher.finalize()))
195}
196
197/// Walk `assets/gfx/sprites` and build a publish manifest (relative paths → hash).
198pub fn build_bundle_index(sprites_dir: &Path, publish_rev: u64, published_at: &str) -> anyhow::Result<AssetBundleIndex> {
199    let mut files = BTreeMap::new();
200    walk_sprites_dir(sprites_dir, sprites_dir, &mut files)?;
201    Ok(AssetBundleIndex {
202        publish_rev,
203        published_at: published_at.to_string(),
204        files,
205    })
206}
207
208fn walk_sprites_dir(
209    root: &Path,
210    dir: &Path,
211    files: &mut BTreeMap<String, AssetFileEntry>,
212) -> anyhow::Result<()> {
213    for entry in std::fs::read_dir(dir)? {
214        let entry = entry?;
215        let path = entry.path();
216        if path.is_dir() {
217            let name = entry.file_name();
218            if name == "previews" {
219                continue;
220            }
221            walk_sprites_dir(root, &path, files)?;
222            continue;
223        }
224        let rel = path
225            .strip_prefix(root)?
226            .to_string_lossy()
227            .replace('\\', "/");
228        if rel.starts_with('.') || rel.contains("/.") {
229            continue;
230        }
231        if rel.ends_with(".html") {
232            continue;
233        }
234        let meta = std::fs::metadata(&path)?;
235        files.insert(
236            rel,
237            AssetFileEntry {
238                sha256: sha256_file(&path)?,
239                size: meta.len(),
240            },
241        );
242    }
243    Ok(())
244}
245
246pub struct AssetSyncOptions {
247    pub index_url: String,
248    pub storage_prefix: String,
249    pub target_rev: Option<u64>,
250    pub quiet: bool,
251}
252
253/// Outcome of [`sync_assets`] for logging / HUD toasts.
254#[derive(Debug, Clone, Copy, PartialEq, Eq)]
255pub enum AssetSyncKind {
256    /// Downloaded or verified files against remote `latest.json`.
257    Remote,
258    /// Remote index missing; reused `~/.flatland3` cache.
259    LocalCacheNoRemote,
260    /// Remote index missing; using repo `assets/gfx/sprites` (dev checkout).
261    RepoDevNoRemote,
262}
263
264#[derive(Debug, Clone)]
265pub struct AssetSyncResult {
266    pub state: LocalAssetState,
267    pub kind: AssetSyncKind,
268}
269
270impl Default for AssetSyncOptions {
271    fn default() -> Self {
272        Self {
273            index_url: assets_index_url(),
274            storage_prefix: assets_storage_prefix(),
275            target_rev: None,
276            quiet: false,
277        }
278    }
279}
280
281pub async fn sync_assets(opts: AssetSyncOptions) -> anyhow::Result<AssetSyncResult> {
282    // Local checkout: prefer repo sprites and skip remote download so gfx play does not
283    // freeze on Firebase after login (no render loop until sync finishes).
284    if std::env::var_os("FLATLAND_FORCE_ASSET_SYNC").is_none() {
285        if let Some(repo_dir) = find_repo_sprites_dir() {
286            if let Some(publish_rev) = read_repo_publish_rev() {
287                if opts.target_rev.map_or(true, |t| publish_rev >= t) {
288                    if !opts.quiet {
289                        println!(
290                            "Using repo sprites at {} (rev {publish_rev}); set FLATLAND_FORCE_ASSET_SYNC=1 to pull remote.",
291                            repo_dir.display()
292                        );
293                    }
294                    return Ok(AssetSyncResult {
295                        state: LocalAssetState {
296                            publish_rev,
297                            sprites_dir: repo_dir,
298                        },
299                        kind: AssetSyncKind::RepoDevNoRemote,
300                    });
301                }
302            }
303        }
304    }
305
306    let client = reqwest::Client::builder()
307        .user_agent(format!("flatland-client-lib/{}", env!("CARGO_PKG_VERSION")))
308        .connect_timeout(std::time::Duration::from_secs(5))
309        .timeout(std::time::Duration::from_secs(30))
310        .build()?;
311    let response = client.get(&opts.index_url).send().await?;
312    if response.status() == reqwest::StatusCode::NOT_FOUND {
313        return sync_without_remote_index(opts);
314    }
315    let index: AssetBundleIndex = response.error_for_status()?.json().await?;
316    sync_from_index(&client, opts, index).await
317}
318
319fn sync_without_remote_index(opts: AssetSyncOptions) -> anyhow::Result<AssetSyncResult> {
320    if let Some(local) = read_local_state() {
321        if local.sprites_dir.join("manifest.yaml").is_file() {
322            if !opts.quiet {
323                println!(
324                    "Remote latest.json not found; using cached publish rev {}.",
325                    local.publish_rev
326                );
327            }
328            return Ok(AssetSyncResult {
329                state: local,
330                kind: AssetSyncKind::LocalCacheNoRemote,
331            });
332        }
333    }
334    if let Some(repo) = find_repo_sprites_dir() {
335        let publish_rev = read_repo_publish_rev().unwrap_or(0);
336        if !opts.quiet {
337            println!(
338                "Remote latest.json not found; using repo sprites at {} (rev {publish_rev}).",
339                repo.display()
340            );
341        }
342        return Ok(AssetSyncResult {
343            state: LocalAssetState {
344                publish_rev,
345                sprites_dir: repo,
346            },
347            kind: AssetSyncKind::RepoDevNoRemote,
348        });
349    }
350    anyhow::bail!(
351        "Gfx asset bundle not published yet (HTTP 404 on latest.json). \
352         Server admin: flatland-admin content publish"
353    );
354}
355
356async fn sync_from_index(
357    client: &reqwest::Client,
358    opts: AssetSyncOptions,
359    index: AssetBundleIndex,
360) -> anyhow::Result<AssetSyncResult> {
361    let publish_rev = opts.target_rev.unwrap_or(index.publish_rev);
362    if publish_rev != index.publish_rev {
363        anyhow::bail!(
364            "requested publish rev {publish_rev} but remote latest is {}",
365            index.publish_rev
366        );
367    }
368
369    if let Some(local) = read_local_state() {
370        if local.publish_rev == publish_rev && local.sprites_dir.join("manifest.yaml").is_file() {
371            if verify_rev_dir(&local.sprites_dir, &index)? {
372                if !opts.quiet {
373                    println!("Assets up to date (publish rev {publish_rev}).");
374                }
375                return Ok(AssetSyncResult {
376                    state: local,
377                    kind: AssetSyncKind::Remote,
378                });
379            }
380        }
381    }
382
383    let rev_dir = sprites_dir_for_rev(publish_rev)?;
384    std::fs::create_dir_all(&rev_dir)?;
385
386    let total = index.files.len();
387    let mut done = 0usize;
388    for (rel, entry) in &index.files {
389        let dest = rev_dir.join(rel);
390        if dest.is_file() {
391            if sha256_file(&dest)? == entry.sha256 {
392                done += 1;
393                continue;
394            }
395        }
396        if let Some(parent) = dest.parent() {
397            std::fs::create_dir_all(parent)?;
398        }
399        let url = firebase_download_url(
400            DEFAULT_FIREBASE_BUCKET,
401            &firebase_object_path_for_prefix(&opts.storage_prefix, publish_rev, rel),
402        );
403        let bytes = client.get(&url).send().await?.error_for_status()?.bytes().await?;
404        if sha256_bytes(&bytes) != entry.sha256 {
405            anyhow::bail!("hash mismatch for {rel} after download");
406        }
407        std::fs::write(&dest, &bytes)?;
408        done += 1;
409        if !opts.quiet {
410            println!("  [{done}/{total}] {rel}");
411        }
412    }
413
414    activate_rev_dir(&rev_dir)?;
415    let state = LocalAssetState {
416        publish_rev,
417        sprites_dir: rev_dir,
418    };
419    write_local_state(&state)?;
420    if !opts.quiet {
421        println!(
422            "Synced publish rev {publish_rev} → {}",
423            state.sprites_dir.display()
424        );
425    }
426    Ok(AssetSyncResult {
427        state,
428        kind: AssetSyncKind::Remote,
429    })
430}
431
432pub fn needs_asset_sync(server_publish_rev: u64) -> bool {
433    if server_publish_rev == 0 {
434        return false;
435    }
436    if let Some(local) = read_local_state() {
437        if local.publish_rev >= server_publish_rev
438            && local.sprites_dir.join("manifest.yaml").is_file()
439        {
440            return false;
441        }
442    }
443    if let Some(repo_rev) = read_repo_publish_rev() {
444        if repo_rev >= server_publish_rev && find_repo_sprites_dir().is_some() {
445            return false;
446        }
447    }
448    resolve_sprites_dir().is_none()
449}
450
451/// Publish rev from `assets/.content-publish.json` when running from a dev checkout.
452pub fn read_repo_publish_rev() -> Option<u64> {
453    let sprites = find_repo_sprites_dir()?;
454    let mut dir = sprites.as_path();
455    for _ in 0..8 {
456        let marker = dir.join(".content-publish.json");
457        if marker.is_file() {
458            #[derive(Deserialize)]
459            struct Marker {
460                rev: u64,
461            }
462            let text = std::fs::read_to_string(marker).ok()?;
463            let m: Marker = serde_json::from_str(&text).ok()?;
464            return Some(m.rev);
465        }
466        dir = dir.parent()?;
467    }
468    None
469}
470
471fn verify_rev_dir(dir: &Path, index: &AssetBundleIndex) -> anyhow::Result<bool> {
472    for (rel, entry) in &index.files {
473        let path = dir.join(rel);
474        if !path.is_file() {
475            return Ok(false);
476        }
477        if sha256_file(&path)? != entry.sha256 {
478            return Ok(false);
479        }
480    }
481    Ok(true)
482}
483
484fn sha256_bytes(bytes: &[u8]) -> String {
485    let mut hasher = Sha256::new();
486    hasher.update(bytes);
487    hex::encode(hasher.finalize())
488}
489
490#[cfg(test)]
491mod tests {
492    use super::*;
493    use std::fs;
494
495    #[test]
496    fn firebase_url_encodes_slashes() {
497        let url = firebase_download_url("bucket", "flatland3/client-assets/latest.json");
498        assert!(url.contains("%2F"));
499        assert!(url.contains("alt=media"));
500    }
501
502    #[test]
503    fn build_index_hashes_files() {
504        let dir = std::env::temp_dir().join(format!("flatland-assets-test-{}", std::process::id()));
505        let _ = fs::remove_dir_all(&dir);
506        fs::create_dir_all(dir.join("cells")).expect("dir");
507        fs::write(dir.join("manifest.yaml"), "version: 1\n").expect("write");
508        fs::write(dir.join("cells/a.png"), b"png").expect("write");
509        let index = build_bundle_index(&dir, 3, "2026-01-01T00:00:00Z").expect("index");
510        assert_eq!(index.publish_rev, 3);
511        assert_eq!(index.files.len(), 2);
512        let _ = fs::remove_dir_all(&dir);
513    }
514
515    #[test]
516    fn needs_sync_false_when_repo_matches_server_rev() {
517        if read_repo_publish_rev().is_some() && find_repo_sprites_dir().is_some() {
518            let rev = read_repo_publish_rev().unwrap();
519            assert!(!needs_asset_sync(rev));
520        }
521    }
522
523    #[test]
524    fn repo_outranks_stale_synced_cache() {
525        assert!(repo_sprites_outrank_cache(Some(85), Some(75)));
526        assert!(repo_sprites_outrank_cache(Some(75), Some(75)));
527        assert!(!repo_sprites_outrank_cache(Some(70), Some(75)));
528        assert!(repo_sprites_outrank_cache(Some(85), None));
529        assert!(!repo_sprites_outrank_cache(None, Some(75)));
530    }
531}
flatland_client_lib/assets.rs

flatland_client_lib/
assets.rs
