nix_compat/store_path/
mod.rs

1use crate::nixbase32;
2use data_encoding::DecodeError;
3use smol_str::SmolStr;
4use std::{
5    fmt,
6    str::{self, FromStr},
7};
8use thiserror;
9
10mod borrowed;
11mod utils;
12
13pub use borrowed::StorePathRef;
14pub use utils::*;
15
16pub const DIGEST_SIZE: usize = 20;
17pub const ENCODED_DIGEST_SIZE: usize = nixbase32::encode_len(DIGEST_SIZE);
18
19// The store dir prefix, without trailing slash.
20// That's usually where the Nix store is mounted at.
21pub const STORE_DIR: &str = "/nix/store";
22pub const STORE_DIR_WITH_SLASH: &str = "/nix/store/";
23
24/// Error returned by [`validate_name`].
25#[derive(Debug, PartialEq, Eq, Clone, thiserror::Error)]
26pub enum ParseStorePathNameError {
27    #[error("Invalid length")]
28    Length,
29    #[error("Invalid name")]
30    Name,
31}
32
33impl From<ParseStorePathNameError> for ParseStorePathError {
34    fn from(value: ParseStorePathNameError) -> Self {
35        match value {
36            ParseStorePathNameError::Length => ParseStorePathError::Length,
37            ParseStorePathNameError::Name => ParseStorePathError::Name,
38        }
39    }
40}
41
42/// Errors that can occur when parsing a literal store path
43#[derive(Debug, PartialEq, Eq, thiserror::Error)]
44pub enum ParseStorePathError {
45    #[error("Dash is missing between hash and name")]
46    MissingDash,
47    #[error("Hash encoding is invalid: {0}")]
48    DigestEncoding(#[from] DecodeError),
49    #[error("Invalid length")]
50    Length,
51    #[error("Invalid name")]
52    Name,
53    #[error("Tried to parse an absolute path which was missing the store dir prefix.")]
54    MissingStoreDir,
55}
56
57/// Represents a path in the Nix store (a direct child of [STORE_DIR]).
58///
59/// It consists of a digest (20 bytes), and a name, which is a string.
60/// The name may only contain ASCII alphanumeric, or one of the following
61/// characters: `-`, `_`, `.`, `+`, `?`, `=`.
62/// The name is usually used to describe the pname and version of a package.
63/// Derivation paths can also be represented as store paths, their names just
64/// end with the `.drv` prefix.
65///
66/// A [StorePath] does not encode any additional subpath "inside" the store
67/// path.
68#[derive(Clone, Debug, Eq, PartialEq, Hash)]
69pub struct StorePath {
70    digest: [u8; DIGEST_SIZE],
71    name: SmolStr,
72}
73
74impl StorePath {
75    pub fn digest(&self) -> &[u8; DIGEST_SIZE] {
76        &self.digest
77    }
78
79    pub fn name(&self) -> &'_ str {
80        &self.name
81    }
82
83    /// Construct a [StorePath] by passing the `$digest-$name` string
84    /// that comes after [STORE_DIR_WITH_SLASH].
85    pub fn from_bytes(s: &[u8]) -> Result<Self, ParseStorePathError> {
86        Ok(StorePathRef::from_bytes(s)?.to_owned())
87    }
88
89    /// Construct a [StorePath] from a name and digest.
90    /// The name is validated, and the digest checked for size.
91    pub fn from_name_and_digest(name: &str, digest: &[u8]) -> Result<Self, ParseStorePathError> {
92        Ok(StorePathRef::from_name_and_digest(name, digest)?.to_owned())
93    }
94
95    /// Construct a [StorePathRef] from a name and digest of correct length.
96    /// The name is validated.
97    pub fn from_name_and_digest_fixed(
98        name: &str,
99        digest: [u8; DIGEST_SIZE],
100    ) -> Result<Self, ParseStorePathError> {
101        Ok(StorePathRef::from_name_and_digest_fixed(name, digest)?.to_owned())
102    }
103
104    /// Construct a [StorePathRef] from an absolute store path string.
105    /// This is equivalent to calling [StorePathRef::from_bytes], but stripping
106    /// the [STORE_DIR_WITH_SLASH] prefix before.
107    pub fn from_absolute_path(s: &[u8]) -> Result<Self, ParseStorePathError> {
108        Ok(StorePathRef::from_absolute_path(s)?.to_owned())
109    }
110
111    /// Decompose a string into a [StorePathRef] and a [std::path::Path]
112    /// containing the rest of the path, or an error.
113    pub fn from_absolute_path_full<P>(
114        path: &P,
115    ) -> Result<(Self, &std::path::Path), ParseStorePathError>
116    where
117        P: AsRef<std::path::Path> + ?Sized,
118    {
119        let (store_path_ref, path) = StorePathRef::from_absolute_path_full(path)?;
120
121        Ok((store_path_ref.to_owned(), path))
122    }
123
124    /// Returns as an absolute store path (prefixed with [STORE_DIR_WITH_SLASH]).
125    pub fn to_absolute_path(&self) -> String {
126        self.as_absolute_path_fmt().to_string()
127    }
128
129    /// Returns a formatter writing an absolute store path (prefixed with [STORE_DIR_WITH_SLASH]).
130    pub fn as_absolute_path_fmt<'a>(&'a self) -> impl std::fmt::Display + 'a {
131        struct WithAbsolutePath<'a>(&'a StorePath);
132
133        impl std::fmt::Display for WithAbsolutePath<'_> {
134            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
135                write!(f, "{}", self.0.as_ref().as_absolute_path_fmt())
136            }
137        }
138
139        WithAbsolutePath(self)
140    }
141}
142
143impl PartialOrd for StorePath {
144    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
145        Some(self.cmp(other))
146    }
147}
148
149/// `StorePath`s are sorted by their reverse digest to match the sorting order
150/// of the nixbase32-encoded string.
151impl Ord for StorePath {
152    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
153        self.as_ref().cmp(&other.as_ref())
154    }
155}
156
157impl FromStr for StorePath {
158    type Err = ParseStorePathError;
159
160    /// Construct a [StorePath] by passing the `$digest-$name` string
161    /// that comes after [STORE_DIR_WITH_SLASH].
162    fn from_str(s: &str) -> Result<Self, Self::Err> {
163        StorePath::from_bytes(s.as_bytes())
164    }
165}
166
167#[cfg(feature = "serde")]
168impl<'de> serde::Deserialize<'de> for StorePath {
169    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
170    where
171        D: serde::Deserializer<'de>,
172    {
173        StorePathRef::<'de>::deserialize(deserializer).map(|sp| sp.to_owned())
174    }
175}
176
177#[cfg(feature = "serde")]
178impl serde::Serialize for StorePath {
179    fn serialize<SR>(&self, serializer: SR) -> Result<SR::Ok, SR::Error>
180    where
181        SR: serde::Serializer,
182    {
183        self.as_ref().serialize(serializer)
184    }
185}
186
187/// NAME_CHARS contains `true` for bytes that are valid in store path names.
188static NAME_CHARS: [bool; 256] = {
189    let mut tbl = [false; 256];
190    let mut c = 0;
191
192    loop {
193        tbl[c as usize] = matches!(c, b'a'..=b'z' | b'A'..=b'Z' | b'0'..=b'9' | b'+' | b'-' | b'_' | b'?' | b'=' | b'.');
194
195        if c == u8::MAX {
196            break;
197        }
198
199        c += 1;
200    }
201
202    tbl
203};
204
205/// Checks a given &[u8] to match the restrictions for [StorePath::name], and
206/// returns the name as &str if successful.
207pub fn validate_name(s: &[u8]) -> Result<&str, ParseStorePathNameError> {
208    // Empty or excessively long names are not allowed.
209    if s.is_empty() || s.len() > 211 {
210        return Err(ParseStorePathNameError::Length);
211    }
212
213    let mut valid = true;
214    for &c in s {
215        valid = valid && NAME_CHARS[c as usize];
216    }
217
218    if !valid {
219        for &c in s.iter() {
220            if !NAME_CHARS[c as usize] {
221                return Err(ParseStorePathNameError::Name);
222            }
223        }
224
225        unreachable!();
226    }
227
228    // SAFETY: We permit a subset of ASCII, which guarantees valid UTF-8.
229    Ok(unsafe { str::from_utf8_unchecked(s) })
230}
231
232/// Checks a given OsStr to match the restrictions for [StorePath::name], and
233/// returns the name as &str if successful.
234pub fn validate_name_from_os_str(s: &std::ffi::OsStr) -> Result<&str, ParseStorePathNameError> {
235    validate_name(s.as_encoded_bytes())
236}
237
238impl fmt::Display for StorePath {
239    /// The string representation of a store path starts with a digest (20
240    /// bytes), [crate::nixbase32]-encoded, followed by a `-`,
241    /// and ends with the name.
242    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
243        fmt::Display::fmt(&self.as_ref(), f)
244    }
245}
246
247#[cfg(test)]
248mod tests {
249    use super::ParseStorePathError;
250
251    use crate::store_path::{DIGEST_SIZE, StorePath, StorePathRef};
252    use hex_literal::hex;
253    use pretty_assertions::assert_eq;
254    use rstest::rstest;
255    #[cfg(feature = "serde")]
256    use serde::Deserialize;
257
258    /// An example struct, holding a StorePathRef.
259    /// Used to test deserializing StorePathRef.
260    #[cfg(feature = "serde")]
261    #[derive(Deserialize)]
262    struct Container<'a> {
263        #[serde(borrow)]
264        store_path: StorePathRef<'a>,
265    }
266
267    #[test]
268    fn happy_path() {
269        let example_nix_path_str =
270            "00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432";
271        let nixpath = StorePathRef::from_bytes(example_nix_path_str.as_bytes())
272            .expect("Error parsing example string");
273
274        let expected_digest: [u8; DIGEST_SIZE] = hex!("8a12321522fd91efbd60ebb2481af88580f61600");
275
276        assert_eq!("net-tools-1.60_p20170221182432", nixpath.name());
277        assert_eq!(nixpath.digest(), &expected_digest);
278
279        assert_eq!(example_nix_path_str, nixpath.to_string())
280    }
281
282    #[test]
283    fn store_path_ordering() {
284        let store_paths = [
285            "/nix/store/0lk5dgi01r933abzfj9c9wlndg82yd3g-psutil-5.9.6.tar.gz.drv",
286            "/nix/store/1xj43bva89f9qmwm37zl7r3d7m67i9ck-shorttoc-1.3-tex.drv",
287            "/nix/store/2gb633czchi20jq1kqv70rx2yvvgins8-lifted-base-0.2.3.12.tar.gz.drv",
288            "/nix/store/2vksym3r3zqhp15q3fpvw2mnvffv11b9-docbook-xml-4.5.zip.drv",
289            "/nix/store/5q918awszjcz5720xvpc2czbg1sdqsf0-rust_renaming-0.1.0-lib",
290            "/nix/store/7jw30i342sr2p1fmz5xcfnch65h4zbd9-dbus-1.14.10.tar.xz.drv",
291            "/nix/store/96yqwqhnp3qya4rf4n0rcl0lwvrylp6k-eap8021x-222.40.1.tar.gz.drv",
292            "/nix/store/9gjqg36a1v0axyprbya1hkaylmnffixg-virtualenv-20.24.5.tar.gz.drv",
293            "/nix/store/a4i5mci2g9ada6ff7ks38g11dg6iqyb8-perl-5.32.1.drv",
294            "/nix/store/a5g76ljava4h5pxlggz3aqdhs3a4fk6p-ToolchainInfo.plist.drv",
295            "/nix/store/db46l7d6nswgz4ffp1mmd56vjf9g51v6-version.plist.drv",
296            "/nix/store/g6f7w20sd7vwy0rc1r4bfsw4ciclrm4q-crates-io-num_cpus-1.12.0.drv",
297            "/nix/store/iw82n1wwssb8g6772yddn8c3vafgv9np-bootstrap-stage1-sysctl-stdenv-darwin.drv",
298            "/nix/store/lp78d1y5wxpcn32d5c4r7xgbjwiw0cgf-logo.svg.drv",
299            "/nix/store/mf00ank13scv1f9l1zypqdpaawjhfr3s-python3.11-psutil-5.9.6.drv",
300            "/nix/store/mpfml61ra7pz90124jx9r3av0kvkz2w1-perl5.36.0-Encode-Locale-1.05",
301            "/nix/store/qhsvwx4h87skk7c4mx0xljgiy3z93i23-source.drv",
302            "/nix/store/riv7d73adim8hq7i04pr8kd0jnj93nav-fdk-aac-2.0.2.tar.gz.drv",
303            "/nix/store/s64b9031wga7vmpvgk16xwxjr0z9ln65-human-signals-5.0.0.tgz-extracted",
304            "/nix/store/w6svg3m2xdh6dhx0gl1nwa48g57d3hxh-thiserror-1.0.49",
305        ];
306
307        for w in store_paths.windows(2) {
308            if w.len() < 2 {
309                continue;
310            }
311
312            let pa = StorePathRef::from_absolute_path(w[0].as_bytes()).expect("parseable");
313            let pb = StorePathRef::from_absolute_path(w[1].as_bytes()).expect("parseable");
314
315            assert!(pa < pb, "{pa} not less than {pb}");
316        }
317    }
318
319    /// This is the store path *accepted* when `nix-store --add`'ing an
320    /// empty `.gitignore` file.
321    ///
322    /// Nix 2.4 accidentally permitted this behaviour, but the revert came
323    /// too late to beat Hyrum's law. It is now considered permissible.
324    ///
325    /// https://github.com/NixOS/nix/pull/9095 (revert)
326    /// https://github.com/NixOS/nix/pull/9867 (revert-of-revert)
327    #[test]
328    fn starts_with_dot() {
329        StorePathRef::from_bytes(b"fli4bwscgna7lpm7v5xgnjxrxh0yc7ra-.gitignore")
330            .expect("must succeed");
331    }
332
333    #[test]
334    fn empty_name() {
335        StorePathRef::from_bytes(b"00bgd045z0d4icpbc2yy-").expect_err("must fail");
336    }
337
338    #[test]
339    fn excessive_length() {
340        StorePathRef::from_bytes(b"00bgd045z0d4icpbc2yy-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
341            .expect_err("must fail");
342    }
343
344    #[test]
345    fn invalid_hash_length() {
346        StorePathRef::from_bytes(b"00bgd045z0d4icpbc2yy-net-tools-1.60_p20170221182432")
347            .expect_err("must fail");
348    }
349
350    #[test]
351    fn invalid_encoding_hash() {
352        StorePathRef::from_bytes(
353            b"00bgd045z0d4icpbc2yyz4gx48aku4la-net-tools-1.60_p20170221182432",
354        )
355        .expect_err("must fail");
356    }
357
358    #[test]
359    fn more_than_just_the_bare_nix_store_path() {
360        StorePathRef::from_bytes(
361            b"00bgd045z0d4icpbc2yyz4gx48aku4la-net-tools-1.60_p20170221182432/bin/arp",
362        )
363        .expect_err("must fail");
364    }
365
366    #[test]
367    fn no_dash_between_hash_and_name() {
368        StorePathRef::from_bytes(b"00bgd045z0d4icpbc2yyz4gx48ak44lanet-tools-1.60_p20170221182432")
369            .expect_err("must fail");
370    }
371
372    #[test]
373    fn absolute_path() {
374        let example_nix_path_str =
375            "00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432";
376        let nixpath_expected =
377            StorePathRef::from_bytes(example_nix_path_str.as_bytes()).expect("must parse");
378
379        let nixpath_actual = StorePathRef::from_absolute_path(
380            "/nix/store/00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432".as_bytes(),
381        )
382        .expect("must parse");
383
384        assert_eq!(nixpath_expected, nixpath_actual);
385
386        assert_eq!(
387            "/nix/store/00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432",
388            nixpath_actual.to_absolute_path(),
389        );
390    }
391
392    #[test]
393    fn absolute_path_missing_prefix() {
394        assert_eq!(
395            ParseStorePathError::MissingStoreDir,
396            StorePathRef::from_absolute_path(b"foobar-123").expect_err("must fail")
397        );
398    }
399
400    #[cfg(feature = "serde")]
401    #[test]
402    fn serialize_ref() {
403        let nixpath_actual = StorePathRef::from_bytes(
404            b"00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432",
405        )
406        .expect("can parse");
407
408        let serialized = serde_json::to_string(&nixpath_actual).expect("can serialize");
409
410        assert_eq!(
411            "\"/nix/store/00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432\"",
412            &serialized
413        );
414    }
415
416    #[cfg(feature = "serde")]
417    #[test]
418    fn serialize_owned() {
419        let nixpath_actual = StorePathRef::from_bytes(
420            b"00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432",
421        )
422        .expect("can parse");
423
424        let serialized = serde_json::to_string(&nixpath_actual).expect("can serialize");
425
426        assert_eq!(
427            "\"/nix/store/00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432\"",
428            &serialized
429        );
430    }
431
432    #[cfg(feature = "serde")]
433    #[test]
434    fn deserialize_ref() {
435        let store_path_str_json =
436            "\"/nix/store/00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432\"";
437
438        let store_path: StorePathRef<'_> =
439            serde_json::from_str(store_path_str_json).expect("valid json");
440
441        assert_eq!(
442            "/nix/store/00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432",
443            store_path.to_absolute_path()
444        );
445    }
446
447    #[cfg(feature = "serde")]
448    #[test]
449    fn deserialize_ref_container() {
450        let str_json = "{\"store_path\":\"/nix/store/00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432\"}";
451
452        let container: Container<'_> = serde_json::from_str(str_json).expect("must deserialize");
453
454        assert_eq!(
455            "/nix/store/00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432",
456            container.store_path.to_absolute_path()
457        );
458    }
459
460    #[cfg(feature = "serde")]
461    #[test]
462    fn deserialize_owned() {
463        let store_path_str_json =
464            "\"/nix/store/00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432\"";
465
466        let store_path: StorePath = serde_json::from_str(store_path_str_json).expect("valid json");
467
468        assert_eq!(
469            "/nix/store/00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432",
470            store_path.to_absolute_path()
471        );
472    }
473
474    #[rstest]
475    #[case::without_prefix(
476        "/nix/store/00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432",
477        StorePath::from_bytes(b"00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432").unwrap(), "")]
478    #[case::without_prefix_but_trailing_slash(
479        "/nix/store/00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432/",
480        StorePath::from_bytes(b"00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432").unwrap(), "")]
481    #[case::with_prefix(
482        "/nix/store/00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432/bin/arp",
483        StorePath::from_bytes(b"00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432").unwrap(), "bin/arp")]
484    #[case::with_prefix_and_trailing_slash(
485        "/nix/store/00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432/bin/arp/",
486        StorePath::from_bytes(b"00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432").unwrap(), "bin/arp/")]
487    fn from_absolute_path_full(
488        #[case] s: &str,
489        #[case] exp_store_path: StorePath,
490        #[case] exp_rest_str: &str,
491    ) {
492        let (actual_store_path, actual_rest) =
493            StorePath::from_absolute_path_full(s).expect("must succeed");
494
495        assert_eq!(exp_store_path, actual_store_path);
496        assert_eq!(exp_rest_str, actual_rest);
497    }
498
499    #[test]
500    fn from_absolute_path_errors() {
501        assert_eq!(
502            ParseStorePathError::Length,
503            StorePathRef::from_absolute_path_full("/nix/store/").expect_err("must fail")
504        );
505        assert_eq!(
506            ParseStorePathError::Length,
507            StorePathRef::from_absolute_path_full("/nix/store/foo").expect_err("must fail")
508        );
509        assert_eq!(
510            ParseStorePathError::MissingStoreDir,
511            StorePathRef::from_absolute_path_full(
512                "00bgd045z0d4icpbc2yyz4gx48ak44la-net-tools-1.60_p20170221182432"
513            )
514            .expect_err("must fail")
515        );
516    }
517}
nix_compat/store_path/mod.rs

nix_compat/store_path/
mod.rs
