"""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']