ReticulumTelemetryHub 0.1.0__py3-none-any.whl → 0.143.0__py3-none-any.whl

reticulum_telemetry_hub/internal_api/versioning.py

@@ -0,0 +1,63 @@
+"""API version negotiation utilities for the internal contract."""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable
+from typing import Optional
+
+from reticulum_telemetry_hub.internal_api.v1.schemas import SUPPORTED_API_VERSION
+
+
+_VERSION_PATTERN = re.compile(r"(\d+)\.(\d+)")
+
+
+class ApiVersionError(ValueError):
+    """Raised when API version negotiation fails."""
+
+
+def parse_api_version(value: str) -> tuple[int, int]:
+    """Parse a semantic API version string (major.minor)."""
+
+    match = _VERSION_PATTERN.fullmatch(value)
+    if not match:
+        raise ApiVersionError("Invalid API version format")
+    return int(match.group(1)), int(match.group(2))
+
+
+def is_version_compatible(
+    candidate: str, *, supported: str = SUPPORTED_API_VERSION
+) -> bool:
+    """Return True when candidate is compatible with supported."""
+
+    try:
+        major, minor = parse_api_version(candidate)
+        supported_major, supported_minor = parse_api_version(supported)
+    except ApiVersionError:
+        return False
+    return major == supported_major and minor >= supported_minor
+
+
+def negotiate_api_version(
+    peer_versions: Iterable[str], *, supported: str = SUPPORTED_API_VERSION
+) -> Optional[str]:
+    """Return the negotiated API version or None if incompatible."""
+
+    if any(is_version_compatible(version, supported=supported) for version in peer_versions):
+        return supported
+    return None
+
+
+def select_api_version(
+    peer_versions: Optional[Iterable[str]] = None,
+    *,
+    supported: str = SUPPORTED_API_VERSION,
+) -> str:
+    """Select a compatible API version or raise ApiVersionError."""
+
+    if not peer_versions:
+        return supported
+    negotiated = negotiate_api_version(peer_versions, supported=supported)
+    if negotiated is None:
+        raise ApiVersionError("No compatible API version")
+    return negotiated

reticulum_telemetry_hub/lxmf_daemon/Handlers.py

@@ -0,0 +1,122 @@
+import time
+import threading
+import RNS
+import RNS.vendor.umsgpack as msgpack
+
+from .LXMF import APP_NAME, stamp_cost_from_app_data, pn_announce_data_is_valid
+from .LXMessage import LXMessage
+
+
+class LXMFDeliveryAnnounceHandler:
+    def __init__(self, lxmrouter):
+        self.aspect_filter = APP_NAME + ".delivery"
+        self.receive_path_responses = True
+        self.lxmrouter = lxmrouter
+
+    def received_announce(self, destination_hash, announced_identity, app_data):
+        for lxmessage in self.lxmrouter.pending_outbound:
+            if destination_hash == lxmessage.destination_hash:
+                if (
+                    lxmessage.method == LXMessage.DIRECT
+                    or lxmessage.method == LXMessage.OPPORTUNISTIC
+                ):
+                    lxmessage.next_delivery_attempt = time.time()
+
+                    def outbound_trigger():
+                        while self.lxmrouter.processing_outbound:
+                            time.sleep(0.1)
+                        self.lxmrouter.process_outbound()
+
+                    threading.Thread(target=outbound_trigger, daemon=True).start()
+
+        try:
+            stamp_cost = stamp_cost_from_app_data(app_data)
+            self.lxmrouter.update_stamp_cost(destination_hash, stamp_cost)
+
+        except Exception as e:
+            RNS.log(
+                f"An error occurred while trying to decode announced stamp cost. The contained exception was: {e}",
+                RNS.LOG_ERROR,
+            )
+
+
+class LXMFPropagationAnnounceHandler:
+    def __init__(self, lxmrouter):
+        self.aspect_filter = APP_NAME + ".propagation"
+        self.receive_path_responses = True
+        self.lxmrouter = lxmrouter
+
+    def received_announce(
+        self,
+        destination_hash,
+        announced_identity,
+        app_data,
+        announce_packet_hash,
+        is_path_response,
+    ):
+        try:
+            if type(app_data) == bytes:
+                if self.lxmrouter.propagation_node:
+                    if pn_announce_data_is_valid(app_data):
+                        data = msgpack.unpackb(app_data)
+                        node_timebase = int(data[1])
+                        propagation_enabled = data[2]
+                        propagation_transfer_limit = int(data[3])
+                        propagation_sync_limit = int(data[4])
+                        propagation_stamp_cost = int(data[5][0])
+                        propagation_stamp_cost_flexibility = int(data[5][1])
+                        peering_cost = int(data[5][2])
+                        metadata = data[6]
+
+                        if destination_hash in self.lxmrouter.static_peers:
+                            static_peer = self.lxmrouter.peers[destination_hash]
+                            if not is_path_response or static_peer.last_heard == 0:
+                                self.lxmrouter.peer(
+                                    destination_hash=destination_hash,
+                                    timestamp=node_timebase,
+                                    propagation_transfer_limit=propagation_transfer_limit,
+                                    propagation_sync_limit=propagation_sync_limit,
+                                    propagation_stamp_cost=propagation_stamp_cost,
+                                    propagation_stamp_cost_flexibility=propagation_stamp_cost_flexibility,
+                                    peering_cost=peering_cost,
+                                    metadata=metadata,
+                                )
+
+                        else:
+                            if self.lxmrouter.autopeer and not is_path_response:
+                                if propagation_enabled == True:
+                                    if (
+                                        RNS.Transport.hops_to(destination_hash)
+                                        <= self.lxmrouter.autopeer_maxdepth
+                                    ):
+                                        self.lxmrouter.peer(
+                                            destination_hash=destination_hash,
+                                            timestamp=node_timebase,
+                                            propagation_transfer_limit=propagation_transfer_limit,
+                                            propagation_sync_limit=propagation_sync_limit,
+                                            propagation_stamp_cost=propagation_stamp_cost,
+                                            propagation_stamp_cost_flexibility=propagation_stamp_cost_flexibility,
+                                            peering_cost=peering_cost,
+                                            metadata=metadata,
+                                        )
+
+                                    else:
+                                        if destination_hash in self.lxmrouter.peers:
+                                            RNS.log(
+                                                f"Peer {self.lxmrouter.peers[destination_hash]} moved outside auto-peering range, breaking peering..."
+                                            )
+                                            self.lxmrouter.unpeer(
+                                                destination_hash, node_timebase
+                                            )
+
+                                elif propagation_enabled == False:
+                                    self.lxmrouter.unpeer(
+                                        destination_hash, node_timebase
+                                    )
+
+        except Exception as e:
+            RNS.log(
+                "Error while evaluating propagation node announce, ignoring announce.",
+                RNS.LOG_DEBUG,
+            )
+            RNS.log(f"The contained exception was: {str(e)}", RNS.LOG_DEBUG)

reticulum_telemetry_hub/lxmf_daemon/LXMF.py

@@ -0,0 +1,252 @@
+import RNS
+import RNS.vendor.umsgpack as msgpack
+
+APP_NAME = "lxmf"
+
+##########################################################
+# The following core fields are provided to facilitate   #
+# interoperability in data exchange between various LXMF #
+# clients and systems.                                   #
+##########################################################
+FIELD_EMBEDDED_LXMS = 0x01
+FIELD_TELEMETRY = 0x02
+FIELD_TELEMETRY_STREAM = 0x03
+FIELD_ICON_APPEARANCE = 0x04
+FIELD_FILE_ATTACHMENTS = 0x05
+FIELD_IMAGE = 0x06
+FIELD_AUDIO = 0x07
+FIELD_THREAD = 0x08
+FIELD_COMMANDS = 0x09
+FIELD_RESULTS = 0x0A
+FIELD_GROUP = 0x0B
+FIELD_TICKET = 0x0C
+FIELD_EVENT = 0x0D
+FIELD_RNR_REFS = 0x0E
+FIELD_RENDERER = 0x0F
+
+# For usecases such as including custom data structures,
+# embedding or encapsulating other data types or protocols
+# that are not native to LXMF, or bridging/tunneling
+# external protocols or services over LXMF, the following
+# fields are available. A format/type/protocol (or other)
+# identifier can be included in the CUSTOM_TYPE field, and
+# the embedded payload can be included in the CUSTOM_DATA
+# field. It is up to the client application to correctly
+# discern and potentially utilise any data embedded using
+# this mechanism.
+FIELD_CUSTOM_TYPE = 0xFB
+FIELD_CUSTOM_DATA = 0xFC
+FIELD_CUSTOM_META = 0xFD
+
+# The non-specific and debug fields are intended for
+# development, testing and debugging use.
+FIELD_NON_SPECIFIC = 0xFE
+FIELD_DEBUG = 0xFF
+
+##########################################################
+# The following section lists field-specific specifiers, #
+# modes and identifiers that are native to LXMF. It is   #
+# optional for any client or system to support any of    #
+# these, and they are provided as template for easing    #
+# interoperability without sacrificing expandability     #
+# and flexibility of the format.                         #
+##########################################################
+
+# Audio modes for the data structure in FIELD_AUDIO
+
+# Codec2 Audio Modes
+AM_CODEC2_450PWB = 0x01
+AM_CODEC2_450 = 0x02
+AM_CODEC2_700C = 0x03
+AM_CODEC2_1200 = 0x04
+AM_CODEC2_1300 = 0x05
+AM_CODEC2_1400 = 0x06
+AM_CODEC2_1600 = 0x07
+AM_CODEC2_2400 = 0x08
+AM_CODEC2_3200 = 0x09
+
+# Opus Audio Modes
+AM_OPUS_OGG = 0x10
+AM_OPUS_LBW = 0x11
+AM_OPUS_MBW = 0x12
+AM_OPUS_PTT = 0x13
+AM_OPUS_RT_HDX = 0x14
+AM_OPUS_RT_FDX = 0x15
+AM_OPUS_STANDARD = 0x16
+AM_OPUS_HQ = 0x17
+AM_OPUS_BROADCAST = 0x18
+AM_OPUS_LOSSLESS = 0x19
+
+# Custom, unspecified audio mode, the client must
+# determine it itself based on the included data.
+AM_CUSTOM = 0xFF
+
+# Message renderer specifications for FIELD_RENDERER.
+# The renderer specification is completely optional,
+# and only serves as an indication to the receiving
+# client on how to render the message contents. It is
+# not mandatory to implement, either on sending or
+# receiving sides, but is the recommended way to
+# signal how to render a message, if non-plaintext
+# formatting is used.
+RENDERER_PLAIN = 0x00
+RENDERER_MICRON = 0x01
+RENDERER_MARKDOWN = 0x02
+RENDERER_BBCODE = 0x03
+
+# Optional propagation node metadata fields. These
+# fields may be highly unstable in allocation and
+# availability until the version 1.0.0 release, so use
+# at your own risk until then, and expect changes!
+PN_META_VERSION = 0x00
+PN_META_NAME = 0x01
+PN_META_SYNC_STRATUM = 0x02
+PN_META_SYNC_THROTTLE = 0x03
+PN_META_AUTH_BAND = 0x04
+PN_META_UTIL_PRESSURE = 0x05
+PN_META_CUSTOM = 0xFF
+
+##########################################################
+# The following helper functions makes it easier to      #
+# handle and operate on LXMF data in client programs     #
+##########################################################
+
+
+def display_name_from_app_data(app_data=None):
+    if app_data == None:
+        return None
+    elif len(app_data) == 0:
+        return None
+    else:
+        # Version 0.5.0+ announce format
+        if (app_data[0] >= 0x90 and app_data[0] <= 0x9F) or app_data[0] == 0xDC:
+            peer_data = msgpack.unpackb(app_data)
+            if type(peer_data) == list:
+                if len(peer_data) < 1:
+                    return None
+                else:
+                    dn = peer_data[0]
+                    if dn == None:
+                        return None
+                    else:
+                        try:
+                            decoded = dn.decode("utf-8")
+                            return decoded
+                        except Exception as e:
+                            RNS.log(
+                                f"Could not decode display name in included announce data. The contained exception was: {e}",
+                                RNS.LOG_ERROR,
+                            )
+                            return None
+
+        # Original announce format
+        else:
+            return app_data.decode("utf-8")
+
+
+def stamp_cost_from_app_data(app_data=None):
+    if app_data == None or app_data == b"":
+        return None
+    else:
+        # Version 0.5.0+ announce format
+        if (app_data[0] >= 0x90 and app_data[0] <= 0x9F) or app_data[0] == 0xDC:
+            peer_data = msgpack.unpackb(app_data)
+            if type(peer_data) == list:
+                if len(peer_data) < 2:
+                    return None
+                else:
+                    return peer_data[1]
+
+        # Original announce format
+        else:
+            return None
+
+
+def pn_name_from_app_data(app_data=None):
+    if app_data == None:
+        return None
+    else:
+        if pn_announce_data_is_valid(app_data):
+            data = msgpack.unpackb(app_data)
+            metadata = data[6]
+            if not PN_META_NAME in metadata:
+                return None
+            else:
+                try:
+                    return metadata[PN_META_NAME].decode("utf-8")
+                except:
+                    return None
+
+    return None
+
+
+def pn_stamp_cost_from_app_data(app_data=None):
+    if app_data == None:
+        return None
+    else:
+        if pn_announce_data_is_valid(app_data):
+            data = msgpack.unpackb(app_data)
+            return data[5][0]
+        else:
+            return None
+
+
+def pn_announce_data_is_valid(data):
+    try:
+        if type(data) != bytes:
+            return False
+        else:
+            data = msgpack.unpackb(data)
+        if len(data) < 7:
+            raise ValueError(
+                "Invalid announce data: Insufficient peer data, likely from deprecated LXMF version"
+            )
+        else:
+            try:
+                int(data[1])
+            except:
+                raise ValueError("Invalid announce data: Could not decode timebase")
+            if data[2] != True and data[2] != False:
+                raise ValueError(
+                    "Invalid announce data: Indeterminate propagation node status"
+                )
+            try:
+                int(data[3])
+            except:
+                raise ValueError(
+                    "Invalid announce data: Could not decode propagation transfer limit"
+                )
+            try:
+                int(data[4])
+            except:
+                raise ValueError(
+                    "Invalid announce data: Could not decode propagation sync limit"
+                )
+            if type(data[5]) != list:
+                raise ValueError("Invalid announce data: Could not decode stamp costs")
+            try:
+                int(data[5][0])
+            except:
+                raise ValueError(
+                    "Invalid announce data: Could not decode target stamp cost"
+                )
+            try:
+                int(data[5][1])
+            except:
+                raise ValueError(
+                    "Invalid announce data: Could not decode stamp cost flexibility"
+                )
+            try:
+                int(data[5][2])
+            except:
+                raise ValueError("Invalid announce data: Could not decode peering cost")
+            if type(data[6]) != dict:
+                raise ValueError("Invalid announce data: Could not decode metadata")
+
+    except Exception as e:
+        RNS.log(
+            f"Could not validate propagation node announce data: {e}", RNS.LOG_DEBUG
+        )
+        return False
+
+    return True