feat(gix): throttle object refreshes with a freshness window

Add RefreshMode::AfterDuration as a shared gix-odb freshness window. Repeated misses avoid rescanning packs and alternates until the last successful post-initialization refresh reaches the configured age, while failed refreshes, known missing packs, and explicit stale notification remain immediately retryable. Configure gix object handles with a one-second default and expose gitoxide.objects.refreshAfter in milliseconds. Fetch invalidates freshness after publishing a pack, configuration reloads update active handles, and zero restores strict refresh-on-every-miss behavior. Use the test-support clock for deterministic deadline and contention coverage, keep feature-unified workspace builds and Repository size guards valid with the added configuration, and make the minimal CI dependency assertion portable to images without ripgrep.

Codex committed 3 months ago

Commit ca8be2c1 parent ce90da620 files · +432 −25Browse files

Unified · Split

20 files

etc/scripts/cargo-check-all.sh +1 −1
gix-odb/src/lib.rs +2 −0
gix-odb/src/store_impls/dynamic/find.rs +2 −2
gix-odb/src/store_impls/dynamic/handle.rs +1 −0
gix-odb/src/store_impls/dynamic/header.rs +1 −1
gix-odb/src/store_impls/dynamic/init.rs +17 −2
gix-odb/src/store_impls/dynamic/load_index.rs +28 −5
gix-odb/src/store_impls/dynamic/mod.rs +28 −2
gix-odb/src/store_impls/dynamic/prefix.rs +4 −2
gix-odb/src/store_impls/dynamic/structure.rs +9 −0
gix-odb/tests/odb/store/dynamic_scenarios.rs +254 −5
gix/src/config/cache/init.rs +5 −0
gix/src/config/cache/util.rs +12 −0
gix/src/config/mod.rs +4 −0
gix/src/config/tree/sections/gitoxide.rs +8 −0
gix/src/remote/connection/fetch/receive_pack.rs +1 −0
gix/src/repository/init.rs +1 −1
gix/tests/gix/config/tree.rs +11 −0
gix/tests/gix/repository/mod.rs +3 −4
gix/tests/gix/repository/open.rs +40 −0

etc/scripts/cargo-check-all.sh+1−1

@@ -18,7 +18,7 @@ cargo check -p gix-transport --all-features 2>/dev/null · 17 unmodified lines
18	! cargo check -p gitoxide-core --all-features --features gix/sha1 2>/dev/null	18	! cargo check -p gitoxide-core --all-features --features gix/sha1 2>/dev/null
19	cargo check -p gix-protocol --all-features	19	cargo check -p gix-protocol --all-features
20	tree="$(cargo --color=never tree -p gix --no-default-features -e normal --prefix none --format '{p}')"	20	tree="$(cargo --color=never tree -p gix --no-default-features -e normal --prefix none --format '{p}')"
21	! printf '%s\n' "$tree" \| rg -q '^gix-imara-diff(-01)? v'	21	! printf '%s\n' "$tree" \| grep -Eq '^gix-imara-diff(-01)? v'
22	cargo --color=never tree -p gix --no-default-features -e normal -i gix-submodule \	22	cargo --color=never tree -p gix --no-default-features -e normal -i gix-submodule \
23	2>&1 >/dev/null \| grep '^warning: nothing to print\>'	23	2>&1 >/dev/null \| grep '^warning: nothing to print\>'
24	cargo --color=never tree -p gix --no-default-features -e normal -i gix-pathspec \	24	cargo --color=never tree -p gix --no-default-features -e normal -i gix-pathspec \

gix-odb/src/lib.rs+2−0

     pub(crate) num_disk_state_consolidations_completed: AtomicUsize,
     /// The most recent failed consolidation, shared only with callers that were already waiting for it.
     pub(crate) last_disk_state_consolidation_error: parking_lot::Mutex<Option<(usize, Arc<store::load_index::Error>)>>,
+    /// The last successful post-initialization disk-state consolidation, used to throttle miss-triggered refreshes.
+    pub(crate) last_successful_disk_state_consolidation: parking_lot::Mutex<Option<std::time::Instant>>,
     /// If true, we are allowed to use multi-pack indices and they must have the `object_hash` or be ignored.
     use_multi_pack_index: bool,
     /// The hash kind to use for some operations

gix-odb/src/store_impls/dynamic/find.rs+2−2

@@ -146,7 +146,7 @@ where · 145 unmodified lines
146	}	146	}
147	None => {	147	None => {
148	// The pack wasn't available anymore so we are supposed to try another round with a fresh index	148	// The pack wasn't available anymore so we are supposed to try another round with a fresh index
149	match self.store.load_one_index(self.index_ctx(marker))? {	149	match self.store.load_one_index(self.index_ctx(marker).force_refresh())? {
150	Some(new_snapshot) => {	150	Some(new_snapshot) => {
151	*snapshot = new_snapshot;	151	*snapshot = new_snapshot;
152	self.clear_cache();	152	self.clear_cache();
@@ -419,7 +419,7 @@ where · 266 unmodified lines
419	}	419	}
420	None => {	420	None => {
421	// The pack wasn't available anymore so we are supposed to try another round with a fresh index	421	// The pack wasn't available anymore so we are supposed to try another round with a fresh index
422	match self.store.load_one_index(self.index_ctx(marker)).ok()? {	422	match self.store.load_one_index(self.index_ctx(marker).force_refresh()).ok()? {
423	Some(new_snapshot) => {	423	Some(new_snapshot) => {
424	*snapshot = new_snapshot;	424	*snapshot = new_snapshot;
425	self.clear_cache();	425	self.clear_cache();

gix-odb/src/store_impls/dynamic/handle.rs+1−0

@@ -339,6 +339,7 @@ where · 338 unmodified lines
339	pub(crate) fn index_ctx(&self, marker: types::SlotIndexMarker) -> super::IndexCtx {	339	pub(crate) fn index_ctx(&self, marker: types::SlotIndexMarker) -> super::IndexCtx {
340	super::IndexCtx {	340	super::IndexCtx {
341	refresh_mode: self.refresh,	341	refresh_mode: self.refresh,
		342	force_refresh: false,
342	marker,	343	marker,
343	loose_compression: self.loose_compression,	344	loose_compression: self.loose_compression,
344	}	345	}

gix-odb/src/store_impls/dynamic/header.rs+1−1

@@ -60,7 +60,7 @@ where · 59 unmodified lines
60	}	60	}
61	None => {	61	None => {
62	// The pack wasn't available anymore so we are supposed to try another round with a fresh index	62	// The pack wasn't available anymore so we are supposed to try another round with a fresh index
63	match self.store.load_one_index(self.index_ctx(marker))? {	63	match self.store.load_one_index(self.index_ctx(marker).force_refresh())? {
64	Some(new_snapshot) => {	64	Some(new_snapshot) => {
65	*snapshot = new_snapshot;	65	*snapshot = new_snapshot;
66	self.clear_cache();	66	self.clear_cache();

gix-odb/src/store_impls/dynamic/init.rs+17−2

 /// Deterministic synchronization support for tests of concurrent object-database behavior.
 #[cfg(feature = "test-support")]
 pub mod debug {
-    use std::{fmt, sync::Arc};
+    use std::{fmt, sync::Arc, time::Instant};
     /// The result of a filesystem-backed load attempt.
     #[non_exhaustive]
     #[derive(Clone)]
     pub struct Options {
         hook: Arc<dyn Fn(Point) + Send + Sync>,
+        clock: Option<Arc<dyn Fn() -> Instant + Send + Sync>>,
     }
     impl Options {
         /// Create options that invoke `hook` at every configured synchronization point.
         pub fn new(hook: impl Fn(Point) + Send + Sync + 'static) -> Self {
-            Options { hook: Arc::new(hook) }
+            Options {
+                hook: Arc::new(hook),
+                clock: None,
+            }
+        }
+        /// Use `clock` instead of the system monotonic clock for refresh throttling.
+        pub fn with_clock(mut self, clock: impl Fn() -> Instant + Send + Sync + 'static) -> Self {
+            self.clock = Some(Arc::new(clock));
+            self
         }
         pub(crate) fn at(&self, point: Point) {
             (self.hook)(point);
         }
+        pub(crate) fn now(&self) -> Instant {
+            self.clock.as_ref().map_or_else(Instant::now, |clock| clock())
+        }
     }
     impl fmt::Debug for Options {
             num_disk_state_consolidation: Default::default(),
             num_disk_state_consolidations_completed: Default::default(),
             last_disk_state_consolidation_error: Default::default(),
+            last_successful_disk_state_consolidation: Default::default(),
         })
     }
 }

gix-odb/src/store_impls/dynamic/load_index.rs+28−5

         let mut snapshot = self.collect_snapshot();
         while let Some(new_snapshot) = self.load_one_index(IndexCtx {
             refresh_mode: RefreshMode::Never,
+            force_refresh: false,
             marker: snapshot.marker,
             loose_compression: self.loose_compression,
         })? {
         &self,
         IndexCtx {
             refresh_mode,
+            force_refresh,
             marker,
             loose_compression,
         }: IndexCtx,
                 // …and if that didn't yield anything new consider refreshing our disk state.
                 match refresh_mode {
                     RefreshMode::Never => Ok(None),
-                    RefreshMode::AfterAllIndicesLoaded => self.consolidate_with_disk_state(
+                    RefreshMode::AfterDuration(refresh_after)
-                        false, /* needs init */
+                        if !force_refresh && self.last_refresh_is_younger_than(refresh_after) =>
-                        true,  /* load one new index */
+                    {
-                        loose_compression,
+                        Ok(None)
-                    ),
+                    }
+                    RefreshMode::AfterAllIndicesLoaded | RefreshMode::AfterDuration(_) => {
+                        self.consolidate_with_disk_state(
+                            false, /* needs init */
+                            true,  /* load one new index */
+                            loose_compression,
+                        )
+                    }
                 }
             }
         }
     }
+    fn last_refresh_is_younger_than(&self, max_age: std::time::Duration) -> bool {
+        let now = self.now();
+        self.last_successful_disk_state_consolidation
+            .lock()
+            .as_ref()
+            .is_some_and(|last| {
+                now.checked_duration_since(*last)
+                    .is_none_or(|elapsed| elapsed < max_age)
+            })
+    }
     /// load a new index (if not yet loaded), and return true if one was indeed loaded (leading to a `state_id()` change) of the current index.
     /// Note that interacting with the slot-map is inherently racy and we have to deal with it, being conservative in what we even try to load
     /// as our index might already be out-of-date as we try to use it to learn what's next.
             }
             Some(self.collect_snapshot())
         };
+        if !was_uninitialized {
+            *self.last_successful_disk_state_consolidation.lock() = Some(self.now());
+        }
         self.finish_refresh(current_completed_refreshes, Ok(snapshot))
     }

gix-odb/src/store_impls/dynamic/mod.rs+28−2

 //! The standard object store which should fit all needs.
-use std::{cell::RefCell, ops::Deref, sync::Arc};
+use std::{cell::RefCell, ops::Deref, sync::Arc, time::Duration};
 use crate::Store;
 #[derive(Clone, Copy)]
 pub(crate) struct IndexCtx {
     refresh_mode: RefreshMode,
+    force_refresh: bool,
     marker: types::SlotIndexMarker,
     loose_compression: gix_zlib::Compression,
 }
+impl IndexCtx {
+    fn force_refresh(mut self) -> Self {
+        self.force_refresh = true;
+        self
+    }
+}
 /// Decide what happens when all indices are loaded.
-#[derive(Default, Clone, Copy)]
+#[derive(Default, Clone, Copy, Debug, Eq, PartialEq)]
 pub enum RefreshMode {
     /// Check for new or changed pack indices (and pack data files) when the last known index is loaded.
     /// During runtime handles configured for stable pack locations retain the corresponding indices and packs.
     #[default]
     AfterAllIndicesLoaded,
+    /// Check for new or changed pack indices only if the last successful refresh is at least this old.
+    ///
+    /// This throttles filesystem scans caused by repeated misses. A duration of zero behaves like
+    /// [`AfterAllIndicesLoaded`](Self::AfterAllIndicesLoaded).
+    AfterDuration(Duration),
     /// Use this if you expect a lot of missing objects that shouldn't trigger refreshes even after all packs are loaded.
     /// This comes at the risk of not learning that the packs have changed in the mean time.
     Never,
             debug.at(point);
         }
     }
+    pub(crate) fn now(&self) -> std::time::Instant {
+        self.debug
+            .as_ref()
+            .map_or_else(std::time::Instant::now, init::debug::Options::now)
+    }
+}
+#[cfg(not(feature = "test-support"))]
+impl Store {
+    pub(crate) fn now(&self) -> std::time::Instant {
+        std::time::Instant::now()
+    }
 }
 pub(crate) mod handle;

gix-odb/src/store_impls/dynamic/prefix.rs+4−2

     ///
     /// ### Performance Note
     ///
-    /// - Unless the handles refresh mode is set to `Never`, each lookup will trigger a refresh of the object databases files
+    /// - With [`RefreshMode::AfterAllIndicesLoaded`](super::RefreshMode::AfterAllIndicesLoaded), each lookup will refresh the
-    ///   on disk if the prefix doesn't lead to ambiguous results.
+    ///   object database files on disk if the prefix doesn't lead to ambiguous results. Use
+    ///   [`RefreshMode::AfterDuration`](super::RefreshMode::AfterDuration) to throttle these scans, or
+    ///   [`RefreshMode::Never`](super::RefreshMode::Never) to disable them.
     /// - Since all objects need to be examined to assure non-ambiguous return values, after calling this method all indices will
     ///   be loaded.
     /// - If `candidates` is `Some(…)`, the traversal will continue to obtain all candidates, which takes more time

gix-odb/src/store_impls/dynamic/structure.rs+9−0

@@ -47,6 +47,15 @@ pub enum IndexState { · 46 unmodified lines
47	}	47	}
48		48
49	impl Store {	49	impl Store {
		50	/// Mark the known disk state stale after the caller changed the object database.
		51	///
		52	/// This only makes the next miss eligible for a refresh; it performs no I/O.
		53	/// An ongoing refresh is allowed to finish first so it cannot overwrite this invalidation.
		54	pub fn mark_disk_state_stale(&self) {
		55	let _write = self.write.lock();
		56	*self.last_successful_disk_state_consolidation.lock() = None;
		57	}
		58
50	/// Return information about all files known to us as well as their loading state.	59	/// Return information about all files known to us as well as their loading state.
51	///	60	///
52	/// Note that this call is expensive as it gathers additional information about loose object databases.	61	/// Note that this call is expensive as it gathers additional information about loose object databases.

gix-odb/tests/odb/store/dynamic_scenarios.rs+254−5

@@ -343,9 +343,12 @@ fn debug_hooks_coordinate_contending_failed_index_loaders() -> Result { · 342 unmodified lines
343	#[cfg(feature = "parallel")]	343	#[cfg(feature = "parallel")]
344	#[test]	344	#[test]
345	fn debug_hooks_coalesce_successful_refreshes() -> Result {	345	fn debug_hooks_coalesce_successful_refreshes() -> Result {
346	use std::sync::{	346	use std::{
347	Arc,	347	sync::{
348	atomic::{AtomicBool, Ordering},	348	Arc, Mutex,
		349	atomic::{AtomicBool, Ordering},
		350	},
		351	time::{Duration, Instant},
349	};	352	};
350		353
351	use gix_odb::store::init::debug::Point;	354	use gix_odb::store::init::debug::Point;
@@ -354,6 +357,7 @@ fn debug_hooks_coalesce_successful_refreshes() -> Result { · 2 unmodified lines
354	let (point_tx, point_rx) = crossbeam_channel::unbounded();	357	let (point_tx, point_rx) = crossbeam_channel::unbounded();
355	let (resume_tx, resume_rx) = crossbeam_channel::bounded(0);	358	let (resume_tx, resume_rx) = crossbeam_channel::bounded(0);
356	let pause_next_refresh = Arc::new(AtomicBool::new(false));	359	let pause_next_refresh = Arc::new(AtomicBool::new(false));
		360	let now = Arc::new(Mutex::new(Instant::now()));
357	let debug = gix_odb::store::init::debug::Options::new({	361	let debug = gix_odb::store::init::debug::Options::new({
358	let pause_next_refresh = Arc::clone(&pause_next_refresh);	362	let pause_next_refresh = Arc::clone(&pause_next_refresh);
359	move \|point\| {	363	move \|point\| {
@@ -364,8 +368,12 @@ fn debug_hooks_coalesce_successful_refreshes() -> Result { · 4 unmodified lines
364	resume_rx.recv().expect("the test releases the refresh scan");	368	resume_rx.recv().expect("the test releases the refresh scan");
365	}	369	}
366	}	370	}
		371	})
		372	.with_clock({
		373	let now = Arc::clone(&now);
		374	move \|\| *now.lock().expect("the test clock isn't poisoned")
367	});	375	});
368	let handle = gix_odb::at_opts(	376	let mut handle = gix_odb::at_opts(
369	fixture.objects_dir(Database::Primary),	377	fixture.objects_dir(Database::Primary),
370	fixture.manifest.object_hash,	378	fixture.manifest.object_hash,
371	Vec::new(),	379	Vec::new(),
@@ -420,6 +428,12 @@ fn debug_hooks_coalesce_successful_refreshes() -> Result { · 48 unmodified lines
420	"the changed ODB adds one refresh"	428	"the changed ODB adds one refresh"
421	);	429	);
422		430
		431	let refresh_after = Duration::from_secs(1);
		432	handle.refresh = gix_odb::store::RefreshMode::AfterDuration(refresh_after);
		433	{
		434	let mut now = now.lock().expect("the test clock isn't poisoned");
		435	*now += refresh_after;
		436	}
423	point_rx.try_iter().for_each(drop);	437	point_rx.try_iter().for_each(drop);
424	let (first, second, observed) = contended_lookup(	438	let (first, second, observed) = contended_lookup(
425	handle.clone(),	439	handle.clone(),
@@ -440,7 +454,7 @@ fn debug_hooks_coalesce_successful_refreshes() -> Result { · 14 unmodified lines
440	.filter(\|point\| matches!(point, Point::RefreshScanStarted))	454	.filter(\|point\| matches!(point, Point::RefreshScanStarted))
441	.count(),	455	.count(),
442	1,	456	1,
443	"contending misses scan the unchanged ODB once"	457	"contending handles scan the unchanged ODB once at the shared deadline"
444	);	458	);
445	assert_eq!(	459	assert_eq!(
446	handle.store_ref().metrics().num_refreshes,	460	handle.store_ref().metrics().num_refreshes,
@@ -968,6 +982,241 @@ fn never_refresh_does_not_retry_failed_initial_scan() -> Result { · 521 unmodified lines
968	Ok(())	982	Ok(())
969	}	983	}
970		984
		985	#[test]
		986	fn refresh_after_duration_is_shared_by_handles_until_the_deadline() -> Result {
		987	use std::{
		988	sync::{Arc, Mutex},
		989	time::{Duration, Instant},
		990	};
		991
		992	let mut fixture = OdbFixture::from_script()?;
		993	let now = Arc::new(Mutex::new(Instant::now()));
		994	let debug = gix_odb::store::init::debug::Options::new(\|_\| {}).with_clock({
		995	let now = Arc::clone(&now);
		996	move \|\| *now.lock().expect("the test clock isn't poisoned")
		997	});
		998	let mut first = gix_odb::at_opts(
		999	fixture.objects_dir(Database::Primary),
		1000	fixture.manifest.object_hash,
		1001	Vec::new(),
		1002	gix_odb::store::init::Options {
		1003	slots: gix_odb::store::init::Slots::Growable { initial: 1 },
		1004	debug: Some(debug),
		1005	..Default::default()
		1006	},
		1007	)?;
		1008	let refresh_after = Duration::from_secs(1);
		1009	first.refresh = gix_odb::store::RefreshMode::AfterDuration(refresh_after);
		1010	let second = first.clone();
		1011	let id = fixture.manifest.pack(Pack::A).object_ids[0];
		1012
		1013	assert_eq!(
		1014	first.packed_object_count()?,
		1015	0,
		1016	"the empty store initializes without packed objects"
		1017	);
		1018	assert_eq!(
		1019	first.store_ref().metrics().num_refreshes,
		1020	1,
		1021	"initialization scans the shared store once"
		1022	);
		1023	fixture.install_pack(Database::Primary, Pack::A)?;
		1024	assert_object(&second, &id)?;
		1025	assert_eq!(
		1026	first.store_ref().metrics().num_refreshes,
		1027	2,
		1028	"initialization leaves the first miss-triggered refresh available to discover published objects"
		1029	);
		1030	assert_missing(&first, &fixture.manifest.missing_id())?;
		1031	assert_eq!(
		1032	first.store_ref().metrics().num_refreshes,
		1033	2,
		1034	"the other handle shares the freshness window established by the refresh"
		1035	);
		1036	fixture.install_pack(Database::Primary, Pack::B)?;
		1037	let newly_published = fixture.manifest.pack(Pack::B).object_ids[0];
		1038	assert_missing(&second, &newly_published)?;
		1039	first.store_ref().mark_disk_state_stale();
		1040	assert_object(&second, &newly_published)?;
		1041	assert_eq!(
		1042	first.store_ref().metrics().num_refreshes,
		1043	3,
		1044	"marking a known mutation stale makes the next lookup refresh without performing eager I/O"
		1045	);
		1046
		1047	{
		1048	let mut now = now.lock().expect("the test clock isn't poisoned");
		1049	*now += refresh_after;
		1050	}
		1051	assert_missing(&second, &fixture.manifest.missing_id())?;
		1052	assert_eq!(
		1053	first.store_ref().metrics().num_refreshes,
		1054	4,
		1055	"the first handle to miss at the deadline refreshes the shared store"
		1056	);
		1057	Ok(())
		1058	}
		1059
		1060	#[cfg(feature = "parallel")]
		1061	#[test]
		1062	fn invalidation_during_refresh_preserves_newly_published_packs() -> Result {
		1063	use std::{
		1064	sync::{
		1065	Arc,
		1066	atomic::{AtomicBool, Ordering},
		1067	},
		1068	time::{Duration, Instant},
		1069	};
		1070
		1071	use gix_odb::store::init::debug::Point;
		1072
		1073	let mut fixture = OdbFixture::from_script()?;
		1074	let (published_tx, published_rx) = crossbeam_channel::bounded(1);
		1075	let (resume_tx, resume_rx) = crossbeam_channel::bounded(1);
		1076	let pause_next_publication = Arc::new(AtomicBool::new(false));
		1077	let now = Instant::now();
		1078	let debug = gix_odb::store::init::debug::Options::new({
		1079	let pause_next_publication = Arc::clone(&pause_next_publication);
		1080	move \|point\| {
		1081	if matches!(point, Point::IndexStatePublished) && pause_next_publication.swap(false, Ordering::SeqCst) {
		1082	published_tx
		1083	.send(())
		1084	.expect("the test observes publication after scanning");
		1085	resume_rx.recv().expect("the test resumes the refresh");
		1086	}
		1087	}
		1088	})
		1089	.with_clock(move \|\| now);
		1090	let store = Arc::new(gix_odb::Store::at_opts(
		1091	fixture.objects_dir(Database::Primary),
		1092	fixture.manifest.object_hash,
		1093	&mut std::iter::empty(),
		1094	gix_odb::store::init::Options {
		1095	debug: Some(debug),
		1096	..Default::default()
		1097	},
		1098	)?);
		1099	store.structure()?;
		1100	let mut first = store.to_handle_arc();
		1101	first.refresh = gix_odb::store::RefreshMode::AfterDuration(Duration::from_secs(1));
		1102	let second = first.clone();
		1103	fixture.install_pack(Database::Primary, Pack::A)?;
		1104	let object_id = fixture.manifest.pack(Pack::A).object_ids[0];
		1105	pause_next_publication.store(true, Ordering::SeqCst);
		1106	let refresh = std::thread::spawn(move \|\| {
		1107	first
		1108	.try_find(&object_id, &mut Vec::new())
		1109	.map(\|object\| object.is_some())
		1110	});
		1111	published_rx.recv_timeout(Duration::from_secs(10))?;
		1112
		1113	fixture.install_pack(Database::Primary, Pack::B)?;
		1114	let (started_tx, started_rx) = crossbeam_channel::bounded(1);
		1115	let (invalidated_tx, invalidated_rx) = crossbeam_channel::bounded(1);
		1116	let invalidation = std::thread::spawn(move \|\| {
		1117	started_tx.send(()).expect("the test observes the invalidating thread");
		1118	store.mark_disk_state_stale();
		1119	invalidated_tx
		1120	.send(())
		1121	.expect("the test observes completed invalidation");
		1122	});
		1123	started_rx.recv_timeout(Duration::from_secs(10))?;
		1124	// An uncoordinated invalidation can finish while the scan is paused; a coordinated one waits for its release.
		1125	let _ = invalidated_rx.recv_timeout(Duration::from_secs(1));
		1126	resume_tx
		1127	.send(())
		1128	.expect("the refresh can complete before checking invalidation");
		1129	assert!(
		1130	refresh.join().expect("the refresh does not panic")?,
		1131	"the refresh sees the pack published before its scan"
		1132	);
		1133	invalidation.join().expect("invalidation does not panic");
		1134	let object_id = fixture.manifest.pack(Pack::B).object_ids[0];
		1135	assert!(
		1136	second.try_find(&object_id, &mut Vec::new())?.is_some(),
		1137	"invalidation after the directory scan survives refresh completion without advancing the clock"
		1138	);
		1139	Ok(())
		1140	}
		1141
		1142	#[test]
		1143	fn a_failed_refresh_does_not_renew_the_freshness_window() -> Result {
		1144	use std::{
		1145	sync::{Arc, Mutex},
		1146	time::{Duration, Instant},
		1147	};
		1148
		1149	let mut fixture = OdbFixture::from_script()?;
		1150	let now = Arc::new(Mutex::new(Instant::now()));
		1151	let debug = gix_odb::store::init::debug::Options::new(\|_\| {}).with_clock({
		1152	let now = Arc::clone(&now);
		1153	move \|\| *now.lock().expect("the test clock isn't poisoned")
		1154	});
		1155	let mut handle = gix_odb::at_opts(
		1156	fixture.objects_dir(Database::Primary),
		1157	fixture.manifest.object_hash,
		1158	Vec::new(),
		1159	gix_odb::store::init::Options {
		1160	slots: gix_odb::store::init::Slots::Limit(1),
		1161	debug: Some(debug),
		1162	..Default::default()
		1163	},
		1164	)?;
		1165	let refresh_after = Duration::from_secs(1);
		1166	handle.refresh = gix_odb::store::RefreshMode::AfterDuration(refresh_after);
		1167	assert_eq!(
		1168	handle.packed_object_count()?,
		1169	0,
		1170	"the empty store initializes without packed objects"
		1171	);
		1172
		1173	fixture.install_pack(Database::Primary, Pack::A)?;
		1174	fixture.install_pack(Database::Primary, Pack::B)?;
		1175	let mut buffer = Vec::new();
		1176	handle
		1177	.try_find(&fixture.manifest.missing_id(), &mut buffer)
		1178	.expect_err("one slot cannot hold both newly discovered indices");
		1179	assert_eq!(
		1180	handle.store_ref().metrics().num_refreshes,
		1181	2,
		1182	"the failed refresh is attempted once"
		1183	);
		1184
		1185	fixture.remove_pack(Database::Primary, Pack::B)?;
		1186	assert_object(&handle, &fixture.manifest.pack(Pack::A).object_ids[0])?;
		1187	assert_eq!(
		1188	handle.store_ref().metrics().num_refreshes,
		1189	3,
		1190	"the next lookup retries because failure did not renew freshness"
		1191	);
		1192	Ok(())
		1193	}
		1194
		1195	#[test]
		1196	fn a_missing_known_pack_bypasses_the_refresh_deadline() -> Result {
		1197	use std::time::Duration;
		1198
		1199	let mut fixture = OdbFixture::from_script()?;
		1200	fixture.install_pack(Database::Primary, Pack::A)?;
		1201	let mut handle = open(&fixture, 1)?;
		1202	handle.refresh = gix_odb::store::RefreshMode::AfterDuration(Duration::MAX);
		1203	let id = fixture.manifest.pack(Pack::A).object_ids[0];
		1204	assert_eq!(
		1205	handle.packed_object_count()?,
		1206	fixture.manifest.pack(Pack::A).object_ids.len() as u64,
		1207	"the index is known while its pack remains unopened"
		1208	);
		1209	fixture.remove(Database::Primary, Pack::A, Component::Pack)?;
		1210
		1211	assert_missing(&handle, &id)?;
		1212	assert_eq!(
		1213	handle.store_ref().metrics().num_refreshes,
		1214	2,
		1215	"losing a pack named by a known index forces structural reconciliation"
		1216	);
		1217	Ok(())
		1218	}
		1219
971	#[test]	1220	#[test]
972	fn a_midx_rewrite_does_not_require_a_spare_slot() -> Result {	1221	fn a_midx_rewrite_does_not_require_a_spare_slot() -> Result {
973	let mut fixture = OdbFixture::from_script()?;	1222	let mut fixture = OdbFixture::from_script()?;

gix/src/config/cache/init.rs+5−0

         let object_kind_hint = util::disambiguate_hint(&config, lenient_config)?;
         let (static_pack_cache_limit_bytes, pack_cache_bytes, object_cache_bytes, alloc_limit_bytes) =
             util::parse_object_caches(&config, lenient_config, filter_config_section)?;
+        let object_refresh_mode = util::parse_object_refresh_mode(&config, lenient_config, filter_config_section)?;
         let loose_compression = super::access::loose_compression(&config, lenient_config, filter_config_section)?;
         // NOTE: When adding a new initial cache, consider adjusting `reread_values_and_clear_caches()` as well.
         Ok(Cache {
             pack_cache_bytes,
             object_cache_bytes,
             alloc_limit_bytes,
+            object_refresh_mode,
             loose_compression,
             reflog,
             refs_namespace,
             self.object_cache_bytes,
             self.alloc_limit_bytes,
         ) = util::parse_object_caches(config, self.lenient_config, self.filter_config_section)?;
+        self.object_refresh_mode =
+            util::parse_object_refresh_mode(config, self.lenient_config, self.filter_config_section)?;
         let loose_compression =
             super::access::loose_compression(config, self.lenient_config, self.filter_config_section)?;
         self.loose_compression = loose_compression;
     fn apply_changed_values(&mut self) {
         self.refs.write_reflog = util::reflog_or_default(self.config.reflog, self.workdir().is_some());
         self.refs.namespace.clone_from(&self.config.refs_namespace);
+        self.objects.refresh = self.config.object_refresh_mode;
     }
 }

gix/src/config/cache/util.rs+12−0

@@ -98,6 +98,18 @@ pub(crate) fn reflog_or_default( · 97 unmodified lines
98		98
99	pub(crate) type ObjectCaches = (Option<usize>, Option<usize>, usize, Option<usize>);	99	pub(crate) type ObjectCaches = (Option<usize>, Option<usize>, usize, Option<usize>);
100		100
		101	pub(crate) fn parse_object_refresh_mode(
		102	config: &gix_config::File,
		103	lenient: bool,
		104	mut filter_config_section: fn(&gix_config::file::Metadata) -> bool,
		105	) -> Result<gix_odb::store::RefreshMode, Error> {
		106	let refresh_after = gitoxide::Objects::REFRESH_AFTER
		107	.try_into_duration(config.integer_filter("gitoxide.objects.refreshAfter", &mut filter_config_section))
		108	.with_leniency(lenient)?
		109	.unwrap_or(gitoxide::Objects::REFRESH_AFTER_DEFAULT);
		110	Ok(gix_odb::store::RefreshMode::AfterDuration(refresh_after))
		111	}
		112
101	/// Return `(static_pack_cache_limit, pack_cache_bytes, object_cache_bytes, alloc_limit_bytes)` as parsed from gix-config.	113	/// Return `(static_pack_cache_limit, pack_cache_bytes, object_cache_bytes, alloc_limit_bytes)` as parsed from gix-config.
102	pub(crate) fn parse_object_caches(	114	pub(crate) fn parse_object_caches(
103	config: &gix_config::File,	115	config: &gix_config::File,

gix/src/config/mod.rs+4−0

     #[error(transparent)]
     ConfigBoolean(#[from] boolean::Error),
     #[error(transparent)]
+    ConfigDuration(#[from] duration::Error),
+    #[error(transparent)]
     ConfigUnsigned(#[from] unsigned_integer::Error),
     #[error(transparent)]
     ConfigTypedString(#[from] key::GenericErrorWithValue),
     pub(crate) object_cache_bytes: usize,
     /// The maximum size of a single allocation caused by user-controlled on-disk packed object data.
     pub(crate) alloc_limit_bytes: Option<usize>,
+    /// The policy for filesystem refreshes caused by object misses.
+    pub(crate) object_refresh_mode: gix_odb::store::RefreshMode,
     /// The compression level to use when writing loose objects, from `core.looseCompression` or `core.compression`.
     pub(crate) loose_compression: gix_zlib::Compression,
     /// The amount of bytes we can hold in our static LRU cache. Otherwise, go with the defaults.

gix/src/config/tree/sections/gitoxide.rs+8−0

             keys::UnsignedInteger::new_unsigned_integer("allocLimitIfReducedTrust", &Gitoxide::OBJECTS).with_note(
                 "The default allocation limit used for reduced-trust repositories when no explicit allocLimit is configured; set to 0 to disable it",
             );
+        /// The default minimum age of the last successful object database refresh before another miss may refresh it.
+        pub const REFRESH_AFTER_DEFAULT: std::time::Duration = std::time::Duration::from_secs(1);
+        /// The `gitoxide.objects.refreshAfter` key.
+        pub const REFRESH_AFTER: keys::DurationInMilliseconds =
+            keys::DurationInMilliseconds::new_duration("refreshAfter", &Gitoxide::OBJECTS).with_note(
+                "The minimum age of the last successful object database refresh before another object miss may refresh it, in milliseconds; 0 refreshes strictly on every miss",
+            );
         /// The `gitoxide.objects.noReplace` key.
         pub const NO_REPLACE: keys::Boolean = keys::Boolean::new_boolean("noReplace", &Gitoxide::OBJECTS);
         /// The `gitoxide.objects.replaceRefBase` key.
                 &Self::CACHE_LIMIT,
                 &Self::ALLOC_LIMIT,
                 &Self::ALLOC_LIMIT_IF_REDUCED_TRUST,
+                &Self::REFRESH_AFTER,
                 &Self::REPLACE_REF_BASE,
             ]
         }

gix/src/remote/connection/fetch/receive_pack.rs+1−0

@@ -193,6 +193,7 @@ where · 192 unmodified lines
193	repo.object_hash(),	193	repo.object_hash(),
194	write_pack_options,	194	write_pack_options,
195	)?;	195	)?;
		196	repo.objects.store_ref().mark_disk_state_stale();
196	may_read_to_end = true;	197	may_read_to_end = true;
197	Some(res)	198	Some(res)
198	} else {	199	} else {

gix/src/repository/init.rs+1−1

     }
 }
-#[cfg_attr(not(feature = "max-performance-safe"), allow(unused_variables, unused_mut))]
 pub(crate) fn setup_objects(objects: &mut crate::OdbHandle, config: &crate::config::Cache) {
+    objects.refresh = config.object_refresh_mode;
     #[cfg(feature = "max-performance-safe")]
     {
         match config.pack_cache_bytes {

gix/tests/gix/config/tree.rs+11−0

         }
     }
     mod objects {
+        use std::time::Duration;
         use gix::config::tree::{Key, gitoxide};
         #[test]
             );
             Ok(())
         }
+        #[test]
+        fn refresh_after() -> crate::Result {
+            assert_eq!(
+                gitoxide::Objects::REFRESH_AFTER.validated_assignment_fmt(&Duration::from_secs(1).as_millis())?,
+                "gitoxide.objects.refreshAfter=1000"
+            );
+            Ok(())
+        }
     }
 }

gix/tests/gix/repository/mod.rs+3−4

 #[test]
 fn size_in_memory() {
     let actual_size = std::mem::size_of::<Repository>();
-    // The selected index path adds one `PathBuf` to the repository.
+    // Allow the selected index path, network-client cache, and refresh policy stored in both the ODB handle
-    // Network-client features add protocol permission caching to `Repository::config`,
+    // and configuration cache. The largest observed layout is on 64-bit Windows.
-    // which grows the type by one more cached cell.
+    let limit = 1528;
-    let limit = 1500;
     assert!(
         actual_size <= limit,
         "size of Repository shouldn't change without us noticing, it's meant to be cloned: should have been below {limit:?}, was {actual_size}"

gix/tests/gix/repository/open.rs+40−0

@@ -849,6 +849,46 @@ mod pack_alloc_limit_bytes { · 848 unmodified lines
849	}	849	}
850	}	850	}
851		851
		852	mod object_refresh {
		853	use std::time::Duration;
		854
		855	use gix_odb::store::RefreshMode;
		856
		857	use crate::util::repo_opts;
		858
		859	#[test]
		860	fn defaults_to_a_configurable_freshness_window() -> crate::Result {
		861	let mut default = repo_opts("make_packed_and_loose.sh", crate::util::restricted())?.to_thread_local();
		862	assert_eq!(
		863	default.objects.refresh_mode(),
		864	RefreshMode::AfterDuration(Duration::from_secs(1)),
		865	"gix avoids repeated miss-triggered filesystem scans by default"
		866	);
		867	{
		868	let mut config = default.config_snapshot_mut();
		869	config.set_raw_value("gitoxide.objects.refreshAfter", "50")?;
		870	config.commit()?;
		871	}
		872	assert_eq!(
		873	default.objects.refresh_mode(),
		874	RefreshMode::AfterDuration(Duration::from_millis(50)),
		875	"committing configuration updates the active object handle"
		876	);
		877
		878	let mut configured = repo_opts(
		879	"make_packed_and_loose.sh",
		880	gix::open::Options::isolated().config_overrides(["gitoxide.objects.refreshAfter=250"]),
		881	)?
		882	.to_thread_local();
		883	assert_eq!(
		884	configured.objects.refresh_mode(),
		885	RefreshMode::AfterDuration(Duration::from_millis(250)),
		886	"gitoxide.objects.refreshAfter configures the freshness window"
		887	);
		888	Ok(())
		889	}
		890	}
		891
852	mod worktree {	892	mod worktree {
853	use gix::open;	893	use gix::open;
854		894