meshsocket 0.1.1__tar.gz → 0.2.0__tar.gz

{meshsocket-0.1.1 → meshsocket-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshsocket
-Version: 0.1.1
+Version: 0.2.0
 Summary: Lightweight WebSocket mesh networking — broadcast, direct routing, and request/response over a simple JSON wire protocol.
 Author: Carter Beaudoin
 License-Expression: MIT

{meshsocket-0.1.1 → meshsocket-0.2.0}/meshsocket/__init__.py

@@ -4,7 +4,7 @@
 `from socketCore import MeshSocket` continues to work (the module is published alongside)
 so existing code keeps running while it migrates to the package name.
 """
-from socketCore import MeshSocket, LogColors
+from socketCore import MeshSocket, LogColors, sanitize_identity, valid_ident, IDENT_RE, NAMESPACED_RE
 
-__all__ = ["MeshSocket", "LogColors"]
-__version__ = "0.1.0"
+__all__ = ["MeshSocket", "LogColors", "sanitize_identity", "valid_ident", "IDENT_RE", "NAMESPACED_RE"]
+__version__ = "0.2.0"

{meshsocket-0.1.1 → meshsocket-0.2.0}/meshsocket.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshsocket
-Version: 0.1.1
+Version: 0.2.0
 Summary: Lightweight WebSocket mesh networking — broadcast, direct routing, and request/response over a simple JSON wire protocol.
 Author: Carter Beaudoin
 License-Expression: MIT

{meshsocket-0.1.1 → meshsocket-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "meshsocket"
-version = "0.1.1"
+version = "0.2.0"
 description = "Lightweight WebSocket mesh networking — broadcast, direct routing, and request/response over a simple JSON wire protocol."
 readme = "README.md"
 requires-python = ">=3.10"

{meshsocket-0.1.1 → meshsocket-0.2.0}/socketCore.py

@@ -3,14 +3,56 @@ import certifi
 import inspect
 import json
 import ssl
+import stat
 import uuid
 import time
 import logging
 import os
+import re
 import websockets
+from urllib.parse import urlsplit
 from collections import deque
 from typing import Callable, Dict, Any, List, Optional
 
+# Identity grammar enforced by the relay (see socket_server): a plain identifier,
+# or the carter-relay gateway's `<account digits>.<identifier>` form.
+IDENT_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$")
+NAMESPACED_RE = re.compile(r"^[0-9]{1,32}\.[A-Za-z0-9][A-Za-z0-9_-]{0,63}$")
+_NS_PREFIX_RE = re.compile(r"^([0-9]{1,32})\.(.*)$", re.S)
+
+
+def valid_ident(value: Any) -> bool:
+    return isinstance(value, str) and bool(IDENT_RE.match(value) or NAMESPACED_RE.match(value))
+
+
+def sanitize_identity(value: Any, kind: str = "name") -> str:
+    """Turn a free-form string into a name/channel the relay accepts.
+
+    The relay itself does NOT sanitize: an identify whose name or channel fails
+    the grammar is closed with 1008. Clients call this before identifying (for
+    example on a device name such as "Carter's iPhone" -> "Carter-s-iPhone").
+
+    Rule (identical in relay, gateway and app): `value` must be a str of 1..256
+    chars, else ValueError. A leading `<digits>.` namespace prefix is kept and
+    only the remainder is sanitized. Every char outside [A-Za-z0-9_-] becomes
+    "-", runs of "-" collapse to one, leading/trailing "-" (and a leading "_",
+    which the grammar forbids) are stripped, the result is truncated to 64 chars,
+    and an empty result becomes "node" (kind="name") or "default"
+    (kind="channel"). The output always satisfies `valid_ident`.
+    """
+    if not isinstance(value, str) or not 1 <= len(value) <= 256:
+        raise ValueError(f"{kind} must be a string of 1..256 characters")
+    prefix = ""
+    m = _NS_PREFIX_RE.match(value)
+    if m:
+        prefix, value = m.group(1) + ".", m.group(2)
+    out = re.sub(r"[^A-Za-z0-9_-]", "-", value)
+    out = re.sub(r"-{2,}", "-", out).strip("-").lstrip("_")
+    out = out[:64].rstrip("-")
+    if not out:
+        out = "node" if kind == "name" else "default"
+    return prefix + out
+
 # ANSI Colors for nicer logs
 class LogColors:
     HEADER = '\033[95m'
@@ -75,9 +117,22 @@ class MeshSocket:
                  can_route: bool | None = None,
                  can_cross_channel_route: bool | None = None,
                  can_monitor: bool | None = None,
-                 broadcast_scope: str | None = None):
+                 broadcast_scope: str | None = None,
+                 ping_interval: float | None = 30.0,
+                 ping_timeout: float | None = 10.0,
+                 close_timeout: float | None = 5.0):
 
         self.url = url
+        # Client keepalive: a WebSocket ping every `ping_interval` seconds; if
+        # the pong takes longer than `ping_timeout` the socket is closed (1011)
+        # and the supervisor reconnects. None disables (library default was an
+        # implicit 20/20). The relay pings independently.
+        self.ping_interval = ping_interval
+        self.ping_timeout = ping_timeout
+        # How long to wait for the peer's close frame once WE decide to close
+        # (e.g. after a pong timeout). A dead peer never answers, so this bounds
+        # how long a detected-dead socket lingers before the supervisor redials.
+        self.close_timeout = close_timeout
         self.connection = connection
         self.auth_token = auth_token or os.getenv('MESH_AUTH_TOKEN')
         self.channel = channel or os.getenv("MESH_CHANNEL")
@@ -93,7 +148,10 @@ class MeshSocket:
         else:
             self.name = name
 
-        self.id = str(uuid.uuid4())
+        # `id` is a property: the server freezes it once the client is registered
+        # (see `freeze_id`) so no later frame can move a node in the routing table.
+        self._id = str(uuid.uuid4())
+        self._id_frozen = False
 
         # Callbacks
         self.on_reconnect_callback = on_reconnect
@@ -110,6 +168,10 @@ class MeshSocket:
 
         # State
         self.is_running = False
+        # Set by stop(reason=...) when the client is being torn down because of a
+        # FAULT rather than an ordinary shutdown; surfaced when the supervisor exits.
+        self.stopped_reason: Optional[str] = None
+        self._maintain_task: Optional[asyncio.Task] = None
 
         # Lazy-initialised inside the event loop to avoid DeprecationWarning
         # in Python 3.10+ when constructing outside an async context.
@@ -126,10 +188,34 @@ class MeshSocket:
         self.handlers: Dict[str, Callable] = {}
         self._pending_requests: Dict[str, asyncio.Future] = {}
 
-        self.on("handshake", self._handle_handshake)
+        # Optional pre-dispatch gate: `authorize(msg_type) -> bool`. The server
+        # installs one per connection so unidentified sockets can reach nothing
+        # but `identify`; None means every registered handler is reachable.
+        self.authorize: Optional[Callable[[str], bool]] = None
+
+        # `ping` is answered in both modes. The rest are CLIENT-mode handlers:
+        # a server-side node must never let its peer rewrite its id via
+        # `welcome`, nor answer `handshake`/`status_request` before the server's
+        # own auth gate has admitted the socket.
         self.on("ping", self._handle_ping)
-        self.on("status_request", self._handle_status_request)
-        self.on("welcome", self._handle_welcome)
+        if connection is None:
+            self.on("handshake", self._handle_handshake)
+            self.on("status_request", self._handle_status_request)
+            self.on("welcome", self._handle_welcome)
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    @id.setter
+    def id(self, value: str):
+        if self._id_frozen:
+            raise AttributeError("MeshSocket.id is immutable once registered")
+        self._id = value
+
+    def freeze_id(self):
+        """Make `id` read-only. The server calls this right after registration."""
+        self._id_frozen = True
 
     @property
     def connected_event(self) -> asyncio.Event:
@@ -141,7 +227,25 @@ class MeshSocket:
         return self._connected_event
 
     def __str__(self):
-        return f"{self.name}, {self.url}"
+        return f"{self.name}, {self.safe_url}"
+
+    @property
+    def safe_url(self) -> Optional[str]:
+        """scheme://host[:port] only — never the path or query, which may carry a
+        token, and which therefore must never reach a log line."""
+        if not self.url:
+            return self.url
+        try:
+            parts = urlsplit(self.url)
+        except ValueError:
+            return "<unparseable url>"
+        if not parts.scheme or not parts.hostname:
+            return "<unparseable url>"
+        host = parts.hostname
+        if ":" in host:
+            host = f"[{host}]"
+        port = f":{parts.port}" if parts.port else ""
+        return f"{parts.scheme}://{host}{port}"
 
     def on(self, type: str, func: Callable = None):
         if func is None:
@@ -202,12 +306,25 @@ class MeshSocket:
             raise ValueError("Cannot use start() without a URL.")
         self._start_time = time.time()
         self.is_running = True
-        asyncio.create_task(self._maintain_connection())
+        self.stopped_reason = None
+        # Hold the reference: the loop keeps only a weak one, so an unreferenced
+        # task can be garbage-collected mid-flight and take the reconnect
+        # supervisor down silently.
+        self._maintain_task = asyncio.create_task(self._maintain_connection())
 
     async def wait_until_ready(self):
         await self.connected_event.wait()
 
-    async def stop(self):
+    async def stop(self, reason: str = None):
+        """Shut the client down for good (the supervisor will NOT reconnect).
+
+        `reason` marks this as a FAULT rather than an intentional shutdown: it
+        is recorded on `stopped_reason` and logged at ERROR when the supervisor
+        exits. Callers giving up on a socket should always pass one — a caller
+        that reuses the plain shutdown path to mean "fatal error" produces a
+        dead client that never reconnects and never says why.
+        """
+        self.stopped_reason = reason
         self.is_running = False
         if self.connection:
             await self.connection.close()
@@ -227,20 +344,47 @@ class MeshSocket:
 
     # --- INTERNAL CORE ---
     async def _maintain_connection(self):
+        try:
+            await self._maintain_connection_inner()
+        finally:
+            # INVARIANT: this supervisor never dies quietly. While it is alive the
+            # client reconnects forever; once it exits the client is dead until
+            # something calls start() again, so every exit — intentional shutdown,
+            # fault, cancellation, or a bug — must leave a line in the log. A
+            # silent exit here once cost ~30 h of a "connected" client that was
+            # never coming back.
+            if self.stopped_reason:
+                logging.error(f"{LogColors.FAIL}{self.name} connection supervisor "
+                              f"STOPPED: {self.stopped_reason} — this client will "
+                              f"not reconnect until start() is called again"
+                              f"{LogColors.ENDC}")
+            elif self.is_running:
+                logging.error(f"{LogColors.FAIL}{self.name} connection supervisor "
+                              f"exited unexpectedly while still running — this "
+                              f"client will NOT reconnect{LogColors.ENDC}")
+            else:
+                logging.info(f"{self.name} connection supervisor stopped (shutdown)")
+
+    async def _maintain_connection_inner(self):
         retry_delay = 2
         while self.is_running:
             listen_task = None
             admitted = False
             try:
-                logging.info(f"{LogColors.BLUE}{self.name} connecting to {self.url}...{LogColors.ENDC}")
+                logging.info(f"{LogColors.BLUE}{self.name} connecting to {self.safe_url}...{LogColors.ENDC}")
                 ssl_context = ssl.create_default_context(cafile=certifi.where()) if self.url.startswith("wss://") else None
-                async with websockets.connect(self.url, ssl=ssl_context) as ws:
+                async with websockets.connect(self.url, ssl=ssl_context,
+                                              ping_interval=self.ping_interval,
+                                              ping_timeout=self.ping_timeout,
+                                              close_timeout=self.close_timeout) as ws:
                     self.connection = ws
                     retry_delay = 2
 
                     # Arm the admission gate before identify so a welcome delivered
-                    # by the concurrently-running listen loop can't be missed.
+                    # by the concurrently-running listen loop can't be missed. Each
+                    # attempt gets a fresh server-assigned id, so unfreeze it here.
                     self._admitted_event = asyncio.Event()
+                    self._id_frozen = False
 
                     # Send identify directly on the socket: connected_event is not
                     # set yet, so the normal send() path would buffer or raise.
@@ -322,8 +466,9 @@ class MeshSocket:
         return False
 
     # --- SEND LOGIC ---
-    async def send(self, type: str, payload: Any = None, reply_to: str = None) -> Optional[str]:
-        msg_id = str(uuid.uuid4())
+    async def send(self, type: str, payload: Any = None, reply_to: str = None,
+                   msg_id: str = None) -> Optional[str]:
+        msg_id = msg_id or str(uuid.uuid4())
         packet = {"id": msg_id, "type": type, "payload": payload, "reply_to": reply_to}
         packet_str = json.dumps(packet)
 
@@ -370,18 +515,46 @@ class MeshSocket:
         await loop.run_in_executor(None, self._write_lines_to_file, [packet_str])
 
     def _write_lines_to_file(self, lines: List[str]):
-        with open(self.offline_file_path, "a") as f:
+        # Owner-only from the first byte: the buffer holds frames that are
+        # replayed verbatim onto an authenticated socket.
+        fd = os.open(self.offline_file_path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+        with os.fdopen(fd, "a") as f:
             for line in lines:
                 f.write(line + "\n")
+        try:
+            os.chmod(self.offline_file_path, stat.S_IRUSR | stat.S_IWUSR)
+        except OSError:
+            pass
+
+    @staticmethod
+    def _valid_buffered_frame(line: str) -> bool:
+        """A replayable line is one JSON object with a string `type` (a frame this
+        client itself produced). Anything else was not written by us."""
+        try:
+            frame = json.loads(line)
+        except (ValueError, TypeError):
+            return False
+        return (isinstance(frame, dict) and isinstance(frame.get("type"), str)
+                and isinstance(frame.get("id"), str)
+                and frame.get("type") not in ("identify", "welcome"))
 
     async def _flush_offline_queue(self):
         if self.offline_file_path and os.path.exists(self.offline_file_path):
             logging.info(f"{LogColors.WARNING}Flushing disk buffer...{LogColors.ENDC}")
             try:
+                dropped = 0
                 with open(self.offline_file_path, "r") as f:
                     for line in f:
-                        if line.strip():
-                            await self.connection.send(line.strip())
+                        line = line.strip()
+                        if not line:
+                            continue
+                        if not self._valid_buffered_frame(line):
+                            dropped += 1
+                            continue
+                        await self.connection.send(line)
+                if dropped:
+                    logging.warning(f"{LogColors.WARNING}Dropped {dropped} invalid line(s) from the "
+                                    f"disk buffer (not frames this client wrote){LogColors.ENDC}")
                 os.remove(self.offline_file_path)
             except Exception as e:
                 logging.error(f"Failed to flush disk buffer: {e}")
@@ -397,16 +570,24 @@ class MeshSocket:
             logging.warning(f"Request '{type}' waiting for connection...")
             await self.connected_event.wait()
 
-        msg_id = await self.send(type, payload)
+        # Register the pending id BEFORE the frame leaves, so a reply that
+        # arrives faster than we can get back here is matched, not dropped.
+        msg_id = str(uuid.uuid4())
         loop = asyncio.get_running_loop()
         future = loop.create_future()
         self._pending_requests[msg_id] = future
+        try:
+            await self.send(type, payload, msg_id=msg_id)
+        except BaseException:
+            self._pending_requests.pop(msg_id, None)
+            raise
         try:
             return await asyncio.wait_for(future, timeout=timeout)
         except asyncio.TimeoutError:
             self._pending_requests.pop(msg_id, None)
             return None
         except asyncio.CancelledError:
+            self._pending_requests.pop(msg_id, None)
             return None
 
     def _fail_all_pending_requests(self):
@@ -414,7 +595,20 @@ class MeshSocket:
             if not future.done(): future.cancel()
         self._pending_requests.clear()
 
+    # Inbound handler tasks in flight per connection. When all slots are busy
+    # the read loop waits, which lets the websocket's own buffer apply
+    # backpressure to the peer instead of spawning unbounded tasks.
+    MAX_INFLIGHT = 64
+
     async def _listen_loop(self):
+        inflight = asyncio.Semaphore(self.MAX_INFLIGHT)
+
+        async def run(packet):
+            try:
+                await self._process_packet(packet)
+            finally:
+                inflight.release()
+
         async for message in self.connection:
             if self.rate_limit > 0:
                 now = time.time()
@@ -426,19 +620,31 @@ class MeshSocket:
 
             try:
                 data = json.loads(message)
-                asyncio.create_task(self._process_packet(data))
-            except json.JSONDecodeError:
-                pass
+            except (json.JSONDecodeError, TypeError, ValueError):
+                continue
+            await inflight.acquire()
+            asyncio.create_task(run(data))
 
     async def _process_packet(self, packet: dict):
+        if not isinstance(packet, dict):
+            return
         msg_id = packet.get('id')
         msg_type = packet.get('type')
         payload = packet.get('payload')
         reply_to = packet.get('reply_to')
-        if reply_to and reply_to in self._pending_requests:
-            future = self._pending_requests.pop(reply_to)
-            if not future.done(): future.set_result(payload)
-            return 
+        # Single pre-dispatch gate (server installs it per connection): nothing
+        # — not replies, not `ping`, not `node_status` — is processed for a
+        # socket the gate has not admitted.
+        if self.authorize is not None and not self.authorize(msg_type):
+            return
+        if reply_to:
+            # A reply is only ever a reply. One that matches no pending request
+            # (late, duplicate, or forged) is dropped — never re-dispatched as
+            # a fresh request of its `type`.
+            future = self._pending_requests.pop(reply_to, None)
+            if future is not None and not future.done():
+                future.set_result(payload)
+            return
         if msg_type in self.handlers:
             try:
                 response = await self.handlers[msg_type](payload)
@@ -448,13 +654,16 @@ class MeshSocket:
                 logging.error(f"Error processing {msg_type}: {e}")
 
     async def _handle_welcome(self, payload):
-        server_id = payload.get("id")
-        if server_id:
+        # Client mode only: a server-side node never accepts a peer's `welcome`
+        # (the handler is not registered there, and this guard is belt-and-braces).
+        if self._admitted_event is None:
+            return
+        server_id = payload.get("id") if isinstance(payload, dict) else None
+        if isinstance(server_id, str) and server_id and not self._id_frozen:
             logging.info(f"{self.name} assigned server ID: {server_id}")
             self.id = server_id
-        # Admit the connection (client mode). None in server mode.
-        if self._admitted_event is not None:
-            self._admitted_event.set()
+            self.freeze_id()
+        self._admitted_event.set()
 
     async def _handle_handshake(self, payload):
         t_remote = float(payload.get('t'))