asap-protocol 0.3.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

asap/testing/mocks.py

@@ -0,0 +1,152 @@
+"""Mock agents and request/response recording for ASAP tests.
+
+This module provides MockAgent: a configurable mock agent that can
+pre-set responses and record incoming requests for assertions.
+
+Features:
+    - Pre-set responses per skill or per envelope pattern.
+    - Request recording (incoming envelopes) for later assertion.
+    - Configurable delay or failure for error-path tests.
+"""
+
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+from asap.models.envelope import Envelope
+from asap.models.ids import generate_id
+
+
+class MockAgent:
+    """Configurable mock agent for testing ASAP integrations.
+
+    Simulates an agent without a real server. Supports pre-set responses
+    per skill, request recording, optional delay, and simulated failures
+    for error-path tests.
+
+    Attributes:
+        agent_id: URN identifying this mock agent (e.g. urn:asap:agent:test-echo).
+        requests: List of all envelopes received by handle() (read-only).
+    """
+
+    def __init__(self, agent_id: str = "urn:asap:agent:mock") -> None:
+        """Initialize the mock agent.
+
+        Args:
+            agent_id: URN for this mock agent.
+        """
+        self.agent_id = agent_id
+        self._responses: dict[str, dict[str, Any]] = {}
+        self._default_response: dict[str, Any] | None = None
+        self._delay_seconds: float = 0.0
+        self._failure: BaseException | None = None
+        self.requests: list[Envelope] = []
+
+    def set_response(self, skill_id: str, payload: dict[str, Any]) -> None:
+        """Pre-set the response payload for a skill.
+
+        Args:
+            skill_id: Skill id (e.g. 'echo').
+            payload: Response payload (e.g. TaskResponse.model_dump()).
+        """
+        self._responses[skill_id] = payload
+
+    def set_default_response(self, payload: dict[str, Any]) -> None:
+        """Pre-set a response used when no skill-specific response is set.
+
+        Args:
+            payload: Response payload (e.g. TaskResponse.model_dump()).
+        """
+        self._default_response = payload
+
+    def set_delay(self, seconds: float) -> None:
+        """Set a delay (sleep) before returning the response. Useful for timeout tests.
+
+        Args:
+            seconds: Delay in seconds (0 to disable).
+        """
+        self._delay_seconds = max(0.0, seconds)
+
+    def set_failure(self, exception: BaseException | None) -> None:
+        """Set a failure to raise when handle() is called. Clears after raise.
+
+        Args:
+            exception: Exception to raise (None to disable).
+        """
+        self._failure = exception
+
+    def requests_for_skill(self, skill_id: str) -> list[Envelope]:
+        """Return recorded requests whose payload has the given skill_id.
+
+        Args:
+            skill_id: Skill id to filter by.
+
+        Returns:
+            List of envelopes that requested this skill.
+        """
+        result: list[Envelope] = []
+        for env in self.requests:
+            payload = env.payload if isinstance(env.payload, dict) else {}
+            if payload.get("skill_id") == skill_id:
+                result.append(env)
+        return result
+
+    def handle(self, envelope: Envelope) -> Envelope | None:
+        """Handle an incoming envelope and return a response envelope.
+
+        Records the request. Optionally sleeps (set_delay), raises (set_failure),
+        or returns an envelope built from the pre-set response for the
+        envelope's skill_id or default response.
+
+        Args:
+            envelope: Incoming ASAP envelope.
+
+        Returns:
+            Response envelope or None if no response configured.
+
+        Raises:
+            BaseException: If set_failure() was called with an exception.
+        """
+        self.requests.append(envelope)
+
+        if self._failure is not None:
+            exc = self._failure
+            self._failure = None
+            raise exc
+
+        skill_id = (
+            (envelope.payload or {}).get("skill_id") if isinstance(envelope.payload, dict) else None
+        )
+        payload = (self._responses.get(skill_id) if skill_id else None) or self._default_response
+        if payload is None:
+            return None
+
+        if self._delay_seconds > 0:
+            time.sleep(self._delay_seconds)
+
+        return Envelope(
+            id=generate_id(),
+            asap_version=envelope.asap_version,
+            timestamp=datetime.now(timezone.utc),
+            sender=self.agent_id,
+            recipient=envelope.sender,
+            payload_type="TaskResponse",
+            payload=payload,
+            correlation_id=envelope.id,
+            trace_id=envelope.trace_id,
+        )
+
+    def clear(self) -> None:
+        """Clear recorded requests, pre-set responses, delay, and failure."""
+        self.requests.clear()
+        self._responses.clear()
+        self._default_response = None
+        self._delay_seconds = 0.0
+        self._failure = None
+
+    def reset(self) -> None:
+        """Reset internal state. Equivalent to clear()."""
+        self.clear()
+
+
+__all__ = ["MockAgent"]

asap/transport/__init__.py

@@ -18,6 +18,7 @@ Public exports:
     create_echo_handler: Factory for echo handler
     create_default_registry: Factory for default registry
     ASAPClient: Async HTTP client for agent communication
+    RetryConfig: Configuration dataclass for retry logic and circuit breaker
     ASAPConnectionError: Connection error exception
     ASAPTimeoutError: Timeout error exception
     ASAPRemoteError: Remote error exception
@@ -40,11 +41,27 @@ Example:
     >>> app = create_app(manifest)
 """
 
+from asap.transport.cache import (
+    DEFAULT_MAX_SIZE,
+    DEFAULT_TTL,
+    ManifestCache,
+)
 from asap.transport.client import (
     ASAPClient,
     ASAPConnectionError,
     ASAPRemoteError,
     ASAPTimeoutError,
+    RetryConfig,
+)
+from asap.transport.compression import (
+    COMPRESSION_THRESHOLD,
+    CompressionAlgorithm,
+    compress_payload,
+    decompress_payload,
+    get_accept_encoding_header,
+    get_supported_encodings,
+    is_brotli_available,
+    select_best_encoding,
 )
 from asap.transport.handlers import (
     Handler,
@@ -81,4 +98,18 @@ __all__ = [
     "ASAPConnectionError",
     "ASAPTimeoutError",
     "ASAPRemoteError",
+    "RetryConfig",
+    # Cache
+    "ManifestCache",
+    "DEFAULT_TTL",
+    "DEFAULT_MAX_SIZE",
+    # Compression
+    "COMPRESSION_THRESHOLD",
+    "CompressionAlgorithm",
+    "compress_payload",
+    "decompress_payload",
+    "get_accept_encoding_header",
+    "get_supported_encodings",
+    "is_brotli_available",
+    "select_best_encoding",
 ]

asap/transport/cache.py

@@ -0,0 +1,180 @@
+"""Manifest caching for ASAP protocol.
+
+This module provides caching for agent manifests to reduce HTTP requests
+and improve performance when discovering agent capabilities.
+
+The cache uses an OrderedDict with TTL (Time To Live) expiration and LRU
+eviction when max_size is reached. Entries expire after the configured
+TTL (default: 5 minutes).
+"""
+
+import time
+from collections import OrderedDict
+from threading import Lock
+from typing import Optional
+
+from asap.models.entities import Manifest
+
+
+# Default TTL in seconds (5 minutes)
+DEFAULT_TTL = 300.0
+
+# Default max cache size (number of entries)
+DEFAULT_MAX_SIZE = 1000
+
+
+class CacheEntry:
+    """Cache entry with TTL expiration.
+
+    Attributes:
+        manifest: Cached manifest object
+        expires_at: Timestamp when entry expires (seconds since epoch)
+    """
+
+    def __init__(self, manifest: Manifest, ttl: float) -> None:
+        """Initialize cache entry.
+
+        Args:
+            manifest: Manifest to cache
+            ttl: Time to live in seconds
+        """
+        self.manifest = manifest
+        self.expires_at = time.time() + ttl
+
+    def is_expired(self) -> bool:
+        """Check if cache entry has expired.
+
+        Returns:
+            True if entry has expired, False otherwise
+        """
+        return time.time() >= self.expires_at
+
+
+class ManifestCache:
+    """Thread-safe in-memory LRU cache for agent manifests.
+
+    Provides TTL-based expiration, LRU eviction when max_size is reached,
+    and methods for cache management. Thread-safe for concurrent access
+    from multiple async tasks.
+
+    Attributes:
+        _cache: OrderedDict mapping URL to CacheEntry (maintains LRU order)
+        _lock: Lock for thread-safe access
+        _default_ttl: Default TTL in seconds
+        _max_size: Maximum number of entries (0 for unlimited)
+
+    Example:
+        >>> cache = ManifestCache(default_ttl=300.0, max_size=100)
+        >>> cache.set("http://agent.example.com/manifest.json", manifest, ttl=300.0)
+        >>> cached = cache.get("http://agent.example.com/manifest.json")
+        >>> if cached:
+        ...     print(cached.id)
+    """
+
+    def __init__(
+        self,
+        default_ttl: float = DEFAULT_TTL,
+        max_size: int = DEFAULT_MAX_SIZE,
+    ) -> None:
+        """Initialize manifest cache.
+
+        Args:
+            default_ttl: Default TTL in seconds for cache entries (default: 300.0)
+            max_size: Maximum number of cache entries. When exceeded, the least
+                recently used entry is evicted. Set to 0 for unlimited size.
+                Default: 1000. Very large values may increase cleanup_expired() latency.
+        """
+        self._cache: OrderedDict[str, CacheEntry] = OrderedDict()
+        self._lock = Lock()
+        self._default_ttl = default_ttl
+        self._max_size = max_size
+
+    def get(self, url: str) -> Optional[Manifest]:
+        """Get manifest from cache if present and not expired.
+
+        Accessing an entry moves it to the end of the LRU queue,
+        marking it as most recently used.
+
+        Args:
+            url: Manifest URL
+
+        Returns:
+            Cached manifest if found and not expired, None otherwise
+        """
+        with self._lock:
+            entry = self._cache.get(url)
+            if entry is None:
+                return None
+            if entry.is_expired():
+                del self._cache[url]
+                return None
+            self._cache.move_to_end(url)
+            return entry.manifest
+
+    def set(self, url: str, manifest: Manifest, ttl: Optional[float] = None) -> None:
+        """Store manifest in cache with TTL.
+
+        If max_size is set and the cache is full, the least recently used
+        entry is evicted before adding the new entry.
+
+        Args:
+            url: Manifest URL (cache key)
+            manifest: Manifest to cache
+            ttl: Time to live in seconds (defaults to default_ttl)
+        """
+        if ttl is None:
+            ttl = self._default_ttl
+        with self._lock:
+            if url in self._cache:
+                del self._cache[url]
+            elif self._max_size > 0:
+                while len(self._cache) >= self._max_size:
+                    self._cache.popitem(last=False)
+            self._cache[url] = CacheEntry(manifest, ttl)
+
+    def invalidate(self, url: str) -> None:
+        """Remove manifest from cache.
+
+        Args:
+            url: Manifest URL to invalidate
+        """
+        with self._lock:
+            self._cache.pop(url, None)
+
+    def clear_all(self) -> None:
+        """Clear all cached manifests."""
+        with self._lock:
+            self._cache.clear()
+
+    def size(self) -> int:
+        """Get number of cached entries (including expired).
+
+        Returns:
+            Number of entries in cache
+        """
+        with self._lock:
+            return len(self._cache)
+
+    @property
+    def max_size(self) -> int:
+        """Get the configured maximum cache size.
+
+        Returns:
+            Maximum number of entries (0 for unlimited)
+        """
+        return self._max_size
+
+    def cleanup_expired(self) -> int:
+        """Remove all expired entries from cache.
+
+        Holds the lock for O(N). For very large max_size, prefer lazy eviction
+        in get() or call less frequently.
+
+        Returns:
+            Number of expired entries removed
+        """
+        with self._lock:
+            expired_urls = [url for url, entry in self._cache.items() if entry.is_expired()]
+            for url in expired_urls:
+                del self._cache[url]
+            return len(expired_urls)

asap/transport/circuit_breaker.py

@@ -0,0 +1,194 @@
+"""Circuit breaker implementation for resilient request handling.
+
+This module provides the CircuitBreaker pattern implementation and a registry
+for sharing circuit breaker state across multiple client instances.
+"""
+
+import threading
+import time
+from enum import Enum
+
+from asap.models.constants import (
+    DEFAULT_CIRCUIT_BREAKER_THRESHOLD,
+    DEFAULT_CIRCUIT_BREAKER_TIMEOUT,
+)
+from asap.observability import get_logger
+
+logger = get_logger(__name__)
+
+
+class CircuitState(str, Enum):
+    """Circuit breaker states.
+
+    CLOSED: Normal operation, requests are allowed
+    OPEN: Circuit is open, requests are rejected immediately
+    HALF_OPEN: Testing state, allows one request to test if service recovered
+    """
+
+    CLOSED = "closed"
+    OPEN = "open"
+    HALF_OPEN = "half_open"
+
+
+class CircuitBreaker:
+    """Circuit breaker pattern implementation for resilient request handling.
+
+    The circuit breaker prevents cascading failures by opening the circuit
+    after a threshold of consecutive failures, then attempting to recover
+    after a timeout period.
+
+    States:
+    - CLOSED: Normal operation, all requests allowed
+    - OPEN: Circuit is open, all requests rejected immediately
+    - HALF_OPEN: Testing state, allows one request to test recovery
+
+    This implementation is thread-safe using RLock for concurrent access.
+    """
+
+    def __init__(
+        self,
+        threshold: int = DEFAULT_CIRCUIT_BREAKER_THRESHOLD,
+        timeout: float = DEFAULT_CIRCUIT_BREAKER_TIMEOUT,
+    ) -> None:
+        """Initialize circuit breaker.
+
+        Args:
+            threshold: Number of consecutive failures before opening (default: 5)
+            timeout: Seconds before transitioning OPEN -> HALF_OPEN (default: 60.0)
+        """
+        self.threshold = threshold
+        self.timeout = timeout
+        self._state = CircuitState.CLOSED
+        self._consecutive_failures = 0
+        self._last_failure_time: float | None = None
+        self._lock = threading.RLock()
+
+    def record_success(self) -> None:
+        """Record a successful request.
+
+        Resets failure count and closes circuit if it was HALF_OPEN.
+        """
+        with self._lock:
+            self._consecutive_failures = 0
+            if self._state == CircuitState.HALF_OPEN:
+                self._state = CircuitState.CLOSED
+                self._last_failure_time = None
+
+    def record_failure(self) -> None:
+        """Record a failed request.
+
+        Increments failure count and opens circuit if threshold is reached
+        or if the circuit was in HALF_OPEN state.
+        """
+        with self._lock:
+            self._consecutive_failures += 1
+            self._last_failure_time = time.time()
+
+            threshold_reached = (
+                self._consecutive_failures >= self.threshold and self._state == CircuitState.CLOSED
+            )
+
+            if self._state == CircuitState.HALF_OPEN or threshold_reached:
+                self._state = CircuitState.OPEN
+
+    def can_attempt(self) -> bool:
+        """Check if a request can be attempted.
+
+        Returns:
+            True if request can be attempted, False if circuit is open
+        """
+        with self._lock:
+            if self._state == CircuitState.OPEN:
+                if self._last_failure_time is not None:
+                    elapsed = time.time() - self._last_failure_time
+                    if elapsed >= self.timeout:
+                        self._state = CircuitState.HALF_OPEN
+                        return True
+                return False
+
+            return True
+
+    def get_state(self) -> CircuitState:
+        """Get current circuit state.
+
+        Returns:
+            Current circuit state
+        """
+        with self._lock:
+            return self._state
+
+    def get_consecutive_failures(self) -> int:
+        """Get number of consecutive failures.
+
+        Returns:
+            Number of consecutive failures
+        """
+        with self._lock:
+            return self._consecutive_failures
+
+
+class CircuitBreakerRegistry:
+    """Registry for managing shared CircuitBreaker instances.
+
+    Ensures that multiple clients connecting to the same implementation
+    share the same circuit breaker state.
+    """
+
+    def __init__(self) -> None:
+        """Initialize registry."""
+        self._breakers: dict[str, CircuitBreaker] = {}
+        self._lock = threading.RLock()
+
+    def get_or_create(
+        self,
+        base_url: str,
+        threshold: int = DEFAULT_CIRCUIT_BREAKER_THRESHOLD,
+        timeout: float = DEFAULT_CIRCUIT_BREAKER_TIMEOUT,
+    ) -> CircuitBreaker:
+        """Get existing circuit breaker or create a new one.
+
+        Args:
+            base_url: The target URL (key for the registry)
+            threshold: Threshold for new breakers (ignored if exists)
+            timeout: Timeout for new breakers (ignored if exists)
+
+        Returns:
+            Shared CircuitBreaker instance
+        """
+        with self._lock:
+            if base_url not in self._breakers:
+                logger.info(
+                    "asap.circuit_breaker.created",
+                    base_url=base_url,
+                    threshold=threshold,
+                    timeout=timeout,
+                    message=f"Created shared circuit breaker for {base_url}",
+                )
+                self._breakers[base_url] = CircuitBreaker(threshold=threshold, timeout=timeout)
+            return self._breakers[base_url]
+
+    def clear(self) -> None:
+        """Clear all registered circuit breakers (mostly for testing)."""
+        with self._lock:
+            self._breakers.clear()
+
+
+# Global registry instance
+# In a more complex app, this might be injected, but a module-level singleton
+# is standard for this pattern in Python clients.
+# WARNING: This state persists across tests. Use get_registry().clear() in tearDown.
+_registry = CircuitBreakerRegistry()
+
+
+def get_circuit_breaker(
+    base_url: str,
+    threshold: int = DEFAULT_CIRCUIT_BREAKER_THRESHOLD,
+    timeout: float = DEFAULT_CIRCUIT_BREAKER_TIMEOUT,
+) -> CircuitBreaker:
+    """Helper to get a circuit breaker from the global registry."""
+    return _registry.get_or_create(base_url, threshold, timeout)
+
+
+def get_registry() -> CircuitBreakerRegistry:
+    """Helper to get the global registry instance."""
+    return _registry