define transport datagrams

enjo_lib/comm/transport/datagrams.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from collections.abc import (
+    Sequence,
+)
+from typing import (
+    Literal,
+)
+
+from ...our_types import (
+    EpochId,
+    HumanFriendlyDesc,
+    InstanceId,
+    JSON,
+    ServiceType,
+    ServiceClass,
+    serializable,
+)
+
+
+@serializable
+class GeneralTransportDatagram:
+    _version: int = 1
+    timestamp: int
+    sender: InstanceId
+    message_type: str
+    data: JSON | GeneralTransportMetadata | None
+
+
+@serializable
+class GeneralTransportMetadata:
+    pass
+
+
+# connect
+
+
+@serializable
+class ConnectDatagram(GeneralTransportDatagram):
+    message_type: Literal["connect"] = "connect"
+    data: ConnectMetadata
+
+
+@serializable
+class ConnectMetadata(GeneralTransportMetadata):
+    epoch: EpochId
+    type: ServiceType
+    service_classes: Sequence[ServiceClass]
+
+
+# disconnect
+
+
+@serializable
+class DisconnectDatagram(GeneralTransportDatagram):
+    message_type: Literal["disconnect"] = "disconnect"
+    data: DisconnectMetadata
+
+
+@serializable
+class DisconnectMetadata(GeneralTransportMetadata):
+    epoch: EpochId
+    exceptional: bool
+    reason: HumanFriendlyDesc
+
+
+# duplicate & replace sender types
+
+
+@serializable
+class DuplicateSenderDatagram(GeneralTransportDatagram):
+    message_type: Literal["duplicate_sender"] = "duplicate_sender"
+    data: ConnectMetadata
+
+
+@serializable
+class ReplaceSenderDatagram(GeneralTransportMetadata):
+    message_type: Literal["replace_sender"] = "replace_sender"
+    data: ConnectMetadata
+
+
+# failure
+
+
+@serializable
+class FailureDatagram(GeneralTransportDatagram):
+    message_type: Literal["failure"] = "failure"
+    data: FailureMetadata
+
+
+@serializable
+class FailureMetadata(GeneralTransportMetadata):
+    epoch: EpochId
+    reason: HumanFriendlyDesc
+
+
+# restart
+
+
+@serializable
+class RestartDatagram(GeneralTransportDatagram):
+    """issues a restart of a whole Enjo network"""
+
+    message_type: Literal["restart"] = "restart"
+    data: None = None
+
+
+# transmit
+
+
+@serializable
+class TransmitDatagram(GeneralTransportDatagram):
+    message_type: Literal["transmit"] = "transmit"
+    data: JSON

enjo_lib/our_types.py

@@ -7,10 +7,21 @@ from collections.abc import (
 from decimal import (
     Decimal,
 )
+from functools import (
+    partial,
+)
 from typing import (
     TypeAlias,
+    NewType,
     Union,
 )
+from uuid import (
+    UUID,
+)
+
+from attrs import (
+    define,
+)
 
 
 JSON: TypeAlias = Union[
@@ -21,3 +32,21 @@ JSON: TypeAlias = Union[
     Decimal,
     bool,
 ]
+
+
+serializable = partial(
+    define,
+    frozen=True,
+    kw_only=True,
+)
+
+
+ReverseDomainArg = NewType("ReverseDomainArg", str)
+"""e.g. `"de.6nw.enjo.controller"`"""
+
+
+InstanceId = NewType("InstanceId", UUID)
+ServiceType = NewType("ServiceType", ReverseDomainArg)
+ServiceClass = NewType("ServiceClass", ReverseDomainArg)
+EpochId = NewType("EpochId", UUID)
+HumanFriendlyDesc = NewType("HumanFriendlyDesc", str)