gix_pack/data/mod.rs
1//! a pack data file
2use crate::MMap;
3use std::path::Path;
4
5/// The offset to an entry into the pack data file, relative to its beginning.
6pub type Offset = u64;
7
8/// An identifier to uniquely identify all packs loaded within a known context or namespace.
9pub type Id = u32;
10
11/// An representing an full- or delta-object within a pack
12#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
13#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
14pub struct Entry {
15 /// The entry's header
16 pub header: entry::Header,
17 /// The decompressed size of the entry in bytes.
18 ///
19 /// Note that for non-delta entries this will be the size of the object itself.
20 pub decompressed_size: u64,
21 /// absolute offset to compressed object data in the pack, just behind the entry's header
22 pub data_offset: Offset,
23 /// The amount of bytes used to encode the entry header in the pack.
24 ///
25 /// Git accepts non-canonical size encodings in pack entry headers. These are encodings that
26 /// continue the variable-length size field even though the remaining size bits are zero, for
27 /// example `b3 00` for a blob of size `3` instead of the canonical single-byte `33`.
28 ///
29 /// Git does not usually write such headers itself, but they can appear when pack data is reused
30 /// verbatim, for example when a server constructs fetch or clone responses from already stored
31 /// pack entries. Readers have to preserve the byte length that was actually consumed: recomputing
32 /// the canonical length from the decoded size would shift [`Entry::pack_offset()`] backwards and
33 /// make ofs-delta base-offset calculations refer to the wrong entry.
34 ///
35 /// A value of `0` means the actual length is unknown, causing [`Entry::header_size()`] to
36 /// recompute the canonical length from the decoded size. This is useful for deserializing data
37 /// produced by older versions.
38 #[cfg_attr(feature = "serde", serde(default))]
39 pub encoded_header_size: u16,
40}
41
42mod file;
43pub use file::{Header, decode, verify};
44///
45pub mod header;
46
47///
48pub mod init {
49 pub use super::header::decode::Error;
50}
51
52///
53pub mod entry;
54
55///
56#[cfg(feature = "streaming-input")]
57pub mod input;
58
59/// Utilities to encode pack data entries and write them to a `Write` implementation to resemble a pack data file.
60#[cfg(feature = "generate")]
61pub mod output;
62
63/// A slice into a pack file denoting a pack entry.
64///
65/// An entry can be decoded into an object.
66pub type EntryRange = std::ops::Range<Offset>;
67
68/// Supported versions of a pack data file
69#[derive(Default, PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
70#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
71pub enum Version {
72 /// The default pack data version.
73 ///
74 /// This is the version generated by Git and by `gix-pack` writers.
75 #[default]
76 V2,
77 /// A pack data version accepted by Git and recognized by `gix-pack` readers.
78 ///
79 /// Git does not generate this version, and `gix-pack` writers currently reject it.
80 /// Entries are decoded with the same layout as [`V2`](Version::V2); the difference
81 /// visible to this crate is the version number stored in the pack header.
82 V3,
83}
84
85/// A pack data file
86pub struct File<T = MMap> {
87 data: T,
88 path: std::path::PathBuf,
89 /// A value to represent this pack uniquely when used with cache lookup, or a way to identify this pack by its location on disk.
90 /// The same location on disk should yield the same id.
91 ///
92 /// These must be unique per pack and must be stable, that is they don't change if the pack doesn't change.
93 /// If the same id is assigned (or reassigned) to different packs, pack creation or cache access will fail in hard-to-debug ways.
94 ///
95 /// 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.
96 pub id: Id,
97 version: Version,
98 num_objects: u32,
99 /// The kind of hash contained within. This is entirely determined by the caller, and repositories have to know which hash to use
100 /// based on their configuration.
101 object_hash: gix_hash::Kind,
102 /// The maximum size of a single allocation caused by user-controlled on-disk pack data.
103 ///
104 /// If `None`, no additional limit is enforced.
105 pub alloc_limit_bytes: Option<usize>,
106}
107
108/// Information about the pack data file itself
109impl<T> File<T>
110where
111 T: crate::FileData,
112{
113 /// The pack data version of this file
114 pub fn version(&self) -> Version {
115 self.version
116 }
117 /// The number of objects stored in this pack data file
118 pub fn num_objects(&self) -> u32 {
119 self.num_objects
120 }
121 /// The length of all mapped data, including the pack header and the pack trailer
122 pub fn data_len(&self) -> usize {
123 self.data.len()
124 }
125 /// The kind of hash we use internally.
126 pub fn object_hash(&self) -> gix_hash::Kind {
127 self.object_hash
128 }
129 /// The position of the byte one past the last pack entry, or in other terms, the first byte of the trailing hash.
130 pub fn pack_end(&self) -> usize {
131 self.data.len() - self.object_hash.len_in_bytes()
132 }
133
134 /// The path to the pack data file on disk
135 pub fn path(&self) -> &Path {
136 &self.path
137 }
138
139 /// Returns the pack data at the given slice if its range is contained in the mapped pack data
140 pub fn entry_slice(&self, slice: EntryRange) -> Option<&[u8]> {
141 let entry_end: usize = slice.end.try_into().expect("end of pack fits into usize");
142 let entry_start = slice.start as usize;
143 self.data.get(entry_start..entry_end)
144 }
145
146 /// Returns the CRC32 of the pack data indicated by `pack_offset` and the `size` of the mapped data.
147 ///
148 /// _Note:_ finding the right size is only possible by decompressing
149 /// the pack entry beforehand, or by using the (to be sorted) offsets stored in an index file.
150 ///
151 /// # Panics
152 ///
153 /// If `pack_offset` or `size` are pointing to a range outside of the mapped pack data.
154 pub fn entry_crc32(&self, pack_offset: Offset, size: usize) -> u32 {
155 let pack_offset: usize = pack_offset.try_into().expect("pack_size fits into usize");
156 gix_features::hash::crc32(&self.data[pack_offset..pack_offset + size])
157 }
158}
159
160///
161pub mod delta;