nat-engine 1__py3-none-any.whl

mannf/product/ingestors/postman_ingestor.py

@@ -0,0 +1,631 @@
+# 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.
+
+"""Postman Collection ingestor plugin.
+
+Parses Postman v2.1+ Collection JSON files and produces normalised
+:class:`~mannf.product.ingestors.models.IngestedEndpoint` and
+:class:`~mannf.product.ingestors.models.IngestedTestCase` objects.
+
+Utility functions (``_resolve_variables``, ``_path_to_endpoint_name``,
+``_parse_url``, ``_parse_body``, ``_build_auth_headers``,
+``_collect_collection_variables``) are imported from the existing
+:mod:`mannf.product.integrations.postman_parser` module to avoid duplication.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+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,
+)
+from mannf.product.integrations.postman_parser import (
+    _build_auth_headers,
+    _collect_collection_variables,
+    _get_auth_param,
+    _parse_body,
+    _parse_url,
+    _path_to_endpoint_name,
+    _resolve_variables,
+)
+
+logger = logging.getLogger(__name__)
+
+# Postman schema URL fragment that identifies v2.x collections
+_POSTMAN_SCHEMA_FRAGMENT = "collection.json"
+
+# Body modes that are not raw JSON — warn rather than crash
+_UNSUPPORTED_BODY_MODES = {"graphql", "file"}
+
+
+def _is_postman_collection(data: dict[str, Any]) -> bool:
+    """Return ``True`` if *data* looks like a Postman v2.x collection.
+
+    Parameters
+    ----------
+    data:
+        Parsed JSON object.
+
+    Returns
+    -------
+    bool
+        ``True`` when the document has the expected Postman collection shape.
+    """
+    info = data.get("info")
+    if not isinstance(info, dict):
+        return False
+    schema: str = info.get("schema", "") or ""
+    postman_id: str = info.get("_postman_id", "") or ""
+    has_items = "item" in data
+    return has_items and (
+        _POSTMAN_SCHEMA_FRAGMENT in schema or bool(postman_id)
+    )
+
+
+def _extract_auth_schemes(auth_block: dict[str, Any] | None) -> list[str]:
+    """Return a list of auth scheme names present in *auth_block*.
+
+    Parameters
+    ----------
+    auth_block:
+        A Postman ``auth`` object, or ``None``.
+
+    Returns
+    -------
+    list[str]
+        E.g. ``["bearer"]``, ``["apikey"]``, ``["basic"]``, or ``[]``.
+    """
+    if not auth_block:
+        return []
+    auth_type = auth_block.get("type", "").lower()
+    if auth_type in {"noauth", ""}:
+        return []
+    return [auth_type]
+
+
+def _extract_headers(
+    request: dict[str, Any],
+    variables: dict[str, str],
+) -> list[dict[str, str]]:
+    """Return a list of non-disabled header parameter dicts for *request*.
+
+    Parameters
+    ----------
+    request:
+        The Postman request object.
+    variables:
+        Collection-level variable mappings for ``{{var}}`` resolution.
+
+    Returns
+    -------
+    list[dict[str, str]]
+        Each item has ``name`` and ``value`` keys.
+    """
+    headers: list[dict[str, str]] = []
+    for hdr in request.get("header", []):
+        if hdr.get("disabled"):
+            continue
+        key = hdr.get("key", "")
+        value = _resolve_variables(hdr.get("value", "") or "", variables)
+        if key:
+            headers.append({"name": key, "value": value})
+    return headers
+
+
+def _flatten_items(
+    items: list[dict[str, Any]],
+    folder_tags: list[str] | None = None,
+) -> list[tuple[dict[str, Any], list[str]]]:
+    """Recursively flatten a Postman item tree into ``(item, tags)`` pairs.
+
+    Folder names are accumulated as tags for the leaf requests they contain.
+
+    Parameters
+    ----------
+    items:
+        Top-level list of items or folders from the collection.
+    folder_tags:
+        Tags inherited from parent folders.
+
+    Returns
+    -------
+    list[tuple[dict[str, Any], list[str]]]
+        Each tuple is ``(request_item, accumulated_folder_tags)``.
+    """
+    folder_tags = folder_tags or []
+    result: list[tuple[dict[str, Any], list[str]]] = []
+    for item in items:
+        if "item" in item:
+            # Folder — recurse with this folder's name appended to tags
+            folder_name = item.get("name", "")
+            child_tags = folder_tags + ([folder_name] if folder_name else [])
+            result.extend(_flatten_items(item["item"], child_tags))
+        elif "request" in item:
+            result.append((item, list(folder_tags)))
+    return result
+
+
+def _build_request_body_schema(
+    body_obj: dict[str, Any] | None,
+    variables: dict[str, str],
+    warnings: list[str],
+) -> dict[str, Any] | None:
+    """Convert a Postman request body into a normalised schema-like dict.
+
+    Handles ``raw`` (JSON), ``formdata``, and ``urlencoded`` modes.
+    Emits a warning for unsupported modes such as ``graphql`` or ``file``.
+
+    Parameters
+    ----------
+    body_obj:
+        The Postman ``body`` object from the request, or ``None``.
+    variables:
+        Collection variable mappings for ``{{var}}`` resolution.
+    warnings:
+        Mutable list to append warning strings to.
+
+    Returns
+    -------
+    dict[str, Any] | None
+        A body representation dict, or ``None`` for absent/unrecognised body.
+    """
+    if not body_obj:
+        return None
+
+    mode = body_obj.get("mode", "")
+
+    if mode in _UNSUPPORTED_BODY_MODES:
+        warnings.append(
+            f"Request body mode '{mode}' is not fully supported; "
+            "body content will be omitted."
+        )
+        return None
+
+    if mode == "raw":
+        json_body, _ = _parse_body(body_obj, variables)
+        if json_body is not None:
+            return {
+                "content": {
+                    "application/json": {
+                        "schema": {
+                            "type": "object",
+                            "example": json_body,
+                        }
+                    }
+                }
+            }
+        # Raw but not valid JSON (e.g. plain text, XML)
+        raw_text = _resolve_variables(body_obj.get("raw", "") or "", variables)
+        if raw_text.strip():
+            return {
+                "content": {
+                    "text/plain": {
+                        "schema": {"type": "string", "example": raw_text}
+                    }
+                }
+            }
+        return None
+
+    if mode == "formdata":
+        properties: dict[str, Any] = {}
+        for field in body_obj.get("formdata", []):
+            if field.get("disabled"):
+                continue
+            fname = field.get("key", "")
+            fval = _resolve_variables(field.get("value", "") or "", variables)
+            if fname:
+                properties[fname] = {"type": "string", "example": fval}
+        return (
+            {
+                "content": {
+                    "multipart/form-data": {
+                        "schema": {"type": "object", "properties": properties}
+                    }
+                }
+            }
+            if properties
+            else None
+        )
+
+    if mode == "urlencoded":
+        properties = {}
+        for field in body_obj.get("urlencoded", []):
+            if field.get("disabled"):
+                continue
+            fname = field.get("key", "")
+            fval = _resolve_variables(field.get("value", "") or "", variables)
+            if fname:
+                properties[fname] = {"type": "string", "example": fval}
+        return (
+            {
+                "content": {
+                    "application/x-www-form-urlencoded": {
+                        "schema": {"type": "object", "properties": properties}
+                    }
+                }
+            }
+            if properties
+            else None
+        )
+
+    return None
+
+
+def _generate_test_cases(
+    item: dict[str, Any],
+    method: str,
+    path: str,
+    auth_schemes: list[str],
+    folder_tags: list[str],
+    variables: dict[str, str],
+    query_params: dict[str, str],
+    headers: list[dict[str, str]],
+    body_obj: dict[str, Any] | None,
+) -> list[IngestedTestCase]:
+    """Generate positive and optional negative test cases for one request item.
+
+    Parameters
+    ----------
+    item:
+        The Postman request item dict.
+    method:
+        HTTP method (uppercased).
+    path:
+        Resolved URL path.
+    auth_schemes:
+        Auth scheme names active for this request.
+    folder_tags:
+        Folder-inherited tags.
+    variables:
+        Collection variable mappings.
+    query_params:
+        Resolved query parameters.
+    headers:
+        Resolved header list.
+    body_obj:
+        The Postman request ``body`` object, or ``None``.
+
+    Returns
+    -------
+    list[IngestedTestCase]
+        Positive test case, plus a no-auth negative case if auth is present.
+    """
+    name = item.get("name", "Unnamed request")
+    source_ref = f"{method} {path}"
+    cases: list[IngestedTestCase] = []
+
+    # --- Positive test case ---
+    pos_inputs: dict[str, Any] = {"method": method, "path": path}
+    if query_params:
+        pos_inputs["query_params"] = query_params
+    if headers:
+        pos_inputs["headers"] = {h["name"]: h["value"] for h in headers}
+
+    json_body, required_fields = _parse_body(body_obj, variables) if body_obj else (None, [])
+    if json_body is not None and method in {"POST", "PUT", "PATCH"}:
+        pos_inputs["json"] = json_body
+
+    cases.append(
+        IngestedTestCase(
+            name=f"[positive] {name}",
+            description=f"Send a valid {method} request to {path} and expect a 2xx response.",
+            steps=[
+                {
+                    "action": f"{method} {path}",
+                    "description": "Send valid request",
+                }
+            ],
+            expected_result="2xx response",
+            priority="medium",
+            tags=["positive", "functional"] + folder_tags,
+            source_ref=source_ref,
+            metadata={
+                "test_type": "positive",
+                "generator": "postman",
+                "item_name": name,
+            },
+        )
+    )
+
+    # --- No-auth negative test case (only when auth is required) ---
+    if auth_schemes:
+        cases.append(
+            IngestedTestCase(
+                name=f"[security] {name} — missing auth",
+                description=(
+                    f"Send a {method} request to {path} without authentication "
+                    f"and expect a 401 or 403 response."
+                ),
+                steps=[
+                    {
+                        "action": f"{method} {path}",
+                        "description": "Send request without auth credentials",
+                    }
+                ],
+                expected_result="401 or 403 response",
+                priority="high",
+                tags=["security", "auth", "negative"] + folder_tags,
+                source_ref=source_ref,
+                metadata={
+                    "test_type": "negative",
+                    "neg_type": "missing_auth",
+                    "generator": "postman",
+                    "item_name": name,
+                    "auth_schemes": auth_schemes,
+                },
+            )
+        )
+
+    return cases
+
+
+class PostmanIngestor(IngestorPlugin):
+    """Ingest Postman v2.1+ Collection JSON files.
+
+    Produces normalised :class:`~mannf.product.ingestors.models.IngestedEndpoint`
+    and :class:`~mannf.product.ingestors.models.IngestedTestCase` objects from
+    Postman Collection v2.1 JSON files.  Utility functions are reused from
+    :mod:`mannf.product.integrations.postman_parser`.
+
+    Configuration keys
+    ------------------
+    base_url : str, optional
+        Override the base URL extracted from the collection.
+    resolve_variables : bool, optional
+        When ``True`` (default), ``{{variable}}`` placeholders in URLs, headers,
+        and bodies are replaced with collection-level variable values.
+    """
+
+    name = "postman"
+    display_name = "Postman Collection"
+    description = "Ingest Postman v2.1 Collection JSON files."
+    supported_extensions = [".json", ".postman_collection.json"]
+    supported_formats = ["postman"]
+
+    # ------------------------------------------------------------------
+    # validate_config
+    # ------------------------------------------------------------------
+
+    def validate_config(self, config: dict) -> list[str]:
+        """Validate the plugin configuration.
+
+        Parameters
+        ----------
+        config:
+            Supported keys: ``base_url`` (str, optional),
+            ``resolve_variables`` (bool, optional).
+
+        Returns
+        -------
+        list[str]
+            A list of human-readable error strings.  Empty when config is valid.
+        """
+        errors: list[str] = []
+        if "base_url" in config and not isinstance(config["base_url"], str):
+            errors.append("'base_url' must be a string.")
+        if "resolve_variables" in config and not isinstance(
+            config["resolve_variables"], bool
+        ):
+            errors.append("'resolve_variables' must be a boolean.")
+        return errors
+
+    # ------------------------------------------------------------------
+    # can_handle
+    # ------------------------------------------------------------------
+
+    def can_handle(self, source: IngestorSource) -> bool:
+        """Return ``True`` for Postman format or matching JSON extension + content.
+
+        Parameters
+        ----------
+        source:
+            The source to evaluate.
+
+        Returns
+        -------
+        bool
+            ``True`` if this plugin can ingest the source.
+        """
+        if source.format and source.format in self.supported_formats:
+            return True
+
+        if not source.format and source.path is not None:
+            ext = Path(source.path).suffix.lower()
+            if ext not in {".json"}:
+                return False
+            # Content-sniff when raw_content is available
+            if source.raw_content:
+                content_lower = source.raw_content.lower()
+                return (
+                    '"info"' in content_lower
+                    and '"item"' in content_lower
+                    and "postman" in content_lower
+                )
+            return True  # Extension match is sufficient without content
+
+        return False
+
+    # ------------------------------------------------------------------
+    # ingest
+    # ------------------------------------------------------------------
+
+    async def ingest(self, source: IngestorSource, config: dict) -> IngestResult:
+        """Parse a Postman Collection JSON file and return a :class:`IngestResult`.
+
+        Parameters
+        ----------
+        source:
+            The source to ingest.  Must provide either ``raw_content`` or a
+            valid ``path``.
+        config:
+            Plugin-specific configuration.  See :meth:`validate_config` for
+            supported keys.
+
+        Returns
+        -------
+        IngestResult
+            Populated result on success; ``success=False`` with ``errors`` on
+            failure.
+        """
+        # --- Read content ---
+        try:
+            content = self._read_source(source)
+        except (FileNotFoundError, ValueError) as exc:
+            return self._make_error_result(source, str(exc))
+
+        # --- Parse JSON ---
+        try:
+            data: dict[str, Any] = json.loads(content)
+        except (json.JSONDecodeError, ValueError) as exc:
+            return self._make_error_result(
+                source, f"Failed to parse JSON: {exc}"
+            )
+
+        if not isinstance(data, dict):
+            return self._make_error_result(
+                source, "Expected a JSON object at the top level."
+            )
+
+        # Unwrap collections sometimes wrapped under a "collection" key
+        if "collection" in data and isinstance(data["collection"], dict):
+            data = data["collection"]
+
+        # --- Validate Postman collection ---
+        if not _is_postman_collection(data):
+            return self._make_error_result(
+                source,
+                "Content does not appear to be a Postman v2.1 Collection "
+                "(missing 'info._postman_id' or 'info.schema' + 'item').",
+            )
+
+        warnings: list[str] = []
+
+        # --- Collect variables ---
+        should_resolve = bool(config.get("resolve_variables", True))
+        variables: dict[str, str] = (
+            _collect_collection_variables(data) if should_resolve else {}
+        )
+        # Config base_url takes precedence
+        config_base_url: str | None = config.get("base_url") or None
+
+        # Collection-level auth (lower priority than request-level)
+        collection_auth: dict[str, Any] | None = data.get("auth")
+
+        # --- Walk items ---
+        raw_items = data.get("item", [])
+        if not isinstance(raw_items, list):
+            raw_items = []
+
+        flat_items = _flatten_items(raw_items)
+
+        if not flat_items:
+            warnings.append("Collection contains no request items.")
+
+        endpoints: list[IngestedEndpoint] = []
+        test_cases: list[IngestedTestCase] = []
+
+        # Track unique method+path to avoid duplicates
+        seen_endpoints: set[tuple[str, str]] = set()
+
+        for item, folder_tags in flat_items:
+            request = item.get("request", {})
+            if not isinstance(request, dict):
+                continue
+
+            # --- Method ---
+            method = (request.get("method") or "GET").upper()
+
+            # --- URL ---
+            url_obj = request.get("url", "")
+            path, query_params = _parse_url(url_obj, variables)
+
+            # --- Auth ---
+            request_auth: dict[str, Any] | None = request.get("auth")
+            effective_auth = request_auth if request_auth is not None else collection_auth
+            auth_schemes = _extract_auth_schemes(effective_auth)
+
+            # --- Headers ---
+            headers = _extract_headers(request, variables)
+
+            # --- Body ---
+            body_obj: dict[str, Any] | None = request.get("body")
+            request_body_schema = _build_request_body_schema(
+                body_obj, variables, warnings
+            )
+
+            # --- Parameters ---
+            parameters: list[dict[str, Any]] = []
+            for qp_key, qp_val in query_params.items():
+                parameters.append(
+                    {
+                        "name": qp_key,
+                        "in": "query",
+                        "required": False,
+                        "schema": {"type": "string"},
+                        "example": qp_val,
+                    }
+                )
+
+            # --- Tags ---
+            item_tags = list(folder_tags)
+
+            # --- Build endpoint (deduplicated) ---
+            ep_key = (method, path)
+            if ep_key not in seen_endpoints:
+                seen_endpoints.add(ep_key)
+                item_name = item.get("name", "")
+                endpoint = IngestedEndpoint(
+                    method=method,
+                    path=path,
+                    summary=item_name,
+                    parameters=parameters,
+                    request_body=request_body_schema,
+                    auth_requirements=auth_schemes,
+                    tags=item_tags,
+                    metadata={
+                        "generator": "postman",
+                        "base_url": config_base_url or "",
+                        "item_name": item_name,
+                    },
+                )
+                endpoints.append(endpoint)
+
+            # --- Build test cases (always, even for duplicate method+path) ---
+            test_cases.extend(
+                _generate_test_cases(
+                    item=item,
+                    method=method,
+                    path=path,
+                    auth_schemes=auth_schemes,
+                    folder_tags=folder_tags,
+                    variables=variables,
+                    query_params=query_params,
+                    headers=headers,
+                    body_obj=body_obj,
+                )
+            )
+
+        stats: dict[str, Any] = {
+            "endpoints_count": len(endpoints),
+            "test_cases_count": len(test_cases),
+            "collection_name": data.get("info", {}).get("name", ""),
+        }
+
+        return IngestResult(
+            success=True,
+            source=source,
+            endpoints=endpoints,
+            test_cases=test_cases,
+            warnings=warnings,
+            stats=stats,
+        )