socketflow 0.1.0__py3-none-any.whl

socketflow/global_side/compression.py

@@ -0,0 +1,155 @@
+import pickle
+from typing import Any, Dict, Tuple
+
+try:
+    import lzma
+
+    HAS_LZMA = True
+except ImportError:
+    HAS_LZMA = False
+
+try:
+    import bz2
+
+    HAS_BZ2 = True
+except ImportError:
+    HAS_BZ2 = False
+
+try:
+    import zlib
+
+    HAS_ZLIB = True
+except ImportError:
+    HAS_ZLIB = False
+
+try:
+    import gzip
+
+    HAS_GZIP = True
+except ImportError:
+    HAS_GZIP = False
+
+try:
+    import zstandard as zstd
+
+    HAS_ZSTD = True
+except ImportError:
+    HAS_ZSTD = False
+
+try:
+    import brotli
+
+    HAS_BROTLI = True
+except ImportError:
+    HAS_BROTLI = False
+
+
+class MultiCompressor:
+    """
+    NOTE:
+    - pickle methods are unsafe for untrusted data
+    - bytes methods are safe
+    """
+
+    _REGISTRY: Dict[str, Tuple[bool, callable, callable, int]] = {
+        "zstd": (
+            HAS_ZSTD,
+            lambda d, level: zstd.compress(d, level=level),
+            zstd.decompress if HAS_ZSTD else None,
+            22,
+        ),
+        "brotli": (
+            HAS_BROTLI,
+            lambda d, level: brotli.compress(d, quality=level),
+            brotli.decompress if HAS_BROTLI else None,
+            11,
+        ),
+        "lzma": (
+            HAS_LZMA,
+            lambda d, level: lzma.compress(d, preset=level),
+            lzma.decompress if HAS_LZMA else None,
+            9,
+        ),
+        "bz2": (
+            HAS_BZ2,
+            lambda d, level: bz2.compress(d, compresslevel=level),
+            bz2.decompress if HAS_BZ2 else None,
+            9,
+        ),
+        "zlib": (
+            HAS_ZLIB,
+            lambda d, level: zlib.compress(d, level=level),
+            zlib.decompress if HAS_ZLIB else None,
+            9,
+        ),
+        "gzip": (
+            HAS_GZIP,
+            lambda d, level: gzip.compress(d, compresslevel=level),
+            gzip.decompress if HAS_GZIP else None,
+            9,
+        ),
+    }
+
+    HEADER_SEP = b":"
+
+    @classmethod
+    def available_methods(cls):
+        return [m for m, (ok, *_) in cls._REGISTRY.items() if ok]
+
+    # ---------- OBJECT (pickle) ----------
+
+    @classmethod
+    def compress(
+        cls,
+        obj: Any,
+        method: str = "zstd",
+        level: int | None = None,
+        pickle_protocol: int = pickle.HIGHEST_PROTOCOL,
+    ) -> bytes:
+        data = pickle.dumps(obj, protocol=pickle_protocol)
+        return cls.compress_bytes(data, method, level)
+
+    @classmethod
+    def decompress(cls, data: bytes) -> Any:
+        raw = cls.decompress_bytes(data)
+        return pickle.loads(raw)
+
+    # ---------- BYTES (in-memory / file) ----------
+
+    @classmethod
+    def compress_bytes(
+        cls,
+        data: bytes,
+        method: str = "zstd",
+        level: int | None = None,
+    ) -> bytes:
+        method = method.lower()
+        if method not in cls._REGISTRY:
+            raise ValueError(f"Unsupported method '{method}'")
+
+        available, compress_fn, _, default_level = cls._REGISTRY[method]
+        if not available:
+            raise ValueError(f"Method '{method}' not available")
+
+        if level is None:
+            level = default_level
+
+        compressed = compress_fn(data, level)
+        return method.encode() + cls.HEADER_SEP + compressed
+
+    @classmethod
+    def decompress_bytes(cls, data: bytes) -> bytes:
+        try:
+            method_raw, payload = data.split(cls.HEADER_SEP, 1)
+        except ValueError:
+            raise ValueError("Invalid data header")
+
+        method = method_raw.decode()
+        if method not in cls._REGISTRY:
+            raise ValueError(f"Unknown method '{method}'")
+
+        available, _, decompress_fn, _ = cls._REGISTRY[method]
+        if not available or decompress_fn is None:
+            raise ValueError(f"Method '{method}' not available")
+
+        return decompress_fn(payload)

socketflow/global_side/dispatcher.py

@@ -0,0 +1,104 @@
+from typing import Dict, List, Callable, Any
+import threading
+
+
+class EventDispatcher:
+    def __init__(self):
+        self._event_handlers: Dict[str, List[Callable]] = {}
+        self._path_handlers: Dict[str, List[Callable]] = {}
+        self._path_middleware: Dict[str, List[Callable]] = {}
+        self._server = None
+        self._client = None
+
+    def event(self, event_type: str):
+        """Decorator for event handlers"""
+
+        def decorator(func):
+            self.register_event(event_type, func)
+            return func
+
+        return decorator
+
+    def path(self, path: str, middleware=None):
+        """Decorator for path handlers"""
+
+        def decorator(func):
+            self.register_path(path, func, middleware)
+            return func
+
+        return decorator
+
+    def register_event(self, event_type: str, handler: Callable):
+        """Register an event handler"""
+        if event_type not in self._event_handlers:
+            self._event_handlers[event_type] = []
+        self._event_handlers[event_type].append(handler)
+
+    def register_path(self, path: str, handler: Callable, middleware=None):
+        """Register a path handler"""
+        if path not in self._path_handlers:
+            self._path_handlers[path] = []
+        self._path_handlers[path].append(handler)
+
+        # Register middleware separately if provided
+        if middleware:
+            if isinstance(middleware, list):
+                for m in middleware:
+                    self.register_path_middleware(path, m)
+            else:
+                self.register_path_middleware(path, middleware)
+
+    def register_path_middleware(self, path: str, middleware: Callable):
+        """Register path middleware"""
+        if path not in self._path_middleware:
+            self._path_middleware[path] = []
+        self._path_middleware[path].append(middleware)
+
+    def emit(self, event_type: str, data: Any):
+        """Emit event"""
+
+        def _run_handlers():
+            if event_type in self._event_handlers:
+                for handler in self._event_handlers[event_type]:
+                    try:
+                        handler(data)
+                    except Exception:
+                        pass
+
+        threading.Thread(target=_run_handlers, daemon=True).start()
+
+    def emit_path(self, path: str, data: Any):
+        """Emit path event"""
+
+        def _run_path_handlers():
+            # Run middleware first
+            current_data = data
+            if path in self._path_middleware:
+                for middleware_func in self._path_middleware[path]:
+                    try:
+                        result = middleware_func(current_data)
+                        if result is False:  # Middleware rejected the request
+                            return
+                        elif result is not None:  # Middleware modified the data
+                            current_data = result
+                    except Exception:
+                        # Middleware failed, don't proceed to handlers
+                        return
+
+            # Run path handlers
+            if path in self._path_handlers:
+                for handler in self._path_handlers[path]:
+                    try:
+                        handler(current_data)
+                    except Exception:
+                        pass
+
+        threading.Thread(target=_run_path_handlers, daemon=True).start()
+
+    def register_blueprint(self, blueprint):
+        """Register a blueprint"""
+        blueprint.register_with_dispatcher(self)
+
+    def set_event_loop(self, loop):
+        """Compatibility method - not needed for sync version"""
+        pass

socketflow/global_side/event.py

@@ -0,0 +1,69 @@
+from dataclasses import dataclass
+from typing import Any, Optional, Tuple
+
+
+@dataclass
+class ConnectData:
+    server_addr: Tuple[str, int]
+    transport: Any
+
+
+@dataclass
+class DisconnectData:
+    server_addr: Tuple[str, int]
+    transport: Any
+
+
+@dataclass
+class ClientConnectData:
+    client_addr: Tuple[str, int]
+    transport: Any
+
+
+@dataclass
+class ClientDisconnectData:
+    client_addr: Tuple[str, int]
+    transport: Any
+
+
+@dataclass
+class MessageReceivedData:
+    data: Any
+    client_addr: Optional[Tuple[str, int]] = None
+    server_addr: Optional[Tuple[str, int]] = None
+    data_id: Optional[str] = None
+
+
+@dataclass
+class ErrorData:
+    error: Exception
+    context: str
+
+
+@dataclass
+class ServerStartData:
+    host: str
+    port: int
+
+
+@dataclass
+class ServerStopData:
+    host: str
+    port: int
+
+
+class EventType:
+    class Client:
+        CONNECT = "client.connect"
+        DISCONNECT = "client.disconnect"
+        MESSAGE = "client.message"
+
+    class Server:
+        CLIENT_CONNECT = "server.client_connect"
+        CLIENT_DISCONNECT = "server.client_disconnect"
+        MESSAGE = "server.message"
+        START = "server.start"
+        STOP = "server.stop"
+
+    class Global:
+        ERROR = "global.error"

socketflow/global_side/exceptions.py

@@ -0,0 +1,100 @@
+"""
+Exception types for socketflow library
+"""
+
+
+class SocketFlowException(Exception):
+    """Base exception for all socketflow exceptions"""
+
+    pass
+
+
+class NotConnected(SocketFlowException):
+    """Raised when trying to perform operations on a disconnected client/server"""
+
+    pass
+
+
+class NoResponse(SocketFlowException):
+    """Raised when no response is received within timeout"""
+
+    pass
+
+
+class ConnectionTimeout(SocketFlowException):
+    """Raised when connection times out"""
+
+    pass
+
+
+class KeepaliveTimeout(SocketFlowException):
+    """Raised when keepalive timeout occurs"""
+
+    pass
+
+
+class InvalidData(SocketFlowException):
+    """Raised when invalid data is received or sent"""
+
+    pass
+
+
+class ProtocolError(SocketFlowException):
+    """Raised when protocol error occurs"""
+
+    pass
+
+
+class ServerError(SocketFlowException):
+    """Raised when server-side error occurs"""
+
+    pass
+
+
+class ClientError(SocketFlowException):
+    """Raised when client-side error occurs"""
+
+    pass
+
+
+class BlueprintError(SocketFlowException):
+    """Raised when blueprint-related error occurs"""
+
+    pass
+
+
+class CompressionError(SocketFlowException):
+    """Raised when compression/decompression fails"""
+
+    pass
+
+
+class MessageHandlerError(SocketFlowException):
+    """Raised when message handling fails"""
+
+    pass
+
+
+class DispatcherError(SocketFlowException):
+    """Raised when dispatcher error occurs"""
+
+    pass
+
+
+# Namespace for grouped exception access
+class ExceptionType:
+    """Namespace for all exception types"""
+
+    SocketFlow = SocketFlowException
+    NotConnected = NotConnected
+    NoResponse = NoResponse
+    ConnectionTimeout = ConnectionTimeout
+    KeepaliveTimeout = KeepaliveTimeout
+    InvalidData = InvalidData
+    ProtocolError = ProtocolError
+    ServerError = ServerError
+    ClientError = ClientError
+    BlueprintError = BlueprintError
+    CompressionError = CompressionError
+    MessageHandlerError = MessageHandlerError
+    DispatcherError = DispatcherError

socketflow/global_side/message_handler.py

@@ -0,0 +1,38 @@
+from .message_manager import message_manager
+from .compression import MultiCompressor
+
+
+class MessageHandler:
+    @staticmethod
+    def unpack_data(encoded_message):
+        try:
+            data = message_manager.decode(encoded_message)
+            headers = data[0]
+            body = data[1] if len(data) > 1 else None
+            if headers.get("compressed") and headers.get("type") == "__user__":
+                body = MultiCompressor.decompress(body)
+            return headers, body
+        except Exception as e:
+            print(e)
+            return None, None
+
+    @staticmethod
+    def create_ping():
+        """Create a ping message"""
+        ping_headers = {
+            "type": "__ping__",
+        }
+        length_bytes, encoded_ping = message_manager.encode_with_length(ping_headers)
+        return length_bytes + encoded_ping
+
+    @staticmethod
+    def create_pong():
+        """Create a pong message in response to a ping"""
+        pong_headers = {
+            "type": "__pong__",
+        }
+        length_bytes, encoded_pong = message_manager.encode_with_length(pong_headers)
+        return length_bytes + encoded_pong
+
+
+message_handler = MessageHandler()

socketflow/global_side/message_manager.py

@@ -0,0 +1,98 @@
+import struct
+from typing import Any
+import json
+
+
+class MessageManager:
+    def __init__(self):
+        pass
+
+    def encode(self, *messages: Any) -> bytes:
+        if not messages:
+            raise ValueError("At least one message must be provided")
+
+        encoded_parts = []
+
+        for data in messages:
+            if isinstance(data, bytes):
+                encoded_parts.append(struct.pack("!B", 0))
+                encoded_parts.append(struct.pack("!I", len(data)))
+                encoded_parts.append(data)
+            elif isinstance(data, str):
+                msg_bytes = data.encode("utf-8")
+                encoded_parts.append(struct.pack("!B", 1))
+                encoded_parts.append(struct.pack("!I", len(msg_bytes)))
+                encoded_parts.append(msg_bytes)
+            else:
+                try:
+                    json_str = json.dumps(data, ensure_ascii=False)
+                    json_bytes = json_str.encode("utf-8")
+                    encoded_parts.append(struct.pack("!B", 2))
+                    encoded_parts.append(struct.pack("!I", len(json_bytes)))
+                    encoded_parts.append(json_bytes)
+                except (TypeError, ValueError) as e:
+                    raise TypeError(f"Message is not JSON-serializable: {e}")
+
+        return b"".join(encoded_parts)
+
+    def encode_with_length(self, *messages: Any) -> tuple[bytes, bytes]:
+        encoded_payload = self.encode(*messages)
+        length_bytes = struct.pack(">I", len(encoded_payload))
+        return length_bytes, encoded_payload
+
+    def decode(self, payload: bytes, keys_required: int = None):
+        if not payload:
+            raise ValueError("Payload cannot be empty")
+
+        messages = []
+        offset = 0
+        payload_len = len(payload)
+
+        while offset < payload_len:
+            if offset + 5 > payload_len:
+                raise ValueError("Malformed payload: incomplete header")
+
+            msg_type = struct.unpack("!B", payload[offset : offset + 1])[0]
+            offset += 1
+            msg_len = struct.unpack("!I", payload[offset : offset + 4])[0]
+            offset += 4
+
+            if offset + msg_len > payload_len:
+                raise ValueError("Malformed payload: incomplete message data")
+
+            msg_data = payload[offset : offset + msg_len]
+            offset += msg_len
+
+            if msg_type == 0:
+                messages.append(msg_data)
+            elif msg_type == 1:
+                try:
+                    messages.append(msg_data.decode("utf-8"))
+                except UnicodeDecodeError as e:
+                    raise ValueError(f"Failed to decode string data: {e}")
+            elif msg_type == 2:
+                try:
+                    json_str = msg_data.decode("utf-8")
+                    messages.append(json.loads(json_str))
+                except (UnicodeDecodeError, json.JSONDecodeError) as e:
+                    raise ValueError(f"Failed to decode JSON data: {e}")
+            else:
+                raise ValueError(f"Unknown message type: {msg_type}")
+
+        if keys_required is None:
+            return messages
+        elif keys_required == 1:
+            if len(messages) != 1:
+                raise ValueError(f"Expected exactly 1 message, but got {len(messages)}")
+            return messages[0]
+        elif keys_required > 1:
+            if len(messages) != keys_required:
+                raise ValueError(
+                    f"Expected exactly {keys_required} messages, but got {len(messages)}"
+                )
+            return tuple(messages)
+        else:
+            raise ValueError("keys_required must be None, 1, or greater")
+
+
+message_manager = MessageManager()

socketflow/server_side/__init__.py

@@ -0,0 +1,3 @@
+from .server import TcpServer
+
+__all__ = ["TcpServer"]