Skip to main content

nix_archive/
lib.rs

1#![doc = include_str!("../README.md")]
2
3mod dec;
4mod encoder;
5pub mod git;
6mod refscan;
7#[cfg(unix)]
8mod restore;
9mod walk;
10mod wire;
11
12/// The Nix Archive (NAR) format.
13///
14/// NAR serialization is part of Nix store-path identity, so this module is
15/// byte-oriented and tested against `nix-store --dump`.
16///
17/// # Allocation behavior
18///
19/// - [`decode_events`](crate::nar::decode_events) visits borrowed root-first
20///   events without allocating on valid input; [`decode`](crate::nar::decode)
21///   is an allocating post-order convenience API.
22/// - [`decode_events_reader`](crate::nar::decode_events_reader) visits the same
23///   [`Event`](crate::nar::Event)s from a stream, with a file's contents as a
24///   [`FileContents`](crate::nar::FileContents) reader, so memory use follows
25///   directory depth and metadata rather than payload size. `Event` is generic
26///   over its contents type, so one visitor can serve both decoders.
27/// - [`encode_tree`](crate::nar::encode_tree) and
28///   [`hash_tree`](crate::nar::hash_tree) serialize an already-sorted borrowed
29///   tree without allocating when the writer does not allocate.
30/// - [`Encoder`](crate::nar::Encoder) serializes validated root-first events
31///   and streams externally backed regular-file contents through
32///   [`RegularWriter`](crate::nar::RegularWriter).
33/// - [`encode_path`](crate::nar::encode_path) and
34///   [`hash_path`](crate::nar::hash_path) allocate directory-name metadata for
35///   canonical sorting, while file payloads remain streaming.
36/// - [`restore_reader`](crate::nar::restore_reader) recreates a tree from a
37///   stream with payload-independent memory use; [`restore`](crate::nar::restore)
38///   is the borrowed-slice convenience API. Both require an explicit
39///   [`CaseHack`](crate::nar::CaseHack) for Nix's macOS case-collision hack;
40///   [`CaseHack::native`](crate::nar::CaseHack::native) reproduces Nix's own
41///   default.
42///
43/// The wire-level APIs preserve names, symlink targets, and contents as raw
44/// bytes. Filesystem paths require UTF-8 when collected or encoded on Windows.
45pub mod nar {
46    pub use crate::dec::{
47        decode, decode_events, decode_events_reader, Entry, Event, FileContents, ReadEvent,
48    };
49    pub use crate::encoder::{
50        encode_path, encode_regular, encode_tree, hash_path, hash_regular, hash_tree, CaseHack,
51        Encoder, NamedNode, NarHash, Node, RegularWriter, CASE_HACK_SUFFIX,
52    };
53    #[allow(deprecated)]
54    pub use crate::encoder::{encode_path_with_case_hack, hash_path_with_case_hack};
55    pub use crate::refscan::{
56        ReferencePattern, ReferencePatternError, ReferenceScan, ReferenceScanner, ReferenceWriter,
57        REFERENCE_LENGTH,
58    };
59    #[cfg(unix)]
60    pub use crate::restore::{restore, restore_reader};
61    #[cfg(unix)]
62    #[allow(deprecated)]
63    pub use crate::restore::{
64        restore_path, restore_path_with_case_hack, restore_reader_with_case_hack,
65    };
66
67    use thiserror::Error;
68
69    /// A malformed NAR or filesystem encoding/restoration failure.
70    #[derive(Debug, Error)]
71    #[non_exhaustive]
72    pub enum Error {
73        #[error("unexpected end of archive")]
74        UnexpectedEof,
75        #[error("not a NAR: bad magic")]
76        BadMagic,
77        #[error("padding bytes were not zero")]
78        BadPadding,
79        #[error("expected {expected:?}, got {got:?}")]
80        UnexpectedToken { expected: &'static str, got: String },
81        #[error("invalid entry name {0:?}")]
82        InvalidName(String),
83        #[error("directory entries not sorted: {0:?} after {1:?}")]
84        UnsortedEntries(String, String),
85        #[error("trailing bytes after archive end")]
86        TrailingBytes,
87        #[error("NAR directory nesting exceeds maximum depth of {0}")]
88        MaxDepth(usize),
89        #[error("file name collision between {0} and {1} after removing the Nix case-hack suffix")]
90        CaseHackEncodeCollision(std::path::PathBuf, std::path::PathBuf),
91        #[error(
92            "archive name {archive_name:?} maps to {generated_name:?}, which collides with explicit name {existing_name:?}"
93        )]
94        CaseHackRestoreCollision {
95            archive_name: String,
96            generated_name: String,
97            existing_name: String,
98        },
99        #[error("too many case-colliding names in one directory")]
100        CaseHackCounterOverflow,
101        #[error("NAR metadata token is {size} bytes, exceeding the streaming limit of {limit}")]
102        TokenTooLarge {
103            /// Declared token size.
104            size: u64,
105            /// Maximum size accepted by the streaming decode and restore APIs.
106            limit: usize,
107        },
108        #[error("file changed size while encoding: {0}")]
109        FileChanged(std::path::PathBuf),
110        #[error("invalid incremental encoder event: {0}")]
111        InvalidEncoderEvent(&'static str),
112        #[error("incremental encoder has an unfinished archive")]
113        UnfinishedArchive,
114        #[error("regular file declared {expected} bytes but received {actual}")]
115        RegularSizeMismatch { expected: u64, actual: u64 },
116        #[error("incremental encoder is poisoned after a writer failure")]
117        EncoderPoisoned,
118        #[error("unsupported file type: {0}")]
119        UnsupportedFileType(std::path::PathBuf),
120        #[error(transparent)]
121        Io(#[from] std::io::Error),
122    }
123}