polyc_runtime/

release_manifest.rs

//! The release digest manifest (`release-images.yaml`).
//!
//! Schema, parsing, and the shared digest-resolution precedence rule for
//! `polychrome upgrade --cluster` and the control-plane operator-mailbox
//! originator.
//!
//! `.github/workflows/publish.yml`'s `channel` job writes one
//! `release-images.yaml` per tagged release (via `scripts/make_channel.sh`),
//! records it alongside a versioned Kustomize channel under
//! `manifests/channels/<tag>/`, and attaches it to the GitHub Release as an
//! asset. This module is the *reader*: [`fetch`] downloads and
//! [`parse_and_validate`] checks it, and [`resolve_release_digests`]
//! implements the one digest-source precedence rule both binaries share —
//! see `docs/deploy/digest-pinning.md` for the operator-facing walkthrough.
//!
//! # Format versioning — refuse, never degrade
//!
//! The manifest carries `format_version` so a future breaking schema change
//! is *detectable*. Polychrome ships zero cross-version compatibility code
//! (the standing no-legacy rule): [`parse_and_validate`] refuses any
//! `format_version` other than [`FORMAT_VERSION`] outright rather than
//! attempting a downgrade-safe read. There is no support window — a format
//! bump means updating the CLI before the next cluster upgrade, exactly like
//! every other wire-format change in this repo.
//!
//! # Digest-source precedence
//!
//! [`resolve_release_digests`] resolves each published component's digest by,
//! per component:
//!
//! 1. If `POLYCHROME_UPGRADE_IMAGE_<COMPONENT>` overrides the component's
//!    image reference (e.g. a Google Artifact Registry mirror in production),
//!    resolve live against that registry — the release manifest genuinely
//!    doesn't describe an image built and pushed to a different registry, so
//!    this is a distinct scenario, not a fallback.
//! 2. Otherwise (the default public-GHCR reference), require the release
//!    manifest and read the component's digest from it. A release published
//!    before this manifest existed has no asset to read — that is a hard
//!    error naming the release, not a silent fallback to a live registry
//!    resolve (no-legacy rule: no reader degrades to the old behavior).
//!
//! A signed `--digest` set (see `crates/cli/src/cmd/upgrade_cluster.rs`) sits
//! *above* both of these — it is pinned verbatim and never reaches this
//! module at all.

use std::collections::BTreeMap;

use crate::ghcr;

/// The only release-manifest schema version this binary reads. Bump only in
/// lockstep with a `scripts/make_channel.sh` change that writes the new shape
/// — see the module-level "Format versioning" section.
pub const FORMAT_VERSION: u32 = 1;

/// Name of the release asset carrying the manifest, as attached by
/// `.github/workflows/publish.yml`'s `channel` job.
const MANIFEST_ASSET_NAME: &str = "release-images.yaml";

/// One published image's entry in a [`ReleaseManifest`].
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct ManifestImage {
    /// The bare GHCR image name this entry was published under — matches
    /// [`ghcr::Component::ghcr_basename`] for the components the
    /// cluster-upgrade path rolls (e.g. `polychrome`, `polychrome-slack`);
    /// other published images — edges the CLI doesn't yet manage — are
    /// carried too but simply never looked up by name. NOT
    /// [`ghcr::Component::name`], which is a different, CLI-facing
    /// identifier (`control-plane`, `slack`, …) used for the `--digest
    /// <name>=…` argument.
    pub name: String,
    /// Full image reference with no tag, always `ghcr.io/officialunofficial/<name>`
    /// for a genuine entry — validated in [`parse_and_validate`].
    pub image: String,
    /// The image's immutable index digest, `sha256:<64 lowercase hex>`.
    pub digest: String,
}

/// The parsed, `serde`-mapped shape of `release-images.yaml`.
///
/// Use [`parse_and_validate`] rather than deserializing this directly — the
/// raw `serde` mapping alone does not check the format-version, version-match,
/// or per-entry integrity rules the release manifest must satisfy before it's
/// safe to pin a cluster to.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct ReleaseManifest {
    /// Schema version of this document. See the module-level "Format
    /// versioning" section.
    pub format_version: u32,
    /// Release version this manifest was published for, with no leading `v`
    /// (e.g. `2026.8.0`).
    pub version: String,
    /// One entry per image `.github/workflows/publish.yml` publishes.
    pub images: Vec<ManifestImage>,
}

impl ReleaseManifest {
    /// Look up a component's digest by its short stable name
    /// ([`ManifestImage::name`]).
    #[must_use]
    pub fn digest_for(&self, name: &str) -> Option<&str> {
        self.images
            .iter()
            .find(|i| i.name == name)
            .map(|i| i.digest.as_str())
    }
}

/// A release-manifest fetch, parse, or validation failure.
#[derive(Debug, thiserror::Error)]
pub enum ReleaseManifestError {
    /// The manifest's `format_version` is not one this binary understands.
    /// Refuse rather than degrade — see the module-level "Format versioning"
    /// section.
    #[error(
        "this polychrome binary reads release-manifest format {supported}; release {version} \
         publishes format {found} — update the binary, then retry"
    )]
    UnknownFormatVersion {
        /// The `format_version` the manifest actually carries.
        found: u32,
        /// The only `format_version` this binary reads ([`FORMAT_VERSION`]).
        supported: u32,
        /// The release version the manifest was fetched for.
        version: String,
    },
    /// The manifest's `version` field does not match the release it was
    /// fetched for — it was published for a different release than requested
    /// (or was tampered with).
    #[error("release manifest version `{found}` does not match the requested release `{expected}`")]
    VersionMismatch {
        /// The version the caller requested.
        expected: String,
        /// The version the manifest actually declares.
        found: String,
    },
    /// An entry's `image` field is not exactly
    /// `ghcr.io/officialunofficial/<lowercase-name>` — could be a typo, a
    /// different registry/owner entirely, or an uppercase/invalid component
    /// name.
    #[error("component `{name}` names image `{image}`, not `ghcr.io/officialunofficial/{name}`")]
    MalformedImage {
        /// The component name the entry claims.
        name: String,
        /// The image reference the entry actually carries.
        image: String,
    },
    /// An entry's `digest` field is not a `sha256:<64 lowercase hex>` content
    /// address.
    #[error("component `{name}` carries digest `{digest}`, not a sha256:<64-hex> content address")]
    MalformedDigest {
        /// The component the malformed digest belongs to.
        name: String,
        /// The digest string as read from the manifest.
        digest: String,
    },
    /// [`resolve_release_digests`] needed a component's digest from the
    /// manifest, but the manifest carries no entry for it.
    #[error("release manifest is missing component `{0}` — refusing to resolve a partial set")]
    MissingComponent(String),
    /// The release exists but carries no `release-images.yaml` asset — it
    /// predates the digest-manifest channel (#115). Not a fallback case: a
    /// default-GHCR-ref component has nowhere else to resolve its digest from.
    #[error("release `{0}` predates the digest manifest — pick a newer release")]
    AssetMissing(String),
    /// The manifest bytes are not valid YAML, or don't match the expected
    /// shape.
    #[error("release manifest is not valid YAML: {0}")]
    Yaml(#[from] serde_yaml_ng::Error),
    /// The GitHub Releases API request (or the asset download) failed in
    /// transport, or returned a non-success status.
    #[error("release-manifest request failed: {0}")]
    Http(#[from] reqwest::Error),
    /// A component's live-registry resolve failed (the
    /// `POLYCHROME_UPGRADE_IMAGE_*`-overridden path, e.g. Google Artifact
    /// Registry in production).
    #[error("live registry resolve failed: {0}")]
    Ghcr(#[from] ghcr::GhcrError),
}

/// Is `digest` a lowercase `sha256:<64 hex>` content address?
fn is_valid_digest(digest: &str) -> bool {
    digest.strip_prefix("sha256:").is_some_and(|hex| {
        hex.len() == 64
            && hex
                .bytes()
                .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
    })
}

/// Is `name` a valid bare component name (`ghcr.io/officialunofficial/<name>`'s
/// path segment) — lowercase ASCII letters, digits, and hyphens only?
fn is_valid_component_name(name: &str) -> bool {
    !name.is_empty()
        && name
            .bytes()
            .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
}

/// Parse `release-images.yaml` bytes and validate every integrity rule a
/// manifest must satisfy before any of its digests are safe to pin a cluster
/// to.
///
/// Checks, in order: the schema version is [`FORMAT_VERSION`]; the declared
/// `version` matches `expected_version` (no leading `v` on either side); every
/// entry's `image` is exactly `ghcr.io/officialunofficial/<name>` with a valid
/// lowercase `name`; every entry's `digest` is a `sha256:<64-hex>` content
/// address. All fail closed, naming the offending component/entry.
///
/// # Errors
///
/// Returns [`ReleaseManifestError::Yaml`] if `bytes` isn't valid YAML matching
/// the manifest shape, [`ReleaseManifestError::UnknownFormatVersion`],
/// [`ReleaseManifestError::VersionMismatch`],
/// [`ReleaseManifestError::MalformedImage`], or
/// [`ReleaseManifestError::MalformedDigest`] for the corresponding validation
/// failure.
pub fn parse_and_validate(
    bytes: &[u8],
    expected_version: &str,
) -> Result<ReleaseManifest, ReleaseManifestError> {
    let manifest: ReleaseManifest = serde_yaml_ng::from_slice(bytes)?;
    if manifest.format_version != FORMAT_VERSION {
        return Err(ReleaseManifestError::UnknownFormatVersion {
            found: manifest.format_version,
            supported: FORMAT_VERSION,
            version: expected_version.to_owned(),
        });
    }
    if manifest.version != expected_version {
        return Err(ReleaseManifestError::VersionMismatch {
            expected: expected_version.to_owned(),
            found: manifest.version,
        });
    }
    for entry in &manifest.images {
        let expected_image = format!("ghcr.io/officialunofficial/{}", entry.name);
        if !is_valid_component_name(&entry.name) || entry.image != expected_image {
            return Err(ReleaseManifestError::MalformedImage {
                name: entry.name.clone(),
                image: entry.image.clone(),
            });
        }
        if !is_valid_digest(&entry.digest) {
            return Err(ReleaseManifestError::MalformedDigest {
                name: entry.name.clone(),
                digest: entry.digest.clone(),
            });
        }
    }
    Ok(manifest)
}

/// Fetch and validate the release manifest for `release_tag` (the GitHub tag
/// name, e.g. `v2026.8.0`) from `{base_url}/repos/{owner}/{repo}`.
///
/// Mirrors the asset-download shape `crates/cli/src/cmd/upgrade.rs` already
/// uses for the CLI's own self-update path: `GET
/// /repos/{owner}/{repo}/releases/tags/{tag}`, find the
/// `release-images.yaml` asset, then `GET` its API asset URL with `Accept:
/// application/octet-stream` (the GitHub API's download-bytes contract for a
/// release asset).
///
/// # Errors
///
/// Returns [`ReleaseManifestError::Http`] if the release lookup or asset
/// download fails in transport or returns a non-success status,
/// [`ReleaseManifestError::AssetMissing`] if the release carries no
/// `release-images.yaml` asset, or any [`parse_and_validate`] validation
/// error.
pub async fn fetch(
    client: &reqwest::Client,
    base_url: &str,
    owner: &str,
    repo: &str,
    release_tag: &str,
    expected_version: &str,
) -> Result<ReleaseManifest, ReleaseManifestError> {
    let url = format!("{base_url}/repos/{owner}/{repo}/releases/tags/{release_tag}");
    let user_agent = concat!("polychrome/", env!("CARGO_PKG_VERSION"));
    let release: serde_json::Value = client
        .get(&url)
        .header(reqwest::header::USER_AGENT, user_agent)
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;
    let asset_url = release["assets"]
        .as_array()
        .into_iter()
        .flatten()
        .find(|asset| asset["name"].as_str() == Some(MANIFEST_ASSET_NAME))
        .and_then(|asset| asset["url"].as_str())
        .map(str::to_owned)
        .ok_or_else(|| ReleaseManifestError::AssetMissing(release_tag.to_owned()))?;
    let bytes = client
        .get(&asset_url)
        .header(reqwest::header::USER_AGENT, user_agent)
        .header(reqwest::header::ACCEPT, "application/octet-stream")
        .send()
        .await?
        .error_for_status()?
        .bytes()
        .await?;
    parse_and_validate(&bytes, expected_version)
}

/// Resolve every published [`ghcr::Component`]'s target digest for `version`.
///
/// Applies the module's digest-source precedence: a component whose image
/// reference is overridden by its `POLYCHROME_UPGRADE_IMAGE_*` environment
/// variable is resolved live against that registry; every other component
/// (the default public-GHCR reference) is resolved from the release manifest,
/// fetched once and only if at least one component needs it.
///
/// `env_lookup` is injected (not read from the process) so the decision of
/// *which* components need the manifest at all is exercised without a real
/// environment; production callers pass `|k| std::env::var(k).ok()`.
///
/// Shared by the CLI's `upgrade --cluster` executor
/// (`crates/cli/src/cmd/upgrade_cluster.rs`) and the control plane's
/// operator-mailbox originator (`crates/control-plane/src/originator.rs`), so
/// the ask a mailbox item opens with and the digests the executor ultimately
/// pins are resolved by the exact same rule.
///
/// # Errors
///
/// Returns [`ReleaseManifestError::Ghcr`] if a `POLYCHROME_UPGRADE_IMAGE_*`-
/// overridden component's live registry resolve fails, or any [`fetch`] /
/// [`parse_and_validate`] error (including
/// [`ReleaseManifestError::MissingComponent`] if the fetched manifest omits a
/// component this binary still needs from it).
pub async fn resolve_release_digests<F>(
    client: &reqwest::Client,
    base_url: &str,
    owner: &str,
    repo: &str,
    version: &str,
    env_lookup: F,
) -> Result<BTreeMap<&'static str, String>, ReleaseManifestError>
where
    F: Fn(&str) -> Option<String> + Copy,
{
    let image_tag = ghcr::image_tag_for_version(version)?;
    let release_tag = format!("v{image_tag}");

    let manifest_needed = ghcr::COMPONENTS
        .iter()
        .any(|c| env_lookup(c.image_env).is_none());
    let manifest = if manifest_needed {
        Some(fetch(client, base_url, owner, repo, &release_tag, &image_tag).await?)
    } else {
        None
    };

    let mut digests = BTreeMap::new();
    for component in &ghcr::COMPONENTS {
        let digest = if env_lookup(component.image_env).is_some() {
            let image = ghcr::image_ref(component, env_lookup);
            ghcr::resolve_digest(client, &image.registry, &image.repository, &image_tag).await?
        } else {
            // The manifest is keyed by the actual published GHCR basename
            // (`ghcr_basename`), not `component.name` — see
            // `ghcr::Component::ghcr_basename`'s doc for why these differ.
            manifest
                .as_ref()
                .and_then(|m| m.digest_for(component.ghcr_basename()))
                .ok_or_else(|| {
                    ReleaseManifestError::MissingComponent(component.ghcr_basename().to_owned())
                })?
                .to_owned()
        };
        digests.insert(component.name, digest);
    }
    Ok(digests)
}

#[cfg(test)]
mod tests {
    #![allow(clippy::pedantic, clippy::nursery)]

    use super::*;

    /// A hand-written manifest literal (not round-tripped through
    /// `serde_yaml_ng::to_string`) — cross-checks the real on-disk shape
    /// `scripts/make_channel.sh` writes, independent of how this crate's own
    /// serializer would format it. Named `polychrome` (not `control-plane`)
    /// deliberately: that's the real published GHCR basename
    /// (`ghcr::Component::ghcr_basename`), the key `make_channel.sh` actually
    /// writes entries under.
    fn literal_yaml(digest: &str) -> String {
        format!(
            "format_version: 1\n\
             version: 2026.8.0\n\
             images:\n\
             \x20\x20- name: polychrome\n\
             \x20\x20\x20\x20image: ghcr.io/officialunofficial/polychrome\n\
             \x20\x20\x20\x20digest: {digest}\n"
        )
    }

    fn digest64(byte: char) -> String {
        format!("sha256:{}", byte.to_string().repeat(64))
    }

    /// Uses the real published GHCR basenames (`polychrome`,
    /// `polychrome-slack`) as entry names, not `ghcr::Component::name`
    /// (`control-plane`, `slack`) — see [`literal_yaml`].
    fn sample_manifest() -> ReleaseManifest {
        ReleaseManifest {
            format_version: FORMAT_VERSION,
            version: "2026.8.0".to_owned(),
            images: vec![
                ManifestImage {
                    name: "polychrome".to_owned(),
                    image: "ghcr.io/officialunofficial/polychrome".to_owned(),
                    digest: digest64('1'),
                },
                ManifestImage {
                    name: "polychrome-slack".to_owned(),
                    image: "ghcr.io/officialunofficial/polychrome-slack".to_owned(),
                    digest: digest64('2'),
                },
            ],
        }
    }

    fn to_yaml(manifest: &ReleaseManifest) -> String {
        serde_yaml_ng::to_string(manifest).unwrap()
    }

    #[test]
    fn valid_manifest_parses() {
        let manifest = sample_manifest();
        let yaml = to_yaml(&manifest);
        let parsed = parse_and_validate(yaml.as_bytes(), "2026.8.0").expect("valid manifest");
        assert_eq!(parsed, manifest);
        assert_eq!(
            parsed.digest_for("polychrome"),
            Some(digest64('1')).as_deref()
        );
        assert_eq!(parsed.digest_for("nope"), None);
    }

    #[test]
    fn unknown_format_version_is_refused() {
        let mut manifest = sample_manifest();
        manifest.format_version = 2;
        let yaml = to_yaml(&manifest);
        let err = parse_and_validate(yaml.as_bytes(), "2026.8.0").expect_err("must refuse");
        let msg = err.to_string();
        assert!(msg.contains("format 1"), "{msg}");
        assert!(msg.contains("format 2"), "{msg}");
        assert!(matches!(
            err,
            ReleaseManifestError::UnknownFormatVersion {
                found: 2,
                supported: 1,
                ..
            }
        ));
    }

    #[test]
    fn version_mismatch_is_rejected() {
        let manifest = sample_manifest();
        let yaml = to_yaml(&manifest);
        let err = parse_and_validate(yaml.as_bytes(), "2026.9.0").expect_err("must reject");
        assert!(matches!(err, ReleaseManifestError::VersionMismatch { .. }));
    }

    #[test]
    fn wrong_repo_owner_is_malformed() {
        let mut manifest = sample_manifest();
        manifest.images[0].image = "ghcr.io/evil/polychrome".to_owned();
        let yaml = to_yaml(&manifest);
        let err = parse_and_validate(yaml.as_bytes(), "2026.8.0").expect_err("must reject");
        assert!(matches!(err, ReleaseManifestError::MalformedImage { .. }));
    }

    #[test]
    fn short_digest_is_malformed() {
        let mut manifest = sample_manifest();
        manifest.images[0].digest = "sha256:abc".to_owned();
        let yaml = to_yaml(&manifest);
        let err = parse_and_validate(yaml.as_bytes(), "2026.8.0").expect_err("must reject");
        assert!(matches!(err, ReleaseManifestError::MalformedDigest { .. }));
    }

    #[test]
    fn uppercase_digest_is_malformed() {
        let mut manifest = sample_manifest();
        manifest.images[0].digest = format!("sha256:{}", "A".repeat(64));
        let yaml = to_yaml(&manifest);
        let err = parse_and_validate(yaml.as_bytes(), "2026.8.0").expect_err("must reject");
        assert!(matches!(err, ReleaseManifestError::MalformedDigest { .. }));
    }

    #[test]
    fn non_sha256_digest_is_malformed() {
        let mut manifest = sample_manifest();
        manifest.images[0].digest = format!("sha512:{}", "1".repeat(64));
        let yaml = to_yaml(&manifest);
        let err = parse_and_validate(yaml.as_bytes(), "2026.8.0").expect_err("must reject");
        assert!(matches!(err, ReleaseManifestError::MalformedDigest { .. }));
    }

    #[test]
    fn missing_component_is_named() {
        let manifest = sample_manifest();
        assert_eq!(manifest.digest_for("polychrome-telegram"), None);
    }

    #[test]
    fn literal_manifest_yaml_parses() {
        let digest = digest64('1');
        let parsed =
            parse_and_validate(literal_yaml(&digest).as_bytes(), "2026.8.0").expect("valid");
        assert_eq!(parsed.format_version, 1);
        assert_eq!(parsed.digest_for("polychrome"), Some(digest.as_str()));
    }
}