1use std::collections::BTreeSet;
9
10use serde_json::Value;
11
12use crate::normalize::Normalizer;
13use crate::observe::{DiffError, Observation};
14use crate::op::{OpKind, Operation};
15use crate::path::JsonPath;
16use crate::target::DiffTarget;
17use crate::verdict::{Divergence, Gvr, Severity, Side, Verdict};
18
19pub async fn run(
27 op: &Operation,
28 engenho: &dyn DiffTarget,
29 k3s: &dyn DiffTarget,
30 norm: &Normalizer,
31) -> Result<Verdict, DiffError> {
32 let eng_obs = op_observe(op, engenho).await?;
33 let k3s_obs = op_observe(op, k3s).await?;
34 let divs = diff_observations(op, &eng_obs, &k3s_obs, norm);
35 Ok(if divs.is_empty() {
36 Verdict::parity()
37 } else {
38 Verdict::Divergent(divs)
39 })
40}
41
42pub async fn run_strict(
49 op: &Operation,
50 engenho: &dyn DiffTarget,
51 k3s: &dyn DiffTarget,
52 norm: &Normalizer,
53) -> Result<(Vec<Divergence>, Vec<Divergence>), DiffError> {
54 let eng_obs = op_observe(op, engenho).await?;
55 let k3s_obs = op_observe(op, k3s).await?;
56 let hard = diff_observations(op, &eng_obs, &k3s_obs, norm);
57 let cosmetic = cosmetic_divergences(op, &eng_obs, &k3s_obs, &hard);
58 Ok((hard, cosmetic))
59}
60
61async fn op_observe(op: &Operation, target: &dyn DiffTarget) -> Result<Observation, DiffError> {
62 target
63 .raw(
64 op.method,
65 &op.path,
66 op.body_bytes().as_deref(),
67 op.content_type.as_deref(),
68 )
69 .await
70}
71
72#[must_use]
74pub fn diff_observations(
75 op: &Operation,
76 eng: &Observation,
77 k3s: &Observation,
78 norm: &Normalizer,
79) -> Vec<Divergence> {
80 if eng.status != k3s.status {
82 return status_divergence(op, eng.status, k3s.status);
83 }
84 if !eng.is_success() {
86 return Vec::new();
87 }
88 match op.kind {
90 OpKind::Object => diff_object_focused(
91 &norm.apply(&eng.json),
92 &norm.apply(&k3s.json),
93 op.focus.as_ref(),
94 Severity::Hard,
95 ),
96 OpKind::List => diff_list(&eng.json, &k3s.json, norm, Severity::Hard),
97 OpKind::Discovery => diff_discovery(&eng.json, &k3s.json),
98 }
99}
100
101fn diff_object_focused(
108 eng: &Value,
109 k3s: &Value,
110 focus: Option<&JsonPath>,
111 sev: Severity,
112) -> Vec<Divergence> {
113 match focus {
114 None => diff_object(eng, k3s, sev),
115 Some(p) => {
116 let en = p.get(eng).cloned().unwrap_or(Value::Null);
117 let kn = p.get(k3s).cloned().unwrap_or(Value::Null);
118 diff_object(&en, &kn, sev)
121 .into_iter()
122 .map(|d| d.reroot(p))
123 .collect()
124 }
125 }
126}
127
128#[must_use]
132fn cosmetic_divergences(
133 op: &Operation,
134 eng: &Observation,
135 k3s: &Observation,
136 hard: &[Divergence],
137) -> Vec<Divergence> {
138 if eng.status != k3s.status || !eng.is_success() {
139 return Vec::new();
140 }
141 let raw = match op.kind {
142 OpKind::Object => {
143 diff_object_focused(&eng.json, &k3s.json, op.focus.as_ref(), Severity::Cosmetic)
144 }
145 OpKind::List => diff_list_raw(&eng.json, &k3s.json, Severity::Cosmetic),
146 OpKind::Discovery => Vec::new(),
147 };
148 let hard_sigs: BTreeSet<String> = hard.iter().map(Divergence::signature).collect();
149 raw.into_iter()
150 .filter(|d| !hard_sigs.contains(&d.signature()))
151 .collect()
152}
153
154fn status_divergence(op: &Operation, eng: u16, k3s: u16) -> Vec<Divergence> {
155 let eng_ok = (200..300).contains(&eng);
156 let k3s_ok = (200..300).contains(&k3s);
157 if let Some((gvr, verb)) = &op.verb_probe {
159 if eng_ok != k3s_ok {
160 let present_on = if k3s_ok { Side::K3s } else { Side::Engenho };
161 return vec![Divergence::MissingVerb {
162 gvr: gvr.clone(),
163 verb: *verb,
164 present_on,
165 }];
166 }
167 }
168 if eng == 404 && k3s_ok {
170 return vec![Divergence::MissingResource {
171 path: JsonPath::root(),
172 present_on: Side::K3s,
173 }];
174 }
175 if k3s == 404 && eng_ok {
176 return vec![Divergence::MissingResource {
177 path: JsonPath::root(),
178 present_on: Side::Engenho,
179 }];
180 }
181 vec![Divergence::StatusCodeDiff {
182 op: op.id.clone(),
183 method: op.method,
184 engenho: eng,
185 k3s,
186 }]
187}
188
189pub fn diff_object(eng: &Value, k3s: &Value, sev: Severity) -> Vec<Divergence> {
199 let mut out = Vec::new();
200 walk(JsonPath::root(), eng, k3s, sev, &mut out);
201 out
202}
203
204fn walk(path: JsonPath, eng: &Value, k3s: &Value, sev: Severity, out: &mut Vec<Divergence>) {
205 match (eng, k3s) {
206 (Value::Object(e), Value::Object(k)) => {
207 for (key, kv) in k {
208 match e.get(key) {
209 None => out.push(Divergence::MissingDefault {
210 path: path.clone().key(key.clone()),
211 k3s_value: kv.clone(),
212 severity: sev,
213 }),
214 Some(ev) => walk(path.clone().key(key.clone()), ev, kv, sev, out),
215 }
216 }
217 for (key, ev) in e {
218 if !k.contains_key(key) {
219 out.push(Divergence::ExtraField {
220 path: path.clone().key(key.clone()),
221 side: Side::Engenho,
222 value: ev.clone(),
223 severity: sev,
224 });
225 }
226 }
227 }
228 (Value::Array(e), Value::Array(k)) => {
229 if e.len() == k.len() {
230 for (i, (ev, kv)) in e.iter().zip(k.iter()).enumerate() {
231 walk(path.clone().index(i), ev, kv, sev, out);
232 }
233 } else {
234 out.push(Divergence::FieldDiff {
235 path,
236 engenho: eng.clone(),
237 k3s: k3s.clone(),
238 severity: sev,
239 });
240 }
241 }
242 (e, k) if e == k => {}
243 (e, k) => out.push(Divergence::FieldDiff {
244 path,
245 engenho: e.clone(),
246 k3s: k.clone(),
247 severity: sev,
248 }),
249 }
250}
251
252fn diff_list(eng: &Value, k3s: &Value, norm: &Normalizer, sev: Severity) -> Vec<Divergence> {
256 let mut out = Vec::new();
257 envelope_check(eng, k3s, sev, &mut out);
259 let eng_items = items_by_name(eng);
260 let k3s_items = items_by_name(k3s);
261 let names: BTreeSet<&String> = eng_items.keys().chain(k3s_items.keys()).collect();
262 for name in names {
263 match (eng_items.get(name), k3s_items.get(name)) {
264 (Some(e), Some(k)) => {
265 out.extend(diff_object(&norm.apply(e), &norm.apply(k), sev));
266 }
267 (None, Some(_)) => out.push(Divergence::MissingResource {
268 path: JsonPath::root().key("items").key((*name).clone()),
269 present_on: Side::K3s,
270 }),
271 (Some(_), None) => out.push(Divergence::MissingResource {
272 path: JsonPath::root().key("items").key((*name).clone()),
273 present_on: Side::Engenho,
274 }),
275 (None, None) => {}
276 }
277 }
278 out
279}
280
281fn diff_list_raw(eng: &Value, k3s: &Value, sev: Severity) -> Vec<Divergence> {
284 let mut out = Vec::new();
285 let eng_items = items_by_name(eng);
286 let k3s_items = items_by_name(k3s);
287 for (name, e) in &eng_items {
288 if let Some(k) = k3s_items.get(name) {
289 out.extend(diff_object(e, k, sev));
290 }
291 }
292 out
293}
294
295fn envelope_check(eng: &Value, k3s: &Value, sev: Severity, out: &mut Vec<Divergence>) {
296 for field in ["kind", "apiVersion"] {
297 let ev = eng.get(field);
298 let kv = k3s.get(field);
299 if ev != kv {
300 match (ev, kv) {
301 (None, Some(k)) => out.push(Divergence::MissingDefault {
302 path: JsonPath::root().key(field),
303 k3s_value: k.clone(),
304 severity: sev,
305 }),
306 (Some(e), None) => out.push(Divergence::ExtraField {
307 path: JsonPath::root().key(field),
308 side: Side::Engenho,
309 value: e.clone(),
310 severity: sev,
311 }),
312 (Some(e), Some(k)) => out.push(Divergence::FieldDiff {
313 path: JsonPath::root().key(field),
314 engenho: e.clone(),
315 k3s: k.clone(),
316 severity: sev,
317 }),
318 (None, None) => {}
319 }
320 }
321 }
322}
323
324fn items_by_name(list: &Value) -> std::collections::BTreeMap<String, Value> {
325 let mut m = std::collections::BTreeMap::new();
326 if let Some(items) = list.get("items").and_then(Value::as_array) {
327 for it in items {
328 let name = it
329 .get("metadata")
330 .and_then(|md| md.get("name"))
331 .and_then(Value::as_str)
332 .unwrap_or_default()
333 .to_string();
334 m.insert(name, it.clone());
335 }
336 }
337 m
338}
339
340fn diff_discovery(eng: &Value, k3s: &Value) -> Vec<Divergence> {
343 let mut out = Vec::new();
344 let eng_res = resources_by_name(eng);
345 let k3s_res = resources_by_name(k3s);
346 for name in ["configmaps", "namespaces"] {
347 match (eng_res.get(name), k3s_res.get(name)) {
348 (Some(e), Some(k)) => diff_resource_entry(name, e, k, &mut out),
349 (None, Some(_)) => out.push(Divergence::MissingResource {
350 path: JsonPath::root().key("resources").key(name),
351 present_on: Side::K3s,
352 }),
353 (Some(_), None) => out.push(Divergence::MissingResource {
354 path: JsonPath::root().key("resources").key(name),
355 present_on: Side::Engenho,
356 }),
357 (None, None) => {}
358 }
359 }
360 for sub in ["namespaces/status", "namespaces/finalize"] {
362 let on_eng = eng_res.contains_key(sub);
363 let on_k3s = k3s_res.contains_key(sub);
364 if on_k3s && !on_eng {
365 out.push(Divergence::MissingSubresource {
366 gvr: Gvr {
367 group: String::new(),
368 version: "v1".into(),
369 resource: "namespaces".into(),
370 },
371 sub: sub.rsplit('/').next().unwrap_or(sub).to_string(),
372 present_on: Side::K3s,
373 });
374 }
375 }
376 out
377}
378
379fn resources_by_name(list: &Value) -> std::collections::BTreeMap<String, Value> {
380 let mut m = std::collections::BTreeMap::new();
381 if let Some(resources) = list.get("resources").and_then(Value::as_array) {
382 for r in resources {
383 if let Some(name) = r.get("name").and_then(Value::as_str) {
384 m.insert(name.to_string(), r.clone());
385 }
386 }
387 }
388 m
389}
390
391fn diff_resource_entry(name: &str, eng: &Value, k3s: &Value, out: &mut Vec<Divergence>) {
392 let e_ns = eng.get("namespaced").and_then(Value::as_bool);
394 let k_ns = k3s.get("namespaced").and_then(Value::as_bool);
395 if e_ns != k_ns {
396 let mut detail = String::from(name);
397 detail.push_str(": namespaced engenho=");
398 detail.push_str(&fmt_opt_bool(e_ns));
399 detail.push_str(" k3s=");
400 detail.push_str(&fmt_opt_bool(k_ns));
401 out.push(Divergence::DiscoveryDiff {
402 group: String::new(),
403 version: "v1".into(),
404 detail,
405 });
406 }
407 let e_verbs = str_set(eng.get("verbs"));
409 let k_verbs = str_set(k3s.get("verbs"));
410 let missing: Vec<&String> = k_verbs.difference(&e_verbs).collect();
411 let extra: Vec<&String> = e_verbs.difference(&k_verbs).collect();
412 if !missing.is_empty() {
413 let mut detail = String::from(name);
414 detail.push_str(": engenho missing verbs ");
415 detail.push_str(&join_refs(&missing));
416 out.push(Divergence::DiscoveryDiff {
417 group: String::new(),
418 version: "v1".into(),
419 detail,
420 });
421 }
422 if !extra.is_empty() {
423 let mut detail = String::from(name);
424 detail.push_str(": engenho extra verbs ");
425 detail.push_str(&join_refs(&extra));
426 out.push(Divergence::DiscoveryDiff {
427 group: String::new(),
428 version: "v1".into(),
429 detail,
430 });
431 }
432 let e_short = str_set(eng.get("shortNames"));
434 let k_short = str_set(k3s.get("shortNames"));
435 if e_short != k_short {
436 let mut detail = String::from(name);
437 detail.push_str(": shortNames differ (engenho ");
438 detail.push_str(&join_set(&e_short));
439 detail.push_str(", k3s ");
440 detail.push_str(&join_set(&k_short));
441 detail.push(')');
442 out.push(Divergence::DiscoveryDiff {
443 group: String::new(),
444 version: "v1".into(),
445 detail,
446 });
447 }
448}
449
450fn fmt_opt_bool(b: Option<bool>) -> String {
451 match b {
452 Some(true) => "true".into(),
453 Some(false) => "false".into(),
454 None => "unset".into(),
455 }
456}
457
458fn str_set(v: Option<&Value>) -> BTreeSet<String> {
459 v.and_then(Value::as_array)
460 .map(|a| {
461 a.iter()
462 .filter_map(Value::as_str)
463 .map(str::to_string)
464 .collect()
465 })
466 .unwrap_or_default()
467}
468
469fn join_refs(items: &[&String]) -> String {
470 let mut out = String::from("[");
471 for (i, s) in items.iter().enumerate() {
472 if i > 0 {
473 out.push_str(", ");
474 }
475 out.push_str(s);
476 }
477 out.push(']');
478 out
479}
480
481fn join_set(items: &BTreeSet<String>) -> String {
482 let refs: Vec<&String> = items.iter().collect();
483 join_refs(&refs)
484}
485
486impl Verdict {
488 pub(crate) fn parity() -> Self {
489 Self::Parity(crate::verdict::ParityWitness::new())
490 }
491}
492
493#[cfg(test)]
494mod tests {
495 use super::*;
496 use crate::normalize::volatile_meta;
497 use serde_json::json;
498
499 fn obs(status: u16, json: Value) -> Observation {
500 Observation {
501 status,
502 content_type: Some("application/json".into()),
503 json,
504 }
505 }
506
507 fn get_cm() -> Operation {
508 Operation::get_configmap("ns", "cm")
509 }
510
511 #[test]
512 fn identical_objects_are_parity() {
513 let norm = volatile_meta();
514 let body = json!({"kind": "ConfigMap", "metadata": {"name": "cm"}, "data": {"a": "b"}});
515 let d = diff_observations(&get_cm(), &obs(200, body.clone()), &obs(200, body), &norm);
516 assert!(d.is_empty(), "identical bodies must be parity, got {d:?}");
517 }
518
519 #[test]
520 fn masked_fields_do_not_diverge() {
521 let norm = volatile_meta();
522 let eng = json!({"metadata": {"name": "cm", "resourceVersion": "7"}, "data": {"a": "b"}});
523 let k3s = json!({"metadata": {"name": "cm", "resourceVersion": "90210", "uid": "abc",
524 "creationTimestamp": "2026-01-01T00:00:00Z"}, "data": {"a": "b"}});
525 let d = diff_observations(&get_cm(), &obs(200, eng), &obs(200, k3s), &norm);
526 assert!(d.is_empty(), "volatile meta must be masked, got {d:?}");
527 }
528
529 #[test]
530 fn missing_default_and_extra_field_detected() {
531 let norm = volatile_meta();
532 let eng = json!({"metadata": {"name": "ns", "finalizers": ["kubernetes"]}});
534 let k3s = json!({"metadata": {"name": "ns", "labels": {"kubernetes.io/metadata.name": "ns"}},
535 "spec": {"finalizers": ["kubernetes"]}});
536 let d = diff_observations(
537 &Operation::get_namespace("ns"),
538 &obs(200, eng),
539 &obs(200, k3s),
540 &norm,
541 );
542 let sigs: BTreeSet<String> = d.iter().map(Divergence::signature).collect();
543 assert!(
544 sigs.contains("MissingDefault:.spec"),
545 "want MissingDefault .spec, got {sigs:?}"
546 );
547 assert!(sigs.contains("MissingDefault:.metadata.labels"));
548 assert!(sigs.contains("ExtraField:.metadata.finalizers:engenho"));
549 }
550
551 #[test]
552 fn put_verb_probe_becomes_missing_verb() {
553 let norm = volatile_meta();
554 let op = Operation::replace_configmap("ns", "cm", json!({}));
555 let d = diff_observations(&op, &obs(400, json!({})), &obs(200, json!({})), &norm);
557 assert_eq!(d.len(), 1);
558 assert_eq!(d[0].signature(), "MissingVerb:v1/configmaps:update:k3s");
559 assert_eq!(d[0].owning_crate(), "engenho-apiserver");
560 }
561
562 #[test]
563 fn agreeing_status_is_parity() {
564 let norm = volatile_meta();
565 let d = diff_observations(&get_cm(), &obs(404, json!({})), &obs(404, json!({})), &norm);
567 assert!(d.is_empty());
568 let op = Operation::merge_patch_configmap("ns", "cm", json!({}));
570 let d = diff_observations(&op, &obs(500, json!({})), &obs(200, json!({})), &norm);
571 assert_eq!(d.len(), 1);
572 assert!(matches!(d[0], Divergence::StatusCodeDiff { .. }));
573 }
574
575 #[test]
576 fn discovery_missing_verbs_detected() {
577 let eng = json!({"resources": [
578 {"name": "configmaps", "namespaced": true, "kind": "ConfigMap", "verbs": ["get", "list", "create"]},
579 {"name": "namespaces", "namespaced": false, "kind": "Namespace", "verbs": ["get", "list"]},
580 ]});
581 let k3s = json!({"resources": [
582 {"name": "configmaps", "namespaced": true, "kind": "ConfigMap", "verbs": ["get", "list", "create", "update", "patch", "delete"], "shortNames": ["cm"]},
583 {"name": "namespaces", "namespaced": false, "kind": "Namespace", "verbs": ["get", "list"], "shortNames": ["ns"]},
584 {"name": "namespaces/status", "namespaced": false, "kind": "Namespace"},
585 ]});
586 let op = Operation::discovery_core_v1();
587 let d = diff_observations(&op, &obs(200, eng), &obs(200, k3s), &Normalizer::new());
588 let sigs: Vec<String> = d.iter().map(Divergence::signature).collect();
589 assert!(
590 sigs.iter().any(|s| s.contains("engenho missing verbs")),
591 "want a missing-verbs discovery diff, got {sigs:?}"
592 );
593 assert!(
594 d.iter()
595 .any(|x| matches!(x, Divergence::MissingSubresource { .. })),
596 "want namespaces/status subresource gap, got {d:?}"
597 );
598 }
599
600 #[tokio::test]
603 async fn two_mock_clients_feed_the_differ() {
604 use engenho_kube_client::mock::MockKubeClient;
605 use engenho_types::client::KubeClient;
606
607 let a = MockKubeClient::new();
608 let b = MockKubeClient::new();
609 let pod = toy::pod("p", "default", "img:1");
610 let ca = a.create(&pod).await.unwrap();
611 let cb = b.create(&pod).await.unwrap();
612 let norm = volatile_meta();
613 let d = diff_observations(
614 &get_cm(),
615 &obs(200, serde_json::to_value(&ca).unwrap()),
616 &obs(200, serde_json::to_value(&cb).unwrap()),
617 &norm,
618 );
619 assert!(
620 d.is_empty(),
621 "identical mock objects must be parity, got {d:?}"
622 );
623
624 let cb2 = b.create(&toy::pod("p2", "default", "img:2")).await.unwrap();
626 let ca2 = a.create(&toy::pod("p2", "default", "img:1")).await.unwrap();
627 let d2 = diff_observations(
628 &get_cm(),
629 &obs(200, serde_json::to_value(&ca2).unwrap()),
630 &obs(200, serde_json::to_value(&cb2).unwrap()),
631 &norm,
632 );
633 assert!(
634 d2.iter().any(|x| matches!(x, Divergence::FieldDiff { .. })),
635 "want a FieldDiff on the mutated image, got {d2:?}"
636 );
637 }
638
639 mod toy {
641 use engenho_types::kind::{GroupVersionKind, GroupVersionResource, KubeResource, Scope};
642 use serde::{Deserialize, Serialize};
643
644 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
645 pub struct ToyPod {
646 pub metadata: engenho_types::meta::ObjectMeta,
647 pub spec: ToySpec,
648 }
649 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
650 pub struct ToySpec {
651 pub image: String,
652 }
653 impl KubeResource for ToyPod {
654 const GVK: GroupVersionKind = GroupVersionKind {
655 group: "",
656 version: "v1",
657 kind: "ToyPod",
658 };
659 const GVR: GroupVersionResource = GroupVersionResource {
660 group: "",
661 version: "v1",
662 resource: "toypods",
663 };
664 const SCOPE: Scope = Scope::Namespaced;
665 fn name(&self) -> std::borrow::Cow<'_, str> {
666 self.metadata.name.as_str().into()
667 }
668 fn namespace(&self) -> Option<std::borrow::Cow<'_, str>> {
669 self.metadata.namespace.as_deref().map(Into::into)
670 }
671 fn resource_version(&self) -> Option<std::borrow::Cow<'_, str>> {
672 if self.metadata.resource_version.is_empty() {
673 None
674 } else {
675 Some(self.metadata.resource_version.as_str().into())
676 }
677 }
678 }
679 pub fn pod(name: &str, ns: &str, image: &str) -> ToyPod {
680 ToyPod {
681 metadata: engenho_types::meta::ObjectMeta {
682 name: name.into(),
683 namespace: Some(ns.into()),
684 ..Default::default()
685 },
686 spec: ToySpec {
687 image: image.into(),
688 },
689 }
690 }
691 }
692}