holger-server-lib 0.6.9

//! The `Repository` config node and its backend factory — the seam between RON
//! config and a live `RepositoryBackendTrait`.
//!
//! A `Repository` is parsed from RON as inert `ron_*` fields; the wiring engine
//! (`lib::wire_holger`) then calls [`Repository::backend_from_config`] in a
//! second pass to materialize `backend_repository`, dispatching on
//! `ron_repo_type` to the right per-ecosystem backend. The three rust storage
//! flavors are the ones to keep straight: `ron_writable_archive` = live
//! seal-able znippy registry (the /sparring + /cache primary), `ron_archive_path`
//! = read-only drift snapshot, `ron_data_dir` = loose-file dev backend; the
//! `*-remote` types instead build read-only crates.io/Nexus/Artifactory
//! pull-through upstreams. Most ecosystems go through the `znippy_backed!` macro
//! (archive required); npm/nuget/oci are hand-rolled so `ron_base_url` can be
//! threaded into client-facing URLs (packument tarballs, V3 service index).
//!
//! Gotcha: `wired_upstreams`/`wired_storage`/`wired_exposed` are raw pointers
//! filled in *after* the graph is built and pinned — they are `null`/dangling
//! until wiring completes and must never be followed before then.
use std::sync::Arc;
use std::path::PathBuf;
use anyhow::Context;
use serde::{Deserialize, Serialize};
use repository_file_rust::RustRepoFile as RustRepo;
use repository_znippy_rust::RustRepoZnippy;
use repository_znippy_maven::MavenRepoZnippy;
use repository_znippy_python::PipRepoZnippy;
use repository_znippy_npm::NpmRepoZnippy;
use repository_znippy_nuget::NugetRepoZnippy;
use repository_znippy_go::GoRepoZnippy;
use repository_znippy_gem::GemRepoZnippy;
use repository_znippy_deb::DebRepoZnippy;
use repository_znippy_rpm::RpmRepoZnippy;
use repository_znippy_helm::HelmRepoZnippy;
use repository_file_oci::OciRepoFile;
use repository_znippy_docker::DockerRepoZnippy;
use repository_znippy_conda::CondaRepoZnippy;
use repository_znippy_composer::ComposerRepoZnippy;
use repository_znippy_package::ZnippyRepoZnippy;
use traits::{ArtifactFormat, RepositoryBackendTrait, UpstreamAuth};
// The `rust-remote` pull-through upstream is a live `ureq` HTTP client, so it is
// gated behind `online` (like reqwest/ureq themselves). The zero-egress airgap
// tiers (`embedded`/`mini`) omit `online`, do not compile this module, and the
// `rust-remote` repo arm below fails closed instead of reaching for the network.
#[cfg(feature = "online")]
use crate::upstream_rust::RustRegistryUpstream;
use crate::raw::RawBackend;
use crate::{ExposedEndpoint, StorageEndpoint};

/// Build a remote-registry-federation upstream backend (Artifactory · Nexus ·
/// Azure Artifacts · AWS CodeArtifact) by hiring Skidbladnir's harbour clients.
/// Only compiled in the `federation` (`full`) tier.
#[cfg(feature = "federation")]
fn make_remote_upstream(
    kind: &str,
    name: String,
    base: String,
    repo: String,
    auth: UpstreamAuth,
    format: ArtifactFormat,
) -> anyhow::Result<Arc<dyn RepositoryBackendTrait>> {
    use crate::upstream::SkidbladnirUpstream;
    let up = match kind {
        "nexus-remote" => SkidbladnirUpstream::nexus(name, base, repo, auth, format),
        "artifactory-remote" => SkidbladnirUpstream::artifactory(name, base, repo, auth, format),
        "azure-remote" => SkidbladnirUpstream::azure(name, base, repo, auth, format),
        "aws-remote" => SkidbladnirUpstream::aws(name, base, auth, format),
        other => anyhow::bail!("unknown remote upstream kind: {other}"),
    };
    Ok(Arc::new(up))
}

/// `federation`-off fallback: the harbour clients are compiled OUT of the
/// `mini`/`embedded` tiers (they carry no Skidbladnir / registry-client
/// dependency), so a config that asks for a remote upstream fails closed with a
/// clear rebuild hint rather than silently doing nothing.
#[cfg(not(feature = "federation"))]
fn make_remote_upstream(
    kind: &str,
    _name: String,
    _base: String,
    _repo: String,
    _auth: UpstreamAuth,
    _format: ArtifactFormat,
) -> anyhow::Result<Arc<dyn RepositoryBackendTrait>> {
    anyhow::bail!(
        "repository type `{kind}` needs upstream-registry federation, which is compiled OUT of this holger build (the `mini`/`embedded` tiers link no registry clients). Rebuild the `full` tier, e.g. `cargo build -p holger-server-lib --no-default-features --features full`."
    )
}

#[derive(Serialize, Deserialize)]
pub struct Repository {
    // Parsed from RON
    pub ron_name: String,
    pub ron_repo_type: String,        // rust/java/python/raw
    pub ron_upstreams: Vec<String>,   // empty means no upstreams
    pub ron_in: Option<RepositoryIO>,
    pub ron_out: Option<RepositoryIO>,

    /// Member repositories of a **virtual `group`** repo (`ron_repo_type: "group"`).
    /// The group owns no storage; it resolves each request across these members in
    /// declaration order (first hit wins) — the Nexus/Artifactory "group repo".
    /// Only meaningful for the `group` type; empty for every other type.
    #[serde(default)]
    pub ron_members: Vec<String>,

    /// Optional path to a znippy archive (.znippy file)
    #[serde(default)]
    pub ron_archive_path: Option<String>,

    /// Optional storage directory for file-backed (writable) repos.
    /// Defaults to /var/lib/holger/{ron_name} when omitted.
    #[serde(default)]
    pub ron_data_dir: Option<String>,

    /// Public base URL used in config.json `dl` for the disk-backed Rust repo.
    /// E.g. `https://holger.example.com`.  Defaults to `https://127.0.0.1:8443`
    /// when omitted.
    #[serde(default)]
    pub ron_base_url: Option<String>,

    /// Optional path to a WRITABLE znippy archive (rust repos). When set, the repo
    /// is a live `/sparring`-style registry: crates are appended into this single
    /// `.znippy` (created on first push, reboot-safe re-seal per write) and can
    /// later be `seal`ed into a static "drift" snapshot. Distinct from
    /// `ron_archive_path` (read-only drift) and `ron_data_dir` (loose-file repo).
    #[serde(default)]
    pub ron_writable_archive: Option<String>,

    /// Remote-cache upstream: the Nexus/Artifactory repository name to proxy
    /// (e.g. `maven-central`, `cargo-proxy`). Used by the `nexus-remote` /
    /// `artifactory-remote` backends together with `ron_base_url`.
    #[serde(default)]
    pub ron_upstream_repo: Option<String>,

    /// Remote-cache upstream ecosystem/layout (`maven2`, `cargo`, `npm`, …).
    /// Selects the per-format coordinate→URL mapping. Defaults to `rust` (cargo).
    #[serde(default)]
    pub ron_upstream_format: Option<String>,

    /// Remote-cache upstream auth (RON enum: `None`, `Basic`, `Bearer`,
    /// `ApiKey`, `Mtls`). Defaults to `None`.
    #[serde(default)]
    pub ron_upstream_auth: Option<UpstreamAuth>,

    /// Optional path to a DER-encoded trusted root certificate. When set on a
    /// `znippy` repo, the backing archive's provenance (per-artifact + per-archive
    /// detached CMS signatures) is verified against this root BEFORE the repo is
    /// served; verification failure — including an unsigned archive or a signer
    /// that does not chain to this root — fails the wiring closed. Requires the
    /// server to be built with the `sign` feature. Omitted ⇒ served unverified
    /// (the default, byte-for-byte unchanged behaviour).
    #[serde(default)]
    pub ron_trusted_roots: Option<String>,

    /// Negative-cache TTL in **seconds** for a proxy repo (one with
    /// `ron_upstreams`). When set and non-zero, a coordinate that misses the
    /// primary AND every upstream is remembered as a miss for this long, so a
    /// repeated fetch of a not-yet-published artifact short-circuits without
    /// re-walking the (potentially slow / network) upstream chain — the
    /// Nexus/Artifactory "negative cache". Omitted or `0` ⇒ disabled (every miss
    /// re-queries the upstreams, byte-for-byte the prior behaviour). Only
    /// meaningful on a repo with upstreams; ignored otherwise.
    #[serde(default)]
    pub ron_negative_cache_secs: Option<u64>,

    // Wired in second pass
    #[serde(skip_serializing, skip_deserializing, default)]
    pub backend_repository: Option<Arc<dyn RepositoryBackendTrait>>,
    


    #[serde(skip_serializing, skip_deserializing, default)]
    pub wired_upstreams: Vec<*const Repository>, // or &Repository pinned after build

    /// Wired members of a `group` repo (resolved from `ron_members` in the second
    /// pass). Same pinned-pointer discipline as `wired_upstreams`: `null`/dangling
    /// until wiring completes, never followed before then.
    #[serde(skip_serializing, skip_deserializing, default)]
    pub wired_members: Vec<*const Repository>,
}
impl Repository {
    pub fn backend_from_config(&mut self) -> anyhow::Result<()> {
        // Build a znippy-backed repo that requires an archive path.
        macro_rules! znippy_backed {
            ($ty:ty, $label:expr) => {{
                if let Some(archive_path) = &self.ron_archive_path {
                    let repo = <$ty>::with_archive(
                        self.ron_name.clone(),
                        PathBuf::from(archive_path),
                    ).with_context(|| format!(
                        "repo '{}' ({}): failed to open znippy archive '{}' — corrupt, \
                         truncated, or written by an incompatible znippy version",
                        self.ron_name, $label, archive_path
                    ))?;
                    self.backend_repository = Some(Arc::new(repo));
                } else {
                    anyhow::bail!(concat!($label, " repository requires ron_archive_path to a znippy archive"));
                }
                Ok(())
            }};
        }

        match self.ron_repo_type.as_str() {
            "rust" => {
                if let Some(writable) = &self.ron_writable_archive {
                    // Writable znippy-archive registry (the /sparring + /cache
                    // primary): seal-able into a drift snapshot, reboot-safe.
                    let mut repo = RustRepoZnippy::with_writable_archive(
                        self.ron_name.clone(),
                        PathBuf::from(writable),
                    );
                    if let Some(url) = &self.ron_base_url {
                        repo = repo.with_base_url(url.clone());
                    }
                    self.backend_repository = Some(Arc::new(repo));
                } else if let Some(archive_path) = &self.ron_archive_path {
                    let base_url = self
                        .ron_base_url
                        .clone()
                        .unwrap_or_else(|| "https://127.0.0.1:8443".to_string());
                    let repo = RustRepoZnippy::with_archive_and_url(
                        self.ron_name.clone(),
                        PathBuf::from(archive_path),
                        base_url,
                    ).with_context(|| format!(
                        "repo '{}' (rust): failed to open znippy archive '{}' — corrupt, \
                         truncated, or written by an incompatible znippy version",
                        self.ron_name, archive_path
                    ))?;
                    self.backend_repository = Some(Arc::new(repo));
                } else {
                    // Writable, disk-backed dev backend. Requires a storage dir.
                    let dir = self.ron_data_dir.clone().ok_or_else(|| {
                        anyhow::anyhow!(
                            "Rust file-backed repository requires ron_data_dir (storage directory)"
                        )
                    })?;
                    let base_url = self
                        .ron_base_url
                        .clone()
                        .unwrap_or_else(|| "https://127.0.0.1:8443".to_string());
                    let repo = RustRepo::new(self.ron_name.clone(), PathBuf::from(dir), base_url);
                    self.backend_repository = Some(Arc::new(repo));
                }
                Ok(())
            }
            // Read-only REMOTE rust registry (the /cache upstream). Defaults to
            // crates.io; `ron_base_url` (when set) overrides the sparse index base.
            // Pair with a writable "rust" + `ron_upstreams` to get a caching mirror.
            #[cfg(feature = "online")]
            "rust-remote" => {
                let repo = match &self.ron_base_url {
                    Some(idx) => RustRegistryUpstream::new(
                        self.ron_name.clone(),
                        idx.clone(),
                        format!("{}/crates", idx.trim_end_matches('/')),
                    ),
                    None => RustRegistryUpstream::crates_io(self.ron_name.clone()),
                };
                self.backend_repository = Some(Arc::new(repo));
                Ok(())
            }
            // Zero-egress airgap tiers (`online` off) link no outbound HTTP client,
            // so the pull-through `rust-remote` upstream is not compiled. Fail
            // CLOSED with an actionable message rather than silently degrading —
            // an airgap operator must use a local 'rust' repo, not a network mirror.
            #[cfg(not(feature = "online"))]
            "rust-remote" => Err(anyhow::anyhow!(
                "repo '{}' is 'rust-remote' (a pull-through network upstream) but this \
                 binary was built WITHOUT the `online` feature (zero-egress airgap tier) \
                 — no HTTP client is linked. Rebuild with `--features online`, or serve \
                 crates from a local 'rust' repository backed by a znippy archive.",
                self.ron_name
            )),
            // Read-only REMOTE upstream-registry-federation harbours (holger's
            // `full`-tier feature). holger owns the orchestration (which repos
            // proxy which upstreams, pull-through caching via `ProxyBackend`,
            // compression via znippy); the registry-client MECHANISM lives in
            // Skidbladnir's `federation` "ship" (see `crate::upstream`). Shared
            // config fields: `ron_base_url` = harbour base, `ron_upstream_repo` =
            // repo/feed, `ron_upstream_format` = ecosystem (default cargo),
            // `ron_upstream_auth` = creds (default None). Pair with a writable
            // primary + `ron_upstreams` for transparent pull-through caching.
            //  - `nexus-remote`       → `ron_base_url` = Nexus base, `ron_upstream_repo` = hosted/proxy repo.
            //  - `artifactory-remote` → `ron_base_url` = Artifactory base, `ron_upstream_repo` = repo; auth may be Bearer or JFrog API-key.
            //  - `azure-remote`       → `ron_base_url` = Azure DevOps org, `ron_upstream_repo` = "{project}/{feed}" (or "{feed}" org-scoped); auth = PAT-as-Basic or AAD Bearer.
            //  - `aws-remote`         → `ron_base_url` = CodeArtifact repository endpoint; auth = Bearer authorization token.
            "nexus-remote" | "artifactory-remote" | "azure-remote" | "aws-remote" => {
                let base = self.ron_base_url.clone().ok_or_else(|| {
                    anyhow::anyhow!(
                        "{}: requires ron_base_url (the harbour base URL / org / repository endpoint)",
                        self.ron_repo_type
                    )
                })?;
                // aws-remote addresses artifacts off the single repository endpoint
                // and needs no separate repo name; the others require one.
                let repo = if self.ron_repo_type == "aws-remote" {
                    self.ron_upstream_repo.clone().unwrap_or_default()
                } else {
                    self.ron_upstream_repo.clone().ok_or_else(|| {
                        anyhow::anyhow!(
                            "{}: requires ron_upstream_repo (the hosted/proxy repo or project/feed)",
                            self.ron_repo_type
                        )
                    })?
                };
                let format = self
                    .ron_upstream_format
                    .as_deref()
                    .and_then(ArtifactFormat::from_format_str)
                    .unwrap_or(ArtifactFormat::Rust);
                let auth = self.ron_upstream_auth.clone().unwrap_or_default();
                let backend = make_remote_upstream(
                    &self.ron_repo_type,
                    self.ron_name.clone(),
                    base,
                    repo,
                    auth,
                    format,
                )?;
                self.backend_repository = Some(backend);
                Ok(())
            }
            "maven3" => znippy_backed!(MavenRepoZnippy, "Maven3"),
            "pip" => znippy_backed!(PipRepoZnippy, "Pip"),
            // npm threads `ron_base_url` into the packument tarball links (R2): no
            // hardcoded host, so pulls work behind any public host / reverse proxy.
            // Unset ⇒ host-relative URLs.
            "npm" => {
                if let Some(archive_path) = &self.ron_archive_path {
                    let repo = NpmRepoZnippy::with_archive_and_url(
                        self.ron_name.clone(),
                        PathBuf::from(archive_path),
                        self.ron_base_url.clone().unwrap_or_default(),
                    )?;
                    self.backend_repository = Some(Arc::new(repo));
                    Ok(())
                } else {
                    anyhow::bail!("Npm repository requires ron_archive_path to a znippy archive")
                }
            }
            // NuGet threads `ron_base_url` into the V3 service-index
            // PackageBaseAddress so remote clients are pointed at the public host,
            // not a hardcoded loopback. Unset ⇒ the dev-loopback default.
            "nuget" => {
                if let Some(archive_path) = &self.ron_archive_path {
                    let mut repo = NugetRepoZnippy::with_archive(
                        self.ron_name.clone(),
                        PathBuf::from(archive_path),
                    )?;
                    if let Some(url) = &self.ron_base_url {
                        repo = repo.with_base_url(url.clone());
                    }
                    self.backend_repository = Some(Arc::new(repo));
                    Ok(())
                } else {
                    anyhow::bail!("Nuget repository requires ron_archive_path to a znippy archive");
                }
            }
            "go" => znippy_backed!(GoRepoZnippy, "Go"),
            "gem" => znippy_backed!(GemRepoZnippy, "Gem"),
            "deb" => znippy_backed!(DebRepoZnippy, "Deb"),
            "rpm" => znippy_backed!(RpmRepoZnippy, "Rpm"),
            "helm" => znippy_backed!(HelmRepoZnippy, "Helm"),
            "docker" => znippy_backed!(DockerRepoZnippy, "Docker"),
            // Writable OCI registry (Distribution Spec v2). Push target for the
            // modern Helm flow (`helm push oci://…`) and any OCI artifact; needs
            // no archive — it owns a disk-backed, content-addressed store.
            "oci" => {
                let dir = self
                    .ron_data_dir
                    .clone()
                    .unwrap_or_else(|| format!("/var/lib/holger/{}", self.ron_name));
                let repo = OciRepoFile::new(self.ron_name.clone(), PathBuf::from(dir))?;
                self.backend_repository = Some(Arc::new(repo));
                Ok(())
            }
            // Generic / **raw** writable bucket for arbitrary blobs, addressed by
            // path (Nexus/Artifactory "raw hosted repo"). Owns a disk-backed,
            // path-addressed loose-file store — no archive, no index synthesis; a
            // `ron_data_dir` is its only requirement (defaults under /var/lib).
            "raw" => {
                let dir = self
                    .ron_data_dir
                    .clone()
                    .unwrap_or_else(|| format!("/var/lib/holger/{}", self.ron_name));
                let repo = RawBackend::new(self.ron_name.clone(), PathBuf::from(dir));
                self.backend_repository = Some(Arc::new(repo));
                Ok(())
            }
            "conda" => znippy_backed!(CondaRepoZnippy, "Conda"),
            "composer" => znippy_backed!(ComposerRepoZnippy, "Composer"),
            // A virtual `group` repo owns no storage of its own — it aggregates
            // its `ron_members`' backends. The concrete `GroupBackend` is built in
            // the wiring pass (`wire_holger`) once every member backend exists, so
            // there is nothing to materialize here.
            "group" => {
                if self.ron_members.is_empty() {
                    anyhow::bail!(
                        "group repository '{}' requires ron_members (member repo names)",
                        self.ron_name
                    );
                }
                Ok(())
            }
            "znippy" => {
                if self.ron_trusted_roots.is_some() {
                    // Provenance-enforced path (opt-in via `ron_trusted_roots`).
                    self.wire_verified_znippy()
                } else {
                    znippy_backed!(ZnippyRepoZnippy, "Znippy")
                }
            }
            other => anyhow::bail!("Unsupported repository type: {}", other),
        }
    }

    /// Wire a `znippy` repo with provenance verification enabled (built with the
    /// `sign` feature). Loads the DER trusted root from `ron_trusted_roots` and
    /// verifies the backing archive before it is served; any read/parse/verify
    /// failure fails the wiring closed.
    #[cfg(feature = "sign")]
    fn wire_verified_znippy(&mut self) -> anyhow::Result<()> {
        let roots_path = self
            .ron_trusted_roots
            .as_ref()
            .expect("caller checks ron_trusted_roots is Some");
        let archive_path = self.ron_archive_path.as_ref().ok_or_else(|| {
            anyhow::anyhow!("Znippy repository requires ron_archive_path to a znippy archive")
        })?;
        let repo = ZnippyRepoZnippy::with_archive_verified_der_roots(
            self.ron_name.clone(),
            PathBuf::from(archive_path),
            &[PathBuf::from(roots_path)],
        )
        .with_context(|| {
            format!(
                "repo '{}' (Znippy): provenance verification of archive '{}' against trusted \
                 root '{}' failed — archive is unsigned, tampered, or not chained to the root",
                self.ron_name, archive_path, roots_path
            )
        })?;
        self.backend_repository = Some(Arc::new(repo));
        Ok(())
    }

    /// Fail-closed stub for builds WITHOUT the `sign` feature: a configured
    /// `ron_trusted_roots` cannot be honoured, so refuse to wire rather than
    /// silently serving the archive unverified.
    #[cfg(not(feature = "sign"))]
    fn wire_verified_znippy(&mut self) -> anyhow::Result<()> {
        anyhow::bail!(
            "repo '{}': ron_trusted_roots is configured but this server was built without the \
             `sign` feature; provenance cannot be enforced — rebuild with `--features sign` or \
             remove ron_trusted_roots",
            self.ron_name
        )
    }
}




#[derive(Serialize, Deserialize)]
pub struct RepositoryIO {
    pub ron_storage_endpoint: String,
    pub ron_exposed_endpoint: String,


    #[serde(skip_serializing, skip_deserializing, default = "std::ptr::null")]
    pub wired_storage: *const StorageEndpoint,
    #[serde(skip_serializing, skip_deserializing, default = "std::ptr::null")]
    pub wired_exposed: *const ExposedEndpoint,
}

#[cfg(test)]
mod tests {
    use super::*;
    use traits::{ArtifactFormat, ArtifactId, UpstreamAuth};

    fn rust_repo(name: &str) -> Repository {
        Repository {
            ron_name: name.to_string(),
            ron_repo_type: "rust".to_string(),
            ron_upstreams: vec![],
            ron_in: None,
            ron_out: None,
            ron_members: vec![],
            ron_archive_path: None,
            ron_data_dir: None,
            ron_base_url: None,
            ron_writable_archive: None,
            ron_upstream_repo: None,
            ron_upstream_format: None,
            ron_upstream_auth: None,
            ron_trusted_roots: None,
            ron_negative_cache_secs: None,
            backend_repository: None,
            wired_upstreams: vec![],
            wired_members: vec![],
        }
    }

    /// `ron_writable_archive` (the `/sparring` + `/cache`-primary config) builds a
    /// WRITABLE znippy-backed rust backend that accepts a crate and serves it back.
    #[test]
    fn writable_archive_config_builds_writable_backend() {
        let dir = tempfile::tempdir().unwrap();
        let archive = dir.path().join("sparring.znippy");

        let mut repo = rust_repo("sparring");
        repo.ron_writable_archive = Some(archive.to_string_lossy().into_owned());
        repo.backend_from_config().unwrap();

        let backend = repo.backend_repository.as_ref().expect("backend built");
        assert!(backend.is_writable(), "ron_writable_archive must yield a writable backend");

        let id = ArtifactId { namespace: None, name: "serde".into(), version: "1.0.0".into() };
        backend.put(&id, b"crate-bytes").unwrap();
        assert_eq!(
            backend.fetch(&id).unwrap().as_deref(),
            Some(b"crate-bytes".as_slice()),
            "writable backend must serve the crate it was given"
        );
    }

    /// `ron_archive_path` stays the read-only "drift" backend: seal a sparring
    /// archive (via the writable path), reopen it read-only, confirm not writable
    /// but still serves the sealed crate.
    #[test]
    fn archive_path_config_is_read_only_drift() {
        let dir = tempfile::tempdir().unwrap();
        let archive = dir.path().join("drift.znippy");
        let id = ArtifactId { namespace: None, name: "x".into(), version: "1.0.0".into() };

        let mut seed = rust_repo("seed");
        seed.ron_writable_archive = Some(archive.to_string_lossy().into_owned());
        seed.backend_from_config().unwrap();
        seed.backend_repository.unwrap().put(&id, b"sealed-bytes").unwrap();

        let mut ro = rust_repo("drift");
        ro.ron_archive_path = Some(archive.to_string_lossy().into_owned());
        ro.backend_from_config().unwrap();
        let backend = ro.backend_repository.unwrap();
        assert!(!backend.is_writable(), "ron_archive_path must yield a read-only backend");
        assert_eq!(
            backend.fetch(&id).unwrap().as_deref(),
            Some(b"sealed-bytes".as_slice()),
            "read-only drift backend must serve the sealed crate"
        );
    }

    /// `rust-remote` builds a read-only remote-registry upstream (the /cache
    /// upstream); crates.io by default, no archive/dir required.
    #[test]
    fn rust_remote_config_builds_read_only_upstream() {
        let mut repo = rust_repo("crates-io");
        repo.ron_repo_type = "rust-remote".to_string();
        repo.backend_from_config().unwrap();
        let backend = repo.backend_repository.as_ref().expect("backend built");
        assert!(!backend.is_writable(), "remote upstream must be read-only");
        assert_eq!(backend.name(), "crates-io");
    }

    /// `nexus-remote` builds a read-only Nexus upstream from `ron_base_url` +
    /// `ron_upstream_repo`; missing required config fails cleanly. Federation
    /// (`full`) tier only — the mechanism is Skidbladnir's ship.
    #[cfg(feature = "federation")]
    #[test]
    fn nexus_remote_config_builds_read_only_upstream() {
        let mut repo = rust_repo("nexus-cache");
        repo.ron_repo_type = "nexus-remote".to_string();
        // missing ron_base_url + ron_upstream_repo -> error
        assert!(repo.backend_from_config().is_err(), "nexus-remote needs base_url + repo");

        repo.ron_base_url = Some("https://nexus.corp".to_string());
        repo.ron_upstream_repo = Some("crates-proxy".to_string());
        repo.ron_upstream_auth = Some(UpstreamAuth::Basic {
            username: "u".into(),
            password: "p".into(),
        });
        repo.backend_from_config().unwrap();
        let backend = repo.backend_repository.as_ref().expect("backend built");
        assert!(!backend.is_writable(), "nexus upstream must be read-only");
        assert_eq!(backend.name(), "nexus-cache");
    }

    /// `artifactory-remote` builds a read-only Artifactory upstream (`full` tier).
    #[cfg(feature = "federation")]
    #[test]
    fn artifactory_remote_config_builds_read_only_upstream() {
        let mut repo = rust_repo("jfrog-cache");
        repo.ron_repo_type = "artifactory-remote".to_string();
        repo.ron_base_url = Some("https://jfrog.corp".to_string());
        repo.ron_upstream_repo = Some("maven-remote".to_string());
        repo.ron_upstream_format = Some("maven2".to_string());
        repo.backend_from_config().unwrap();
        let backend = repo.backend_repository.as_ref().expect("backend built");
        assert!(!backend.is_writable(), "artifactory upstream must be read-only");
        assert_eq!(backend.format(), ArtifactFormat::Maven3);
    }

    /// The two new cloud harbours (`azure-remote`, `aws-remote`) build read-only
    /// upstreams from RON config (`full` tier).
    #[cfg(feature = "federation")]
    #[test]
    fn azure_and_aws_remote_configs_build_read_only_upstreams() {
        let mut az = rust_repo("azure-cache");
        az.ron_repo_type = "azure-remote".to_string();
        az.ron_base_url = Some("contoso".to_string()); // Azure DevOps org
        az.ron_upstream_repo = Some("proj/myfeed".to_string()); // project/feed
        az.ron_upstream_format = Some("npm".to_string());
        az.backend_from_config().unwrap();
        assert!(!az.backend_repository.as_ref().unwrap().is_writable());

        let mut aws = rust_repo("aws-cache");
        aws.ron_repo_type = "aws-remote".to_string();
        aws.ron_base_url = Some(
            "https://d-111122223333.d.codeartifact.us-west-2.amazonaws.com/npm/my-repo".to_string(),
        );
        aws.ron_upstream_format = Some("npm".to_string());
        aws.ron_upstream_auth = Some(UpstreamAuth::Bearer { token: "AUTHTOK".into() });
        aws.backend_from_config().unwrap(); // aws-remote needs no ron_upstream_repo
        assert!(!aws.backend_repository.as_ref().unwrap().is_writable());
    }

    /// `mini`/`embedded` tier: the federation mechanism is compiled OUT, so a
    /// config asking for a remote harbour FAILS CLOSED (never a silent no-op).
    #[cfg(not(feature = "federation"))]
    #[test]
    fn remote_upstream_configs_fail_closed_without_federation() {
        for kind in ["nexus-remote", "artifactory-remote", "azure-remote", "aws-remote"] {
            let mut repo = rust_repo("cache");
            repo.ron_repo_type = kind.to_string();
            repo.ron_base_url = Some("https://example.corp".to_string());
            repo.ron_upstream_repo = Some("some-repo".to_string());
            let err = repo.backend_from_config().unwrap_err().to_string();
            assert!(
                err.contains("federation") && err.contains("full"),
                "{kind}: mini must fail closed with a rebuild-`full` hint, got: {err}"
            );
        }
    }
}