ktstr/cache/mod.rs
1//! Kernel image cache for ktstr.
2//!
3//! Manages a local cache of built kernel images under an XDG-compliant
4//! directory. Each cached kernel is a directory containing the boot
5//! image, optionally a stripped vmlinux ELF (symbol table, BTF, and
6//! the section headers that monitor/probe code reads), and a
7//! `metadata.json` descriptor. `CONFIG_HZ` is recovered from the
8//! embedded IKCONFIG blob in the stripped vmlinux (ktstr.kconfig
9//! forces `CONFIG_IKCONFIG=y`), so no separate `.config` sidecar is
10//! cached.
11//!
12//! # Cache location
13//!
14//! Resolved in order:
15//! 1. `KTSTR_CACHE_DIR` environment variable
16//! 2. `$XDG_CACHE_HOME/ktstr/kernels/`
17//! 3. `$HOME/.cache/ktstr/kernels/`
18//!
19//! # Submodule layout
20//!
21//! - `metadata` — public types: [`KernelSource`], [`KernelMetadata`],
22//! [`CacheArtifacts`], [`KconfigStatus`], [`CacheEntry`],
23//! [`ListedEntry`], plus the internal `classify_corrupt_reason`
24//! dispatcher.
25//! - `cache_dir` — [`CacheDir`] handle, lock guards
26//! ([`SharedLockGuard`], [`ExclusiveLockGuard`]), store/lookup/list/
27//! clean lifecycle, and reader/writer-asymmetric lock policy.
28//! - `housekeeping` — atomic-rename install primitives, cache-key
29//! and image-name validators, `read_metadata` decoder, and the
30//! `clean_orphaned_tmp_dirs` cross-PID sweep.
31//! - `vmlinux_strip` — ELF strip pipeline (`strip_vmlinux_debug`,
32//! `neutralize_relocs`, `strip_keep_list`, `strip_debug_prefix`)
33//! plus the keep-list / zero-data section-name unions.
34//! - `resolve` — env-cascade root resolution
35//! (`resolve_cache_root_with_suffix`, `validate_home_for_cache`,
36//! `path_inside_cache_root`) and source-tree path helpers
37//! ([`prefer_source_tree_for_dwarf`], [`recover_local_source_tree`]).
38//!
39//! Each submodule owns its tests in a `#[cfg(test)] mod tests`
40//! block — inline in the same file except `cache_dir`, whose tests
41//! live in `cache_dir_tests.rs` via `#[path]`; shared test fixtures
42//! used by
43//! more than one submodule's tests live in
44//! `shared_test_helpers`.
45
46use crate::flock::LOCK_DIR_NAME;
47
48#[doc(hidden)]
49pub mod artifact_tree;
50mod cache_dir;
51pub(crate) mod content;
52mod housekeeping;
53mod metadata;
54mod resolve;
55mod vmlinux_strip;
56
57// Public API re-exports — preserve every `crate::cache::*` path that
58// external callers (lib.rs, cli, fetch.rs, monitor/*, probe/btf.rs,
59// vmm/disk_template, test_support/*, remote_cache.rs, stats,
60// flock) rely on.
61
62pub(crate) use cache_dir::GitBuilderLockGuard;
63pub use cache_dir::{CacheDir, ExclusiveLockGuard, SharedLockGuard};
64pub(crate) use metadata::kernel_config_include_for_image;
65pub use metadata::{
66 CacheArtifacts, CacheEntry, KconfigStatus, KernelMetadata, KernelSource, ListedEntry,
67 boot_modules_for_image, initrd_compression_for_image, ordered_boot_modules_in,
68};
69pub use resolve::{prefer_source_tree_for_dwarf, recover_local_source_tree};
70
71// Re-export KernelId from kernel_path (canonical definition, std-only).
72pub use crate::kernel_path::KernelId;
73
74// Crate-internal API re-exports for callers in other modules:
75// path_inside_cache_root (monitor/btf_offsets),
76// resolve_cache_root_with_suffix (vmm/disk_template,
77// vmm/cast_analysis_load), resolve_lock_dir
78// (vmm/host_topology, cli/locks).
79pub(crate) use resolve::{
80 path_inside_cache_root, resolve_cache_root_with_suffix, resolve_lock_dir,
81};
82
83/// Create one strict copy-on-write clone of `source` at `destination`.
84///
85/// This is the pathname-facing boundary used by cross-crate cache lifecycle
86/// code. Unlike the older kernel-cache staging helper, it deliberately has no
87/// byte-copy fallback: callers choosing this API require shared backing
88/// extents and must keep both paths on one reflink-capable filesystem.
89/// `destination` must not already exist. A failed clone removes the empty
90/// destination inode before returning.
91///
92/// # Errors
93///
94/// Returns an error when either path cannot be opened safely, `source` is not
95/// a regular file, the files are not on a reflink-capable filesystem, or the
96/// destination metadata cannot be finalized.
97#[doc(hidden)]
98pub fn reflink_file_required(
99 source: impl AsRef<std::path::Path>,
100 destination: impl AsRef<std::path::Path>,
101) -> anyhow::Result<u64> {
102 use anyhow::Context as _;
103 use std::os::unix::fs::OpenOptionsExt as _;
104
105 let source = source.as_ref();
106 let destination = destination.as_ref();
107 let source_file = std::fs::OpenOptions::new()
108 .read(true)
109 .custom_flags(libc::O_NOFOLLOW | libc::O_NONBLOCK)
110 .open(source)
111 .with_context(|| format!("open strict reflink source {}", source.display()))?;
112 let source_metadata = source_file
113 .metadata()
114 .with_context(|| format!("stat strict reflink source {}", source.display()))?;
115 anyhow::ensure!(
116 source_metadata.is_file(),
117 "strict reflink source is not a regular file: {}",
118 source.display(),
119 );
120 let destination_file = std::fs::OpenOptions::new()
121 .read(true)
122 .write(true)
123 .create_new(true)
124 .custom_flags(libc::O_NOFOLLOW)
125 .open(destination)
126 .with_context(|| {
127 format!(
128 "create strict reflink destination {}",
129 destination.display(),
130 )
131 })?;
132 if let Err(error) = crate::reflink::ficlone(&destination_file, &source_file) {
133 drop(destination_file);
134 let _ = std::fs::remove_file(destination);
135 return Err(error).with_context(|| {
136 format!(
137 "FICLONE is required for cached COW persistence {} -> {}; place both paths on the same reflink-capable filesystem",
138 source.display(),
139 destination.display(),
140 )
141 });
142 }
143 if let Err(error) = destination_file.set_permissions(source_metadata.permissions()) {
144 drop(destination_file);
145 let _ = std::fs::remove_file(destination);
146 return Err(error).with_context(|| {
147 format!(
148 "preserve strict reflink destination permissions {}",
149 destination.display(),
150 )
151 });
152 }
153 match destination_file.metadata() {
154 Ok(metadata) => Ok(metadata.len()),
155 Err(error) => {
156 drop(destination_file);
157 let _ = std::fs::remove_file(destination);
158 Err(error).with_context(|| {
159 format!("stat strict reflink destination {}", destination.display(),)
160 })
161 }
162 }
163}
164
165/// Cache root for the `cargo ktstr affected` per-scheduler input-set cache.
166///
167/// Exposed as `pub` (unlike the crate-internal
168/// `resolve_cache_root_with_suffix`) because the affected engine lives in
169/// the cargo-ktstr BIN crate, a separate crate that reaches it as
170/// `ktstr::cache::affected_cache_root()`. Runs the same `KTSTR_CACHE_DIR` ->
171/// `$XDG_CACHE_HOME` -> `$HOME/.cache` cascade as every other ktstr cache,
172/// under the `affected` suffix.
173pub fn affected_cache_root() -> anyhow::Result<std::path::PathBuf> {
174 resolve_cache_root_with_suffix("affected")
175}
176
177/// Host-global coordination namespace for wrapper-owned Cargo output locks.
178///
179/// Output ownership follows the canonical Cargo target directory, not the
180/// caller's artifact-cache selection. Two invocations which deliberately use
181/// different `KTSTR_CACHE_DIR`s can still write the same `CARGO_TARGET_DIR`;
182/// placing this lock below either cache root would let both writers enter
183/// Cargo's artifact lock while holding separate ktstr build reservations.
184/// `KTSTR_LOCK_DIR` is the existing machine-wide coordination namespace for
185/// ktstr participants, with `/tmp` as its normal fallback.
186///
187/// The version is intentionally part of the directory name. Every ktstr
188/// writer participating in this protocol acquires the same per-target-dir
189/// lock before spawning Cargo and retains it until emitted artifacts are
190/// pinned. There is no lookup of an older cache-rooted namespace.
191pub fn cargo_build_output_lock_root() -> anyhow::Result<std::path::PathBuf> {
192 Ok(resolve_lock_dir().join("ktstr-cargo-build-output-v3"))
193}
194
195/// Machine-local record namespace for reusable Cargo artifact trees.
196///
197/// The files referenced by these records live in the ordinary shared content
198/// CAS; this root contains only small, reconstructible tree manifests and
199/// their cross-process election locks.
200#[doc(hidden)]
201pub fn cargo_artifact_tree_cache_root() -> anyhow::Result<std::path::PathBuf> {
202 resolve_cache_root_with_suffix("cargo-artifact-tree-v1")
203}
204
205/// Return ktstr's stable, fixed-seed fast digest for one exact file revision.
206///
207/// This is the source-input half of the scheduler-build cache identity. It
208/// uses the same machine-wide inode-revision memo as content-CAS publication,
209/// so repeated source-tree walks do not reread unchanged files in one shared
210/// checkout.
211#[doc(hidden)]
212pub fn content_file_digest(path: impl AsRef<std::path::Path>) -> anyhow::Result<u64> {
213 let path = path.as_ref();
214 let pinned = pin_content_file(path)?;
215 content::cached_file_digest(pinned.source(), pinned.identity)
216}
217
218/// Scoped file-digest client for large immutable source snapshots.
219///
220/// A session pins the machine content-cache namespace and its descriptor-
221/// relative subdirectories once. Every file retains the same exact-inode,
222/// cross-process memo validation as [`content_file_digest`], without reopening
223/// the complete cache namespace for every path in a source tree.
224#[doc(hidden)]
225pub struct ContentFileDigestSession {
226 namespace: content::ContentNamespaceLease,
227}
228
229impl ContentFileDigestSession {
230 pub fn open() -> anyhow::Result<Self> {
231 Ok(Self {
232 namespace: content::lease_content_namespace()?,
233 })
234 }
235
236 pub fn digest(&self, path: impl AsRef<std::path::Path>) -> anyhow::Result<u64> {
237 let pinned = pin_content_file(path)?;
238 self.namespace.digest_file(pinned.source(), pinned.identity)
239 }
240}
241
242/// One immutable, content-addressed snapshot of an input file.
243///
244/// The original file descriptor and the shared CAS lease remain live until
245/// this owner is dropped. [`Self::path`] is therefore a stable pathname for
246/// child processes even if the caller's original pathname is replaced or the
247/// cache's background garbage collection runs.
248pub struct ContentFileSnapshot {
249 _source: std::fs::File,
250 lease: content::ContentObjectLease,
251 content_hash: u64,
252 len: u64,
253}
254
255/// One opened regular-file revision retained independently of its pathname.
256///
257/// Cargo installs final artifacts by atomic replacement. Opening the artifact
258/// while the wrapper's output lock is held pins that exact inode; a later
259/// pathname replacement cannot retarget this owner.
260pub struct PinnedContentFile {
261 source: std::fs::File,
262 identity: content::StableFileIdentity,
263 display_path: std::path::PathBuf,
264}
265
266impl PinnedContentFile {
267 /// Original pathname used to open this revision, for diagnostics and
268 /// provenance. Consumers must use the pinned descriptor for bytes.
269 pub fn source_path(&self) -> &std::path::Path {
270 &self.display_path
271 }
272
273 /// Linux descriptor pathname for an exact-inode child execution probe.
274 #[doc(hidden)]
275 pub fn proc_fd_path(&self) -> std::path::PathBuf {
276 use std::os::fd::AsRawFd as _;
277
278 std::path::PathBuf::from(format!("/proc/self/fd/{}", self.source.as_raw_fd()))
279 }
280
281 pub(crate) fn source(&self) -> &std::fs::File {
282 &self.source
283 }
284
285 pub(crate) fn into_parts(
286 self,
287 ) -> (
288 std::fs::File,
289 content::StableFileIdentity,
290 std::path::PathBuf,
291 ) {
292 (self.source, self.identity, self.display_path)
293 }
294}
295
296/// Open and pin one regular-file revision without publishing it yet.
297pub fn pin_content_file(path: impl AsRef<std::path::Path>) -> anyhow::Result<PinnedContentFile> {
298 let path = path.as_ref();
299 let (source, identity) = content::open_pinned_file(path)?;
300 Ok(PinnedContentFile {
301 source,
302 identity,
303 display_path: path.to_path_buf(),
304 })
305}
306
307/// Pin generated artifact metadata in an inode on the content-CAS filesystem.
308///
309/// The returned descriptor has no durable source pathname. Keeping the open
310/// file description alive is sufficient for strict FICLONE publication and
311/// avoids making `/tmp` filesystem placement part of artifact-cache behavior.
312pub(crate) fn pin_generated_artifact_bytes(
313 bytes: &[u8],
314 mode: u32,
315) -> anyhow::Result<PinnedContentFile> {
316 let (source, identity) = content::open_pinned_generated_artifact(bytes, mode)?;
317 Ok(PinnedContentFile {
318 source,
319 identity,
320 display_path: std::path::PathBuf::from("<generated artifact metadata>"),
321 })
322}
323
324/// Publish an already-pinned file revision into the shared content CAS.
325///
326/// Publication is uniformly FICLONE-only so every snapshot preserves shared
327/// backing extents and private/COW behavior across processes.
328pub fn snapshot_pinned_content_file(
329 pinned: PinnedContentFile,
330) -> anyhow::Result<ContentFileSnapshot> {
331 let (source, identity, _) = pinned.into_parts();
332 let content_hash = content::cached_file_digest(&source, identity)?;
333 let lease = content::open_or_publish_content_object_lease(content_hash, &source, identity)?;
334 Ok(ContentFileSnapshot {
335 _source: source,
336 lease,
337 content_hash,
338 len: identity.size,
339 })
340}
341
342/// Publish an artifact-tree input with a strict FICLONE requirement.
343///
344/// Artifact closures deliberately have no byte-copy fallback: both CAS
345/// publication and private materialization must preserve cross-process COW.
346pub(crate) fn snapshot_pinned_artifact_file(
347 pinned: PinnedContentFile,
348) -> anyhow::Result<ContentFileSnapshot> {
349 snapshot_pinned_content_file(pinned)
350}
351
352impl ContentFileSnapshot {
353 /// Return the canonical pathname of the leased immutable object.
354 pub fn path(&self) -> &std::path::Path {
355 self.lease.path()
356 }
357
358 /// Stable fast content key used by reconstructible cache manifests.
359 #[doc(hidden)]
360 pub fn content_hash(&self) -> u64 {
361 self.content_hash
362 }
363
364 /// Exact byte length validated by the content-object lease.
365 #[doc(hidden)]
366 pub fn len(&self) -> u64 {
367 self.len
368 }
369
370 /// Whether the immutable object is empty.
371 #[doc(hidden)]
372 pub fn is_empty(&self) -> bool {
373 self.len == 0
374 }
375}
376
377/// Pin one regular-file revision and publish it into the shared content CAS.
378///
379/// Opening uses the same nonblocking regular-file guard as scheduler
380/// snapshots, so FIFOs and device nodes are rejected without waiting. The
381/// digest, publication, and returned lease all validate the single pinned
382/// revision.
383pub fn snapshot_content_file(
384 path: impl AsRef<std::path::Path>,
385) -> anyhow::Result<ContentFileSnapshot> {
386 snapshot_pinned_content_file(pin_content_file(path)?)
387}
388// Durable-publish primitives shared by both cache layers
389// (cache_dir::CacheDir::store and vmm/disk_template::store_atomic) so
390// the two stay consistent — see fsync_staging_dir's contract.
391pub(crate) use housekeeping::{fsync_parent, fsync_staging_dir};
392// Re-exported so the `[`crate::cache::strip_vmlinux_debug`]`
393// intra-doc links in probe/btf.rs, monitor/mod.rs, and
394// monitor/symbols.rs resolve under cargo doc. No
395// `crate::cache::strip_vmlinux_debug` code call sites today;
396// intra-cache callers (cache_dir.rs, tests) reach the function
397// via `super::vmlinux_strip::strip_vmlinux_debug`.
398#[allow(unused_imports)]
399pub(crate) use vmlinux_strip::strip_vmlinux_debug;
400
401/// Filename prefix that marks an in-progress atomic-store directory
402/// under the cache root. Format: `{TMP_DIR_PREFIX}{cache_key}-{pid}`.
403/// Centralized here so the three roles that reference it — emitter
404/// ([`cache_dir::CacheDir::store`]), scanner
405/// ([`housekeeping::clean_orphaned_tmp_dirs`]), and validator
406/// ([`housekeeping::validate_cache_key`]) — cannot drift.
407/// [`cache_dir::CacheDir::list`] does not reference the const; it
408/// skips these directories via its broader leading-`.` filter.
409pub(crate) const TMP_DIR_PREFIX: &str = ".tmp-";
410
411#[cfg(test)]
412pub(crate) mod shared_test_helpers;
413
414#[cfg(test)]
415mod coordination_tests {
416 use super::*;
417 use crate::test_support::test_helpers::{EnvVarGuard, lock_env};
418
419 #[test]
420 fn cargo_output_lock_root_is_independent_of_artifact_cache_root() {
421 let _env = lock_env();
422 let lock_dir = tempfile::tempdir().expect("lock directory");
423 let first_cache = tempfile::tempdir().expect("first cache directory");
424 let second_cache = tempfile::tempdir().expect("second cache directory");
425 let _lock_dir = EnvVarGuard::set(crate::KTSTR_LOCK_DIR_ENV, lock_dir.path());
426
427 let first = {
428 let _cache = EnvVarGuard::set(crate::KTSTR_CACHE_DIR_ENV, first_cache.path());
429 cargo_build_output_lock_root().expect("first output lock root")
430 };
431 let second = {
432 let _cache = EnvVarGuard::set(crate::KTSTR_CACHE_DIR_ENV, second_cache.path());
433 cargo_build_output_lock_root().expect("second output lock root")
434 };
435
436 assert_eq!(first, second);
437 assert_eq!(first, lock_dir.path().join("ktstr-cargo-build-output-v3"));
438 }
439}