Source code for fleetmesh_node.commands.peering

"""Peering management, bilateral grants, accounting windows, and trust tiers."""
from __future__ import annotations

import argparse
import json
import os
import time
from typing import Any, Mapping, cast

from fleetmesh_node import app as app_mod
from fleetmesh_node.app import socket as control
from fleetmesh_node.storage import accounts as accounts_mod, grants as grants_mod
from . import account
from .base import (
    TIERS,
    _ask,
    _grants,
    _live,
    _peer,
    _status_file,
    _table,
    _when,
    add_command,
    emit,
    fail,
    load_json_arg,
)


def _peers_table(view: list) -> None:
    if not view:
        print('no peers: nothing granted and nothing held')
        return
    rows = []
    for v in view:
        last = v.get('last_evaluated') or {}
        standing = v.get('standing') or {}
        rows.append((v['peer'][:16], (v.get('issued') or {}).get('tier') or '-', (v.get('received') or {}).get('tier') or '-',
                     ('%s from %s' % (v['pending']['tier'], v['pending']['from_epoch'])) if v.get('pending') else '-',
                     ('%s %s' % (last.get('epoch'), last.get('severity'))) if last else '-',
                     ('%d clean / %d' % (standing['clean_windows'], standing['evaluated_windows'])) if standing else '-',
                     ','.join(v.get('pulls') or []) or '-',
                     ('%d' % len(v['shared'])) if v.get('shared') else '-',
                     ('other %s' % v['digest'][:8]) if v.get('digest') else 'same' if v.get('descriptor') else '-'))
    _table(('peer', 'issued', 'received', 'pending', 'last window', 'streak', 'pulling', 'shared', 'schema'), rows)
    for v in view:
        for n in v.get('notices') or []:
            print('%s: %s' % (v['peer'][:16], n))
        if v.get('not_shared'):
            print('%s: not shared with this node: %s' % (v['peer'][:16], ', '.join(v['not_shared'])))
    zeroed = [v for v in view if v.get('zeroed_until')]
    for v in zeroed:
        print('%s is zeroed after S3 until %s UTC' % (v['peer'][:16], time.strftime('%Y-%m-%d %H:%M', time.gmtime(v['zeroed_until']))))


[docs]def cmd_peers(a: argparse.Namespace) -> int: view = _live(a, 'peers', timeout=15) if view is None: # From disk: the grants and what the last status said. g = _grants(a.dir) st: Mapping[str, Any] = {} try: st = dict(_status_file(a.dir)) except SystemExit: pass cfg_peers: dict[str, list[str]] = {} try: for p in app_mod.load_config(a.dir).get('peers', []): cfg_peers.setdefault(p['pubkey'], []).append(p['shard']) except (OSError, ValueError): pass view = [] for pk in sorted({r['peer'] for r in g.list()}): issued, received, pend = g.get(pk, grants_mod.ISSUED), g.get(pk, grants_mod.RECEIVED), g.pending(pk) ev = [e for e in st.get('evaluations', []) if pk.startswith(e['peer'])] view.append({'peer': pk, 'issued': {'tier': issued['payload'].get('tier'), 'status': issued['status']} if issued else None, 'received': {'tier': received['payload'].get('tier'), 'status': received['status']} if received else None, 'pending': {'tier': pend['payload'].get('tier'), 'from_epoch': pend['decided_epoch'] + 1} if pend else None, 'last_evaluated': ev[-1] if ev else None, 'standing': None, 'zeroed_until': None, 'pulls': cfg_peers.get(pk, []), 'descriptor': None, 'shared': [], 'not_shared': [], 'digest': None, 'notices': []}) return emit(a, view, _peers_table)
[docs]def cmd_grant(a: argparse.Namespace) -> int: pk = _peer(a.dir, a.peer) out = app_mod.grant_view(_grants(a.dir), pk) if a.json: return emit(a, out) if out['issued'] is None and out['received'] is None: fail('no grant either way with %s' % pk[:16]) out_dict = cast(Mapping[str, Any], out) for direction in (grants_mod.ISSUED, grants_mod.RECEIVED): row = out_dict.get(direction) print('%s %s' % (direction, '(none)' if row is None else '')) if row is None: continue p = row['payload'] print(' envelope %s tier %s status %s window %ss receipt every %ss' % (row['envelope_id'][:16] + '…', p.get('tier'), row['status'], p.get('window'), (p.get('receipt') or ['?'])[0])) limits = p.get('limits') or {} print(' limits ' + ' '.join('%s %s' % (k, v) for k, v in sorted(limits.items()))) scope = p.get('scope') or {} print(' scope pull %s push %s' % (json.dumps(scope.get('pull')), json.dumps(scope.get('push')))) hist = out_dict.get(direction + '_history', []) if len(hist) > 1: print(' history ' + '; '.join('%s… %s from %s' % (h['envelope_id'][:8], h['tier'], h['effective_epoch']) for h in hist)) if out['pending']: p = out['pending'] print('waiting tier %s from window %s (%s UTC): %s' % (p['payload'].get('tier'), p['decided_epoch'] + 1, _when(p['decided_epoch'] + 1), p['note'])) if out['seed_applied']: print('seed %s, decided at %s' % (out['seed_applied'][0], time.strftime('%Y-%m-%d %H:%M UTC', time.gmtime(out['seed_applied'][1])) if out['seed_applied'][1] else 'time zero')) return 0
[docs]def cmd_windows(a: argparse.Namespace) -> int: pk = _peer(a.dir, a.peer) path = os.path.join(a.dir, 'accounts.sqlite') if not os.path.exists(path): fail('no accounts.sqlite yet: nothing has been metered') # Through the store, not a bare sqlite3 connection: `windows_view` already # prefers `_all` when it is given one, and a store reaches whatever backend # is configured. readonly=True keeps exactly what the direct connection # gave - no writes, no schema, no WAL writer lock beside a running node. acc = accounts_mod.AccountStore(path, readonly=True) try: out = app_mod.windows_view(acc, pk, a.last) finally: acc.close() rows = [] for rec in out: m, cl = rec['measured'], rec['claimed'] or {} rows.append((rec['epoch'], _when(rec['epoch'] + 1), rec['severity'] or 'not evaluated', '%s/%s' % (m.get('req', 0), cl.get('req', '-')), '%s/%s' % (m.get('events_in', 0), cl.get('events_in', '-')), '%s/%s' % (m.get('bytes_in', 0), cl.get('bytes_in', '-')), rec['receipts_in'], rec['my_receipts_sent'])) if a.json: return emit(a, out) if not rows: fail('no windows metered with %s' % pk[:16]) print('windows with %s (measured/claimed, in the issuer frame)' % pk[:16]) _table(('window', 'closed UTC', 'severity', 'req', 'events_in', 'bytes_in', 'receipts in', 'sent'), rows) return 0
[docs]def cmd_peer(a: argparse.Namespace) -> int: cfg = dict(app_mod.load_config(a.dir)) pk = _peer(a.dir, a.peer) filt = load_json_arg(a.filter, '--filter') if not isinstance(filt, dict): fail('--filter must be a nostr filter object') if a.every < 1: fail('--every must be a positive number of seconds') entry = {'pubkey': pk, 'shard': a.shard, 'filter': filt, 'pull_every': a.every} others = [p for p in cfg.get('peers', []) if (p['pubkey'], p['shard']) != (pk, a.shard)] if entry in cfg.get('peers', []): # Already exactly this. Saying "will peer" here made every deploy pass # restart every node, which on a public mesh is a round of farewells, # replays and conn_rate refusals for nothing. return emit(a, {'action': 'peer', 'peer': pk, 'shard': a.shard, 'every': a.every, 'peers_configured': len(cfg['peers']), 'changed': False}, lambda _: print('already peered with %s for shard %s; %d peers configured' % (pk[:16], a.shard, len(cfg['peers'])))) cfg['peers'] = others + [entry] app_mod.save_config(a.dir, cfg) return emit(a, {'action': 'peer', 'peer': pk, 'shard': a.shard, 'every': a.every, 'peers_configured': len(cfg['peers']), 'changed': True}, lambda _: print('will peer with %s for shard %s on the next %s; %d peers configured' % (pk[:16], a.shard, 'tick' if control.running(a.dir) else 'run', len(cfg['peers']))))
[docs]def cmd_unpeer(a: argparse.Namespace) -> int: cfg = dict(app_mod.load_config(a.dir)) pk = _peer(a.dir, a.peer) before = len(cfg.get('peers', [])) cfg['peers'] = [p for p in cfg.get('peers', []) if p['pubkey'] != pk or (a.shard and p['shard'] != a.shard)] app_mod.save_config(a.dir, cfg) n = before - len(cfg['peers']) if not n: fail('%s was not being pulled from' % pk[:16]) return emit(a, {'action': 'unpeer', 'peer': pk, 'shard': a.shard, 'shards_removed': n, 'peers_configured': len(cfg['peers'])}, lambda _: print('stopped pulling %d shard(s) from %s; the grants stay live (`terminate` ends the peering)' % (n, pk[:16])))
def _trust_table(st: dict) -> None: decided = st['decided'] if not decided: print('no operator trust decisions recorded') return print('%-16s %-12s %-12s %-12s %s' % ('peer', 'decided', 'held', 'state', 'when')) for pk, d in sorted(decided.items()): when = time.strftime('%Y-%m-%d %H:%M', time.gmtime(d['at'])) if d.get('at') else 'initial' print('%-16s %-12s %-12s %-12s %s' % (pk[:16], d.get('tier', '-'), str(d.get('held') or '-'), d.get('state', '-'), when)) print('\nin force: %d pending: %d overridden: %d waiting: %d' % ( st.get('in_force', 0), len(st.get('pending') or []), len(st.get('overridden') or []), len(st.get('waiting') or [])))
[docs]def cmd_trust(a: argparse.Namespace) -> int: """The one decision that raises a tier, and it is a person's.""" if not getattr(a, 'tier', None): st = _live(a, 'trust') if st is None: cfg = app_mod.load_config(a.dir) trust_cfg = dict(cfg.get('trust') or {}) st = { 'decided': { pk[:16]: { 'tier': e.get('tier') if isinstance(e, dict) else e, 'at': e.get('at', 0) if isinstance(e, dict) else 0, 'held': None, 'state': 'offline', } for pk, e in trust_cfg.items() }, 'in_force': 0, 'pending': [], 'overridden': [], 'waiting': [pk[:16] for pk in trust_cfg], } decided = st.get('decided') or {} if getattr(a, 'peer', None): pk_filter = _peer(a.dir, a.peer) decided = {k: v for k, v in decided.items() if k == pk_filter[:16] or k == pk_filter} out = dict(st) out['decided'] = decided return emit(a, out, _trust_table) if not getattr(a, 'peer', None): fail('meshnode trust: error: setting a tier requires a peer') cfg = dict(app_mod.load_config(a.dir)) pk = _peer(a.dir, a.peer) trust = dict(cfg.get('trust') or {}) trust[pk] = {'tier': a.tier, 'at': int(time.time())} cfg['trust'] = trust app_mod.save_config(a.dir, cfg) def seeded(_: dict) -> None: print('%s is %s' % (pk[:16], a.tier)) if _grants(a.dir).get(pk, 'issued') is None: print(' no grant issued to it yet; it will open at %s when you peer' % a.tier) else: print(' the live grant will be re-issued at %s at the next window boundary' % a.tier) return emit(a, {'peer': pk, 'tier': a.tier, 'at': trust[pk]['at']}, seeded)
[docs]def cmd_terminate(a: argparse.Namespace) -> int: pk = _peer(a.dir, a.peer) r = _ask(a.dir, 'terminate', peer=pk, reason=a.reason) def human(r: dict) -> None: told = r.get('told') or {} print('terminated the peering with %s (%s); both grants are zero here' % (pk[:16], r.get('reason'))) if 'error' in told: print(' the peer could not be told: %s' % told['error']) else: print(' told via %s' % ', '.join(u for u, v in told.items() if v[0]) or 'no relay accepted the message') if r.get('pulls_removed'): print(' %d scheduled pull(s) removed from the config' % r['pulls_removed']) return emit(a, r, human)
def _retired(r: dict) -> None: print('retiring: %s' % r.get('reason')) for d in r.get('did') or []: print(' %s' % ' '.join(str(x) for x in d)) print(' %d handover(s) to %d peer(s); %d claim(s) withdrawn' % (r.get('handed', 0), len(r.get('peers') or []), r.get('withdrawn', 0))) if r.get('revoked'): print(' the node key is revoked: a successor inherits nothing and starts on probation') else: print(' the key is NOT revoked; this node can be started again') print(' the node is stopping, and says farewell to every peer on the way out')
[docs]def cmd_retire(a: argparse.Namespace) -> int: """Leave the mesh in order. Not what a restart does.""" r = _ask(a.dir, 'retire', reason=a.reason, revoke=bool(a.revoke), lapses_in=a.lapses_in) return emit(a, r, _retired)
[docs]def cmd_withdraw(a: argparse.Namespace) -> int: pk = _peer(a.dir, a.peer) r = _ask(a.dir, 'withdraw', peer=pk, window=a.window, why=a.why) def human(r: dict | list) -> None: for row in (r if isinstance(r, list) else [r]): if row['was_published']: print('withdrew the report about %s for window %s (%s)' % (pk[:16], row['window'], row['report'][:16])) print(' the kind 30802 is not deleted; it carries its own expiration and lapses on it') else: print('withdrew the finding about %s for window %s; it had not been published' % (pk[:16], row['window'])) print(' the subject was told: %s' % row['why']) return emit(a, r, human)
[docs]def cmd_standing(a: argparse.Namespace) -> int: pk = _peer(a.dir, a.peer) target = _peer(a.dir, a.target) r = _ask(a.dir, 'standing', peer=pk, target=target) def human(r: dict) -> None: if r['answer'] == 'decline': print('%s declined to say: %s' % (pk[:16], (r['body'] or {}).get('reason'))) return b = r['body'] print('%s says of %s: tier %s, %s clean window(s) in a row, %s evaluated, %s' % (pk[:16], target[:16], b.get('tier'), b.get('clean_windows'), b.get('evaluated_windows'), 'has adverse reports' if b.get('has_adverse_reports') else 'no adverse reports')) return emit(a, r, human)
[docs]def cmd_reports(a: argparse.Namespace) -> int: target = _peer(a.dir, a.target) r = _ask(a.dir, 'reports', target=target, timeout=60) def human(r: dict) -> None: reps = r.get('reports') or [] if not reps: print('no kind 30802 about %s on this node\'s relays' % target[:16]) return _table(('reporter', 'severity', 'admissible', 'weight here', 'published UTC'), [(x['reporter'][:16], x['severity'], 'yes' if x['admissible'] else 'no: ' + '; '.join(x['reasons'])[:60], x['weight'], time.strftime('%Y-%m-%d %H:%M', time.gmtime(x['created_at']))) for x in reps]) print('\nthis node\'s view of %s, its own S0 weighed against them: %s' % (target[:16], r.get('view'))) return emit(a, r, human)
from ..config.parameter import Parameter from .adapter import add_parameter_argument PARAM_WIN_LAST = Parameter(key='last', name='last', description='how many, newest last (0 for all)', type=int, default=24) PARAM_PEER_SHARD = Parameter(key='shard', name='shard', description='shard name', type=str, default='', required=True) PARAM_PEER_FILTER = Parameter(key='filter', name='filter', description='a nostr filter, JSON or @file', type=str, default='', required=True) PARAM_PEER_EVERY = Parameter( key='every', name='every', description='seconds between pulls. The default is the probation connection ceiling: four an hour. It was 600, which is six, so a peering that used the shipped default overran the grant it was shipped with', type=int, default=900, ) PARAM_UNPEER_SHARD = Parameter(key='shard', name='shard', description='only this shard', type=str, default='') PARAM_TRUST_PEER = Parameter(key='peer', name='peer', description='the peer to seed a tier for (pubkey, did, npub or prefix)', type=str, default='', positional=True, required=False, nargs='?') PARAM_TRUST_TIER = Parameter(key='tier', name='tier', description='the tier to seed for this peer', type=str, default=None, choices=TIERS) PARAM_TERM_REASON = Parameter(key='reason', name='reason', description='reason for termination', type=str, default='operator') PARAM_RET_REASON = Parameter(key='reason', name='reason', description='reason for retirement', type=str, default='operator') PARAM_RET_REVOKE = Parameter(key='revoke', name='revoke', description='publish a kind 11802 as well: the key is retired for good and a successor inherits nothing', type=bool, default=False) PARAM_RET_LAPSES = Parameter(key='lapses_in', name='lapses_in', cli_name='--lapses-in', description='how long the withdrawn claims stay on the relays before they expire', type=int, default=86400) PARAM_WD_WINDOW = Parameter(key='window', name='window', description='the window epoch the finding is about', type=int, default=0, positional=True, required=True) PARAM_WD_WHY = Parameter(key='why', name='why', description='what to tell the subject; recorded on the complaint thread', type=str, default=None) PARAM_ST_TARGET = Parameter(key='target', name='target', description='the node asked about: pubkey, did:nostr or prefix', type=str, default='', positional=True, required=True) PARAM_RP_TARGET = Parameter(key='target', name='target', description='pubkey, did:nostr or prefix', type=str, default='', positional=True, required=True)
[docs]class PeeringCommandProvider: """Registers peer management, trust tier, bilateral grant, and report commands."""
[docs] @classmethod def register(cls, sub: argparse._SubParsersAction) -> None: add_command(sub, 'peers', cmd_peers, 'every peer: tiers, pending grant, last window, standing', js=True) add_command(sub, 'grant', cmd_grant, 'both grants with a peer, their history, and what waits for the boundary', peer=True, js=True) w = add_command(sub, 'windows', cmd_windows, 'the windows this node priced for a peer', peer=True, js=True) add_parameter_argument(w, PARAM_WIN_LAST) account.register(sub) p = add_command(sub, 'peer', cmd_peer, 'add a peer and shard to pull from', peer=True, js=True) add_parameter_argument(p, PARAM_PEER_SHARD, require_flag=True) add_parameter_argument(p, PARAM_PEER_FILTER, require_flag=True) add_parameter_argument(p, PARAM_PEER_EVERY) u = add_command(sub, 'unpeer', cmd_unpeer, 'stop pulling from a peer; the grants stay live', peer=True, js=True) add_parameter_argument(u, PARAM_UNPEER_SHARD) t = add_command(sub, 'trust', cmd_trust, "inspect or set a peer's tier, which nothing else can raise", js=True) add_parameter_argument(t, PARAM_TRUST_PEER) add_parameter_argument(t, PARAM_TRUST_TIER) te = add_command(sub, 'terminate', cmd_terminate, 'end a peering: zero both grants and tell the peer (needs the node running)', peer=True, js=True) add_parameter_argument(te, PARAM_TERM_REASON) rt = add_command(sub, 'retire', cmd_retire, 'leave the mesh in order: hand over every asserted shard, withdraw the claims, stop', js=True) add_parameter_argument(rt, PARAM_RET_REASON) add_parameter_argument(rt, PARAM_RET_REVOKE) add_parameter_argument(rt, PARAM_RET_LAPSES) wd = add_command(sub, 'withdraw', cmd_withdraw, 'withdraw a finding this node made about one window (needs the node running)', peer=True, js=True) add_parameter_argument(wd, PARAM_WD_WINDOW) add_parameter_argument(wd, PARAM_WD_WHY) st = add_command(sub, 'standing', cmd_standing, 'ask a peer what it knows about a third node (needs the node running)', peer=True, js=True) add_parameter_argument(st, PARAM_ST_TARGET) r = add_command(sub, 'reports', cmd_reports, 'the kind 30802s about a node, weighed by this one (needs the node running)', js=True) add_parameter_argument(r, PARAM_RP_TARGET)