Source code for fleetmesh_node.config.node

"""NodeConfig: the whole of config.json as one frozen dataclass.

`DEFAULTS` in fleetmesh_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 fleetmesh_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 fleetmesh_core.identity.did import parse_operator, same_operator

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, NetworkConfig, 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, VisibilityConfig)

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]
    publish_operator: bool
    operator_relays: list[str]
    pow_bits: Optional[int]
    visibility: Mapping[str, Any]
    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]]
    network: Optional[Mapping[str, Any]]
    protocol_suites: Optional[Mapping[str, Any]]
    extensions: Mapping[str, Any]


def _is_group_did(value: Any) -> bool:
    if not isinstance(value, str) or not value.startswith('did:group:'):
        return False
    try:
        return parse_operator(value)['method'] == 'group'
    except ValueError:
        return False

[docs]@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 # Plan D28: the brand strand ids this node claims. Each one writes its own # L/l self-label pair into the descriptor (constants.json brand.namespace) - # the CLAIM half of the two rules. A brand shows on this node only when the # authority's kind 1985 endorsement exists too (`meshctl brand endorse`). # Public and never a private tag: it survives into the public copy. brands: tuple[str, ...] = () operator: Optional[str] = None # Plan D26: the descriptor names the operator only when this is set - for a # node serving the public network as an anchor or mediator, where leaves # read it to pick independent anchors. Otherwise ownership stays blinded. publish_operator: bool = False # Private relays the operator names for operator-specific material # (revocation lists, the circle's documents); joined with the relays of # the node's private networks. Never the public `relays` (plan D26). operator_relays: tuple[str, ...] = () pow_bits: Optional[int] = None # None: the constants' default # What this node exposes in public (plan: kind 11801 visibility/expose). # default public and no override mirrors no visibility tag and no expose # tag, so an untouched node's descriptor is byte for byte what it was. visibility: VisibilityConfig = VisibilityConfig() 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 network: Optional[NetworkConfig] = None # live block; the compartment is always built (plan D6) 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', 'brands', '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, 'brands': None, 'operator': None, 'publish_operator': None, 'operator_relays': None, 'pow_bits': None, 'visibility': VisibilityConfig, '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, 'network': NetworkConfig, 'protocol_suites': ProtocolSuitesConfig, 'extensions': None, # Written by the node, not the operator; carried and never checked. 'executors': None, # Written by `meshnode enrol` (plan D18/D19): the operator the node # joined and the fleet/enrol grant that let it, so a restart keeps # the operator and `status` can say where it came from. 'enrolment': None, }
[docs] @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') op_relays = raw.get('operator_relays', []) if not isinstance(op_relays, list) or not all(is_relay_url(r) for r in op_relays): p.add('operator_relays must be a list of ws:// or wss:// URLs') if not isinstance(raw.get('publish_operator', False), bool): p.add('publish_operator must be true or false') 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) and not _is_group_did(op): p.add('operator must be a 64-hex pubkey or a did:group (plan D20)') enr = raw.get('enrolment') if enr is not None: if not isinstance(enr, Mapping): p.add('enrolment must be an object (meshnode enrol writes it)') else: if not isinstance(enr.get('operator'), str) or not enr['operator']: p.add('enrolment.operator must be the operator DID') if not isinstance(enr.get('token_id'), str) or not is_hex64(enr['token_id']): p.add('enrolment.token_id must be the 64-hex grant id') if not is_int(enr.get('at')): p.add('enrolment.at must be a unix timestamp') if op is not None and isinstance(enr.get('operator'), str) and not same_operator(op, enr['operator']): p.add('enrolment.operator must name the same operator as `operator`') 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') brands = raw.get('brands', []) if not isinstance(brands, list) or not all(isinstance(b, str) and b.strip() for b in brands): p.add('brands must be a list of brand strand ids (plan D28)') 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))
[docs] @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)), brands=tuple(raw.get('brands') or ()), operator=raw.get('operator'), publish_operator=bool(raw.get('publish_operator', False)), operator_relays=tuple(raw.get('operator_relays') or ()), pow_bits=raw.get('pow_bits'), visibility=block('visibility', VisibilityConfig), 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), network=block('network', NetworkConfig, 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 {}), )
[docs] @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']