"""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)