Phase 1: Cluster-Fundament – Nachrichten, Registry, Paarung, Discovery
- hms_cluster: ClusterMessage (§6.5: Pflichtfelder, Sequenzen, Revisionen, execute_at, Trace-ID), CommandTracker (idempotent, vorwärts-only: accepted->armed->executed/failed) - NodeRegistry: online/degraded/stale/offline über Schwellen, UI-Kategorien discovered/paired/unknown/incompatible/offline, Doppel-Node-ID blockiert, IP-Wechsel erhaelt node_id (§6.3, §6.5) - Pairing: PIN (TTL 120s, Versuchslimit), Fingerprint (SHA-256 gruppiert), Token nur als Hash, Scopes read/control/content_sync/admin, Ablauf + sofortiger Widerruf (§6.3, §27.1, ADR-0010) - Discovery-Modell: _hmsmedia._tcp.local. TXT ohne Secrets, Capability- Digest, persistente manuelle Fallback-Liste (ADR-0009) - ADR-0009 (mDNS + Fallback) und ADR-0010 (Paarung) dokumentiert - 25 Unit-Tests; Gesamtsuite 183 Tests gruen, Ruff gruen
This commit is contained in:
HMS MediaEngine Agent
@@ -0,0 +1,54 @@
|
||||
"""hms_cluster – Clusterprotokoll, Node-Registry, Paarung, Discovery
|
||||
(PLAN.md §6.3, §6.5; ADR-0009, ADR-0010)."""
|
||||
|
||||
from hms_cluster.discovery import (
|
||||
DISCOVERY_PROTOCOL_VERSION,
|
||||
SERVICE_TYPE,
|
||||
ManualNodeList,
|
||||
ServiceInfo,
|
||||
capability_digest,
|
||||
)
|
||||
from hms_cluster.message import ClusterMessage, CommandStatus, CommandTracker
|
||||
from hms_cluster.pairing import (
|
||||
PairingPin,
|
||||
PairingStore,
|
||||
Scope,
|
||||
generate_pin,
|
||||
hash_token,
|
||||
identity_fingerprint,
|
||||
new_token,
|
||||
pin_valid,
|
||||
)
|
||||
from hms_cluster.registry import (
|
||||
DuplicateNodeError,
|
||||
HealthThresholds,
|
||||
NodeCategory,
|
||||
NodeEntry,
|
||||
NodeHealth,
|
||||
NodeRegistry,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
"SERVICE_TYPE",
|
||||
"DISCOVERY_PROTOCOL_VERSION",
|
||||
"ServiceInfo",
|
||||
"ManualNodeList",
|
||||
"capability_digest",
|
||||
"ClusterMessage",
|
||||
"CommandStatus",
|
||||
"CommandTracker",
|
||||
"PairingPin",
|
||||
"PairingStore",
|
||||
"Scope",
|
||||
"generate_pin",
|
||||
"pin_valid",
|
||||
"identity_fingerprint",
|
||||
"new_token",
|
||||
"hash_token",
|
||||
"DuplicateNodeError",
|
||||
"HealthThresholds",
|
||||
"NodeCategory",
|
||||
"NodeEntry",
|
||||
"NodeHealth",
|
||||
"NodeRegistry",
|
||||
]
|
||||
@@ -0,0 +1,131 @@
|
||||
"""Discovery: mDNS-Service-Modell + manuelle Fallback-Liste (PLAN.md §6.3;
|
||||
ADR-0009).
|
||||
|
||||
- Service-Typ: _hmsmedia._tcp.local.
|
||||
- TXT nur kleine, nicht vertrauliche Daten: proto, node, roles, port, caps
|
||||
- manuelle Node-Liste für VLANs/geroutete Netze (§6.3)
|
||||
- IP-Wechsel ändert die node_id nicht (§6.3)
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
|
||||
SERVICE_TYPE = "_hmsmedia._tcp.local."
|
||||
DISCOVERY_PROTOCOL_VERSION = 1
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ServiceInfo:
|
||||
"""mDNS-Ankündigung eines Nodes (TXT-Inhalt, ADR-0009)."""
|
||||
|
||||
node_id: str
|
||||
display_name: str
|
||||
port: int
|
||||
roles: tuple[str, ...]
|
||||
protocol_version: int = DISCOVERY_PROTOCOL_VERSION
|
||||
capability_digest: str = ""
|
||||
|
||||
@property
|
||||
def instance_name(self) -> str:
|
||||
"""Eindeutiger Instanzname: bereinigter Anzeigename."""
|
||||
safe = "".join(c for c in self.display_name if c.isalnum() or c in " -_")
|
||||
return safe[:63] or self.node_id[:8]
|
||||
|
||||
def txt(self) -> dict[str, str]:
|
||||
"""TXT-Record: klein, nicht vertraulich (ADR-0009, §27.1)."""
|
||||
return {
|
||||
"proto": str(self.protocol_version),
|
||||
"node": self.node_id,
|
||||
"roles": ",".join(self.roles),
|
||||
"port": str(self.port),
|
||||
"caps": self.capability_digest[:16],
|
||||
}
|
||||
|
||||
@classmethod
|
||||
def from_txt(cls, instance_name: str, port: int, txt: dict[str, str]) -> ServiceInfo:
|
||||
"""Parst eine fremde Ankündigung; wirft bei unvollständigen Daten."""
|
||||
required = ("proto", "node", "port")
|
||||
missing = [k for k in required if k not in txt]
|
||||
if missing:
|
||||
raise ValueError(f"TXT unvollstaendig, fehlt: {missing}")
|
||||
node_id = txt["node"]
|
||||
if len(node_id) < 8:
|
||||
raise ValueError("node-Eintrag ungueltig")
|
||||
roles = tuple(r for r in txt.get("roles", "").split(",") if r)
|
||||
return cls(
|
||||
node_id=node_id,
|
||||
display_name=instance_name,
|
||||
port=int(txt["port"]) or port,
|
||||
roles=roles,
|
||||
protocol_version=int(txt["proto"]),
|
||||
capability_digest=txt.get("caps", ""),
|
||||
)
|
||||
|
||||
|
||||
def capability_digest(capabilities: dict) -> str:
|
||||
"""Kurzer, stabiler Digest über Capabilities (ADR-0009 TXT 'caps')."""
|
||||
canonical = json.dumps(capabilities, sort_keys=True, separators=(",", ":"))
|
||||
return hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:16]
|
||||
|
||||
|
||||
@dataclass
|
||||
class ManualNodeList:
|
||||
"""Persistente manuelle Node-Liste (Fallback ohne mDNS, §6.3).
|
||||
|
||||
JSON-Format: Liste von {"host", "port", "node_id"}; ungeprüfte Hosts
|
||||
bleiben Kategorie `unknown`, bis sich die Node legitim identifiziert.
|
||||
"""
|
||||
|
||||
path: Path
|
||||
|
||||
def save(self, entries: list[dict]) -> None:
|
||||
clean = [
|
||||
{
|
||||
"host": str(e.get("host", "")),
|
||||
"port": int(e.get("port", 0)),
|
||||
"node_id": str(e.get("node_id", "")),
|
||||
}
|
||||
for e in entries
|
||||
]
|
||||
self.path.parent.mkdir(parents=True, exist_ok=True)
|
||||
self.path.write_text(
|
||||
json.dumps(clean, indent=2, ensure_ascii=False), encoding="utf-8"
|
||||
)
|
||||
|
||||
def load(self) -> list[dict]:
|
||||
if not self.path.is_file():
|
||||
return []
|
||||
try:
|
||||
data = json.loads(self.path.read_text(encoding="utf-8"))
|
||||
except json.JSONDecodeError:
|
||||
return []
|
||||
entries = []
|
||||
for item in data if isinstance(data, list) else []:
|
||||
if not isinstance(item, dict):
|
||||
continue
|
||||
host = str(item.get("host", ""))
|
||||
if not host:
|
||||
continue
|
||||
try:
|
||||
port = int(item.get("port", 0))
|
||||
except (TypeError, ValueError):
|
||||
continue
|
||||
entries.append(
|
||||
{"host": host, "port": port, "node_id": str(item.get("node_id", ""))}
|
||||
)
|
||||
return entries
|
||||
|
||||
def add(self, host: str, port: int, node_id: str = "") -> None:
|
||||
entries = self.load()
|
||||
if any(e["host"] == host and e["port"] == port for e in entries):
|
||||
return
|
||||
entries.append({"host": host, "port": port, "node_id": node_id})
|
||||
self.save(entries)
|
||||
|
||||
def remove(self, host: str, port: int) -> None:
|
||||
entries = [e for e in self.load() if not (e["host"] == host and e["port"] == port)]
|
||||
self.save(entries)
|
||||
@@ -0,0 +1,164 @@
|
||||
"""Cluster-Nachrichtenhülle (PLAN.md §6.5).
|
||||
|
||||
Jede Cluster-Nachricht enthält mindestens: cluster_id, node_id, command_id,
|
||||
Sequenz, Projekt-Revision, Absenderzeit, optionale execute_at-Showzeit und
|
||||
Trace-ID. Zustandsändernde Commands sind idempotent und werden mit
|
||||
accepted/armed/executed/failed bestätigt.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import time
|
||||
import uuid
|
||||
from enum import StrEnum
|
||||
|
||||
|
||||
class CommandStatus(StrEnum):
|
||||
"""Bestätigungsstufen zustandsändernder Commands (§6.5)."""
|
||||
|
||||
ACCEPTED = "accepted"
|
||||
ARMED = "armed"
|
||||
EXECUTED = "executed"
|
||||
FAILED = "failed"
|
||||
|
||||
|
||||
class ClusterMessage:
|
||||
"""Versionierte Cluster-Nachricht mit Pflichtfeldern (§6.5).
|
||||
|
||||
- sequence: je Absender monoton; Lücken signalisieren Paketverlust
|
||||
- project_revision: Zustandsrevision, auf die sich der Command bezieht
|
||||
- sender_time_ns: monotone Absenderzeit (nicht Wanduhr)
|
||||
- execute_at_show_time_ns: optional; 100–300 ms Vorlauf für Sync-Starts
|
||||
- trace_id: Korrelations-ID über Log-Grenzen (§28.1)
|
||||
"""
|
||||
|
||||
__slots__ = (
|
||||
"cluster_id",
|
||||
"node_id",
|
||||
"command_id",
|
||||
"sequence",
|
||||
"project_revision",
|
||||
"sender_time_ns",
|
||||
"execute_at_show_time_ns",
|
||||
"trace_id",
|
||||
"status",
|
||||
"payload",
|
||||
)
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
cluster_id: str,
|
||||
node_id: str,
|
||||
command_id: str,
|
||||
sequence: int,
|
||||
project_revision: int,
|
||||
sender_time_ns: int | None = None,
|
||||
execute_at_show_time_ns: int | None = None,
|
||||
trace_id: str | None = None,
|
||||
status: CommandStatus | None = None,
|
||||
payload: dict | None = None,
|
||||
) -> None:
|
||||
for field_name, value in (
|
||||
("cluster_id", cluster_id),
|
||||
("node_id", node_id),
|
||||
("command_id", command_id),
|
||||
):
|
||||
try:
|
||||
uuid.UUID(value)
|
||||
except (ValueError, AttributeError) as exc:
|
||||
raise ValueError(f"{field_name} must be a UUID") from exc
|
||||
if sequence < 0:
|
||||
raise ValueError("sequence must be >= 0")
|
||||
if project_revision < 0:
|
||||
raise ValueError("project_revision must be >= 0")
|
||||
self.cluster_id = cluster_id
|
||||
self.node_id = node_id
|
||||
self.command_id = command_id
|
||||
self.sequence = sequence
|
||||
self.project_revision = project_revision
|
||||
self.sender_time_ns = (
|
||||
sender_time_ns if sender_time_ns is not None else time.monotonic_ns()
|
||||
)
|
||||
self.execute_at_show_time_ns = execute_at_show_time_ns
|
||||
self.trace_id = trace_id or str(uuid.uuid4())
|
||||
self.status = status
|
||||
self.payload = payload or {}
|
||||
|
||||
def to_dict(self) -> dict:
|
||||
return {
|
||||
"cluster_id": self.cluster_id,
|
||||
"node_id": self.node_id,
|
||||
"command_id": self.command_id,
|
||||
"sequence": self.sequence,
|
||||
"project_revision": self.project_revision,
|
||||
"sender_time_ns": self.sender_time_ns,
|
||||
"execute_at_show_time_ns": self.execute_at_show_time_ns,
|
||||
"trace_id": self.trace_id,
|
||||
"status": self.status.value if self.status else None,
|
||||
"payload": self.payload,
|
||||
}
|
||||
|
||||
@classmethod
|
||||
def from_dict(cls, data: dict) -> ClusterMessage:
|
||||
status_raw = data.get("status")
|
||||
status = CommandStatus(status_raw) if status_raw else None
|
||||
return cls(
|
||||
cluster_id=data["cluster_id"],
|
||||
node_id=data["node_id"],
|
||||
command_id=data["command_id"],
|
||||
sequence=int(data["sequence"]),
|
||||
project_revision=int(data["project_revision"]),
|
||||
sender_time_ns=data.get("sender_time_ns"),
|
||||
execute_at_show_time_ns=data.get("execute_at_show_time_ns"),
|
||||
trace_id=data.get("trace_id"),
|
||||
status=status,
|
||||
payload=data.get("payload", {}),
|
||||
)
|
||||
|
||||
|
||||
class CommandTracker:
|
||||
"""Idempotenz je (node_id, command_id) mit Statusübergängen (§6.5).
|
||||
|
||||
- register: neuer Command → True; Duplikat → False (gleiches Ack)
|
||||
- advance: nur vorwärts accepted → armed → executed/failed
|
||||
- veraltete Einträge werden nach Kapazität begrenzt (kein unbeschränkter
|
||||
Cache, §33)
|
||||
"""
|
||||
|
||||
_ORDER = {
|
||||
CommandStatus.ACCEPTED: 1,
|
||||
CommandStatus.ARMED: 2,
|
||||
CommandStatus.EXECUTED: 3,
|
||||
CommandStatus.FAILED: 3,
|
||||
}
|
||||
|
||||
def __init__(self, capacity: int = 4096) -> None:
|
||||
if capacity <= 0:
|
||||
raise ValueError("capacity must be positive")
|
||||
self._capacity = capacity
|
||||
self._states: dict[str, CommandStatus] = {}
|
||||
|
||||
def register(self, node_id: str, command_id: str) -> bool:
|
||||
"""True, wenn der Command neu ist; False bei Duplikat."""
|
||||
key = f"{node_id}:{command_id}"
|
||||
if key in self._states:
|
||||
return False
|
||||
self._states[key] = CommandStatus.ACCEPTED
|
||||
if len(self._states) > self._capacity:
|
||||
oldest = next(iter(self._states))
|
||||
del self._states[oldest]
|
||||
return True
|
||||
|
||||
def advance(self, node_id: str, command_id: str, new_status: CommandStatus) -> bool:
|
||||
"""Nur vorwärts; False bei unbekanntem Command oder Rückschritt."""
|
||||
key = f"{node_id}:{command_id}"
|
||||
current = self._states.get(key)
|
||||
if current is None:
|
||||
return False
|
||||
if self._ORDER[new_status] <= self._ORDER[current]:
|
||||
return False
|
||||
self._states[key] = new_status
|
||||
return True
|
||||
|
||||
def status(self, node_id: str, command_id: str) -> CommandStatus | None:
|
||||
return self._states.get(f"{node_id}:{command_id}")
|
||||
@@ -0,0 +1,175 @@
|
||||
"""Node-Paarung: PIN, Fingerprint, Token-Scopes, Widerruf (§6.3, §27.1)."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import hmac
|
||||
import secrets
|
||||
import time
|
||||
from dataclasses import dataclass, field
|
||||
from enum import StrEnum
|
||||
|
||||
PIN_TTL_S = 120.0
|
||||
|
||||
|
||||
class Scope(StrEnum):
|
||||
"""Getrennte Berechtigungsscopes (§27.1)."""
|
||||
|
||||
READ = "read"
|
||||
CONTROL = "control"
|
||||
CONTENT_SYNC = "content_sync"
|
||||
ADMIN = "admin"
|
||||
|
||||
|
||||
_ALL_SCOPES = frozenset(s.value for s in Scope)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class PairingPin:
|
||||
"""Kurzlebige Paarungs-PIN (§6.3)."""
|
||||
|
||||
value: str
|
||||
created_ns: int
|
||||
|
||||
@property
|
||||
def expires_ns(self) -> int:
|
||||
return self.created_ns + int(PIN_TTL_S * 1_000_000_000)
|
||||
|
||||
|
||||
def generate_pin() -> PairingPin:
|
||||
"""6-stellige PIN, kryptographisch erzeugt (§6.3)."""
|
||||
return PairingPin(
|
||||
value=f"{secrets.randbelow(1_000_000):06d}",
|
||||
created_ns=time.monotonic_ns(),
|
||||
)
|
||||
|
||||
|
||||
def pin_valid(pin: PairingPin, now_ns: int | None = None) -> bool:
|
||||
now = now_ns if now_ns is not None else time.monotonic_ns()
|
||||
return now <= pin.expires_ns
|
||||
|
||||
|
||||
def identity_fingerprint(
|
||||
node_id: str,
|
||||
display_name: str,
|
||||
public_key_pem: str | None = None,
|
||||
) -> str:
|
||||
"""Sichtbarer Fingerprint über öffentliche Identitätsdaten (§6.3).
|
||||
|
||||
Format: 8 Gruppen à 4 Hex-Zeichen (128 Bits des SHA-256), für Menschen
|
||||
vergleichbar.
|
||||
"""
|
||||
material = f"{node_id}|{display_name}".encode()
|
||||
if public_key_pem:
|
||||
material += b"|" + public_key_pem.encode("ascii", errors="replace")
|
||||
digest = hashlib.sha256(material).hexdigest()
|
||||
groups = [digest[i : i + 4] for i in range(0, 32, 4)]
|
||||
return ":".join(groups)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class PairedToken:
|
||||
"""Ausgestelltes Token; nur der Hash wird gespeichert (§27.1)."""
|
||||
|
||||
token_hash: str
|
||||
scopes: frozenset[str]
|
||||
expires_ns: int | None
|
||||
created_ns: int
|
||||
|
||||
|
||||
def hash_token(token: str) -> str:
|
||||
"""Token-Hash; Klartext existiert nur beim Besitzer."""
|
||||
return hashlib.sha256(token.encode("utf-8")).hexdigest()
|
||||
|
||||
|
||||
def new_token(scopes: frozenset[str], ttl_s: float | None = None) -> tuple[str, PairedToken]:
|
||||
"""Erzeugt Token + gespeicherte Repräsentation; Klartext genau einmal."""
|
||||
unknown = scopes - _ALL_SCOPES
|
||||
if unknown:
|
||||
raise ValueError(f"unknown scopes: {sorted(unknown)}")
|
||||
if not scopes:
|
||||
raise ValueError("scopes must not be empty")
|
||||
now = time.monotonic_ns()
|
||||
token = secrets.token_urlsafe(32)
|
||||
expires = now + int(ttl_s * 1_000_000_000) if ttl_s is not None else None
|
||||
return token, PairedToken(
|
||||
token_hash=hash_token(token),
|
||||
scopes=scopes,
|
||||
expires_ns=expires,
|
||||
created_ns=now,
|
||||
)
|
||||
|
||||
|
||||
@dataclass
|
||||
class PairingStore:
|
||||
"""PINs, Paarungszustand und Tokens je Node (§6.3, §27.1, ADR-0010)."""
|
||||
|
||||
_pins: dict[str, PairingPin] = field(default_factory=dict)
|
||||
_tokens: dict[str, PairedToken] = field(default_factory=dict)
|
||||
_failed_attempts: dict[str, int] = field(default_factory=dict)
|
||||
max_pin_attempts: int = 3
|
||||
|
||||
def issue_pin(self, node_id: str) -> PairingPin:
|
||||
pin = generate_pin()
|
||||
self._pins[node_id] = pin
|
||||
self._failed_attempts.pop(node_id, None)
|
||||
return pin
|
||||
|
||||
def complete_pairing(
|
||||
self,
|
||||
node_id: str,
|
||||
entered_pin: str,
|
||||
fingerprint_seen: str,
|
||||
expected_fingerprint: str,
|
||||
scopes: frozenset[str],
|
||||
token_ttl_s: float | None = None,
|
||||
now_ns: int | None = None,
|
||||
) -> str:
|
||||
"""Prüft PIN + Fingerprint, stellt Token aus; gibt Klartext zurück.
|
||||
|
||||
Fehlversuche erhöhen den Zähler; nach max_pin_attempts wird die PIN
|
||||
gesperrt (Neuausstellung nötig). Vergleiche konstantzeit über
|
||||
hmac.compare_digest.
|
||||
"""
|
||||
pin = self._pins.get(node_id)
|
||||
now = now_ns if now_ns is not None else time.monotonic_ns()
|
||||
if pin is None:
|
||||
raise PermissionError("keine PIN ausgestellt")
|
||||
if self._failed_attempts.get(node_id, 0) >= self.max_pin_attempts:
|
||||
raise PermissionError("PIN gesperrt; neu ausstellen")
|
||||
if not pin_valid(pin, now_ns=now) or not hmac.compare_digest(pin.value, entered_pin):
|
||||
self._failed_attempts[node_id] = self._failed_attempts.get(node_id, 0) + 1
|
||||
raise PermissionError("PIN falsch oder abgelaufen")
|
||||
if not hmac.compare_digest(
|
||||
fingerprint_seen.strip().lower(), expected_fingerprint.strip().lower()
|
||||
):
|
||||
self._failed_attempts[node_id] = self._failed_attempts.get(node_id, 0) + 1
|
||||
raise PermissionError("Fingerprint stimmt nicht ueberein")
|
||||
token, stored = new_token(scopes, ttl_s=token_ttl_s)
|
||||
self._tokens[node_id] = stored
|
||||
self._pins.pop(node_id, None) # PIN nur einmal verwendbar
|
||||
self._failed_attempts.pop(node_id, None)
|
||||
return token
|
||||
|
||||
def revoke(self, node_id: str) -> None:
|
||||
"""Sofortiger Widerruf (§27.1)."""
|
||||
self._tokens.pop(node_id, None)
|
||||
self._pins.pop(node_id, None)
|
||||
|
||||
def verify(
|
||||
self,
|
||||
node_id: str,
|
||||
token: str,
|
||||
required_scope: Scope,
|
||||
now_ns: int | None = None,
|
||||
) -> bool:
|
||||
"""Token- und Scope-Prüfung; Hash-Vergleich konstantzeit."""
|
||||
stored = self._tokens.get(node_id)
|
||||
if stored is None:
|
||||
return False
|
||||
now = now_ns if now_ns is not None else time.monotonic_ns()
|
||||
if stored.expires_ns is not None and now > stored.expires_ns:
|
||||
return False
|
||||
if not hmac.compare_digest(stored.token_hash, hash_token(token)):
|
||||
return False
|
||||
return required_scope.value in stored.scopes
|
||||
@@ -0,0 +1,168 @@
|
||||
"""Node-Registry mit Heartbeat-Zuständen (PLAN.md §6.3, §6.5).
|
||||
|
||||
- Zustände je Node: online / degraded / stale / offline mit konfigurierbaren
|
||||
Schwellen (§6.5)
|
||||
- doppelte node_id wird als Fehler blockiert, nie still übernommen (§6.3)
|
||||
- Kategorien für die UI: discovered / paired / unknown / incompatible /
|
||||
offline werden getrennt geführt (§6.3)
|
||||
- persistente node_id bleibt identisch bei IP-Wechsel; Endpunkte werden
|
||||
als „zuletzt bekannt" aktualisiert (§10.1 Node)
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import time
|
||||
from dataclasses import dataclass, field
|
||||
from enum import StrEnum
|
||||
|
||||
|
||||
class NodeHealth(StrEnum):
|
||||
ONLINE = "online"
|
||||
DEGRADED = "degraded"
|
||||
STALE = "stale"
|
||||
OFFLINE = "offline"
|
||||
|
||||
|
||||
class NodeCategory(StrEnum):
|
||||
"""UI-Kategorien gemäß §6.3: gefunden, gepaart, unbekannt, inkompatibel,
|
||||
offline werden getrennt aufgeführt."""
|
||||
|
||||
DISCOVERED = "discovered"
|
||||
PAIRED = "paired"
|
||||
UNKNOWN = "unknown"
|
||||
INCOMPATIBLE = "incompatible"
|
||||
OFFLINE = "offline"
|
||||
|
||||
|
||||
class DuplicateNodeError(Exception):
|
||||
"""Doppelte node_id – wird als Fehler blockiert (§6.3)."""
|
||||
|
||||
|
||||
@dataclass
|
||||
class NodeEntry:
|
||||
"""Registry-Eintrag: Identität stabil, Endpunkte „zuletzt bekannt" (§10.1)."""
|
||||
|
||||
node_id: str
|
||||
display_name: str
|
||||
roles: tuple[str, ...] = ()
|
||||
api_port: int = 0
|
||||
protocol_version: int = 1
|
||||
capability_digest: str = ""
|
||||
last_known_endpoints: list[str] = field(default_factory=list)
|
||||
last_heartbeat_ns: int = 0
|
||||
health: NodeHealth = NodeHealth.OFFLINE
|
||||
category: NodeCategory = NodeCategory.DISCOVERED
|
||||
clock_offset_ns: int = 0
|
||||
|
||||
def record_endpoint(self, endpoint: str) -> None:
|
||||
"""IP-Wechsel: node_id bleibt, Endpunkt wird aktualisiert (§6.3)."""
|
||||
if endpoint in self.last_known_endpoints:
|
||||
self.last_known_endpoints.remove(endpoint)
|
||||
self.last_known_endpoints.insert(0, endpoint)
|
||||
del self.last_known_endpoints[4:] # die letzten 5 genügen
|
||||
|
||||
|
||||
@dataclass
|
||||
class HealthThresholds:
|
||||
"""Konfigurierbare Schwellen je Zustand (§6.5).
|
||||
|
||||
Heartbeat pünktlich < degraded_after_ns; verspätet, aber vorhanden
|
||||
< stale_after_ns; danach offline. Standard-Heartbeat 500 ms (§6.5).
|
||||
"""
|
||||
|
||||
heartbeat_interval_ns: int = 500_000_000
|
||||
degraded_after_ns: int = 2_000_000_000 # 2 s ohne Heartbeat
|
||||
stale_after_ns: int = 5_000_000_000 # 5 s ohne Heartbeat
|
||||
|
||||
|
||||
class NodeRegistry:
|
||||
"""Autoritative Liste bekannter Nodes (Coordinator-seitig)."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
thresholds: HealthThresholds | None = None,
|
||||
protocol_version: int = 1,
|
||||
) -> None:
|
||||
self._nodes: dict[str, NodeEntry] = {}
|
||||
self._thresholds = thresholds or HealthThresholds()
|
||||
self._protocol_version = protocol_version
|
||||
|
||||
def register(
|
||||
self,
|
||||
node_id: str,
|
||||
display_name: str,
|
||||
roles: tuple[str, ...] = (),
|
||||
api_port: int = 0,
|
||||
protocol_version: int = 1,
|
||||
capability_digest: str = "",
|
||||
endpoint: str = "",
|
||||
) -> NodeEntry:
|
||||
"""Neue Node oder Update bekannter Node; Doppel-ID mit
|
||||
widersprüchlicher Identität ist ein Fehler (§6.3)."""
|
||||
existing = self._nodes.get(node_id)
|
||||
if existing is not None and existing.display_name != display_name:
|
||||
raise DuplicateNodeError(
|
||||
f"node_id {node_id} bereits als {existing.display_name!r} registriert"
|
||||
)
|
||||
if existing is None:
|
||||
entry = NodeEntry(
|
||||
node_id=node_id,
|
||||
display_name=display_name,
|
||||
roles=tuple(roles),
|
||||
api_port=api_port,
|
||||
protocol_version=protocol_version,
|
||||
capability_digest=capability_digest,
|
||||
)
|
||||
self._nodes[node_id] = entry
|
||||
else:
|
||||
entry = existing
|
||||
entry.roles = tuple(roles)
|
||||
entry.api_port = api_port
|
||||
entry.capability_digest = capability_digest
|
||||
if endpoint:
|
||||
entry.record_endpoint(endpoint)
|
||||
# Inkompatible Protokollversion sichtbar kategorisieren (§6.3)
|
||||
if entry.protocol_version != self._protocol_version:
|
||||
entry.category = NodeCategory.INCOMPATIBLE
|
||||
return entry
|
||||
|
||||
def record_heartbeat(self, node_id: str, clock_offset_ns: int = 0) -> None:
|
||||
entry = self._nodes.get(node_id)
|
||||
if entry is None:
|
||||
raise KeyError(f"unknown node {node_id}")
|
||||
entry.last_heartbeat_ns = time.monotonic_ns()
|
||||
entry.clock_offset_ns = clock_offset_ns
|
||||
|
||||
def evaluate_health(self, node_id: str) -> NodeHealth:
|
||||
"""Berechnet den Zustand aus letztem Heartbeat + Schwellen (§6.5)."""
|
||||
entry = self._nodes[node_id]
|
||||
if entry.last_heartbeat_ns == 0:
|
||||
entry.health = NodeHealth.OFFLINE
|
||||
if entry.category not in (NodeCategory.INCOMPATIBLE, NodeCategory.PAIRED):
|
||||
entry.category = NodeCategory.DISCOVERED
|
||||
return entry.health
|
||||
elapsed = time.monotonic_ns() - entry.last_heartbeat_ns
|
||||
if elapsed < self._thresholds.degraded_after_ns:
|
||||
entry.health = NodeHealth.ONLINE
|
||||
elif elapsed < self._thresholds.stale_after_ns:
|
||||
entry.health = NodeHealth.DEGRADED
|
||||
else:
|
||||
entry.health = NodeHealth.OFFLINE
|
||||
if entry.category is NodeCategory.PAIRED:
|
||||
entry.category = NodeCategory.OFFLINE # Vertrauen bleibt, nur weg
|
||||
return entry.health
|
||||
|
||||
def mark_paired(self, node_id: str) -> None:
|
||||
self._nodes[node_id].category = NodeCategory.PAIRED
|
||||
|
||||
def mark_unknown(self, node_id: str) -> None:
|
||||
self._nodes[node_id].category = NodeCategory.UNKNOWN
|
||||
|
||||
def get(self, node_id: str) -> NodeEntry | None:
|
||||
return self._nodes.get(node_id)
|
||||
|
||||
def by_category(self, category: NodeCategory) -> list[NodeEntry]:
|
||||
return [n for n in self._nodes.values() if n.category is category]
|
||||
|
||||
def all(self) -> list[NodeEntry]:
|
||||
return list(self._nodes.values())
|
||||
Reference in New Issue
Block a user