messagex-client 0.1.0__py3-none-any.whl

messagex/frame.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import json
+import struct
+from typing import Any, List
+
+HEADER_SIZE = 4
+DEFAULT_MAX_FRAME_SIZE = 1024 * 1024
+
+
+def encode_frame(message: Any, max_frame_size: int = DEFAULT_MAX_FRAME_SIZE) -> bytes:
+    """Encode ``message`` as JSON with a 4-byte big-endian length prefix."""
+    try:
+        text = json.dumps(message, separators=(",", ":"), ensure_ascii=False, allow_nan=False)
+    except (TypeError, ValueError) as exc:
+        raise TypeError("MessageX protocol message must be JSON serializable") from exc
+
+    body = text.encode("utf-8")
+    if len(body) == 0 or len(body) > max_frame_size:
+        raise ValueError(f"MessageX frame size must be between 1 and {max_frame_size} bytes")
+    return struct.pack(">I", len(body)) + body
+
+
+class FrameDecoder:
+    """Incremental decoder that turns a byte stream into frame bodies."""
+
+    def __init__(self, max_frame_size: int = DEFAULT_MAX_FRAME_SIZE) -> None:
+        self._max_frame_size = max_frame_size
+        self._buffer = bytearray()
+
+    def push(self, chunk: bytes) -> List[bytes]:
+        if not chunk:
+            return []
+        self._buffer.extend(chunk)
+        frames: List[bytes] = []
+
+        while len(self._buffer) >= HEADER_SIZE:
+            (length,) = struct.unpack_from(">I", self._buffer, 0)
+            if length < 1 or length > self._max_frame_size:
+                self.reset()
+                raise ValueError(f"Invalid MessageX frame length: {length}")
+
+            frame_length = HEADER_SIZE + length
+            if len(self._buffer) < frame_length:
+                break
+
+            frames.append(bytes(self._buffer[HEADER_SIZE:frame_length]))
+            del self._buffer[:frame_length]
+
+        return frames
+
+    def reset(self) -> None:
+        self._buffer = bytearray()
+
+    @property
+    def buffered_bytes(self) -> int:
+        return len(self._buffer)

messagex/types.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Dict, Optional, TypedDict, Union
+
+try:  # Python 3.8+
+    from typing import Literal
+except ImportError:  # pragma: no cover
+    from typing_extensions import Literal  # type: ignore
+
+ExchangeType = Literal["direct", "fanout", "topic", "headers"]
+
+
+@dataclass
+class DeliveredMessage:
+    """A message delivered to a consumer. Settle it with :meth:`ack` or :meth:`nack`."""
+
+    consumer_tag: str
+    queue_name: str
+    message_id: str
+    delivery_tag: str
+    body: Any
+    headers: Dict[str, Any]
+    routing_key: str
+    delivery_count: int
+    created_at: str
+    _ack: Optional[Callable[[], Awaitable[None]]] = field(default=None, repr=False, compare=False)
+    _nack: Optional[Callable[[bool], Awaitable[None]]] = field(default=None, repr=False, compare=False)
+
+    async def ack(self) -> None:
+        """Acknowledge successful processing."""
+        assert self._ack is not None
+        await self._ack()
+
+    async def nack(self, requeue: bool = True) -> None:
+        """Reject the delivery, optionally requeueing it."""
+        assert self._nack is not None
+        await self._nack(requeue)
+
+
+MessageHandler = Callable[[DeliveredMessage], Union[None, Awaitable[None]]]
+
+
+@dataclass
+class ConsumerSubscription:
+    consumer_tag: str
+    queue_name: str
+    _cancel: Callable[[], Awaitable[None]] = field(repr=False, compare=False)
+
+    async def cancel(self) -> None:
+        await self._cancel()
+
+
+@dataclass
+class PublishResult:
+    exchange_name: str
+    routed_queues: int
+
+
+class QueueInfo(TypedDict, total=False):
+    id: str
+    name: str
+    durable: bool
+    exclusive: bool
+    autoDelete: bool
+    maxDeliveryCount: Optional[int]
+    deadLetterQueue: Optional[str]
+
+
+class ExchangeInfo(TypedDict, total=False):
+    id: str
+    name: str
+    type: str
+    durable: bool
+
+
+class BindingInfo(TypedDict, total=False):
+    id: str
+    exchangeName: str
+    queueName: str
+    routingKey: str
+    arguments: Dict[str, Any]