Skip to main content

lockdocs_core/private/
cargo.rs

1//! Cargo alternate registries (sparse protocol), from `.cargo/config.toml`,
2//! `$CARGO_HOME/credentials.toml`, `CARGO_REGISTRIES_<NAME>_*` variables, the
3//! registry `Cargo.lock` recorded per package and the `registry = "name"` key
4//! of `Cargo.toml` dependencies.
5
6use super::*;
7
8const PUBLIC_HOSTS: &[&str] = &["crates.io", "index.crates.io", "static.crates.io", "github.com"];
9
10fn cargo_home(env: &Env) -> Option<PathBuf> {
11    env.get("CARGO_HOME").map(PathBuf::from).or_else(|| env.home_file(".cargo"))
12}
13
14fn table_of(p: &Path) -> Option<toml::Table> {
15    toml::from_str(&read(p)?).ok()
16}
17
18/// Config tables, lowest priority first: `$CARGO_HOME`, then each ancestor
19/// directory's `.cargo/`, the project's last.
20fn configs(root: &Path, env: &Env) -> Vec<toml::Table> {
21    let mut dirs: Vec<PathBuf> = cargo_home(env).into_iter().collect();
22    let mut up: Vec<PathBuf> = root.ancestors().map(|a| a.join(".cargo")).collect();
23    up.reverse();
24    dirs.extend(up);
25    let mut out = Vec::new();
26    for d in dirs {
27        for n in ["config.toml", "config"] {
28            if let Some(t) = table_of(&d.join(n)) {
29                out.push(t);
30                break;
31            }
32        }
33    }
34    out
35}
36
37fn norm_index(s: &str) -> String {
38    s.trim()
39        .strip_prefix("sparse+")
40        .or_else(|| s.trim().strip_prefix("registry+"))
41        .unwrap_or(s.trim())
42        .trim_end_matches('/')
43        .to_string()
44}
45
46fn is_public(index: &str) -> bool {
47    let i = norm_index(index);
48    Url::parse(&i).is_none_or(|u| PUBLIC_HOSTS.contains(&u.host.as_str()) && (u.host != "github.com" || u.path.contains("crates.io-index")))
49}
50
51/// The public fetch base for a crates.io `Cargo.lock` source, or `None` when it
52/// is not one. `static.crates.io` serves the `.crate` files directly.
53fn public_base(src: &str) -> Option<String> {
54    is_public(src).then(|| "https://static.crates.io".to_string())
55}
56
57struct Registry {
58    name: String,
59    index: String,
60}
61
62fn registries(cfgs: &[toml::Table], env: &Env) -> Vec<Registry> {
63    let mut out: Vec<Registry> = Vec::new();
64    let mut put = |name: &str, index: &str| {
65        out.retain(|r| r.name != name);
66        out.push(Registry {
67            name: name.to_string(),
68            index: index.to_string(),
69        });
70    };
71    for t in cfgs {
72        if let Some(r) = t.get("registries").and_then(|r| r.as_table()) {
73            for (n, v) in r {
74                if let Some(i) = v.get("index").and_then(|i| i.as_str()) {
75                    put(n, i);
76                }
77            }
78        }
79        if let Some(s) = t.get("source").and_then(|s| s.as_table()) {
80            for (n, v) in s {
81                if let Some(i) = v.get("registry").and_then(|i| i.as_str()) {
82                    put(n, i);
83                }
84            }
85        }
86    }
87    for (k, v) in env.with_prefix("CARGO_REGISTRIES_") {
88        if let Some(n) = k.to_ascii_uppercase().strip_prefix("CARGO_REGISTRIES_").and_then(|r| r.strip_suffix("_INDEX")) {
89            put(&n.to_ascii_lowercase().replace('_', "-"), &v);
90        }
91    }
92    out
93}
94
95/// The token for a registry name: environment, then credentials file, then config.
96fn token(name: &str, cfgs: &[toml::Table], creds_files: &[toml::Table], env: &Env) -> Option<String> {
97    let key = format!("CARGO_REGISTRIES_{}_TOKEN", name.to_ascii_uppercase().replace('-', "_"));
98    if let Some(t) = env.get(&key) {
99        return Some(t);
100    }
101    creds_files
102        .iter()
103        .rev()
104        .chain(cfgs.iter().rev())
105        .find_map(|t| t.get("registries")?.get(name)?.get("token")?.as_str().map(String::from))
106}
107
108fn lock_entry(dep: &Dep, root: &Path) -> Option<String> {
109    let t = table_of(&root.join("Cargo.lock"))?;
110    let want = crate::norm_name(Eco::Cargo, &dep.name);
111    t.get("package")?.as_array()?.iter().filter_map(|p| p.as_table()).find_map(|p| {
112        (crate::norm_name(Eco::Cargo, p.get("name")?.as_str()?) == want && p.get("version")?.as_str()? == dep.version).then_some(())?;
113        p.get("source")?.as_str().map(String::from)
114    })
115}
116
117/// The registry name a `Cargo.toml` dependency asks for.
118fn manifest_registry(dep: &Dep, root: &Path) -> Option<String> {
119    let t = table_of(&root.join("Cargo.toml"))?;
120    let want = crate::norm_name(Eco::Cargo, &dep.name);
121    let mut tables: Vec<&toml::Table> = Vec::new();
122    for k in ["dependencies", "dev-dependencies", "build-dependencies"] {
123        tables.extend(t.get(k).and_then(|d| d.as_table()));
124    }
125    tables.extend(t.get("workspace").and_then(|w| w.get("dependencies")).and_then(|d| d.as_table()));
126    tables.into_iter().find_map(|d| {
127        d.iter().find_map(|(k, v)| {
128            let real = v.get("package").and_then(|p| p.as_str()).unwrap_or(k);
129            (crate::norm_name(Eco::Cargo, real) == want).then(|| v.get("registry")?.as_str().map(String::from))?
130        })
131    })
132}
133
134pub fn plan(dep: &Dep, root: &Path, env: &Env) -> Plan {
135    let cfgs = configs(root, env);
136    let creds_files: Vec<toml::Table> = cargo_home(env)
137        .into_iter()
138        .flat_map(|h| ["credentials.toml", "credentials"].map(|n| h.join(n)))
139        .filter_map(|p| table_of(&p))
140        .collect();
141    let regs = registries(&cfgs, env);
142    let mut creds = Creds::default();
143    let mut candidates = Vec::new();
144    let add = |index: &str, name: Option<&str>, definitive: bool, git: bool, candidates: &mut Vec<Candidate>, creds: &mut Creds| {
145        let base = norm_index(index);
146        let Some(u) = Url::parse(&base) else { return };
147        if candidates.iter().any(|c: &Candidate| c.base == base) {
148            return;
149        }
150        let name = name
151            .map(String::from)
152            .or_else(|| regs.iter().find(|r| norm_index(&r.index) == base).map(|r| r.name.clone()));
153        if let Some(t) = name.and_then(|n| token(&n, &cfgs, &creds_files, env)) {
154            creds.push(Credential::new(u.origin(), Auth::Raw(t)));
155        }
156        candidates.push(Candidate {
157            base,
158            private: true,
159            definitive,
160            pinned: git.then(|| "git-index".to_string()),
161        });
162    };
163    // 1. Cargo.lock; 2. the manifest's `registry = "name"`.
164    if let Some(src) = lock_entry(dep, root) {
165        if !is_public(&src) {
166            add(
167                &src,
168                None,
169                true,
170                src.starts_with("registry+") && !src.contains("sparse+"),
171                &mut candidates,
172                &mut creds,
173            );
174        } else if let Some(base) = public_base(&src) {
175            // Cargo.lock resolved this package to crates.io: honour it. A
176            // configured mirror or replacement registry must not shadow the
177            // artifact the lockfile actually pinned.
178            candidates.push(Candidate {
179                base,
180                private: false,
181                definitive: true,
182                pinned: None,
183            });
184        }
185    }
186    if candidates.is_empty() {
187        if let Some(r) = manifest_registry(dep, root).and_then(|n| regs.iter().find(|r| r.name == n)) {
188            add(&r.index, Some(&r.name), true, !r.index.starts_with("sparse+"), &mut candidates, &mut creds);
189        }
190    }
191    // 3. crates.io replaced by a mirror.
192    if candidates.is_empty() {
193        let replaced = cfgs
194            .iter()
195            .rev()
196            .find_map(|t| t.get("source")?.get("crates-io")?.get("replace-with")?.as_str().map(String::from));
197        if let Some(r) = replaced.and_then(|n| regs.iter().find(|r| r.name == n)) {
198            add(&r.index, Some(&r.name), false, !r.index.starts_with("sparse+"), &mut candidates, &mut creds);
199        }
200    }
201    if candidates.first().is_none_or(|c| !c.definitive) {
202        candidates.push(Candidate {
203            base: "https://index.crates.io".into(),
204            private: false,
205            definitive: false,
206            pinned: None,
207        });
208    }
209    Plan { candidates, creds }
210}
211
212fn prefix(name: &str) -> String {
213    match name.len() {
214        1 => "1".into(),
215        2 => "2".into(),
216        3 => format!("3/{}", &name[..1]),
217        _ => format!("{}/{}", &name[..2], &name[2..4]),
218    }
219}
220
221/// The download URL from the registry's `dl` template.
222pub fn dl_url(dl: &str, krate: &str, version: &str) -> Option<String> {
223    if !dl.contains(['{']) {
224        return Some(format!("{}/{krate}/{version}/download", dl.trim_end_matches('/')));
225    }
226    let out = dl
227        .replace("{crate}", krate)
228        .replace("{version}", version)
229        .replace("{prefix}", &prefix(krate))
230        .replace("{lowerprefix}", &prefix(&krate.to_ascii_lowercase()));
231    (!out.contains("{sha256-checksum}")).then_some(out)
232}
233
234/// Download one version from a sparse registry. Ok(false) when it has none.
235pub fn download(http: &Http, dep: &Dep, c: &Candidate, dir: &Path) -> Result<bool> {
236    if c.pinned.as_deref() == Some("git-index") {
237        bail!("this registry uses the git index protocol; lockdocs reads sparse registries (`sparse+https://...`)");
238    }
239    let base = c.base.trim_end_matches('/');
240    let Some(cfg) = http.get_ok(&format!("{base}/config.json"), None)? else {
241        return Ok(false);
242    };
243    let cfg: serde_json::Value = serde_json::from_slice(&cfg)?;
244    let Some(dl) = cfg.get("dl").and_then(|d| d.as_str()) else {
245        bail!("the registry's config.json has no `dl` template");
246    };
247    let Some(url) = dl_url(dl, &dep.name, &dep.version) else {
248        bail!("the registry's `dl` template uses {{sha256-checksum}}, which lockdocs does not read yet");
249    };
250    let url = if url.starts_with('/') {
251        Url::parse(base).and_then(|b| b.join(&url)).map_or(url.clone(), |u| u.clean())
252    } else {
253        url
254    };
255    let Some(bytes) = http.get_ok(&url, None)? else { return Ok(false) };
256    crate::fetch::untar_gz(&bytes, dir)?;
257    Ok(true)
258}
259
260#[cfg(test)]
261mod tests {
262    use super::super::testutil::*;
263    use super::*;
264
265    fn dep(name: &str, v: &str) -> Dep {
266        Dep {
267            eco: Eco::Cargo,
268            name: name.into(),
269            version: v.into(),
270            direct: true,
271            from: "Cargo.lock".into(),
272        }
273    }
274
275    #[test]
276    fn lock_source_config_and_token() {
277        let t = tempfile::tempdir().unwrap();
278        write(&t.path().join("Cargo.lock"), "version = 4\n[[package]]\nname = \"acme-core\"\nversion = \"0.3.0\"\nsource = \"sparse+https://cargo.acme.example/index/\"\n[[package]]\nname = \"serde\"\nversion = \"1.0.0\"\nsource = \"registry+https://github.com/rust-lang/crates.io-index\"\n");
279        write(
280            &t.path().join(".cargo/config.toml"),
281            "[registries.acme]\nindex = \"sparse+https://cargo.acme.example/index/\"\n",
282        );
283        let home = tempfile::tempdir().unwrap();
284        write(&home.path().join(".cargo/credentials.toml"), "[registries.acme]\ntoken = \"SECRET-CRED\"\n");
285        let env = Env::fixed(&[], Some(home.path()));
286        let p = plan(&dep("acme-core", "0.3.0"), t.path(), &env);
287        assert!(p.definitely_private());
288        assert_eq!(p.candidates[0].base, "https://cargo.acme.example/index");
289        let auth = p.creds.for_url(&Url::parse("https://cargo.acme.example/index/config.json").unwrap()).unwrap();
290        assert_eq!(auth.header(), "SECRET-CRED");
291        assert!(p.creds.for_url(&Url::parse("https://index.crates.io/config.json").unwrap()).is_none());
292        assert!(!plan(&dep("serde", "1.0.0"), t.path(), &env).any_private());
293        // The environment token wins over the credentials file.
294        let env2 = Env::fixed(&[("CARGO_REGISTRIES_ACME_TOKEN", "SECRET-ENV")], Some(home.path()));
295        let p2 = plan(&dep("acme-core", "0.3.0"), t.path(), &env2);
296        assert_eq!(
297            p2.creds.for_url(&Url::parse("https://cargo.acme.example/index/x").unwrap()).unwrap().header(),
298            "SECRET-ENV"
299        );
300    }
301
302    #[test]
303    fn manifest_registry_key_without_lock() {
304        let t = tempfile::tempdir().unwrap();
305        write(
306            &t.path().join("Cargo.toml"),
307            "[package]\nname=\"x\"\n[dependencies]\nacme-core = { version = \"0.3\", registry = \"acme\" }\n",
308        );
309        write(
310            &t.path().join(".cargo/config.toml"),
311            "[registries.acme]\nindex = \"sparse+https://cargo.acme.example/index/\"\n",
312        );
313        let p = plan(&dep("acme-core", "0.3.0"), t.path(), &Env::fixed(&[], None));
314        assert!(p.definitely_private());
315    }
316
317    #[test]
318    fn git_index_registry_is_refused_clearly() {
319        let t = tempfile::tempdir().unwrap();
320        write(
321            &t.path().join("Cargo.lock"),
322            "version = 4\n[[package]]\nname = \"a\"\nversion = \"1.0.0\"\nsource = \"registry+https://git.acme.example/index\"\n",
323        );
324        let p = plan(&dep("a", "1.0.0"), t.path(), &Env::fixed(&[], None));
325        let e = download(&Http::new(Creds::default()), &dep("a", "1.0.0"), &p.candidates[0], t.path())
326            .unwrap_err()
327            .to_string();
328        assert!(e.contains("sparse"), "{e}");
329    }
330
331    #[test]
332    fn dl_templates() {
333        assert_eq!(
334            dl_url("https://d.example/api", "acme", "1.0.0").unwrap(),
335            "https://d.example/api/acme/1.0.0/download"
336        );
337        assert_eq!(
338            dl_url("https://d.example/{prefix}/{crate}-{version}.crate", "acme", "1.0.0").unwrap(),
339            "https://d.example/ac/me/acme-1.0.0.crate"
340        );
341        assert_eq!(
342            dl_url("https://d.example/{lowerprefix}/{crate}", "ab", "1.0.0").unwrap(),
343            "https://d.example/2/ab"
344        );
345        assert!(dl_url("https://d.example/{sha256-checksum}", "ab", "1").is_none());
346    }
347
348    #[test]
349    fn downloads_with_the_raw_token() {
350        let krate = tgz(&[("acme-core-0.3.0/README.md", b"# acme"), ("acme-core-0.3.0/Cargo.toml", b"[package]")]);
351        let m = serve(move |p, auth| {
352            if auth != Some("SECRET-TOK") {
353                return (401, "text/plain".into(), vec![], vec![]);
354            }
355            match p {
356                "/index/config.json" => (200, "application/json".into(), br#"{"dl":"/dl/{crate}/{version}.crate"}"#.to_vec(), vec![]),
357                "/dl/acme-core/0.3.0.crate" => (200, "application/gzip".into(), krate.clone(), vec![]),
358                _ => (404, "text/plain".into(), vec![], vec![]),
359            }
360        });
361        let t = tempfile::tempdir().unwrap();
362        write(
363            &t.path().join("Cargo.lock"),
364            &format!(
365                "version = 4\n[[package]]\nname = \"acme-core\"\nversion = \"0.3.0\"\nsource = \"sparse+{}/index/\"\n",
366                m.base
367            ),
368        );
369        let env = Env::fixed(&[("CARGO_REGISTRIES_TEST_TOKEN", "SECRET-TOK")], None);
370        write(
371            &t.path().join(".cargo/config.toml"),
372            &format!("[registries.test]\nindex = \"sparse+{}/index/\"\n", m.base),
373        );
374        let p = plan(&dep("acme-core", "0.3.0"), t.path(), &env);
375        let out = tempfile::tempdir().unwrap();
376        assert!(download(&Http::new(p.creds), &dep("acme-core", "0.3.0"), &p.candidates[0], out.path()).unwrap());
377        assert!(out.path().join("README.md").is_file());
378    }
379}