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

asap/testing/assertions.py

@@ -0,0 +1,108 @@
+"""Custom assertions for ASAP protocol tests.
+
+This module provides assertion helpers to validate envelopes and
+task outcomes with clear error messages.
+
+Functions:
+    assert_envelope_valid: Assert an Envelope has required fields and valid shape.
+    assert_task_completed: Assert a TaskResponse or envelope payload indicates
+                           task completion (e.g. status completed).
+    assert_response_correlates: Assert response envelope correlates to request.
+"""
+
+from typing import Any
+
+from asap.models.envelope import Envelope
+
+
+def assert_envelope_valid(
+    envelope: Envelope,
+    *,
+    require_id: bool = True,
+    require_timestamp: bool = True,
+    allowed_payload_types: list[str] | None = None,
+) -> None:
+    """Assert that an envelope has required fields and valid structure.
+
+    Args:
+        envelope: The envelope to validate.
+        require_id: If True, envelope.id must be non-empty.
+        require_timestamp: If True, envelope.timestamp must be set.
+        allowed_payload_types: If set, payload_type must be in this list.
+
+    Raises:
+        AssertionError: If any check fails.
+    """
+    assert envelope is not None, "Envelope must not be None"  # nosec B101
+    if require_id:
+        assert envelope.id, "Envelope must have a non-empty id"  # nosec B101
+    if require_timestamp:
+        assert envelope.timestamp is not None, "Envelope must have a timestamp"  # nosec B101
+    assert envelope.sender, "Envelope must have a sender"  # nosec B101
+    assert envelope.recipient, "Envelope must have a recipient"  # nosec B101
+    assert envelope.payload_type, "Envelope must have a payload_type"  # nosec B101
+    assert envelope.payload is not None, "Envelope must have a payload"  # nosec B101
+    if allowed_payload_types is not None:
+        assert envelope.payload_type in allowed_payload_types, (  # nosec B101
+            f"payload_type {envelope.payload_type!r} not in {allowed_payload_types}"
+        )
+
+
+def assert_task_completed(
+    payload: dict[str, Any] | Envelope,
+    *,
+    status_key: str = "status",
+    completed_value: str = "completed",
+) -> None:
+    """Assert that a task response indicates completion.
+
+    Accepts either a TaskResponse-like dict (with status_key) or an
+    Envelope whose payload is such a dict.
+
+    Args:
+        payload: TaskResponse payload dict or Envelope containing it.
+        status_key: Key in payload that holds status (default 'status').
+        completed_value: Value that indicates completion (default 'completed').
+
+    Raises:
+        AssertionError: If payload does not indicate completion.
+    """
+    if isinstance(payload, Envelope):
+        payload = payload.payload or {}
+    assert isinstance(payload, dict), "payload must be a dict or Envelope"  # nosec B101
+    actual = payload.get(status_key)
+    assert actual == completed_value, f"Expected task status {completed_value!r}, got {actual!r}"  # nosec B101
+
+
+def assert_response_correlates(
+    request_envelope: Envelope,
+    response_envelope: Envelope,
+    *,
+    correlation_id_field: str = "correlation_id",
+) -> None:
+    """Assert that a response envelope correlates to the request (by correlation id).
+
+    Args:
+        request_envelope: The request envelope (must have id).
+        response_envelope: The response envelope (must have correlation_id).
+        correlation_id_field: Attribute name on response for correlation (default
+            'correlation_id').
+
+    Raises:
+        AssertionError: If request id or response correlation_id is missing or
+            they do not match.
+    """
+    assert request_envelope.id, "Request envelope must have a non-empty id"  # nosec B101
+    correlation_id = getattr(response_envelope, correlation_id_field, None)
+    assert correlation_id is not None, f"Response envelope must have {correlation_id_field!r}"  # nosec B101
+    assert correlation_id == request_envelope.id, (  # nosec B101
+        f"Response {correlation_id_field!r} {correlation_id!r} does not match "
+        f"request id {request_envelope.id!r}"
+    )
+
+
+__all__ = [
+    "assert_envelope_valid",
+    "assert_task_completed",
+    "assert_response_correlates",
+]

asap/testing/fixtures.py

@@ -0,0 +1,113 @@
+"""Pytest fixtures and context managers for ASAP tests.
+
+This module provides shared fixtures and context managers to reduce
+boilerplate when testing agents, clients, and snapshot stores.
+
+Fixtures (use with pytest):
+    mock_agent: Configurable mock agent for request/response tests.
+    mock_client: ASAP client configured for testing (async; use in async tests).
+    mock_snapshot_store: In-memory snapshot store for state persistence tests.
+
+Context managers:
+    test_agent(): Sync context manager yielding a MockAgent for the scope.
+    test_client(): Async context manager yielding an ASAPClient for the scope.
+"""
+
+from contextlib import asynccontextmanager, contextmanager
+from typing import AsyncIterator, Iterator
+
+import pytest
+
+from asap.state.snapshot import InMemorySnapshotStore
+from asap.testing.mocks import MockAgent
+from asap.transport.client import ASAPClient
+
+DEFAULT_TEST_BASE_URL = "http://localhost:9999"
+
+
+@pytest.fixture
+def mock_agent() -> MockAgent:
+    """Create a fresh MockAgent for the test.
+
+    Returns:
+        A MockAgent instance (cleared between tests via fresh fixture).
+    """
+    return MockAgent()
+
+
+@pytest.fixture
+def mock_snapshot_store() -> InMemorySnapshotStore:
+    """Create an in-memory snapshot store for the test.
+
+    Returns:
+        An InMemorySnapshotStore instance (empty, isolated per test).
+    """
+    return InMemorySnapshotStore()
+
+
+@pytest.fixture
+async def mock_client() -> AsyncIterator[ASAPClient]:
+    """Provide an ASAPClient entered for the test (async fixture).
+
+    Yields an open ASAPClient pointing at DEFAULT_TEST_BASE_URL.
+    Use in async tests; the client is closed after the test.
+
+    Yields:
+        ASAPClient instance (already in async context).
+    """
+    async with ASAPClient(DEFAULT_TEST_BASE_URL) as client:
+        yield client
+
+
+@contextmanager
+def test_agent(agent_id: str = "urn:asap:agent:mock") -> Iterator[MockAgent]:
+    """Context manager that provides a MockAgent for the scope.
+
+    On exit, the agent is cleared (requests and responses reset).
+
+    Args:
+        agent_id: URN for the mock agent.
+
+    Yields:
+        A MockAgent instance.
+
+    Example:
+        >>> with test_agent() as agent:
+        ...     agent.set_response("echo", {"status": "completed"})
+        ...     out = agent.handle(request_envelope)
+    """
+    agent = MockAgent(agent_id)
+    try:
+        yield agent
+    finally:
+        agent.clear()
+
+
+@asynccontextmanager
+async def test_client(
+    base_url: str = DEFAULT_TEST_BASE_URL,
+) -> AsyncIterator[ASAPClient]:
+    """Async context manager that provides an ASAPClient for the scope.
+
+    Args:
+        base_url: Agent base URL (default: localhost:9999 for test servers).
+
+    Yields:
+        An open ASAPClient instance.
+
+    Example:
+        >>> async with test_client("http://localhost:8000") as client:
+        ...     response = await client.send(envelope)
+    """
+    async with ASAPClient(base_url) as client:
+        yield client
+
+
+__all__ = [
+    "DEFAULT_TEST_BASE_URL",
+    "mock_agent",
+    "mock_client",
+    "mock_snapshot_store",
+    "test_agent",
+    "test_client",
+]

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

@@ -41,6 +41,11 @@ Example:
     >>> app = create_app(manifest)
 """
 
+from asap.transport.cache import (
+    DEFAULT_MAX_SIZE,
+    DEFAULT_TTL,
+    ManifestCache,
+)
 from asap.transport.client import (
     ASAPClient,
     ASAPConnectionError,
@@ -48,6 +53,16 @@ from asap.transport.client import (
     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,
     HandlerNotFoundError,
@@ -84,4 +99,17 @@ __all__ = [
     "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

@@ -7,7 +7,6 @@ for sharing circuit breaker state across multiple client instances.
 import threading
 import time
 from enum import Enum
-from typing import Dict
 
 from asap.models.constants import (
     DEFAULT_CIRCUIT_BREAKER_THRESHOLD,
@@ -78,13 +77,18 @@ class CircuitBreaker:
     def record_failure(self) -> None:
         """Record a failed request.
 
-        Increments failure count and opens circuit if threshold is reached.
+        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()
 
-            if self._consecutive_failures >= self.threshold and self._state == CircuitState.CLOSED:
+            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:
@@ -94,18 +98,14 @@ class CircuitBreaker:
             True if request can be attempted, False if circuit is open
         """
         with self._lock:
-            # Check if we should transition from OPEN to HALF_OPEN
             if self._state == CircuitState.OPEN:
                 if self._last_failure_time is not None:
                     elapsed = time.time() - self._last_failure_time
                     if elapsed >= self.timeout:
-                        # Transition to HALF_OPEN to test recovery
                         self._state = CircuitState.HALF_OPEN
                         return True
-                # Still in OPEN state, reject request
                 return False
 
-            # CLOSED or HALF_OPEN: allow request
             return True
 
     def get_state(self) -> CircuitState:
@@ -136,7 +136,7 @@ class CircuitBreakerRegistry:
 
     def __init__(self) -> None:
         """Initialize registry."""
-        self._breakers: Dict[str, CircuitBreaker] = {}
+        self._breakers: dict[str, CircuitBreaker] = {}
         self._lock = threading.RLock()
 
     def get_or_create(
@@ -176,6 +176,7 @@ class CircuitBreakerRegistry:
 # 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()