Skip to main content

zombienet_orchestrator/generators/
db_snapshot.rs

1//! Resolve `db_snapshot` `AssetLocation`s into local cache paths, once per
2//! unique location, **before** the parallel spawn fanout.
3//!
4//! Cache layout is: `{ns_base_dir}/{sha256(loc_str)}.tgz`. The
5//! provider's `initialize_db_snapshot` takes this already-resolved file and
6//! only has to extract it.
7//!
8//! The exception is a URL for a provider whose fileserver can fetch it
9//! itself ([`ProviderCapabilities::fileserver_fetches_db_snapshot_url`],
10//! k8s). The fileserver downloads it once, under the same
11//! `sha256(loc_str).tgz` name, and every node curls it from there as it would
12//! an uploaded one. Downloading it here instead would hold the whole snapshot
13//! in this host's memory and then upload it to that same fileserver — for
14//! every distinct snapshot, gigabytes each for a forked public network.
15//!
16//! [`ProviderCapabilities::fileserver_fetches_db_snapshot_url`]: provider::types::ProviderCapabilities
17
18use std::{collections::HashMap, path::Path};
19
20use configuration::types::AssetLocation;
21use provider::{types::DbSnapshot, DynNamespace, ProviderError};
22use sha2::Digest;
23use support::fs::FileSystem;
24use tracing::trace;
25
26use crate::network_spec::node::NodeSpec;
27
28/// Lookup map produced by [`resolve_db_snapshots`].
29pub type ResolvedDbSnapshots = HashMap<AssetLocation, DbSnapshot>;
30
31/// Walk every node's `db_snapshot`, deduplicate by `AssetLocation`, and
32/// fetch each unique location once: into the namespace cache, or into the
33/// namespace's fileserver (see the module docs). Returns a map from the
34/// original `AssetLocation` to what the provider is handed for it.
35pub async fn resolve_db_snapshots<'a, FS, I>(
36    nodes: I,
37    ns: &DynNamespace,
38    filesystem: &FS,
39) -> Result<ResolvedDbSnapshots, ProviderError>
40where
41    FS: FileSystem,
42    I: IntoIterator<Item = &'a NodeSpec>,
43{
44    let ns_base_dir = ns.base_dir().to_string_lossy().to_string();
45    let fileserver_fetches = ns.capabilities().fileserver_fetches_db_snapshot_url;
46    let mut resolved: ResolvedDbSnapshots = HashMap::new();
47
48    for loc in nodes.into_iter().filter_map(|n| n.db_snapshot.as_ref()) {
49        if resolved.contains_key(loc) {
50            continue;
51        }
52        let name = cache_name(loc);
53        let in_fileserver = match fetched_by_fileserver(loc, fileserver_fetches) {
54            Some(url) => ns.fetch_into_fileserver(url, &name).await?,
55            None => None,
56        };
57        let snapshot = match in_fileserver {
58            Some(url) => {
59                trace!("db_snapshot {name} fetched by the fileserver: {url}");
60                DbSnapshot::InFileserver(url)
61            },
62            None => {
63                let cache_path = Path::new(&ns_base_dir).join(&name);
64                if !filesystem.exists(&cache_path).await {
65                    fetch_into_cache(loc, &cache_path, filesystem).await?;
66                } else {
67                    trace!("db_snapshot cache hit: {}", cache_path.display());
68                }
69                DbSnapshot::Local(cache_path)
70            },
71        };
72        resolved.insert(loc.clone(), snapshot);
73    }
74
75    Ok(resolved)
76}
77
78/// The name a snapshot is kept under, in the namespace cache or in the
79/// fileserver alike.
80fn cache_name(location: &AssetLocation) -> String {
81    format!(
82        "{}.tgz",
83        hex::encode(sha2::Sha256::digest(location.to_string()))
84    )
85}
86
87/// The URL to hand the fileserver, when it fetches `location` itself.
88fn fetched_by_fileserver(location: &AssetLocation, fileserver_fetches: bool) -> Option<&url::Url> {
89    match location {
90        AssetLocation::Url(url) if fileserver_fetches => Some(url),
91        _ => None,
92    }
93}
94
95/// Remove cache tarballs after all consumers have finished extracting them,
96/// gated by the `ZOMBIE_RM_TGZ_AFTER_EXTRACT` env var. Best-effort: errors
97/// are logged and swallowed (cleanup must never fail spawn).
98///
99/// Must be called only after every node that consumes the cache has
100/// completed its `initialize_db_snapshot` — otherwise concurrent readers
101/// will hit `ENOENT`.
102pub async fn cleanup_db_snapshot_cache(resolved: &ResolvedDbSnapshots) {
103    if std::env::var("ZOMBIE_RM_TGZ_AFTER_EXTRACT").is_err() {
104        return;
105    }
106    for snapshot in resolved.values() {
107        // Nothing was cached here for a snapshot the fileserver fetched.
108        let DbSnapshot::Local(cache_path) = snapshot else {
109            continue;
110        };
111        match tokio::fs::remove_file(cache_path).await {
112            Ok(()) => trace!("removed cache {}", cache_path.display()),
113            Err(err) => trace!("failed to remove cache {}: {err}", cache_path.display()),
114        }
115    }
116}
117
118async fn fetch_into_cache<FS: FileSystem>(
119    location: &AssetLocation,
120    cache_path: &Path,
121    filesystem: &FS,
122) -> Result<(), ProviderError> {
123    trace!(
124        "resolving db_snapshot {} -> {}",
125        location,
126        cache_path.display()
127    );
128    match location {
129        AssetLocation::Url(url) => {
130            let res = reqwest::get(url.as_ref())
131                .await
132                .map_err(|err| ProviderError::DownloadFile(url.to_string(), err.into()))?;
133            let bytes = res
134                .bytes()
135                .await
136                .map_err(|err| ProviderError::DownloadFile(url.to_string(), err.into()))?;
137            filesystem.write(cache_path, &bytes[..]).await?;
138        },
139        AssetLocation::FilePath(filepath) => {
140            filesystem.copy(filepath, cache_path).await?;
141        },
142    }
143    Ok(())
144}
145
146#[cfg(test)]
147mod tests {
148    use super::*;
149
150    fn url() -> AssetLocation {
151        AssetLocation::Url(
152            "https://example.com/snaps/rc.tgz?sig=a&b=c"
153                .parse()
154                .unwrap(),
155        )
156    }
157
158    #[test]
159    fn a_url_is_fetched_by_a_fileserver_that_can() {
160        let AssetLocation::Url(expected) = url() else {
161            unreachable!()
162        };
163        assert_eq!(fetched_by_fileserver(&url(), true), Some(&expected));
164        assert_eq!(fetched_by_fileserver(&url(), false), None);
165    }
166
167    #[test]
168    fn a_local_file_is_never_fetched_by_the_fileserver() {
169        let local = AssetLocation::FilePath("/snaps/rc.tgz".into());
170        assert_eq!(fetched_by_fileserver(&local, true), None);
171    }
172
173    #[test]
174    fn a_snapshot_keeps_its_cache_name_wherever_it_is_kept() {
175        let name = cache_name(&url());
176        assert_eq!(name, cache_name(&url()));
177        assert_eq!(name.len(), 64 + ".tgz".len());
178        assert_ne!(
179            name,
180            cache_name(&AssetLocation::FilePath("/snaps/rc.tgz".into()))
181        );
182    }
183}