Source code for fleetmesh_node.meshnode

#!/usr/bin/env python3
"""meshnode: the operator's command.

<!-- commands:begin -->
    meshnode init DIR                       generate keys, write config, mine and publish the descriptor
    meshnode run DIR                        start the node and tick until SIGTERM
    meshnode status DIR                     what the running node last wrote, and its trouble
    meshnode health DIR                     every error plane: relays, drops, rejections, failures
    meshnode whoami DIR                     the node's identity: DID, npub, keys, descriptor
    meshnode enrol DIR TOKEN                join a fleet with an fmenrol1 token minted for this node's pubkey
    meshnode network DIR ACTION NETWORK     ask an approved private network to admit this node
    meshnode visibility DIR                 show or set the node default public/private and per-app or per-protocol overrides
    meshnode check DIR                      is this directory a node that can run? exits 1 if not
    meshnode tick DIR                       one tick now, and what it did (needs the node running)
    meshnode api DIR                        the control socket described by itself: protocol, commands, arguments, replies
    meshnode peers DIR                      every peer: tiers, pending grant, last window, standing
    meshnode grant DIR PEER                 both grants with a peer, their history, and what waits for the boundary
    meshnode windows DIR PEER               the windows this node priced for a peer
    meshnode account DIR ACTION             everything billable, from the node's own stores: budget, settlement, sidecar sessions, storage
    meshnode peer DIR PEER                  add a peer and shard to pull from
    meshnode unpeer DIR PEER                stop pulling from a peer; the grants stay live
    meshnode trust DIR PEER                 inspect or set a peer's tier, which nothing else can raise
    meshnode terminate DIR PEER             end a peering: zero both grants and tell the peer (needs the node running)
    meshnode retire DIR                     leave the mesh in order: hand over every asserted shard, withdraw the claims, stop
    meshnode withdraw DIR PEER WINDOW       withdraw a finding this node made about one window (needs the node running)
    meshnode standing DIR PEER TARGET       ask a peer what it knows about a third node (needs the node running)
    meshnode reports DIR TARGET             the kind 30802s about a node, weighed by this one (needs the node running)
    meshnode strain DIR                     what this node has survived, by direction, and the reserves it sets
    meshnode subsystems DIR                 every compartment of this node, and what each has refused
    meshnode refusals DIR                   every no this node said, across every compartment
    meshnode events DIR                     the node's recent bus events, from memory
    meshnode subscribe DIR                  follow the node's bus live, one line per event
    meshnode capacity DIR                   this node's own ceiling, the pressure on it, and what it is shedding
    meshnode scheduled DIR                  every scheduled pull, throttles and holds
    meshnode coverage DIR ACTION SHARD      the shards this node claims to hold, as kind 30803
    meshnode descriptor DIR                 the kind 11801 this node published
    meshnode pull DIR PEER SHARD            pull a shard from a peer now (needs the node running)
    meshnode bridge DIR ACTION              interact with the Universal Nostr Relay Bridge
    meshnode compute DIR ACTION             (experimental) inspect or interact with the compute market and order book
    meshnode dvm DIR ACTION                 (experimental) interact with the NIP-90 Data Vending Machine Gateway
    meshnode settle DIR ACTION              (experimental) inspect settlement rails, escrows, and execute live payments
    meshnode gossip DIR ACTION              (experimental) gossip/1.0 group topics: create and publish rosters, flood sealed wraps
    meshnode enclave DIR ACTION             (experimental) inspect and interact with hardware enclaves and passkeys
    meshnode iroh DIR ACTION                (experimental) iroh P2P QUIC transport diagnostics and control
    meshnode fips DIR ACTION                (experimental) FIPS Native Datagram API transport diagnostics and control
    meshnode cluster DIR CLUSTER_ACTION     manage a local multi-node testnet cluster
    meshnode nsite DIR ACTION               (experimental) host static sites (NIP-5A): publish this node's site, manage custom domains
    meshnode sidecars DIR ACTION            fronted sidecars (grasp, ncontainer, magpie, ...): self-test results, or run the tests now
    meshnode sidecar-manifest FILE          write, lint or try a sidecar manifest with no node (for sidecar authors)
    meshnode plugin-check REF               hold a plugin class to the rules the node applies at startup, with no node (for plugin authors)
<!-- commands:end -->

Two kinds of command. The ones that read state read the node directory, so
they work whether the node is running or not. The ones that change what the
node is told to do - peer, unpeer, trust, coverage - write config.json and
nothing else; a running node re-reads it every tick. The ones that need the
daemon itself - pull, terminate, withdraw, standing, reports, tick, republish - go over
the control socket in the directory, and say so when no node is running.

PEER may be a pubkey, a did:nostr, an npub, or an unambiguous prefix of a peer this
node holds a grant with.

`trust` is the only thing that raises a peer's tier. The severity ladder
lowers one and never raises it, because standing is bought with observed
time rather than granted by arithmetic; seeding a tier for a node you know
out of band is a human decision, recorded as a signed grant and reversible.
A peer left alone opens at probation, whose reporter weight is zero.

DIR holds keys.json (0600), config.json, descriptor.json, events.sqlite,
grants.sqlite, accounts.sqlite, status.json and, while the node runs, the
control socket.

The command table above sits between marker comments and is regenerated from
the parser by `scripts/check-cli.py --write`; the checker fails when it drifts.
The commands themselves live in fleetmesh_node/commands/*.py, one module per group; this
file only assembles the parser and is the `meshnode` entrypoint.
"""
from __future__ import annotations

import argparse
import os
import sys
from typing import Sequence

sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(os.path.abspath(__file__)), '..')))
from fleetmesh_node.commands import PROVIDERS, base, plugin_cli_classes, register_plugin_cli

TIERS: tuple[str, ...] = base.TIERS


[docs]def build_parser(argv: Sequence[str] | None = None) -> argparse.ArgumentParser: """The whole operator CLI. Separate from main() so a checker can walk it. `argv` lets the plugins a node directory declares add their verbs (fleetmesh_node/commands `register_plugin_cli`); without it the parser is the core CLI alone, which is what the documentation checker reads. """ ap = argparse.ArgumentParser(prog='meshnode', description=__doc__.split('\n\n')[0]) sub = ap.add_subparsers(dest='cmd', required=True) for provider in PROVIDERS: provider.register(sub) if argv is not None: register_plugin_cli(sub, plugin_cli_classes(argv)) return ap
[docs]def main(argv: Sequence[str] | None = None) -> None: a = build_parser(argv if argv is not None else sys.argv[1:]).parse_args(argv) code = a.fn(a) if isinstance(code, int) and code: sys.exit(code)
if __name__ == '__main__': main()