Phase 0: Repository-Initialisierung nach Bauplan v1.2

- Struktur gemäß §8 (Eigentumsgrenzen), PLAN.md als normative Basis - Pflichtdokumente: STATUS.md, ERRORS.md, TEST_REPORT.md, CHANGELOG.md, ADRs - ADR-0001 Python 3.13-Pin, ADR-0002 GStreamer 1.28.6-Pin (Windows), ADR-0003 IPC TCP+MessagePack v1 - Kernpakete: hms_protocol, hms_domain, hms_parameter, hms_artnet, hms_adaptive, hms_capabilities, hms_plugin_sdk - Renderer-Spike: D3D11-Primärpfad + Dev-GL-Pfad (§36 Nr. 4-5) - Control Core: FastAPI REST + WebSocket (§36 Nr. 9) - Beispielplugins: Passthrough + Gaussian Blur (3 Adaptive-Quality- Varianten, HLSL/GLSL/GLES) - Tools: Art-Net-Emulator, Fixture-Generator (Master32/Layer64-CSV), Capability-Probe - JSON-Schemas: IPC, Plugin, Projekt, Cluster - 121 Unit-/Integrationstests grün, Ruff grün Gate 0 bleibt offen: Hardwaremessungen nur auf echter Windows-Referenz- hardware gültig (§29.7, §33).
2026-09-11 00:36:59 +02:00
commit 0922cc1d68
133 changed files with 7939 additions and 0 deletions
@@ -0,0 +1,18 @@
+"""hms_protocol – versioniertes IPC (PLAN.md §6.2, ADR-0003).
+
+Lokales TCP auf 127.0.0.1, length-prefixed MessagePack, Protokollversion 1.
+"""
+
+from hms_protocol.envelope import Envelope, MessageType
+from hms_protocol.framing import decode_frame, encode_frame, read_frame, write_frame
+from hms_protocol.idempotency import IdempotencyRegistry
+
+__all__ = [
+    "Envelope",
+    "MessageType",
+    "encode_frame",
+    "decode_frame",
+    "read_frame",
+    "write_frame",
+    "IdempotencyRegistry",
+]
@@ -0,0 +1,37 @@
+"""IPC-Nachrichten-Umschlag (PLAN.md §6.2)."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+PROTOCOL_VERSION = 1
+
+
+class MessageType(StrEnum):
+    COMMAND = "command"
+    EVENT = "event"
+    SNAPSHOT = "snapshot"
+    ACK = "ack"
+    ERROR = "error"
+    TELEMETRY = "telemetry"
+
+
+class Envelope(BaseModel):
+    """Jede IPC-Nachricht besitzt mindestens diese Felder (§6.2)."""
+
+    protocol_version: int = PROTOCOL_VERSION
+    message_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    type: MessageType
+    revision: int = 0
+    monotonic_timestamp_ns: int = Field(default_factory=lambda: time.monotonic_ns())
+    payload: dict = Field(default_factory=dict)
+
+    def model_post_init(self, _ctx: object) -> None:
+        if self.protocol_version != PROTOCOL_VERSION:
+            raise ValueError(
+                f"protocol_version {self.protocol_version} != {PROTOCOL_VERSION}"
+            )
@@ -0,0 +1,61 @@
+"""Length-prefixed MessagePack-Framing (ADR-0003).
+
+4-Byte-Big-Endian-Länge, danach MessagePack-Payload. Maximale Payloadgröße
+schützt vor unkontrollierten Queues/Resourcenerschöpfung (§6.2, §33).
+"""
+
+from __future__ import annotations
+
+import socket
+import struct
+
+import msgpack
+
+MAX_PAYLOAD_SIZE = 16 * 1024 * 1024  # 16 MiB Obergrenze je Nachricht
+_LENGTH = struct.Struct(">I")
+
+
+def encode_frame(payload: dict) -> bytes:
+    """Serialisiert ein dict zu length-prefixed MessagePack."""
+    body = msgpack.packb(payload, use_bin_type=True)
+    if len(body) > MAX_PAYLOAD_SIZE:
+        raise ValueError(f"payload too large: {len(body)} > {MAX_PAYLOAD_SIZE}")
+    return _LENGTH.pack(len(body)) + body
+
+
+def decode_frame(frame: bytes) -> dict:
+    """Dekodiert einen vollständigen Frame (Länge + Body)."""
+    if len(frame) < _LENGTH.size:
+        raise ValueError("frame too short")
+    (length,) = _LENGTH.unpack_from(frame, 0)
+    if length > MAX_PAYLOAD_SIZE:
+        raise ValueError(f"declared length {length} exceeds limit")
+    body = frame[_LENGTH.size : _LENGTH.size + length]
+    if len(body) != length:
+        raise ValueError(f"truncated frame: expected {length}, got {len(body)}")
+    return msgpack.unpackb(body, raw=False)
+
+
+def read_frame(sock: socket.socket) -> dict:
+    """Liest einen Frame von einem verbundenen Socket."""
+    header = _recv_exact(sock, _LENGTH.size)
+    (length,) = _LENGTH.unpack(header)
+    if length > MAX_PAYLOAD_SIZE:
+        raise ValueError(f"declared length {length} exceeds limit")
+    body = _recv_exact(sock, length)
+    return msgpack.unpackb(body, raw=False)
+
+
+def write_frame(sock: socket.socket, payload: dict) -> None:
+    """Schreibt einen Frame auf einen verbundenen Socket."""
+    sock.sendall(encode_frame(payload))
+
+
+def _recv_exact(sock: socket.socket, count: int) -> bytes:
+    buf = bytearray()
+    while len(buf) < count:
+        chunk = sock.recv(count - len(buf))
+        if not chunk:
+            raise ConnectionError("socket closed mid-frame")
+        buf.extend(chunk)
+    return bytes(buf)
@@ -0,0 +1,37 @@
+"""Idempotency-Registry für wiederholbare Commands (§6.2, §23.2)."""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import Any
+
+
+class IdempotencyRegistry:
+    """Merkt sich command_id → Ergebnis; Wiederholungen liefern dasselbe Ack."""
+
+    def __init__(self, capacity: int = 4096) -> None:
+        if capacity <= 0:
+            raise ValueError("capacity must be positive")
+        self._capacity = capacity
+        self._entries: OrderedDict[str, Any] = OrderedDict()
+
+    def register(self, command_id: str) -> bool:
+        """False, wenn die command_id bereits bekannt ist (Duplikat)."""
+        if command_id in self._entries:
+            self._entries.move_to_end(command_id)
+            return False
+        self._entries[command_id] = None  # Ergebnis folgt mit complete()
+        if len(self._entries) > self._capacity:
+            self._entries.popitem(last=False)
+        return True
+
+    def complete(self, command_id: str, result: Any) -> None:
+        if command_id in self._entries:
+            self._entries[command_id] = result
+            self._entries.move_to_end(command_id)
+
+    def result(self, command_id: str) -> Any | None:
+        return self._entries.get(command_id)
+
+    def __len__(self) -> int:
+        return len(self._entries)