xianyun_deploy/deployer/kustomize/

builtin.rs

//! Registry of kustomizations embedded in caproni itself.
//!
//! Ported from `internal/deployer/kustomize/builtin.go`. The Go original
//! walks an embedded `io/fs.FS` per overlay (`//go:embed *.yaml`); this
//! port instead reuses the flat `(name, content)` file lists already
//! ported to `xianyun_infra::{dev_ca, traefik_tlsstore}::FILES`, since
//! both builtin overlays here are flat (no nested directories).

use std::path::{Path, PathBuf};

use thiserror::Error;

use super::Cleanup;

/// Prefixes a kustomize path that references an overlay embedded in
/// caproni itself rather than a directory on disk. For example
/// `"builtin:dev-ca"` resolves to the embedded dev-CA supporting-manifests
/// overlay.
const BUILTIN_SCHEME: &str = "builtin:";

/// Errors from builtin overlay resolution and materialization.
#[derive(Debug, Error)]
pub enum BuiltinError {
    /// A kustomize path used the `builtin:` scheme with a name that is
    /// not registered.
    #[error("unknown builtin kustomize overlay: {0}")]
    UnknownOverlay(String),
    /// Creating the temporary directory to materialize an overlay into
    /// failed.
    #[error("creating temp overlay directory: {0}")]
    CreateTempDir(#[source] std::io::Error),
    /// Writing an overlay's embedded files into its materialized
    /// directory failed.
    #[error("materializing builtin overlay {0:?}: {1}")]
    Materialize(String, #[source] std::io::Error),
}

/// Describes a kustomization embedded in caproni itself.
///
/// What caproni writes into the materialized directory before building
/// is declared per overlay rather than assumed: an overlay that wants
/// the runtime CA material or the cluster hostname must say so, and the
/// injection then fails loudly if the overlay does not carry the
/// generator it needs. Injecting unconditionally and skipping when a
/// generator is absent would turn a broken dev-CA kustomization into a
/// silent fallback to its placeholder hostname literal.
struct BuiltinOverlay {
    /// The overlay's embedded files, as `(name, content)` pairs.
    files: &'static [(&'static str, &'static str)],
    /// Marks an overlay whose secretGenerator references the runtime CA
    /// cert/key files, which are written into the materialized
    /// directory.
    needs_ca: bool,
    /// Marks an overlay whose configMapGenerator carries the cluster
    /// hostname literals, which are rewritten in the materialized
    /// kustomization.
    needs_hostname: bool,
}

/// Looks up a builtin overlay by its bare name (without the `builtin:`
/// prefix). Adding a new builtin overlay only requires adding a case
/// here.
fn lookup(name: &str) -> Option<BuiltinOverlay> {
    match name {
        // The dev-CA supporting manifests: CA Secret, ClusterIssuer, trust
        // Bundle, and a wildcard Certificate for the cluster hostname.
        "dev-ca" => Some(BuiltinOverlay {
            files: xianyun_infra::dev_ca::FILES,
            needs_ca: true,
            needs_hostname: true,
        }),
        // The TLSStore making that wildcard certificate Traefik's default. It
        // names the certificate Secret and nothing else, so it takes no
        // injection.
        "traefik-tlsstore" => Some(BuiltinOverlay {
            files: xianyun_infra::traefik_tlsstore::FILES,
            needs_ca: false,
            needs_hostname: false,
        }),
        _ => None,
    }
}

/// Reports whether `path` uses the `builtin:` scheme.
#[must_use]
pub fn is_builtin_path(path: &str) -> bool {
    path.starts_with(BUILTIN_SCHEME)
}

/// Extracts the overlay name from a `builtin:` path.
#[must_use]
pub fn builtin_name(path: &str) -> &str {
    path.strip_prefix(BUILTIN_SCHEME).unwrap_or(path)
}

/// Reports whether `path` names a registered builtin overlay that
/// consumes caproni's runtime CA material.
#[must_use]
pub fn overlay_needs_ca(path: &str) -> bool {
    registered_builtin(path).is_some_and(|overlay| overlay.needs_ca)
}

/// Reports whether `path` names a registered builtin overlay that
/// carries the cluster hostname literals.
#[must_use]
pub fn overlay_needs_hostname(path: &str) -> bool {
    registered_builtin(path).is_some_and(|overlay| overlay.needs_hostname)
}

/// Returns the overlay a `builtin:` path names, if it is registered.
fn registered_builtin(path: &str) -> Option<BuiltinOverlay> {
    if !is_builtin_path(path) {
        return None;
    }

    lookup(builtin_name(path))
}

/// Returns `Ok(())` when `path` names a registered builtin overlay.
///
/// # Errors
///
/// Returns [`BuiltinError::UnknownOverlay`] if `path` names an
/// unregistered overlay.
pub fn validate_builtin_path(path: &str) -> Result<(), BuiltinError> {
    if lookup(builtin_name(path)).is_none() {
        return Err(BuiltinError::UnknownOverlay(builtin_name(path).to_string()));
    }

    Ok(())
}

/// Copies the embedded overlay named by a `builtin:` path into a fresh
/// temporary directory and returns it -- kustomize builds it directly,
/// and caproni writes the CA material and hostname into the same
/// directory. The caller owns the directory and must remove it via the
/// returned cleanup function, which is always safe to call.
///
/// # Errors
///
/// Returns [`BuiltinError::UnknownOverlay`] if `path` names an
/// unregistered overlay, or [`BuiltinError::CreateTempDir`] /
/// [`BuiltinError::Materialize`] if materializing the overlay's files
/// fails.
pub fn materialize_builtin_overlay(path: &str) -> Result<(PathBuf, Cleanup), BuiltinError> {
    let name = builtin_name(path);
    let overlay = lookup(name).ok_or_else(|| BuiltinError::UnknownOverlay(name.to_string()))?;

    let tmp_dir =
        super::mkdtemp("caproni-builtin-kustomize-").map_err(BuiltinError::CreateTempDir)?;

    if let Err(e) = write_overlay_files(&tmp_dir, overlay.files) {
        let _ = std::fs::remove_dir_all(&tmp_dir);
        return Err(BuiltinError::Materialize(name.to_string(), e));
    }

    let cleanup_dir = tmp_dir.clone();
    let cleanup: Cleanup = Box::new(move || {
        let _ = std::fs::remove_dir_all(&cleanup_dir);
    });

    Ok((tmp_dir, cleanup))
}

/// Writes an overlay's embedded `(name, content)` files into `dir`,
/// which must already exist.
fn write_overlay_files(dir: &Path, files: &[(&str, &str)]) -> std::io::Result<()> {
    for (name, content) in files {
        std::fs::write(dir.join(name), content)?;
    }

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::deployer::kustomize::manager::{DEPLOYER_TYPE, Manager};
    use crate::deployer::kustomize::test_support::{MockKubectlBackend, MockKustomizeBackend};
    use xianyun_core::config::latest::{CaproniConfig, DeployerConfig, KustomizeConfig};

    // Ported from internal/deployer/kustomize/builtin_test.go:15 (TestValidate_BuiltinDevCAPath)
    #[test]
    fn test_validate_builtin_dev_ca_path() {
        let mgr = Manager::new(
            Box::new(MockKustomizeBackend::new()),
            Box::new(MockKubectlBackend::new()),
        );

        let deployer_cfg = DeployerConfig {
            deployer_type: DEPLOYER_TYPE.to_string(),
            kustomize: Some(KustomizeConfig {
                path: "builtin:dev-ca".to_string(),
                namespace: "cert-manager".to_string(),
                ..Default::default()
            }),
            ..Default::default()
        };

        // builtin: paths are validated by name, not by stat-ing disk, so an
        // empty ConfigDir (no on-disk path) must still validate.
        mgr.validate(&deployer_cfg, &CaproniConfig::default())
            .unwrap();
    }

    // Ported from internal/deployer/kustomize/builtin_test.go:34 (TestValidate_UnknownBuiltinPath)
    #[test]
    fn test_validate_unknown_builtin_path() {
        let mgr = Manager::new(
            Box::new(MockKustomizeBackend::new()),
            Box::new(MockKubectlBackend::new()),
        );

        let deployer_cfg = DeployerConfig {
            deployer_type: DEPLOYER_TYPE.to_string(),
            kustomize: Some(KustomizeConfig {
                path: "builtin:does-not-exist".to_string(),
                ..Default::default()
            }),
            ..Default::default()
        };

        let err = mgr
            .validate(&deployer_cfg, &CaproniConfig::default())
            .unwrap_err();
        assert!(matches!(
            err,
            crate::deployer::kustomize::manager::KustomizeError::Builtin(
                BuiltinError::UnknownOverlay(_)
            )
        ));
    }

    // Ported from internal/deployer/kustomize/builtin_test.go:50 (TestMaterializeBuiltinOverlay_DevCA)
    #[test]
    fn test_materialize_builtin_overlay_dev_ca() {
        let (dir, cleanup) = materialize_builtin_overlay("builtin:dev-ca").unwrap();

        // The flat overlay ships every manifest in one directory: the base CA
        // resources plus the wildcard Certificate. The Traefik TLSStore is a
        // separate overlay, since it needs the Traefik CRDs rather than
        // cert-manager's.
        for name in [
            "kustomization.yaml",
            "namespace.yaml",
            "clusterissuer.yaml",
            "bundle.yaml",
            "certificate.yaml",
        ] {
            assert!(
                dir.join(name).is_file(),
                "expected materialized file {name:?}"
            );
        }

        cleanup();
    }

    // Ported from internal/deployer/kustomize/builtin_test.go:70 (TestMaterializeBuiltinOverlay_Unknown)
    #[test]
    fn test_materialize_builtin_overlay_unknown() {
        match materialize_builtin_overlay("builtin:nope") {
            Ok(_) => panic!("expected an UnknownOverlay error"),
            Err(err) => assert!(matches!(err, BuiltinError::UnknownOverlay(_))),
        }
    }

    // Ported from internal/deployer/kustomize/builtin_test.go:83 (TestBuiltinOverlayCapabilities)
    //
    // Pins what caproni injects into each builtin overlay. The dev-CA overlay
    // carries a CA secretGenerator and the hostname literals; the TLSStore
    // overlay carries neither, and injecting into it would fail on the
    // missing generators.
    #[test]
    fn test_builtin_overlay_capabilities() {
        struct Case {
            name: &'static str,
            path: &'static str,
            want_ca: bool,
            want_hostname: bool,
        }

        let cases = [
            Case {
                name: "dev-ca takes CA material and hostname",
                path: "builtin:dev-ca",
                want_ca: true,
                want_hostname: true,
            },
            Case {
                name: "traefik-tlsstore takes neither",
                path: "builtin:traefik-tlsstore",
                want_ca: false,
                want_hostname: false,
            },
            Case {
                name: "unknown builtin",
                path: "builtin:nope",
                want_ca: false,
                want_hostname: false,
            },
            Case {
                name: "ordinary path",
                path: "./manifests",
                want_ca: false,
                want_hostname: false,
            },
        ];

        for case in cases {
            assert_eq!(
                overlay_needs_ca(case.path),
                case.want_ca,
                "{}: needs CA material",
                case.name
            );
            assert_eq!(
                overlay_needs_hostname(case.path),
                case.want_hostname,
                "{}: needs hostname",
                case.name
            );
        }
    }
}