deegzlibs-command-bus 2.0.0__py3-none-any.whl

command_bus/__init__.py

@@ -0,0 +1,41 @@
+"""
+DeegzLibs CommandBus: a small command bus with pluggable queue adapters (e.g. SQS).
+"""
+
+from .bus import CommandBus
+from .interfaces import (
+    CommandBusAdapter,
+    CommandBusInterface,
+    CommandBusRouterInterface,
+    CommandMessage,
+    CommandHandler,
+    ResponseStore,
+    TransmissibleBaseModel,
+)
+from .parsers import (
+    Base64MessageParser,
+    JsonMessageParser,
+    MessageParser,
+    MessageParserBase,
+    ReprMessageParser,
+)
+from .registry import CommandBusRouter, CommandBusRouterEntry, get_qual_name
+
+__all__ = [
+    "Base64MessageParser",
+    "CommandBus",
+    "CommandBusAdapter",
+    "ResponseStore",
+    "CommandBusInterface",
+    "CommandBusRouter",
+    "CommandBusRouterEntry",
+    "CommandBusRouterInterface",
+    "CommandMessage",
+    "CommandHandler",
+    "JsonMessageParser",
+    "MessageParser",
+    "MessageParserBase",
+    "ReprMessageParser",
+    "TransmissibleBaseModel",
+    "get_qual_name",
+]

command_bus/adapters/__init__.py

@@ -0,0 +1,30 @@
+"""Queue and response adapters for the command bus."""
+
+from .queue import FileQueueAdapter, InMemoryCommandBusAdapter, SqsCommandBusAdapter
+
+__all__ = ["InMemoryCommandBusAdapter", "SqsCommandBusAdapter", "FileQueueAdapter"]
+
+try:
+    from .queue import RabbitMqCommandBusAdapter
+
+    __all__ += ["RabbitMqCommandBusAdapter"]
+except ImportError:
+    pass
+
+try:
+    from .queue import RedisCommandBusAdapter
+
+    __all__ += ["RedisCommandBusAdapter"]
+except ImportError:
+    pass
+
+from .response import FileResponseStore, InMemoryResponseStore
+
+__all__ += ["InMemoryResponseStore", "FileResponseStore"]
+
+try:
+    from .response import RedisResponseStore
+
+    __all__ += ["RedisResponseStore"]
+except ImportError:
+    pass

command_bus/adapters/queue/__init__.py

@@ -0,0 +1,21 @@
+"""Queue adapters for the command bus (SQS, RabbitMQ, Redis, in-memory, file, etc.)."""
+
+from .file import FileQueueAdapter
+from .in_memory import InMemoryCommandBusAdapter
+from .sqs import SqsCommandBusAdapter
+
+__all__ = ["InMemoryCommandBusAdapter", "SqsCommandBusAdapter", "FileQueueAdapter"]
+
+try:
+    from .rabbitmq import RabbitMqCommandBusAdapter
+
+    __all__ += ["RabbitMqCommandBusAdapter"]
+except ImportError:
+    pass
+
+try:
+    from .redis import RedisCommandBusAdapter
+
+    __all__ += ["RedisCommandBusAdapter"]
+except ImportError:
+    pass

command_bus/adapters/queue/file.py

@@ -0,0 +1,193 @@
+"""File-based queue adapter for persistent cross-process command queuing."""
+
+import fcntl
+import json
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List
+
+from ...interfaces import CommandBusAdapter, CommandMessage
+
+
+class FileQueueAdapter(CommandBusAdapter):
+    """File-based queue adapter that persists to disk for cross-process access."""
+
+    def __init__(
+        self, 
+        queue_name: str = "events", 
+        storage_file: Path = None,
+        default_visibility_timeout: int = 60
+    ) -> None:
+        """
+        Initialize file-based queue adapter.
+        
+        Args:
+            queue_name: Name of the queue
+            storage_file: Path to JSON file for storage. Defaults to ~/.qubot/queue.json
+            default_visibility_timeout: Default visibility timeout in seconds (how long a message
+                is hidden after being retrieved). Defaults to 60 seconds.
+        """
+        self.queue_name = queue_name
+        self.default_visibility_timeout = default_visibility_timeout
+        
+        if storage_file is None:
+            storage_dir = Path.home() / ".qubot"
+            storage_dir.mkdir(exist_ok=True)
+            storage_file = storage_dir / "queue.json"
+        
+        self.storage_file = Path(storage_file)
+        self._lock_file = self.storage_file.with_suffix('.lock')
+        self._lock = None
+
+    def _acquire_lock(self):
+        """Simple file-based lock."""
+        self._lock = open(self._lock_file, 'w', encoding='utf-8')
+        fcntl.flock(self._lock.fileno(), fcntl.LOCK_EX)
+
+    def _release_lock(self):
+        """Release file-based lock."""
+        if self._lock is not None:
+            try:
+                fcntl.flock(self._lock.fileno(), fcntl.LOCK_UN)
+            except (OSError, ValueError):
+                pass
+            finally:
+                self._lock.close()
+                self._lock = None
+
+    def _load_queue(self) -> List[Dict[str, Any]]:
+        """Load queue from disk."""
+        if not self.storage_file.exists():
+            return []
+        try:
+            with open(self.storage_file, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        except (json.JSONDecodeError, FileNotFoundError):
+            return []
+
+    def _save_queue(self, queue: List[Dict[str, Any]]) -> None:
+        """Save queue to disk."""
+        try:
+            # Create parent directory if it doesn't exist
+            self.storage_file.parent.mkdir(parents=True, exist_ok=True)
+            with open(self.storage_file, 'w', encoding='utf-8') as f:
+                json.dump(queue, f, indent=2)
+        except Exception as e:
+            raise RuntimeError(f"Failed to save queue: {e}") from e
+
+    def enqueue(self, message_instance: CommandMessage, delay_seconds: int = 0) -> None:
+        """Add a message to the queue."""
+        try:
+            self._acquire_lock()
+            queue = self._load_queue()
+
+            # Serialize the message with full module path
+            # Format: module.ClassName(arg1=val1, arg2=val2, ...)
+            class_name = message_instance.__class__.__name__
+            module_name = message_instance.__class__.__module__
+            full_class_path = f"{module_name}.{class_name}"
+
+            # Get the arguments from the message instance
+            if hasattr(message_instance, 'model_dump'):
+                args_dict = message_instance.model_dump()
+            else:
+                args_dict = message_instance.__dict__
+            
+            args_str = ", ".join(f"{k}={repr(v)}" for k, v in args_dict.items())
+            message_str = f"{full_class_path}({args_str})"
+
+            queue.append({
+                "id": str(uuid.uuid4()),
+                "message": message_str,
+                "delay_until": time.time() + delay_seconds,
+                "queue_name": self.queue_name,
+                "hidden_until": 0  # Initially visible
+            })
+
+            self._save_queue(queue)
+        finally:
+            self._release_lock()
+
+    def dequeue(self, message_instance: Any) -> None:
+        """Remove a message from the queue."""
+        try:
+            self._acquire_lock()
+            queue = self._load_queue()
+
+            # Find and remove the message by ID (more reliable than message string)
+            msg_id = None
+            if hasattr(message_instance, '_data') and isinstance(message_instance._data, dict):
+                msg_id = message_instance._data.get("id")  # noqa: SLF001
+            
+            if msg_id:
+                queue[:] = [msg for msg in queue if msg.get("id") != msg_id]
+            else:
+                # Fallback to message string matching
+                message_str = message_instance.body if hasattr(message_instance, 'body') else str(message_instance)
+                queue[:] = [msg for msg in queue if msg.get("message") != message_str]
+
+            self._save_queue(queue)
+        finally:
+            self._release_lock()
+
+    def get_messages(
+        self,
+        max_messages: int = 1,
+        wait_seconds: int = 0,  # noqa: ARG002
+        visibility_timeout: int = None,
+        **kwargs: Any
+    ) -> List[Any]:
+        """
+        Get messages from the queue.
+        
+        Args:
+            max_messages: Maximum number of messages to retrieve
+            wait_seconds: Not used (file-based queue doesn't support blocking)
+            visibility_timeout: How long (in seconds) to hide the message after retrieval.
+                If None, uses the adapter's default_visibility_timeout.
+        """
+        try:
+            self._acquire_lock()
+            queue = self._load_queue()
+            current_time = time.time()
+            
+            # Use provided visibility timeout or default
+            vis_timeout = visibility_timeout if visibility_timeout is not None else self.default_visibility_timeout
+
+            # Filter messages for this queue that are:
+            # 1. For this queue name
+            # 2. Delay has passed (delay_until <= current_time)
+            # 3. Not currently hidden (hidden_until <= current_time)
+            visible_messages = [
+                msg for msg in queue
+                if msg.get("queue_name") == self.queue_name
+                and msg.get("delay_until", 0) <= current_time
+                and msg.get("hidden_until", 0) <= current_time
+            ]
+
+            # Limit to max_messages
+            messages_to_return = visible_messages[:max_messages]
+            
+            # Update hidden_until for returned messages (only if visibility_timeout > 0)
+            if vis_timeout > 0:
+                for msg in messages_to_return:
+                    msg["hidden_until"] = current_time + vis_timeout
+                
+                # Save the updated queue with new hidden_until values
+                if messages_to_return:
+                    self._save_queue(queue)
+
+            # Return as message objects (the bus will parse them)
+            class QueueMessage:
+                def __init__(self, msg_data: Dict[str, Any]):
+                    self.body = msg_data["message"]
+                    self._data = msg_data
+
+                def __repr__(self):
+                    return self.body
+
+            return [QueueMessage(msg) for msg in messages_to_return]
+        finally:
+            self._release_lock()
+

command_bus/adapters/queue/in_memory.py

@@ -0,0 +1,59 @@
+"""In-memory command bus adapter for tests or in-process use."""
+
+from collections import deque
+from typing import Any, List
+
+from ...interfaces import CommandBusAdapter, CommandMessage
+
+
+class _InMemoryMessage:
+    """Message wrapper with .body and .delete() for bus compatibility."""
+
+    __slots__ = ("body",)
+
+    def __init__(self, body: str) -> None:
+        self.body = body
+
+    def delete(self) -> None:
+        """No-op: message already removed from queue when get_messages() popped it."""
+        pass
+
+
+class InMemoryCommandBusAdapter(CommandBusAdapter):
+    """
+    In-memory FIFO queue adapter. Useful for tests or single-process command dispatch.
+    delay_seconds is ignored (no native delay); messages are available immediately.
+    """
+
+    def __init__(self, queue_name: str = "default") -> None:
+        self.queue_name = queue_name
+        self._queue: deque[str] = deque()
+
+    def enqueue(
+        self,
+        message_instance: CommandMessage,
+        delay_seconds: int = 0,
+    ) -> None:
+        """Append message to the queue. delay_seconds is ignored."""
+        self._queue.append(str(message_instance))
+
+    def dequeue(self, message_instance: Any) -> None:
+        """No-op: message was already removed when get_messages() popped it."""
+        if hasattr(message_instance, "delete"):
+            message_instance.delete()
+
+    def get_messages(
+        self,
+        max_messages: int = 1,
+        wait_seconds: int = 0,
+        **kwargs: Any,
+    ) -> List[_InMemoryMessage]:
+        """Pop up to max_messages from the queue. wait_seconds is ignored (no blocking)."""
+        out: List[_InMemoryMessage] = []
+        for _ in range(max_messages):
+            try:
+                body = self._queue.popleft()
+            except IndexError:
+                break
+            out.append(_InMemoryMessage(body=body))
+        return out

command_bus/adapters/queue/rabbitmq.py

@@ -0,0 +1,119 @@
+"""RabbitMQ-backed command bus adapter."""
+
+from typing import Any, List, Optional
+
+import pika
+from pika.adapters.blocking_connection import BlockingChannel
+
+from ...interfaces import CommandBusAdapter, CommandMessage
+
+
+class _RabbitMQMessage:
+    """Wrapper so RabbitMQ messages have .body and .delete() like SQS messages."""
+
+    __slots__ = ("body", "_channel", "_delivery_tag")
+
+    def __init__(self, body: str, channel: BlockingChannel, delivery_tag: int) -> None:
+        self.body = body
+        self._channel = channel
+        self._delivery_tag = delivery_tag
+
+    def delete(self) -> None:
+        self._channel.basic_ack(self._delivery_tag)
+
+
+class RabbitMqCommandBusAdapter(CommandBusAdapter):
+    """CommandBus adapter using RabbitMQ for queue operations (via pika)."""
+
+    def __init__(
+        self,
+        queue_name: str,
+        connection_url: Optional[str] = None,
+        connection_params: Optional[pika.ConnectionParameters] = None,
+    ) -> None:
+        if not connection_url and not connection_params:
+            raise ValueError("Provide either connection_url or connection_params")
+        self.queue_name = queue_name
+        self._connection_url = connection_url
+        self._connection_params = connection_params
+        self._connection: Optional[pika.BlockingConnection] = None
+        self._channel: Optional[BlockingChannel] = None
+
+    def _ensure_connection(self) -> BlockingChannel:
+        if self._channel is None or self._channel.is_closed:
+            if self._connection_url:
+                self._connection = pika.BlockingConnection(
+                    pika.URLParameters(self._connection_url)
+                )
+            else:
+                self._connection = pika.BlockingConnection(self._connection_params)
+            self._channel = self._connection.channel()
+            self._channel.queue_declare(queue=self.queue_name, durable=True)
+        return self._channel
+
+    def _connection_for_publish(self) -> tuple:
+        """Short-lived connection for publishing (no shared state)."""
+        if self._connection_url:
+            conn = pika.BlockingConnection(pika.URLParameters(self._connection_url))
+        else:
+            conn = pika.BlockingConnection(self._connection_params)
+        ch = conn.channel()
+        ch.queue_declare(queue=self.queue_name, durable=True)
+        return conn, ch
+
+    def enqueue(
+        self,
+        message_instance: CommandMessage,
+        delay_seconds: int = 0,
+    ) -> None:
+        """Add a message to the queue. (delay_seconds is ignored; use a delayed-exchange plugin for delays.)"""
+        conn, ch = self._connection_for_publish()
+        try:
+            ch.basic_publish(
+                exchange="",
+                routing_key=self.queue_name,
+                body=str(message_instance),
+                properties=pika.BasicProperties(delivery_mode=2),  # persistent
+            )
+        finally:
+            conn.close()
+
+    def dequeue(self, message_instance: Any) -> None:
+        """Ack the message (remove from queue after successful processing)."""
+        if hasattr(message_instance, "delete"):
+            message_instance.delete()
+        else:
+            raise TypeError(
+                "message_instance must be a _RabbitMQMessage with .delete()"
+            )
+
+    def get_messages(
+        self,
+        max_messages: int = 1,
+        **kwargs: Any,
+    ) -> List[_RabbitMQMessage]:
+        """Fetch messages from the queue. Uses a shared connection/channel for acks."""
+        channel = self._ensure_connection()
+        out: List[_RabbitMQMessage] = []
+        for _ in range(max_messages):
+            method_frame, _, body = channel.basic_get(queue=self.queue_name)
+            if method_frame is None:
+                break
+            body_str = body.decode("utf-8") if isinstance(body, bytes) else body
+            out.append(
+                _RabbitMQMessage(
+                    body=body_str,
+                    channel=channel,
+                    delivery_tag=method_frame.delivery_tag,
+                )
+            )
+        return out
+
+    def close(self) -> None:
+        """Close the consumer connection (optional; call when done with get_messages)."""
+        if self._channel and not self._channel.is_closed:
+            self._channel.close()
+        if self._connection and self._connection.is_open:
+            self._connection.close()
+        self._channel = None
+        self._connection = None

command_bus/adapters/queue/redis.py

@@ -0,0 +1,67 @@
+"""Redis-backed command bus adapter using Redis Lists (LPUSH/BRPOP)."""
+
+from typing import Any, List
+
+from ...interfaces import CommandBusAdapter, CommandMessage
+
+
+class _RedisMessage:
+    """Wrapper so Redis messages have .body and .delete() like SQS/RabbitMQ. Message already popped, so delete is no-op."""
+
+    __slots__ = ("body",)
+
+    def __init__(self, body: str) -> None:
+        self.body = body
+
+    def delete(self) -> None:
+        """No-op: message was already removed from the list when we BRPOP'd."""
+        pass
+
+
+class RedisCommandBusAdapter(CommandBusAdapter):
+    """
+    CommandBus adapter using a Redis List for queue operations (LPUSH to enqueue, BRPOP to consume).
+    FIFO: producers LPUSH, workers BRPOP. delay_seconds is not supported (use a delayed-queue pattern separately if needed).
+    """
+
+    def __init__(self, redis_client: Any, queue_name: str) -> None:
+        self._redis = redis_client
+        self.queue_name = queue_name
+
+    def enqueue(
+        self,
+        message_instance: CommandMessage,
+        delay_seconds: int = 0,
+    ) -> None:
+        """Add a message to the queue. delay_seconds is ignored (Redis List has no native delay)."""
+        self._redis.lpush(self.queue_name, str(message_instance))
+
+    def dequeue(self, message_instance: Any) -> None:
+        """No-op: message was already removed when get_messages() used BRPOP."""
+        if hasattr(message_instance, "delete"):
+            message_instance.delete()
+
+    def get_messages(
+        self,
+        max_messages: int = 1,
+        wait_seconds: int = 0,
+        **kwargs: Any,
+    ) -> List[_RedisMessage]:
+        """Fetch messages from the queue. Uses BRPOP (blocking) when wait_seconds > 0, else RPOP (non-blocking)."""
+        out: List[_RedisMessage] = []
+        timeout = max(0, wait_seconds)
+        for i in range(max_messages):
+            if timeout > 0 and i == 0:
+                result = self._redis.brpop(self.queue_name, timeout=timeout)
+            else:
+                result = self._redis.rpop(self.queue_name)
+            if result is None:
+                break
+            # brpop returns (key, value); rpop returns value only
+            if isinstance(result, (list, tuple)):
+                _, raw = result
+            else:
+                raw = result
+            body = raw.decode("utf-8") if isinstance(raw, bytes) else raw
+            out.append(_RedisMessage(body=body))
+        return out

command_bus/adapters/queue/sqs.py

@@ -0,0 +1,45 @@
+"""SQS-backed command bus adapter."""
+
+from typing import Any
+
+from ...interfaces import CommandBusAdapter, CommandMessage
+
+
+class SqsCommandBusAdapter(CommandBusAdapter):
+    """CommandBus adapter using AWS SQS for queue operations."""
+
+    def __init__(self, queue_name: str, sqs_client: Any) -> None:
+        self.queue_name = queue_name
+        self.sqs_client = sqs_client
+        self.sqs_queue = self.sqs_client.get_queue_by_name(
+            QueueName=self.queue_name,
+        )
+
+    def enqueue(
+        self,
+        message_instance: CommandMessage,
+        delay_seconds: int = 0,
+    ) -> None:
+        """Add a message to the queue."""
+        self.sqs_queue.send_message(
+            MessageBody=str(message_instance),
+            DelaySeconds=delay_seconds,
+        )
+
+    def dequeue(self, message_instance: Any) -> None:
+        """Remove a message from the queue (e.g. after successful processing)."""
+        message_instance.delete()
+
+    def get_messages(
+        self,
+        max_messages: int = 1,
+        wait_seconds: int = 0,
+        visibility_timeout: int = 60,
+    ) -> Any:
+        """Fetch messages from the queue."""
+        return self.sqs_queue.receive_messages(
+            MessageAttributeNames=["ALL"],
+            MaxNumberOfMessages=max_messages,
+            WaitTimeSeconds=wait_seconds,
+            VisibilityTimeout=visibility_timeout,
+        )

command_bus/adapters/response/__init__.py

@@ -0,0 +1,13 @@
+"""Response store adapters for request/response over the command bus (Redis, in-memory, file, etc.)."""
+
+from .file import FileResponseStore
+from .in_memory import InMemoryResponseStore
+
+__all__ = ["InMemoryResponseStore", "FileResponseStore"]
+
+try:
+    from .redis import RedisResponseStore
+
+    __all__ += ["RedisResponseStore"]
+except ImportError:
+    pass