gix_pack/index/verify.rs
1use std::sync::atomic::AtomicBool;
2
3use gix_features::progress::{DynNestedProgress, Progress};
4use gix_object::WriteTo;
5
6use crate::index;
7
8///
9pub mod integrity {
10 use std::marker::PhantomData;
11
12 use gix_object::bstr::BString;
13
14 /// Returned by [`index::File::verify_integrity()`][crate::index::File::verify_integrity()].
15 #[derive(thiserror::Error, Debug)]
16 #[allow(missing_docs)]
17 pub enum Error {
18 #[error("Reserialization of an object failed")]
19 Io(#[from] std::io::Error),
20 #[error("The fan at index {index} is out of order as it's larger then the following value.")]
21 Fan { index: usize },
22 #[error("{kind} object {id} could not be decoded")]
23 ObjectDecode {
24 source: gix_object::decode::Error,
25 kind: gix_object::Kind,
26 id: gix_hash::ObjectId,
27 },
28 #[error("{kind} object {id} wasn't re-encoded without change, wanted\n{expected}\n\nGOT\n\n{actual}")]
29 ObjectEncodeMismatch {
30 kind: gix_object::Kind,
31 id: gix_hash::ObjectId,
32 expected: BString,
33 actual: BString,
34 },
35 }
36
37 /// Returned by [`index::File::verify_integrity()`][crate::index::File::verify_integrity()].
38 pub struct Outcome {
39 /// The computed checksum of the index which matched the stored one.
40 pub actual_index_checksum: gix_hash::ObjectId,
41 /// The packs traversal outcome, if one was provided
42 pub pack_traverse_statistics: Option<crate::index::traverse::Statistics>,
43 }
44
45 /// Additional options to define how the integrity should be verified.
46 #[derive(Clone)]
47 pub struct Options<F> {
48 /// The thoroughness of the verification
49 pub verify_mode: crate::index::verify::Mode,
50 /// The way to traverse packs
51 pub traversal: crate::index::traverse::Algorithm,
52 /// The amount of threads to use of `Some(N)`, with `None|Some(0)` using all available cores are used.
53 pub thread_limit: Option<usize>,
54 /// A function to create a pack cache
55 pub make_pack_lookup_cache: F,
56 }
57
58 impl Default for Options<fn() -> crate::cache::Never> {
59 fn default() -> Self {
60 Options {
61 verify_mode: Default::default(),
62 traversal: Default::default(),
63 thread_limit: None,
64 make_pack_lookup_cache: || crate::cache::Never,
65 }
66 }
67 }
68
69 /// The progress ids used in [`index::File::verify_integrity()`][crate::index::File::verify_integrity()].
70 ///
71 /// Use this information to selectively extract the progress of interest in case the parent application has custom visualization.
72 #[derive(Debug, Copy, Clone)]
73 pub enum ProgressId {
74 /// The amount of bytes read to verify the index checksum.
75 ChecksumBytes,
76 /// A root progress for traversal which isn't actually used directly, but here to link to the respective `ProgressId` types.
77 Traverse(PhantomData<crate::index::verify::index::traverse::ProgressId>),
78 }
79
80 impl From<ProgressId> for gix_features::progress::Id {
81 fn from(v: ProgressId) -> Self {
82 match v {
83 ProgressId::ChecksumBytes => *b"PTHI",
84 ProgressId::Traverse(_) => gix_features::progress::UNKNOWN,
85 }
86 }
87 }
88}
89
90///
91pub mod checksum {
92 /// Returned by [`index::File::verify_checksum()`][crate::index::File::verify_checksum()].
93 pub type Error = crate::verify::checksum::Error;
94}
95
96/// Various ways in which a pack and index can be verified
97#[derive(Default, Debug, Eq, PartialEq, Hash, Clone, Copy)]
98pub enum Mode {
99 /// Validate the object hash and CRC32
100 HashCrc32,
101 /// Validate hash and CRC32, and decode each non-Blob object.
102 /// Each object should be valid, i.e. be decodable.
103 HashCrc32Decode,
104 /// Validate hash and CRC32, and decode and encode each non-Blob object.
105 /// Each object should yield exactly the same hash when re-encoded.
106 #[default]
107 HashCrc32DecodeEncode,
108}
109
110/// Information to allow verifying the integrity of an index with the help of its corresponding pack.
111pub struct PackContext<'a, F> {
112 /// The pack data file itself.
113 pub data: &'a crate::data::File,
114 /// The options further configuring the pack traversal and verification
115 pub options: integrity::Options<F>,
116}
117
118/// Verify and validate the content of the index file
119impl index::File {
120 /// Returns the trailing hash stored at the end of this index file.
121 ///
122 /// It's a hash over all bytes of the index.
123 pub fn index_checksum(&self) -> gix_hash::ObjectId {
124 gix_hash::ObjectId::from_bytes_or_panic(&self.data[self.data.len() - self.hash_len..])
125 }
126
127 /// Returns the hash of the pack data file that this index file corresponds to.
128 ///
129 /// It should [`crate::data::File::checksum()`] of the corresponding pack data file.
130 pub fn pack_checksum(&self) -> gix_hash::ObjectId {
131 let from = self.data.len() - self.hash_len * 2;
132 gix_hash::ObjectId::from_bytes_or_panic(&self.data[from..][..self.hash_len])
133 }
134
135 /// Validate that our [`index_checksum()`][index::File::index_checksum()] matches the actual contents
136 /// of this index file, and return it if it does.
137 pub fn verify_checksum(
138 &self,
139 progress: &mut dyn Progress,
140 should_interrupt: &AtomicBool,
141 ) -> Result<gix_hash::ObjectId, checksum::Error> {
142 crate::verify::checksum_on_disk_or_mmap(
143 self.path(),
144 &self.data,
145 self.index_checksum(),
146 self.object_hash,
147 progress,
148 should_interrupt,
149 )
150 }
151
152 /// The most thorough validation of integrity of both index file and the corresponding pack data file, if provided.
153 /// Returns the checksum of the index file, the traversal outcome and the given progress if the integrity check is successful.
154 ///
155 /// If `pack` is provided, it is expected (and validated to be) the pack belonging to this index.
156 /// It will be used to validate internal integrity of the pack before checking each objects integrity
157 /// is indeed as advertised via its SHA1 as stored in this index, as well as the CRC32 hash.
158 /// The last member of the Option is a function returning an implementation of [`crate::cache::DecodeEntry`] to be used if
159 /// the [`index::traverse::Algorithm`] is `Lookup`.
160 /// To set this to `None`, use `None::<(_, _, _, fn() -> crate::cache::Never)>`.
161 ///
162 /// The `thread_limit` optionally specifies the amount of threads to be used for the [pack traversal][index::File::traverse()].
163 /// `make_cache` is only used in case a `pack` is specified, use existing implementations in the [`crate::cache`] module.
164 ///
165 /// # Tradeoffs
166 ///
167 /// The given `progress` is inevitably consumed if there is an error, which is a tradeoff chosen to easily allow using `?` in the
168 /// error case.
169 pub fn verify_integrity<C, F>(
170 &self,
171 pack: Option<PackContext<'_, F>>,
172 progress: &mut dyn DynNestedProgress,
173 should_interrupt: &AtomicBool,
174 ) -> Result<integrity::Outcome, index::traverse::Error<index::verify::integrity::Error>>
175 where
176 C: crate::cache::DecodeEntry,
177 F: Fn() -> C + Send + Clone,
178 {
179 if let Some(first_invalid) = crate::verify::fan(&self.fan) {
180 return Err(index::traverse::Error::Processor(integrity::Error::Fan {
181 index: first_invalid,
182 }));
183 }
184
185 match pack {
186 Some(PackContext {
187 data: pack,
188 options:
189 integrity::Options {
190 verify_mode,
191 traversal,
192 thread_limit,
193 make_pack_lookup_cache,
194 },
195 }) => self
196 .traverse(
197 pack,
198 progress,
199 should_interrupt,
200 {
201 let mut encode_buf = Vec::with_capacity(2048);
202 move |kind, data, index_entry, progress| {
203 Self::verify_entry(verify_mode, &mut encode_buf, kind, data, index_entry, progress)
204 }
205 },
206 index::traverse::Options {
207 traversal,
208 thread_limit,
209 check: index::traverse::SafetyCheck::All,
210 make_pack_lookup_cache,
211 },
212 )
213 .map(|o| integrity::Outcome {
214 actual_index_checksum: o.actual_index_checksum,
215 pack_traverse_statistics: Some(o.statistics),
216 }),
217 None => self
218 .verify_checksum(
219 &mut progress
220 .add_child_with_id("Sha1 of index".into(), integrity::ProgressId::ChecksumBytes.into()),
221 should_interrupt,
222 )
223 .map_err(Into::into)
224 .map(|id| integrity::Outcome {
225 actual_index_checksum: id,
226 pack_traverse_statistics: None,
227 }),
228 }
229 }
230
231 #[allow(clippy::too_many_arguments)]
232 fn verify_entry(
233 verify_mode: Mode,
234 encode_buf: &mut Vec<u8>,
235 object_kind: gix_object::Kind,
236 buf: &[u8],
237 index_entry: &index::Entry,
238 _progress: &dyn gix_features::progress::Progress,
239 ) -> Result<(), integrity::Error> {
240 if let Mode::HashCrc32Decode | Mode::HashCrc32DecodeEncode = verify_mode {
241 use gix_object::Kind::*;
242 match object_kind {
243 Tree | Commit | Tag => {
244 let object = gix_object::ObjectRef::from_bytes(object_kind, buf).map_err(|err| {
245 integrity::Error::ObjectDecode {
246 source: err,
247 kind: object_kind,
248 id: index_entry.oid,
249 }
250 })?;
251 if let Mode::HashCrc32DecodeEncode = verify_mode {
252 encode_buf.clear();
253 object.write_to(&mut *encode_buf)?;
254 if encode_buf.as_slice() != buf {
255 return Err(integrity::Error::ObjectEncodeMismatch {
256 kind: object_kind,
257 id: index_entry.oid,
258 expected: buf.into(),
259 actual: encode_buf.clone().into(),
260 });
261 }
262 }
263 }
264 Blob => {}
265 };
266 }
267 Ok(())
268 }
269}