mesh.verify

{
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty",
  "type": "object"
}

{
  "$defs": {
    "LinkState": {
      "description": "A link's standing, from this runtime's side. It is a statement about a connection and\nnever about the peer: a runtime reachable only through a third party is `Expired` here\nwhile its streams beat on everywhere, which is why claims follow streams and not this.\n\nThe variants are ordered by how far the link has fallen, so the worst link in a table\nis the maximum and a reader never has to rank them by hand.\n\n```\nuse majordomus_cli::mesh::cooperation::LinkState;\n\nlet table = [LinkState::Connected, LinkState::Unreachable, LinkState::Degraded];\nassert_eq!(table.iter().max(), Some(&LinkState::Unreachable), \"the worst link shows\");\nassert_eq!(serde_json::to_value(LinkState::Connected).unwrap(), \"connected\");\n```",
      "oneOf": [
        {
          "const": "connecting",
          "description": "Handshaking, or never yet exchanged.",
          "type": "string"
        },
        {
          "const": "connected",
          "description": "An exchange within two heartbeats.",
          "type": "string"
        },
        {
          "const": "degraded",
          "description": "Rounds are failing; the last exchange is under half the expiry old.",
          "type": "string"
        },
        {
          "const": "unreachable",
          "description": "The last exchange is over half the expiry old; the link is about to expire.",
          "type": "string"
        },
        {
          "const": "expired",
          "description": "No exchange within the expiry: the link is dropped and will be re-dialed.",
          "type": "string"
        }
      ]
    },
    "MeshVerifyCheck": {
      "description": "One verification check: what was checked, whether it holds, the evidence, and — when\nsomething is wrong or limited — the impact and what to do about it.\n\nThe impact and the remedy are carried with the verdict rather than left to whoever\nrenders it, so that a failing check is actionable wherever it is read — in a terminal,\nin a JSON answer, or by an agent that has never seen the mesh before. A check that\nholds carries neither, because there is nothing to do.\n\n```\n# use std::sync::Arc;\n# use majordomus_cli::mesh::config::{CooperationConfig, TrustConfig};\n# use majordomus_cli::mesh::cooperation::{CheckoutFacts, Cooperation, CooperationSetup};\n# use majordomus_cli::mesh::identity::NodeIdentity;\n# use majordomus_cli::mesh::link::HttpTransport;\n# use majordomus_cli::mesh::registry::MeshRegistry;\n# use majordomus_cli::mesh::repository::of_root_commits;\n# let cooperation = Cooperation::new(CooperationSetup {\n#     identity: Arc::new(NodeIdentity::ephemeral().unwrap()), runtime: \"0000000000000001\".into(),\n#     repository: of_root_commits(&[\"root\".into()]), endpoints: vec![\"127.0.0.1:9\".into()],\n#     version: \"doc\".into(), config: CooperationConfig::default(), trust: TrustConfig::default(),\n#     journal_path: None, registry: Arc::new(MeshRegistry::new()),\n#     transport: Arc::new(HttpTransport), board: None, checkout: CheckoutFacts::default(),\n# }).unwrap();\nuse majordomus_cli::mesh::cooperation::MeshVerifyCheck;\n\nlet report = cooperation.verify();\nlet first: &MeshVerifyCheck = &report.checks[0];\nassert_eq!(first.check, \"cooperation\");\nassert!(first.detail.contains(cooperation.runtime_key()), \"the evidence, not a verdict\");\nassert!(first.remediation.is_none(), \"a check that holds asks for nothing\");\n```",
      "properties": {
        "check": {
          "description": "What was checked.",
          "type": "string"
        },
        "detail": {
          "description": "The evidence.",
          "type": "string"
        },
        "impact": {
          "description": "What the failure or limitation means for cooperation.",
          "type": [
            "string",
            "null"
          ]
        },
        "ok": {
          "description": "Whether it holds.",
          "type": "boolean"
        },
        "remediation": {
          "description": "What to do.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "check",
        "ok",
        "detail"
      ],
      "type": "object"
    },
    "PeerVerdict": {
      "description": "What one sync round, run now rather than remembered, said about one peer. Verification\ndoes not report the link's standing and stop there: it exchanges with the peer and says\nwhether the exchange worked and whether both sides ended holding the same marks, which\nis the difference between a peer that answers and a peer that agrees.\n\n`round_trip` and `converged` are optional because a peer this runtime does not dial is\nnot asked — an absent answer is not a failed one, and reporting `false` there would\nmake an inbound-only link look broken every time.\n\n```\n# use std::collections::BTreeMap;\n# use std::sync::{Arc, Mutex, Weak};\n# use majordomus_cli::mesh::config::{CooperationConfig, TrustConfig};\n# use majordomus_cli::mesh::cooperation::*;\n# use majordomus_cli::mesh::identity::NodeIdentity;\n# use majordomus_cli::mesh::link::{LinkReply, LinkTransport, Signed, HELLO_PATH};\n# use majordomus_cli::mesh::registry::MeshRegistry;\n# use majordomus_cli::mesh::repository::{of_root_commits, runtime_id};\n# use majordomus_cli::mesh::trust::TrustPolicy;\n# #[derive(Default)] struct Net(Mutex<BTreeMap<String, Weak<Cooperation>>>);\n# impl LinkTransport for Net {\n#   fn post(&self, e: &str, p: &str, m: &Signed) -> Result<LinkReply, String> {\n#     let peer = (self.0.lock().unwrap().get(e).and_then(Weak::upgrade))\n#         .ok_or_else(|| format!(\"{e}: nobody there\"))?;\n#     Ok(if p == HELLO_PATH { peer.accept_hello(m) } else { peer.accept_sync(m) }) } }\n# let net = Arc::new(Net::default());\n# let runtime = |endpoint: &str| { let c = Cooperation::new(CooperationSetup {\n#     identity: Arc::new(NodeIdentity::ephemeral().unwrap()), runtime: runtime_id(endpoint),\n#     repository: of_root_commits(&[\"root\".into()]), endpoints: vec![endpoint.into()],\n#     version: \"doc\".into(), config: CooperationConfig::default(),\n#     trust: TrustConfig { policy: TrustPolicy::Tofu, allow: vec![] }, journal_path: None,\n#     registry: Arc::new(MeshRegistry::new()),\n#     transport: Arc::clone(&net) as Arc<dyn LinkTransport>, board: None,\n#     checkout: CheckoutFacts::default() }).unwrap();\n#   net.0.lock().unwrap().insert(endpoint.into(), Arc::downgrade(&c)); c };\n# let (a, b) = (runtime(\"a:1\"), runtime(\"b:1\"));\na.dial(&[\"b:1\".into()]).unwrap();\n\nlet dialer: &PeerVerdict = &a.verify().peers[0];\nassert_eq!(dialer.round_trip, Some(true), \"asked, and answered\");\n\nlet answerer = &b.verify().peers[0];\nassert!(!answerer.dialed, \"B does not dial A, so B asks nothing of it\");\nassert_eq!(answerer.round_trip, None, \"and reports no verdict it did not earn\");\n```",
      "properties": {
        "converged": {
          "description": "Whether both sides hold the same high-water mark of every stream after the round.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "detail": {
          "description": "What happened.",
          "type": "string"
        },
        "dialed": {
          "description": "Whether this runtime dials the peer (and so ran a round with it now).",
          "type": "boolean"
        },
        "round_trip": {
          "description": "Whether the round succeeded; `None` when the peer dials this runtime instead.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "rtt_ms": {
          "description": "The round trip, milliseconds.",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "runtime": {
          "description": "The peer's runtime key.",
          "type": "string"
        },
        "state": {
          "$ref": "#/$defs/LinkState",
          "description": "The link's standing after the round."
        }
      },
      "required": [
        "runtime",
        "state",
        "dialed",
        "detail"
      ],
      "type": "object"
    }
  },
  "description": "What `mesh verify` found: the local checks, every peer's round, and the state digest\nafterwards. The digest is what makes the report worth running on two machines — two\nruntimes that print the same digest have the same sessions, claims, handovers and\nreviews, and two that do not have something to reconcile, whatever their links say.\n\n`ok` is the conjunction of everything below it, so a caller may act on the one field\nand a person may read the rest to find out which part of it was false.\n\n```\n# use std::sync::Arc;\n# use majordomus_cli::mesh::config::{CooperationConfig, TrustConfig};\n# use majordomus_cli::mesh::cooperation::{CheckoutFacts, Cooperation, CooperationSetup};\n# use majordomus_cli::mesh::identity::NodeIdentity;\n# use majordomus_cli::mesh::link::HttpTransport;\n# use majordomus_cli::mesh::registry::MeshRegistry;\n# use majordomus_cli::mesh::repository::of_root_commits;\n# let cooperation = Cooperation::new(CooperationSetup {\n#     identity: Arc::new(NodeIdentity::ephemeral().unwrap()), runtime: \"0000000000000001\".into(),\n#     repository: of_root_commits(&[\"root\".into()]), endpoints: vec![\"127.0.0.1:9\".into()],\n#     version: \"doc\".into(), config: CooperationConfig::default(), trust: TrustConfig::default(),\n#     journal_path: None, registry: Arc::new(MeshRegistry::new()),\n#     transport: Arc::new(HttpTransport), board: None, checkout: CheckoutFacts::default(),\n# }).unwrap();\nuse majordomus_cli::mesh::cooperation::MeshVerifyReport;\n\nlet report: MeshVerifyReport = cooperation.verify();\nassert_eq!(report.runtime.as_deref(), Some(cooperation.runtime_key()));\nassert_eq!(report.digest, Some(cooperation.state().digest), \"what a peer is compared to\");\nassert_eq!(report.ok, report.checks.iter().all(|c| c.ok), \"one field for every check\");\n```",
  "properties": {
    "checks": {
      "description": "The checks, in the order they ran.",
      "items": {
        "$ref": "#/$defs/MeshVerifyCheck"
      },
      "type": "array"
    },
    "digest": {
      "description": "The state digest after the rounds.",
      "type": [
        "string",
        "null"
      ]
    },
    "ok": {
      "description": "Whether every check holds and every round succeeded.",
      "type": "boolean"
    },
    "peers": {
      "description": "Every linked peer's verdict.",
      "items": {
        "$ref": "#/$defs/PeerVerdict"
      },
      "type": "array"
    },
    "runtime": {
      "description": "This runtime.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "ok",
    "checks",
    "peers"
  ],
  "title": "MeshVerifyReport",
  "type": "object"
}