nat-engine 1__py3-none-any.whl

mannf/product/ingestors/websocket_ingestor.py

@@ -0,0 +1,526 @@
+# 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.
+
+"""WebSocket / AsyncAPI ingestor plugin.
+
+Parses AsyncAPI 2.x and 3.x specification files (YAML or JSON) describing
+WebSocket channels and message schemas, and produces normalised
+:class:`~mannf.product.ingestors.models.IngestedEndpoint` and
+:class:`~mannf.product.ingestors.models.IngestedTestCase` objects.
+
+Two input formats are supported:
+
+* **AsyncAPI YAML** — ``.yaml`` / ``.yml`` files with ``asyncapi: "2.x"`` or
+  ``asyncapi: "3.x"`` at the top level.
+* **AsyncAPI JSON** — equivalent JSON files.
+
+For each WebSocket channel, one :class:`~mannf.product.ingestors.models.IngestedEndpoint`
+is emitted representing the channel's publish/subscribe operations.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+from mannf.product.ingestors.base import IngestorPlugin
+from mannf.product.ingestors.models import (
+    IngestedEndpoint,
+    IngestedTestCase,
+    IngestorSource,
+    IngestResult,
+)
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_OPERATION_PRIORITY: dict[str, str] = {
+    "subscribe": "high",
+    "publish": "medium",
+}
+
+_ASYNCAPI_WS_SCHEMES = {"ws", "wss", "websocket", "websockets"}
+
+# ---------------------------------------------------------------------------
+# AsyncAPI spec helpers
+# ---------------------------------------------------------------------------
+
+
+def _is_asyncapi(data: dict[str, Any]) -> bool:
+    """Return ``True`` if *data* looks like an AsyncAPI spec."""
+    return "asyncapi" in data and ("channels" in data or "operations" in data)
+
+
+def _asyncapi_version(data: dict[str, Any]) -> tuple[int, int]:
+    """Return the (major, minor) version of an AsyncAPI spec."""
+    raw = str(data.get("asyncapi", "2.0"))
+    parts = raw.split(".")
+    try:
+        major = int(parts[0])
+        minor = int(parts[1]) if len(parts) > 1 else 0
+    except (ValueError, IndexError):
+        major, minor = 2, 0
+    return major, minor
+
+
+def _resolve_schema_ref(ref: str, spec: dict[str, Any]) -> dict[str, Any]:
+    """Follow a JSON reference ``#/components/schemas/Foo`` in *spec*."""
+    if not ref.startswith("#/"):
+        return {}
+    parts = ref[2:].split("/")
+    node: Any = spec
+    for part in parts:
+        if isinstance(node, dict):
+            node = node.get(part, {})
+        else:
+            return {}
+    return node if isinstance(node, dict) else {}
+
+
+def _resolve_message(message: dict[str, Any], spec: dict[str, Any]) -> dict[str, Any]:
+    """Resolve a message object, following ``$ref`` if present."""
+    if "$ref" in message:
+        return _resolve_schema_ref(message["$ref"], spec)
+    return message
+
+
+def _extract_schema_properties(schema: dict[str, Any]) -> list[dict[str, Any]]:
+    """Extract a flat list of property descriptors from a JSON Schema object."""
+    properties: list[dict[str, Any]] = []
+    required = schema.get("required", [])
+    for name, prop_schema in (schema.get("properties") or {}).items():
+        properties.append({
+            "name": name,
+            "type": prop_schema.get("type", "string"),
+            "required": name in required,
+            "description": prop_schema.get("description", ""),
+        })
+    return properties
+
+
+def _build_example_from_schema(schema: dict[str, Any]) -> dict[str, Any]:
+    """Build a minimal example dict from a JSON Schema object."""
+    if "example" in schema:
+        return schema["example"]
+    example: dict[str, Any] = {}
+    for name, prop_schema in (schema.get("properties") or {}).items():
+        ptype = prop_schema.get("type", "string")
+        if ptype == "string":
+            example[name] = ""
+        elif ptype in ("integer", "number"):
+            example[name] = 0
+        elif ptype == "boolean":
+            example[name] = False
+        elif ptype == "array":
+            example[name] = []
+        elif ptype == "object":
+            example[name] = {}
+        else:
+            example[name] = None
+    return example
+
+
+def _extract_channels_v2(
+    spec: dict[str, Any],
+    include_subscribe: bool,
+    include_publish: bool,
+) -> list[IngestedEndpoint]:
+    """Extract endpoints from AsyncAPI 2.x ``channels`` map."""
+    endpoints: list[IngestedEndpoint] = []
+    servers = spec.get("servers") or {}
+    ws_urls: list[str] = []
+    for srv in servers.values():
+        protocol = (srv.get("protocol") or "").lower()
+        if protocol in _ASYNCAPI_WS_SCHEMES:
+            ws_urls.append(srv.get("url", ""))
+
+    ws_base = ws_urls[0] if ws_urls else ""
+
+    for channel_path, channel_def in (spec.get("channels") or {}).items():
+        if not isinstance(channel_def, dict):
+            continue
+
+        for operation in ("subscribe", "publish"):
+            if operation == "subscribe" and not include_subscribe:
+                continue
+            if operation == "publish" and not include_publish:
+                continue
+
+            op_def = channel_def.get(operation)
+            if not op_def:
+                continue
+
+            summary = op_def.get("summary") or channel_def.get("description", "")
+            tags: list[str] = ["websocket", operation]
+            for tag in (op_def.get("tags") or []):
+                tags.append(tag.get("name", "") if isinstance(tag, dict) else str(tag))
+
+            # Resolve message schema
+            raw_message = op_def.get("message") or {}
+            message = _resolve_message(raw_message, spec)
+            payload_schema = _resolve_message(
+                message.get("payload") or {}, spec
+            )
+            if "$ref" in payload_schema:
+                payload_schema = _resolve_schema_ref(payload_schema["$ref"], spec)
+
+            parameters = _extract_schema_properties(payload_schema)
+            request_body: dict[str, Any] | None = None
+            if payload_schema:
+                request_body = {
+                    "schema": payload_schema,
+                    "example": _build_example_from_schema(payload_schema),
+                    "message_name": message.get("name", ""),
+                }
+
+            path = channel_path if channel_path.startswith("/") else f"/{channel_path}"
+            ws_url = f"{ws_base}{path}" if ws_base else path
+
+            endpoint = IngestedEndpoint(
+                method=operation.upper(),
+                path=path,
+                summary=summary,
+                description=op_def.get("description", ""),
+                parameters=parameters,
+                request_body=request_body,
+                responses={},
+                auth_requirements=[],
+                tags=tags,
+                metadata={
+                    "protocol": "websocket",
+                    "operation": operation,
+                    "channel": channel_path,
+                    "ws_url": ws_url,
+                    "asyncapi_version": "2.x",
+                    "message_name": message.get("name", ""),
+                    "content_type": message.get("contentType", "application/json"),
+                },
+            )
+            endpoints.append(endpoint)
+
+    return endpoints
+
+
+def _extract_channels_v3(
+    spec: dict[str, Any],
+    include_subscribe: bool,
+    include_publish: bool,
+) -> list[IngestedEndpoint]:
+    """Extract endpoints from AsyncAPI 3.x ``channels`` + ``operations`` maps."""
+    endpoints: list[IngestedEndpoint] = []
+    servers = spec.get("servers") or {}
+    ws_urls: list[str] = []
+    for srv in servers.values():
+        protocol = (srv.get("protocol") or "").lower()
+        if protocol in _ASYNCAPI_WS_SCHEMES:
+            host = srv.get("host", "")
+            path = srv.get("pathname", "")
+            ws_urls.append(f"{host}{path}")
+
+    ws_base = ws_urls[0] if ws_urls else ""
+
+    # In AsyncAPI 3.x, operations reference channels
+    operations = spec.get("operations") or {}
+    channels_map = spec.get("channels") or {}
+
+    for _op_id, op_def in operations.items():
+        if not isinstance(op_def, dict):
+            continue
+
+        action = (op_def.get("action") or "").lower()
+        operation = "subscribe" if action in ("receive", "subscribe") else "publish"
+
+        if operation == "subscribe" and not include_subscribe:
+            continue
+        if operation == "publish" and not include_publish:
+            continue
+
+        # Resolve channel reference
+        channel_ref = op_def.get("channel") or {}
+        if "$ref" in channel_ref:
+            channel_key = channel_ref["$ref"].split("/")[-1]
+            channel_def = channels_map.get(channel_key, {})
+            channel_path = channel_def.get("address", channel_key)
+        else:
+            channel_path = channel_ref.get("address", "")
+
+        summary = op_def.get("summary") or op_def.get("description", "")
+        tags: list[str] = ["websocket", operation]
+
+        # Resolve message
+        raw_messages = op_def.get("messages") or []
+        message: dict[str, Any] = {}
+        if raw_messages:
+            first = raw_messages[0]
+            if "$ref" in first:
+                message = _resolve_schema_ref(first["$ref"], spec)
+            else:
+                message = first
+
+        payload_schema = message.get("payload") or {}
+        if "$ref" in payload_schema:
+            payload_schema = _resolve_schema_ref(payload_schema["$ref"], spec)
+
+        parameters = _extract_schema_properties(payload_schema)
+        request_body: dict[str, Any] | None = None
+        if payload_schema:
+            request_body = {
+                "schema": payload_schema,
+                "example": _build_example_from_schema(payload_schema),
+                "message_name": message.get("name", ""),
+            }
+
+        path = channel_path if channel_path.startswith("/") else f"/{channel_path}"
+        ws_url = f"{ws_base}{path}" if ws_base else path
+
+        endpoint = IngestedEndpoint(
+            method=operation.upper(),
+            path=path,
+            summary=summary,
+            description=op_def.get("description", ""),
+            parameters=parameters,
+            request_body=request_body,
+            responses={},
+            auth_requirements=[],
+            tags=tags,
+            metadata={
+                "protocol": "websocket",
+                "operation": operation,
+                "channel": channel_path,
+                "ws_url": ws_url,
+                "asyncapi_version": "3.x",
+                "message_name": message.get("name", ""),
+                "content_type": message.get("contentType", "application/json"),
+            },
+        )
+        endpoints.append(endpoint)
+
+    return endpoints
+
+
+def _generate_test_cases(endpoint: IngestedEndpoint) -> list[IngestedTestCase]:
+    """Generate basic test cases for a WebSocket endpoint."""
+    cases: list[IngestedTestCase] = []
+    meta = endpoint.metadata
+    channel = meta.get("channel", endpoint.path)
+    operation = meta.get("operation", "subscribe")
+    ws_url = meta.get("ws_url", "")
+    priority = _OPERATION_PRIORITY.get(operation, "medium")
+    example = (endpoint.request_body or {}).get("example", {})
+
+    # Happy-path connection + message test
+    cases.append(
+        IngestedTestCase(
+            name=f"{channel} — {operation} happy path",
+            description=f"Connect to {channel} and {operation} a well-formed message",
+            steps=[
+                {"action": "ws_connect", "url": ws_url},
+                {"action": "ws_send", "payload": example} if operation == "publish" else
+                {"action": "ws_receive", "timeout": 5.0},
+                {"action": "ws_close"},
+            ],
+            expected_result="WebSocket connection established; message received without error",
+            priority=priority,
+            tags=["websocket", operation, "happy_path"],
+            source_ref=channel,
+            metadata={
+                "case_type": "happy_path",
+                "channel": channel,
+                "operation": operation,
+                "ws_url": ws_url,
+            },
+        )
+    )
+
+    # Connection disconnect / reconnect scenario
+    cases.append(
+        IngestedTestCase(
+            name=f"{channel} — reconnection after disconnect",
+            description="Verify client can reconnect after an unexpected disconnect",
+            steps=[
+                {"action": "ws_connect", "url": ws_url},
+                {"action": "ws_disconnect_abrupt"},
+                {"action": "ws_connect", "url": ws_url},
+                {"action": "ws_close"},
+            ],
+            expected_result="Reconnection succeeds; no lingering error state",
+            priority="medium",
+            tags=["websocket", operation, "reconnection"],
+            source_ref=channel,
+            metadata={
+                "case_type": "reconnection",
+                "channel": channel,
+                "operation": operation,
+                "ws_url": ws_url,
+            },
+        )
+    )
+
+    return cases
+
+
+# ---------------------------------------------------------------------------
+# WebSocketIngestor
+# ---------------------------------------------------------------------------
+
+
+def _looks_like_asyncapi(raw: str) -> bool:
+    """Quick heuristic to detect AsyncAPI content."""
+    return "asyncapi:" in raw or '"asyncapi"' in raw
+
+
+class WebSocketIngestor(IngestorPlugin):
+    """Parse AsyncAPI 2.x/3.x specs describing WebSocket channels.
+
+    Produces one :class:`~mannf.product.ingestors.models.IngestedEndpoint`
+    per channel/operation and generates happy-path and reconnection test cases.
+
+    Supported input formats:
+
+    * AsyncAPI YAML (``.yaml`` / ``.yml``) with a ``asyncapi:`` key.
+    * AsyncAPI JSON (``.json``) with an ``"asyncapi"`` key.
+
+    Configuration keys (passed in the *config* dict to :meth:`ingest`):
+
+    ``include_subscribe``
+        Include subscribe/receive operations (default: ``True``).
+    ``include_publish``
+        Include publish/send operations (default: ``True``).
+    ``ws_endpoint``
+        Override the WebSocket base URL extracted from the spec servers block.
+    """
+
+    name = "websocket"
+    display_name = "WebSocket / AsyncAPI"
+    description = "Parse AsyncAPI 2.x/3.x specs and extract WebSocket channel definitions."
+    supported_extensions = [".yaml", ".yml", ".json"]
+    supported_formats = ["websocket", "asyncapi", "ws"]
+
+    # ------------------------------------------------------------------
+    # can_handle
+    # ------------------------------------------------------------------
+
+    def can_handle(self, source: IngestorSource) -> bool:
+        if source.format in self.supported_formats:
+            return True
+        if source.raw_content and _looks_like_asyncapi(source.raw_content):
+            return True
+        if source.path is not None:
+            ext = Path(source.path).suffix.lower()
+            if ext in (".yaml", ".yml", ".json") and source.raw_content:
+                return _looks_like_asyncapi(source.raw_content)
+        return False
+
+    # ------------------------------------------------------------------
+    # validate_config
+    # ------------------------------------------------------------------
+
+    def validate_config(self, config: dict) -> list[str]:
+        return []
+
+    # ------------------------------------------------------------------
+    # ingest
+    # ------------------------------------------------------------------
+
+    async def ingest(self, source: IngestorSource, config: dict) -> IngestResult:
+        """Parse an AsyncAPI spec and return a normalised :class:`IngestResult`.
+
+        Parameters
+        ----------
+        source:
+            The source to ingest.  Must provide either ``raw_content`` or a
+            valid ``path``.
+        config:
+            Plugin-specific configuration.  See class docstring for keys.
+
+        Returns
+        -------
+        IngestResult
+            Populated result on success; ``success=False`` with ``errors`` on
+            failure.
+        """
+        try:
+            content = self._read_source(source)
+        except (FileNotFoundError, ValueError) as exc:
+            return self._make_error_result(source, str(exc))
+
+        if not content or not content.strip():
+            return self._make_error_result(source, "Empty content — nothing to ingest.")
+
+        include_subscribe: bool = bool(config.get("include_subscribe", True))
+        include_publish: bool = bool(config.get("include_publish", True))
+        ws_endpoint_override: str = config.get("ws_endpoint", "") or ""
+
+        # Parse YAML or JSON
+        stripped = content.strip()
+        spec: dict[str, Any]
+        try:
+            if stripped.startswith("{"):
+                spec = json.loads(content)
+            else:
+                import yaml  # pyyaml
+                spec = yaml.safe_load(content) or {}
+        except Exception as exc:  # noqa: BLE001
+            return self._make_error_result(source, f"Failed to parse spec: {exc}")
+
+        if not isinstance(spec, dict) or not _is_asyncapi(spec):
+            return self._make_error_result(
+                source,
+                "Content does not appear to be an AsyncAPI specification "
+                "(missing 'asyncapi' key or 'channels' / 'operations' block).",
+            )
+
+        major, _minor = _asyncapi_version(spec)
+        warnings: list[str] = []
+
+        if major >= 3:
+            endpoints = _extract_channels_v3(spec, include_subscribe, include_publish)
+        else:
+            endpoints = _extract_channels_v2(spec, include_subscribe, include_publish)
+
+        # Apply ws_endpoint override
+        if ws_endpoint_override:
+            for ep in endpoints:
+                channel = ep.metadata.get("channel", ep.path)
+                ep.metadata["ws_url"] = f"{ws_endpoint_override}{channel}"
+
+        # Generate test cases
+        test_cases: list[IngestedTestCase] = []
+        for ep in endpoints:
+            test_cases.extend(_generate_test_cases(ep))
+
+        if not endpoints:
+            warnings.append(
+                "No WebSocket channels found. Ensure the AsyncAPI spec defines "
+                "channels with subscribe or publish operations and that the server "
+                "uses a WebSocket protocol (ws, wss, websocket, websockets)."
+            )
+
+        stats: dict[str, Any] = {
+            "endpoints_count": len(endpoints),
+            "test_cases_count": len(test_cases),
+            "asyncapi_version": f"{major}.x",
+            "subscribe_count": sum(
+                1 for e in endpoints if e.metadata.get("operation") == "subscribe"
+            ),
+            "publish_count": sum(
+                1 for e in endpoints if e.metadata.get("operation") == "publish"
+            ),
+        }
+
+        return IngestResult(
+            success=True,
+            source=source,
+            endpoints=endpoints,
+            test_cases=test_cases,
+            warnings=warnings,
+            stats=stats,
+        )

mannf/product/integrations/__init__.py

@@ -0,0 +1,21 @@
+# 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.
+
+"""Integrations sub-package — HTTP SUT, OpenAPI parser, Postman parser, and auth strategies."""
+
+from mannf.product.integrations.auth import ApiKeyAuth, AuthStrategy, BearerTokenAuth, NoAuth
+from mannf.product.integrations.http_sut import HttpApiSUT
+from mannf.product.integrations.openapi_parser import OpenApiParser
+from mannf.product.integrations.postman_parser import PostmanParser
+
+__all__ = [
+    "AuthStrategy",
+    "NoAuth",
+    "ApiKeyAuth",
+    "BearerTokenAuth",
+    "HttpApiSUT",
+    "OpenApiParser",
+    "PostmanParser",
+]