HMS MediaEngine Agent
c4574927fd
- 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
2.2 KiB
2.2 KiB
ADR-0009: Node-Discovery – mDNS/DNS-SD mit manueller Fallback-Liste
- Status: Angenommen
- Datum: 2026-09-11
- Phase: 1
- Bauplan: §6.3, §27.1, §32 (ADR-Pflicht: Node-Discovery und manueller Subnetz-Fallback)
Entscheidung
- Discovery-Protokoll: mDNS/DNS-SD, Service-Typ
_hmsmedia._tcp.local.(§6.3). - TXT-Record enthält ausschließlich kleine, nicht vertrauliche Daten:
proto(Protokollversion),node(Node-ID),roles(Rollen, kommasepariert),port(API-Port),caps(Capability-Digest, kurzer Hash). Keine Tokens, keine Secrets (§27.1). - mDNS ist keine Vertrauensentscheidung: gefundene Nodes sind zunächst
discovered, steuerbar erst nach Paarung (ADR-0010). - Für Umgebungen ohne Multicast (VLAN, geroutete Netze, blockiertes mDNS) existiert eine persistente manuelle Node-Liste (Host/IP + Port) als gleichwertiger Fallback (§6.3).
- Bibliothek:
zeroconf(Standard-Python-mDNS) für den Betrieb auf Zielsystemen. Kein Eigenbau des Multicast-Stacks; Alternativen (python-avahi, Eigenbau) verworfen: plattformneutral unzureichend bzw. unnötiges Risiko (§33). Im Entwicklungscontainer werden nur Modell und Registry getestet (kein Multicast nötig); der Echtnetz-Test gehört zu Gate 1 (§29.2).
Alternativen
- Avahi via D-Bus: Linux-only, ungeeignet für Windows-first.
- Eigener Multicast-Code: hoher Aufwand, kein messbarer Nutzen.
- Nur manuelle Liste: widerspricht §6.3 (Discovery ist Fundament).
Folgen
hms_cluster.discoverydefiniert ServiceInfo (Instanzname, TXT-Kodierung) und Registry-Kategorien:discovered,paired,unknown,incompatible,offline(§6.3: UI führt Gruppen getrennt auf).- Doppelte Node-IDs werden als Fehler blockiert, nicht still gemischt (§6.3).
- Inkompatible Protokollversionen erscheinen als
incompatible.
Messwerte / Nachweise
- Unit-Tests: TXT-Roundtrip, Registry-Kategorien, Doppel-Node-ID-Blockade, manuelle Liste, Protokoll-Inkompatibilität.
- Multicast-Echtnetz-Test mit zwei Nodes: Teil von Gate 1 (§29.2), auf echter Hardware bzw. im LAN-Test nachzuholen.
Freigabe
- Standardumsetzung gemäß §6.3; zeroconf-Addition als ADR dokumentiert (§33).