fleetmesh-node 0.2.0__py3-none-any.whl

node/config/node.py

@@ -0,0 +1,318 @@
+"""NodeConfig: the whole of config.json as one frozen dataclass.
+
+`DEFAULTS` in node.app.config is generated from `NodeConfig()` so the file's
+defaults have one source. `check` names every problem; `from_dict` builds
+the typed view. The dict the compartments still read is kept beside it
+(see node.app.config.load_config) until every compartment reads its block
+through `Registry.assemble`.
+
+Unknown top-level keys are refused by name: a misspelt block (`capacitty`)
+is exactly the silent failure this exists to catch. Out-of-tree compartments
+put theirs under `extensions`, which is carried as-is and checked by the
+compartment that owns it. Keys beginning with `_` are the node's own
+runtime notes and never saved.
+"""
+from __future__ import annotations
+
+import dataclasses
+from typing import Any, ClassVar, Mapping, MutableMapping, Optional, TypedDict, cast
+
+from .base import Block, Problems, all_str, is_hex64, is_int, is_relay_url, positive_int
+from .compartments import (AnnounceConfig, BlobReplicationConfig, BlobWireConfig, BlobsConfig, BridgeConfig,
+                           CapacityConfig, ComputeConfig, DVMConfig, FetchPricingConfig, NsiteConfig, GossipConfig, LanConfig,
+                           MediationConfig, P2PConfig, PluginsConfig, SettlementConfig, SidecarsConfig, SIDECAR_KEYS_MOVED, sidecars_of, StorageConfig,
+                           TransportConfig, UpdatesConfig, HostMultiplexerConfig, NostrProtocolConfig, ProtocolSuitesConfig)
+from .records import (CLASSES, HANDOVER, CoverageClaim, Endpoint, FaceConfig, PeerPull, PolicyConfig,
+                      TrustDecision)
+
+DEFAULT_PROTOCOLS: tuple[str, ...] = ('https://fleetmesh.org/sync/1.0',)
+DEFAULT_CAPABILITIES: tuple[str, ...] = ('relay', 'negentropy')
+
+
+class NodeConfigDict(TypedDict, total=False):
+    cls_: str
+    name: str
+    relays: list[str]
+    face: Mapping[str, Any]
+    endpoints: list[Mapping[str, Any]]
+    protocols: list[str]
+    capabilities: list[str]
+    operator: Optional[str]
+    pow_bits: Optional[int]
+    policy: Mapping[str, Any]
+    coverage: list[Mapping[str, Any]]
+    handover: str
+    retention: dict[int, int]
+    trust: Mapping[str, Any]
+    peers: list[Mapping[str, Any]]
+    tick_seconds: int
+    heartbeat: bool
+    projection: bool
+    telemetry: bool
+    fetch_pricing: Mapping[str, Any]
+    bridge: Optional[Mapping[str, Any]]
+    announce: Mapping[str, Any]
+    lan: Mapping[str, Any]
+    p2p: Optional[Mapping[str, Any]]
+    gossip: Optional[Mapping[str, Any]]
+    linked: Mapping[str, Any]
+    capacity: Mapping[str, Any]
+    compute: Optional[Mapping[str, Any]]
+    dvm: Optional[Mapping[str, Any]]
+    settlement: Mapping[str, Any]
+    mediation: Mapping[str, Any]
+    transport: Mapping[str, Any]
+    blob_wire: Mapping[str, Any]
+    blob_replication: Mapping[str, Any]
+    storage: Mapping[str, Any]
+    blobs: Mapping[str, Any]
+    sidecars: Mapping[str, Any]
+    plugins: Mapping[str, Any]
+    updates: Optional[Mapping[str, Any]]
+    protocol_suites: Optional[Mapping[str, Any]]
+    extensions: Mapping[str, Any]
+
+
+@dataclasses.dataclass(frozen=True)
+class NodeConfig(Block):
+    # --- the node -----------------------------------------------------------
+    cls_: str = 'edge'                                   # `class` in the file
+    name: str = 'meshnode'
+    relays: tuple[str, ...] = ()                         # the control plane's relays; empty allowed
+    face: FaceConfig = FaceConfig()
+    endpoints: tuple[Endpoint, ...] = ()
+    protocols: tuple[str, ...] = DEFAULT_PROTOCOLS
+    capabilities: tuple[str, ...] = DEFAULT_CAPABILITIES
+    operator: Optional[str] = None
+    pow_bits: Optional[int] = None                       # None: the constants' default
+    policy: PolicyConfig = PolicyConfig()
+    coverage: tuple[CoverageClaim, ...] = ()
+    handover: str = 'offer'
+    retention: dict[int, int] = dataclasses.field(default_factory=dict)       # {kind: seconds}; empty keeps everything
+    trust: dict[str, TrustDecision] = dataclasses.field(default_factory=dict)
+    peers: tuple[PeerPull, ...] = ()
+    tick_seconds: int = 30
+    heartbeat: bool = True
+    projection: bool = True
+    telemetry: bool = False          # kind 21802, opt-in: coarse counters about this node, no per-peer attribution
+    # --- the compartments ------------------------------------------------------
+    fetch_pricing: FetchPricingConfig = FetchPricingConfig()
+    bridge: Optional[BridgeConfig] = None               # None: the block is absent (bridge on with defaults)
+    announce: AnnounceConfig = AnnounceConfig()
+    lan: LanConfig = LanConfig()
+    p2p: Optional[P2PConfig] = None                     # None: absent; the compartment is off
+    gossip: Optional[GossipConfig] = None               # None: absent; the compartment is off
+    capacity: CapacityConfig = CapacityConfig()
+    compute: Optional[ComputeConfig] = None
+    dvm: Optional[DVMConfig] = None
+    nsite: Optional[NsiteConfig] = None
+    settlement: SettlementConfig = SettlementConfig()
+    mediation: MediationConfig = MediationConfig()
+    transport: TransportConfig = TransportConfig()
+    blob_wire: BlobWireConfig = BlobWireConfig()
+    blob_replication: BlobReplicationConfig = BlobReplicationConfig()
+    storage: StorageConfig = StorageConfig()
+    blobs: BlobsConfig = BlobsConfig()
+    sidecars: SidecarsConfig = SidecarsConfig()
+    plugins: PluginsConfig = PluginsConfig()
+    updates: Optional[UpdatesConfig] = None               # optional compartment; presence is the switch
+    protocol_suites: ProtocolSuitesConfig = ProtocolSuitesConfig()
+    extensions: Mapping[str, Any] = dataclasses.field(default_factory=dict)
+
+    # Keys the file carries that are written by default. Absent-by-default
+    # blocks (bridge, p2p, compute, dvm, and every other compartment's) are
+    # not written: their presence has meaning (`enabled_by`), and a default
+    # file should ask for nothing. `defaults_dict` is derived from this list
+    # and the dataclass defaults, so the two cannot drift.
+    WRITTEN_BY_DEFAULT: ClassVar[tuple[str, ...]] = ('class', 'relays', 'face', 'endpoints', 'protocols', 'capabilities', 'operator',
+                          'pow_bits', 'policy', 'coverage', 'handover', 'retention', 'trust', 'peers',
+                          'tick_seconds', 'heartbeat', 'projection', 'fetch_pricing')
+
+    # File key -> dataclass field, where they differ.
+    FIELD_OF: ClassVar[dict[str, str]] = {'class': 'cls_'}
+
+    # Every key the file may carry, with the block that checks it (None: checked inline).
+    BLOCKS: ClassVar[dict[str, Optional[type[Block]]]] = {
+        'class': None, 'name': None, 'relays': None, 'face': FaceConfig, 'endpoints': None, 'protocols': None,
+        'capabilities': None, 'operator': None, 'pow_bits': None, 'policy': PolicyConfig, 'coverage': None,
+        'handover': None, 'retention': None, 'trust': None, 'peers': None, 'tick_seconds': None,
+        'heartbeat': None, 'projection': None, 'telemetry': None,
+        'fetch_pricing': FetchPricingConfig, 'bridge': BridgeConfig, 'announce': AnnounceConfig, 'lan': LanConfig,
+        'p2p': P2PConfig, 'gossip': GossipConfig, 'capacity': CapacityConfig, 'compute': ComputeConfig, 'dvm': DVMConfig, 'nsite': NsiteConfig,
+        # `video` is a known key with its block declared on the compartment
+        # (VideoConfig), the way `trust` carries TrustConfig. It was neither:
+        # the compartment declared reads=('video',) and config_cls=VideoConfig
+        # while NodeConfig had no such key, so the block was never a typed,
+        # validated part of the config - which nothing caught, because
+        # test_config_contract walks MANIFEST and this compartment was not in it.
+        'video': None,
+        'settlement': SettlementConfig, 'mediation': MediationConfig, 'transport': TransportConfig,
+        'blob_wire': BlobWireConfig, 'blob_replication': BlobReplicationConfig, 'storage': StorageConfig,
+        'blobs': BlobsConfig, 'sidecars': SidecarsConfig, 'plugins': PluginsConfig,
+        # The sidecar blocks before they moved under `sidecars`: read for one
+        # release, folded in by from_dict, written back in the new shape.
+        'grasp': None, 'ncontainer': None, 'magpie': None,
+        'updates': UpdatesConfig,
+        'protocol_suites': ProtocolSuitesConfig,
+        'extensions': None,
+        # Written by the node, not the operator; carried and never checked.
+        'executors': None,
+    }
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('config is not an object'); return
+        if raw.get('class') not in CLASSES:
+            p.add('class must be leaf, edge or anchor')
+        relays = raw.get('relays', [])
+        if not isinstance(relays, list) or not all(is_relay_url(r) for r in relays):
+            p.add('relays must be a list of ws:// or wss:// URLs')
+        FaceConfig.check(raw.get('face', {}), p)
+        eps = raw.get('endpoints', [])
+        if not isinstance(eps, list) or not all(Endpoint.well_formed(e) for e in eps):
+            p.add('endpoints must be a list of {transport, address[, priority]}')
+        if not positive_int(raw.get('tick_seconds', 30)):
+            p.add('tick_seconds must be a positive integer')
+        if not isinstance(raw.get('heartbeat', True), bool):
+            p.add('heartbeat must be true or false')
+        if not isinstance(raw.get('projection', True), bool):
+            p.add('projection must be true or false')
+        if not isinstance(raw.get('telemetry', False), bool):
+            p.add('telemetry must be true or false')
+        if 'name' in raw and not isinstance(raw['name'], str):
+            p.add('name must be a string')
+        op = raw.get('operator')
+        if op is not None and not is_hex64(op):
+            p.add('operator must be a 64-hex pubkey')
+        bits = raw.get('pow_bits')
+        if bits is not None and (not is_int(bits) or not 0 <= bits <= 40):
+            p.add('pow_bits must be an integer from 0 to 40')
+        raw_protocols = raw.get('protocols')
+        if raw_protocols is not None:
+            if isinstance(raw_protocols, Mapping):
+                ProtocolSuitesConfig.check(raw_protocols, p)
+            elif isinstance(raw_protocols, (list, tuple)):
+                if not all_str(raw_protocols):
+                    p.add('protocols must be a list of identifiers')
+            else:
+                p.add('protocols must be a list of strings or a protocol suite object')
+        if 'protocol_suites' in raw and raw['protocol_suites'] is not None:
+            ProtocolSuitesConfig.check(raw['protocol_suites'], p)
+        if not all_str(raw.get('capabilities', [])):
+            p.add('capabilities must be a list of names')
+        peers = raw.get('peers', [])
+        if not isinstance(peers, list):
+            p.add('peers must be a list')
+        else:
+            for i, e in enumerate(peers):
+                PeerPull.check_one(i, e, p)
+        trust = raw.get('trust', {})
+        if not isinstance(trust, Mapping):
+            p.add('trust must be an object of pubkey -> decision')
+        else:
+            for pk, e in trust.items():
+                TrustDecision.check_one(pk, e, p)
+        if raw.get('handover', 'offer') not in HANDOVER:
+            p.add('handover must be offer or never')
+        cov = raw.get('coverage', [])
+        if not isinstance(cov, list):
+            p.add('coverage must be a list')
+        else:
+            for i, e in enumerate(cov):
+                CoverageClaim.check_one(i, e, p)
+        ret = raw.get('retention', {})
+        if not isinstance(ret, Mapping):
+            p.add('retention must be an object of {kind: seconds}')
+        else:
+            for k, v in ret.items():
+                if not str(k).lstrip('-').isdigit() or not is_int(v) or int(v) < 0:
+                    p.add('retention[%s] must be a kind number and a positive number of seconds' % str(k)[:12])
+        PolicyConfig.check(raw.get('policy', {}), p)
+        if 'extensions' in raw and not isinstance(raw['extensions'], Mapping):
+            p.add('extensions must be an object of {name: block}')
+        for key, blk in cls.BLOCKS.items():
+            if blk is not None and key not in ('face', 'policy') and raw.get(key) is not None:
+                blk.check(raw[key], p)
+        moved = {k: raw[k] for k in SIDECAR_KEYS_MOVED if raw.get(k) is not None}
+        if moved:
+            SidecarsConfig.check(moved, p)
+        unknown = sorted(k for k in raw if k not in cls.BLOCKS and not str(k).startswith('_'))
+        if unknown:
+            p.add('no compartment reads: %s (an out-of-tree block goes under extensions)' % ', '.join(unknown))
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'NodeConfig':
+        def block(key: str, blk: Any, absent: Any = 'default') -> Any:
+            v = raw.get(key)
+            if v is None:
+                return blk() if absent == 'default' else None
+            return blk.from_dict(v)
+        return cls(
+            cls_=raw.get('class', 'edge'), name=raw.get('name', 'meshnode'), relays=tuple(raw.get('relays') or ()),
+            face=FaceConfig.from_dict(raw.get('face') or {}),
+            endpoints=tuple(Endpoint.from_dict(e) for e in raw.get('endpoints') or ()),
+            capabilities=tuple(raw.get('capabilities', DEFAULT_CAPABILITIES)),
+            operator=raw.get('operator'), pow_bits=raw.get('pow_bits'),
+            policy=PolicyConfig.from_dict(raw.get('policy') or {}),
+            coverage=tuple(CoverageClaim.from_dict(c) for c in raw.get('coverage') or ()),
+            handover=raw.get('handover', 'offer'),
+            retention={int(k): int(v) for k, v in (raw.get('retention') or {}).items()},
+            trust={pk: TrustDecision.from_dict(e) for pk, e in (raw.get('trust') or {}).items()},
+            peers=tuple(PeerPull.from_dict(e) for e in raw.get('peers') or ()),
+            tick_seconds=int(raw.get('tick_seconds', 30)), heartbeat=bool(raw.get('heartbeat', True)),
+            projection=bool(raw.get('projection', True)), telemetry=bool(raw.get('telemetry', False)),
+            fetch_pricing=block('fetch_pricing', FetchPricingConfig),
+            bridge=block('bridge', BridgeConfig, absent=None),
+            announce=block('announce', AnnounceConfig), lan=block('lan', LanConfig),
+            p2p=block('p2p', P2PConfig, absent=None), gossip=block('gossip', GossipConfig, absent=None),
+            capacity=block('capacity', CapacityConfig),
+            compute=block('compute', ComputeConfig, absent=None), dvm=block('dvm', DVMConfig, absent=None),
+            nsite=block('nsite', NsiteConfig, absent=None),
+            settlement=block('settlement', SettlementConfig), mediation=block('mediation', MediationConfig),
+            transport=block('transport', TransportConfig), blob_wire=block('blob_wire', BlobWireConfig),
+            blob_replication=block('blob_replication', BlobReplicationConfig), storage=block('storage', StorageConfig),
+            blobs=block('blobs', BlobsConfig), sidecars=SidecarsConfig.from_dict(sidecars_of(raw)),
+            plugins=block('plugins', PluginsConfig),
+            updates=block('updates', UpdatesConfig, absent=None),
+            protocol_suites=(
+                ProtocolSuitesConfig.from_dict(raw['protocols']) if isinstance(raw.get('protocols'), Mapping)
+                else ProtocolSuitesConfig.from_dict(raw['protocol_suites']) if isinstance(raw.get('protocol_suites'), Mapping)
+                else ProtocolSuitesConfig(
+                    host=HostMultiplexerConfig(
+                        listen=str((raw.get('face') or {}).get('host', '127.0.0.1')),
+                        port=int((raw.get('face') or {}).get('port', 0)),
+                    ),
+                    nostr=NostrProtocolConfig(
+                        future_seconds=int((raw.get('face') or {}).get('future_seconds', 900)),
+                    ),
+                )
+            ),
+            protocols=(
+                DEFAULT_PROTOCOLS if isinstance(raw.get('protocols'), Mapping)
+                else tuple(raw.get('protocols', DEFAULT_PROTOCOLS))
+            ),
+            extensions=dict(raw.get('extensions') or {}),
+        )
+
+    @classmethod
+    def defaults_dict(cls) -> NodeConfigDict:
+        """What a fresh config.json carries: the file shape of NodeConfig(),
+        one entry per WRITTEN_BY_DEFAULT key, each the JSON form of that
+        field's dataclass default (blocks via to_dict, tuples as lists)."""
+        d = cls()
+        out: MutableMapping[str, Any] = {}
+        for key in cls.WRITTEN_BY_DEFAULT:
+            v = getattr(d, cls.FIELD_OF.get(key, key))
+            if isinstance(v, Block):
+                out[key] = v.to_dict()
+            elif isinstance(v, tuple):
+                out[key] = list(v)
+            elif isinstance(v, dict):
+                out[key] = dict(v)
+            else:
+                out[key] = v
+        return cast(NodeConfigDict, out)
+
+
+__all__ = ['NodeConfig', 'DEFAULT_PROTOCOLS', 'DEFAULT_CAPABILITIES']