redqueue 0.10.0__py3-none-any.whl

redqueue/compat.py

@@ -0,0 +1,184 @@
+# SPDX-License-Identifier: Apache-2.0
+# Author: SpringMirror-pear
+
+"""Redis version and capability detection."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+from redqueue.exceptions import BackendUnavailableError, RedisCompatibilityError
+
+
+@runtime_checkable
+class RedisInfoClient(Protocol):
+    """Protocol for sync Redis clients that expose INFO."""
+
+    def info(self, section: str | None = None) -> Mapping[str, Any]:
+        """Return Redis INFO fields."""
+
+
+@runtime_checkable
+class AsyncRedisInfoClient(Protocol):
+    """Protocol for async Redis clients that expose INFO."""
+
+    async def info(self, section: str | None = None) -> Mapping[str, Any]:
+        """Return Redis INFO fields."""
+
+
+@dataclass(frozen=True, order=True)
+class RedisVersion:
+    """Comparable Redis semantic version subset."""
+
+    major: int
+    minor: int
+    patch: int = 0
+
+    @classmethod
+    def parse(cls, value: str) -> RedisVersion:
+        version_text = value.strip()
+        release_text = version_text.split("-", 1)[0]
+        parts = release_text.split(".")
+        if len(parts) < 2:
+            raise ValueError(f"invalid Redis version: {value!r}")
+        try:
+            major = cls._parse_part(parts[0], value)
+            minor = cls._parse_part(parts[1], value)
+            patch = cls._parse_part(parts[2], value) if len(parts) > 2 else 0
+        except ValueError as exc:
+            raise ValueError(f"invalid Redis version: {value!r}") from exc
+        return cls(major=major, minor=minor, patch=patch)
+
+    @staticmethod
+    def _parse_part(part: str, original: str) -> int:
+        digits = ""
+        for char in part:
+            if char.isdigit():
+                digits += char
+                continue
+            break
+        if not digits:
+            raise ValueError(f"invalid Redis version: {original!r}")
+        return int(digits)
+
+    def __str__(self) -> str:
+        return f"{self.major}.{self.minor}.{self.patch}"
+
+
+@dataclass(frozen=True)
+class RedisCapabilities:
+    """Feature flags derived from Redis server version."""
+
+    version: RedisVersion
+
+    @property
+    def supports_list_blocking(self) -> bool:
+        return self.version >= RedisVersion(2, 0, 0)
+
+    @property
+    def supports_list_reliable_brpoplpush(self) -> bool:
+        return self.version >= RedisVersion(2, 2, 0)
+
+    @property
+    def supports_list_reliable_blmove(self) -> bool:
+        return self.version >= RedisVersion(6, 2, 0)
+
+    @property
+    def supports_streams(self) -> bool:
+        return self.version >= RedisVersion(5, 0, 0)
+
+    @property
+    def supports_streams_auto_claim(self) -> bool:
+        return self.version >= RedisVersion(6, 2, 0)
+
+    @property
+    def supports_delay_sorted_set(self) -> bool:
+        return self.version >= RedisVersion(1, 2, 0)
+
+    def require_streams(self) -> None:
+        if not self.supports_streams:
+            raise RedisCompatibilityError.for_feature(
+                "Streams backend",
+                current_version=self.version,
+                required_version="5.0.0",
+                action="redis.require_streams",
+            )
+
+    def require_list_reliable(self) -> None:
+        if not self.supports_list_reliable_brpoplpush:
+            raise RedisCompatibilityError.for_feature(
+                "List reliable backend",
+                current_version=self.version,
+                required_version="2.2.0",
+                action="redis.require_list_reliable",
+            )
+
+    def require_delay_sorted_set(self) -> None:
+        if not self.supports_delay_sorted_set:
+            raise RedisCompatibilityError.for_feature(
+                "Delayed task backend",
+                current_version=self.version,
+                required_version="1.2.0",
+                action="redis.require_delay_sorted_set",
+            )
+
+    @classmethod
+    def from_info(cls, info: Mapping[str, Any]) -> RedisCapabilities:
+        """Build capabilities from Redis INFO output."""
+
+        version = extract_redis_version(info)
+        return cls(version=version)
+
+
+def extract_redis_version(info: Mapping[str, Any]) -> RedisVersion:
+    """Extract and parse redis_version from INFO server output."""
+
+    try:
+        version_value = info["redis_version"]
+    except KeyError as exc:
+        raise BackendUnavailableError(
+            "Redis INFO server response does not contain redis_version",
+            action="redis.info",
+        ) from exc
+    if isinstance(version_value, bytes):
+        version_text = version_value.decode("ascii")
+    else:
+        version_text = str(version_value)
+    try:
+        return RedisVersion.parse(version_text)
+    except ValueError as exc:
+        raise BackendUnavailableError(
+            f"Redis INFO server returned invalid redis_version {version_text!r}",
+            action="redis.info",
+            details={"redis_version": version_text},
+        ) from exc
+
+
+def detect_capabilities(client: RedisInfoClient) -> RedisCapabilities:
+    """Detect Redis capabilities using a synchronous Redis client."""
+
+    try:
+        info = client.info("server")
+    except Exception as exc:
+        raise BackendUnavailableError(
+            "Failed to read Redis INFO server",
+            action="redis.info",
+        ) from exc
+    return RedisCapabilities.from_info(info)
+
+
+async def detect_capabilities_async(
+    client: AsyncRedisInfoClient,
+) -> RedisCapabilities:
+    """Detect Redis capabilities using an asynchronous Redis client."""
+
+    try:
+        info = await client.info("server")
+    except Exception as exc:
+        raise BackendUnavailableError(
+            "Failed to read Redis INFO server",
+            action="redis.info",
+        ) from exc
+    return RedisCapabilities.from_info(info)

redqueue/config.py

@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: Apache-2.0
+# Author: SpringMirror-pear
+
+"""Configuration models for RedQueue."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from redqueue.exceptions import QueueConfigError
+from redqueue.monitoring import MonitoringHook, NoopMonitoringHook, SafeMonitoringHook
+from redqueue.serialization import JsonSerializer, Serializer
+
+
+class BackendType(str, Enum):
+    """Supported Redis queue backends."""
+
+    LIST = "list"
+    STREAM = "stream"
+
+    @classmethod
+    def coerce(cls, value: str | BackendType) -> BackendType:
+        """Convert user input into a backend enum with RedQueue errors."""
+
+        if isinstance(value, cls):
+            return value
+        try:
+            return cls(value)
+        except ValueError as exc:
+            supported = ", ".join(item.value for item in cls)
+            raise QueueConfigError(
+                f"unsupported backend {value!r}; supported backends: {supported}"
+            ) from exc
+
+
+@dataclass(frozen=True)
+class RetryConfig:
+    """Retry behavior for failed messages."""
+
+    max_retries: int = 3
+    base_delay_seconds: float = 0.0
+    max_delay_seconds: float | None = None
+
+    def __post_init__(self) -> None:
+        if self.max_retries < 0:
+            raise QueueConfigError("max_retries must be greater than or equal to 0")
+        if self.base_delay_seconds < 0:
+            raise QueueConfigError(
+                "base_delay_seconds must be greater than or equal to 0"
+            )
+        if self.max_delay_seconds is not None and self.max_delay_seconds < 0:
+            raise QueueConfigError(
+                "max_delay_seconds must be greater than or equal to 0"
+            )
+        if (
+            self.max_delay_seconds is not None
+            and self.max_delay_seconds < self.base_delay_seconds
+        ):
+            raise QueueConfigError(
+                "max_delay_seconds must be greater than or equal to base_delay_seconds"
+            )
+
+    def next_delay(self, attempts: int) -> float:
+        """Return the retry delay for an attempt count."""
+
+        if attempts < 0:
+            raise QueueConfigError("attempts must be greater than or equal to 0")
+        delay = self.base_delay_seconds * attempts
+        if self.max_delay_seconds is not None:
+            return min(delay, self.max_delay_seconds)
+        return delay
+
+
+@dataclass(frozen=True)
+class QueueConfig:
+    """Queue configuration shared by sync and async clients."""
+
+    queue: str
+    backend: BackendType | str = BackendType.LIST
+    enable_delay: bool = False
+    namespace: str = "rq"
+    retry: RetryConfig = field(default_factory=RetryConfig)
+    monitoring: MonitoringHook = field(
+        default_factory=lambda: SafeMonitoringHook(NoopMonitoringHook())
+    )
+    serializer: Serializer = field(default_factory=JsonSerializer)
+    visibility_timeout_seconds: float = 300.0
+    consumer_group: str = "redqueue"
+    consumer_name: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        queue = self._normalize_name(self.queue, field_name="queue")
+        namespace = self._normalize_name(self.namespace, field_name="namespace")
+        object.__setattr__(self, "queue", queue)
+        object.__setattr__(self, "namespace", namespace)
+        object.__setattr__(self, "backend", BackendType.coerce(self.backend))
+
+        if self.visibility_timeout_seconds <= 0:
+            raise QueueConfigError("visibility_timeout_seconds must be greater than 0")
+        if not isinstance(self.retry, RetryConfig):
+            raise QueueConfigError("retry must be a RetryConfig instance")
+        if not hasattr(self.monitoring, "emit"):
+            raise QueueConfigError(
+                "monitoring must implement the MonitoringHook protocol"
+            )
+        if not isinstance(self.monitoring, SafeMonitoringHook):
+            object.__setattr__(
+                self,
+                "monitoring",
+                SafeMonitoringHook(self.monitoring),
+            )
+        if not isinstance(self.serializer, Serializer):
+            raise QueueConfigError("serializer must implement the Serializer protocol")
+        if self.consumer_group is not None:
+            consumer_group = self.consumer_group.strip()
+            if not consumer_group:
+                raise QueueConfigError("consumer_group must not be empty")
+            object.__setattr__(self, "consumer_group", consumer_group)
+        if self.consumer_name is not None:
+            consumer_name = self.consumer_name.strip()
+            if not consumer_name:
+                raise QueueConfigError("consumer_name must not be empty")
+            object.__setattr__(self, "consumer_name", consumer_name)
+
+    @staticmethod
+    def _normalize_name(value: str, *, field_name: str) -> str:
+        if not isinstance(value, str):
+            raise QueueConfigError(f"{field_name} must be a string")
+        normalized = value.strip()
+        if not normalized:
+            raise QueueConfigError(f"{field_name} must not be empty")
+        if any(ch.isspace() for ch in normalized):
+            raise QueueConfigError(f"{field_name} must not contain whitespace")
+        return normalized
+
+    @property
+    def backend_type(self) -> BackendType:
+        """Normalized backend type."""
+
+        return BackendType.coerce(self.backend)
+
+    @property
+    def key_prefix(self) -> str:
+        """Redis key prefix for this queue."""
+
+        return f"{self.namespace}:{{{self.queue}}}"
+
+    def key(self, suffix: str) -> str:
+        """Build a namespaced Redis key for a queue-owned data structure."""
+
+        suffix = self._normalize_name(suffix, field_name="suffix")
+        return f"{self.key_prefix}:{suffix}"

redqueue/exceptions.py

@@ -0,0 +1,167 @@
+# SPDX-License-Identifier: Apache-2.0
+# Author: SpringMirror-pear
+
+"""RedQueue exception hierarchy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ErrorContext:
+    """Structured context attached to RedQueue errors."""
+
+    action: str | None = None
+    queue: str | None = None
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return only populated context fields."""
+
+        data: dict[str, Any] = {}
+        if self.action:
+            data["action"] = self.action
+        if self.queue:
+            data["queue"] = self.queue
+        if self.details:
+            data["details"] = dict(self.details)
+        return data
+
+
+class RedQueueError(Exception):
+    """Base class for all RedQueue errors."""
+
+    default_message = "RedQueue operation failed"
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        action: str | None = None,
+        queue: str | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        self.message = message or self.default_message
+        self.context = ErrorContext(
+            action=action,
+            queue=queue,
+            details=dict(details or {}),
+        )
+        super().__init__(self.__str__())
+
+    def __str__(self) -> str:
+        context = self.context.as_dict()
+        if not context:
+            return self.message
+        context_text = ", ".join(
+            f"{key}={value!r}" for key, value in context.items()
+        )
+        return f"{self.message} ({context_text})"
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a structured representation suitable for logs or APIs."""
+
+        return {
+            "type": self.__class__.__name__,
+            "message": self.message,
+            **self.context.as_dict(),
+        }
+
+
+class RedisCompatibilityError(RedQueueError):
+    """Raised when the connected Redis server lacks a required capability."""
+
+    default_message = "Redis server does not meet RedQueue compatibility requirements"
+
+    @classmethod
+    def for_feature(
+        cls,
+        feature: str,
+        *,
+        current_version: Any,
+        required_version: str,
+        action: str | None = None,
+        queue: str | None = None,
+    ) -> RedisCompatibilityError:
+        """Create a compatibility error with a consistent upgrade message."""
+
+        return cls(
+            f"{feature} requires Redis >= {required_version}, "
+            f"current Redis is {current_version}. "
+            f"Disable {feature.lower()} or upgrade Redis.",
+            action=action,
+            queue=queue,
+            details={
+                "feature": feature,
+                "current_version": str(current_version),
+                "required_version": required_version,
+            },
+        )
+
+
+class QueueConfigError(RedQueueError):
+    """Raised when queue configuration is invalid."""
+
+    default_message = "Queue configuration is invalid"
+
+
+class MessageEncodeError(RedQueueError):
+    """Raised when a message cannot be encoded."""
+
+    default_message = "Message encoding failed"
+
+    @classmethod
+    def from_exception(
+        cls,
+        exc: Exception,
+        *,
+        action: str = "message.encode",
+        queue: str | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> MessageEncodeError:
+        """Wrap a lower-level encoding exception while preserving cause."""
+
+        error = cls(str(exc), action=action, queue=queue, details=details)
+        error.__cause__ = exc
+        return error
+
+
+class MessageDecodeError(RedQueueError):
+    """Raised when a message cannot be decoded."""
+
+    default_message = "Message decoding failed"
+
+    @classmethod
+    def from_exception(
+        cls,
+        exc: Exception,
+        *,
+        action: str = "message.decode",
+        queue: str | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> MessageDecodeError:
+        """Wrap a lower-level decoding exception while preserving cause."""
+
+        error = cls(str(exc), action=action, queue=queue, details=details)
+        error.__cause__ = exc
+        return error
+
+
+class BackendUnavailableError(RedQueueError):
+    """Raised when the Redis backend is unavailable or command execution fails."""
+
+    default_message = "Redis backend is unavailable"
+
+
+class AckError(RedQueueError):
+    """Raised when a message cannot be acknowledged consistently."""
+
+    default_message = "Message acknowledgement failed"
+
+
+class RetryExceededError(RedQueueError):
+    """Raised when a message exceeds the configured retry policy."""
+
+    default_message = "Message retry limit exceeded"

redqueue/message.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: Apache-2.0
+# Author: SpringMirror-pear
+
+"""Message model used by RedQueue backends."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from time import time
+from typing import Any
+from uuid import uuid4
+
+from redqueue.exceptions import QueueConfigError
+
+
+def new_message_id() -> str:
+    """Create a stable opaque message identifier."""
+
+    return uuid4().hex
+
+
+@dataclass(frozen=True)
+class Message:
+    """A normalized message returned by RedQueue consumers."""
+
+    payload: Any
+    queue: str
+    id: str = field(default_factory=new_message_id)
+    headers: dict[str, Any] = field(default_factory=dict)
+    attempts: int = 0
+    created_at: float = field(default_factory=time)
+    available_at: float | None = None
+    backend: str | None = None
+    raw_id: str | None = None
+
+    def __post_init__(self) -> None:
+        message_id = self._normalize_required(self.id, field_name="id")
+        queue = self._normalize_required(self.queue, field_name="queue")
+        object.__setattr__(self, "id", message_id)
+        object.__setattr__(self, "queue", queue)
+        object.__setattr__(self, "headers", dict(self.headers))
+
+        if self.attempts < 0:
+            raise QueueConfigError("attempts must be greater than or equal to 0")
+        if self.available_at is not None and self.available_at < 0:
+            raise QueueConfigError("available_at must be greater than or equal to 0")
+        if self.created_at < 0:
+            raise QueueConfigError("created_at must be greater than or equal to 0")
+
+    @staticmethod
+    def _normalize_required(value: str, *, field_name: str) -> str:
+        if not isinstance(value, str):
+            raise QueueConfigError(f"message {field_name} must be a string")
+        normalized = value.strip()
+        if not normalized:
+            raise QueueConfigError(f"message {field_name} must not be empty")
+        return normalized
+
+    def with_attempt(self) -> Message:
+        """Return a copy with attempts incremented by one."""
+
+        return replace(self, attempts=self.attempts + 1)
+
+    def with_backend(self, backend: str, *, raw_id: str | None = None) -> Message:
+        """Return a copy tagged with backend-specific metadata."""
+
+        return replace(self, backend=backend, raw_id=raw_id)

redqueue/monitoring.py

@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: Apache-2.0
+# Author: SpringMirror-pear
+
+"""Monitoring hooks for RedQueue lifecycle events."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from time import time
+from typing import Any, Protocol
+
+
+class MonitoringEventType(str, Enum):
+    """Event names emitted by RedQueue."""
+
+    CLIENT_CREATED = "client.created"
+    MESSAGE_PUBLISHED = "message.published"
+    MESSAGE_CONSUMED = "message.consumed"
+    MESSAGE_ACKED = "message.acked"
+    MESSAGE_NACKED = "message.nacked"
+    MESSAGE_RETRIED = "message.retried"
+    MESSAGE_DEAD_LETTERED = "message.dead_lettered"
+    DELAY_SCHEDULED = "delay.scheduled"
+    DELAY_RELEASED = "delay.released"
+    BACKEND_ERROR = "backend.error"
+
+
+@dataclass(frozen=True)
+class MonitoringEvent:
+    """A structured monitoring event emitted by clients and backends."""
+
+    type: MonitoringEventType
+    queue: str
+    timestamp: float = field(default_factory=time)
+    message_id: str | None = None
+    backend: str | None = None
+    duration_ms: float | None = None
+    error: str | None = None
+    attributes: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a dictionary representation safe for logs and metrics."""
+
+        data: dict[str, Any] = {
+            "type": self.type.value,
+            "queue": self.queue,
+            "timestamp": self.timestamp,
+        }
+        if self.message_id is not None:
+            data["message_id"] = self.message_id
+        if self.backend is not None:
+            data["backend"] = self.backend
+        if self.duration_ms is not None:
+            data["duration_ms"] = self.duration_ms
+        if self.error is not None:
+            data["error"] = self.error
+        if self.attributes:
+            data["attributes"] = dict(self.attributes)
+        return data
+
+
+class MonitoringHook(Protocol):
+    """Protocol for metrics, tracing, and logging integrations."""
+
+    def emit(self, event: MonitoringEvent) -> None:
+        """Handle a monitoring event."""
+
+
+class NoopMonitoringHook:
+    """Default monitoring hook that drops events."""
+
+    def emit(self, event: MonitoringEvent) -> None:
+        return None
+
+
+class InMemoryMonitoringHook:
+    """Monitoring hook that stores events in memory for tests or diagnostics."""
+
+    def __init__(self) -> None:
+        self.events: list[MonitoringEvent] = []
+
+    def emit(self, event: MonitoringEvent) -> None:
+        self.events.append(event)
+
+    def clear(self) -> None:
+        self.events.clear()
+
+
+class CompositeMonitoringHook:
+    """Monitoring hook that fans out events to multiple hooks."""
+
+    def __init__(self, *hooks: MonitoringHook) -> None:
+        self.hooks = hooks
+
+    def emit(self, event: MonitoringEvent) -> None:
+        for hook in self.hooks:
+            hook.emit(event)
+
+
+class SafeMonitoringHook:
+    """Monitoring hook wrapper that isolates hook failures from queue operations."""
+
+    def __init__(self, hook: MonitoringHook) -> None:
+        self.hook = hook
+        self.errors: list[Exception] = []
+
+    def emit(self, event: MonitoringEvent) -> None:
+        try:
+            self.hook.emit(event)
+        except Exception as exc:
+            self.errors.append(exc)