nat-engine 1__py3-none-any.whl

mannf/product/integrations/webhook_receiver.py

@@ -0,0 +1,344 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""Mock webhook receiver for event-driven / async API testing.
+
+:class:`WebhookReceiver` spins up a lightweight HTTP server that listens for
+incoming webhook payloads.  Test cases can:
+
+1. Register a webhook URL by starting the receiver.
+2. Trigger the external system (via the API under test or a separate trigger).
+3. Wait for the expected payload to arrive.
+4. Assert its contents and validate the schema.
+
+This enables autonomous testing of outbound notification flows (GitHub webhooks,
+Stripe events, Slack messages, etc.) without requiring a publicly-routable
+server — the receiver binds to a local port only.
+
+Usage::
+
+    receiver = WebhookReceiver(port=8765)
+    await receiver.start()
+    # ... trigger the webhook ...
+    payload = await receiver.wait_for_payload(timeout=10.0)
+    await receiver.stop()
+
+The receiver also implements the standard ``execute()`` / ``health_check()``
+interface for integration with the NATOrchestrator.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+import uuid
+from typing import Any, Callable, Dict, List, Optional
+
+from mannf.core.distributed.endpoint import Endpoint, EndpointRegistry
+from mannf.core.distributed.system_under_test import SystemUnderTest
+from mannf.core.testing.models import TestCase, TestResult
+
+logger = logging.getLogger(__name__)
+
+
+class _WebhookHandler:
+    """Minimal ASGI-compatible handler that collects incoming webhook payloads."""
+
+    def __init__(self) -> None:
+        self._payloads: asyncio.Queue = asyncio.Queue()
+        self._request_count: int = 0
+
+    @property
+    def request_count(self) -> int:
+        return self._request_count
+
+    async def handle(
+        self, method: str, path: str, headers: dict, body: bytes
+    ) -> tuple[int, dict, bytes]:
+        """Process a single incoming HTTP request.  Returns (status, headers, body)."""
+        self._request_count += 1
+
+        content_type = (headers.get("content-type") or "").lower()
+        payload: Any
+        if "json" in content_type:
+            try:
+                payload = json.loads(body.decode("utf-8"))
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                payload = body.decode("utf-8", errors="replace")
+        else:
+            payload = body.decode("utf-8", errors="replace")
+
+        await self._payloads.put({
+            "method": method,
+            "path": path,
+            "headers": dict(headers),
+            "payload": payload,
+            "received_at": time.time(),
+        })
+
+        return 200, {"Content-Type": "application/json"}, b'{"ok": true}'
+
+    async def get_payload(self, timeout: float = 10.0) -> Optional[dict]:
+        """Wait up to *timeout* seconds for the next payload and return it."""
+        try:
+            return await asyncio.wait_for(self._payloads.get(), timeout=timeout)
+        except asyncio.TimeoutError:
+            return None
+
+    def get_all_payloads(self) -> list[dict]:
+        """Return all payloads received so far without blocking."""
+        results: list[dict] = []
+        try:
+            while True:
+                results.append(self._payloads.get_nowait())
+        except asyncio.QueueEmpty:
+            pass
+        return results
+
+
+class WebhookReceiver(SystemUnderTest):
+    """Mock HTTP server that captures and validates incoming webhook payloads.
+
+    Parameters
+    ----------
+    port:
+        Local port to listen on (default: 0 = OS-assigned).
+    host:
+        Interface to bind to (default: ``"127.0.0.1"``).
+    path_filter:
+        Only capture payloads whose path matches this prefix (default: all).
+    validators:
+        List of callables ``(payload: dict) -> bool`` run against each
+        received payload.  Used to assert schema or content correctness.
+    """
+
+    def __init__(
+        self,
+        port: int = 0,
+        host: str = "127.0.0.1",
+        path_filter: str = "",
+        validators: Optional[List[Callable[[dict], bool]]] = None,
+    ) -> None:
+        self.host = host
+        self.requested_port = port
+        self.actual_port: int = 0
+        self.path_filter = path_filter
+        self.validators: List[Callable[[dict], bool]] = validators or []
+
+        self._handler = _WebhookHandler()
+        self._server: Optional[asyncio.Server] = None
+        self._running = False
+
+        self._registry = EndpointRegistry()
+        self._registry.register(
+            Endpoint(
+                name="default",
+                host=host,
+                port=port or 0,
+                protocol="http",
+                health_check_path="/health",
+            )
+        )
+
+    # ------------------------------------------------------------------
+    # Server lifecycle
+    # ------------------------------------------------------------------
+
+    async def start(self) -> None:
+        """Start the webhook receiver server."""
+        self._server = await asyncio.start_server(
+            self._handle_connection, self.host, self.requested_port
+        )
+        self.actual_port = self._server.sockets[0].getsockname()[1]
+        self._running = True
+
+        # Update registry with actual port
+        self._registry.register(
+            Endpoint(
+                name="default",
+                host=self.host,
+                port=self.actual_port,
+                protocol="http",
+            )
+        )
+        logger.info("WebhookReceiver listening on %s:%d", self.host, self.actual_port)
+
+    async def stop(self) -> None:
+        """Stop the webhook receiver server."""
+        if self._server is not None:
+            self._server.close()
+            await self._server.wait_closed()
+            self._server = None
+        self._running = False
+        logger.info("WebhookReceiver stopped")
+
+    @property
+    def url(self) -> str:
+        """Return the base URL of the receiver (e.g. ``http://127.0.0.1:8765``)."""
+        return f"http://{self.host}:{self.actual_port}"
+
+    async def wait_for_payload(self, timeout: float = 10.0) -> Optional[dict]:
+        """Block until a payload is received or *timeout* elapses."""
+        return await self._handler.get_payload(timeout=timeout)
+
+    def get_all_payloads(self) -> list[dict]:
+        """Return all payloads received so far."""
+        return self._handler.get_all_payloads()
+
+    @property
+    def request_count(self) -> int:
+        """Total number of HTTP requests received."""
+        return self._handler.request_count
+
+    # ------------------------------------------------------------------
+    # Raw TCP handler
+    # ------------------------------------------------------------------
+
+    async def _handle_connection(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+    ) -> None:
+        """Parse a minimal HTTP/1.1 request and dispatch to the handler."""
+        try:
+            raw = await asyncio.wait_for(reader.read(65536), timeout=5.0)
+        except asyncio.TimeoutError:
+            writer.close()
+            return
+
+        try:
+            # Split headers from body
+            header_end = raw.find(b"\r\n\r\n")
+            if header_end == -1:
+                writer.close()
+                return
+
+            header_bytes = raw[:header_end]
+            body = raw[header_end + 4:]
+
+            lines = header_bytes.decode("utf-8", errors="replace").splitlines()
+            if not lines:
+                writer.close()
+                return
+
+            # Request line
+            parts = lines[0].split()
+            method = parts[0] if len(parts) > 0 else "GET"
+            path = parts[1] if len(parts) > 1 else "/"
+
+            # Parse headers
+            headers: dict = {}
+            for line in lines[1:]:
+                if ":" in line:
+                    key, _, val = line.partition(":")
+                    headers[key.strip().lower()] = val.strip()
+
+            # Apply path filter
+            if self.path_filter and not path.startswith(self.path_filter):
+                status, resp_headers, resp_body = 404, {}, b"Not Found"
+            else:
+                status, resp_headers, resp_body = await self._handler.handle(
+                    method, path, headers, body
+                )
+
+            # Build minimal HTTP response
+            header_lines = [f"HTTP/1.1 {status} OK"]
+            for k, v in resp_headers.items():
+                header_lines.append(f"{k}: {v}")
+            header_lines.append(f"Content-Length: {len(resp_body)}")
+            header_lines.append("Connection: close")
+            response = "\r\n".join(header_lines) + "\r\n\r\n"
+            writer.write(response.encode("utf-8") + resp_body)
+            await writer.drain()
+        except Exception as exc:  # noqa: BLE001
+            logger.debug("WebhookReceiver: error handling request: %s", exc)
+        finally:
+            writer.close()
+
+    # ------------------------------------------------------------------
+    # SystemUnderTest interface
+    # ------------------------------------------------------------------
+
+    @property
+    def registry(self) -> EndpointRegistry:
+        return self._registry
+
+    async def execute(self, test_case: TestCase) -> TestResult:
+        """Wait for a webhook payload and validate it.
+
+        ``test_case.target`` is used as a path filter suffix.
+
+        ``test_case.inputs`` may contain:
+
+        * ``timeout`` — how long to wait for the payload (default: ``10.0``).
+        * ``expected_keys`` — list of top-level JSON keys to verify.
+        * ``expected_values`` — dict of ``{key: expected_value}`` pairs to
+          check against the received payload.
+        """
+        timeout = float(test_case.inputs.get("timeout") or 10.0)
+        expected_keys: list = test_case.inputs.get("expected_keys") or []
+        expected_values: dict = test_case.inputs.get("expected_values") or {}
+
+        start = time.monotonic()
+        record = await self.wait_for_payload(timeout=timeout)
+        elapsed_ms = (time.monotonic() - start) * 1000.0
+
+        if record is None:
+            return TestResult(
+                test_case_id=test_case.id,
+                passed=False,
+                actual_output=None,
+                execution_time_ms=elapsed_ms,
+                error="No webhook payload received within timeout",
+            )
+
+        payload = record.get("payload")
+
+        # Run validators
+        error_msg: Optional[str] = None
+        passed = True
+
+        if expected_keys and isinstance(payload, dict):
+            missing = [k for k in expected_keys if k not in payload]
+            if missing:
+                passed = False
+                error_msg = f"Webhook payload missing expected keys: {missing}"
+
+        if passed and expected_values and isinstance(payload, dict):
+            for key, expected_val in expected_values.items():
+                actual_val = payload.get(key)
+                if actual_val != expected_val:
+                    passed = False
+                    error_msg = (
+                        f"Webhook payload key {key!r}: "
+                        f"expected {expected_val!r}, got {actual_val!r}"
+                    )
+                    break
+
+        if passed:
+            for validator in self.validators:
+                try:
+                    if not validator(payload):
+                        passed = False
+                        error_msg = "Custom webhook validator returned False"
+                        break
+                except Exception as exc:  # noqa: BLE001
+                    passed = False
+                    error_msg = f"Custom webhook validator raised: {exc}"
+                    break
+
+        return TestResult(
+            test_case_id=test_case.id,
+            passed=passed,
+            actual_output=payload,
+            execution_time_ms=elapsed_ms,
+            error=error_msg,
+        )
+
+    async def health_check(self) -> bool:
+        """Return True if the server is currently running."""
+        return self._running