Non-Destructive Hot-Reconciliation =================================== Fleetmesh is designed for continuous operation in mission-critical and edge networking environments. Modifying network topologies, bandwidth allocations, or peering policies must never require daemon restarts or cause in-flight cryptographic sessions to abort. The `meshctl apply` command implements **non-destructive hot-reconciliation**, aligning active runtime state with desired manifest declarations without dropping active QUIC connections or interrupting sessions. Reconciliation Architecture --------------------------- The diagram below illustrates the reconciliation pipeline between `meshctl` and the `meshnode` daemon: .. code-block:: text ┌────────────────────────────────┐ │ Declarative Manifests (.yaml) │ │ - Peering │ │ - GrantPolicy │ │ - ComputeProvider │ └───────────────┬────────────────┘ │ ▼ ┌────────────────────────────────┐ │ meshctl apply │ │ 1. Parse & validate apiVersion │ │ 2. Check diff against live │ │ 3. Compute surgical updates │ └───────────────┬────────────────┘ │ ▼ (meshnode-control/1 IPC) ┌────────────────────────────────┐ │ meshnode Host Daemon │ │ ├─ PeeringManager │ ◄── Updates budget & policy in-place │ ├─ IrohTransport (QUIC) │ ◄── Keeps active TLS/QUIC sessions alive │ └─ GrantStore │ ◄── Inserts/amends bilateral grants └────────────────────────────────┘ Reconciliation Mechanics ------------------------ 1. Manifest Ingestion & Schema Checking ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When `meshctl apply -f ` is invoked: - `meshctl` deserializes YAML manifests into strongly typed internal structures. - It validates the ``apiVersion``. Normative manifests require ``apiVersion: fleetmesh.org/v1alpha1``. Legacy ``meshstr.org/v1alpha1`` manifests trigger a warning recommending ``meshctl convert``. - Validates required metadata (``name``, ``namespace``) and spec attributes. 2. Socket Negotiation (meshnode-control/1) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `meshctl` locates the daemon's control socket: - By default, checks ``/var/lib/fleetmesh/meshnode.sock`` or the directory specified with ``--dir``. - Connects using standard Unix domain socket semantics. - Executes an initial handshake querying daemon health and active state. 3. Granular In-Flight Mutators ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Depending on the manifest ``kind``, `meshctl` issues targeted control commands rather than restarting subsystems: - **``Peering`` manifests**: - `meshctl` maps the spec to the ``peer`` control verb: .. code-block:: json { "peer": "did:key:z6Mkh...", "transport": "iroh", "ingress": { "max_rate_bytes": 10485760 }, "egress": { "kinds": [11801, 21801, 31801] }, "budget": { "sat_ceiling": 50000 } } - The `PeeringManager` in `meshnode` inspects active session pools. If an Iroh QUIC connection or WebSocket session is currently open with that peer, it updates the ingress/egress filters and rate limiters **in memory**. - No connection handshake is re-triggered, and open multiplexed streams continue transferring data without packet loss. - **``GrantPolicy`` manifests**: - Dispatches updates directly to the node's ``trust`` control interface. - Automatically updates the bilateral trust store (``grants.sqlite``), updating credit ceilings and payment schedules without blocking database transactions. Offline Staging Fallback ------------------------ If the `meshnode` daemon is not currently running (e.g., during machine provisioning or system boot): - `meshctl apply` detects that the Unix domain socket is inactive. - Instead of failing, it logs a notice and performs **offline config staging**: - Reads existing ``config.json`` in the node data directory, safely merges the manifest declarations into the configuration, and writes the updated state to disk atomically. - When `meshnode` subsequently boots, it initializes with the newly applied declarative state. Dry-Run Simulation ------------------ Operators and CI/CD pipelines can evaluate the impact of changes prior to applying them using the ``--dry-run`` flag: .. code-block:: sh meshctl apply -f manifests/peering.yaml --dry-run In dry-run mode: - All schema validations and property checks are executed. - The control socket status is queried to ensure connectivity. - A simulated reconciliation plan is printed to stdout detailing each resource that would be updated, added, or retained. - Zero mutations are applied to either memory or disk.