orchestrata_ultimate.postman.constants

Reference › orchestrata_ultimate › postman › constants

The single home for the numeric and string defaults of the broker (SPEC-002), so that no other postman module hard-codes a limit. It defines values only, with no classes or functions, and imports nothing from the project. config, envelope, error_handler, governance, guarantees, message_store, metrics, payload and others import from it.

The constants are grouped by topic. Message limits: a 1 MB payload, a 4 KB envelope, at most 50 custom headers of up to 1024 characters. Queue defaults: 10000 messages per queue, 24-hour retention, a dead-letter queue named _dead_letter. Delivery defaults: a one-hour time-to-live, a 30-second acknowledgement timeout, 3 retries, a one-second initial retry delay doubling to a 60-second cap. Priority values run from PRIORITY_CRITICAL (0) to PRIORITY_BACKGROUND (4), with normal (2) as the default. Topic limits: 1000 subscribers per topic and 100 subscriptions per agent. The spec's performance targets (5000 messages per second, delivery latency at p95 of 100 ms and similar) are recorded as TARGET_* values. Circuit breaker settings are a failure threshold of 5, a 60-second reset timeout and 3 half-open calls. Content types, metrics windows and histogram buckets, storage defaults, query limits, cache time-to-live values for governance and routing, and PostmanConfig defaults complete the list.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

API

No public API: the module defines no classes, functions or constants.

Source

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

"""
Postman Message Broker Constants

Shared constants for message limits, queue configuration, delivery settings,
priority values, and performance targets for the Postman component.
"""

# Spec: 002 - Postman Message Broker

# ==============================================================================
# Message Limits
# ==============================================================================

MAX_MESSAGE_SIZE_BYTES = 1024 * 1024  # 1 MB - Maximum payload size
MAX_ENVELOPE_SIZE_BYTES = 4096  # 4 KB - Maximum envelope (headers + metadata)
MAX_HEADER_COUNT = 50  # Maximum number of custom headers
MAX_HEADER_VALUE_LENGTH = 1024  # Maximum length of a single header value


# ==============================================================================
# Queue Defaults
# ==============================================================================

DEFAULT_QUEUE_MAX_SIZE = 10000  # Maximum messages per queue
DEFAULT_QUEUE_MAX_AGE_SECONDS = 86400  # 24 hours - Message retention time
DEFAULT_DEAD_LETTER_QUEUE_NAME = "_dead_letter"  # Name of DLQ for failed messages
QUEUE_CHECKPOINT_INTERVAL_SECONDS = 60  # How often to persist queue state


# ==============================================================================
# Delivery Defaults
# ==============================================================================

DEFAULT_MESSAGE_TTL_SECONDS = 3600  # 1 hour - Message time-to-live
DEFAULT_ACK_TIMEOUT_SECONDS = 30  # Timeout for acknowledgment
DEFAULT_MAX_RETRIES = 3  # Maximum delivery retry attempts
DEFAULT_RETRY_DELAY_MS = 1000  # Initial retry delay (1 second)
DEFAULT_RETRY_BACKOFF_MULTIPLIER = 2.0  # Exponential backoff multiplier
MAX_RETRY_DELAY_MS = 60000  # 1 minute - Maximum retry delay


# ==============================================================================
# Priority Values
# ==============================================================================

PRIORITY_CRITICAL = 0  # Highest priority - immediate processing
PRIORITY_HIGH = 1  # High priority - fast processing
PRIORITY_NORMAL = 2  # Normal priority - standard processing
PRIORITY_LOW = 3  # Low priority - background processing
PRIORITY_BACKGROUND = 4  # Lowest priority - deferred processing
DEFAULT_PRIORITY = PRIORITY_NORMAL  # Default message priority


# ==============================================================================
# Topic Defaults
# ==============================================================================

DEFAULT_TOPIC_RETENTION_SECONDS = 604800  # 7 days - Topic message retention
DEFAULT_SUBSCRIPTION_TTL_SECONDS = 0  # No expiry for subscriptions
MAX_SUBSCRIBERS_PER_TOPIC = 1000  # Maximum subscribers per topic
MAX_SUBSCRIPTIONS_PER_AGENT = 100  # Maximum subscriptions per agent


# ==============================================================================
# Performance Targets (from spec)
# ==============================================================================

TARGET_THROUGHPUT_MSG_PER_SEC = 5000  # Messages per second throughput
TARGET_DELIVERY_LATENCY_P95_MS = 100  # 95th percentile delivery latency
TARGET_QUEUE_OP_LATENCY_P95_MS = 50  # 95th percentile queue operation latency
TARGET_SUBSCRIBE_LATENCY_P95_MS = 50  # 95th percentile subscribe latency
TARGET_ACK_LATENCY_P95_MS = 10  # 95th percentile acknowledgment latency


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

CIRCUIT_BREAKER_FAILURE_THRESHOLD = 5  # Failures before opening circuit
CIRCUIT_BREAKER_RESET_TIMEOUT_SECONDS = 60  # Time before attempting reset
CIRCUIT_BREAKER_HALF_OPEN_MAX_CALLS = 3  # Max calls in half-open state


# ==============================================================================
# Content Types
# ==============================================================================

CONTENT_TYPE_JSON = "application/json"  # JSON payload
CONTENT_TYPE_TEXT = "text/plain"  # Plain text payload
CONTENT_TYPE_BINARY = "application/octet-stream"  # Binary payload
CONTENT_TYPE_COMPRESSED = "application/gzip"  # Compressed payload


# ==============================================================================
# Metrics
# ==============================================================================

METRICS_WINDOW_SECONDS = 60  # Time window for metrics aggregation
METRICS_HISTOGRAM_BUCKETS = [
    1,
    5,
    10,
    25,
    50,
    100,
    250,
    500,
    1000,
]  # Latency histogram buckets (milliseconds)


# ==============================================================================
# Storage
# ==============================================================================

DEFAULT_STORAGE_PATH = "/var/lib/postman"  # Default storage directory
DEFAULT_RETENTION_DAYS = 7  # Default message retention period
DEFAULT_STORAGE_LIMIT_GB = 10  # Default storage size limit


# ==============================================================================
# Query / Pagination Defaults
# ==============================================================================

DEFAULT_MESSAGE_QUERY_LIMIT = 100  # Default number of messages returned per query
DEFAULT_RECEIPT_QUERY_LIMIT = 100  # Default number of receipts returned per query
DEFAULT_REPLAY_QUERY_LIMIT = 1000  # Default number of message IDs fetched for replay


# ==============================================================================
# Internal Runtime Defaults
# ==============================================================================

GOVERNANCE_CACHE_TTL_SECONDS = 60  # TTL for postman governance rule cache
ROUTER_CACHE_TTL_SECONDS = 60  # TTL for routing engine route cache
AGE_BOOST_THRESHOLD_SECONDS = 60  # Seconds of age before priority is boosted
RETRY_BASE_DELAY_MS = 100  # Base delay for exponential backoff (milliseconds)
METRICS_LATENCY_SAMPLE_MAXLEN = 1000  # Max latency samples kept in deque
CONFIG_WATCH_THREAD_JOIN_TIMEOUT_SECONDS = 5  # Timeout joining config watch thread
REDIS_HEALTH_CHECK_TIMEOUT_SECONDS = 1  # Socket connect timeout for Redis health check


# ==============================================================================
# Message / Envelope Limits (runtime-facing)
# ==============================================================================

MAX_ENVELOPE_TTL_SECONDS = 86400  # 24 hours — maximum allowed envelope TTL


# ==============================================================================
# PostmanConfig Defaults
# ==============================================================================

DEFAULT_SERVER_PORT = 8080  # Default HTTP port for Postman broker
DEFAULT_MAX_MESSAGE_SIZE_BYTES = 10 * 1024 * 1024  # 10 MB max message size
DEFAULT_THREAD_POOL_SIZE = 10  # Default thread pool size for broker
DEFAULT_ROUTING_RULE_PRIORITY = 100  # Default priority for routing rules