nac-test-pyats-common 0.2.0__tar.gz → 0.2.1__tar.gz

{nac_test_pyats_common-0.2.0 → nac_test_pyats_common-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nac-test-pyats-common
-Version: 0.2.0
+Version: 0.2.1
 Summary: Architecture adapters for Network as Code (NaC) PyATS testing - auth classes, test base classes, and device resolvers
 Project-URL: Homepage, https://github.com/netascode/nac-test-pyats-common
 Project-URL: Documentation, https://github.com/netascode/nac-test-pyats-common
@@ -23,8 +23,9 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Testing
 Classifier: Topic :: System :: Networking
 Requires-Python: >=3.10
+Requires-Dist: filelock>=3.20.1
 Requires-Dist: httpx>=0.28
-Requires-Dist: nac-test==1.1.0b2
+Requires-Dist: nac-test==1.1.0b3
 Provides-Extra: dev
 Requires-Dist: bandit[toml]>=1.8.6; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'

{nac_test_pyats_common-0.2.0 → nac_test_pyats_common-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nac-test-pyats-common"
-version = "0.2.0"
+version = "0.2.1"
 description = "Architecture adapters for Network as Code (NaC) PyATS testing - auth classes, test base classes, and device resolvers"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -27,8 +27,9 @@ classifiers = [
 keywords = ["cisco", "network", "testing", "pyats", "nac", "aci", "sdwan", "catalyst-center"]
 
 dependencies = [
-    "httpx>=0.28",        # HTTP client for auth
-    "nac-test==1.1.0b2",  # Pinned until nac-test stable release includes pyats functionality
+    "filelock>=3.20.1",
+    "httpx>=0.28", # HTTP client for auth
+    "nac-test==1.1.0b3", # Pinned until nac-test stable release includes pyats functionality
 ]
 
 [project.optional-dependencies]
@@ -145,3 +146,8 @@ exclude_lines = [
     "@abstract",
 ]
 omit = ["*/__main__.py"]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.14.10",
+]

nac_test_pyats_common-0.2.1/src/nac_test_pyats_common/aci/auth.py

@@ -0,0 +1,287 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
+"""APIC authentication module for Cisco ACI (Application Centric Infrastructure).
+
+This module provides authentication functionality for Cisco APIC (Application Policy
+Infrastructure Controller), which is the central management and policy enforcement
+point for ACI fabric. The authentication mechanism uses REST API calls to obtain
+session tokens that are valid for a limited time period.
+
+The module implements a two-tier API design:
+1. authenticate() - Low-level method that performs direct APIC authentication
+2. get_token() - High-level method that leverages caching for efficient token reuse
+
+This design ensures efficient token management by reusing valid tokens and only
+re-authenticating when necessary, reducing unnecessary API calls to the APIC controller.
+
+Note on Fork Safety:
+    This module uses urllib instead of httpx for synchronous authentication requests.
+    httpx is NOT fork-safe on macOS - creating httpx.Client after fork() causes
+    silent crashes due to OpenSSL threading issues. urllib uses simpler primitives
+    that work correctly after fork().
+"""
+
+import os
+
+from nac_test.pyats_core.common.auth_cache import AuthCache
+from nac_test.pyats_core.common.subprocess_auth import (
+    SubprocessAuthError,  # noqa: F401 - re-exported for callers to catch
+    execute_auth_subprocess,
+)
+
+# Default token lifetime for APIC authentication tokens in seconds
+# APIC tokens are typically valid for 10 minutes (600 seconds) by default
+APIC_TOKEN_LIFETIME_SECONDS: int = 600
+
+# HTTP timeout for authentication request
+AUTH_REQUEST_TIMEOUT_SECONDS: float = 30.0
+
+
+class APICAuth:
+    """APIC-specific authentication implementation with token caching.
+
+    This class provides a two-tier API for APIC authentication:
+
+    1. Low-level authenticate() method: Directly authenticates with APIC and returns
+       a token along with its expiration time. This is typically used by the caching
+       layer and not called directly by consumers.
+
+    2. High-level get_token() method: Provides cached token management, automatically
+       handling token renewal when expired. This is the primary method that consumers
+       should use for obtaining APIC tokens.
+
+    The two-tier design ensures efficient token reuse across multiple API calls while
+    maintaining clean separation between authentication logic and caching concerns.
+    """
+
+    @staticmethod
+    def authenticate(
+        url: str, username: str, password: str, verify_ssl: bool = False
+    ) -> tuple[str, int]:
+        """Perform direct APIC authentication and obtain a session token.
+
+        This method performs a direct authentication request to the APIC controller
+        using the provided credentials. It returns both the token and its lifetime
+        for proper cache management.
+
+        Internally uses execute_auth_subprocess() to run authentication in a clean
+        subprocess, avoiding the macOS fork+SSL crash issue where SSL operations
+        crash after fork().
+
+        Args:
+            url: Base URL of the APIC controller (e.g., "https://apic.example.com").
+                Should not include trailing slashes or API paths.
+            username: APIC username for authentication. This should be a valid user
+                configured in the APIC with appropriate permissions.
+            password: Password for the specified APIC user account.
+            verify_ssl: Whether to verify SSL certificates. Defaults to False for
+                backward compatibility with lab environments using self-signed certs.
+
+        Returns:
+            A tuple containing:
+                - token (str): The APIC session token that should be included in
+                  subsequent API requests as a cookie (APIC-cookie).
+                - expires_in (int): Token lifetime in seconds (typically 600 seconds).
+
+        Raises:
+            SubprocessAuthError: If authentication subprocess fails or returns an error.
+            ValueError: If the APIC response contains malformed JSON or unexpected
+                structure that cannot be properly parsed.
+
+        Note:
+            SSL verification defaults to disabled to handle self-signed certificates
+            commonly used in lab and development APIC deployments. Set verify_ssl=True
+            for production environments with proper certificate validation.
+        """
+        # Build auth parameters for subprocess
+        auth_params = {
+            "url": url,
+            "username": username,
+            "password": password,
+            "timeout": AUTH_REQUEST_TIMEOUT_SECONDS,
+            "verify_ssl": verify_ssl,
+        }
+
+        # APIC-specific authentication logic
+        # This script assumes `params` dict is already loaded by execute_auth_subprocess
+        auth_script_body = """
+import json
+import ssl
+import urllib.request
+import urllib.error
+
+url = params["url"]
+username = params["username"]
+password = params["password"]
+timeout = params["timeout"]
+verify_ssl = params["verify_ssl"]
+
+try:
+    # Create SSL context
+    ssl_context = ssl.create_default_context()
+    if not verify_ssl:
+        ssl_context.check_hostname = False
+        ssl_context.verify_mode = ssl.CERT_NONE
+
+    # Build JSON payload for APIC authentication
+    payload = json.dumps({
+        "aaaUser": {
+            "attributes": {
+                "name": username,
+                "pwd": password
+            }
+        }
+    }).encode("utf-8")
+
+    # Create request with proper headers
+    request = urllib.request.Request(
+        f"{url}/api/aaaLogin.json",
+        data=payload,
+        headers={"Content-Type": "application/json"},
+        method="POST"
+    )
+
+    # Create HTTPS handler with SSL context
+    https_handler = urllib.request.HTTPSHandler(context=ssl_context)
+    opener = urllib.request.build_opener(https_handler)
+
+    # Execute authentication request
+    response = opener.open(request, timeout=timeout)
+    response_body = response.read().decode("utf-8")
+    response_data = json.loads(response_body)
+
+    # Extract token from response
+    token = response_data["imdata"][0]["aaaLogin"]["attributes"]["token"]
+    result = {"token": token}
+
+except urllib.error.HTTPError as e:
+    error_body = e.read().decode("utf-8") if e.fp else ""
+    result = {
+        "error": f"HTTP {e.code}: {e.reason}",
+        "response": error_body[:500]
+    }
+except (KeyError, IndexError) as e:
+    result = {
+        "error": f"Unexpected response structure: {str(e)}",
+        "response": response_body[:500] if "response_body" in dir() else ""
+    }
+except Exception as e:
+    result = {"error": str(e)}
+"""
+
+        # Execute authentication in subprocess
+        auth_data = execute_auth_subprocess(auth_params, auth_script_body)
+
+        return auth_data["token"], APIC_TOKEN_LIFETIME_SECONDS
+
+    @classmethod
+    def get_token(
+        cls, url: str, username: str, password: str, verify_ssl: bool = False
+    ) -> str:
+        """Get APIC token with automatic caching and renewal.
+
+        This is the primary method that consumers should use to obtain APIC tokens.
+        It leverages the AuthCache to efficiently manage token lifecycle, reusing
+        valid tokens and automatically renewing expired ones. This significantly
+        reduces the number of authentication requests to the APIC controller.
+
+        The method uses a cache key based on the controller type ("ACI"), URL,
+        and username to ensure proper token isolation between different APIC
+        instances and user accounts.
+
+        Args:
+            url: Base URL of the APIC controller (e.g., "https://apic.example.com").
+                Should not include trailing slashes or API paths.
+            username: APIC username for authentication. This should be a valid user
+                configured in the APIC with appropriate permissions.
+            password: Password for the specified APIC user account.
+            verify_ssl: Whether to verify SSL certificates. Defaults to False for
+                backward compatibility with lab environments using self-signed certs.
+
+        Returns:
+            A valid APIC session token that can be used in API requests.
+            The token should be included as a cookie (APIC-cookie) in subsequent
+            API calls to the APIC controller.
+
+        Raises:
+            SubprocessAuthError: If authentication fails due to invalid credentials,
+                network issues, connection timeouts, or APIC server errors. The error
+                message will contain details from the authentication subprocess.
+
+        Examples:
+            >>> # Get a token for APIC access
+            >>> token = APICAuth.get_token(
+            ...     url="https://apic.example.com",
+            ...     username="admin",
+            ...     password="password123"
+            ... )
+            >>> # Use the token in subsequent API calls
+            >>> headers = {"Cookie": f"APIC-cookie={token}"}
+        """
+        # AuthCache.get_or_create_token returns str, but mypy can't verify this
+        # because nac_test lacks py.typed marker. The return type is guaranteed
+        # by AuthCache's implementation which uses extract_token=True mode.
+        return AuthCache.get_or_create_token(  # type: ignore[no-any-return]
+            controller_type="ACI",
+            url=url,
+            username=username,
+            password=password,
+            auth_func=lambda u, un, pw: cls.authenticate(u, un, pw, verify_ssl),
+        )
+
+    @classmethod
+    def get_auth(cls) -> str:
+        """Get APIC token with automatic caching, using environment variables.
+
+        This is the primary method that consumers should use to obtain APIC tokens
+        when using environment variable configuration. It leverages the AuthCache
+        to efficiently manage token lifecycle.
+
+        Environment Variables Required:
+            APIC_URL: Base URL of the APIC controller
+            APIC_USERNAME: APIC username for authentication
+            APIC_PASSWORD: APIC password for authentication
+            APIC_INSECURE: Optional. Set to "True" to disable SSL verification
+                (default: True for backward compatibility)
+
+        Returns:
+            A valid APIC session token.
+
+        Raises:
+            ValueError: If required environment variables are not set.
+        """
+        url = os.environ.get("APIC_URL")
+        username = os.environ.get("APIC_USERNAME")
+        password = os.environ.get("APIC_PASSWORD")
+        insecure = os.environ.get("APIC_INSECURE", "True").lower() in (
+            "true",
+            "1",
+            "yes",
+        )
+
+        # Validate environment variables and collect missing ones
+        missing_vars: list[str] = []
+        if not url:
+            missing_vars.append("APIC_URL")
+        if not username:
+            missing_vars.append("APIC_USERNAME")
+        if not password:
+            missing_vars.append("APIC_PASSWORD")
+
+        if missing_vars:
+            raise ValueError(
+                f"Missing required environment variables: {', '.join(missing_vars)}"
+            )
+
+        # Type narrowing: url, username, password are guaranteed to be str
+        # We raised ValueError above if any were None/empty
+        assert url is not None
+        assert username is not None
+        assert password is not None
+
+        # Normalize URL by removing trailing slash
+        url = url.rstrip("/")
+        verify_ssl = not insecure  # APIC_INSECURE=True means verify=False
+
+        return cls.get_token(url, username, password, verify_ssl)

{nac_test_pyats_common-0.2.0 → nac_test_pyats_common-0.2.1}/src/nac_test_pyats_common/aci/test_base.py

@@ -34,7 +34,8 @@ class APICTestBase(NACTestBase):  # type: ignore[misc]
 
     Attributes:
         token (str): APIC authentication token obtained during setup.
-        client (httpx.AsyncClient): Wrapped async HTTP client configured for APIC.
+        client (httpx.AsyncClient | None): Wrapped async HTTP client configured
+            for APIC. Initialized to None, set during run_async_verification_test().
         controller_url (str): Base URL of the APIC controller (inherited).
         username (str): APIC username for authentication (inherited).
         password (str): APIC password for authentication (inherited).
@@ -58,6 +59,8 @@ class APICTestBase(NACTestBase):  # type: ignore[misc]
                 self.run_async_verification_test(steps)
     """
 
+    client: httpx.AsyncClient | None = None  # MUST declare at class level
+
     @aetest.setup  # type: ignore[misc, untyped-decorator]
     def setup(self) -> None:
         """Setup method that extends the generic base class setup.
@@ -65,7 +68,11 @@ class APICTestBase(NACTestBase):  # type: ignore[misc]
         Initializes the APIC test environment by:
         1. Calling the parent class setup method
         2. Obtaining an APIC authentication token using file-based locking
-        3. Creating and storing an APIC client for use in verification methods
+
+        Note: Client creation is deferred to run_async_verification_test() to avoid
+        macOS fork() issues with httpx/SSL. Creating httpx.AsyncClient in a forked
+        process before entering an async context can cause crashes on macOS due to
+        OpenSSL threading primitives that are not fork-safe.
 
         The authentication token is obtained through the APICAuth utility which
         manages token lifecycle and prevents duplicate authentication requests
@@ -74,12 +81,20 @@ class APICTestBase(NACTestBase):  # type: ignore[misc]
         super().setup()
 
         # Get shared APIC token using file-based locking
-        self.token = APICAuth.get_token(
-            self.controller_url, self.username, self.password
-        )
-
-        # Store the APIC client for use in verification methods
-        self.client = self.get_apic_client()
+        # This reads from file cache - no httpx client creation here
+        try:
+            self.token = APICAuth.get_token(
+                self.controller_url, self.username, self.password
+            )
+        except (RuntimeError, ValueError) as e:
+            # Convert auth failures to FAILED (not ERRORED) - auth issues are
+            # expected failure conditions, not infrastructure errors
+            self.token = ""  # Ensure attribute exists for cleanup code
+            self.failed(f"Authentication failed: {e}")
+            return
+
+        # NOTE: Client creation is deferred to run_async_verification_test()
+        # to avoid macOS fork() + httpx/SSL crash issues
 
     def get_apic_client(self) -> httpx.AsyncClient:
         """Get an httpx async client configured for APIC with response tracking.
@@ -114,9 +129,10 @@ class APICTestBase(NACTestBase):  # type: ignore[misc]
         Simple entry point that uses base class orchestration to run async
         verification tests. This thin wrapper:
         1. Creates and manages an event loop for async operations
-        2. Calls NACTestBase.run_verification_async() to execute tests
-        3. Passes results to NACTestBase.process_results_smart() for reporting
-        4. Ensures proper cleanup of async resources
+        2. Creates the APIC client (deferred from setup for fork safety)
+        3. Calls NACTestBase.run_verification_async() to execute tests
+        4. Passes results to NACTestBase.process_results_smart() for reporting
+        5. Ensures proper cleanup of async resources
 
         The actual verification logic is handled by:
         - get_items_to_verify() - must be implemented by the test class
@@ -131,10 +147,17 @@ class APICTestBase(NACTestBase):  # type: ignore[misc]
             This method creates its own event loop to ensure compatibility
             with PyATS synchronous test execution model. The loop and client
             connections are properly closed after test completion.
+
+            Client creation is done HERE (not in setup) to avoid macOS fork()
+            issues with httpx/SSL. Creating httpx.AsyncClient after fork() but
+            before entering an async context can crash on macOS.
         """
         loop = asyncio.new_event_loop()
         asyncio.set_event_loop(loop)
         try:
+            # Create client INSIDE the event loop context to avoid macOS fork+SSL crash
+            self.client = self.get_apic_client()
+
             # Call the base class generic orchestration
             results = loop.run_until_complete(self.run_verification_async())
 
@@ -142,6 +165,6 @@ class APICTestBase(NACTestBase):  # type: ignore[misc]
             self.process_results_smart(results, steps)
         finally:
             # Clean up the APIC client connection
-            if hasattr(self, "client"):
+            if self.client is not None:  # MANDATORY: never use hasattr()
                 loop.run_until_complete(self.client.aclose())
             loop.close()

{nac_test_pyats_common-0.2.0 → nac_test_pyats_common-0.2.1}/src/nac_test_pyats_common/catc/api_test_base.py

@@ -34,15 +34,16 @@ class CatalystCenterTestBase(NACTestBase):  # type: ignore[misc]
     response capture. It serves as the foundation for all Catalyst Center-specific
     API test classes.
 
-    The class follows the same pattern as APICTestBase and VManageTestBase for
+    The class follows the same pattern as APICTestBase and SDWANManagerTestBase for
     consistency across NAC architecture adapters. Token refresh is handled
     automatically by the AuthCache TTL mechanism.
 
     Attributes:
         auth_data (dict): Catalyst Center authentication data containing the
             token obtained during setup.
-        client (httpx.AsyncClient): Wrapped async HTTP client configured for
-            Catalyst Center.
+        client (httpx.AsyncClient | None): Wrapped async HTTP client configured for
+            Catalyst Center. Initialized to None, set during
+            run_async_verification_test().
         controller_url (str): Base URL of the Catalyst Center controller.
         verify_ssl (bool): Whether SSL verification is enabled.
 
@@ -67,6 +68,9 @@ class CatalystCenterTestBase(NACTestBase):  # type: ignore[misc]
                 self.run_async_verification_test(steps)
     """
 
+    client: httpx.AsyncClient | None = None  # MUST declare at class level
+    auth_data: dict[str, Any]  # Declared at class level for type checker compatibility
+
     @aetest.setup  # type: ignore[misc, untyped-decorator]
     def setup(self) -> None:
         """Setup method that extends the generic base class setup.
@@ -75,7 +79,11 @@ class CatalystCenterTestBase(NACTestBase):  # type: ignore[misc]
         1. Calling the parent class setup method
         2. Obtaining Catalyst Center authentication token using cached auth
         3. Configuring SSL verification from environment
-        4. Creating and storing a Catalyst Center client for use in verification methods
+
+        Note: Client creation is deferred to run_async_verification_test() to avoid
+        macOS fork() issues with httpx/SSL. Creating httpx.AsyncClient in a forked
+        process before entering an async context can cause crashes on macOS due to
+        OpenSSL threading primitives that are not fork-safe.
 
         The authentication token is obtained through the CatalystCenterAuth utility
         which manages token lifecycle and prevents duplicate authentication requests
@@ -84,7 +92,15 @@ class CatalystCenterTestBase(NACTestBase):  # type: ignore[misc]
         super().setup()
 
         # Get Catalyst Center auth data (token)
-        self.auth_data = CatalystCenterAuth.get_auth()
+        # This reads from file cache - no httpx client creation here
+        try:
+            self.auth_data = CatalystCenterAuth.get_auth()
+        except (RuntimeError, ValueError) as e:
+            # Convert auth failures to FAILED (not ERRORED) - auth issues are
+            # expected failure conditions, not infrastructure errors
+            self.auth_data = {}  # Ensure attribute exists for cleanup code
+            self.failed(f"Authentication failed: {e}")
+            return
 
         # Get controller URL from environment
         self.controller_url = os.environ.get("CC_URL", "").rstrip("/")
@@ -93,8 +109,8 @@ class CatalystCenterTestBase(NACTestBase):  # type: ignore[misc]
         insecure = os.environ.get("CC_INSECURE", "True").lower() in ("true", "1", "yes")
         self.verify_ssl = not insecure
 
-        # Store the Catalyst Center client for use in verification methods
-        self.client = self.get_catc_client()
+        # NOTE: Client creation is deferred to run_async_verification_test()
+        # to avoid macOS fork() + httpx/SSL crash issues
 
     def get_catc_client(self) -> httpx.AsyncClient:
         """Get an httpx async client configured for Catalyst Center.
@@ -144,9 +160,10 @@ class CatalystCenterTestBase(NACTestBase):  # type: ignore[misc]
         Simple entry point that uses base class orchestration to run async
         verification tests. This thin wrapper:
         1. Creates and manages an event loop for async operations
-        2. Calls NACTestBase.run_verification_async() to execute tests
-        3. Passes results to NACTestBase.process_results_smart() for reporting
-        4. Ensures proper cleanup of async resources
+        2. Creates the Catalyst Center client (deferred from setup for fork safety)
+        3. Calls NACTestBase.run_verification_async() to execute tests
+        4. Passes results to NACTestBase.process_results_smart() for reporting
+        5. Ensures proper cleanup of async resources
 
         The actual verification logic is handled by:
         - get_items_to_verify() - must be implemented by the test class
@@ -161,10 +178,17 @@ class CatalystCenterTestBase(NACTestBase):  # type: ignore[misc]
             This method creates its own event loop to ensure compatibility
             with PyATS synchronous test execution model. The loop and client
             connections are properly closed after test completion.
+
+            Client creation is done HERE (not in setup) to avoid macOS fork()
+            issues with httpx/SSL. Creating httpx.AsyncClient after fork() but
+            before entering an async context can crash on macOS.
         """
         loop = asyncio.new_event_loop()
         asyncio.set_event_loop(loop)
         try:
+            # Create client INSIDE the event loop context to avoid macOS fork+SSL crash
+            self.client = self.get_catc_client()
+
             # Call the base class generic orchestration
             results = loop.run_until_complete(self.run_verification_async())
 
@@ -172,6 +196,6 @@ class CatalystCenterTestBase(NACTestBase):  # type: ignore[misc]
             self.process_results_smart(results, steps)
         finally:
             # Clean up the Catalyst Center client connection
-            if hasattr(self, "client"):
+            if self.client is not None:  # MANDATORY: never use hasattr()
                 loop.run_until_complete(self.client.aclose())
             loop.close()