ktstr/distro/
repo.rs

1//! Repo-metadata resolution: from a distro spec to concrete kernel
2//! package URLs + sha256 checksums, pulled from each distro's official
3//! repository metadata.
4//!
5//! This module resolves metadata ONLY — it never downloads the kernel
6//! packages themselves. Extraction of the resolved packages and the
7//! download/cache integration are handled elsewhere; the seam between
8//! them is the [`ResolvedDistroKernel`] this module returns.
9//!
10//! # Endpoint choices
11//!
12//! - **Fedora** — latest stable release number from
13//!   `https://fedoraproject.org/releases.json` (official, stable JSON,
14//!   served by fedoraproject.org). It lists only shipped GA releases
15//!   with numeric `version` fields, so filtering to all-digit versions
16//!   and taking the max yields the current stable release without the
17//!   Rawhide/Branched noise a mirror directory listing would carry.
18//!   Kernel packages come from the `updates` repo (falling back to the
19//!   GA `releases/.../os` repo), debuginfo from the matching `debug`
20//!   repo. Package selection is by RPM EVR (`rpmvercmp`).
21//! - **Ubuntu** — latest LTS from
22//!   `https://changelogs.ubuntu.com/meta-release-lts` (official, plain
23//!   text, carries the codename). Kernel = the HWE stack: the
24//!   `linux-image-generic-hwe-{YY.MM}` meta package's `Depends` pins
25//!   the concrete `linux-image-{kver}-generic`, whose modules live in
26//!   `linux-modules{,-extra}-{kver}-generic`. debuginfo is the
27//!   `-dbgsym` ddeb from `ddebs.ubuntu.com`, with Launchpad's primary
28//!   archive API and file store as an independent resolution/download
29//!   provider when the DDEB archive is unavailable.
30//! - **Amazon Linux 2023** — repo base from
31//!   `https://cdn.amazonlinux.com/al2023/core/mirrors/latest/{arch}/mirror.list`.
32//!   AL2023 carries parallel kernel STREAMS as differently-named
33//!   packages — the default `kernel` (6.1) plus versioned
34//!   `kernel6.12` / `kernel6.18` — with no Fedora-style
35//!   kernel-core/modules split; each stream splits a handful of extra
36//!   drivers, `virtio_console` among them, into a
37//!   `<stream>-modules-extra` subpackage (verified against the live
38//!   filelists metadata). The resolver picks the stream with the
39//!   newest kernel by RPM EVR and pairs it with its modules-extra at
40//!   the same EVR; debuginfo (`<stream>-debuginfo`, which carries the
41//!   full vmlinux on its own) comes from the sibling `debuginfo`
42//!   mirror.
43//! - **SteamOS** — Valve's official package mirror
44//!   `https://steamdeck-packages.steamos.cloud/archlinux-mirror/`.
45//!   The kernel lives in the `jupiter-<MAJOR.MINOR>` channels (Valve's
46//!   per-release trains; verified live: `jupiter-3.7`, `jupiter-3.8`).
47//!   A bare `steamos` picks the highest version-numbered jupiter
48//!   channel — the newest release train Valve publishes — because the
49//!   mirror exposes no machine-readable stable pointer: `jupiter-rel`
50//!   is the legacy 3.0-era channel (its newest kernel is 5.13) and
51//!   `-main`/`-staging`/`-ci-test` are development churn, so the
52//!   numbered trains are the only sane axis; pin `steamos-3.7` to
53//!   hold an older train. The channel's pacman database
54//!   (`jupiter-<v>.db`, a compressed tar of per-package `desc`
55//!   files) declares name/version/sha256/filename; the kernel package
56//!   is `linux-neptune[-<series>]` (`linux-neptune-618` today) and
57//!   the newest series wins by kernel version (compared with
58//!   `rpmvercmp`, whose plain alnum-segment ordering matches pacman's
59//!   `vercmp` for these dotted versions). x86_64 only — Valve
60//!   publishes no other architecture. No debug packages exist for
61//!   linux-neptune anywhere on the mirror (the `*-debug-*` repos only
62//!   mirror Arch's own core/extra split), so SteamOS resolves with NO
63//!   debuginfo — the one distro exempt from the mandatory-vmlinux
64//!   policy; acquisition warns about what that degrades.
65//!
66//! All metadata fetches ride the shared HTTP client and transient-retry
67//! seam via `crate::fetch::fetch_metadata_bytes` /
68//! `crate::fetch::fetch_metadata_text`. Parsing/selection is factored
69//! into pure functions over `&[u8]` / `&str` so the unit tests exercise
70//! them on small fixtures without touching the network.
71
72use std::cmp::Ordering;
73use std::io::{BufReader, Cursor, Read};
74
75use anyhow::{Context, Result, anyhow, bail};
76use quick_xml::events::BytesStart;
77use quick_xml::events::Event;
78use quick_xml::reader::Reader;
79use reqwest::Url;
80use sha2::{Digest, Sha256};
81
82pub use crate::kernel_path::DistroKind;
83
84/// A single resolved package: name, version, ordered official download URLs,
85/// and the sha256 the repository metadata declares for it.
86#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
87pub struct PackageRef {
88    pub name: String,
89    pub version: String,
90    pub url: String,
91    /// Equivalent official origins, tried in order after [`Self::url`].
92    ///
93    /// Acquisition verifies every origin against the same content hash, so
94    /// this stays generic rather than embedding repository-specific fallback
95    /// policy in the downloader.
96    #[serde(default, skip_serializing_if = "Vec::is_empty")]
97    pub alternate_urls: Vec<String>,
98    pub sha256: String,
99    pub size: Option<u64>,
100}
101
102/// The resolved kernel for a distro spec: the packages that carry the
103/// kernel image + modules, plus the vmlinux-bearing debuginfo packages.
104#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
105pub struct ResolvedDistroKernel {
106    /// Short distro tag, e.g. `"fedora44"`, `"ubuntu24.04-hwe"`, `"al2023"`.
107    pub distro: String,
108    /// Package version-release, best effort (e.g. `"7.1.3-200.fc44"`).
109    pub kernel_release: String,
110    /// Distro package architecture (`x86_64`/`aarch64` for Fedora/AL,
111    /// `amd64`/`arm64` for Ubuntu).
112    pub arch: String,
113    /// Kernel image + modules packages, in download order.
114    pub packages: Vec<PackageRef>,
115    /// vmlinux-bearing debuginfo packages.
116    pub debuginfo: Vec<PackageRef>,
117}
118
119/// Resolve a distro spec to concrete kernel package URLs + checksums
120/// for the host architecture.
121///
122/// `release` pins a specific stream (`Some("44")`, `Some("24.04")`);
123/// `None` resolves the distro's latest. For Amazon Linux the release
124/// selects the AL2023 stream (always latest-dated) regardless of value.
125pub fn resolve_distro_kernel(
126    kind: DistroKind,
127    release: Option<&str>,
128) -> Result<ResolvedDistroKernel> {
129    let (arch, _) = crate::fetch::arch_info();
130    resolve_for_arch(kind, release, arch)
131}
132
133/// Architecture-injectable core of [`resolve_distro_kernel`]. `arch` is
134/// the host arch string from [`crate::fetch::arch_info`]
135/// (`x86_64`/`aarch64`); the resolvers map it to each distro's naming.
136/// Exposed to the in-module tests so they can resolve `aarch64`
137/// metadata from an `x86_64` host (metadata-only, no download).
138pub(crate) fn resolve_for_arch(
139    kind: DistroKind,
140    release: Option<&str>,
141    arch: &str,
142) -> Result<ResolvedDistroKernel> {
143    let key = distro_resolution_cache_key(kind, release, arch);
144    crate::lookup_cache::last_known_good(
145        &key,
146        || resolve_for_arch_uncached(kind, release, arch),
147        |resolved| validate_cached_resolution(kind, release, arch, resolved),
148    )
149}
150
151/// Resolve a distro directly from its repository metadata.
152///
153/// The last-known-good boundary deliberately wraps this whole dispatcher:
154/// only a fully selected package set whose complete metadata chain succeeded
155/// can be persisted, and any failure in that chain can fall back to the last
156/// validated complete result.
157fn resolve_for_arch_uncached(
158    kind: DistroKind,
159    release: Option<&str>,
160    arch: &str,
161) -> Result<ResolvedDistroKernel> {
162    match kind {
163        DistroKind::Fedora => resolve_fedora(release, arch),
164        DistroKind::Ubuntu => resolve_ubuntu(release, arch),
165        DistroKind::AmazonLinux => resolve_amazonlinux(release, arch),
166        DistroKind::SteamOs => resolve_steamos(release, arch),
167        DistroKind::Gke => {
168            bail!("GKE kernels use Google COS image metadata, not a distro package repository")
169        }
170    }
171}
172
173/// On-disk schema for complete distro-resolution records.
174///
175/// Bump this when either the serialized payload or its validation semantics
176/// change incompatibly. Kind, requested release (or the explicit `latest`
177/// marker), and host architecture are separate components so one resolver
178/// input can never supply another's stale result.
179const DISTRO_RESOLUTION_CACHE_SCHEMA: &str = "distro-resolution-v1";
180
181fn distro_kind_cache_name(kind: DistroKind) -> &'static str {
182    match kind {
183        DistroKind::Fedora => "fedora",
184        DistroKind::Ubuntu => "ubuntu",
185        DistroKind::AmazonLinux => "amazonlinux",
186        DistroKind::SteamOs => "steamos",
187        DistroKind::Gke => "gke",
188    }
189}
190
191fn distro_resolution_cache_key(kind: DistroKind, release: Option<&str>, arch: &str) -> String {
192    let release = if kind == DistroKind::AmazonLinux {
193        // Every accepted Amazon Linux spelling selects the same rolling
194        // AL2023 repository; the resolver intentionally ignores `release`.
195        // Canonicalize that equivalence here so `amazonlinux`, `al2023`, and
196        // `amazonlinux-2023` share one last-known-good result.
197        "rolling-al2023".to_string()
198    } else {
199        release
200            .map(|release| format!("release={release}"))
201            .unwrap_or_else(|| "latest".to_string())
202    };
203    format!(
204        "{DISTRO_RESOLUTION_CACHE_SCHEMA}/{}/{release}/{arch}",
205        distro_kind_cache_name(kind)
206    )
207}
208
209/// Validate a deserialized last-known-good record against the exact resolver
210/// request that selected its cache slot.
211///
212/// Treat the cache as untrusted input: besides request identity, validate all
213/// fields that acquisition later relies on before accepting stale metadata.
214fn validate_cached_resolution(
215    kind: DistroKind,
216    release: Option<&str>,
217    host_arch: &str,
218    resolved: &ResolvedDistroKernel,
219) -> Result<()> {
220    validate_cached_distro_tag(kind, release, &resolved.distro)?;
221
222    let expected_arch = match kind {
223        DistroKind::Fedora | DistroKind::AmazonLinux => match host_arch {
224            "x86_64" | "aarch64" => host_arch,
225            other => bail!("unsupported cached distro host architecture {other}"),
226        },
227        DistroKind::Ubuntu => ubuntu_arch(host_arch)?,
228        DistroKind::SteamOs => {
229            if host_arch != "x86_64" {
230                bail!("SteamOS cached resolution requires x86_64, got {host_arch}");
231            }
232            "x86_64"
233        }
234        DistroKind::Gke => {
235            bail!("GKE does not use distro package-repository resolution")
236        }
237    };
238    if resolved.arch != expected_arch {
239        bail!(
240            "cached {} architecture is {:?}, expected {expected_arch:?}",
241            distro_kind_cache_name(kind),
242            resolved.arch
243        );
244    }
245    if resolved.kernel_release.trim().is_empty() {
246        bail!("cached distro kernel release is empty");
247    }
248    if resolved.packages.is_empty() {
249        bail!("cached distro resolution has no kernel packages");
250    }
251
252    match kind {
253        DistroKind::SteamOs if !resolved.debuginfo.is_empty() => {
254            bail!("cached SteamOS resolution unexpectedly contains debuginfo")
255        }
256        DistroKind::Fedora | DistroKind::Ubuntu | DistroKind::AmazonLinux
257            if resolved.debuginfo.is_empty() =>
258        {
259            bail!(
260                "cached {} resolution has no mandatory debuginfo",
261                distro_kind_cache_name(kind)
262            )
263        }
264        _ => {}
265    }
266
267    for package in resolved.packages.iter().chain(&resolved.debuginfo) {
268        validate_cached_package(package)?;
269    }
270    Ok(())
271}
272
273fn validate_cached_distro_tag(kind: DistroKind, release: Option<&str>, distro: &str) -> Result<()> {
274    let valid = match (kind, release) {
275        (DistroKind::Fedora, Some(release)) => {
276            !release.is_empty()
277                && release.bytes().all(|byte| byte.is_ascii_digit())
278                && distro == format!("fedora{release}")
279        }
280        (DistroKind::Fedora, None) => distro.strip_prefix("fedora").is_some_and(|release| {
281            !release.is_empty() && release.bytes().all(|b| b.is_ascii_digit())
282        }),
283        (DistroKind::Ubuntu, Some(release)) => {
284            valid_dotted_release(release) && distro == format!("ubuntu{release}-hwe")
285        }
286        (DistroKind::Ubuntu, None) => distro
287            .strip_prefix("ubuntu")
288            .and_then(|tag| tag.strip_suffix("-hwe"))
289            .is_some_and(valid_dotted_release),
290        (DistroKind::AmazonLinux, _) => distro == "al2023",
291        (DistroKind::SteamOs, Some(release)) => {
292            valid_dotted_release(release) && distro == format!("steamos{release}")
293        }
294        (DistroKind::SteamOs, None) => distro
295            .strip_prefix("steamos")
296            .is_some_and(valid_dotted_release),
297        (DistroKind::Gke, _) => false,
298    };
299    if !valid {
300        bail!(
301            "cached {} distro tag {:?} does not match requested release {:?}",
302            distro_kind_cache_name(kind),
303            distro,
304            release
305        );
306    }
307    Ok(())
308}
309
310fn valid_dotted_release(release: &str) -> bool {
311    !release.is_empty()
312        && release.bytes().all(|b| b.is_ascii_digit() || b == b'.')
313        && release.split('.').all(|part| !part.is_empty())
314}
315
316fn validate_cached_package(package: &PackageRef) -> Result<()> {
317    if package.name.trim().is_empty() {
318        bail!("cached distro package has an empty name");
319    }
320    if package.version.trim().is_empty() {
321        bail!(
322            "cached distro package {} has an empty version",
323            package.name
324        );
325    }
326    let mut seen_urls = std::collections::HashSet::new();
327    for url in std::iter::once(&package.url).chain(&package.alternate_urls) {
328        let parsed = Url::parse(url).with_context(|| {
329            format!("cached distro package {} has an invalid URL", package.name)
330        })?;
331        if !matches!(parsed.scheme(), "http" | "https") || parsed.host_str().is_none() {
332            bail!(
333                "cached distro package {} URL must be absolute http(s): {}",
334                package.name,
335                url
336            );
337        }
338        if !seen_urls.insert(url) {
339            bail!(
340                "cached distro package {} repeats download URL {}",
341                package.name,
342                url
343            );
344        }
345    }
346    if package.sha256.len() != 64 || !package.sha256.bytes().all(|byte| byte.is_ascii_hexdigit()) {
347        bail!(
348            "cached distro package {} has an invalid sha256",
349            package.name
350        );
351    }
352    if package.size == Some(0) {
353        bail!("cached distro package {} has a zero size", package.name);
354    }
355    Ok(())
356}
357
358// ------------------------------------------------------------------
359// RPM EVR comparison (rpmvercmp)
360// ------------------------------------------------------------------
361
362/// An RPM epoch:version-release, kept as strings so comparison uses the
363/// documented `rpmvercmp` segment algorithm rather than lossy parsing.
364#[derive(Clone, Debug, PartialEq, Eq)]
365struct Evr {
366    epoch: String,
367    ver: String,
368    rel: String,
369}
370
371impl Evr {
372    /// `version-release`, prefixed with `epoch:` only when the epoch is
373    /// not the default `0`.
374    fn display(&self) -> String {
375        if self.epoch.is_empty() || self.epoch == "0" {
376            format!("{}-{}", self.ver, self.rel)
377        } else {
378            format!("{}:{}-{}", self.epoch, self.ver, self.rel)
379        }
380    }
381
382    fn cmp(&self, other: &Evr) -> Ordering {
383        let ea: i64 = self.epoch.parse().unwrap_or(0);
384        let eb: i64 = other.epoch.parse().unwrap_or(0);
385        ea.cmp(&eb)
386            .then_with(|| rpmvercmp(&self.ver, &other.ver))
387            .then_with(|| rpmvercmp(&self.rel, &other.rel))
388    }
389}
390
391/// Compare two RPM version (or release) strings per the `rpmvercmp`
392/// algorithm from `rpm`'s `lib/rpmvercmp.c`: split into maximal
393/// all-alpha / all-numeric segments across separator characters,
394/// compare numeric segments numerically (ignoring leading zeros) and
395/// alpha segments lexically, with `~` sorting before everything (even
396/// the empty string) and `^` sorting before an ended string but after
397/// any real segment.
398fn rpmvercmp(one: &str, two: &str) -> Ordering {
399    if one == two {
400        return Ordering::Equal;
401    }
402    let a = one.as_bytes();
403    let b = two.as_bytes();
404    let is_sep = |c: u8| !c.is_ascii_alphanumeric() && c != b'~' && c != b'^';
405    let (mut i, mut j) = (0usize, 0usize);
406    loop {
407        while i < a.len() && is_sep(a[i]) {
408            i += 1;
409        }
410        while j < b.len() && is_sep(b[j]) {
411            j += 1;
412        }
413
414        // `~` sorts before everything, including the end of the string.
415        let at = i < a.len() && a[i] == b'~';
416        let bt = j < b.len() && b[j] == b'~';
417        if at || bt {
418            if !at {
419                return Ordering::Greater;
420            }
421            if !bt {
422                return Ordering::Less;
423            }
424            i += 1;
425            j += 1;
426            continue;
427        }
428
429        // `^` sorts before an ended string but after any real segment.
430        let ac = i < a.len() && a[i] == b'^';
431        let bc = j < b.len() && b[j] == b'^';
432        if ac || bc {
433            if i >= a.len() {
434                return Ordering::Less;
435            }
436            if j >= b.len() {
437                return Ordering::Greater;
438            }
439            if !ac {
440                return Ordering::Greater;
441            }
442            if !bc {
443                return Ordering::Less;
444            }
445            i += 1;
446            j += 1;
447            continue;
448        }
449
450        if i >= a.len() || j >= b.len() {
451            break;
452        }
453
454        let isnum = a[i].is_ascii_digit();
455        let s1 = take_segment(a, &mut i, isnum);
456        let s2 = take_segment(b, &mut j, isnum);
457        // A numeric segment always outranks an alpha (or empty) one.
458        if s2.is_empty() {
459            return if isnum {
460                Ordering::Greater
461            } else {
462                Ordering::Less
463            };
464        }
465        let cmp = if isnum {
466            let n1 = trim_leading_zeros(s1);
467            let n2 = trim_leading_zeros(s2);
468            n1.len().cmp(&n2.len()).then_with(|| n1.cmp(n2))
469        } else {
470            s1.cmp(s2)
471        };
472        if cmp != Ordering::Equal {
473            return cmp;
474        }
475    }
476
477    // All compared segments were equal; whichever string still has
478    // characters left is the newer one.
479    match (i >= a.len(), j >= b.len()) {
480        (true, true) => Ordering::Equal,
481        (true, false) => Ordering::Less,
482        (false, true) => Ordering::Greater,
483        (false, false) => Ordering::Equal,
484    }
485}
486
487/// Consume the maximal all-numeric (or all-alpha) run at `*idx` and
488/// return it, advancing `idx` past it.
489fn take_segment<'a>(s: &'a [u8], idx: &mut usize, numeric: bool) -> &'a [u8] {
490    let start = *idx;
491    while *idx < s.len()
492        && ((numeric && s[*idx].is_ascii_digit()) || (!numeric && s[*idx].is_ascii_alphabetic()))
493    {
494        *idx += 1;
495    }
496    &s[start..*idx]
497}
498
499fn trim_leading_zeros(s: &[u8]) -> &[u8] {
500    let mut k = 0;
501    while k < s.len() && s[k] == b'0' {
502        k += 1;
503    }
504    &s[k..]
505}
506
507// ------------------------------------------------------------------
508// Debian version comparison (dpkg verrevcmp)
509// ------------------------------------------------------------------
510
511/// Compare two full Debian version strings (`[epoch:]upstream[-revision]`)
512/// per dpkg's algorithm: compare epoch numerically, then the upstream
513/// and revision parts with [`deb_verrevcmp`].
514fn deb_version_cmp(a: &str, b: &str) -> Ordering {
515    let (ea, ua, ra) = split_deb_version(a);
516    let (eb, ub, rb) = split_deb_version(b);
517    ea.cmp(&eb)
518        .then_with(|| deb_verrevcmp(ua, ub))
519        .then_with(|| deb_verrevcmp(ra, rb))
520}
521
522/// Split `[epoch:]upstream[-revision]` into `(epoch, upstream, revision)`.
523fn split_deb_version(v: &str) -> (u64, &str, &str) {
524    let (epoch, rest) = match v.split_once(':') {
525        Some((e, r)) if !e.is_empty() && e.bytes().all(|c| c.is_ascii_digit()) => {
526            (e.parse().unwrap_or(0), r)
527        }
528        _ => (0, v),
529    };
530    let (upstream, revision) = match rest.rsplit_once('-') {
531        Some((u, r)) => (u, r),
532        None => (rest, ""),
533    };
534    (epoch, upstream, revision)
535}
536
537/// Port of dpkg's `verrevcmp`: alternating non-digit / digit passes,
538/// with `~` sorting before everything (even the empty string) and
539/// letters sorting before non-letter punctuation.
540fn deb_verrevcmp(a: &str, b: &str) -> Ordering {
541    let a = a.as_bytes();
542    let b = b.as_bytes();
543    let (mut i, mut j) = (0usize, 0usize);
544    // dpkg's `order()`: digits sort as 0, letters as their ASCII value,
545    // `~` below everything, other punctuation above letters.
546    let order = |c: Option<u8>| -> i32 {
547        match c {
548            Some(c) if c.is_ascii_digit() => 0,
549            Some(c) if c.is_ascii_alphabetic() => c as i32,
550            Some(b'~') => -1,
551            Some(c) => c as i32 + 256,
552            None => 0,
553        }
554    };
555    while i < a.len() || j < b.len() {
556        // Non-digit prefix comparison.
557        while (i < a.len() && !a[i].is_ascii_digit()) || (j < b.len() && !b[j].is_ascii_digit()) {
558            let ac = order(a.get(i).copied());
559            let bc = order(b.get(j).copied());
560            if ac != bc {
561                return ac.cmp(&bc);
562            }
563            i += 1;
564            j += 1;
565        }
566        while i < a.len() && a[i] == b'0' {
567            i += 1;
568        }
569        while j < b.len() && b[j] == b'0' {
570            j += 1;
571        }
572        let mut first_diff = 0i32;
573        while i < a.len() && a[i].is_ascii_digit() && j < b.len() && b[j].is_ascii_digit() {
574            if first_diff == 0 {
575                first_diff = a[i] as i32 - b[j] as i32;
576            }
577            i += 1;
578            j += 1;
579        }
580        if i < a.len() && a[i].is_ascii_digit() {
581            return Ordering::Greater;
582        }
583        if j < b.len() && b[j].is_ascii_digit() {
584            return Ordering::Less;
585        }
586        if first_diff != 0 {
587            return first_diff.cmp(&0);
588        }
589    }
590    Ordering::Equal
591}
592
593// ------------------------------------------------------------------
594// repomd.xml + primary.xml (rpm) parsing
595// ------------------------------------------------------------------
596
597/// One `<data type=...>` entry from a `repomd.xml`.
598#[derive(Clone, Debug, PartialEq, Eq)]
599struct RepoData {
600    data_type: String,
601    href: String,
602    checksum: String,
603    checksum_type: String,
604}
605
606/// Parse `repomd.xml`, returning every `<data>` entry with its
607/// location href and (sha-typed) checksum.
608fn parse_repomd(xml: &[u8]) -> Result<Vec<RepoData>> {
609    let mut reader = Reader::from_reader(BufReader::new(Cursor::new(xml)));
610    reader.config_mut().trim_text(true);
611    let mut buf = Vec::new();
612    let mut out = Vec::new();
613    let mut cur: Option<RepoData> = None;
614    let mut in_checksum = false;
615    loop {
616        match reader
617            .read_event_into(&mut buf)
618            .with_context(|| "parse repomd.xml")?
619        {
620            Event::Start(e) => match e.local_name().as_ref() {
621                b"data" => {
622                    cur = Some(RepoData {
623                        data_type: attr(&e, b"type").unwrap_or_default(),
624                        href: String::new(),
625                        checksum: String::new(),
626                        checksum_type: String::new(),
627                    });
628                }
629                b"checksum" => {
630                    if let Some(c) = cur.as_mut() {
631                        c.checksum_type = attr(&e, b"type").unwrap_or_default();
632                        in_checksum = true;
633                    }
634                }
635                _ => {}
636            },
637            Event::Empty(e) => {
638                if e.local_name().as_ref() == b"location"
639                    && let Some(c) = cur.as_mut()
640                {
641                    c.href = attr(&e, b"href").unwrap_or_default();
642                }
643            }
644            Event::Text(t) if in_checksum => {
645                if let Some(c) = cur.as_mut() {
646                    c.checksum = t.decode().map(|s| s.into_owned()).unwrap_or_default();
647                }
648                in_checksum = false;
649            }
650            Event::End(e) => {
651                if e.local_name().as_ref() == b"data"
652                    && let Some(c) = cur.take()
653                {
654                    out.push(c);
655                }
656                in_checksum = false;
657            }
658            Event::Eof => break,
659            _ => {}
660        }
661        buf.clear();
662    }
663    Ok(out)
664}
665
666/// A candidate RPM parsed out of a `primary.xml`.
667#[derive(Clone, Debug, PartialEq, Eq)]
668struct RpmCand {
669    name: String,
670    arch: String,
671    evr: Evr,
672    sha256: String,
673    href: String,
674    size: Option<u64>,
675}
676
677/// Stream a (decompressed) `primary.xml`, collecting every package
678/// whose `<name>` satisfies `wanted`. Streaming keeps the multi-MB
679/// metadata out of memory: each `<package>` is filtered as its
680/// `</package>` closes rather than materializing a DOM.
681fn parse_primary<R: std::io::BufRead, F: Fn(&str) -> bool>(
682    reader: R,
683    wanted: F,
684) -> Result<Vec<RpmCand>> {
685    let mut reader = Reader::from_reader(reader);
686    reader.config_mut().trim_text(true);
687    let mut buf = Vec::new();
688    let mut out = Vec::new();
689    let mut cur: Option<RpmCand> = None;
690    // Which text-bearing field the next `Event::Text` fills in.
691    let mut pending: Option<Field> = None;
692    loop {
693        match reader
694            .read_event_into(&mut buf)
695            .with_context(|| "parse primary.xml")?
696        {
697            Event::Start(e) => match e.local_name().as_ref() {
698                b"package" => cur = Some(RpmCand::default_cand()),
699                b"name" if cur.is_some() => pending = Some(Field::Name),
700                b"arch" if cur.is_some() => pending = Some(Field::Arch),
701                b"checksum" if cur.is_some() => {
702                    let c = cur.as_ref().unwrap();
703                    if c.sha256.is_empty() && attr(&e, b"type").as_deref() == Some("sha256") {
704                        pending = Some(Field::Checksum);
705                    }
706                }
707                _ => apply_attr_element(cur.as_mut(), e.local_name().as_ref(), &e),
708            },
709            Event::Empty(e) => apply_attr_element(cur.as_mut(), e.local_name().as_ref(), &e),
710            Event::Text(t) if pending.is_some() && cur.is_some() => {
711                let val = t.decode().map(|s| s.into_owned()).unwrap_or_default();
712                let c = cur.as_mut().unwrap();
713                match pending.take().unwrap() {
714                    Field::Name if c.name.is_empty() => c.name = val,
715                    Field::Arch if c.arch.is_empty() => c.arch = val,
716                    Field::Checksum if c.sha256.is_empty() => c.sha256 = val,
717                    _ => {}
718                }
719            }
720            Event::End(e) => {
721                if e.local_name().as_ref() == b"package"
722                    && let Some(c) = cur.take()
723                    && wanted(&c.name)
724                {
725                    out.push(c);
726                }
727                pending = None;
728            }
729            Event::Eof => break,
730            _ => {}
731        }
732        buf.clear();
733    }
734    Ok(out)
735}
736
737enum Field {
738    Name,
739    Arch,
740    Checksum,
741}
742
743impl RpmCand {
744    fn default_cand() -> Self {
745        RpmCand {
746            name: String::new(),
747            arch: String::new(),
748            evr: Evr {
749                epoch: String::new(),
750                ver: String::new(),
751                rel: String::new(),
752            },
753            sha256: String::new(),
754            href: String::new(),
755            size: None,
756        }
757    }
758}
759
760/// Fill the attribute-only `<version>`, `<location>`, and `<size>`
761/// elements (self-closing in primary.xml, so they arrive as `Start`
762/// with no children or `Empty`). First-wins: the top-level elements
763/// precede the `<format>` block whose `rpm:entry` children reuse
764/// `ver`/`name` attribute spellings under different element names.
765fn apply_attr_element(cur: Option<&mut RpmCand>, local: &[u8], e: &BytesStart) {
766    let Some(c) = cur else { return };
767    match local {
768        b"version" if c.evr.ver.is_empty() => {
769            c.evr.epoch = attr(e, b"epoch").unwrap_or_else(|| "0".into());
770            c.evr.ver = attr(e, b"ver").unwrap_or_default();
771            c.evr.rel = attr(e, b"rel").unwrap_or_default();
772        }
773        b"location" if c.href.is_empty() => {
774            c.href = attr(e, b"href").unwrap_or_default();
775        }
776        b"size" if c.size.is_none() => {
777            c.size = attr(e, b"package").and_then(|s| s.parse().ok());
778        }
779        _ => {}
780    }
781}
782
783/// Read attribute `key` off `e` as an owned, entity-unescaped `String`.
784fn attr(e: &BytesStart, key: &[u8]) -> Option<String> {
785    e.try_get_attribute(key)
786        .ok()
787        .flatten()
788        .and_then(|a| a.unescape_value().ok().map(|c| c.into_owned()))
789}
790
791// ------------------------------------------------------------------
792// Debian Packages + text-metadata parsing
793// ------------------------------------------------------------------
794
795/// One binary-package stanza from a Debian `Packages` file.
796#[derive(Clone, Debug, PartialEq, Eq)]
797struct DebPkg {
798    package: String,
799    version: String,
800    filename: String,
801    sha256: String,
802    size: Option<u64>,
803    depends: Vec<String>,
804}
805
806/// Parse a decompressed Debian `Packages` file into stanzas. Only the
807/// fields the resolver consumes are extracted; folded continuation
808/// lines (never used by these fields) are ignored.
809fn parse_deb_packages(text: &str) -> Vec<DebPkg> {
810    let mut out = Vec::new();
811    for stanza in text.split("\n\n") {
812        if stanza.trim().is_empty() {
813            continue;
814        }
815        let mut p = DebPkg {
816            package: String::new(),
817            version: String::new(),
818            filename: String::new(),
819            sha256: String::new(),
820            size: None,
821            depends: Vec::new(),
822        };
823        for line in stanza.lines() {
824            let Some((key, val)) = line.split_once(": ") else {
825                continue;
826            };
827            match key {
828                "Package" => p.package = val.trim().to_string(),
829                "Version" => p.version = val.trim().to_string(),
830                "Filename" => p.filename = val.trim().to_string(),
831                "SHA256" => p.sha256 = val.trim().to_string(),
832                "Size" => p.size = val.trim().parse().ok(),
833                "Depends" => {
834                    p.depends = val
835                        .split(',')
836                        // Take the bare package name of each dependency,
837                        // dropping any `(>= x)` version constraint and
838                        // `pkg:arch` qualifier.
839                        .filter_map(|d| d.split_whitespace().next())
840                        .map(|d| d.split(':').next().unwrap_or(d).to_string())
841                        .collect();
842                }
843                _ => {}
844            }
845        }
846        if !p.package.is_empty() {
847            out.push(p);
848        }
849    }
850    out
851}
852
853/// Newest stanza named `name` by Debian version order, if any.
854fn newest_deb<'a>(pkgs: &'a [DebPkg], name: &str) -> Option<&'a DebPkg> {
855    pkgs.iter()
856        .filter(|p| p.package == name)
857        .max_by(|a, b| deb_version_cmp(&a.version, &b.version))
858}
859
860/// One release row from `meta-release-lts`.
861#[derive(Clone, Debug, PartialEq, Eq)]
862struct UbuntuRelease {
863    dist: String,
864    version: String,
865    supported: bool,
866}
867
868/// Parse `meta-release-lts` (blank-line-separated stanzas of
869/// `Key: value` lines) into release rows.
870fn parse_meta_release_lts(text: &str) -> Vec<UbuntuRelease> {
871    let mut out = Vec::new();
872    for stanza in text.split("\n\n") {
873        let mut dist = String::new();
874        let mut version = String::new();
875        let mut supported = false;
876        for line in stanza.lines() {
877            let Some((key, val)) = line.split_once(": ") else {
878                continue;
879            };
880            match key {
881                "Dist" => dist = val.trim().to_string(),
882                "Version" => version = val.trim().to_string(),
883                "Supported" => supported = val.trim() == "1",
884                _ => {}
885            }
886        }
887        if !dist.is_empty() {
888            out.push(UbuntuRelease {
889                dist,
890                version,
891                supported,
892            });
893        }
894    }
895    out
896}
897
898/// `major.minor` of a `meta-release-lts` `Version` string
899/// (e.g. `"24.04.1 LTS"` -> `(24, 4)`), for LTS ordering.
900fn lts_version_key(version: &str) -> Option<(u32, u32)> {
901    let head = version.split_whitespace().next()?;
902    let mut it = head.split('.');
903    let major = it.next()?.parse().ok()?;
904    let minor = it.next()?.parse().ok()?;
905    Some((major, minor))
906}
907
908/// Newest supported LTS `(version, codename)` from the parsed rows,
909/// where `version` is normalized to `major.minor` (e.g. `"24.04"`).
910fn latest_lts(rels: &[UbuntuRelease]) -> Option<(String, String)> {
911    rels.iter()
912        .filter(|r| r.supported)
913        .filter_map(|r| lts_version_key(&r.version).map(|k| (k, r)))
914        .max_by_key(|(k, _)| *k)
915        .map(|((major, minor), r)| (format!("{major}.{minor:02}"), r.dist.clone()))
916}
917
918/// Codename for a pinned `major.minor` version (e.g. `"24.04"`).
919fn codename_for_version(rels: &[UbuntuRelease], version: &str) -> Option<String> {
920    rels.iter()
921        .find(|r| lts_version_key(&r.version) == lts_version_key(version))
922        .map(|r| r.dist.clone())
923}
924
925/// Offline fallback: version -> codename for the LTS releases the live
926/// `meta-release-lts` map should also carry. Used only when the network
927/// map lacks the pinned version (and by the offline unit tests).
928fn fallback_codename(version: &str) -> Option<&'static str> {
929    match version {
930        "24.04" => Some("noble"),
931        "22.04" => Some("jammy"),
932        "20.04" => Some("focal"),
933        _ => None,
934    }
935}
936
937/// First non-empty line of an Amazon Linux `mirror.list`, normalized to
938/// end in `/` so it composes as a repo base URL.
939fn parse_mirror_list(text: &str) -> Option<String> {
940    let line = text.lines().map(str::trim).find(|l| !l.is_empty())?;
941    Some(if line.ends_with('/') {
942        line.to_string()
943    } else {
944        format!("{line}/")
945    })
946}
947
948// ------------------------------------------------------------------
949// URL joining + metadata decompression + checksum
950// ------------------------------------------------------------------
951
952/// Resolve `href` (which may be relative, including `../` traversal, as
953/// AL2023's blobstore hrefs are) against `base` per RFC 3986.
954fn join_url(base: &str, href: &str) -> Result<String> {
955    Url::parse(base)
956        .with_context(|| format!("parse repo base url {base}"))?
957        .join(href)
958        .with_context(|| format!("join {href} onto {base}"))
959        .map(|u| u.to_string())
960}
961
962/// Wrap `bytes` in the decompressor its metadata filename extension
963/// implies (`.gz` / `.zst` / `.xz`, or plain for `.xml`).
964fn decompress_metadata<'a>(href: &str, bytes: &'a [u8]) -> Result<Box<dyn Read + 'a>> {
965    let cursor = Cursor::new(bytes);
966    if href.ends_with(".gz") {
967        Ok(Box::new(flate2::read::GzDecoder::new(cursor)))
968    } else if href.ends_with(".zst") {
969        Ok(Box::new(
970            zstd::Decoder::new(cursor).with_context(|| "init zstd decoder")?,
971        ))
972    } else if href.ends_with(".xz") {
973        Ok(Box::new(xz2::read::XzDecoder::new(cursor)))
974    } else if href.ends_with(".xml") {
975        Ok(Box::new(cursor))
976    } else {
977        bail!("unsupported metadata compression for {href}")
978    }
979}
980
981/// Verify `bytes` hash against a repomd-declared sha256 (case-insensitive).
982fn verify_metadata_sha256(bytes: &[u8], expected: &str, href: &str) -> Result<()> {
983    let mut h = Sha256::new();
984    h.update(bytes);
985    let actual = hex::encode(h.finalize());
986    if actual.eq_ignore_ascii_case(expected) {
987        Ok(())
988    } else {
989        bail!("sha256 mismatch for {href}: expected {expected}, got {actual}")
990    }
991}
992
993/// Fetch `repodata/repomd.xml` under `base`, then the `type="primary"`
994/// metadata it references, verify the compressed file's declared
995/// sha256, and stream-parse it for the `wanted` package names.
996fn fetch_repo_candidates(base: &str, wanted: &[&str]) -> Result<Vec<RpmCand>> {
997    fetch_repo_candidates_where(base, |name| wanted.contains(&name))
998}
999
1000/// Predicate-driven form of [`fetch_repo_candidates`], for resolvers
1001/// whose package names are not known up front (AL2023's dynamic
1002/// `kernel<X>.<Y>` stream names).
1003fn fetch_repo_candidates_where<F: Fn(&str) -> bool>(base: &str, wanted: F) -> Result<Vec<RpmCand>> {
1004    let repomd_url = join_url(base, "repodata/repomd.xml")?;
1005    let repomd = crate::fetch::fetch_metadata_bytes(&repomd_url, "fetch")?;
1006    let datas = parse_repomd(&repomd)?;
1007    let primary = datas
1008        .iter()
1009        .find(|d| d.data_type == "primary")
1010        .ok_or_else(|| anyhow!("repomd.xml at {repomd_url} has no primary metadata"))?;
1011    let primary_url = join_url(base, &primary.href)?;
1012    let compressed = crate::fetch::fetch_metadata_bytes(&primary_url, "fetch")?;
1013    if primary.checksum_type == "sha256" && !primary.checksum.is_empty() {
1014        verify_metadata_sha256(&compressed, &primary.checksum, &primary.href)?;
1015    }
1016    let reader = BufReader::new(decompress_metadata(&primary.href, &compressed)?);
1017    parse_primary(reader, wanted)
1018}
1019
1020/// Newest EVR among `cands` named `name`.
1021fn newest_evr(cands: &[RpmCand], name: &str) -> Option<Evr> {
1022    cands
1023        .iter()
1024        .filter(|c| c.name == name)
1025        .max_by(|a, b| a.evr.cmp(&b.evr))
1026        .map(|c| c.evr.clone())
1027}
1028
1029/// Build [`PackageRef`]s for `names` (in order) at exactly `target`
1030/// EVR. Missing names are skipped when `strict` is false; when `strict`
1031/// (debuginfo — mandatory in this design — and package sets where every
1032/// member is load-bearing, like AL2023's kernel + modules-extra pair) a
1033/// missing name is a hard error.
1034fn build_package_set(
1035    cands: &[RpmCand],
1036    base: &str,
1037    names: &[&str],
1038    target: &Evr,
1039    strict: bool,
1040) -> Result<Vec<PackageRef>> {
1041    let mut out = Vec::new();
1042    for name in names {
1043        match cands.iter().find(|c| c.name == *name && c.evr == *target) {
1044            Some(c) => out.push(PackageRef {
1045                name: c.name.clone(),
1046                version: c.evr.display(),
1047                url: join_url(base, &c.href)?,
1048                alternate_urls: Vec::new(),
1049                sha256: c.sha256.clone(),
1050                size: c.size,
1051            }),
1052            None if strict => bail!(
1053                "{name}-{} not found in repo metadata at {base}",
1054                target.display()
1055            ),
1056            None => {}
1057        }
1058    }
1059    Ok(out)
1060}
1061
1062// ------------------------------------------------------------------
1063// Per-distro resolvers
1064// ------------------------------------------------------------------
1065
1066const FEDORA_RELEASES_JSON: &str = "https://fedoraproject.org/releases.json";
1067const FEDORA_MIRROR_BASE: &str = "https://dl.fedoraproject.org/pub/fedora/linux";
1068
1069/// Latest stable Fedora release number from `releases.json`: the max
1070/// all-numeric `version` field (GA releases only; Rawhide/Branched carry
1071/// non-numeric or absent versions and are filtered out).
1072fn fedora_latest_release() -> Result<String> {
1073    let body = crate::fetch::fetch_metadata_text(FEDORA_RELEASES_JSON, "fetch")?;
1074    let latest = fedora_latest_from_json(&body)?;
1075    Ok(latest)
1076}
1077
1078fn fedora_latest_from_json(body: &str) -> Result<String> {
1079    let json: serde_json::Value =
1080        serde_json::from_str(body).with_context(|| "parse fedora releases.json")?;
1081    json.as_array()
1082        .ok_or_else(|| anyhow!("fedora releases.json: expected top-level array"))?
1083        .iter()
1084        .filter_map(|r| r.get("version").and_then(|v| v.as_str()))
1085        .filter_map(|v| v.parse::<u32>().ok())
1086        .max()
1087        .map(|n| n.to_string())
1088        .ok_or_else(|| anyhow!("fedora releases.json: no numeric release version found"))
1089}
1090
1091fn resolve_fedora(release: Option<&str>, arch: &str) -> Result<ResolvedDistroKernel> {
1092    let rel = match release {
1093        Some(r) => r.to_string(),
1094        None => fedora_latest_release()?,
1095    };
1096    let common = format!("kernel-debuginfo-common-{arch}");
1097    let pkg_names = ["kernel-core", "kernel-modules-core", "kernel-modules"];
1098
1099    // Prefer the updates repo; fall back to the GA releases repo if it
1100    // carries no kernel-core (fresh release before its first update).
1101    let updates_base = format!("{FEDORA_MIRROR_BASE}/updates/{rel}/Everything/{arch}/");
1102    let mut base = updates_base.clone();
1103    let mut cands = fetch_repo_candidates(&base, &pkg_names)?;
1104    let mut debug_base = format!("{FEDORA_MIRROR_BASE}/updates/{rel}/Everything/{arch}/debug/");
1105    if newest_evr(&cands, "kernel-core").is_none() {
1106        base = format!("{FEDORA_MIRROR_BASE}/releases/{rel}/Everything/{arch}/os/");
1107        cands = fetch_repo_candidates(&base, &pkg_names)?;
1108        debug_base = format!("{FEDORA_MIRROR_BASE}/releases/{rel}/Everything/{arch}/debug/tree/");
1109    }
1110
1111    let target = newest_evr(&cands, "kernel-core")
1112        .ok_or_else(|| anyhow!("no kernel-core found in Fedora {rel} repos for {arch}"))?;
1113    let packages = build_package_set(&cands, &base, &pkg_names, &target, false)?;
1114
1115    let debug_names = ["kernel-debuginfo", common.as_str()];
1116    let debug_cands = fetch_repo_candidates(&debug_base, &debug_names)?;
1117    let debuginfo = build_package_set(&debug_cands, &debug_base, &debug_names, &target, true)?;
1118
1119    Ok(ResolvedDistroKernel {
1120        distro: format!("fedora{rel}"),
1121        kernel_release: target.display(),
1122        arch: arch.to_string(),
1123        packages,
1124        debuginfo,
1125    })
1126}
1127
1128const UBUNTU_META_RELEASE_LTS: &str = "https://changelogs.ubuntu.com/meta-release-lts";
1129const UBUNTU_ARCHIVE: &str = "https://archive.ubuntu.com/ubuntu/";
1130const UBUNTU_PORTS: &str = "https://ports.ubuntu.com/ubuntu-ports/";
1131const UBUNTU_DDEBS: &str = "https://ddebs.ubuntu.com/";
1132const LAUNCHPAD_PRIMARY_ARCHIVE_API: &str =
1133    "https://api.launchpad.net/devel/ubuntu/+archive/primary";
1134const LAUNCHPAD_PRIMARY_FILES: &str = "https://launchpad.net/ubuntu/+archive/primary/+files/";
1135
1136/// Map the host arch string to Ubuntu's package architecture.
1137fn ubuntu_arch(arch: &str) -> Result<&'static str> {
1138    match arch {
1139        "x86_64" => Ok("amd64"),
1140        "aarch64" => Ok("arm64"),
1141        other => bail!("unsupported arch for Ubuntu: {other}"),
1142    }
1143}
1144
1145fn resolve_ubuntu(release: Option<&str>, arch: &str) -> Result<ResolvedDistroKernel> {
1146    let deb_arch = ubuntu_arch(arch)?;
1147    // amd64 lives on archive.ubuntu.com; every other port on ports.ubuntu.com.
1148    let archive_base = if deb_arch == "amd64" {
1149        UBUNTU_ARCHIVE
1150    } else {
1151        UBUNTU_PORTS
1152    };
1153
1154    let meta = crate::fetch::fetch_metadata_text(UBUNTU_META_RELEASE_LTS, "fetch")?;
1155    let rels = parse_meta_release_lts(&meta);
1156    let (version, codename) = match release {
1157        Some(v) => {
1158            let codename = codename_for_version(&rels, v)
1159                .or_else(|| fallback_codename(v).map(str::to_string))
1160                .ok_or_else(|| anyhow!("no Ubuntu LTS codename for {v}"))?;
1161            (v.to_string(), codename)
1162        }
1163        None => latest_lts(&rels)
1164            .ok_or_else(|| anyhow!("meta-release-lts: no supported LTS release found"))?,
1165    };
1166
1167    let debs = fetch_deb_packages(archive_base, &codename, deb_arch)?;
1168    let meta_name = format!("linux-image-generic-hwe-{version}");
1169    let meta_pkg = newest_deb(&debs, &meta_name).ok_or_else(|| {
1170        anyhow!("HWE meta {meta_name} not found in {codename}-updates/{deb_arch}")
1171    })?;
1172    let preferred_kver = hwe_kver(meta_pkg)
1173        .ok_or_else(|| anyhow!("{meta_name} Depends has no linux-image-*-generic"))?;
1174
1175    // The HWE meta names the newest supported kernel, but its -dbgsym
1176    // ddeb can lag the image publish by hours on ddebs.ubuntu.com. Rather
1177    // than hard-fail during that window, resolve the NEWEST kernel that
1178    // is FULLY published — image AND debuginfo both present. Debuginfo
1179    // stays mandatory (see [`newest_kernel_with_debuginfo`]); we just don't
1180    // demand the bleeding edge when an equally-valid, complete kernel is
1181    // one step back. A hard error remains only when NO kernel in the
1182    // series has debuginfo — a genuinely broken archive, not a lag.
1183    // The DDEB archive is the fast index provider. Launchpad's official API
1184    // and Librarian are a genuinely independent provider: unlike switching
1185    // schemes on ddebs.ubuntu.com, they can resolve a cold cache while that
1186    // archive returns 503. A healthy DDEB result also carries a deterministic
1187    // Launchpad file URL as an independent download origin, verified against
1188    // the DDEB index's exact SHA256 and size.
1189    let selected = match fetch_ubuntu_ddebs(&codename, deb_arch).and_then(|ddebs| {
1190        let selected = newest_kernel_with_debuginfo(&debs, &ddebs).ok_or_else(|| {
1191            anyhow!(
1192                "no Ubuntu {codename}-updates/{deb_arch} kernel has both an image and \
1193                 a dbgsym ddeb in the DDEB index"
1194            )
1195        })?;
1196        Ok(UbuntuResolvedSelection {
1197            kver: selected.kver,
1198            image: selected.image,
1199            debuginfo: ubuntu_ddeb_package_ref(selected.dbgsym)?,
1200        })
1201    }) {
1202        Ok(selected) => selected,
1203        Err(ddebs_error) => {
1204            tracing::warn!(
1205                codename,
1206                arch = deb_arch,
1207                error = %format!("{ddebs_error:#}"),
1208                "Ubuntu DDEB index unavailable; resolving exact dbgsym through Launchpad",
1209            );
1210            newest_kernel_with_launchpad_debuginfo(&debs, &codename, deb_arch)?.ok_or_else(
1211                || {
1212                    anyhow!(
1213                        "no Ubuntu {codename}-updates/{deb_arch} kernel has a published \
1214                         dbgsym in either official provider; DDEB index failed: \
1215                         {ddebs_error:#}"
1216                    )
1217                },
1218            )?
1219        }
1220    };
1221    let kver = selected.kver.as_str();
1222    if kver != preferred_kver {
1223        crate::ktstr_status!(
1224            "ktstr: newest HWE kernel {preferred_kver} has no dbgsym ddeb yet \
1225             (Ubuntu dbgsym publishing can lag by hours); using {kver}, the newest \
1226             fully-published kernel with debuginfo"
1227        );
1228    }
1229
1230    // The HWE meta's Depends chain: linux-image (vmlinuz) ->
1231    // linux-modules, plus linux-modules-extra (the meta depends on it
1232    // directly). Include all three so no in-tree module the guest might
1233    // need is left out; the extraction stage decides what to unpack.
1234    let pkg_names = [
1235        format!("linux-image-{kver}-generic"),
1236        format!("linux-modules-{kver}-generic"),
1237        format!("linux-modules-extra-{kver}-generic"),
1238    ];
1239    let packages = ubuntu_package_refs(&debs, archive_base, &pkg_names, false)?;
1240
1241    // Debuginfo: the -dbgsym ddeb carries vmlinux. The unsigned image's
1242    // dbgsym is the canonical vmlinux carrier; fall back to the signed
1243    // one. The exact ddeb stanza is carried by `selected`, making kernel
1244    // version selection and debuginfo selection one atomic operation.
1245    // There is deliberately no second name lookup that could disagree
1246    // with the fallback decision.
1247    let debuginfo = vec![selected.debuginfo];
1248
1249    // Report the CHOSEN kernel's image version (a fallback may be older
1250    // than the HWE meta's), not the meta package's.
1251    let kernel_release = selected.image.version.clone();
1252
1253    Ok(ResolvedDistroKernel {
1254        distro: format!("ubuntu{version}-hwe"),
1255        kernel_release,
1256        arch: deb_arch.to_string(),
1257        packages,
1258        debuginfo,
1259    })
1260}
1261
1262/// One fully-published Ubuntu kernel and the exact image/dbgsym stanzas
1263/// selected for it.
1264struct UbuntuKernelSelection<'image, 'debug> {
1265    kver: String,
1266    image: &'image DebPkg,
1267    dbgsym: &'debug DebPkg,
1268}
1269
1270/// Provider-independent resolved Ubuntu selection. The image stanza always
1271/// comes from Ubuntu's normal archive; the owned debuginfo reference may come
1272/// from the DDEB index or Launchpad's API/Librarian.
1273struct UbuntuResolvedSelection<'a> {
1274    kver: String,
1275    image: &'a DebPkg,
1276    debuginfo: PackageRef,
1277}
1278
1279/// Newest kernel (e.g. `6.17.0-38`) in the `-updates` `debs`
1280/// that is FULLY published: it has a `linux-image-{kver}-generic` image
1281/// deb AND a matching dbgsym ddeb (unsigned preferred, signed fallback)
1282/// in `ddebs`. Ordered by the image package's Debian version, newest
1283/// first. `None` only when no kernel in the series has debuginfo at all.
1284///
1285/// This is the fallback that tolerates the hours-long window where a
1286/// just-published kernel's ddeb has not yet landed on ddebs.ubuntu.com:
1287/// the newest kernel whose debuginfo IS present is picked instead of
1288/// hard-failing on the bleeding edge. `{kver}` candidates come from the
1289/// image debs (not the ddebs) so a stray dbgsym without a matching image
1290/// can never be selected; the digit-prefix filter drops meta/unsigned/
1291/// flavored names, leaving only concrete `MAJOR.MINOR.PATCH-ABI` kvers.
1292fn newest_kernel_with_debuginfo<'image, 'debug>(
1293    debs: &'image [DebPkg],
1294    ddebs: &'debug [DebPkg],
1295) -> Option<UbuntuKernelSelection<'image, 'debug>> {
1296    debs.iter()
1297        .filter_map(|p| {
1298            p.package
1299                .strip_prefix("linux-image-")
1300                .and_then(|s| s.strip_suffix("-generic"))
1301                .filter(|kver| kver.chars().next().is_some_and(|c| c.is_ascii_digit()))
1302                .and_then(|kver| {
1303                    ubuntu_dbgsym(ddebs, kver).map(|dbgsym| UbuntuKernelSelection {
1304                        kver: kver.to_string(),
1305                        image: p,
1306                        dbgsym,
1307                    })
1308                })
1309        })
1310        .max_by(|a, b| deb_version_cmp(&a.image.version, &b.image.version))
1311}
1312
1313/// Return the exact dbgsym stanza for `kver`, preferring the unsigned
1314/// image package (Ubuntu's canonical vmlinux carrier) over the signed
1315/// fallback.
1316fn ubuntu_dbgsym<'a>(ddebs: &'a [DebPkg], kver: &str) -> Option<&'a DebPkg> {
1317    let unsigned = format!("linux-image-unsigned-{kver}-generic-dbgsym");
1318    let signed = format!("linux-image-{kver}-generic-dbgsym");
1319    newest_deb(ddebs, &unsigned).or_else(|| newest_deb(ddebs, &signed))
1320}
1321
1322/// Query candidate images newest-first through an injected exact dbgsym
1323/// lookup. Unsigned is Ubuntu's canonical vmlinux carrier; the signed package
1324/// is accepted only when the unsigned publication is absent.
1325fn newest_kernel_with_exact_dbgsym_lookup<'a, F>(
1326    debs: &'a [DebPkg],
1327    mut lookup: F,
1328) -> Result<Option<UbuntuResolvedSelection<'a>>>
1329where
1330    F: FnMut(&str, &str) -> Result<Option<PackageRef>>,
1331{
1332    let mut images: Vec<(String, &'a DebPkg)> = debs
1333        .iter()
1334        .filter_map(|image| {
1335            image
1336                .package
1337                .strip_prefix("linux-image-")
1338                .and_then(|name| name.strip_suffix("-generic"))
1339                .filter(|kver| kver.chars().next().is_some_and(|c| c.is_ascii_digit()))
1340                .map(|kver| (kver.to_string(), image))
1341        })
1342        .collect();
1343    images.sort_by(|(_, a), (_, b)| deb_version_cmp(&b.version, &a.version));
1344
1345    for (kver, image) in images {
1346        let names = [
1347            format!("linux-image-unsigned-{kver}-generic-dbgsym"),
1348            format!("linux-image-{kver}-generic-dbgsym"),
1349        ];
1350        for name in names {
1351            let Some(debuginfo) = lookup(&name, &image.version)? else {
1352                continue;
1353            };
1354            if debuginfo.name != name || debuginfo.version != image.version {
1355                bail!(
1356                    "exact dbgsym lookup returned {} {} for requested {} {}",
1357                    debuginfo.name,
1358                    debuginfo.version,
1359                    name,
1360                    image.version
1361                );
1362            }
1363            validate_cached_package(&debuginfo)
1364                .with_context(|| format!("validate exact dbgsym result for {name}"))?;
1365            return Ok(Some(UbuntuResolvedSelection {
1366                kver,
1367                image,
1368                debuginfo,
1369            }));
1370        }
1371    }
1372    Ok(None)
1373}
1374
1375fn newest_kernel_with_launchpad_debuginfo<'a>(
1376    debs: &'a [DebPkg],
1377    codename: &str,
1378    deb_arch: &str,
1379) -> Result<Option<UbuntuResolvedSelection<'a>>> {
1380    newest_kernel_with_exact_dbgsym_lookup(debs, |name, version| {
1381        fetch_launchpad_ddeb(codename, deb_arch, name, version)
1382    })
1383}
1384
1385/// Fetch and parse `{codename}-updates` `Packages.gz` for `deb_arch`.
1386fn fetch_deb_packages(base: &str, codename: &str, deb_arch: &str) -> Result<Vec<DebPkg>> {
1387    let url = deb_packages_url(base, codename, deb_arch);
1388    let gz = crate::fetch::fetch_metadata_bytes(&url, "fetch")?;
1389    let mut text = String::new();
1390    flate2::read::GzDecoder::new(Cursor::new(&gz))
1391        .read_to_string(&mut text)
1392        .with_context(|| format!("gunzip {url}"))?;
1393    Ok(parse_deb_packages(&text))
1394}
1395
1396/// Fetch Ubuntu's debug-package index from its one published DDEB archive.
1397/// Availability failover is Launchpad below, not another scheme on this host.
1398fn fetch_ubuntu_ddebs(codename: &str, deb_arch: &str) -> Result<Vec<DebPkg>> {
1399    fetch_deb_packages(UBUNTU_DDEBS, codename, deb_arch)
1400}
1401
1402#[derive(Debug, serde::Deserialize)]
1403struct LaunchpadBinaryPublications {
1404    total_size: usize,
1405    entries: Vec<LaunchpadBinaryPublication>,
1406}
1407
1408#[derive(Debug, serde::Deserialize)]
1409struct LaunchpadBinaryPublication {
1410    self_link: String,
1411    binary_package_name: String,
1412    binary_package_version: String,
1413    distro_arch_series_link: String,
1414    status: String,
1415    pocket: String,
1416    is_debug: bool,
1417}
1418
1419#[derive(Debug, serde::Deserialize)]
1420struct LaunchpadBinaryFile {
1421    url: String,
1422    sha256: String,
1423    size: u64,
1424}
1425
1426fn launchpad_arch_series(codename: &str, deb_arch: &str) -> String {
1427    format!("https://api.launchpad.net/devel/ubuntu/{codename}/{deb_arch}")
1428}
1429
1430/// Exact anonymous Launchpad query for one published Updates-pocket binary.
1431/// Every identity axis is repeated in response validation; query filtering is
1432/// an optimization, never the correctness boundary.
1433fn launchpad_ddeb_query_url(
1434    codename: &str,
1435    deb_arch: &str,
1436    name: &str,
1437    version: &str,
1438) -> Result<String> {
1439    let mut url = Url::parse(LAUNCHPAD_PRIMARY_ARCHIVE_API)
1440        .context("parse Launchpad primary archive API URL")?;
1441    url.query_pairs_mut()
1442        .append_pair("ws.op", "getPublishedBinaries")
1443        .append_pair("binary_name", name)
1444        .append_pair("exact_match", "true")
1445        .append_pair("version", version)
1446        .append_pair(
1447            "distro_arch_series",
1448            &launchpad_arch_series(codename, deb_arch),
1449        )
1450        .append_pair("pocket", "Updates")
1451        .append_pair("status", "Published")
1452        .append_pair("order_by", "published_date_desc");
1453    Ok(url.to_string())
1454}
1455
1456fn validate_launchpad_binarypub_url(value: &str) -> Result<Url> {
1457    const PREFIX: &str = "/devel/ubuntu/+archive/primary/+binarypub/";
1458    let url = Url::parse(value).context("parse Launchpad binary publication URL")?;
1459    let id = url.path().strip_prefix(PREFIX).unwrap_or_default();
1460    if url.scheme() != "https"
1461        || url.host_str() != Some("api.launchpad.net")
1462        || id.is_empty()
1463        || !id.bytes().all(|byte| byte.is_ascii_digit())
1464        || url.query().is_some()
1465        || url.fragment().is_some()
1466    {
1467        bail!("Launchpad returned a non-primary binary publication URL: {value}");
1468    }
1469    Ok(url)
1470}
1471
1472fn exact_launchpad_publication(
1473    bytes: &[u8],
1474    codename: &str,
1475    deb_arch: &str,
1476    name: &str,
1477    version: &str,
1478) -> Result<Option<LaunchpadBinaryPublication>> {
1479    let mut response: LaunchpadBinaryPublications =
1480        serde_json::from_slice(bytes).context("parse Launchpad published-binaries response")?;
1481    if response.total_size == 0 {
1482        if !response.entries.is_empty() {
1483            bail!("Launchpad returned entries with total_size=0");
1484        }
1485        return Ok(None);
1486    }
1487    if response.total_size != response.entries.len() {
1488        bail!(
1489            "exact Launchpad dbgsym query returned a paginated or torn result: \
1490             total_size={}, entries={}",
1491            response.total_size,
1492            response.entries.len()
1493        );
1494    }
1495    if response.entries.len() != 1 {
1496        bail!(
1497            "exact Launchpad dbgsym query returned {} publications for {name} {version}",
1498            response.entries.len()
1499        );
1500    }
1501
1502    let publication = response.entries.pop().unwrap();
1503    let expected_arch_series = launchpad_arch_series(codename, deb_arch);
1504    if publication.binary_package_name != name
1505        || publication.binary_package_version != version
1506        || publication.distro_arch_series_link != expected_arch_series
1507        || publication.status != "Published"
1508        || publication.pocket != "Updates"
1509        || !publication.is_debug
1510    {
1511        bail!(
1512            "Launchpad dbgsym publication identity mismatch for requested \
1513             {name} {version} in {codename}/{deb_arch}: {publication:?}"
1514        );
1515    }
1516    validate_launchpad_binarypub_url(&publication.self_link)?;
1517    Ok(Some(publication))
1518}
1519
1520fn launchpad_binary_files_url(self_link: &str) -> Result<String> {
1521    let mut url = validate_launchpad_binarypub_url(self_link)?;
1522    url.query_pairs_mut()
1523        .append_pair("ws.op", "binaryFileUrls")
1524        .append_pair("include_meta", "true");
1525    Ok(url.to_string())
1526}
1527
1528fn launchpad_ddeb_package_ref(
1529    bytes: &[u8],
1530    name: &str,
1531    version: &str,
1532    deb_arch: &str,
1533) -> Result<PackageRef> {
1534    let mut files: Vec<LaunchpadBinaryFile> =
1535        serde_json::from_slice(bytes).context("parse Launchpad binary-file response")?;
1536    if files.len() != 1 {
1537        bail!(
1538            "Launchpad returned {} binary files for exact dbgsym {name} {version}",
1539            files.len()
1540        );
1541    }
1542    let file = files.pop().unwrap();
1543    let url = Url::parse(&file.url).context("parse Launchpad dbgsym file URL")?;
1544    let filename = url
1545        .path_segments()
1546        .and_then(|mut segments| segments.next_back())
1547        .unwrap_or_default();
1548    let expected_filename = format!("{name}_{version}_{deb_arch}.ddeb");
1549    if url.scheme() != "https"
1550        || url.host_str() != Some("launchpad.net")
1551        || !url.path().starts_with("/ubuntu/+archive/primary/+files/")
1552        || filename != expected_filename
1553        || url.query().is_some()
1554        || url.fragment().is_some()
1555    {
1556        bail!(
1557            "Launchpad returned an invalid primary-archive dbgsym URL: {}",
1558            file.url
1559        );
1560    }
1561    if file.sha256.len() != 64
1562        || !file.sha256.bytes().all(|byte| byte.is_ascii_hexdigit())
1563        || file.size == 0
1564    {
1565        bail!("Launchpad returned invalid SHA256/size metadata for {name} {version}");
1566    }
1567
1568    Ok(PackageRef {
1569        name: name.to_string(),
1570        version: version.to_string(),
1571        url: file.url,
1572        alternate_urls: Vec::new(),
1573        sha256: file.sha256,
1574        size: Some(file.size),
1575    })
1576}
1577
1578fn fetch_launchpad_ddeb(
1579    codename: &str,
1580    deb_arch: &str,
1581    name: &str,
1582    version: &str,
1583) -> Result<Option<PackageRef>> {
1584    let query_url = launchpad_ddeb_query_url(codename, deb_arch, name, version)?;
1585    let publications = crate::fetch::fetch_metadata_bytes(
1586        &query_url,
1587        "fetch Ubuntu dbgsym publication from Launchpad",
1588    )?;
1589    let Some(publication) =
1590        exact_launchpad_publication(&publications, codename, deb_arch, name, version)?
1591    else {
1592        return Ok(None);
1593    };
1594    let files_url = launchpad_binary_files_url(&publication.self_link)?;
1595    let files = crate::fetch::fetch_metadata_bytes(
1596        &files_url,
1597        "fetch Ubuntu dbgsym file metadata from Launchpad",
1598    )?;
1599    Ok(Some(launchpad_ddeb_package_ref(
1600        &files, name, version, deb_arch,
1601    )?))
1602}
1603
1604fn deb_packages_url(base: &str, codename: &str, deb_arch: &str) -> String {
1605    format!("{base}dists/{codename}-updates/main/binary-{deb_arch}/Packages.gz")
1606}
1607
1608/// Extract the `{kver}` (e.g. `6.17.0-35`) from an HWE meta's
1609/// `linux-image-{kver}-generic` dependency.
1610fn hwe_kver(meta: &DebPkg) -> Option<String> {
1611    meta.depends
1612        .iter()
1613        .find(|d| d.starts_with("linux-image-") && d.ends_with("-generic"))
1614        .and_then(|d| d.strip_prefix("linux-image-"))
1615        .and_then(|d| d.strip_suffix("-generic"))
1616        .map(str::to_string)
1617}
1618
1619/// Resolve concrete Ubuntu package stanzas to [`PackageRef`]s.
1620fn ubuntu_package_refs(
1621    debs: &[DebPkg],
1622    base: &str,
1623    names: &[String],
1624    strict: bool,
1625) -> Result<Vec<PackageRef>> {
1626    let mut out = Vec::new();
1627    for name in names {
1628        match newest_deb(debs, name) {
1629            Some(p) => out.push(deb_package_ref(p, base)?),
1630            None if strict => bail!("{name} not found in repo metadata"),
1631            None => {}
1632        }
1633    }
1634    Ok(out)
1635}
1636
1637fn deb_package_ref(p: &DebPkg, base: &str) -> Result<PackageRef> {
1638    Ok(PackageRef {
1639        name: p.package.clone(),
1640        version: p.version.clone(),
1641        url: join_url(base, &p.filename)?,
1642        alternate_urls: Vec::new(),
1643        sha256: p.sha256.clone(),
1644        size: p.size,
1645    })
1646}
1647
1648/// Build a DDEB reference with Launchpad's primary-archive file store as an
1649/// independent download origin. Both URLs are accepted only for bytes matching
1650/// the DDEB index's exact SHA256 and size.
1651fn ubuntu_ddeb_package_ref(p: &DebPkg) -> Result<PackageRef> {
1652    let mut package = deb_package_ref(p, UBUNTU_DDEBS)?;
1653    let filename = p
1654        .filename
1655        .rsplit('/')
1656        .next()
1657        .filter(|filename| filename.ends_with(".ddeb"))
1658        .ok_or_else(|| anyhow!("Ubuntu dbgsym has invalid Filename: {}", p.filename))?;
1659    let launchpad_url = join_url(LAUNCHPAD_PRIMARY_FILES, filename)?;
1660    if launchpad_url != package.url {
1661        package.alternate_urls.push(launchpad_url);
1662    }
1663    Ok(package)
1664}
1665
1666const AL2023_MIRROR: &str = "https://cdn.amazonlinux.com/al2023/core/mirrors/latest";
1667
1668/// The AL2023 kernel-stream family a package name belongs to: the
1669/// default `kernel` (6.1) stream or a versioned `kernel<MAJ>.<MIN>`
1670/// stream (`kernel6.12`, `kernel6.18`), each with a `-modules-extra`
1671/// subpackage. Returns `Some(stream)` for the bare stream package and
1672/// its modules-extra, `None` for every other kernel-adjacent name
1673/// (`-devel`, `-headers`, `-tools`, `-libbpf*`, `-livepatch-*`,
1674/// `-modules-extra-common`, …).
1675fn al2023_stream(name: &str) -> Option<&str> {
1676    let stream = name.strip_suffix("-modules-extra").unwrap_or(name);
1677    let rest = stream.strip_prefix("kernel")?;
1678    if rest.is_empty() {
1679        return Some(stream);
1680    }
1681    let digits = |s: &str| !s.is_empty() && s.bytes().all(|b| b.is_ascii_digit());
1682    let (major, minor) = rest.split_once('.')?;
1683    (digits(major) && digits(minor)).then_some(stream)
1684}
1685
1686/// Pick the AL2023 stream with the newest kernel, as `(stream, evr)`.
1687/// Selection is two-level: WITHIN a stream, the newest build by full
1688/// RPM EVR (epoch included — the live repo carries epoch 0 and 1
1689/// builds under one stream name); ACROSS streams, by the kernel
1690/// version alone (`rpmvercmp` on `ver`: `6.18.36` > `6.1.176`).
1691/// Epoch and release only order builds of the SAME package name, so
1692/// letting a whole-EVR compare span streams would let an epoch bump
1693/// in an old stream outrank a newer stream's kernel.
1694fn al2023_pick_stream(cands: &[RpmCand]) -> Option<(&str, Evr)> {
1695    let streams: std::collections::BTreeSet<&str> = cands
1696        .iter()
1697        .filter(|c| al2023_stream(&c.name) == Some(c.name.as_str()))
1698        .map(|c| c.name.as_str())
1699        .collect();
1700    streams
1701        .into_iter()
1702        .filter_map(|s| newest_evr(cands, s).map(|evr| (s, evr)))
1703        .max_by(|(_, a), (_, b)| rpmvercmp(&a.ver, &b.ver).then_with(|| a.cmp(b)))
1704}
1705
1706fn resolve_amazonlinux(_release: Option<&str>, arch: &str) -> Result<ResolvedDistroKernel> {
1707    // AL2023 is a single rolling stream; `release` (Some("2023")/None)
1708    // always resolves to the latest dated build.
1709    let core_base = al2023_repo_base(&format!("{AL2023_MIRROR}/{arch}/mirror.list"))?;
1710    // Resolve every kernel stream (`kernel`, `kernel6.12`, `kernel6.18`,
1711    // …) plus each stream's `-modules-extra` subpackage — which carries
1712    // `virtio_console.ko`, without which ktstr's console cannot come up
1713    // — and pick the stream with the newest kernel. Both packages are
1714    // strict: a stream missing its modules-extra at the kernel's exact
1715    // EVR cannot boot under ktstr.
1716    let cands = fetch_repo_candidates_where(&core_base, |n| al2023_stream(n).is_some())?;
1717    let (stream, target) = al2023_pick_stream(&cands)
1718        .ok_or_else(|| anyhow!("no kernel stream package in AL2023 {arch} repo"))?;
1719    let extra = format!("{stream}-modules-extra");
1720    let pkg_names = [stream, extra.as_str()];
1721    let packages = build_package_set(&cands, &core_base, &pkg_names, &target, true)?;
1722
1723    let debug_base = al2023_repo_base(&format!("{AL2023_MIRROR}/debuginfo/{arch}/mirror.list"))?;
1724    // `<stream>-debuginfo` alone carries the complete vmlinux
1725    // (`/usr/lib/debug/lib/modules/<rel>/vmlinux`). The sibling
1726    // `-debuginfo-common-{arch}` is deliberately NOT fetched: it only
1727    // adds `/usr/src/debug` sources, plus a second
1728    // `<rel>.microvm/vmlinux.debug` flavor tree (verified against the
1729    // live filelists) that would make the extracted packages disagree
1730    // on the kernel release.
1731    let dbg = format!("{stream}-debuginfo");
1732    let debug_names = [dbg.as_str()];
1733    let debug_cands = fetch_repo_candidates(&debug_base, &debug_names)?;
1734    let debuginfo = build_package_set(&debug_cands, &debug_base, &debug_names, &target, true)?;
1735
1736    Ok(ResolvedDistroKernel {
1737        distro: "al2023".to_string(),
1738        kernel_release: target.display(),
1739        arch: arch.to_string(),
1740        packages,
1741        debuginfo,
1742    })
1743}
1744
1745fn al2023_repo_base(mirror_url: &str) -> Result<String> {
1746    let list = crate::fetch::fetch_metadata_text(mirror_url, "fetch")?;
1747    parse_mirror_list(&list).ok_or_else(|| anyhow!("empty mirror.list at {mirror_url}"))
1748}
1749
1750const STEAMOS_MIRROR: &str = "https://steamdeck-packages.steamos.cloud/archlinux-mirror/";
1751
1752/// One package parsed out of a pacman repo database's `desc` file.
1753#[derive(Clone, Debug, PartialEq, Eq)]
1754struct PacmanPkg {
1755    name: String,
1756    version: String,
1757    filename: String,
1758    sha256: String,
1759    csize: Option<u64>,
1760    arch: String,
1761}
1762
1763/// Parse a pacman repo database — a (compressed) tar whose
1764/// `<name>-<version>/desc` members carry `%FIELD%\n<value>` records —
1765/// into package rows. Fields the resolver does not consume are skipped.
1766fn parse_pacman_db<R: Read>(reader: R) -> Result<Vec<PacmanPkg>> {
1767    let mut archive = tar::Archive::new(reader);
1768    let mut out = Vec::new();
1769    for entry in archive.entries().with_context(|| "read pacman db tar")? {
1770        let mut entry = entry.with_context(|| "read pacman db entry")?;
1771        let path = entry.path().with_context(|| "pacman db entry path")?;
1772        if path.file_name().and_then(|n| n.to_str()) != Some("desc") {
1773            continue;
1774        }
1775        let mut text = String::new();
1776        entry
1777            .read_to_string(&mut text)
1778            .with_context(|| "read pacman desc")?;
1779        out.push(parse_pacman_desc(&text));
1780    }
1781    Ok(out)
1782}
1783
1784/// Parse one `desc` file: `%FIELD%` header lines each followed by the
1785/// field's value line(s); the resolver's fields are all single-line.
1786fn parse_pacman_desc(text: &str) -> PacmanPkg {
1787    let mut pkg = PacmanPkg {
1788        name: String::new(),
1789        version: String::new(),
1790        filename: String::new(),
1791        sha256: String::new(),
1792        csize: None,
1793        arch: String::new(),
1794    };
1795    let mut lines = text.lines();
1796    while let Some(line) = lines.next() {
1797        let field = line.trim();
1798        if !(field.starts_with('%') && field.ends_with('%')) {
1799            continue;
1800        }
1801        let Some(value) = lines.next().map(str::trim) else {
1802            break;
1803        };
1804        match field {
1805            "%NAME%" => pkg.name = value.to_string(),
1806            "%VERSION%" => pkg.version = value.to_string(),
1807            "%FILENAME%" => pkg.filename = value.to_string(),
1808            "%SHA256SUM%" => pkg.sha256 = value.to_string(),
1809            "%CSIZE%" => pkg.csize = value.parse().ok(),
1810            "%ARCH%" => pkg.arch = value.to_string(),
1811            _ => {}
1812        }
1813    }
1814    pkg
1815}
1816
1817/// Wrap a downloaded pacman `.db` in the decompressor its leading
1818/// magic implies. Valve's live databases are xz tars
1819/// (`jupiter-3.8.db`); gzip and zstd are accepted for robustness
1820/// against a repo-tooling change, plain tar as the last resort.
1821fn decompress_pacman_db(bytes: &[u8]) -> Result<Box<dyn Read + '_>> {
1822    let cursor = Cursor::new(bytes);
1823    if bytes.starts_with(&[0xfd, 0x37, 0x7a, 0x58, 0x5a]) {
1824        Ok(Box::new(xz2::read::XzDecoder::new(cursor)))
1825    } else if bytes.starts_with(&[0x1f, 0x8b]) {
1826        Ok(Box::new(flate2::read::GzDecoder::new(cursor)))
1827    } else if bytes.starts_with(&[0x28, 0xb5, 0x2f, 0xfd]) {
1828        Ok(Box::new(
1829            zstd::Decoder::new(cursor).with_context(|| "init zstd decoder")?,
1830        ))
1831    } else {
1832        Ok(Box::new(cursor))
1833    }
1834}
1835
1836/// The SteamOS kernel-package family a pacman package name belongs to:
1837/// the legacy `linux-neptune` (5.13) or a versioned
1838/// `linux-neptune-<digits>` series (`linux-neptune-618`). Returns
1839/// `None` for every other neptune-adjacent name (`-headers`, `-devel`,
1840/// `-kasan`, `-drm-exec`, `-rtw-debug`, …).
1841fn steamos_kernel_series(name: &str) -> Option<&str> {
1842    let rest = name.strip_prefix("linux-neptune")?;
1843    if rest.is_empty() {
1844        return Some(name);
1845    }
1846    let digits = rest.strip_prefix('-')?;
1847    (!digits.is_empty() && digits.bytes().all(|b| b.is_ascii_digit())).then_some(name)
1848}
1849
1850/// Highest version-numbered `jupiter-<MAJOR.MINOR>` channel in the
1851/// mirror's top-level listing. Point/suffix channels (`jupiter-3.3.1`,
1852/// `jupiter-3.8.1x`) and the non-numeric channels (`-rel`, `-main`,
1853/// `-staging`, `-ci-test`) are skipped — see the module docs for why
1854/// the numbered trains are the selection axis.
1855fn steamos_latest_channel(listing_html: &str) -> Option<String> {
1856    listing_html
1857        .split("href=\"")
1858        .skip(1)
1859        .filter_map(|rest| rest.split_once('"').map(|(href, _)| href))
1860        .filter_map(|href| href.strip_suffix('/'))
1861        .filter_map(|dir| dir.strip_prefix("jupiter-"))
1862        .filter_map(|ver| {
1863            let (maj, min) = ver.split_once('.')?;
1864            let digits = |s: &str| !s.is_empty() && s.bytes().all(|b| b.is_ascii_digit());
1865            (digits(maj) && digits(min))
1866                .then(|| (maj.parse::<u32>().ok(), min.parse::<u32>().ok(), ver))
1867        })
1868        .filter_map(|(maj, min, ver)| Some((maj?, min?, ver)))
1869        .max_by_key(|(maj, min, _)| (*maj, *min))
1870        .map(|(_, _, ver)| ver.to_string())
1871}
1872
1873/// Pick the newest kernel among the `linux-neptune*` series rows: by
1874/// kernel version (`rpmvercmp` on the pkgver before the `-pkgrel`,
1875/// e.g. `6.18.33.valve2` > `6.16.12.valve24.2`), tying back to the
1876/// full version string for determinism. Same cross-series principle as
1877/// [`al2023_pick_stream`]: only the kernel version orders different
1878/// package names.
1879fn steamos_pick_kernel(pkgs: &[PacmanPkg]) -> Option<&PacmanPkg> {
1880    let pkgver = |v: &str| {
1881        v.rsplit_once('-')
1882            .map_or_else(|| v.to_string(), |(v, _)| v.to_string())
1883    };
1884    pkgs.iter()
1885        .filter(|p| steamos_kernel_series(&p.name).is_some())
1886        .max_by(|a, b| {
1887            rpmvercmp(&pkgver(&a.version), &pkgver(&b.version))
1888                .then_with(|| rpmvercmp(&a.version, &b.version))
1889        })
1890}
1891
1892fn resolve_steamos(release: Option<&str>, arch: &str) -> Result<ResolvedDistroKernel> {
1893    if arch != "x86_64" {
1894        bail!(
1895            "SteamOS kernels are published for x86_64 only \
1896             (Valve's mirror has no {arch} packages)"
1897        );
1898    }
1899    let channel_ver = match release {
1900        Some(r) => r.to_string(),
1901        None => {
1902            let listing = crate::fetch::fetch_metadata_text(STEAMOS_MIRROR, "fetch")?;
1903            steamos_latest_channel(&listing).ok_or_else(|| {
1904                anyhow!("no jupiter-<MAJOR.MINOR> channel found under {STEAMOS_MIRROR}")
1905            })?
1906        }
1907    };
1908    let channel = format!("jupiter-{channel_ver}");
1909    let base = format!("{STEAMOS_MIRROR}{channel}/os/{arch}/");
1910    let db_url = format!("{base}{channel}.db");
1911    let db = crate::fetch::fetch_metadata_bytes(&db_url, "fetch")?;
1912    let pkgs = parse_pacman_db(decompress_pacman_db(&db)?)
1913        .with_context(|| format!("parse pacman db {db_url}"))?;
1914    let kernel = steamos_pick_kernel(&pkgs)
1915        .ok_or_else(|| anyhow!("no linux-neptune kernel package in {channel}"))?;
1916    if kernel.arch != arch {
1917        bail!(
1918            "{} in {channel} declares arch {} (expected {arch})",
1919            kernel.name,
1920            kernel.arch
1921        );
1922    }
1923    let packages = vec![PackageRef {
1924        name: kernel.name.clone(),
1925        version: kernel.version.clone(),
1926        url: format!("{base}{}", kernel.filename),
1927        alternate_urls: Vec::new(),
1928        sha256: kernel.sha256.clone(),
1929        size: kernel.csize,
1930    }];
1931
1932    Ok(ResolvedDistroKernel {
1933        distro: format!("steamos{channel_ver}"),
1934        kernel_release: kernel.version.clone(),
1935        arch: arch.to_string(),
1936        packages,
1937        // Valve publishes no debug packages for linux-neptune (the
1938        // mirror's *-debug-* repos only carry Arch's own core/extra
1939        // split), so SteamOS is exempt from the mandatory-debuginfo
1940        // policy; acquisition warns about the degraded features.
1941        debuginfo: Vec::new(),
1942    })
1943}
1944
1945#[cfg(test)]
1946mod tests;