weenspace-queue 0.1.0__py3-none-any.whl

weenspace_queue/__init__.py

@@ -0,0 +1,128 @@
+from typing import Any, Callable, Dict, Type
+
+from .asyncio.aws_async import AwsAsyncEngine
+from .asyncio.rabbitmq_async import RabbitMqAsyncEngine
+from .base import (
+    AsyncQueueEngine,
+    Message,
+    QueueEngine,
+    QueueSpecification,
+    TopicSpecification,
+)
+from .constants import (
+    PROVIDER_AWS,
+    PROVIDER_RABBITMQ,
+    ExchangeKind,
+    Provider,
+    QueueKind,
+)
+from .providers.aws import AwsEngine
+from .providers.rabbitmq import RabbitMqEngine
+
+
+class QueueClient:
+    """Single client: pass provider name, then use the same publish/consume/topology methods."""
+
+    _ENGINES: Dict[str, Type[QueueEngine]] = {
+        PROVIDER_AWS: AwsEngine,
+        PROVIDER_RABBITMQ: RabbitMqEngine,
+    }
+
+    def __init__(self, provider: str, **config: Any) -> None:
+        prov_key = provider.lower().strip()
+        engine_cls = self._ENGINES.get(prov_key)
+        if engine_cls is None:
+            supported = ", ".join(sorted(self._ENGINES))
+            raise ValueError(
+                f"Unsupported provider '{provider}'. Supported: {supported}"
+            )
+        self.provider = prov_key
+        self.engine: QueueEngine = engine_cls(**config)
+
+    def declare_queue(self, spec: QueueSpecification) -> str:
+        return self.engine.declare_queue(spec)
+
+    def declare_topic(self, spec: TopicSpecification) -> str:
+        return self.engine.declare_topic(spec)
+
+    def bind_pattern(self, queue_id: str, topic_id: str, pattern: str) -> None:
+        self.engine.bind_pattern(queue_id, topic_id, pattern)
+
+    def publish(self, destination: str, message: Message) -> None:
+        self.engine.publish(destination, message)
+
+    def consume(self, queue_id: str, handler: Callable[[Message], None]) -> None:
+        self.engine.consume(queue_id, handler)
+
+    def stop(self) -> None:
+        self.engine.stop()
+
+    def close(self) -> None:
+        self.engine.close()
+
+    def __enter__(self) -> "QueueClient":
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        self.close()
+
+
+class AsyncQueueClient:
+    """Async twin of QueueClient. Same method names, same provider argument."""
+
+    _ENGINES: Dict[str, Type[AsyncQueueEngine]] = {
+        PROVIDER_AWS: AwsAsyncEngine,
+        PROVIDER_RABBITMQ: RabbitMqAsyncEngine,
+    }
+
+    def __init__(self, provider: str, **config: Any) -> None:
+        prov_key = provider.lower().strip()
+        engine_cls = self._ENGINES.get(prov_key)
+        if engine_cls is None:
+            supported = ", ".join(sorted(self._ENGINES))
+            raise ValueError(
+                f"Unsupported provider '{provider}'. Supported: {supported}"
+            )
+        self.provider = prov_key
+        self.engine: AsyncQueueEngine = engine_cls(**config)
+
+    async def declare_queue(self, spec: QueueSpecification) -> str:
+        return await self.engine.declare_queue(spec)
+
+    async def declare_topic(self, spec: TopicSpecification) -> str:
+        return await self.engine.declare_topic(spec)
+
+    async def bind_pattern(self, queue_id: str, topic_id: str, pattern: str) -> None:
+        await self.engine.bind_pattern(queue_id, topic_id, pattern)
+
+    async def publish(self, destination: str, message: Message) -> None:
+        await self.engine.publish(destination, message)
+
+    async def consume(self, queue_id: str, handler: Callable[[Message], None]) -> None:
+        await self.engine.consume(queue_id, handler)
+
+    async def stop(self) -> None:
+        await self.engine.stop()
+
+    async def close(self) -> None:
+        await self.engine.close()
+
+    async def __aenter__(self) -> "AsyncQueueClient":
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        await self.close()
+
+
+__all__ = [
+    "AsyncQueueClient",
+    "AsyncQueueEngine",
+    "ExchangeKind",
+    "Message",
+    "Provider",
+    "QueueClient",
+    "QueueEngine",
+    "QueueKind",
+    "QueueSpecification",
+    "TopicSpecification",
+]

weenspace_queue/asyncio/__init__.py

@@ -0,0 +1,4 @@
+from .aws_async import AwsAsyncEngine
+from .rabbitmq_async import RabbitMqAsyncEngine
+
+__all__ = ["AwsAsyncEngine", "RabbitMqAsyncEngine"]

weenspace_queue/asyncio/aws_async.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import asyncio
+from weenspace_queue.base import (
+    AsyncQueueEngine,
+    Message,
+    QueueSpecification,
+    TopicSpecification,
+)
+from weenspace_queue.providers.aws import AwsEngine
+
+
+class AwsAsyncEngine(AsyncQueueEngine):
+    """Async AWS engine. Uses aioboto3 when installed, otherwise boto3 in a worker thread."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._sync = AwsEngine(**kwargs)
+
+    async def declare_queue(self, spec: QueueSpecification) -> str:
+        return await asyncio.to_thread(self._sync.declare_queue, spec)
+
+    async def declare_topic(self, spec: TopicSpecification) -> str:
+        return await asyncio.to_thread(self._sync.declare_topic, spec)
+
+    async def bind_pattern(self, queue_id: str, topic_id: str, pattern: str) -> None:
+        await asyncio.to_thread(self._sync.bind_pattern, queue_id, topic_id, pattern)
+
+    async def publish(self, destination: str, message: Message) -> None:
+        await asyncio.to_thread(self._sync.publish, destination, message)
+
+    async def consume(self, queue_id: str, handler: Callable[[Message], None]) -> None:
+        await asyncio.to_thread(self._sync.consume, queue_id, handler)
+
+    async def stop(self) -> None:
+        self._sync.stop()
+
+    async def close(self) -> None:
+        await asyncio.to_thread(self._sync.close)

weenspace_queue/asyncio/rabbitmq_async.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from weenspace_queue import (
+    ClassicQueueSpecification,
+    ExchangeSpecification,
+    ExchangeToQueueBindingSpecification,
+    ExchangeType,
+    Message as ProtonMessage,
+    QuorumQueueSpecification,
+    StreamSpecification,
+)
+from weenspace_queue.asyncio import AsyncEnvironment
+from weenspace_queue.delivery_context import DeliveryContext
+from weenspace_queue.amqp_consumer_handler import AMQPMessagingHandler
+from weenspace_queue.qpid.proton._events import Event
+
+from weenspace_queue.base import (
+    AsyncQueueEngine,
+    Message,
+    QueueSpecification,
+    TopicSpecification,
+)
+from weenspace_queue.constants import (
+    DEFAULT_RABBITMQ_URI,
+    ExchangeKind,
+    QueueKind,
+)
+from weenspace_queue.utils import (
+    encode_body,
+    rabbitmq_exchange_address,
+    rabbitmq_queue_address,
+    rabbitmq_resource_name,
+)
+
+_EXCHANGE_KIND_MAP = {
+    ExchangeKind.DIRECT: ExchangeType.DIRECT,
+    ExchangeKind.TOPIC: ExchangeType.TOPIC,
+    ExchangeKind.FANOUT: ExchangeType.FANOUT,
+    ExchangeKind.HEADERS: ExchangeType.HEADERS,
+}
+
+
+class _CallbackHandler(AMQPMessagingHandler):
+    def __init__(self, handler: Callable[[Message], None]) -> None:
+        super().__init__(auto_accept=False, auto_settle=True)
+        self._handler = handler
+
+    def on_amqp_message(self, event: Event) -> None:
+        proton_msg = event.message
+        routing_key = proton_msg.subject or ""
+        attributes = dict(proton_msg.properties or {})
+        context = DeliveryContext()
+
+        def accept(evt: Event = event) -> None:
+            context.accept(evt)
+
+        def reject(evt: Event = event) -> None:
+            context.discard(evt)
+
+        def requeue(evt: Event = event) -> None:
+            context.requeue(evt)
+
+        self._handler(
+            Message(
+                body=encode_body(proton_msg.body),
+                routing_key=routing_key,
+                attributes=attributes,
+                accept=accept,
+                reject=reject,
+                requeue=requeue,
+            )
+        )
+
+
+class RabbitMqAsyncEngine(AsyncQueueEngine):
+    def __init__(self, **kwargs: Any) -> None:
+        uri = kwargs.get("uri")
+        uris = kwargs.get("uris")
+        if uri is None and uris is None:
+            uri = DEFAULT_RABBITMQ_URI
+        env_kwargs: dict[str, Any] = {"uri": uri, "uris": uris}
+        for key in ("ssl_context", "oauth2_options", "recovery_configuration"):
+            if kwargs.get(key) is not None:
+                env_kwargs[key] = kwargs[key]
+        self._env = AsyncEnvironment(**env_kwargs)
+        self._conn: Any = None
+        self._mgmt: Any = None
+        self._consumer: Any = None
+
+    async def _ensure(self) -> None:
+        if self._conn is not None:
+            return
+        self._conn = await self._env.connection()
+        await self._conn.dial()
+        self._mgmt = await self._conn.management()
+
+    async def declare_queue(self, spec: QueueSpecification) -> str:
+        await self._ensure()
+        if spec.kind == QueueKind.STREAM:
+            await self._mgmt.declare_queue(StreamSpecification(name=spec.name))
+        elif spec.kind == QueueKind.QUORUM:
+            await self._mgmt.declare_queue(
+                QuorumQueueSpecification(
+                    name=spec.name,
+                    dead_letter_exchange=spec.dead_letter_target,
+                    dead_letter_routing_key=spec.dead_letter_routing_key,
+                    deliver_limit=spec.max_receive_count,
+                )
+            )
+        else:
+            await self._mgmt.declare_queue(
+                ClassicQueueSpecification(
+                    name=spec.name,
+                    is_durable=spec.is_durable,
+                    dead_letter_exchange=spec.dead_letter_target,
+                    dead_letter_routing_key=spec.dead_letter_routing_key,
+                )
+            )
+        return rabbitmq_queue_address(spec.name)
+
+    async def declare_topic(self, spec: TopicSpecification) -> str:
+        await self._ensure()
+        await self._mgmt.declare_exchange(
+            ExchangeSpecification(
+                name=spec.name,
+                exchange_type=_EXCHANGE_KIND_MAP.get(spec.kind, ExchangeType.TOPIC),
+                is_durable=spec.is_durable,
+            )
+        )
+        return spec.name
+
+    async def bind_pattern(self, queue_id: str, topic_id: str, pattern: str) -> None:
+        await self._ensure()
+        await self._mgmt.bind(
+            ExchangeToQueueBindingSpecification(
+                source_exchange=rabbitmq_resource_name(topic_id),
+                destination_queue=rabbitmq_resource_name(queue_id),
+                binding_key=pattern,
+            )
+        )
+
+    async def publish(self, destination: str, message: Message) -> None:
+        await self._ensure()
+        address = self._publish_address(destination, message.routing_key)
+        publisher = await self._conn.publisher(address)
+        try:
+            proton_msg = ProtonMessage(body=encode_body(message.body))
+            proton_msg.inferred = True
+            if message.routing_key:
+                proton_msg.subject = message.routing_key
+            await publisher.publish(proton_msg)
+        finally:
+            await publisher.close()
+
+    async def consume(self, queue_id: str, handler: Callable[[Message], None]) -> None:
+        await self._ensure()
+        destination = rabbitmq_queue_address(queue_id)
+        self._consumer = await self._conn.consumer(
+            destination, message_handler=_CallbackHandler(handler)
+        )
+        await self._consumer.run()
+
+    async def stop(self) -> None:
+        if self._consumer is not None:
+            await self._consumer.stop()
+
+    async def close(self) -> None:
+        await self.stop()
+        if self._conn is not None:
+            await self._conn.close()
+        await self._env.close()
+
+    def _publish_address(self, destination: str, routing_key: str) -> str:
+        if destination.startswith("/queues/"):
+            return destination
+        if destination.startswith("/exchanges/"):
+            return rabbitmq_exchange_address(destination, routing_key)
+        if routing_key:
+            return rabbitmq_exchange_address(destination, routing_key)
+        return rabbitmq_queue_address(destination)

weenspace_queue/base.py

@@ -0,0 +1,103 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Optional
+
+from .constants import (
+    DEFAULT_MAX_RECEIVE_COUNT,
+    ExchangeKind,
+    QueueKind,
+)
+
+
+@dataclass
+class Message:
+    body: bytes
+    routing_key: str = ""
+    attributes: Dict[str, Any] = field(default_factory=dict)
+    accept: Optional[Callable[[], None]] = None
+    reject: Optional[Callable[[], None]] = None
+    requeue: Optional[Callable[[], None]] = None
+
+
+@dataclass
+class QueueSpecification:
+    name: str
+    is_durable: bool = True
+    kind: QueueKind = QueueKind.CLASSIC
+    dead_letter_target: Optional[str] = None
+    dead_letter_routing_key: Optional[str] = None
+    max_receive_count: int = DEFAULT_MAX_RECEIVE_COUNT
+    visibility_timeout_seconds: Optional[int] = None
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class TopicSpecification:
+    name: str
+    is_durable: bool = True
+    kind: ExchangeKind = ExchangeKind.TOPIC
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+
+class QueueEngine(ABC):
+    """Provider strategy: one method set for publish, consume, and topology."""
+
+    @abstractmethod
+    def declare_queue(self, spec: QueueSpecification) -> str:
+        pass
+
+    @abstractmethod
+    def declare_topic(self, spec: TopicSpecification) -> str:
+        pass
+
+    @abstractmethod
+    def bind_pattern(self, queue_id: str, topic_id: str, pattern: str) -> None:
+        pass
+
+    @abstractmethod
+    def publish(self, destination: str, message: Message) -> None:
+        pass
+
+    @abstractmethod
+    def consume(self, queue_id: str, handler: Callable[[Message], None]) -> None:
+        pass
+
+    @abstractmethod
+    def stop(self) -> None:
+        pass
+
+    @abstractmethod
+    def close(self) -> None:
+        pass
+
+
+class AsyncQueueEngine(ABC):
+    """Async counterpart of QueueEngine with identical method names."""
+
+    @abstractmethod
+    async def declare_queue(self, spec: QueueSpecification) -> str:
+        pass
+
+    @abstractmethod
+    async def declare_topic(self, spec: TopicSpecification) -> str:
+        pass
+
+    @abstractmethod
+    async def bind_pattern(self, queue_id: str, topic_id: str, pattern: str) -> None:
+        pass
+
+    @abstractmethod
+    async def publish(self, destination: str, message: Message) -> None:
+        pass
+
+    @abstractmethod
+    async def consume(self, queue_id: str, handler: Callable[[Message], None]) -> None:
+        pass
+
+    @abstractmethod
+    async def stop(self) -> None:
+        pass
+
+    @abstractmethod
+    async def close(self) -> None:
+        pass

weenspace_queue/constants.py

@@ -0,0 +1,75 @@
+"""Shared uppercase constants for the unified queue client."""
+
+from enum import Enum
+
+
+class Provider(str, Enum):
+    AWS = "aws"
+    RABBITMQ = "rabbitmq"
+
+
+class QueueKind(str, Enum):
+    CLASSIC = "classic"
+    QUORUM = "quorum"
+    STREAM = "stream"
+
+
+class ExchangeKind(str, Enum):
+    DIRECT = "direct"
+    TOPIC = "topic"
+    FANOUT = "fanout"
+    HEADERS = "headers"
+
+
+PROVIDER_AWS = Provider.AWS.value
+PROVIDER_RABBITMQ = Provider.RABBITMQ.value
+
+DEFAULT_AWS_REGION = "us-east-1"
+DEFAULT_RABBITMQ_URI = "amqp://guest:guest@localhost:5672/"
+DEFAULT_MAX_RECEIVE_COUNT = 5
+DEFAULT_SQS_WAIT_TIME_SECONDS = 20
+DEFAULT_SQS_MAX_MESSAGES = 10
+DEFAULT_SQS_RETENTION_SECONDS = "345600"
+DEFAULT_SQS_VISIBILITY_TIMEOUT_SECONDS = 30
+
+SNS_ARN_MARKER = "arn:aws:sns"
+SQS_ARN_MARKER = "arn:aws:sqs"
+SQS_URL_MARKER = "amazonaws.com"
+SQS_FIFO_SUFFIX = ".fifo"
+
+WILDCARD_SINGLE = "*"
+WILDCARD_MULTI = "#"
+ROUTING_SEPARATOR = "."
+
+ROUTING_KEY_ATTR = "routing_key"
+ROUTING_KEY_LENGTH_ATTR = "rk_len"
+ROUTING_KEY_INDEX_PREFIX = "rk_idx_"
+ROUTING_KEY_REVERSE_INDEX_PREFIX = "rk_ridx_"
+
+AWS_STRING_DATA_TYPE = "String"
+AWS_NUMBER_DATA_TYPE = "Number"
+SNS_FILTER_POLICY_SCOPE_MESSAGE_ATTRIBUTES = "MessageAttributes"
+SNS_PROTOCOL_SQS = "sqs"
+
+RABBITMQ_QUEUE_PREFIX = "/queues/"
+RABBITMQ_EXCHANGE_PREFIX = "/exchanges/"
+
+SQS_RECEIPT_HANDLE_ATTR = "ReceiptHandle"
+SQS_MESSAGE_ATTRIBUTES_KEY = "MessageAttributes"
+SQS_BODY_KEY = "Body"
+SNS_NOTIFICATION_TYPE = "Notification"
+SNS_MESSAGE_KEY = "Message"
+
+IAM_POLICY_VERSION = "2012-10-17"
+SQS_SEND_MESSAGE_ACTION = "sqs:SendMessage"
+SNS_SERVICE_PRINCIPAL = "sns.amazonaws.com"
+SQS_POLICY_ATTRIBUTE = "Policy"
+SQS_QUEUE_ARN_ATTRIBUTE = "QueueArn"
+SQS_REDRIVE_POLICY_ATTRIBUTE = "RedrivePolicy"
+SQS_RETENTION_ATTRIBUTE = "MessageRetentionPeriod"
+SQS_VISIBILITY_ATTRIBUTE = "VisibilityTimeout"
+DEAD_LETTER_TARGET_ARN_KEY = "deadLetterTargetArn"
+MAX_RECEIVE_COUNT_KEY = "maxReceiveCount"
+
+AWS_SOURCE_ARN_CONDITION = "aws:SourceArn"
+ALLOW_SNS_SEND_SID_PREFIX = "AllowSnsSendMessage"

weenspace_queue/providers/__init__.py

@@ -0,0 +1,4 @@
+from .aws import AwsEngine
+from .rabbitmq import RabbitMqEngine
+
+__all__ = ["AwsEngine", "RabbitMqEngine"]