refactor(server): extract framework-neutral protocol package

.gitignore

@@ -10,6 +10,7 @@ venv
 # ides
 .vscode
 .idea
+.cursor
 
 *~
 .*.swp

server/pyproject.toml

@@ -36,7 +36,7 @@ optional-dependencies.test = [ "pytest", "testcontainers>=4" ]
 urls.Repository = "https://github.com/ChannelFinder/recsync"
 
 [tool.setuptools]
-packages = [ "recceiver", "twisted.plugins" ]
+packages = [ "recceiver", "recceiver.protocol", "twisted.plugins" ]
 include-package-data = true
 package-data.twisted = [ "plugins/recceiver_plugin.py" ]
 

server/recceiver/announce.py

@@ -1,16 +1,14 @@
 # -*- coding: utf-8 -*-
 
 import logging
-import struct
-import sys
 
 from twisted.internet import protocol
 from twisted.internet.error import MessageLengthError
 
-_log = logging.getLogger(__name__)
+from recceiver.protocol.announce import ANNOUNCE_PORT, BROADCAST_ADDRESS, Announce
 
+_log = logging.getLogger(__name__)
 
-_Ann = struct.Struct(">HH4sHHI")
 
 __all__ = ["Announcer"]
 
@@ -20,19 +18,18 @@ def __init__(
         self,
         tcpport,
         key=0,
-        tcpaddr="\xff\xff\xff\xff",
-        udpaddrs=[("<broadcast>", 5049)],
+        host=BROADCAST_ADDRESS,
+        udpaddrs=None,
         period=15.0,
     ):
         from twisted.internet import reactor
 
         self.reactor = reactor
 
-        if sys.version_info[0] < 3:
-            self.msg = _Ann.pack(0x5243, 0, tcpaddr, tcpport, 0, key)
-        else:
-            self.msg = _Ann.pack(0x5243, 0, tcpaddr.encode("latin-1"), tcpport, 0, key)
+        if udpaddrs is None:
+            udpaddrs = [("<broadcast>", ANNOUNCE_PORT)]
 
+        self.msg = Announce(tcp_port=tcpport, key=key, host=host).encode()
         self.delay = period
         self.udps = udpaddrs
         self.udpErr = set()
@@ -43,7 +40,7 @@ def __init__(
     def startProtocol(self):
         _log.info("Setup Announcer")
         self.D = self.reactor.callLater(0, self.sendOne)
-        # we won't process any receieved traffic, so no reason to wake
+        # we won't process any received traffic, so no reason to wake
         # up for it...
         self.transport.pauseProducing()
 

server/recceiver/protocol/__init__.py

@@ -0,0 +1 @@
+"""Framework-neutral recsync protocol helpers."""

server/recceiver/protocol/announce.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+"""Framework-neutral RecSync UDP announce packet."""
+
+import socket
+import struct
+from dataclasses import dataclass
+from typing import ClassVar
+
+from recceiver.protocol.messages import PROTO_ID, ProtocolError
+
+ANNOUNCE_PORT = 5049
+BROADCAST_ADDRESS = "255.255.255.255"
+
+
+@dataclass(frozen=True)
+class Announce:
+    """UDP packet advertising the RecCeiver's TCP endpoint.
+
+    Wire layout: PROTO_ID(2) + 0(2) + SERV_ADDR(4) + PORT(2) + pad(2) + SERV_KEY(4).
+    """
+
+    payload: ClassVar = struct.Struct("!HH4sHxxI")
+
+    tcp_port: int
+    key: int = 0
+    host: str = BROADCAST_ADDRESS
+
+    def encode(self):
+        try:
+            addr = socket.inet_aton(self.host)
+        except OSError:
+            raise ProtocolError(f"invalid announce address: {self.host}")
+        reserved = 0
+        return self.payload.pack(PROTO_ID, reserved, addr, self.tcp_port, self.key)
+
+    @classmethod
+    def decode(cls, wire_bytes):
+        if len(wire_bytes) < cls.payload.size:
+            raise ProtocolError(f"announce packet must be at least {cls.payload.size} bytes")
+        proto_id, version, addr, tcp_port, key = cls.payload.unpack(wire_bytes[: cls.payload.size])
+        if proto_id != PROTO_ID:
+            raise ProtocolError(f"bad protocol id {proto_id:#06x}")
+        if version != 0:
+            raise ProtocolError(f"unsupported announce version {version}")
+        return cls(tcp_port=tcp_port, key=key, host=socket.inet_ntoa(addr))
+
+
+assert Announce.payload.size == 16