fleetmesh-node 0.2.0__py3-none-any.whl

node/app/commands.py

@@ -0,0 +1,265 @@
+"""NODE_COMMANDS: what the node answers over the control socket, declared where it is.
+
+The 26 operator-facing commands answered by NodeApp and the control socket:
+each a Command or an Alias under the node namespace. CONTROL is generated
+from them, and the socket dispatches on them.
+"""
+from __future__ import annotations
+
+import collections
+
+from ..compartment import Alias, Command
+from ..config.parameter import Parameter
+from ..interfaces import CommandSpec
+
+NODE_COMMANDS: tuple[Command, ...] = (
+    Command(
+        key='version',
+        name='version',
+        description='the protocol this socket speaks, the schema digest this node declares, and its identity',
+        run='cmd_version',
+        reply='{protocol, fleetmesh, digest, did, pubkey, class, commands: [name]}',
+    ),
+    Command(
+        key='commands',
+        name='commands',
+        description='every command this socket answers, with its arguments and reply',
+        run='cmd_commands',
+        reply='[{name, args: {name: required|optional}, does, reply}]',
+    ),
+    Command(
+        key='status',
+        name='status',
+        description='what the node would write to status.json now',
+        run='status',
+        reply='the status.json object',
+    ),
+    Command(
+        key='health',
+        name='health',
+        description='every error plane: relays, drops, rejections, failures, throttles',
+        run='health',
+        reply='the health object status.json carries under health',
+    ),
+    Command(
+        key='peers',
+        name='peers',
+        description='every peer this node holds a grant with',
+        run='peer_view',
+        reply='[{peer, issued, received, pending, last_evaluated, standing, zeroed_until, pulls, descriptor}]',
+    ),
+    Command(
+        key='grant',
+        name='grant',
+        description='both grants with a peer, their history, and what waits for the boundary',
+        parameters=(
+            Parameter(key='peer', name='peer', description='peer pubkey', type=str, default='', required=True),
+        ),
+        run='cmd_grant',
+        reply='{peer, issued, received, issued_history, received_history, pending, seed_applied}',
+    ),
+    Command(
+        key='windows',
+        name='windows',
+        description='the windows this node priced for a peer, newest last',
+        parameters=(
+            Parameter(key='peer', name='peer', description='peer pubkey', type=str, default='', required=True),
+            Parameter(key='last', name='last', description='limit count', type=int, default=0, required=False),
+        ),
+        run='cmd_windows',
+        reply='[{epoch, closed, severity, measured, claimed, receipts_in, my_usage, my_receipts_sent}]',
+    ),
+    Command(
+        key='subsystems',
+        name='subsystems',
+        description='every compartment of this node: what it is, and every refusal it recorded',
+        run='cmd_subsystems',
+        reply='{name: {..., refusals: {total, by_reason, recent}}}',
+    ),
+    Command(
+        key='refusals',
+        name='refusals',
+        description='every no this node said, across every compartment, newest last',
+        parameters=(
+            Parameter(key='last', name='last', description='limit count', type=int, default=5, required=False),
+        ),
+        run='cmd_refusals',
+        reply='[{subsystem, at, kind, subject, why, detail}]',
+    ),
+    Command(
+        key='lifecycle',
+        name='lifecycle',
+        description='where every compartment is in its lifecycle: running, degraded, '
+                    'quarantined (breaker open, and until when), failed, retired',
+        run='cmd_lifecycle',
+        reply='{name: {state, since, failures, trips, until, last_error, started, restarts, '
+              'transitions, declared}}',
+    ),
+    Command(
+        key='resume',
+        name='resume',
+        description="end a compartment's quarantine now instead of waiting "
+                    'out its backoff; a compartment not quarantined is left as it is',
+        parameters=(
+            Parameter(key='name', name='name', description='compartment name', type=str, default='', required=True),
+        ),
+        run='cmd_resume',
+        reply='{name, state}',
+    ),
+    Command(
+        key='restart',
+        name='restart',
+        description='stop and start one compartment in place; only one that '
+                    'declares Lifecycle(restart=True) - any other is refused',
+        parameters=(
+            Parameter(key='name', name='name', description='compartment name', type=str, default='', required=True),
+        ),
+        run='cmd_restart',
+        reply='{name, state}',
+    ),
+    Command(
+        key='events',
+        name='events',
+        description='the most recent bus events still in memory, oldest first; since is a seq to resume from, topics a list to keep',
+        parameters=(
+            Parameter(key='since', name='since', description='resume sequence', type=int, default=0, required=False),
+            Parameter(key='topics', name='topics', description='topics to filter', type=object, default=None, required=False),
+            Parameter(key='last', name='last', description='limit count', type=int, default=0, required=False),
+        ),
+        run='cmd_events',
+        reply='{seq, oldest, topics: [name], events: [{seq, ts, topic, data}]}',
+    ),
+    Command(
+        key='subscribe',
+        name='subscribe',
+        description='hold the connection open and stream one {seq, ts, topic, data} line per bus event as it happens; '
+                    'since replays what the ring still holds first; a slow reader gets meta.dropped with a count',
+        parameters=(
+            Parameter(key='topics', name='topics', description='topics to filter', type=object, default=None, required=False),
+            Parameter(key='since', name='since', description='resume sequence', type=int, default=None, required=False),
+        ),
+        run='cmd_subscribe',
+        reply='ack {seq, topics}; then one envelope per line until the reader closes',
+    ),
+    Alias(
+        key='strain',
+        target='strain.show',
+        description="what this node has survived, by direction, and the reserves it sets; never a finding and never on the wire",
+        reply='{kinds, directions, weighted_directions, reserve_multiple, dominant_share, flag_tree}',
+    ),
+    Alias(
+        key='capacity',
+        target='capacity.show',
+        description="this node's own ceiling: what it declared, the pressure against it, which shed rungs are engaged and the largest window it has carried",
+        reply='{declared, total, pressure, binding, rungs, held, since, measured, peak, suggested, note}',
+    ),
+    Alias(
+        key='scheduled',
+        target='scheduler.show',
+        description='every scheduled pull, when it last ran, and what is holding it back now',
+        reply='{pulls, throttled, held, declined_until}',
+    ),
+    Alias(
+        key='trust',
+        target='trust.show',
+        description="the operator's decisions about peers, and which are still in force: "
+                    "a decision the ladder has since overridden is carried out and not true",
+        reply='{decided, in_force, pending, overridden, waiting}',
+    ),
+    Alias(
+        key='withdraw',
+        target='reporter.withdraw',
+        description="withdraw a finding this node made about one window, published or not; the operator's call",
+        parameters=(
+            Parameter(key='peer', name='peer', description='peer pubkey or did', type=str, default='', required=True),
+            Parameter(key='window', name='window', description='window number', type=int, default=0, required=True),
+            Parameter(key='why', name='why', description='reason for withdrawal', type=str, default=None, required=False),
+        ),
+        reply='{peer, window, was_published, report, why}',
+    ),
+    Command(
+        key='tick',
+        name='tick',
+        description='one tick now',
+        run='cmd_tick',
+        reply='[[what, ...], ...] the tick did',
+    ),
+    Command(
+        key='pull',
+        name='pull',
+        description='one sync session with a peer now; refused when the grant does not cover one unless force',
+        parameters=(
+            Parameter(key='peer', name='peer', description='peer pubkey', type=str, default='', required=True),
+            Parameter(key='shard', name='shard', description='shard name', type=str, default='', required=True),
+            Parameter(key='filter', name='filter', description='filter object', type=object, default=None, required=True),
+            Parameter(key='force', name='force', description='force pull', type=bool, default=False, required=False),
+            Parameter(key='timeout', name='timeout', description='timeout in seconds', type=float, default=60.0, required=False),
+        ),
+        run='cmd_pull',
+        reply='{status, counters, findings, ...} the session result',
+    ),
+    Command(
+        key='terminate',
+        name='terminate',
+        description='end a peering: zero both grants here and tell the peer',
+        parameters=(
+            Parameter(key='peer', name='peer', description='peer pubkey', type=str, default='', required=True),
+            Parameter(key='reason', name='reason', description='reason for termination', type=str, default='operator', required=False),
+        ),
+        run='cmd_terminate',
+        reply='{peer, reason, told: {relay: [accepted, note]}, pulls_removed}',
+    ),
+    Command(
+        key='standing',
+        name='standing',
+        description='ask a peer what it makes of a third node, over standing/1.0',
+        parameters=(
+            Parameter(key='peer', name='peer', description='peer pubkey', type=str, default='', required=True),
+            Parameter(key='target', name='target', description='target pubkey', type=str, default='', required=True),
+        ),
+        run='cmd_standing',
+        reply='{answer: tell|decline, body}',
+    ),
+    Command(
+        key='reports',
+        name='reports',
+        description="the kind 30802s about a node on this node's relays, weighed by this node",
+        parameters=(
+            Parameter(key='target', name='target', description='target pubkey', type=str, default='', required=True),
+        ),
+        run='cmd_reports',
+        reply='{view, reports: [{reporter, severity, admissible, reasons, weight, id, created_at}]}',
+    ),
+    Command(
+        key='republish',
+        name='republish',
+        description='send the descriptor to the relays again',
+        run='cmd_republish',
+        reply='{descriptor, relays: {url: [accepted, note]}}',
+    ),
+    Command(
+        key='retire',
+        name='retire',
+        description='leave the mesh in order: close every asserted range, hand the shards to every '
+                    'granted peer, withdraw the claims, and stop. Not a restart',
+        parameters=(
+            Parameter(key='reason', name='reason', description='reason for retirement', type=str, default='operator', required=False),
+            Parameter(key='revoke', name='revoke', description='revoke identity event', type=bool, default=False, required=False),
+            Parameter(key='lapses_in', name='lapses_in', description='seconds until claim lapses', type=int, default=86400, required=False),
+        ),
+        run='cmd_retire',
+        reply='{reason, at, did, peers, handed, withdrawn, revoked}',
+    ),
+)
+
+NODE_COMMANDS_BY_KEY: dict[str, Command] = {c.key: c for c in NODE_COMMANDS}
+
+CONTROL: collections.OrderedDict[str, CommandSpec] = collections.OrderedDict([
+    (c.key, c.to_spec()) for c in NODE_COMMANDS
+])
+
+__all__ = [
+    'CONTROL',
+    'NODE_COMMANDS',
+    'NODE_COMMANDS_BY_KEY',
+]

node/app/config.py

@@ -0,0 +1,131 @@
+"""The node's configuration: the control-socket table, the defaults, and the
+file that carries them.
+
+Separate from the node so `meshnode init`, `peer` and `trust` can read and
+write config.json without constructing a NodeApp.
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Mapping, Sequence
+
+from fleetmesh_core.identity.did import node_of_did
+from ..config import ConfigError, NodeConfig, Problems
+from .commands import CONTROL, NODE_COMMANDS, NODE_COMMANDS_BY_KEY
+
+__all__ = [
+    'CONTROL',
+    'ConfigError',
+    'DEFAULTS',
+    'NODE_COMMANDS',
+    'NODE_COMMANDS_BY_KEY',
+    'NodeConfig',
+    'Problems',
+    'config_from_manifests',
+    'defaults',
+    'load_config',
+    'save_config',
+    'typed_config',
+    'validate_config',
+]
+
+# The file's defaults are the file shape of NodeConfig(): one source. The
+# comments that used to sit beside each key are on the dataclass fields in
+# node/config/. Only the node's own keys are written; a compartment's block
+# is absent until the operator asks for it, because presence has meaning.
+DEFAULTS: Mapping[str, Any] = NodeConfig.defaults_dict()
+
+
+def defaults() -> Mapping[str, Any]:
+    """A fresh copy, nested values included.
+
+    DEFAULTS holds dicts and lists, and dict(DEFAULTS) copies only the top
+    level: two nodes built from it shared one `face` dict, so the first to
+    record its port set it for every node after. Anything that hands out
+    defaults hands out copies.
+    """
+    return json.loads(json.dumps(DEFAULTS))
+
+
+def validate_config(cfg: Any) -> list[str]:
+    """Every problem with a config, as a list of sentences; empty if none.
+
+    The file is the interface, so it is checked the way a message is: at the
+    door, with reasons. NodeConfig.check does the checking; this is the list
+    the CLI and the tests read.
+    """
+    p = Problems()
+    NodeConfig.check(cfg, p)
+    return list(p)
+
+
+def typed_config(cfg: Mapping[str, Any]) -> NodeConfig:
+    """The typed view of a config that validate_config passed."""
+    return NodeConfig.from_dict(cfg)
+
+
+def load_config(directory: str) -> Mapping[str, Any]:
+    with open(os.path.join(directory, 'config.json'), encoding='utf-8') as f:
+        cfg = json.load(f)
+    out = dict(defaults())
+    if not isinstance(cfg, dict):
+        raise ConfigError('config.json is not an object')
+    out.update(cfg)
+    problems = validate_config(out)
+    if problems:
+        raise ConfigError('config.json: ' + '; '.join(problems))
+    return out
+
+
+def _blob_storage_cap(cfg: Mapping[str, Any]) -> int | None:
+    """Byte cap for the Blossom blob store, or None for unbounded.
+
+    FLEETMESH_BLOB_MAX_BYTES wins, then config ``blobs.max_storage_bytes``, then
+    the MeshNode manifest's ``storage.maxBytes`` (config_from_manifests copies
+    it to ``cfg['storage']``). Before this nothing passed a cap, so the LRU
+    eviction in BlobStore.put never ran and a node's disk filled without bound.
+    0 or a negative value means unbounded.
+    """
+    raw: Any = os.environ.get('FLEETMESH_BLOB_MAX_BYTES')
+    if raw in (None, ''):
+        raw = (cfg.get('blobs') or {}).get('max_storage_bytes')
+    if raw in (None, ''):
+        raw = (cfg.get('storage') or {}).get('maxBytes')
+    try:
+        cap = int(raw) if raw not in (None, '') else 0
+    except (TypeError, ValueError):
+        raise ConfigError(f'blob storage cap is not an integer: {raw!r}')
+    return cap if cap > 0 else None
+
+
+def save_config(directory: str, cfg: Mapping[str, Any]) -> None:
+    os.makedirs(directory, mode=0o700, exist_ok=True)
+    path = os.path.join(directory, 'config.json')
+    tmp = path + '.tmp'
+    with open(tmp, 'w', encoding='utf-8') as f:
+        json.dump(cfg, f, indent=2, sort_keys=True)
+        f.write('\n')
+    os.replace(tmp, path)
+
+
+def config_from_manifests(meshnode: Mapping[str, Any], peerings: Sequence[Mapping[str, Any]] = ()) -> Mapping[str, Any]:
+    """A config from a MeshNode manifest and any Peering manifests (parsed YAML or JSON)."""
+    spec = meshnode['spec']
+    cfg = dict(defaults())
+    cfg['class'] = spec['class']
+    cfg['operator'] = spec['operator']['pubkey']
+    cfg['endpoints'] = [{'transport': e['transport'], 'address': e.get('address') or e.get('ticket'),
+                         'priority': e.get('priority', 50)} for e in spec.get('endpoints', [])]
+    caps = spec.get('capabilities', [])
+    cfg['capabilities'] = [c for c in caps if not c.startswith('https://')]
+    cfg['protocols'] = sorted(set(DEFAULTS['protocols']) | {c for c in caps if c.startswith('https://')})
+    cfg['storage'] = spec.get('storage', {})
+    cfg['peers'] = []
+    for pm in peerings:
+        ps = pm['spec']
+        cfg['peers'].append({'pubkey': node_of_did(ps['peer']), 'shard': pm['metadata']['name'],
+                             'filter': ps['ingress']['filter'], 'pull_every': 600,
+                             'window': ps.get('budget', {}).get('window')})
+    return cfg
+