zlayer_toolchain/

coverage.rs

//! Toolchain build-coverage recording (writes) + advisory coverage-map reads.
//!
//! **Writes** go to the package index: `POST {base}/v1/coverage` (base =
//! `ZLAYER_PACKAGE_INDEX_URL`, default `https://packages.zlayer.dev`), where the
//! body is a single JSON [`CoverageRecord`] signed with the same reposync HMAC
//! scheme as every other index write — `x-reposync-signature: sha256=<hex>` over
//! the exact raw body bytes, via [`crate::package_index::sign`]. The server
//! upserts keyed `(tool, platform, arch)` and batch-pushes per-arch maps to
//! `RepoSources`.
//!
//! **Reads** never hit the worker: consumers GET the static Pages artifact
//! `https://zachhandley.github.io/RepoSources/coverage/{platform}_{arch}.json`
//! ([`fetch_coverage_map`]), which lags writes by a Pages build. Coverage is
//! purely advisory — the toolchain always retains its build-it-yourself
//! fallback, so a stale/missing map is never an error for provisioning itself.
//!
//! Recording ([`record`]) is **best-effort by construction**: it returns `()`,
//! not a `Result`, so a caller physically cannot fail a resolve on it. A
//! missing secret, transport error, or non-2xx response produces exactly one
//! `warn!` and nothing else.
//!
//! Token conventions (kept consistent with the rest of the crate):
//! - `platform` is the lockfile/manifest token `"macos"` / `"windows"` —
//!   `platform_token()` in `lib.rs` (`ToolPlatform::MacOS => "macos"`).
//! - `arch` is the toolchain cache-key token `"arm64"` / `"x86_64"` —
//!   `arch_token()` in `lib.rs` and `windows_arch_token()` in `windows.rs`.
//!   NOT the vendor-download alias `"amd64"` (`vendor_arch()` is documented as
//!   a download-URL-only mapping for the prebuilt resolvers).

use std::collections::HashMap;
use std::time::Duration;

use serde::{Deserialize, Serialize};
use tracing::{debug, warn};

use crate::error::{Result, ToolchainError};
use zlayer_types::package_index::PackageIndexConfig;

/// The default tool set the `seed` command builds coverage for: the C-toolchain
/// substrate most Homebrew source builds bottom out on.
///
/// Note: `protoc` is `protobuf`'s binary — the seed command surfaces the alias
/// (a user asking for `protoc` seeds/reads the `protobuf` coverage row).
pub const SEED_TOOLS: &[&str] = &[
    "protobuf",
    "cmake",
    "ninja",
    "pkgconf",
    "jq",
    "git",
    "autoconf",
    "automake",
    "libtool",
    "gettext",
    "pcre2",
    "oniguruma",
    "openssl@3",
    "zstd",
    "xz",
];

/// Runtime environment variable carrying the reposync HMAC secret. Takes
/// precedence over the compile-time `option_env!` bake so the secret can be
/// rotated without rebuilding the binary.
pub const REPOSYNC_HMAC_SECRET_ENV: &str = "ZLAYER_REPOSYNC_HMAC_SECRET";

/// Compile-time reposync HMAC secret bake (same bake `package_index.rs` uses;
/// absent in most builds). The runtime env var wins when both are present.
const REPOSYNC_HMAC_SECRET_BAKED: Option<&str> = option_env!("ZLAYER_REPOSYNC_HMAC_SECRET");

/// The header carrying the reposync HMAC signature. Mirrors the (private)
/// constant in `package_index.rs` — same header, same `sha256=<hex>` value
/// shape, verified by the server's existing `hmacPost` wrapper.
const REPOSYNC_SIGNATURE_HEADER: &str = "x-reposync-signature";

/// Static GitHub Pages base serving the per-arch advisory coverage maps.
const COVERAGE_PAGES_BASE: &str = "https://zachhandley.github.io/RepoSources/coverage";

/// Outcome of a toolchain provisioning attempt, as recorded in coverage.
///
/// Serializes `snake_case` (`"built"` / `"failed"` / `"net_fallback"`) — the
/// server contract and the token stored in the Pages maps.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CoverageStatus {
    /// The toolchain built (or restored from registry) successfully.
    Built,
    /// The build failed; `error_tail` carries the log tail for triage.
    Failed,
    /// Provisioning succeeded only via the loud full-network fallback
    /// (`NetPolicy::AllowLoud`) — coverage exists but is not hermetic.
    NetFallback,
}

/// One coverage row: how provisioning `tool` went on `(platform, arch)`.
///
/// This is the exact wire shape sent (POST) to `/v1/coverage` (single record; the
/// server accepts single or batch — we send single).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CoverageRecord {
    /// Formula/tool name (e.g. `"protobuf"` — `protoc` is its binary).
    pub tool: String,
    /// Platform token: `"macos"` | `"windows"` (matches `platform_token()` /
    /// the lockfile `platform` key).
    pub platform: String,
    /// Arch token: `"arm64"` | `"x86_64"` (matches `arch_token()` /
    /// `windows_arch_token()` cache-key tokens; never the vendor `"amd64"`).
    pub arch: String,
    /// Provisioning outcome.
    pub status: CoverageStatus,
    /// Resolved tool version (e.g. `"1.8.2"`).
    pub version: String,
    /// OCI reference the built toolchain was published under, when any.
    #[serde(default)]
    pub registry_ref: String,
    /// Digest of the published toolchain artifact, when any.
    #[serde(default)]
    pub registry_digest: String,
    /// Tail of the build log on failure (`ContainerBuildReport::log_tail`).
    #[serde(default)]
    pub error_tail: String,
    /// ISO-8601 / RFC3339 UTC timestamp — generate with [`now_rfc3339`].
    pub recorded_at: String,
}

/// A per-arch coverage map as served by the `RepoSources` Pages artifact
/// (`coverage/{platform}_{arch}.json`): `{metadata: {...}, tools: {...}}`.
///
/// Permissive by design (advisory read): unknown fields are ignored, missing
/// fields default, and `metadata` stays untyped JSON so a map-format evolution
/// never breaks a reader.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct CoverageMap {
    /// Free-form map metadata (platform/arch/generated-at/…); shape is owned
    /// by the `RepoSources` publisher, so it is deliberately untyped.
    #[serde(default)]
    pub metadata: serde_json::Value,
    /// Per-tool coverage entries, keyed by formula/tool name.
    #[serde(default)]
    pub tools: HashMap<String, CoverageEntry>,
}

/// One tool's entry inside a [`CoverageMap`].
///
/// `status` is kept as a plain string (values match the [`CoverageStatus`]
/// `snake_case` tokens) so an unknown future token degrades to data, not a
/// parse error — the map is advisory.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct CoverageEntry {
    /// Resolved tool version.
    #[serde(default)]
    pub version: String,
    /// Coverage status token (`"built"` / `"failed"` / `"net_fallback"`).
    #[serde(default)]
    pub status: String,
    /// Which provisioning path produced the coverage (publisher-owned token).
    #[serde(default)]
    pub source: String,
    /// When the row was last upserted (RFC3339).
    #[serde(default)]
    pub updated_at: String,
}

/// Current UTC time as an RFC3339 string — the value for
/// [`CoverageRecord::recorded_at`]. Uses the crate's existing `chrono` dep
/// (the same idiom every manifest/lockfile timestamp in this crate uses).
#[must_use]
pub fn now_rfc3339() -> String {
    chrono::Utc::now().to_rfc3339()
}

/// Best-effort coverage write: POST `rec` (single JSON record) to
/// `{index}/v1/coverage`, HMAC-signed over the exact raw body bytes.
///
/// Returns `()` — deliberately not a `Result` — so it is UNMISTAKABLE that a
/// coverage write can never fail the resolve that triggered it. Every failure
/// path (no secret resolvable, serialization failure, transport error, non-2xx
/// response) emits exactly one `warn!` and returns; a 2xx emits a `debug!`.
pub async fn record(rec: &CoverageRecord) {
    let Some(secret) = resolve_hmac_secret() else {
        warn!(
            tool = %rec.tool,
            "no reposync HMAC secret (env or compile-time bake); skipping coverage record"
        );
        return;
    };

    // Serialize ONCE and sign those exact bytes — the signature must cover the
    // bytes actually sent, byte-for-byte.
    let body = match serde_json::to_vec(rec) {
        Ok(b) => b,
        Err(e) => {
            warn!(tool = %rec.tool, error = %e, "coverage record failed to serialize; skipping");
            return;
        }
    };
    let signature = crate::package_index::sign(&secret, &body);
    let url = coverage_post_url(&PackageIndexConfig::from_env().base_url);

    match http_client()
        .post(&url)
        .header(REPOSYNC_SIGNATURE_HEADER, signature)
        .header(reqwest::header::CONTENT_TYPE, "application/json")
        .body(body)
        .send()
        .await
    {
        Ok(resp) if resp.status().is_success() => {
            debug!(
                tool = %rec.tool,
                platform = %rec.platform,
                arch = %rec.arch,
                status = %resp.status(),
                "recorded toolchain coverage"
            );
        }
        Ok(resp) => {
            let status = resp.status();
            let snippet: String = resp
                .text()
                .await
                .unwrap_or_default()
                .chars()
                .take(200)
                .collect();
            warn!(
                tool = %rec.tool,
                %status,
                body = %snippet,
                "coverage record rejected (non-fatal)"
            );
        }
        Err(e) => {
            warn!(tool = %rec.tool, error = %e, "coverage record failed to send (non-fatal)");
        }
    }
}

/// Fetch the advisory per-arch coverage map from the `RepoSources` Pages
/// artifact (`{pages}/coverage/{platform}_{arch}.json`).
///
/// `platform`/`arch` take the crate's tokens (`"macos"`/`"windows"`,
/// `"arm64"`/`"x86_64"`). The map lags writes by a Pages build; treat it as a
/// hint, never a gate.
///
/// # Errors
///
/// Returns [`ToolchainError::RegistryError`] on a transport failure, a
/// non-success HTTP status (including 404 — no map published yet for that
/// platform/arch), or an unparseable body.
pub async fn fetch_coverage_map(platform: &str, arch: &str) -> Result<CoverageMap> {
    let url = pages_map_url(platform, arch);
    let resp = http_client()
        .get(&url)
        .send()
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("failed to GET {url}: {e}"),
        })?;
    if !resp.status().is_success() {
        return Err(ToolchainError::RegistryError {
            message: format!("GET {url} returned status {}", resp.status()),
        });
    }
    let bytes = resp
        .bytes()
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("failed to read body from {url}: {e}"),
        })?;
    parse_coverage_map(&bytes).map_err(|e| ToolchainError::RegistryError {
        message: format!("failed to parse coverage map from {url}: {e}"),
    })
}

/// Resolve the reposync HMAC secret: the runtime env var
/// [`REPOSYNC_HMAC_SECRET_ENV`] takes precedence over the compile-time
/// `option_env!` bake (rotation without rebuild). Empty values (either source)
/// count as absent; the env value is trimmed (env files love trailing
/// newlines), the bake is used verbatim.
fn resolve_hmac_secret() -> Option<String> {
    resolve_hmac_secret_from(
        std::env::var(REPOSYNC_HMAC_SECRET_ENV).ok(),
        REPOSYNC_HMAC_SECRET_BAKED,
    )
}

/// Pure core of [`resolve_hmac_secret`] — separated so precedence is testable
/// without racing on process-global env state.
fn resolve_hmac_secret_from(env_value: Option<String>, baked: Option<&str>) -> Option<String> {
    env_value
        .map(|s| s.trim().to_string())
        .filter(|s| !s.is_empty())
        .or_else(|| {
            baked
                .filter(|s| !s.is_empty())
                .map(std::string::ToString::to_string)
        })
}

/// `{base}/v1/coverage` with any trailing slash on `base` trimmed (mirrors
/// `PackageIndexConfig::base()` defensiveness).
fn coverage_post_url(base: &str) -> String {
    format!("{}/v1/coverage", base.trim_end_matches('/'))
}

/// The Pages URL of the per-arch coverage map: `{pages}/{platform}_{arch}.json`.
fn pages_map_url(platform: &str, arch: &str) -> String {
    format!("{COVERAGE_PAGES_BASE}/{platform}_{arch}.json")
}

/// Parse a Pages coverage-map body. Bare JSON (no `{name, data}` envelope —
/// Pages serves the artifact verbatim, unlike the index worker routes).
fn parse_coverage_map(bytes: &[u8]) -> serde_json::Result<CoverageMap> {
    serde_json::from_slice(bytes)
}

/// Short-timeout HTTP client mirroring `package_index.rs`'s construction
/// (same user agent), plus the ~10s cap appropriate for best-effort /
/// advisory calls. Infallible: a builder error falls back to the default
/// client (losing only the timeout), the established idiom in this crate.
fn http_client() -> reqwest::Client {
    reqwest::Client::builder()
        .user_agent("zlayer-toolchain")
        .timeout(Duration::from_secs(10))
        .build()
        .unwrap_or_default()
}

#[cfg(test)]
mod tests {
    use super::*;

    fn sample_record() -> CoverageRecord {
        CoverageRecord {
            tool: "jq".to_string(),
            platform: "macos".to_string(),
            arch: "arm64".to_string(),
            status: CoverageStatus::Built,
            version: "1.8.2".to_string(),
            registry_ref: "forge.blackleafdigital.com/zlayer/toolchains/jq:1.8.2-macos-arm64"
                .to_string(),
            registry_digest: "sha256:abc123".to_string(),
            error_tail: String::new(),
            recorded_at: "2026-07-06T00:00:00+00:00".to_string(),
        }
    }

    // --- secret resolution ---------------------------------------------------

    #[test]
    fn secret_precedence_env_over_baked() {
        // Env wins when both present.
        assert_eq!(
            resolve_hmac_secret_from(Some("from-env".into()), Some("from-bake")).as_deref(),
            Some("from-env"),
        );
        // Env absent -> bake.
        assert_eq!(
            resolve_hmac_secret_from(None, Some("from-bake")).as_deref(),
            Some("from-bake"),
        );
        // Empty/whitespace env counts as absent -> bake.
        assert_eq!(
            resolve_hmac_secret_from(Some("  \n".into()), Some("from-bake")).as_deref(),
            Some("from-bake"),
        );
        // Empty bake counts as absent.
        assert_eq!(resolve_hmac_secret_from(None, Some("")), None);
        // Nothing anywhere.
        assert_eq!(resolve_hmac_secret_from(None, None), None);
        // Env value is trimmed.
        assert_eq!(
            resolve_hmac_secret_from(Some(" s3cret\n".into()), None).as_deref(),
            Some("s3cret"),
        );
    }

    /// Env-facing branch coverage. Kept as ONE test (set + unset asserted
    /// sequentially in the same body) because tests in a binary run in
    /// parallel threads and `REPOSYNC_HMAC_SECRET_ENV` is process-global —
    /// no other test in this crate touches or reads it at runtime (the
    /// `package_index` bake is compile-time), so this cannot race.
    #[test]
    fn resolve_hmac_secret_honors_runtime_env() {
        std::env::set_var(REPOSYNC_HMAC_SECRET_ENV, "runtime-secret-probe");
        // Env set -> env wins regardless of whether a bake exists in this build.
        assert_eq!(
            resolve_hmac_secret().as_deref(),
            Some("runtime-secret-probe")
        );

        std::env::remove_var(REPOSYNC_HMAC_SECRET_ENV);
        // Env absent -> exactly the compile-time bake (None in normal test
        // builds, where the secret is not exported at compile time).
        assert_eq!(
            resolve_hmac_secret(),
            REPOSYNC_HMAC_SECRET_BAKED
                .filter(|s| !s.is_empty())
                .map(str::to_string),
        );
    }

    // --- wire contract ---------------------------------------------------------

    #[test]
    fn status_tokens_are_snake_case() {
        assert_eq!(
            serde_json::to_string(&CoverageStatus::Built).unwrap(),
            "\"built\""
        );
        assert_eq!(
            serde_json::to_string(&CoverageStatus::Failed).unwrap(),
            "\"failed\""
        );
        assert_eq!(
            serde_json::to_string(&CoverageStatus::NetFallback).unwrap(),
            "\"net_fallback\""
        );
        assert_eq!(
            serde_json::from_str::<CoverageStatus>("\"net_fallback\"").unwrap(),
            CoverageStatus::NetFallback
        );
    }

    #[test]
    fn record_serializes_to_server_contract() {
        let v = serde_json::to_value(sample_record()).unwrap();
        assert_eq!(v["tool"], "jq");
        assert_eq!(v["platform"], "macos");
        assert_eq!(v["arch"], "arm64");
        assert_eq!(v["status"], "built");
        assert_eq!(v["version"], "1.8.2");
        assert_eq!(
            v["registry_ref"],
            "forge.blackleafdigital.com/zlayer/toolchains/jq:1.8.2-macos-arm64"
        );
        assert_eq!(v["registry_digest"], "sha256:abc123");
        assert_eq!(v["error_tail"], "");
        assert_eq!(v["recorded_at"], "2026-07-06T00:00:00+00:00");
        // Exactly the nine contract fields — nothing extra sneaks onto the wire.
        assert_eq!(v.as_object().unwrap().len(), 9);
    }

    #[test]
    fn record_round_trips_and_optionals_default() {
        // The three #[serde(default)] fields may be omitted by other writers.
        let rec: CoverageRecord = serde_json::from_str(
            r#"{"tool":"cmake","platform":"windows","arch":"x86_64",
                "status":"failed","version":"4.0.3",
                "recorded_at":"2026-07-06T00:00:00+00:00"}"#,
        )
        .unwrap();
        assert_eq!(rec.status, CoverageStatus::Failed);
        assert_eq!(rec.registry_ref, "");
        assert_eq!(rec.registry_digest, "");
        assert_eq!(rec.error_tail, "");
    }

    // --- signing -----------------------------------------------------------------

    /// [`record`] reuses [`crate::package_index::sign`] directly (single DRY
    /// signer). Cross-check that signer against an independently computed
    /// HMAC-SHA256 over the exact bytes `record` would send.
    #[test]
    fn signing_matches_package_index_sign_for_record_bytes() {
        use hmac::{Hmac, Mac};
        use sha2::Sha256;

        let body = serde_json::to_vec(&sample_record()).unwrap();
        let via_shared_signer = crate::package_index::sign("secret", &body);

        let mut mac = Hmac::<Sha256>::new_from_slice(b"secret").unwrap();
        mac.update(&body);
        let independent = format!("sha256={}", hex::encode(mac.finalize().into_bytes()));

        assert_eq!(via_shared_signer, independent);
    }

    // --- URLs --------------------------------------------------------------------

    #[test]
    fn coverage_post_url_joins_base() {
        assert_eq!(
            coverage_post_url("https://packages.zlayer.dev"),
            "https://packages.zlayer.dev/v1/coverage"
        );
        assert_eq!(
            coverage_post_url("https://packages.zlayer.dev/"),
            "https://packages.zlayer.dev/v1/coverage"
        );
    }

    #[test]
    fn pages_map_url_shape() {
        assert_eq!(
            pages_map_url("macos", "arm64"),
            "https://zachhandley.github.io/RepoSources/coverage/macos_arm64.json"
        );
        assert_eq!(
            pages_map_url("windows", "x86_64"),
            "https://zachhandley.github.io/RepoSources/coverage/windows_x86_64.json"
        );
    }

    // --- Pages map parsing ---------------------------------------------------------

    /// A literal Pages-shaped fixture: `{metadata:{...}, tools:{<tool>:
    /// {version,status,source,updated_at}}}`.
    const PAGES_FIXTURE: &str = r#"{
        "metadata": {
            "platform": "macos",
            "arch": "arm64",
            "generated_at": "2026-07-06T12:00:00Z",
            "tool_count": 2
        },
        "tools": {
            "jq": {
                "version": "1.8.2",
                "status": "built",
                "source": "source_build",
                "updated_at": "2026-07-06T11:58:00Z"
            },
            "cmake": {
                "version": "4.0.3",
                "status": "net_fallback",
                "source": "brew_emulate",
                "updated_at": "2026-07-05T09:00:00Z"
            }
        }
    }"#;

    #[test]
    fn coverage_map_parses_pages_fixture() {
        let map = parse_coverage_map(PAGES_FIXTURE.as_bytes()).unwrap();
        assert_eq!(map.tools.len(), 2);

        let jq = &map.tools["jq"];
        assert_eq!(jq.version, "1.8.2");
        assert_eq!(jq.status, "built");
        assert_eq!(jq.source, "source_build");
        assert_eq!(jq.updated_at, "2026-07-06T11:58:00Z");

        let cmake = &map.tools["cmake"];
        assert_eq!(cmake.status, "net_fallback");

        assert_eq!(map.metadata["platform"], "macos");
        assert_eq!(map.metadata["tool_count"], 2);
    }

    #[test]
    fn coverage_map_is_permissive() {
        // Unknown fields (top-level and per-entry) tolerated; missing entry
        // fields default; unknown status tokens degrade to data.
        let map = parse_coverage_map(
            br#"{"tools":{"git":{"version":"2.55.0","status":"someday","extra":true}},"future_top_level":1}"#,
        )
        .unwrap();
        assert_eq!(map.tools["git"].version, "2.55.0");
        assert_eq!(map.tools["git"].status, "someday");
        assert_eq!(map.tools["git"].source, "");
        assert!(map.metadata.is_null());

        // A bare empty object is a valid (empty) map.
        let empty = parse_coverage_map(b"{}").unwrap();
        assert!(empty.tools.is_empty());

        // Garbage is a parse error, not a husk.
        assert!(parse_coverage_map(b"not json").is_err());
    }

    // --- timestamps -------------------------------------------------------------------

    #[test]
    fn now_rfc3339_parses_back() {
        let ts = now_rfc3339();
        let parsed =
            chrono::DateTime::parse_from_rfc3339(&ts).expect("recorded_at must be valid RFC3339");
        // Sanity: it's UTC "now", not an epoch default.
        assert!(parsed.timestamp() > 1_700_000_000);
    }

    // --- seed set ------------------------------------------------------------------------

    #[test]
    fn seed_tools_shape() {
        assert_eq!(SEED_TOOLS.len(), 15);
        assert!(SEED_TOOLS.contains(&"protobuf"), "protoc's formula");
        assert!(SEED_TOOLS.contains(&"openssl@3"));
        // No accidental duplicates.
        let mut sorted: Vec<_> = SEED_TOOLS.to_vec();
        sorted.sort_unstable();
        sorted.dedup();
        assert_eq!(sorted.len(), SEED_TOOLS.len());
    }
}