xianyun_deploy/diagnostics/builtin/

orphaned_mirror_copies.rs

//! Diagnoses `-caproni` mirror deployment copies left behind by an edit
//! mode session that never shut down cleanly.
//!
//! Ported from `internal/diagnostics/builtin/orphaned_mirror_copies.go`.

use std::collections::HashMap;
use std::sync::Arc;

use xianyun_backends::kubectl::Backend as KubectlBackend;
use xianyun_core::config::latest::ReloaderConfig;

use crate::diagnostics::base::{Diagnostic, Meta, SimpleDiagnostic};
use crate::reloader::mirror::copy::{self, COPY_SUFFIX, SCALE_UP_REPLICA_COUNT, Target};

/// This diagnostic's display title, matching the Go original's
/// `Title`.
pub const TITLE: &str = "Edit mode deployment copies";

type BoxError = Box<dyn std::error::Error + Send + Sync>;

/// Builds the "Edit mode deployment copies" diagnostic.
#[must_use]
pub fn diagnostic() -> Arc<dyn Diagnostic> {
    Arc::new(SimpleDiagnostic::new(TITLE, true, run))
}

fn run(meta: &Meta) -> (String, Option<BoxError>) {
    let Some(config) = meta.config.as_ref() else {
        return (String::new(), None);
    };
    let Some(reloaders) = config.reloaders.as_ref() else {
        return (String::new(), None);
    };

    let reloaders_map: HashMap<String, ReloaderConfig> = reloaders
        .iter()
        .map(|(k, v)| (k.clone(), v.clone()))
        .collect();

    let targets = match copy::collect_and_validate_targets(&reloaders_map) {
        Ok(t) => t,
        Err(e) => {
            return (
                String::new(),
                Some(format!("collecting mirror targets: {e}").into()),
            );
        }
    };

    let findings = match inspect_mirror_targets(meta.kubectl.as_deref(), &targets) {
        Ok(f) => f,
        Err(e) => return (String::new(), Some(e)),
    };

    if findings.is_empty() {
        return (String::new(), None);
    }

    (mirror_copy_warning(&findings), None)
}

/// Maps resource name to its `spec.replicas` for one resource type in
/// one namespace.
type ReplicaIndex = HashMap<String, i64>;

fn inspect_mirror_targets(
    kubectl: Option<&(dyn KubectlBackend + Send + Sync)>,
    targets: &[Target],
) -> Result<Vec<String>, BoxError> {
    let mut findings = Vec::new();
    let mut indexes: HashMap<String, ReplicaIndex> = HashMap::new();

    for target in targets {
        // PrepareCopies only mirrors these two, so nothing else can be left
        // behind.
        if target.kubernetes_type != "deployment" && target.kubernetes_type != "statefulset" {
            continue;
        }

        let key = format!("{}/{}", target.kubernetes_type, target.namespace);

        if !indexes.contains_key(&key) {
            let kubectl =
                kubectl.expect("a supported-type target requires a kubectl backend to inspect");
            let index = list_replicas(kubectl, &target.kubernetes_type, &target.namespace)?;
            indexes.insert(key.clone(), index);
        }

        let index = &indexes[&key];
        let finding = inspect_mirror_target(target, index);
        if !finding.is_empty() {
            findings.push(finding);
        }
    }

    Ok(findings)
}

/// Reports how a single mirror target deviates from its deployed
/// state, along with the commands that restore it. Returns an empty
/// string when the target is healthy or was never deployed.
fn inspect_mirror_target(target: &Target, index: &ReplicaIndex) -> String {
    let Some(&replicas) = index.get(&target.name) else {
        return String::new();
    };

    let copy_name = format!("{}{COPY_SUFFIX}", target.name);
    let copy_exists = index.contains_key(&copy_name);

    if !copy_exists && replicas > 0 {
        return String::new();
    }

    let mut commands = Vec::new();
    let mut state = "no copy present".to_string();

    if copy_exists {
        state = "copy present".to_string();
        commands.push(format!(
            "caproni kubectl delete {}/{copy_name} -n {}",
            target.kubernetes_type, target.namespace
        ));
    }

    if replicas == 0 {
        state = format!("scaled to 0, {state}");
        commands.push(format!(
            "caproni kubectl scale {}/{} -n {} --replicas {SCALE_UP_REPLICA_COUNT}",
            target.kubernetes_type, target.name, target.namespace
        ));
    }

    format!(
        "- {}/{} in namespace {:?} ({state})\n    {}",
        target.kubernetes_type,
        target.name,
        target.namespace,
        commands.join("\n    ")
    )
}

/// Indexes every resource of a type in a namespace with a single
/// kubectl call. Listing beats probing each name: the copy is absent
/// on every healthy cluster, and a per-name lookup would log a command
/// error each time doctor confirmed nothing was wrong.
fn list_replicas(
    kubectl: &(dyn KubectlBackend + Send + Sync),
    resource_type: &str,
    namespace: &str,
) -> Result<ReplicaIndex, BoxError> {
    let out = match kubectl.get(resource_type, "", namespace) {
        // A kubectl error, or an empty namespace, means there is nothing to
        // check: the namespace does not exist yet.
        Ok(out) if !out.is_empty() => out,
        _ => return Ok(ReplicaIndex::new()),
    };

    #[derive(serde::Deserialize)]
    struct ItemMetadata {
        name: String,
    }

    #[derive(serde::Deserialize, Default)]
    struct ItemSpec {
        replicas: Option<i64>,
    }

    #[derive(serde::Deserialize)]
    struct Item {
        metadata: ItemMetadata,
        #[serde(default)]
        spec: ItemSpec,
    }

    #[derive(serde::Deserialize)]
    struct ItemList {
        items: Vec<Item>,
    }

    let list: ItemList = serde_json::from_str(&out).map_err(|e| -> BoxError {
        format!("parsing {resource_type} list in namespace {namespace:?}: {e}").into()
    })?;

    let mut index = ReplicaIndex::with_capacity(list.items.len());

    for item in list.items {
        // Kubernetes defaults an omitted spec.replicas to 1.
        let replicas = item.spec.replicas.unwrap_or(1);
        index.insert(item.metadata.name, replicas);
    }

    Ok(index)
}

fn mirror_copy_warning(findings: &[String]) -> String {
    format!(
        "While `caproni run` is active, edit mode scales a deployment down and runs a\n\"{COPY_SUFFIX}\" copy in its place, then restores the original on exit. That restore is\nskipped if edit mode never got to shut down cleanly, which leaves the workload\nscaled to 0 and the cluster serving nothing.\n\nThese targets are not in their deployed state:\n\n{}\n\nIf `caproni run` is active right now, this is expected and you can ignore it.\nOtherwise, run the commands above to restore them.",
        findings.join("\n")
    )
}

#[cfg(test)]
mod tests {
    use xianyun_core::config::latest::{
        CaproniConfig, MirrorConfig, MirrorTargetConfig, ReloaderConfig,
    };
    use xianyun_core::orderedmap::OrderedMap;

    use super::*;
    use crate::reloader::mirror::test_support::MockKubectlBackend;

    fn config_with_mirror_target(name: &str) -> CaproniConfig {
        let mut reloaders = OrderedMap::new();
        reloaders.set(
            "gitlab".to_string(),
            ReloaderConfig {
                name: "gitlab".to_string(),
                reloader_type: "mirror".to_string(),
                mirror: Some(MirrorConfig {
                    target: Some(MirrorTargetConfig {
                        namespace: "gitlab".to_string(),
                        kubernetes_type: "deployment".to_string(),
                        name: name.to_string(),
                        container: String::new(),
                    }),
                    ..Default::default()
                }),
                ..Default::default()
            },
        );

        CaproniConfig {
            reloaders: Some(reloaders),
            ..Default::default()
        }
    }

    // Ported from internal/diagnostics/builtin/orphaned_mirror_copies_test.go:20 (TestInspectMirrorTarget)
    #[test]
    fn test_inspect_mirror_target() {
        let target = Target::new("gitlab", "deployment", "gitlab-webservice-default");

        struct Case {
            name: &'static str,
            index: ReplicaIndex,
            want_empty: bool,
            want_contains: Vec<&'static str>,
        }

        let cases = vec![
            Case {
                name: "healthy: original scaled up, no copy",
                index: HashMap::from([("gitlab-webservice-default".to_string(), 1)]),
                want_empty: true,
                want_contains: vec![],
            },
            Case {
                name: "target was never deployed",
                index: HashMap::from([("something-else".to_string(), 1)]),
                want_empty: true,
                want_contains: vec![],
            },
            Case {
                name: "orphan: scaled to 0 with a copy present",
                index: HashMap::from([
                    ("gitlab-webservice-default".to_string(), 0),
                    ("gitlab-webservice-default-caproni".to_string(), 1),
                ]),
                want_empty: false,
                want_contains: vec![
                    r#"deployment/gitlab-webservice-default in namespace "gitlab" (scaled to 0, copy present)"#,
                    "caproni kubectl delete deployment/gitlab-webservice-default-caproni -n gitlab",
                    "caproni kubectl scale deployment/gitlab-webservice-default -n gitlab --replicas 1",
                ],
            },
            Case {
                name: "copy present while the original is still scaled up",
                index: HashMap::from([
                    ("gitlab-webservice-default".to_string(), 1),
                    ("gitlab-webservice-default-caproni".to_string(), 1),
                ]),
                want_empty: false,
                want_contains: vec![
                    "(copy present)",
                    "caproni kubectl delete deployment/gitlab-webservice-default-caproni -n gitlab",
                ],
            },
            Case {
                name: "scaled to 0 with no copy needs only a scale up",
                index: HashMap::from([("gitlab-webservice-default".to_string(), 0)]),
                want_empty: false,
                want_contains: vec![
                    "(scaled to 0, no copy present)",
                    "caproni kubectl scale deployment/gitlab-webservice-default -n gitlab --replicas 1",
                ],
            },
        ];

        for case in cases {
            let got = inspect_mirror_target(&target, &case.index);

            if case.want_empty {
                assert!(got.is_empty(), "{}: expected empty, got {got:?}", case.name);
                continue;
            }

            for want in case.want_contains {
                assert!(
                    got.contains(want),
                    "{}: expected {got:?} to contain {want:?}",
                    case.name
                );
            }
        }
    }

    // Ported from internal/diagnostics/builtin/orphaned_mirror_copies_test.go:99 (TestInspectMirrorTarget_ScaleUpOmitsCopyDelete)
    #[test]
    fn test_inspect_mirror_target_scale_up_omits_copy_delete() {
        let target = Target::new("gitlab", "deployment", "gitlab-webservice-default");
        let index = HashMap::from([("gitlab-webservice-default".to_string(), 0)]);

        let got = inspect_mirror_target(&target, &index);
        assert!(!got.contains("kubectl delete"));
    }

    // Ported from internal/diagnostics/builtin/orphaned_mirror_copies_test.go:111 (TestListReplicas)
    #[test]
    fn test_list_replicas() {
        // indexes names and replicas
        {
            let mock_kubectl =
                MockKubectlBackend::new().expect_get(|resource_type, name, namespace| {
                    assert_eq!(resource_type, "deployment");
                    assert_eq!(name, "");
                    assert_eq!(namespace, "gitlab");
                    Ok(r#"{"items":[
                    {"metadata":{"name":"scaled-down"},"spec":{"replicas":0}},
                    {"metadata":{"name":"scaled-up"},"spec":{"replicas":2}},
                    {"metadata":{"name":"replicas-omitted"},"spec":{}}
                ]}"#
                    .to_string())
                });

            let index = list_replicas(&mock_kubectl, "deployment", "gitlab").unwrap();
            assert_eq!(
                index,
                HashMap::from([
                    ("scaled-down".to_string(), 0),
                    ("scaled-up".to_string(), 2),
                    ("replicas-omitted".to_string(), 1),
                ])
            );
        }

        // a missing namespace yields an empty index, not an error
        {
            let mock_kubectl = MockKubectlBackend::new().expect_get(|_, _, _| {
                Err(xianyun_backends::kubectl::KubectlError::JobFailed(
                    "command failed".to_string(),
                ))
            });

            let index = list_replicas(&mock_kubectl, "deployment", "nope").unwrap();
            assert!(index.is_empty());
        }

        // malformed JSON is an error
        {
            let mock_kubectl =
                MockKubectlBackend::new().expect_get(|_, _, _| Ok(r#"{"items":"#.to_string()));

            let result = list_replicas(&mock_kubectl, "deployment", "gitlab");
            assert!(result.is_err());
        }
    }

    // Ported from internal/diagnostics/builtin/orphaned_mirror_copies_test.go:161 (TestInspectMirrorTargets_ListsEachNamespaceOnce)
    #[test]
    fn test_inspect_mirror_targets_lists_each_namespace_once() {
        // Two targets in the same namespace must share a single kubectl call.
        let mock_kubectl =
            MockKubectlBackend::new().expect_get(|resource_type, _name, namespace| {
                assert_eq!(resource_type, "deployment");
                assert_eq!(namespace, "gitlab");
                Ok(r#"{"items":[
                {"metadata":{"name":"webservice"},"spec":{"replicas":0}},
                {"metadata":{"name":"webservice-caproni"},"spec":{"replicas":1}},
                {"metadata":{"name":"sidekiq"},"spec":{"replicas":1}}
            ]}"#
                .to_string())
            });

        let targets = vec![
            Target::new("gitlab", "deployment", "webservice"),
            Target::new("gitlab", "deployment", "sidekiq"),
        ];

        let findings = inspect_mirror_targets(Some(&mock_kubectl), &targets).unwrap();
        assert_eq!(findings.len(), 1);
        assert!(findings[0].contains("deployment/webservice"));
    }

    // Ported from internal/diagnostics/builtin/orphaned_mirror_copies_test.go:185 (TestInspectMirrorTargets_SkipsUnsupportedTypes)
    #[test]
    fn test_inspect_mirror_targets_skips_unsupported_types() {
        // No kubectl backend proves no lookup happens: PrepareCopies never
        // mirrors a pod, so there can be no copy of one to find.
        let targets = vec![Target::new("gitlab", "pod", "some-pod")];

        let findings = inspect_mirror_targets(None, &targets).unwrap();
        assert!(findings.is_empty());
    }

    // Ported from internal/diagnostics/builtin/orphaned_mirror_copies_test.go:200 (TestOrphanedMirrorCopiesDiagnostic)
    #[test]
    fn test_orphaned_mirror_copies_diagnostic() {
        let d = diagnostic();
        assert_eq!(d.name(), TITLE);
        assert!(
            d.needs_cluster(),
            "the check queries the cluster, so it must be skipped when it is down"
        );

        // no config is not a failure
        {
            let (out, err) = d.run(&Meta::default());
            assert!(err.is_none());
            assert!(out.is_empty());
        }

        // warns for an orphaned copy
        {
            let mock_kubectl = MockKubectlBackend::new().expect_get(|_, _, _| {
                Ok(r#"{"items":[
                    {"metadata":{"name":"gitlab-webservice-default"},"spec":{"replicas":0}},
                    {"metadata":{"name":"gitlab-webservice-default-caproni"},"spec":{"replicas":1}}
                ]}"#
                .to_string())
            });

            let meta = Meta {
                kubectl: Some(std::sync::Arc::new(mock_kubectl)),
                config: Some(config_with_mirror_target("gitlab-webservice-default")),
            };

            let (out, err) = d.run(&meta);
            assert!(err.is_none());
            assert!(out.contains(
                "caproni kubectl delete deployment/gitlab-webservice-default-caproni -n gitlab"
            ));
            assert!(out.contains(
                "caproni kubectl scale deployment/gitlab-webservice-default -n gitlab --replicas 1"
            ));
            assert!(out.contains("`caproni run` is active right now"));
        }

        // silent when every target is healthy
        {
            let mock_kubectl = MockKubectlBackend::new().expect_get(|_, _, _| {
                Ok(r#"{"items":[{"metadata":{"name":"gitlab-webservice-default"},"spec":{"replicas":1}}]}"#
                    .to_string())
            });

            let meta = Meta {
                kubectl: Some(std::sync::Arc::new(mock_kubectl)),
                config: Some(config_with_mirror_target("gitlab-webservice-default")),
            };

            let (out, err) = d.run(&meta);
            assert!(err.is_none());
            assert!(out.is_empty());
        }

        // non-mirror reloaders are ignored
        {
            let mut reloaders = OrderedMap::new();
            reloaders.set(
                "frontend".to_string(),
                ReloaderConfig {
                    name: "frontend".to_string(),
                    reloader_type: "skaffold".to_string(),
                    ..Default::default()
                },
            );

            let meta = Meta {
                kubectl: None,
                config: Some(CaproniConfig {
                    reloaders: Some(reloaders),
                    ..Default::default()
                }),
            };

            // No kubectl backend proves no lookup happens for a skaffold
            // reloader.
            let (out, err) = d.run(&meta);
            assert!(err.is_none());
            assert!(out.is_empty());
        }
    }
}