meshsocket 0.1.0__tar.gz

meshsocket-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carter Beaudoin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

meshsocket-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: meshsocket
+Version: 0.1.0
+Summary: Lightweight WebSocket mesh networking — broadcast, direct routing, and request/response over a simple JSON wire protocol.
+Author: Carter Beaudoin
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Mariner10/MeshSocket
+Project-URL: Repository, https://github.com/Mariner10/MeshSocket
+Keywords: websocket,mesh,networking,rpc,pubsub,asyncio
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: System :: Networking
+Classifier: Framework :: AsyncIO
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets>=12
+Requires-Dist: certifi
+Dynamic: license-file
+
+# MeshSocket (Python)
+
+A lightweight WebSocket **mesh networking** library. Nodes connect to a central relay and
+communicate by **broadcast**, **direct routing**, and **request/response** — all over a
+simple JSON wire protocol.
+
+## Install
+
+```bash
+pip install meshsocket
+```
+
+## Quickstart (client)
+
+```python
+import asyncio
+from meshsocket import MeshSocket
+
+async def main():
+    sock = MeshSocket(url="ws://localhost:8765", name="my-node",
+                      channel="demo", role="device", can_broadcast=True)
+
+    async def on_toggle(payload):
+        print("got", payload)
+        return {"ok": True}            # a returned value is delivered as the reply
+
+    sock.on("toggle", on_toggle)
+
+    await sock.start()                 # connect + identify
+    await sock.wait_until_ready()
+    await sock.send("reading", {"temp_c": 21.4})   # broadcast to the channel
+    await asyncio.sleep(60)
+    await sock.stop()
+
+asyncio.run(main())
+```
+
+## Wire protocol
+
+Every message is a JSON object:
+
+```json
+{ "id": "uuid", "type": "message_type", "payload": "<any JSON or null>", "reply_to": "uuid or null" }
+```
+
+If a handler returns a value, the receiver sends a reply with `reply_to` set to the
+original `id`, enabling request/response round-trips.
+
+## Compatibility
+
+`from meshsocket import MeshSocket` is the supported import. The historical
+`from socketCore import MeshSocket` still works (that module is published alongside the
+package) so existing code keeps running while it migrates.
+
+## Other language clients
+
+Swift (SPM, zero-dependency) and a planned JavaScript client live in the same repo:
+<https://github.com/Mariner10/MeshSocket>

meshsocket-0.1.0/README.md

@@ -0,0 +1,58 @@
+# MeshSocket (Python)
+
+A lightweight WebSocket **mesh networking** library. Nodes connect to a central relay and
+communicate by **broadcast**, **direct routing**, and **request/response** — all over a
+simple JSON wire protocol.
+
+## Install
+
+```bash
+pip install meshsocket
+```
+
+## Quickstart (client)
+
+```python
+import asyncio
+from meshsocket import MeshSocket
+
+async def main():
+    sock = MeshSocket(url="ws://localhost:8765", name="my-node",
+                      channel="demo", role="device", can_broadcast=True)
+
+    async def on_toggle(payload):
+        print("got", payload)
+        return {"ok": True}            # a returned value is delivered as the reply
+
+    sock.on("toggle", on_toggle)
+
+    await sock.start()                 # connect + identify
+    await sock.wait_until_ready()
+    await sock.send("reading", {"temp_c": 21.4})   # broadcast to the channel
+    await asyncio.sleep(60)
+    await sock.stop()
+
+asyncio.run(main())
+```
+
+## Wire protocol
+
+Every message is a JSON object:
+
+```json
+{ "id": "uuid", "type": "message_type", "payload": "<any JSON or null>", "reply_to": "uuid or null" }
+```
+
+If a handler returns a value, the receiver sends a reply with `reply_to` set to the
+original `id`, enabling request/response round-trips.
+
+## Compatibility
+
+`from meshsocket import MeshSocket` is the supported import. The historical
+`from socketCore import MeshSocket` still works (that module is published alongside the
+package) so existing code keeps running while it migrates.
+
+## Other language clients
+
+Swift (SPM, zero-dependency) and a planned JavaScript client live in the same repo:
+<https://github.com/Mariner10/MeshSocket>

meshsocket-0.1.0/meshsocket/__init__.py

@@ -0,0 +1,10 @@
+"""MeshSocket — lightweight WebSocket mesh networking.
+
+`from meshsocket import MeshSocket` is the supported public import. The historical
+`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
+
+__all__ = ["MeshSocket", "LogColors"]
+__version__ = "0.1.0"

meshsocket-0.1.0/meshsocket.egg-info/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: meshsocket
+Version: 0.1.0
+Summary: Lightweight WebSocket mesh networking — broadcast, direct routing, and request/response over a simple JSON wire protocol.
+Author: Carter Beaudoin
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Mariner10/MeshSocket
+Project-URL: Repository, https://github.com/Mariner10/MeshSocket
+Keywords: websocket,mesh,networking,rpc,pubsub,asyncio
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: System :: Networking
+Classifier: Framework :: AsyncIO
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets>=12
+Requires-Dist: certifi
+Dynamic: license-file
+
+# MeshSocket (Python)
+
+A lightweight WebSocket **mesh networking** library. Nodes connect to a central relay and
+communicate by **broadcast**, **direct routing**, and **request/response** — all over a
+simple JSON wire protocol.
+
+## Install
+
+```bash
+pip install meshsocket
+```
+
+## Quickstart (client)
+
+```python
+import asyncio
+from meshsocket import MeshSocket
+
+async def main():
+    sock = MeshSocket(url="ws://localhost:8765", name="my-node",
+                      channel="demo", role="device", can_broadcast=True)
+
+    async def on_toggle(payload):
+        print("got", payload)
+        return {"ok": True}            # a returned value is delivered as the reply
+
+    sock.on("toggle", on_toggle)
+
+    await sock.start()                 # connect + identify
+    await sock.wait_until_ready()
+    await sock.send("reading", {"temp_c": 21.4})   # broadcast to the channel
+    await asyncio.sleep(60)
+    await sock.stop()
+
+asyncio.run(main())
+```
+
+## Wire protocol
+
+Every message is a JSON object:
+
+```json
+{ "id": "uuid", "type": "message_type", "payload": "<any JSON or null>", "reply_to": "uuid or null" }
+```
+
+If a handler returns a value, the receiver sends a reply with `reply_to` set to the
+original `id`, enabling request/response round-trips.
+
+## Compatibility
+
+`from meshsocket import MeshSocket` is the supported import. The historical
+`from socketCore import MeshSocket` still works (that module is published alongside the
+package) so existing code keeps running while it migrates.
+
+## Other language clients
+
+Swift (SPM, zero-dependency) and a planned JavaScript client live in the same repo:
+<https://github.com/Mariner10/MeshSocket>

meshsocket-0.1.0/meshsocket.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+socketCore.py
+socket_server.py
+meshsocket/__init__.py
+meshsocket.egg-info/PKG-INFO
+meshsocket.egg-info/SOURCES.txt
+meshsocket.egg-info/dependency_links.txt
+meshsocket.egg-info/requires.txt
+meshsocket.egg-info/top_level.txt

meshsocket-0.1.0/meshsocket.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

meshsocket-0.1.0/meshsocket.egg-info/requires.txt

@@ -0,0 +1,2 @@
+websockets>=12
+certifi

meshsocket-0.1.0/meshsocket.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+meshsocket
+socketCore
+socket_server

meshsocket-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "meshsocket"
+version = "0.1.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"
+authors = [{ name = "Carter Beaudoin" }]
+keywords = ["websocket", "mesh", "networking", "rpc", "pubsub", "asyncio"]
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+    "websockets>=12",
+    "certifi",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Intended Audience :: Developers",
+    "Topic :: System :: Networking",
+    "Framework :: AsyncIO",
+    "Development Status :: 4 - Beta",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/Mariner10/MeshSocket"
+Repository = "https://github.com/Mariner10/MeshSocket"
+
+# Explicit layout (disables flat-layout auto-discovery, which would trip over the
+# test files and the empty package __init__ in this directory).
+[tool.setuptools]
+py-modules = ["socketCore", "socket_server"]
+packages = ["meshsocket"]

meshsocket-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

meshsocket-0.1.0/socketCore.py

@@ -0,0 +1,473 @@
+import asyncio
+import certifi
+import inspect
+import json
+import ssl
+import uuid
+import time
+import logging
+import os
+import websockets
+from collections import deque
+from typing import Callable, Dict, Any, List, Optional
+
+# ANSI Colors for nicer logs
+class LogColors:
+    HEADER = '\033[95m'
+    BLUE = '\033[94m'
+    GREEN = '\033[92m'
+    WARNING = '\033[93m'
+    FAIL = '\033[91m'
+    ENDC = '\033[0m'
+
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(message)s')
+
+class SocketLoggingHandler(logging.Handler):
+    def __init__(self, socket: 'MeshSocket'):
+        super().__init__()
+        self.socket = socket
+        self._is_logging = False # To prevent recursion
+
+    def emit(self, record):
+        if not self.socket.is_running or self._is_logging:
+            return
+        
+        log_entry = self.format(record)
+        # We use asyncio.create_task because emit is called from non-async contexts
+        try:
+            loop = asyncio.get_running_loop()
+            
+            async def send_log():
+                if self._is_logging: return
+                self._is_logging = True
+                try:
+                    await self.socket.send("service_log", {
+                        "level": record.levelname,
+                        "msg": log_entry,
+                        "name": self.socket.name,
+                        "timestamp": record.created
+                    })
+                except Exception:
+                    # Silently ignore errors in the logging handler to avoid loops
+                    pass
+                finally:
+                    self._is_logging = False
+
+            loop.create_task(send_log())
+        except RuntimeError:
+            # No running event loop
+            pass
+
+class MeshSocket:
+    def __init__(self,
+                 url: str = None,
+                 connection=None,
+                 name="Node",
+                 max_offline_buffer: int = 0,
+                 offline_file_path: str = None,
+                 on_reconnect: Callable = None,
+                 on_disconnect: Callable = None,
+                 auth_token: str = None,
+                 rate_limit: int = 0,
+                 channel: str = None,
+                 role: str = None,
+                 can_broadcast: bool | None = None,
+                 can_route: bool | None = None,
+                 can_cross_channel_route: bool | None = None,
+                 can_monitor: bool | None = None,
+                 broadcast_scope: str | None = None):
+
+        self.url = url
+        self.connection = connection
+        self.auth_token = auth_token or os.getenv('MESH_AUTH_TOKEN')
+        self.channel = channel or os.getenv("MESH_CHANNEL")
+        self.role = role or os.getenv("MESH_ROLE")
+        self.can_broadcast = can_broadcast
+        self.can_route = can_route
+        self.can_cross_channel_route = can_cross_channel_route
+        self.can_monitor = can_monitor
+        self.broadcast_scope = broadcast_scope or os.getenv("MESH_BROADCAST_SCOPE")
+
+        if name == "Node":
+            self.name = os.getenv('CONTAINER_NAME') or os.getenv('HOSTNAME') or "Node"
+        else:
+            self.name = name
+
+        self.id = str(uuid.uuid4())
+
+        # Callbacks
+        self.on_reconnect_callback = on_reconnect
+        self.on_disconnect_callback = on_disconnect
+
+        # Buffering state
+        self.max_offline_buffer = max_offline_buffer
+        self.offline_file_path = offline_file_path
+        self._ram_buffer: deque = deque()
+
+        # Rate limiting — track timestamps of last `rate_limit` messages
+        self.rate_limit = rate_limit
+        self._msg_times: Optional[deque] = deque(maxlen=rate_limit) if rate_limit > 0 else None
+
+        # State
+        self.is_running = False
+
+        # Lazy-initialised inside the event loop to avoid DeprecationWarning
+        # in Python 3.10+ when constructing outside an async context.
+        self._connected_event: Optional[asyncio.Event] = None
+        self._server_mode_connected: bool = connection is not None
+
+        # Admission gate (client mode): set when the server's `welcome` confirms
+        # our identify was accepted, so readiness/on_reconnect don't fire for a
+        # rejected identify (e.g. a duplicate name) that the server silently closes.
+        # Stays None in server mode.
+        self._admitted_event: Optional[asyncio.Event] = None
+
+        # Handlers
+        self.handlers: Dict[str, Callable] = {}
+        self._pending_requests: Dict[str, asyncio.Future] = {}
+
+        self.on("handshake", self._handle_handshake)
+        self.on("ping", self._handle_ping)
+        self.on("status_request", self._handle_status_request)
+        self.on("welcome", self._handle_welcome)
+
+    @property
+    def connected_event(self) -> asyncio.Event:
+        if self._connected_event is None:
+            self._connected_event = asyncio.Event()
+            if self._server_mode_connected:
+                self._connected_event.set()
+                self._server_mode_connected = False
+        return self._connected_event
+
+    def __str__(self):
+        return f"{self.name}, {self.url}"
+
+    def on(self, type: str, func: Callable = None):
+        if func is None:
+            def wrapper(f):
+                self.handlers[type] = f
+                return f
+            return wrapper
+        self.handlers[type] = func
+        return func
+
+    def off(self, type: str):
+        self.handlers.pop(type, None)
+
+    def setup_logging(self, level=logging.INFO):
+        """Attaches a SocketLoggingHandler to the root logger."""
+        handler = SocketLoggingHandler(self)
+        handler.setLevel(level)
+        formatter = logging.Formatter('%(name)s - %(levelname)s - %(message)s')
+        handler.setFormatter(formatter)
+        logging.getLogger().addHandler(handler)
+        logging.info(f"Socket logging enabled for {self.name}")
+
+    def _build_identity_payload(self) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {
+            "name": self.name,
+            "token": self.auth_token
+        }
+        if self.channel:
+            payload["channel"] = self.channel
+        if self.role:
+            payload["role"] = self.role
+        if self.can_broadcast is not None:
+            payload["can_broadcast"] = self.can_broadcast
+        if self.can_route is not None:
+            payload["can_route"] = self.can_route
+        if self.can_cross_channel_route is not None:
+            payload["can_cross_channel_route"] = self.can_cross_channel_route
+        if self.can_monitor is not None:
+            payload["can_monitor"] = self.can_monitor
+        if self.broadcast_scope:
+            payload["broadcast_scope"] = self.broadcast_scope
+        return payload
+
+    async def report_status(self, metrics: Dict[str, Any] = None):
+        """Broadcasts the current status/metrics of this node."""
+        status_payload = {
+            "name": self.name,
+            "id": self.id,
+            "status": "online",
+            "uptime": time.time() - self._start_time if hasattr(self, '_start_time') else 0,
+            "metrics": metrics or {}
+        }
+        await self.send("node_status", status_payload)
+
+    # --- CLIENT MODE METHODS ---
+    async def start(self):
+        if not self.url:
+            raise ValueError("Cannot use start() without a URL.")
+        self._start_time = time.time()
+        self.is_running = True
+        asyncio.create_task(self._maintain_connection())
+
+    async def wait_until_ready(self):
+        await self.connected_event.wait()
+
+    async def stop(self):
+        self.is_running = False
+        if self.connection:
+            await self.connection.close()
+
+    # --- SERVER MODE METHODS ---
+    async def listen(self):
+        if not self.connection:
+            raise ValueError("Server mode requires an existing connection.")
+        self._start_time = time.time()
+        try:
+            await self._listen_loop()
+        except websockets.exceptions.ConnectionClosed:
+            logging.warning(f"{self.name} connection closed normally.")
+        except Exception as e:
+            logging.error(f"{self.name} listen error: {e}")
+            raise e
+
+    # --- INTERNAL CORE ---
+    async def _maintain_connection(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}")
+                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:
+                    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.
+                    self._admitted_event = asyncio.Event()
+
+                    # Send identify directly on the socket: connected_event is not
+                    # set yet, so the normal send() path would buffer or raise.
+                    identify_packet = json.dumps({
+                        "id": str(uuid.uuid4()), "type": "identify",
+                        "payload": self._build_identity_payload(), "reply_to": None,
+                    })
+                    await ws.send(identify_packet)
+
+                    # Pump messages concurrently so the server's welcome — or a close
+                    # that rejects the identify (e.g. a duplicate name) — is observed
+                    # while we wait for admission.
+                    listen_task = asyncio.create_task(self._listen_loop())
+                    admitted = await self._await_admission(listen_task, timeout=10)
+                    if not admitted:
+                        # Never admitted: surface as a failed attempt and retry with
+                        # backoff instead of reporting the connection as up.
+                        listen_task.cancel()
+                        raise ConnectionError(
+                            "identify not admitted (no welcome) — likely a duplicate name or rejected token"
+                        )
+
+                    self.connected_event.set()
+                    logging.info(f"{LogColors.GREEN}{self.name} Connected!{LogColors.ENDC}")
+
+                    await self._flush_offline_queue()
+
+                    if self.on_reconnect_callback:
+                        try:
+                            if inspect.iscoroutinefunction(self.on_reconnect_callback):
+                                await self.on_reconnect_callback()
+                            else:
+                                self.on_reconnect_callback()
+                        except Exception as e:
+                            logging.error(f"Error in on_reconnect callback: {e}")
+
+                    await listen_task
+
+            except Exception as e:
+                # Catch everything (not just OSError/ConnectionClosed): a server
+                # restart behind Cloudflare surfaces as InvalidStatus (HTTP 521),
+                # which previously escaped and killed this task for good.
+                logging.warning(f"{LogColors.WARNING}{self.name} disconnected: {e}{LogColors.ENDC}")
+
+            finally:
+                if listen_task and not listen_task.done():
+                    listen_task.cancel()
+                self.connected_event.clear()
+                self.connection = None
+                self._fail_all_pending_requests()
+                # Pair on_disconnect to the admitted up-edge: an unadmitted attempt
+                # never reported connected, so it must not report a disconnect.
+                if admitted and self.on_disconnect_callback:
+                    try:
+                        if inspect.iscoroutinefunction(self.on_disconnect_callback):
+                            await self.on_disconnect_callback()
+                        else:
+                            self.on_disconnect_callback()
+                    except Exception as err:
+                        logging.error(f"Error in on_disconnect callback: {err}")
+
+            if self.is_running:
+                logging.info(f"{self.name} retrying in {retry_delay}s...")
+                await asyncio.sleep(retry_delay)
+                retry_delay = min(retry_delay * 2, 30)
+
+    async def _await_admission(self, listen_task: asyncio.Task, timeout: float) -> bool:
+        """Wait until the server's welcome admits this connection, or the socket
+        closes / times out first. Returns True only on a real admission."""
+        admit_wait = asyncio.ensure_future(self._admitted_event.wait())
+        done, _ = await asyncio.wait(
+            {admit_wait, listen_task},
+            timeout=timeout,
+            return_when=asyncio.FIRST_COMPLETED,
+        )
+        if admit_wait in done:
+            return True
+        admit_wait.cancel()
+        return False
+
+    # --- SEND LOGIC ---
+    async def send(self, type: str, payload: Any = None, reply_to: str = None) -> Optional[str]:
+        msg_id = str(uuid.uuid4())
+        packet = {"id": msg_id, "type": type, "payload": payload, "reply_to": reply_to}
+        packet_str = json.dumps(packet)
+
+        # CASE A: Connected - Send immediately
+        if self.connection and self.connected_event.is_set():
+            try:
+                await self.connection.send(packet_str)
+                return msg_id
+            except websockets.exceptions.ConnectionClosed:
+                logging.warning(f"Send failed mid-flight, attempting to buffer '{type}'")
+
+        # CASE B: Disconnected & Buffering Enabled
+        if self.max_offline_buffer > 0:
+            await self._handle_offline_buffering(packet_str)
+            return msg_id # Return ID even if buffered
+            
+        # CASE C: Disconnected & No Buffering
+        raise ConnectionError("Socket is not connected and buffering is disabled.")
+
+    async def emit(self, type: str, payload: Any = None, reply_to: str = None) -> Optional[str]:
+        return await self.send(type, payload, reply_to)
+
+    async def _handle_offline_buffering(self, packet_str: str):
+        if len(self._ram_buffer) >= self.max_offline_buffer:
+            if self.offline_file_path:
+                await self._dump_ram_to_disk()
+                await self._append_to_disk(packet_str)
+            else:
+                self._ram_buffer.popleft()
+                self._ram_buffer.append(packet_str)
+                logging.warning("Buffer full (no file path). Dropped oldest message.")
+        else:
+            self._ram_buffer.append(packet_str)
+
+    async def _dump_ram_to_disk(self):
+        if not self._ram_buffer:
+            return
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(None, self._write_lines_to_file, list(self._ram_buffer))
+        self._ram_buffer.clear()
+
+    async def _append_to_disk(self, packet_str: str):
+        loop = asyncio.get_running_loop()
+        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:
+            for line in lines:
+                f.write(line + "\n")
+
+    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:
+                with open(self.offline_file_path, "r") as f:
+                    for line in f:
+                        if line.strip():
+                            await self.connection.send(line.strip())
+                os.remove(self.offline_file_path)
+            except Exception as e:
+                logging.error(f"Failed to flush disk buffer: {e}")
+
+        if self._ram_buffer:
+            logging.info(f"{LogColors.WARNING}Flushing RAM buffer ({len(self._ram_buffer)} items)...{LogColors.ENDC}")
+            while self._ram_buffer:
+                await self.connection.send(self._ram_buffer.popleft())
+
+    # --- REQUEST / RESPONSE ---
+    async def request(self, type: str, payload: Any = None, timeout: float = 5.0):
+        if self.url and not self.connected_event.is_set():
+            logging.warning(f"Request '{type}' waiting for connection...")
+            await self.connected_event.wait()
+
+        msg_id = await self.send(type, payload)
+        loop = asyncio.get_running_loop()
+        future = loop.create_future()
+        self._pending_requests[msg_id] = future
+        try:
+            return await asyncio.wait_for(future, timeout=timeout)
+        except asyncio.TimeoutError:
+            self._pending_requests.pop(msg_id, None)
+            return None
+        except asyncio.CancelledError:
+            return None
+
+    def _fail_all_pending_requests(self):
+        for future in self._pending_requests.values():
+            if not future.done(): future.cancel()
+        self._pending_requests.clear()
+
+    async def _listen_loop(self):
+        async for message in self.connection:
+            if self.rate_limit > 0:
+                now = time.time()
+                if len(self._msg_times) == self.rate_limit and (now - self._msg_times[0]) < 1.0:
+                    logging.warning(f"Rate limit exceeded for {self.name}, closing connection.")
+                    await self.connection.close(1008, "Rate limit exceeded")
+                    return
+                self._msg_times.append(now)
+
+            try:
+                data = json.loads(message)
+                asyncio.create_task(self._process_packet(data))
+            except json.JSONDecodeError:
+                pass
+
+    async def _process_packet(self, packet: dict):
+        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 
+        if msg_type in self.handlers:
+            try:
+                response = await self.handlers[msg_type](payload)
+                if response is not None:
+                    await self.send(type=msg_type, payload=response, reply_to=msg_id)
+            except Exception as e:
+                logging.error(f"Error processing {msg_type}: {e}")
+
+    async def _handle_welcome(self, payload):
+        server_id = payload.get("id")
+        if server_id:
+            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()
+
+    async def _handle_handshake(self, payload):
+        t_remote = float(payload.get('t'))
+        return {"server_id": self.id, "l": time.time() - t_remote}
+
+    async def _handle_ping(self, _):
+        return "pong"
+
+    async def _handle_status_request(self, _):
+        return {
+            "name": self.name,
+            "id": self.id,
+            "status": "online",
+            "uptime": time.time() - self._start_time if hasattr(self, '_start_time') else 0,
+            "memory_usage": "unknown"
+        }

meshsocket-0.1.0/socket_server.py

@@ -0,0 +1,370 @@
+import asyncio
+import uuid
+import websockets
+from socketCore import MeshSocket, LogColors
+import logging
+import os
+from typing import Any, Callable, Dict, Optional
+
+_MAX_PENDING_PER_IP = 10
+_pending_conns: Dict[str, int] = {}
+
+
+class MeshServer:
+    def __init__(self,
+                 host: str = "0.0.0.0",
+                 port: int = 8765,
+                 rate_limit: int = 0,
+                 max_size: int = 1_048_576,
+                 auth_handler: Optional[Callable] = None,
+                 on_startup: Optional[Callable] = None,
+                 on_authenticated: Optional[Callable] = None):
+        self.host = host
+        self.port = port
+        self.rate_limit = rate_limit
+        self.max_size = max_size
+
+        # auth_handler(token, remote_ip) → bool
+        # Default: compare against MESH_AUTH_TOKEN env var.
+        self._auth_handler = auth_handler or self._default_auth
+        # on_startup() — called once before the server starts accepting connections.
+        self._on_startup = on_startup
+        # on_authenticated(client, remote_ip, token) — called after a client passes auth.
+        self._on_authenticated = on_authenticated
+
+        self.clients: Dict[str, MeshSocket] = {}
+        self.clients_by_name: Dict[str, MeshSocket] = {}
+
+    @staticmethod
+    def _default_auth(token: str, remote_ip: str) -> bool:
+        server_token = os.getenv("MESH_AUTH_TOKEN")
+        if not server_token:
+            return True
+        return token == server_token
+
+    def _parse_bool(self, value: Any, default: bool = False) -> bool:
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            return value.strip().lower() in {"1", "true", "yes", "on"}
+        return default
+
+    def _same_channel(self, source: MeshSocket, target: MeshSocket) -> bool:
+        return getattr(source, "channel", "default") == getattr(target, "channel", "default")
+
+    def _can_receive_broadcast(self, source: MeshSocket, target: MeshSocket) -> bool:
+        if getattr(source, "broadcast_scope", "channel") == "global":
+            return True
+        return self._same_channel(source, target)
+
+    def _client_summary(self, client: MeshSocket) -> Dict[str, str]:
+        return {
+            "id": client.id,
+            "name": client.name,
+            "channel": getattr(client, "channel", "default"),
+            "role": getattr(client, "role", "node"),
+        }
+
+    def _client_ip(self, websocket) -> str:
+        request_headers = getattr(websocket, "request_headers", None)
+        if request_headers is None and getattr(websocket, "request", None) is not None:
+            request_headers = websocket.request.headers
+
+        if request_headers:
+            x_real_ip = request_headers.get("X-Real-IP")
+            if x_real_ip:
+                return x_real_ip.strip()
+
+            x_forwarded_for = request_headers.get("X-Forwarded-For")
+            if x_forwarded_for:
+                first_hop = x_forwarded_for.split(",", 1)[0].strip()
+                if first_hop:
+                    return first_hop
+
+        if websocket.remote_address:
+            return websocket.remote_address[0]
+        return "unknown"
+
+    async def start(self):
+        if self._on_startup:
+            self._on_startup()
+        logging.info(f"{LogColors.HEADER}Starting Server on ws://{self.host}:{self.port}{LogColors.ENDC}")
+        async with websockets.serve(
+            self._handle_connection,
+            self.host,
+            self.port,
+            max_size=self.max_size,
+        ):
+            await asyncio.Future()
+
+    async def _handle_connection(self, websocket):
+        remote_ip = self._client_ip(websocket)
+        logging.info(f"New connection from {remote_ip}")
+
+        pending = _pending_conns.get(remote_ip, 0)
+        if pending >= _MAX_PENDING_PER_IP:
+            logging.warning(
+                f"{LogColors.FAIL}Rejected {remote_ip} — "
+                f"{pending} pending connections already{LogColors.ENDC}"
+            )
+            await websocket.close(4429, "Too many pending connections")
+            return
+
+        _pending_conns[remote_ip] = pending + 1
+        try:
+            client = MeshSocket(
+                connection=websocket,
+                name=f"Client-{id(websocket)}",
+                rate_limit=self.rate_limit,
+            )
+            client.channel = "default"
+            client.role = "unknown"
+            client.can_broadcast = False
+            client.can_route = False
+            client.can_cross_channel_route = False
+            client.can_monitor = False
+            client.broadcast_scope = "channel"
+
+            allowed_origins = {
+                origin.strip()
+                for origin in os.getenv(
+                    "MESH_ALLOWED_ORIGINS",
+                    "http://127.0.0.1,http://localhost"
+                ).split(",")
+                if origin.strip()
+            }
+            request_headers = getattr(websocket, "request_headers", None)
+            if request_headers is None and getattr(websocket, "request", None) is not None:
+                request_headers = websocket.request.headers
+            origin = request_headers.get("Origin") if request_headers else None
+            if origin and not any(origin == allowed or origin.startswith(allowed) for allowed in allowed_origins):
+                logging.warning(f"{LogColors.FAIL}Origin rejected: {origin}{LogColors.ENDC}")
+                await websocket.close(1008, "origin not allowed")
+                return
+
+            authenticated: asyncio.Future = asyncio.get_running_loop().create_future()
+
+            @client.on('identify')
+            async def handle_identify(payload):
+                payload = payload or {}
+                requested_name = payload.get('name', client.name)
+                client_token = payload.get('token', '')
+
+                if not self._auth_handler(client_token, remote_ip):
+                    logging.warning(
+                        f"{LogColors.FAIL}Auth failed (bad/missing token) for {remote_ip}{LogColors.ENDC}"
+                    )
+                    if not authenticated.done():
+                        authenticated.set_result(False)
+                    return
+
+                incumbent = self.clients_by_name.get(requested_name)
+                if incumbent is not None and incumbent is not client:
+                    # Last-writer-wins: a reconnecting peer reclaims its name. The
+                    # old socket is usually a half-open ghost the server hasn't
+                    # reaped yet; rejecting the newcomer instead would leave it
+                    # silently retrying forever. Drop the incumbent from the roster
+                    # now (so the newcomer can register cleanly below) and close it
+                    # out of band. The identity-checked cleanup in the connection
+                    # finally keeps the ghost's teardown from clobbering this entry.
+                    logging.warning(
+                        f"{LogColors.WARNING}Name '{requested_name}' reclaimed by {remote_ip} — "
+                        f"evicting stale client {incumbent.id}{LogColors.ENDC}"
+                    )
+                    self.clients.pop(incumbent.id, None)
+                    self.clients_by_name.pop(requested_name, None)
+                    asyncio.create_task(incumbent.stop())
+
+                new_id = str(uuid.uuid4())
+                while new_id in self.clients:
+                    new_id = str(uuid.uuid4())
+
+                client.id = new_id
+                client.name = requested_name
+                client.channel = payload.get('channel') or "default"
+                client.role = payload.get('role') or "node"
+                client.can_broadcast = self._parse_bool(payload.get('can_broadcast'), client.role in {"dashboard", "browser", "mobile", "node"})
+                client.can_route = self._parse_bool(payload.get('can_route'), client.role in {"browser", "mobile", "dashboard", "node"})
+                client.can_cross_channel_route = self._parse_bool(payload.get('can_cross_channel_route'), False)
+                client.can_monitor = self._parse_bool(payload.get('can_monitor'), client.role in {"dashboard", "browser"})
+                client.broadcast_scope = payload.get('broadcast_scope') or ("global" if client.can_monitor else "channel")
+
+                logging.info(
+                    f"{LogColors.GREEN}Identified: '{client.name}' → {client.id}{LogColors.ENDC}"
+                )
+
+                if self._on_authenticated:
+                    self._on_authenticated(client, remote_ip, client_token)
+
+                if not authenticated.done():
+                    authenticated.set_result(True)
+
+                await client.send("welcome", {"id": client.id, "name": client.name})
+                await self._broadcast_client_list()
+
+            # Register handlers BEFORE the listen loop starts so the first
+            # request after the identify ack can't race past registration and
+            # get dropped. Permission flags stay False until identify, so
+            # nothing here is reachable pre-auth.
+            @client.on("broadcast_request")
+            async def on_broadcast(payload):
+                if not client.can_broadcast:
+                    return {"error": "broadcast not allowed", "status": "failed"}
+                await self.broadcast("broadcast", payload, sender=client)
+                return {"status": "sent"}
+
+            @client.on("iCloud_data_Broadcast")
+            async def on_iCloud_broadcast(payload):
+                if not client.can_broadcast:
+                    return {"error": "broadcast not allowed", "status": "failed"}
+                await self.broadcast("iCloudListen", payload, sender=client)
+                return {"status": "sent"}
+
+            @client.on("place_visit_Broadcast")
+            async def on_place_visit_broadcast(payload):
+                if not client.can_broadcast:
+                    return {"error": "broadcast not allowed", "status": "failed"}
+                await self.broadcast("placeVisitListen", payload, sender=client)
+                return {"status": "sent"}
+
+            @client.on("request_prediction")
+            async def on_prediction_request(payload):
+                if not client.can_broadcast:
+                    return {"error": "broadcast not allowed", "status": "failed"}
+                await self.broadcast("request_prediction", payload, sender=client)
+                return {"status": "forwarded"}
+
+            @client.on("prediction_result")
+            async def on_prediction_result(payload):
+                if not client.can_broadcast:
+                    return {"error": "broadcast not allowed", "status": "failed"}
+                await self.broadcast("prediction_result", payload, sender=client)
+                return {"status": "forwarded"}
+
+            @client.on("service_log")
+            async def on_service_log(payload):
+                if not client.can_broadcast:
+                    return {"error": "log broadcast not allowed", "status": "failed"}
+                await self.broadcast("service_log", payload, sender=client)
+                return {"status": "broadcasted"}
+
+            @client.on("node_status")
+            async def on_node_status(payload):
+                await self.broadcast("node_status", payload, sender=client)
+                return {"status": "broadcasted"}
+
+            @client.on('route_msg')
+            async def on_route(payload):
+                target_id = payload.get('target_id')
+                msg_type = payload.get('type')
+                data = payload.get('payload')
+
+                target = self.clients.get(target_id)
+                if target:
+                    if not client.can_route:
+                        return {"error": "routing not allowed", "status": "failed"}
+                    if not client.can_cross_channel_route and not self._same_channel(client, target):
+                        return {"error": "cross-channel route denied", "status": "failed"}
+                    response = await target.request(msg_type, data, timeout=5.0)
+                    return response
+                return {"error": "Target not found", "status": "failed"}
+
+            @client.on("get_nodes")
+            async def on_get_nodes(payload):
+                client_list = [
+                    self._client_summary(c)
+                    for c in self.clients.values()
+                    if c.id != client.id and (client.can_monitor and (client.broadcast_scope == "global" or self._same_channel(client, c)))
+                ]
+                return {"clients": client_list}
+
+            @client.on('route_msg_noreply')
+            async def on_noreply_route(payload):
+                target_name = payload.get('target_name')
+                msg_type = payload.get('type')
+                data = payload.get('payload')
+
+                target = self.clients_by_name.get(target_name)
+                if target:
+                    if not client.can_route:
+                        return {"error": "routing not allowed", "status": "failed"}
+                    if not client.can_cross_channel_route and not self._same_channel(client, target):
+                        return {"error": "cross-channel route denied", "status": "failed"}
+                    await target.send(msg_type, data)
+                else:
+                    return {"error": "Target not found", "status": "failed"}
+
+            listen_task = asyncio.create_task(client.listen())
+
+            try:
+                is_auth = await asyncio.wait_for(authenticated, timeout=5.0)
+            except asyncio.TimeoutError:
+                logging.warning(
+                    f"{LogColors.FAIL}Auth timeout for {remote_ip} — closing silently{LogColors.ENDC}"
+                )
+                listen_task.cancel()
+                await client.stop()
+                return
+            except Exception as e:
+                logging.error(f"Auth error for {remote_ip}: {e}")
+                listen_task.cancel()
+                await client.stop()
+                return
+
+            if not is_auth:
+                listen_task.cancel()
+                await client.stop()
+                return
+
+            self.clients[client.id] = client
+            self.clients_by_name[client.name] = client
+            logging.info(
+                f"{LogColors.GREEN}'{client.name}' connected. "
+                f"Total clients: {len(self.clients)}{LogColors.ENDC}"
+            )
+
+
+            try:
+                await listen_task
+            finally:
+                self.clients.pop(client.id, None)
+                # Only release the name if it still points at *this* client — an
+                # evicted incumbent must not pop the entry of the peer that just
+                # reclaimed its name (see the eviction path in handle_identify).
+                if self.clients_by_name.get(client.name) is client:
+                    self.clients_by_name.pop(client.name, None)
+                logging.info(
+                    f"{LogColors.WARNING}'{client.name}' disconnected. "
+                    f"Remaining: {len(self.clients)}{LogColors.ENDC}"
+                )
+                await self._broadcast_client_list()
+        finally:
+            _pending_conns[remote_ip] = max(0, _pending_conns.get(remote_ip, 1) - 1)
+
+    async def _broadcast_client_list(self):
+        for client in self.clients.values():
+            if not getattr(client, "can_monitor", False):
+                continue
+            if getattr(client, "broadcast_scope", "channel") == "global":
+                visible_clients = [self._client_summary(peer) for peer in self.clients.values()]
+            else:
+                visible_clients = [self._client_summary(peer) for peer in self.clients.values() if self._same_channel(client, peer)]
+            await client.send('server_client_list', {'clients': visible_clients})
+
+    async def broadcast(self, type: str, payload: dict, sender: MeshSocket | None = None):
+        if not self.clients:
+            return
+        tasks = []
+        for peer in self.clients.values():
+            if sender and not self._can_receive_broadcast(sender, peer):
+                continue
+            tasks.append(peer.send(type, payload))
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+
+if __name__ == "__main__":
+    server = MeshServer()
+    try:
+        asyncio.run(server.start())
+    except KeyboardInterrupt:
+        print("Server stopped.")