mesh.status

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

{
  "type": "object",
  "properties": {
    "active": {
      "type": "boolean",
      "description": "Whether the mesh is running in this process."
    },
    "reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why not, when it is not: no declaration, disabled, no identity, stopped."
    },
    "identity": {
      "anyOf": [
        {
          "$ref": "#/$defs/PublicIdentity"
        },
        {
          "type": "null"
        }
      ],
      "description": "This node, when the mesh has an identity."
    },
    "trust_policy": {
      "type": [
        "string",
        "null"
      ],
      "description": "The trust policy in force."
    },
    "providers": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ProviderStatus"
      },
      "description": "Every provider, canonical order (by id)."
    },
    "tallies": {
      "$ref": "#/$defs/Tallies",
      "description": "The registry's tallies."
    },
    "refusals": {
      "$ref": "#/$defs/Refusals",
      "description": "Refused datagrams, by reason."
    },
    "started_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the mesh started, RFC 3339."
    }
  },
  "required": [
    "active",
    "providers",
    "tallies",
    "refusals"
  ],
  "description": "The whole mesh, as every surface reports it.",
  "title": "MeshStatus",
  "$defs": {
    "PublicIdentity": {
      "type": "object",
      "properties": {
        "node_id": {
          "$ref": "#/$defs/NodeId",
          "description": "The node id: a digest of the public key."
        },
        "public_key": {
          "type": "string",
          "description": "The Ed25519 public key, 64 hex characters. Whoever holds the matching secret is\nthis node; there is no other proof."
        },
        "display_name": {
          "type": "string",
          "description": "A human name for the node, from the identity file; defaults to the first eight\ncharacters of the node id. Presentation only — never used for trust."
        },
        "instance_id": {
          "$ref": "#/$defs/InstanceId",
          "description": "This run of the node."
        }
      },
      "required": [
        "node_id",
        "public_key",
        "display_name",
        "instance_id"
      ],
      "description": "What everyone may know about this node: the id, the public key, a display name and\nthis run's instance. Everything an advertisement carries; nothing that signs."
    },
    "NodeId": {
      "type": "string",
      "description": "The stable identity of a node: 32 hex characters of the SHA-256 of its Ed25519 public\nkey. Derived, never chosen: two nodes with one id hold one key."
    },
    "InstanceId": {
      "type": "string",
      "description": "One run of a node: 16 hex characters of OS entropy, new at every process start. A\nrestart keeps the node id and changes this, which is how a reader tells \"the same\nnode came back\" from \"the same process is still there\"."
    },
    "ProviderStatus": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The provider id: `udp_multicast`, `udp_broadcast`, `rendezvous`, `synthetic`."
        },
        "state": {
          "$ref": "#/$defs/MeshProviderState",
          "description": "The state."
        },
        "detail": {
          "type": [
            "string",
            "null"
          ],
          "description": "Why, when `Failed`; what it watches, when `Running`."
        },
        "sent": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Advertisements transmitted."
        },
        "received": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Datagrams heard and handed to the manager."
        }
      },
      "required": [
        "id",
        "state",
        "sent",
        "received"
      ],
      "description": "One provider's status: state, why, and its counters."
    },
    "MeshProviderState": {
      "oneOf": [
        {
          "type": "string",
          "const": "running",
          "description": "Threads up, socket bound (where the provider has one)."
        },
        {
          "type": "string",
          "const": "failed",
          "description": "The provider could not start or died; `ProviderStatus::detail` says why. One\nprovider failing never stops another — failure isolation is the contract."
        },
        {
          "type": "string",
          "const": "stopped",
          "description": "Stopped by the manager."
        }
      ],
      "description": "The provider's health, as every surface reports it."
    },
    "Tallies": {
      "type": "object",
      "properties": {
        "nodes": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Records held."
        },
        "trusted": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Of which trusted."
        },
        "present": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Of which present."
        },
        "accepted": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Observations accepted since start."
        },
        "replayed": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Replayed datagrams dropped since start."
        },
        "expired": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Records expired out since start."
        },
        "evicted": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Records evicted for space since start."
        }
      },
      "required": [
        "nodes",
        "trusted",
        "present",
        "accepted",
        "replayed",
        "expired",
        "evicted"
      ],
      "description": "The registry's tallies, for status and health."
    },
    "Refusals": {
      "type": "object",
      "properties": {
        "oversized": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Longer than the datagram bound."
        },
        "malformed": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Not an envelope."
        },
        "version": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "A protocol version this executable does not read."
        },
        "bounds": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Out-of-bounds fields."
        },
        "stale": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Outside the clock-skew window."
        },
        "signature": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "A signature that does not verify."
        },
        "self_heard": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "This node's own datagrams, heard back and skipped."
        },
        "overflow": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Observations dropped because the queue to the registry was full: a flood, counted\nrather than held (I2133).",
          "default": 0
        }
      },
      "required": [
        "oversized",
        "malformed",
        "version",
        "bounds",
        "stale",
        "signature",
        "self_heard"
      ],
      "description": "Refused datagrams, by reason. The diagnosis of a hostile or misconfigured network:\na mesh that hears garbage says so, with numbers, instead of being quietly empty."
    }
  }
}