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}