ktstr/distro/
gke.rs

1//! Official Google Kubernetes Engine COS kernel acquisition.
2//!
3//! GKE publishes its node-image revisions in the official GKE release
4//! notes. Each promoted `cos-MILESTONE-BUILD-PATCH-REVISION` maps to an
5//! official `cos-tools` board directory containing a bootable `vmlinux`,
6//! prepared kernel headers, and the exact kernel source archive.
7//!
8//! The GKE kernel deliberately builds a few drivers ktstr needs as
9//! modules or leaves them disabled. ktstr keeps the Google-published
10//! kernel byte-for-byte and builds only those missing external modules
11//! against the matching Google headers/source:
12//!
13//! - `virtio_mmio` (with command-line MMIO-device registration enabled)
14//! - `virtio_console`
15//! - `virtio_blk`
16//! - `raid6_pq`
17//! - `btrfs`
18//!
19//! The resulting cache entry uses the same atomic cache install and
20//! ordered initramfs module loading as other prebuilt distro kernels.
21
22use std::fs;
23use std::path::{Path, PathBuf};
24use std::process::{Command, Stdio};
25
26use anyhow::{Context, Result, anyhow, bail, ensure};
27use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64_STANDARD};
28use regex::Regex;
29use serde::{Deserialize, Serialize};
30use sha2::{Digest as _, Sha256};
31
32use crate::cache::KernelSource;
33use crate::distro::acquire::{install_extracted, scratch_dir};
34use crate::distro::extract::{ExtractedKernel, extract_tar, extract_tar_matching};
35
36const GKE_RELEASE_NOTES_URL: &str =
37    "https://docs.cloud.google.com/kubernetes-engine/docs/release-notes";
38const COS_TOOLS_BUCKET: &str = "cos-tools";
39const GKE_RESOLUTION_CACHE_VERSION: &str = "v1";
40const GKE_ARTIFACT_BASENAMES: [&str; 3] = ["vmlinux", "kernel-headers.tgz", "kernel-src.tar.gz"];
41
42const MODULE_MAKEFILE: &str = "\
43ccflags-y += -DCONFIG_VIRTIO_MMIO_CMDLINE_DEVICES
44
45obj-m += drivers/char/virtio_console.o
46obj-m += drivers/virtio/virtio_mmio.o
47obj-m += drivers/block/virtio_blk.o
48obj-m += lib/raid6/
49obj-m += fs/btrfs/
50";
51
52const SOURCE_FILES: &[&str] = &[
53    "drivers/char/virtio_console.c",
54    "drivers/virtio/virtio_mmio.c",
55    "drivers/block/virtio_blk.c",
56    "drivers/tty/hvc/hvc_console.h",
57];
58
59const SOURCE_DIRS: &[&str] = &["lib/raid6", "fs/btrfs"];
60
61const MODULE_OUTPUTS: &[(&str, &str)] = &[
62    ("CONFIG_VIRTIO_MMIO", "drivers/virtio/virtio_mmio.ko"),
63    ("CONFIG_VIRTIO_CONSOLE", "drivers/char/virtio_console.ko"),
64    ("CONFIG_VIRTIO_BLK", "drivers/block/virtio_blk.ko"),
65    ("CONFIG_RAID6_PQ", "lib/raid6/raid6_pq.ko"),
66    ("CONFIG_BTRFS_FS", "fs/btrfs/btrfs.ko"),
67];
68
69/// Capabilities supplied by the Google kernel itself. A future COS
70/// config that drops one fails acquisition explicitly rather than
71/// silently caching a reduced-capability kernel.
72const REQUIRED_BUILTINS: &[&str] = &[
73    "CONFIG_MODULES",
74    "CONFIG_VIRTIO",
75    "CONFIG_VIRTIO_PCI",
76    "CONFIG_VIRTIO_NET",
77    "CONFIG_XOR_BLOCKS",
78    "CONFIG_SCHED_CLASS_EXT",
79    "CONFIG_BPF_SYSCALL",
80    "CONFIG_BPF_JIT",
81    "CONFIG_DEBUG_INFO_BTF",
82    "CONFIG_KALLSYMS_ALL",
83    "CONFIG_IKCONFIG",
84    "CONFIG_IKCONFIG_PROC",
85    "CONFIG_SERIAL_8250_CONSOLE",
86];
87
88#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
89struct GkeImage {
90    milestone: u32,
91    build: u32,
92    patch: u32,
93    revision: u32,
94}
95
96impl GkeImage {
97    fn image_name(self) -> String {
98        format!(
99            "cos-{}-{}-{}-{}",
100            self.milestone, self.build, self.patch, self.revision
101        )
102    }
103
104    fn tools_version(self) -> String {
105        format!("{}.{}.{}", self.build, self.patch, self.revision)
106    }
107
108    fn board_prefix(self) -> String {
109        format!("{}/gke-amd64-gcp", self.tools_version())
110    }
111}
112
113#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
114struct GkeArtifact {
115    name: String,
116    generation: String,
117    size: u64,
118    md5_base64: String,
119    download_url: String,
120}
121
122/// One indivisible, validated GKE metadata lookup result.
123///
124/// Persisting the image and all three generation-pinned objects
125/// together prevents a fallback from combining an older promoted image
126/// with any freshly resolved artifact identity (or vice versa).
127#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
128struct GkeResolution {
129    image: GkeImage,
130    artifacts: [GkeArtifact; 3],
131}
132
133#[derive(Debug, Deserialize)]
134#[serde(rename_all = "camelCase")]
135struct GcsObjectMetadata {
136    name: String,
137    generation: String,
138    size: String,
139    md5_hash: String,
140}
141
142fn parse_release_notes(notes: &str, milestone: Option<u32>) -> Result<GkeImage> {
143    // The delimiter clauses reject derivative names such as
144    // `cos-beta-*` and `cos-...-beta`; only complete promoted COS image
145    // identifiers participate.
146    let re = Regex::new(r"(?:^|[^A-Za-z0-9_-])cos-(\d{2,3})-(\d+)-(\d+)-(\d+)(?:[^A-Za-z0-9_-]|$)")
147        .expect("static GKE image regex");
148    let mut images = Vec::new();
149    for caps in re.captures_iter(notes) {
150        let image = GkeImage {
151            milestone: caps[1].parse()?,
152            build: caps[2].parse()?,
153            patch: caps[3].parse()?,
154            revision: caps[4].parse()?,
155        };
156        if milestone.is_none_or(|wanted| wanted == image.milestone) {
157            images.push(image);
158        }
159    }
160    images.into_iter().max().ok_or_else(|| {
161        if let Some(milestone) = milestone {
162            anyhow!("official GKE release notes contain no promoted cos-{milestone} node image")
163        } else {
164            anyhow!("official GKE release notes contain no promoted COS node image")
165        }
166    })
167}
168
169fn parse_milestone_selector(milestone: Option<&str>) -> Result<Option<u32>> {
170    milestone
171        .map(|value| {
172            value
173                .parse::<u32>()
174                .with_context(|| format!("parse GKE COS milestone {value:?}"))
175        })
176        .transpose()
177}
178
179fn resolve_promoted_image(milestone: Option<u32>) -> Result<GkeImage> {
180    let bytes =
181        crate::fetch::fetch_metadata_bytes(GKE_RELEASE_NOTES_URL, "fetch GKE release notes")
182            .with_context(|| "download official GKE release notes")?;
183    let notes = String::from_utf8(bytes).context("GKE release notes were not UTF-8")?;
184    parse_release_notes(&notes, milestone)
185}
186
187fn encode_gcs_object_name(name: &str) -> String {
188    let mut encoded = String::with_capacity(name.len() + 16);
189    const HEX: &[u8; 16] = b"0123456789ABCDEF";
190    for byte in name.bytes() {
191        if byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.' | b'~') {
192            encoded.push(char::from(byte));
193        } else {
194            encoded.push('%');
195            encoded.push(char::from(HEX[(byte >> 4) as usize]));
196            encoded.push(char::from(HEX[(byte & 0xf) as usize]));
197        }
198    }
199    encoded
200}
201
202fn gcs_download_url(object_name: &str, generation: &str) -> String {
203    let encoded = encode_gcs_object_name(object_name);
204    format!(
205        "https://storage.googleapis.com/download/storage/v1/b/{COS_TOOLS_BUCKET}/o/{encoded}?generation={generation}&alt=media"
206    )
207}
208
209fn parse_gcs_metadata(bytes: &[u8], expected_name: &str) -> Result<GkeArtifact> {
210    let metadata: GcsObjectMetadata =
211        serde_json::from_slice(bytes).context("parse GCS object metadata")?;
212    ensure!(
213        metadata.name == expected_name,
214        "GCS metadata object mismatch: requested {expected_name:?}, got {:?}",
215        metadata.name
216    );
217    let size = metadata
218        .size
219        .parse::<u64>()
220        .context("parse GCS object size")?;
221    ensure!(size > 0, "GCS object {expected_name} is empty");
222    ensure!(
223        !metadata.generation.is_empty() && metadata.generation.bytes().all(|b| b.is_ascii_digit()),
224        "GCS object {expected_name} has invalid generation {:?}",
225        metadata.generation
226    );
227    let md5 = BASE64_STANDARD
228        .decode(&metadata.md5_hash)
229        .with_context(|| format!("decode GCS md5Hash for {expected_name}"))?;
230    ensure!(
231        md5.len() == 16,
232        "GCS object {expected_name} md5Hash decoded to {} bytes, expected 16",
233        md5.len()
234    );
235    let download_url = gcs_download_url(expected_name, &metadata.generation);
236    Ok(GkeArtifact {
237        name: metadata.name,
238        generation: metadata.generation,
239        size,
240        md5_base64: metadata.md5_hash,
241        download_url,
242    })
243}
244
245fn resolve_artifact(object_name: &str) -> Result<GkeArtifact> {
246    let encoded = encode_gcs_object_name(object_name);
247    let metadata_url =
248        format!("https://storage.googleapis.com/storage/v1/b/{COS_TOOLS_BUCKET}/o/{encoded}");
249    let bytes = crate::fetch::fetch_metadata_bytes(&metadata_url, "fetch COS artifact metadata")
250        .with_context(|| format!("download metadata for {object_name}"))?;
251    parse_gcs_metadata(&bytes, object_name)
252}
253
254fn artifact_object_names(image: GkeImage) -> [String; 3] {
255    let prefix = image.board_prefix();
256    GKE_ARTIFACT_BASENAMES.map(|basename| format!("{prefix}/{basename}"))
257}
258
259fn resolve_artifacts(image: GkeImage) -> Result<[GkeArtifact; 3]> {
260    let [vmlinux, headers, source] = artifact_object_names(image);
261    Ok([
262        resolve_artifact(&vmlinux)?,
263        resolve_artifact(&headers)?,
264        resolve_artifact(&source)?,
265    ])
266}
267
268fn resolution_lookup_key(milestone: Option<u32>) -> String {
269    let selector = milestone
270        .map(|value| format!("milestone-{value}"))
271        .unwrap_or_else(|| "latest".to_string());
272    format!("gke-resolution/{GKE_RESOLUTION_CACHE_VERSION}/{selector}/x86_64")
273}
274
275fn validate_resolution(resolution: &GkeResolution, requested_milestone: Option<u32>) -> Result<()> {
276    let image = resolution.image;
277    ensure!(
278        (10..=999).contains(&image.milestone),
279        "cached GKE image has invalid COS milestone {}",
280        image.milestone
281    );
282    if let Some(requested) = requested_milestone {
283        ensure!(
284            image.milestone == requested,
285            "cached GKE image {} does not match requested COS milestone {requested}",
286            image.image_name()
287        );
288    }
289
290    for (artifact, expected_name) in resolution
291        .artifacts
292        .iter()
293        .zip(artifact_object_names(image))
294    {
295        ensure!(
296            artifact.name == expected_name,
297            "cached GKE artifact order/name mismatch: expected {expected_name:?}, got {:?}",
298            artifact.name
299        );
300        ensure!(
301            !artifact.generation.is_empty()
302                && artifact
303                    .generation
304                    .bytes()
305                    .all(|byte| byte.is_ascii_digit()),
306            "cached GKE artifact {expected_name} has invalid generation {:?}",
307            artifact.generation
308        );
309        ensure!(
310            artifact.size > 0,
311            "cached GKE artifact {expected_name} is empty"
312        );
313        let md5 = BASE64_STANDARD
314            .decode(&artifact.md5_base64)
315            .with_context(|| format!("decode cached GCS md5Hash for {expected_name}"))?;
316        ensure!(
317            md5.len() == 16,
318            "cached GKE artifact {expected_name} md5Hash decoded to {} bytes, expected 16",
319            md5.len()
320        );
321        let expected_url = gcs_download_url(&expected_name, &artifact.generation);
322        ensure!(
323            artifact.download_url == expected_url,
324            "cached GKE artifact {expected_name} download URL is not its exact HTTPS \
325             generation-pinned GCS URL"
326        );
327    }
328    Ok(())
329}
330
331fn cache_key(image: GkeImage, artifacts: &[GkeArtifact]) -> String {
332    // The boot ELF, headers, and source form one indivisible input set.
333    // Key all three object identities so a Google-side replacement of
334    // headers/source under the same board version cannot reuse modules
335    // built from an older generation.
336    let mut hasher = Sha256::new();
337    for artifact in artifacts {
338        hasher.update(artifact.name.as_bytes());
339        hasher.update([0]);
340        hasher.update(artifact.generation.as_bytes());
341        hasher.update([0]);
342        hasher.update(artifact.size.to_le_bytes());
343        hasher.update([0]);
344        hasher.update(artifact.md5_base64.as_bytes());
345        hasher.update([0xff]);
346    }
347    let digest = hex::encode(hasher.finalize());
348    format!(
349        "distro-gke{}-{}-x86_64-artifacts{}",
350        image.milestone,
351        image.tools_version(),
352        &digest[..12],
353    )
354}
355
356fn source_path_selected(path: &Path) -> bool {
357    SOURCE_FILES.iter().any(|file| path == Path::new(file))
358        || SOURCE_DIRS.iter().any(|dir| {
359            let dir = Path::new(dir);
360            path == dir || path.starts_with(dir)
361        })
362}
363
364fn find_header_tree(root: &Path) -> Result<(PathBuf, String)> {
365    let usr_src = root.join("usr/src");
366    let mut candidates = fs::read_dir(&usr_src)
367        .with_context(|| format!("read {}", usr_src.display()))?
368        .flatten()
369        .filter(|entry| entry.file_type().map(|ty| ty.is_dir()).unwrap_or(false))
370        .filter_map(|entry| {
371            let name = entry.file_name().to_string_lossy().into_owned();
372            name.strip_prefix("linux-headers-")
373                .map(|release| (entry.path(), release.to_string()))
374        })
375        .collect::<Vec<_>>();
376    candidates.sort_by(|a, b| a.0.cmp(&b.0));
377    ensure!(
378        candidates.len() == 1,
379        "expected exactly one linux-headers-* tree in {}, found {}",
380        usr_src.display(),
381        candidates.len()
382    );
383    Ok(candidates.remove(0))
384}
385
386fn config_value<'a>(config: &'a str, option: &str) -> Option<&'a str> {
387    config.lines().find_map(|line| {
388        let (key, value) = line.split_once('=')?;
389        (key == option).then_some(value)
390    })
391}
392
393fn validate_gke_config(config: &str, release: &str) -> Result<()> {
394    let missing = REQUIRED_BUILTINS
395        .iter()
396        .copied()
397        .filter(|option| config_value(config, option) != Some("y"))
398        .collect::<Vec<_>>();
399    ensure!(
400        missing.is_empty(),
401        "official GKE kernel {release} dropped ktstr-required built-in capabilities {missing:?}; \
402         refusing a reduced-capability fallback"
403    );
404    ensure!(
405        config_value(config, "CONFIG_MODVERSIONS").is_none(),
406        "official GKE kernel {release} enables CONFIG_MODVERSIONS; exact external-module symbol \
407         version support is not implemented"
408    );
409    ensure!(
410        config_value(config, "CONFIG_MODULE_SIG_FORCE").is_none(),
411        "official GKE kernel {release} enforces signed modules; ktstr cannot load its exact-source \
412         transport modules without Google's private signing key"
413    );
414    Ok(())
415}
416
417fn command_available(command: &str) -> bool {
418    Command::new(command)
419        .arg("--version")
420        .stdin(Stdio::null())
421        .stdout(Stdio::null())
422        .stderr(Stdio::null())
423        .status()
424        .is_ok_and(|status| status.success())
425}
426
427fn module_make_args(source_dir: &Path, jobs: usize, lld_available: bool) -> Vec<String> {
428    let mut args = vec![format!("M={}", source_dir.display()), "LLVM=1".to_string()];
429    // LLVM=1 selects Clang plus the LLVM binutils. Some distributions
430    // package Clang without LLD; Linux Kbuild explicitly supports mixing
431    // Clang with GNU ld via LD=ld. External modules retain the exact same
432    // Google headers, source, config, compiler mode, and module ABI.
433    if !lld_available {
434        args.push("LD=ld".to_string());
435    }
436    args.extend([format!("-j{jobs}"), "modules".to_string()]);
437    args
438}
439
440fn build_modules(
441    headers: &Path,
442    source_dir: &Path,
443    config: &str,
444    cli_label: &str,
445    mp: Option<&crate::cli::FetchProgress>,
446) -> Result<Vec<PathBuf>> {
447    fs::write(source_dir.join("Makefile"), MODULE_MAKEFILE)
448        .with_context(|| format!("write {}", source_dir.join("Makefile").display()))?;
449    let jobs = std::thread::available_parallelism()
450        .map(|value| value.get())
451        .unwrap_or(1);
452    let lld_available = command_available("ld.lld");
453    if !lld_available {
454        let status = format!("{cli_label}: ld.lld not found; linking GKE modules with GNU ld");
455        match mp {
456            Some(progress) => progress.println(&status),
457            None => eprintln!("{status}"),
458        }
459    }
460    let args = module_make_args(source_dir, jobs, lld_available);
461    let arg_refs = args.iter().map(String::as_str).collect::<Vec<_>>();
462    let bar = mp.map(|progress| progress.step_bar(&format!("{cli_label}: building GKE modules")));
463    let result = crate::cli::run_make_with_output(headers, &arg_refs, mp)
464        .with_context(|| "build external modules against official GKE headers");
465    if let Some(bar) = &bar {
466        bar.finish();
467    }
468    result?;
469
470    let mut modules = Vec::new();
471    for (config_option, relative) in MODULE_OUTPUTS {
472        let module = source_dir.join(relative);
473        ensure!(
474            module.is_file(),
475            "GKE external-module build did not produce {}",
476            module.display()
477        );
478        // Do not load a duplicate if a later GKE kernel builds the
479        // driver in. We still build the complete known set in one
480        // invocation so source/header drift is detected up front.
481        if config_value(config, config_option) != Some("y") {
482            modules.push(module);
483        }
484    }
485    Ok(modules)
486}
487
488fn artifact_provenance(artifact: &GkeArtifact) -> String {
489    format!(
490        "gs://{COS_TOOLS_BUCKET}/{}#generation={}#size={}",
491        artifact.name, artifact.generation, artifact.size
492    )
493}
494
495/// Acquire the latest GKE-promoted COS kernel, optionally pinned to a
496/// COS milestone (`gke-129`), and return its local cache entry.
497pub(crate) fn acquire_gke_kernel(
498    milestone: Option<&str>,
499    cli_label: &str,
500    mp: Option<&crate::cli::FetchProgress>,
501) -> Result<PathBuf> {
502    let (arch, _) = crate::fetch::arch_info();
503    if arch != "x86_64" {
504        bail!(
505            "--kernel gke currently supports x86_64 only: the official artifact mapping uses \
506             Google's gke-amd64-gcp COS board, not a substituted generic kernel"
507        );
508    }
509
510    let requested_milestone = parse_milestone_selector(milestone)?;
511    let resolution_key = resolution_lookup_key(requested_milestone);
512    let resolution = crate::lookup_cache::last_known_good(
513        &resolution_key,
514        || {
515            let image = resolve_promoted_image(requested_milestone)?;
516            let artifacts = resolve_artifacts(image)?;
517            Ok(GkeResolution { image, artifacts })
518        },
519        |resolution| validate_resolution(resolution, requested_milestone),
520    )
521    .with_context(|| {
522        let selector = requested_milestone
523            .map(|value| format!("COS milestone {value}"))
524            .unwrap_or_else(|| "latest promoted COS image".to_string());
525        format!("resolve official GKE metadata for {selector}")
526    })?;
527    let GkeResolution { image, artifacts } = resolution;
528    let source = &artifacts[2];
529    let key = cache_key(image, &artifacts);
530    let cache = crate::cache::CacheDir::new()?;
531    if let Some(entry) = cache.lookup(&key) {
532        tracing::info!(cache_key = %key, image = %image.image_name(), "GKE kernel cache hit");
533        return Ok(entry.path);
534    }
535
536    let status = format!(
537        "{cli_label}: resolving official GKE image {} (Google kernel + exact-source modules)",
538        image.image_name()
539    );
540    match mp {
541        Some(progress) => progress.println(&status),
542        None => eprintln!("{status}"),
543    }
544
545    let scratch = scratch_dir()?;
546    let downloads = scratch.path().join("artifacts");
547    fs::create_dir_all(&downloads)?;
548    let destinations = [
549        downloads.join("vmlinux"),
550        downloads.join("kernel-headers.tgz"),
551        downloads.join("kernel-src.tar.gz"),
552    ];
553    for (artifact, destination) in artifacts.iter().zip(destinations.iter()) {
554        let label = artifact.name.rsplit('/').next().unwrap_or(&artifact.name);
555        crate::fetch::download_verified_md5_file(
556            &artifact.download_url,
557            destination,
558            &artifact.md5_base64,
559            label,
560            cli_label,
561            mp,
562        )
563        .with_context(|| format!("download official GKE artifact {}", artifact.name))?;
564    }
565
566    let header_root = scratch.path().join("headers");
567    fs::create_dir_all(&header_root)?;
568    let header_file =
569        fs::File::open(&destinations[1]).context("open downloaded GKE kernel headers")?;
570    extract_tar(flate2::read::GzDecoder::new(header_file), &header_root)
571        .context("extract official GKE kernel headers")?;
572    let (header_tree, kernel_release) = find_header_tree(&header_root)?;
573    let config_path = header_tree.join(".config");
574    let config = fs::read_to_string(&config_path)
575        .with_context(|| format!("read GKE kernel config {}", config_path.display()))?;
576    validate_gke_config(&config, &kernel_release)?;
577
578    let module_source = scratch.path().join("module-source");
579    fs::create_dir_all(&module_source)?;
580    let source_file =
581        fs::File::open(&destinations[2]).context("open downloaded GKE kernel source")?;
582    extract_tar_matching(
583        flate2::read::GzDecoder::new(source_file),
584        &module_source,
585        source_path_selected,
586    )
587    .context("extract GKE external-module source subset")?;
588    for required in SOURCE_FILES {
589        ensure!(
590            module_source.join(required).is_file(),
591            "official GKE source archive omitted required module source {required}"
592        );
593    }
594    for required in SOURCE_DIRS {
595        ensure!(
596            module_source.join(required).is_dir(),
597            "official GKE source archive omitted required module directory {required}"
598        );
599    }
600
601    let modules = build_modules(&header_tree, &module_source, &config, cli_label, mp)?;
602    let extracted = ExtractedKernel {
603        kernel_release: kernel_release.clone(),
604        image: destinations[0].clone(),
605        config: Some(config_path),
606        system_map: None,
607        modules_dir: None,
608        // Google's published vmlinux is both the bootable image and
609        // the exact debuginfo-bearing ELF.
610        vmlinux: Some(destinations[0].clone()),
611    };
612    let mut provenance = vec![image.image_name()];
613    provenance.extend(artifacts.iter().map(artifact_provenance));
614    provenance.push(format!(
615        "external-modules-built-from={}",
616        artifact_provenance(source)
617    ));
618    install_extracted(
619        &key,
620        &extracted,
621        &modules,
622        KernelSource::DistroPackage {
623            distro: format!("gke{}", image.milestone),
624            packages: provenance,
625        },
626    )
627}
628
629#[cfg(test)]
630mod tests {
631    use super::*;
632
633    fn resolution_fixture() -> GkeResolution {
634        let image = GkeImage {
635            milestone: 129,
636            build: 19506,
637            patch: 224,
638            revision: 80,
639        };
640        let prefix = image.board_prefix();
641        let artifact = |basename: &str, generation: &str, size| {
642            let name = format!("{prefix}/{basename}");
643            GkeArtifact {
644                download_url: gcs_download_url(&name, generation),
645                name,
646                generation: generation.to_string(),
647                size,
648                md5_base64: "EFRgfQGcG6lmUe4w6b9y1A==".to_string(),
649            }
650        };
651        GkeResolution {
652            image,
653            artifacts: [
654                artifact("vmlinux", "1782777210762594", 378_632_832),
655                artifact("kernel-headers.tgz", "1782777210762595", 24_000_000),
656                artifact("kernel-src.tar.gz", "1782777210762596", 220_000_000),
657            ],
658        }
659    }
660
661    #[test]
662    fn release_notes_choose_latest_promoted_image() {
663        let notes = r#"
664            <li>COS_CONTAINERD: cos-128-19000-1-9</li>
665            <li>COS_CONTAINERD: cos-beta-999-99999-9-9</li>
666            <li>COS_CONTAINERD: cos-129-19506-224-80</li>
667            <li>not promoted: cos-130-20000-1-1-beta</li>
668            <li>COS_CONTAINERD: cos-129-19506-224-79</li>
669        "#;
670        assert_eq!(
671            parse_release_notes(notes, None).unwrap(),
672            GkeImage {
673                milestone: 129,
674                build: 19506,
675                patch: 224,
676                revision: 80,
677            }
678        );
679    }
680
681    #[test]
682    fn release_notes_milestone_pin_stays_within_milestone() {
683        let notes = " cos-128-19000-2-1  cos-129-19506-224-80  cos-128-19001-1-3 ";
684        assert_eq!(
685            parse_release_notes(notes, Some(128)).unwrap(),
686            GkeImage {
687                milestone: 128,
688                build: 19001,
689                patch: 1,
690                revision: 3,
691            }
692        );
693        assert!(parse_release_notes(notes, Some(127)).is_err());
694    }
695
696    #[test]
697    fn gcs_metadata_is_exact_generation_pinned_and_md5_checked() {
698        let name = "19506.224.80/gke-amd64-gcp/vmlinux";
699        let json = format!(
700            r#"{{"name":"{name}","generation":"1782777210762594","size":"378632832","md5Hash":"EFRgfQGcG6lmUe4w6b9y1A=="}}"#
701        );
702        let artifact = parse_gcs_metadata(json.as_bytes(), name).unwrap();
703        assert_eq!(artifact.size, 378_632_832);
704        assert!(
705            artifact
706                .download_url
707                .contains("generation=1782777210762594")
708        );
709        assert!(
710            artifact
711                .download_url
712                .contains("19506.224.80%2Fgke-amd64-gcp%2Fvmlinux")
713        );
714
715        let bad = json.replace("EFRgfQGcG6lmUe4w6b9y1A==", "AA==");
716        assert!(parse_gcs_metadata(bad.as_bytes(), name).is_err());
717        assert!(parse_gcs_metadata(json.as_bytes(), "other/object").is_err());
718    }
719
720    #[test]
721    fn resolution_lookup_key_separates_channel_and_architecture() {
722        assert_eq!(
723            resolution_lookup_key(None),
724            "gke-resolution/v1/latest/x86_64"
725        );
726        assert_eq!(
727            resolution_lookup_key(Some(129)),
728            "gke-resolution/v1/milestone-129/x86_64"
729        );
730        assert_ne!(
731            resolution_lookup_key(None),
732            resolution_lookup_key(Some(129))
733        );
734        assert_ne!(
735            resolution_lookup_key(Some(128)),
736            resolution_lookup_key(Some(129))
737        );
738        assert_eq!(
739            resolution_lookup_key(parse_milestone_selector(Some("0129")).unwrap()),
740            resolution_lookup_key(Some(129)),
741            "equivalent numeric selectors must share one stable lookup key"
742        );
743        assert!(parse_milestone_selector(Some("latest")).is_err());
744    }
745
746    #[test]
747    fn resolution_validator_pins_the_complete_generation_plan() {
748        let baseline = resolution_fixture();
749        validate_resolution(&baseline, None).unwrap();
750        validate_resolution(&baseline, Some(129)).unwrap();
751        assert!(validate_resolution(&baseline, Some(128)).is_err());
752
753        let mut invalid_milestone = baseline.clone();
754        invalid_milestone.image.milestone = 9;
755        assert!(validate_resolution(&invalid_milestone, None).is_err());
756
757        let image_mutations: [fn(&mut GkeImage); 3] = [
758            |image: &mut GkeImage| image.build += 1,
759            |image: &mut GkeImage| image.patch += 1,
760            |image: &mut GkeImage| image.revision += 1,
761        ];
762        for mutate in image_mutations {
763            let mut changed = baseline.clone();
764            mutate(&mut changed.image);
765            assert!(
766                validate_resolution(&changed, None).is_err(),
767                "every image version field must agree with the artifact plan"
768            );
769        }
770
771        let mut wrong_name = baseline.clone();
772        wrong_name.artifacts[0].name.push_str(".old");
773        assert!(validate_resolution(&wrong_name, None).is_err());
774
775        let mut wrong_order = baseline.clone();
776        wrong_order.artifacts.swap(0, 1);
777        assert!(validate_resolution(&wrong_order, None).is_err());
778
779        for generation in ["", "not-numeric"] {
780            let mut bad_generation = baseline.clone();
781            bad_generation.artifacts[0].generation = generation.to_string();
782            assert!(validate_resolution(&bad_generation, None).is_err());
783        }
784
785        let mut empty = baseline.clone();
786        empty.artifacts[0].size = 0;
787        assert!(validate_resolution(&empty, None).is_err());
788
789        for md5 in ["not-base64", "AA=="] {
790            let mut bad_md5 = baseline.clone();
791            bad_md5.artifacts[0].md5_base64 = md5.to_string();
792            assert!(validate_resolution(&bad_md5, None).is_err());
793        }
794
795        let mut non_https = baseline.clone();
796        non_https.artifacts[0].download_url = non_https.artifacts[0]
797            .download_url
798            .replacen("https:", "http:", 1);
799        assert!(validate_resolution(&non_https, None).is_err());
800
801        let mut mismatched_generation = baseline;
802        mismatched_generation.artifacts[0].generation = "1782777210762597".to_string();
803        assert!(validate_resolution(&mismatched_generation, None).is_err());
804    }
805
806    #[test]
807    fn cache_key_covers_every_artifact_generation() {
808        let image = GkeImage {
809            milestone: 129,
810            build: 19506,
811            patch: 224,
812            revision: 80,
813        };
814        let artifact = |name: &str, generation: &str| GkeArtifact {
815            name: name.to_string(),
816            generation: generation.to_string(),
817            size: 123,
818            md5_base64: "EFRgfQGcG6lmUe4w6b9y1A==".to_string(),
819            download_url: String::new(),
820        };
821        let artifacts = vec![
822            artifact("board/vmlinux", "1"),
823            artifact("board/kernel-headers.tgz", "2"),
824            artifact("board/kernel-src.tar.gz", "3"),
825        ];
826        let baseline = cache_key(image, &artifacts);
827        for index in 0..artifacts.len() {
828            let mut changed = artifacts.clone();
829            changed[index].generation.push('9');
830            assert_ne!(
831                cache_key(image, &changed),
832                baseline,
833                "artifact {index} generation must participate in the cache key"
834            );
835        }
836    }
837
838    #[test]
839    fn source_selection_is_exact_and_does_not_match_prefix_siblings() {
840        assert!(source_path_selected(Path::new(
841            "drivers/virtio/virtio_mmio.c"
842        )));
843        assert!(source_path_selected(Path::new("fs/btrfs/inode.c")));
844        assert!(source_path_selected(Path::new("lib/raid6/algos.c")));
845        assert!(!source_path_selected(Path::new("fs/btrfsx/inode.c")));
846        assert!(!source_path_selected(Path::new(
847            "drivers/virtio/virtio_balloon.c"
848        )));
849    }
850
851    #[test]
852    fn config_gate_refuses_capability_or_module_abi_compromise() {
853        let mut config = REQUIRED_BUILTINS
854            .iter()
855            .map(|option| format!("{option}=y\n"))
856            .collect::<String>();
857        config.push_str("# CONFIG_MODVERSIONS is not set\n");
858        config.push_str("# CONFIG_MODULE_SIG_FORCE is not set\n");
859        validate_gke_config(&config, "test").unwrap();
860
861        assert!(validate_gke_config(&config.replace("CONFIG_VIRTIO_NET=y\n", ""), "test").is_err());
862        assert!(
863            validate_gke_config(&format!("{config}CONFIG_MODULE_SIG_FORCE=y\n"), "test").is_err()
864        );
865    }
866
867    #[test]
868    fn module_build_uses_gnu_ld_when_lld_is_unavailable() {
869        let with_lld = module_make_args(Path::new("/tmp/modules"), 8, true);
870        assert!(!with_lld.iter().any(|arg| arg.starts_with("LD=")));
871
872        let without_lld = module_make_args(Path::new("/tmp/modules"), 8, false);
873        assert!(without_lld.iter().any(|arg| arg == "LD=ld"));
874        assert!(without_lld.iter().any(|arg| arg == "LLVM=1"));
875    }
876
877    /// Cheap live metadata gate used by `just test-distro-resolve`.
878    /// It proves GKE release-note parsing and all three official GCS
879    /// object metadata lookups without downloading the artifact bodies.
880    #[test]
881    #[ignore = "requires network access to official Google metadata"]
882    fn live_gke_official_metadata_resolves() {
883        let image = resolve_promoted_image(None).expect("resolve latest GKE-promoted COS image");
884        let artifacts = resolve_artifacts(image).expect("resolve official cos-tools artifacts");
885        assert_eq!(artifacts.len(), 3);
886        assert!(artifacts.iter().all(|artifact| artifact.size > 0));
887        assert!(
888            artifacts
889                .iter()
890                .all(|artifact| artifact.download_url.contains("generation="))
891        );
892    }
893}