orchestrata_ultimate.postman.exceptions

Reference › orchestrata_ultimate › postman › exceptions

The exception tree of the broker, SPEC-002 story FR-008 (REQ-002-FR8-006 to -012). Every error is a PostmanError, so a caller can catch broadly or at the granularity it needs. PostmanError carries a message, an optional machine-readable error_code and a context dictionary; its string form appends the context. The tree is imported by envelope, payload, delivery, router, queue, error_handler and others, and by agents.tool_registry outside the package.

The branches:

• MessageError: InvalidEnvelopeError, InvalidPayloadError, MessageNotFoundError, MessageExpiredError.
• DeliveryError: RecipientNotFoundError, DeliveryTimeoutError, DeliveryFailedError (permanent), MaxRetriesExceededError.
• QueueError: QueueNotFoundError, QueueFullError, QueueEmptyError.
• TopicError: TopicNotFoundError, InvalidTopicPatternError, SubscriptionNotFoundError.
• RoutingError: NoRouteFoundError, InvalidRoutingRuleError.
• ConfigurationError: InvalidConfigError, ConfigReloadError.
• CircuitOpenError, directly under the root.

error_handler uses the classes to decide what is retried: DeliveryFailedError, CircuitOpenError and MaxRetriesExceededError are not.

At a glance

Class diagram

Dependency diagram

API

Classes

PostmanError

Bases: Exception · Decorators: traces(spec='002', story='FR-008', reqs=['REQ-002-FR8-006', 'REQ-002-FR8-007', 'REQ-002-FR8-008', 'REQ-002-FR8-012']) · Line 26

Base exception for all Postman errors.

MessageError

Bases: PostmanError · Line 73

Base exception for message-related errors.

InvalidEnvelopeError

Bases: MessageError · Decorators: traces(spec='002', story='FR-001', reqs=['REQ-002-FR1-014']) · Line 82

Raised when envelope fields are invalid or missing.

InvalidPayloadError

Bases: MessageError · Decorators: traces(spec='002', story='FR-002', reqs=['REQ-002-FR2-007']) · Line 94

Raised when message payload is invalid.

MessageNotFoundError

Bases: MessageError · Line 105

Raised when a message ID cannot be found.

MessageExpiredError

Bases: MessageError · Line 113

Raised when a message has exceeded its TTL.

DeliveryError

Bases: PostmanError · Line 127

Base exception for delivery-related errors.

RecipientNotFoundError

Bases: DeliveryError · Line 135

Raised when the recipient agent cannot be found.

DeliveryTimeoutError

Bases: DeliveryError · Line 144

Raised when message delivery times out.

DeliveryFailedError

Bases: DeliveryError · Decorators: traces(spec='002', story='FR-008', reqs=['REQ-002-FR8-017']) · Line 153

Raised when message delivery permanently fails.

MaxRetriesExceededError

Bases: DeliveryError · Decorators: traces(spec='002', story='US-001', reqs=['REQ-002-US-001-024']) · Line 162

Raised when maximum retry attempts are exceeded.

QueueError

Bases: PostmanError · Line 176

Base exception for queue-related errors.

QueueNotFoundError

Bases: QueueError · Line 184

Raised when a queue does not exist.

QueueFullError

Bases: QueueError · Decorators: traces(spec='002', story='FR-004', reqs=['REQ-002-FR4-004']) · Line 193

Raised when a queue is at capacity.

QueueEmptyError

Bases: QueueError · Line 201

Raised when attempting to dequeue from an empty queue.

TopicError

Bases: PostmanError · Line 215

Base exception for topic-related errors.

TopicNotFoundError

Bases: TopicError · Line 223

Raised when a topic does not exist.

InvalidTopicPatternError

Bases: TopicError · Decorators: traces(spec='002', story='US-002', reqs=['REQ-002-US-002-006']) · Line 232

Raised when a topic pattern is invalid.

SubscriptionNotFoundError

Bases: TopicError · Decorators: traces(spec='002', story='FR-006', reqs=['REQ-002-FR6-007']) · Line 244

Raised when a subscription does not exist.

RoutingError

Bases: PostmanError · Line 257

Base exception for routing-related errors.

NoRouteFoundError

Bases: RoutingError · Decorators: traces(spec='002', story='FR-003', reqs=['REQ-002-FR3-010']) · Line 266

Raised when no route exists for a destination.

InvalidRoutingRuleError

Bases: RoutingError · Decorators: traces(spec='002', story='US-005', reqs=['REQ-002-US-005-017']) · Line 276

Raised when a routing rule is invalid.

ConfigurationError

Bases: PostmanError · Line 292

Base exception for configuration-related errors.

InvalidConfigError

Bases: ConfigurationError · Decorators: traces(spec='001', story='FR-009', reqs=['REQ-001-US-009-008']) · Line 301

Raised when a configuration value is invalid.

ConfigReloadError

Bases: ConfigurationError · Line 312

Raised when configuration reload fails.

CircuitOpenError

Bases: PostmanError · Decorators: traces(spec='002', story='FR-008', reqs=['REQ-002-FR8-020']) · Line 327

Raised when circuit breaker is open.

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/postman/exceptions.py

"""
Custom exceptions for the Postman message broker.

This module defines a comprehensive exception hierarchy for all Postman-related
errors, including message handling, delivery, queuing, topics, routing, and
configuration issues.
"""

# Spec: 002 - Postman Message Broker

from typing import Any

from orchestrata_ultimate.core.base.traces import traces


@traces(
    spec="002",
    story="FR-008",
    reqs=[
        "REQ-002-FR8-006",
        "REQ-002-FR8-007",
        "REQ-002-FR8-008",
        "REQ-002-FR8-012",
    ],
)
class PostmanError(Exception):
    """
    Base exception for all Postman errors.

    All Postman exceptions inherit from this class, allowing for broad
    exception handling when needed.

    Attributes:
        message: Human-readable error description
        error_code: Optional machine-readable error code
        context: Optional dictionary of additional error context
    """

    @traces(
        spec="002",
        story="FR-008",
        reqs=["REQ-002-FR8-007", "REQ-002-FR8-012"],
    )
    def __init__(
        self,
        message: str,
        error_code: str | None = None,
        context: dict[str, Any] | None = None,
    ) -> None:
        self.message = message
        self.error_code = error_code
        self.context = context or {}
        super().__init__(message)

    @traces(
        spec="002",
        story="FR-008",
        reqs=["REQ-002-FR8-006", "REQ-002-FR8-008"],
    )
    def __str__(self) -> str:
        """Return formatted error message with context if present."""
        if self.context:
            context_str = ", ".join(f"{k}={v}" for k, v in self.context.items())
            return f"{self.message} (context: {context_str})"
        return self.message


# ============================================================================
# Message Errors
# ============================================================================


class MessageError(PostmanError):
    """
    Base exception for message-related errors.

    Covers issues with message structure, validation, and lifecycle.
    """


@traces(spec="002", story="FR-001", reqs=["REQ-002-FR1-014"])
class InvalidEnvelopeError(MessageError):
    """
    Raised when envelope fields are invalid or missing.

    Examples:
        - Missing required fields (TO, FROM, THREAD_ID)
        - Invalid field types
        - Malformed envelope structure
    """


@traces(spec="002", story="FR-002", reqs=["REQ-002-FR2-007"])
class InvalidPayloadError(MessageError):
    """
    Raised when message payload is invalid.

    Examples:
        - Payload exceeds maximum size limit
        - Invalid payload type
        - Payload serialization failure
    """


class MessageNotFoundError(MessageError):
    """
    Raised when a message ID cannot be found.

    Occurs during message lookup, status checks, or acknowledgments.
    """


class MessageExpiredError(MessageError):
    """
    Raised when a message has exceeded its TTL.

    Messages past their time-to-live are considered expired and
    must not be delivered.
    """


# ============================================================================
# Delivery Errors
# ============================================================================


class DeliveryError(PostmanError):
    """
    Base exception for delivery-related errors.

    Covers issues during message delivery attempts.
    """


class RecipientNotFoundError(DeliveryError):
    """
    Raised when the recipient agent cannot be found.

    The destination agent specified in the envelope does not exist
    or is not registered.
    """


class DeliveryTimeoutError(DeliveryError):
    """
    Raised when message delivery times out.

    The delivery attempt exceeded the configured timeout period.
    """


@traces(spec="002", story="FR-008", reqs=["REQ-002-FR8-017"])
class DeliveryFailedError(DeliveryError):
    """
    Raised when message delivery permanently fails.

    Delivery failed and no further retry attempts will be made.
    """


@traces(spec="002", story="US-001", reqs=["REQ-002-US-001-024"])
class MaxRetriesExceededError(DeliveryError):
    """
    Raised when maximum retry attempts are exceeded.

    The delivery has been retried the maximum allowed number of times
    without success.
    """


# ============================================================================
# Queue Errors
# ============================================================================


class QueueError(PostmanError):
    """
    Base exception for queue-related errors.

    Covers issues with queue operations and management.
    """


class QueueNotFoundError(QueueError):
    """
    Raised when a queue does not exist.

    Attempted operation on a queue that has not been created.
    """


@traces(spec="002", story="FR-004", reqs=["REQ-002-FR4-004"])
class QueueFullError(QueueError):
    """
    Raised when a queue is at capacity.

    Cannot enqueue message because queue has reached maximum size.
    """


class QueueEmptyError(QueueError):
    """
    Raised when attempting to dequeue from an empty queue.

    Primarily used in blocking dequeue operations to signal
    that the queue is empty.
    """


# ============================================================================
# Topic Errors
# ============================================================================


class TopicError(PostmanError):
    """
    Base exception for topic-related errors.

    Covers issues with pub/sub topics and subscriptions.
    """


class TopicNotFoundError(TopicError):
    """
    Raised when a topic does not exist.

    Attempted operation on a topic that has not been created.
    """


@traces(spec="002", story="US-002", reqs=["REQ-002-US-002-006"])
class InvalidTopicPatternError(TopicError):
    """
    Raised when a topic pattern is invalid.

    Examples:
        - Malformed wildcard pattern
        - Invalid topic naming
        - Unsupported pattern syntax
    """


@traces(spec="002", story="FR-006", reqs=["REQ-002-FR6-007"])
class SubscriptionNotFoundError(TopicError):
    """
    Raised when a subscription does not exist.

    Attempted to unsubscribe or modify a non-existent subscription.
    """


# ============================================================================
# Routing Errors
# ============================================================================


class RoutingError(PostmanError):
    """
    Base exception for routing-related errors.

    Covers issues with message routing and routing rules.
    """


@traces(spec="002", story="FR-003", reqs=["REQ-002-FR3-010"])
class NoRouteFoundError(RoutingError):
    """
    Raised when no route exists for a destination.

    The routing table does not contain a route for the specified
    destination agent or topic.
    """


@traces(spec="002", story="US-005", reqs=["REQ-002-US-005-017"])
class InvalidRoutingRuleError(RoutingError):
    """
    Raised when a routing rule is invalid.

    Examples:
        - Malformed rule syntax
        - Conflicting rules
        - Invalid rule priority
    """


# ============================================================================
# Configuration Errors
# ============================================================================


class ConfigurationError(PostmanError):
    """
    Base exception for configuration-related errors.

    Covers issues with Postman configuration and settings.
    """


@traces(spec="001", story="FR-009", reqs=["REQ-001-US-009-008"])
class InvalidConfigError(ConfigurationError):
    """
    Raised when a configuration value is invalid.

    Examples:
        - Invalid data type
        - Value out of allowed range
        - Missing required configuration
    """


class ConfigReloadError(ConfigurationError):
    """
    Raised when configuration reload fails.

    Occurs when attempting to reload configuration from file
    or external source.
    """


# ============================================================================
# Circuit Breaker
# ============================================================================


@traces(spec="002", story="FR-008", reqs=["REQ-002-FR8-020"])
class CircuitOpenError(PostmanError):
    """
    Raised when circuit breaker is open.

    The circuit breaker has detected too many failures and has
    opened to prevent cascading failures. Operations are temporarily
    blocked until the circuit breaker resets.
    """