vendor/gix-pack/src/data/mod.rs

   1 //! a pack data file
   2 use std::{convert::TryInto, path::Path};
   3
   4 /// The offset to an entry into the pack data file, relative to its beginning.
   5 pub type Offset = u64;
   6
   7 /// An identifier to uniquely identify all packs loaded within a known context or namespace.
   8 pub type Id = u32;
   9
  10 use memmap2::Mmap;
  11
  12 /// An representing an full- or delta-object within a pack
  13 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
  14 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
  15 pub struct Entry {
  16     /// The entry's header
  17     pub header: entry::Header,
  18     /// The decompressed size of the entry in bytes.
  19     ///
  20     /// Note that for non-delta entries this will be the size of the object itself.
  21     pub decompressed_size: u64,
  22     /// absolute offset to compressed object data in the pack, just behind the entry's header
  23     pub data_offset: Offset,
  24 }
  25
  26 mod file;
  27 pub use file::{decode, verify, Header};
  28 ///
  29 pub mod header;
  30
  31 ///
  32 pub mod init {
  33     pub use super::header::decode::Error;
  34 }
  35
  36 ///
  37 pub mod entry;
  38
  39 ///
  40 pub mod input;
  41
  42 /// Utilities to encode pack data entries and write them to a `Write` implementation to resemble a pack data file.
  43 pub mod output;
  44
  45 /// A slice into a pack file denoting a pack entry.
  46 ///
  47 /// An entry can be decoded into an object.
  48 pub type EntryRange = std::ops::Range<Offset>;
  49
  50 /// Supported versions of a pack data file
  51 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
  52 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
  53 #[allow(missing_docs)]
  54 pub enum Version {
  55     V2,
  56     V3,
  57 }
  58
  59 impl Default for Version {
  60     fn default() -> Self {
  61         Version::V2
  62     }
  63 }
  64
  65 /// A pack data file
  66 pub struct File {
  67     data: Mmap,
  68     path: std::path::PathBuf,
  69     /// A value to represent this pack uniquely when used with cache lookup, or a way to identify this pack by its location on disk.
  70     /// The same location on disk should yield the same id.
  71     ///
  72     /// These must be unique per pack and must be stable, that is they don't change if the pack doesn't change.
  73     /// If the same id is assigned (or reassigned) to different packs, pack creation or cache access will fail in hard-to-debug ways.
  74     ///
  75     /// This value is controlled by the owning object store, which can use it in whichever way it wants as long as the above constraints are met.
  76     pub id: Id,
  77     version: Version,
  78     num_objects: u32,
  79     /// The size of the hash contained within. This is entirely determined by the caller, and repositories have to know which hash to use
  80     /// based on their configuration.
  81     hash_len: usize,
  82     object_hash: gix_hash::Kind,
  83 }
  84
  85 /// Information about the pack data file itself
  86 impl File {
  87     /// The pack data version of this file
  88     pub fn version(&self) -> Version {
  89         self.version
  90     }
  91     /// The number of objects stored in this pack data file
  92     pub fn num_objects(&self) -> u32 {
  93         self.num_objects
  94     }
  95     /// The length of all mapped data, including the pack header and the pack trailer
  96     pub fn data_len(&self) -> usize {
  97         self.data.len()
  98     }
  99     /// The kind of hash we use internally.
 100     pub fn object_hash(&self) -> gix_hash::Kind {
 101         self.object_hash
 102     }
 103     /// The position of the byte one past the last pack entry, or in other terms, the first byte of the trailing hash.
 104     pub fn pack_end(&self) -> usize {
 105         self.data.len() - self.hash_len
 106     }
 107
 108     /// The path to the pack data file on disk
 109     pub fn path(&self) -> &Path {
 110         &self.path
 111     }
 112
 113     /// Returns the pack data at the given slice if its range is contained in the mapped pack data
 114     pub fn entry_slice(&self, slice: EntryRange) -> Option<&[u8]> {
 115         let entry_end: usize = slice.end.try_into().expect("end of pack fits into usize");
 116         let entry_start = slice.start as usize;
 117         self.data.get(entry_start..entry_end)
 118     }
 119
 120     /// Returns the CRC32 of the pack data indicated by `pack_offset` and the `size` of the mapped data.
 121     ///
 122     /// _Note:_ finding the right size is only possible by decompressing
 123     /// the pack entry beforehand, or by using the (to be sorted) offsets stored in an index file.
 124     ///
 125     /// # Panics
 126     ///
 127     /// If `pack_offset` or `size` are pointing to a range outside of the mapped pack data.
 128     pub fn entry_crc32(&self, pack_offset: Offset, size: usize) -> u32 {
 129         let pack_offset: usize = pack_offset.try_into().expect("pack_size fits into usize");
 130         gix_features::hash::crc32(&self.data[pack_offset..pack_offset + size])
 131     }
 132 }
 133
 134 pub(crate) mod delta;