"""Local executor for direct HTTP execution of connector operations."""

from __future__ import annotations

import asyncio
import inspect
import logging
import os
import re
import time
from collections.abc import AsyncIterator
from typing import Any, Protocol
from urllib.parse import quote

from jinja2 import Environment, StrictUndefined
from jsonpath_ng import parse as parse_jsonpath
from opentelemetry import trace

from ..auth_template import apply_auth_mapping
from ..connector_model_loader import load_connector_model
from ..constants import (
    DEFAULT_MAX_CONNECTIONS,
    DEFAULT_MAX_KEEPALIVE_CONNECTIONS,
)
from ..http_client import HTTPClient, TokenRefreshCallback
from ..logging import NullLogger, RequestLogger
from ..observability import ObservabilitySession
from ..schema.extensions import RetryConfig
from ..secrets import SecretStr
from ..telemetry import SegmentTracker
from ..types import (
    Action,
    AuthConfig,
    AuthOption,
    ConnectorModel,
    EndpointDefinition,
    EntityDefinition,
)

from .models import (
    ActionNotSupportedError,
    EntityNotFoundError,
    ExecutionConfig,
    ExecutionResult,
    ExecutorError,
    InvalidParameterError,
    MissingParameterError,
    StandardExecuteResult,
)


class _OperationContext:
    """Shared context for operation handlers."""

    def __init__(self, executor: LocalExecutor):
        self.executor = executor
        self.http_client = executor.http_client
        self.tracker = executor.tracker
        self.session = executor.session
        self.logger = executor.logger
        self.entity_index = executor._entity_index
        self.operation_index = executor._operation_index
        # Bind helper methods
        self.build_path = executor._build_path
        self.extract_query_params = executor._extract_query_params
        self.extract_body = executor._extract_body
        self.build_request_body = executor._build_request_body
        self.determine_request_format = executor._determine_request_format
        self.validate_required_body_fields = executor._validate_required_body_fields
        self.extract_records = executor._extract_records


class _OperationHandler(Protocol):
    """Protocol for operation handlers."""

    def can_handle(self, action: Action) -> bool:
        """Check if this handler can handle the given action."""
        ...

    async def execute_operation(
        self,
        entity: str,
        action: Action,
        params: dict[str, Any],
    ) -> StandardExecuteResult | AsyncIterator[bytes]:
        """Execute the operation and return result.

        Returns:
            StandardExecuteResult for standard operations (GET, LIST, CREATE, etc.)
            AsyncIterator[bytes] for download operations
        """
        ...


class LocalExecutor:
    """Async executor for Entity×Action operations with direct HTTP execution.

    This is the "local mode" executor that makes direct HTTP calls to external APIs.
    It performs local entity/action lookups, validation, and request building.

    Implements ExecutorProtocol.
    """

    def __init__(
        self,
        config_path: str | None = None,
        model: ConnectorModel | None = None,
        secrets: dict[str, SecretStr] | None = None,
        auth_config: dict[str, SecretStr] | None = None,
        auth_scheme: str | None = None,
        enable_logging: bool = False,
        log_file: str | None = None,
        execution_context: str | None = None,
        max_connections: int = DEFAULT_MAX_CONNECTIONS,
        max_keepalive_connections: int = DEFAULT_MAX_KEEPALIVE_CONNECTIONS,
        max_logs: int | None = 10000,
        config_values: dict[str, str] | None = None,
        on_token_refresh: TokenRefreshCallback = None,
        retry_config: RetryConfig | None = None,
    ):
        """Initialize async executor.

        Args:
            config_path: Path to connector.yaml.
                If neither config_path nor model is provided, an error will be raised.
            model: ConnectorModel object to execute.
            secrets: (Legacy) Auth parameters that bypass x-airbyte-auth-config mapping.
                Directly passed to auth strategies (e.g., {"username": "...", "password": "..."}).
                Cannot be used together with auth_config.
            auth_config: User-facing auth configuration following x-airbyte-auth-config spec.
                Will be transformed via auth_mapping to produce auth parameters.
                Cannot be used together with secrets.
            auth_scheme: (Multi-auth only) Explicit security scheme name to use.
                If None, SDK will auto-select based on provided credentials.
                Example: auth_scheme="githubOAuth"
            enable_logging: Enable request/response logging
            log_file: Path to log file (if enable_logging=True)
            execution_context: Execution context (mcp, direct, blessed, agent)
            max_connections: Maximum number of concurrent connections
            max_keepalive_connections: Maximum number of keepalive connections
            max_logs: Maximum number of logs to keep in memory before rotation.
                Set to None for unlimited (not recommended for production).
                Defaults to 10000.
            config_values: Optional dict of config values for server variable substitution
                (e.g., {"subdomain": "acme"} for URLs like https://{subdomain}.api.example.com).
            on_token_refresh: Optional callback function(new_tokens: dict) called when
                OAuth2 tokens are refreshed. Use this to persist updated tokens.
                Can be sync or async. Example: lambda tokens: save_to_db(tokens)
            retry_config: Optional retry configuration override. If provided, overrides
                the connector.yaml x-airbyte-retry-config. If None, uses connector.yaml
                config or SDK defaults.
        """
        # Validate mutual exclusivity of secrets and auth_config
        if secrets is not None and auth_config is not None:
            raise ValueError(
                "Cannot provide both 'secrets' and 'auth_config' parameters. "
                "Use 'auth_config' for user-facing credentials (recommended), "
                "or 'secrets' for direct auth parameters (legacy)."
            )

        # Validate mutual exclusivity of config_path and model
        if config_path is not None and model is not None:
            raise ValueError("Cannot provide both 'config_path' and 'model' parameters.")

        if config_path is None and model is None:
            raise ValueError("Must provide either 'config_path' or 'model' parameter.")

        # Load model from path or use provided model
        if config_path is not None:
            self.model: ConnectorModel = load_connector_model(config_path)
        else:
            self.model: ConnectorModel = model

        self.on_token_refresh = on_token_refresh
        self.config_values = config_values or {}

        # Handle auth selection for multi-auth or single-auth connectors
        user_credentials = auth_config if auth_config is not None else secrets
        selected_auth_config, self.secrets = self._initialize_auth(user_credentials, auth_scheme)

        # Create shared observability session
        self.session = ObservabilitySession(
            connector_name=self.model.name,
            connector_version=getattr(self.model, "version", None),
            execution_context=(execution_context or os.getenv("AIRBYTE_EXECUTION_CONTEXT", "direct")),
        )

        # Initialize telemetry tracker
        self.tracker = SegmentTracker(self.session)
        self.tracker.track_connector_init(connector_version=getattr(self.model, "version", None))

        # Initialize logger
        if enable_logging:
            self.logger = RequestLogger(
                log_file=log_file,
                connector_name=self.model.name,
                max_logs=max_logs,
            )
        else:
            self.logger = NullLogger()

        # Initialize async HTTP client with connection pooling
        self.http_client = HTTPClient(
            base_url=self.model.base_url,
            auth_config=selected_auth_config,
            secrets=self.secrets,
            config_values=self.config_values,
            logger=self.logger,
            max_connections=max_connections,
            max_keepalive_connections=max_keepalive_connections,
            on_token_refresh=on_token_refresh,
            retry_config=retry_config or self.model.retry_config,
        )

        # Build O(1) lookup indexes
        self._entity_index: dict[str, EntityDefinition] = {entity.name: entity for entity in self.model.entities}

        # Build O(1) operation index: (entity, action) -> endpoint
        self._operation_index: dict[tuple[str, Action], Any] = {}
        for entity in self.model.entities:
            for action in entity.actions:
                endpoint = entity.endpoints.get(action)
                if endpoint:
                    self._operation_index[(entity.name, action)] = endpoint

        # Register operation handlers (order matters for can_handle priority)
        op_context = _OperationContext(self)
        self._operation_handlers: list[_OperationHandler] = [
            _DownloadOperationHandler(op_context),
            _StandardOperationHandler(op_context),
        ]

    def _apply_auth_config_mapping(self, user_secrets: dict[str, SecretStr]) -> dict[str, SecretStr]:
        """Apply auth_mapping from x-airbyte-auth-config to transform user secrets.

        This method takes user-provided secrets (e.g., {"api_token": "abc123"}) and
        transforms them into the auth scheme format (e.g., {"username": "abc123", "password": "api_token"})
        using the template mappings defined in x-airbyte-auth-config.

        Args:
            user_secrets: User-provided secrets from config

        Returns:
            Transformed secrets matching the auth scheme requirements
        """
        if not self.model.auth.user_config_spec:
            # No x-airbyte-auth-config defined, use secrets as-is
            return user_secrets

        user_config_spec = self.model.auth.user_config_spec
        auth_mapping = None
        required_fields: list[str] | None = None

        # Check for single option (direct auth_mapping)
        if user_config_spec.auth_mapping:
            auth_mapping = user_config_spec.auth_mapping
            required_fields = user_config_spec.required
        # Check for oneOf (multiple auth options)
        elif user_config_spec.one_of:
            # Find the matching option based on which required fields are present
            for option in user_config_spec.one_of:
                option_required = option.required or []
                if all(field in user_secrets for field in option_required):
                    auth_mapping = option.auth_mapping
                    required_fields = option_required
                    break

        if not auth_mapping:
            # No matching auth_mapping found, use secrets as-is
            return user_secrets

        # If required fields are missing and user provided no credentials,
        # return as-is (allows empty auth for testing or optional auth)
        if required_fields and not user_secrets:
            return user_secrets

        # Convert SecretStr values to plain strings for template processing
        user_config_values = {
            key: (value.get_secret_value() if hasattr(value, "get_secret_value") else str(value)) for key, value in user_secrets.items()
        }

        # Apply the auth_mapping templates, passing required_fields so optional
        # fields that are not provided can be skipped
        mapped_values = apply_auth_mapping(auth_mapping, user_config_values, required_fields=required_fields)

        # Convert back to SecretStr
        mapped_secrets = {key: SecretStr(value) for key, value in mapped_values.items()}

        return mapped_secrets

    def _initialize_auth(
        self,
        user_credentials: dict[str, SecretStr] | None,
        explicit_scheme: str | None,
    ) -> tuple[AuthConfig, dict[str, SecretStr] | None]:
        """Initialize authentication for single or multi-auth connectors.

        Handles both legacy single-auth and new multi-auth connectors.
        For multi-auth, the auth scheme can be explicitly provided or inferred
        from the provided credentials by matching against each scheme's required fields.

        Args:
            user_credentials: User-provided credentials (auth_config or secrets)
            explicit_scheme: Explicit scheme name for multi-auth (optional, will be
                inferred from credentials if not provided)

        Returns:
            Tuple of (selected AuthConfig for HTTPClient, transformed secrets)

        Raises:
            ValueError: If multi-auth connector can't determine which scheme to use
        """
        # Multi-auth: explicit scheme selection or inference from credentials
        if self.model.auth.is_multi_auth():
            if not user_credentials:
                available_schemes = [opt.scheme_name for opt in self.model.auth.options]
                raise ValueError(f"Multi-auth connector requires credentials. Available schemes: {available_schemes}")

            # If explicit scheme provided, use it directly
            if explicit_scheme:
                selected_option, transformed_secrets = self._select_auth_option(user_credentials, explicit_scheme)
            else:
                # Infer auth scheme from provided credentials
                selected_option, transformed_secrets = self._infer_auth_scheme(user_credentials)

            # Convert AuthOption to single-auth AuthConfig for HTTPClient
            selected_auth_config = AuthConfig(
                type=selected_option.type,
                config=selected_option.config,
                user_config_spec=None,  # Not needed by HTTPClient
            )

            return (selected_auth_config, transformed_secrets)

        # Single-auth: use existing logic
        if user_credentials is not None:
            # Apply mapping if this is auth_config (not legacy secrets)
            transformed_secrets = self._apply_auth_config_mapping(user_credentials)
        else:
            transformed_secrets = None

        return (self.model.auth, transformed_secrets)

    def _infer_auth_scheme(
        self,
        user_credentials: dict[str, SecretStr],
    ) -> tuple[AuthOption, dict[str, SecretStr]]:
        """Infer authentication scheme from provided credentials.

        Matches user credentials against each auth option's required fields
        to determine which scheme to use.

        Args:
            user_credentials: User-provided credentials

        Returns:
            Tuple of (inferred AuthOption, transformed secrets)

        Raises:
            ValueError: If no scheme matches, or multiple schemes match
        """
        options = self.model.auth.options
        if not options:
            raise ValueError("No auth options available in multi-auth config")

        # Get the credential keys provided by the user
        provided_keys = set(user_credentials.keys())

        # Find all options where all required fields are present
        matching_options: list[AuthOption] = []
        for option in options:
            if option.user_config_spec and option.user_config_spec.required:
                required_fields = set(option.user_config_spec.required)
                if required_fields.issubset(provided_keys):
                    matching_options.append(option)
            elif not option.user_config_spec or not option.user_config_spec.required:
                # Option has no required fields - it matches any credentials
                matching_options.append(option)

        # Handle matching results
        if len(matching_options) == 0:
            # No matches - provide helpful error message
            scheme_requirements = []
            for opt in options:
                required = opt.user_config_spec.required if opt.user_config_spec and opt.user_config_spec.required else []
                scheme_requirements.append(f"  - {opt.scheme_name}: requires {required}")
            raise ValueError(
                f"Could not infer auth scheme from provided credentials. "
                f"Provided keys: {list(provided_keys)}. "
                f"Available schemes and their required fields:\n" + "\n".join(scheme_requirements)
            )

        if len(matching_options) > 1:
            # Multiple matches - need explicit scheme
            matching_names = [opt.scheme_name for opt in matching_options]
            raise ValueError(
                f"Multiple auth schemes match the provided credentials: {matching_names}. Please specify 'auth_scheme' explicitly to disambiguate."
            )

        # Exactly one match - use it
        selected_option = matching_options[0]
        transformed_secrets = self._apply_auth_mapping_for_option(user_credentials, selected_option)
        return (selected_option, transformed_secrets)

    def _select_auth_option(
        self,
        user_credentials: dict[str, SecretStr],
        scheme_name: str,
    ) -> tuple[AuthOption, dict[str, SecretStr]]:
        """Select authentication option by explicit scheme name.

        Args:
            user_credentials: User-provided credentials
            scheme_name: Explicit scheme name (e.g., "githubOAuth")

        Returns:
            Tuple of (selected AuthOption, transformed secrets)

        Raises:
            ValueError: If scheme not found
        """
        options = self.model.auth.options
        if not options:
            raise ValueError("No auth options available in multi-auth config")

        # Find matching scheme
        for option in options:
            if option.scheme_name == scheme_name:
                transformed_secrets = self._apply_auth_mapping_for_option(user_credentials, option)
                return (option, transformed_secrets)

        # Scheme not found
        available = [opt.scheme_name for opt in options]
        raise ValueError(f"Auth scheme '{scheme_name}' not found. Available schemes: {available}")

    def _apply_auth_mapping_for_option(
        self,
        user_credentials: dict[str, SecretStr],
        option: AuthOption,
    ) -> dict[str, SecretStr]:
        """Apply auth mapping for a specific auth option.

        Transforms user credentials using the option's auth_mapping templates.

        Args:
            user_credentials: User-provided credentials
            option: AuthOption to apply

        Returns:
            Transformed secrets after applying auth_mapping

        Raises:
            ValueError: If required fields are missing or mapping fails
        """
        if not option.user_config_spec:
            # No mapping defined, use credentials as-is
            return user_credentials

        # Extract auth_mapping and required fields
        user_config_spec = option.user_config_spec
        auth_mapping = user_config_spec.auth_mapping
        required_fields = user_config_spec.required

        if not auth_mapping:
            raise ValueError(f"No auth_mapping found for scheme '{option.scheme_name}'")

        # Convert SecretStr to plain strings for template processing
        user_config_values = {
            key: (value.get_secret_value() if hasattr(value, "get_secret_value") else str(value)) for key, value in user_credentials.items()
        }

        # Apply the auth_mapping templates
        mapped_values = apply_auth_mapping(auth_mapping, user_config_values, required_fields=required_fields)

        # Convert back to SecretStr
        return {key: SecretStr(value) for key, value in mapped_values.items()}

    async def execute(self, config: ExecutionConfig) -> ExecutionResult:
        """Execute connector operation using handler pattern.

        Args:
            config: Execution configuration (entity, action, params)

        Returns:
            ExecutionResult with success/failure status and data

        Example:
            config = ExecutionConfig(
                entity="customers",
                action="list",
                params={"limit": 10}
            )
            result = await executor.execute(config)
            if result.success:
                print(result.data)
        """
        try:
            # Check for hosted-only actions before converting to Action enum
            if config.action == "search":
                raise NotImplementedError(
                    "search is only available in hosted execution mode. "
                    "Initialize the connector with external_user_id, airbyte_client_id, "
                    "and airbyte_client_secret to use this feature."
                )

            # Convert config to internal format
            action = Action(config.action) if isinstance(config.action, str) else config.action
            params = config.params or {}

            # Dispatch to handler (handlers handle telemetry internally)
            handler = next((h for h in self._operation_handlers if h.can_handle(action)), None)
            if not handler:
                raise ExecutorError(f"No handler registered for action '{action.value}'.")

            # Execute handler
            result = handler.execute_operation(config.entity, action, params)

            # Check if it's an async generator (download) or awaitable (standard)
            if inspect.isasyncgen(result):
                # Download operation: return generator directly
                return ExecutionResult(
                    success=True,
                    data=result,
                    error=None,
                    meta=None,
                )
            else:
                # Standard operation: await and extract data and metadata
                handler_result = await result
                return ExecutionResult(
                    success=True,
                    data=handler_result.data,
                    error=None,
                    meta=handler_result.metadata,
                )

        except (
            EntityNotFoundError,
            ActionNotSupportedError,
            MissingParameterError,
            InvalidParameterError,
        ) as e:
            # These are "expected" execution errors - return them in ExecutionResult
            return ExecutionResult(success=False, data={}, error=str(e))

    async def _execute_operation(
        self,
        entity: str,
        action: str | Action,
        params: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        """Internal method: Execute an action on an entity asynchronously.

        This method now delegates to the appropriate handler and extracts just the data.
        External code should use execute(config) instead for full ExecutionResult with metadata.

        Args:
            entity: Entity name (e.g., "Customer")
            action: Action to execute (e.g., "get" or Action.GET)
            params: Parameters for the operation
                - For GET: {"id": "cus_123"} for path params
                - For LIST: {"limit": 10} for query params
                - For CREATE/UPDATE: {"email": "...", "name": "..."} for body

        Returns:
            API response as dictionary

        Raises:
            ValueError: If entity or action not found
            HTTPClientError: If API request fails
        """
        params = params or {}
        action = Action(action) if isinstance(action, str) else action

        # Delegate to the appropriate handler
        handler = next((h for h in self._operation_handlers if h.can_handle(action)), None)
        if not handler:
            raise ExecutorError(f"No handler registered for action '{action.value}'.")

        # Execute handler and extract just the data for backward compatibility
        result = await handler.execute_operation(entity, action, params)
        if isinstance(result, StandardExecuteResult):
            return result.data
        else:
            # Download operation returns AsyncIterator directly
            return result

    async def execute_batch(self, operations: list[tuple[str, str | Action, dict[str, Any] | None]]) -> list[dict[str, Any] | AsyncIterator[bytes]]:
        """Execute multiple operations concurrently (supports all action types including download).

        Args:
            operations: List of (entity, action, params) tuples

        Returns:
            List of responses in the same order as operations.
            Standard operations return dict[str, Any].
            Download operations return AsyncIterator[bytes].

        Raises:
            ValueError: If any entity or action not found
            HTTPClientError: If any API request fails

        Example:
            results = await executor.execute_batch([
                ("Customer", "list", {"limit": 10}),
                ("Customer", "get", {"id": "cus_123"}),
                ("attachments", "download", {"id": "att_456"}),
            ])
        """
        # Build tasks by dispatching directly to handlers
        tasks = []
        for entity, action, params in operations:
            # Convert action to Action enum if needed
            action = Action(action) if isinstance(action, str) else action
            params = params or {}

            # Find appropriate handler
            handler = next((h for h in self._operation_handlers if h.can_handle(action)), None)
            if not handler:
                raise ExecutorError(f"No handler registered for action '{action.value}'.")

            # Call handler directly (exceptions propagate naturally)
            tasks.append(handler.execute_operation(entity, action, params))

        # Execute all tasks concurrently - exceptions propagate via asyncio.gather
        results = await asyncio.gather(*tasks)

        # Extract data from results
        extracted_results = []
        for result in results:
            if isinstance(result, StandardExecuteResult):
                # Standard operation: extract data
                extracted_results.append(result.data)
            else:
                # Download operation: return iterator as-is
                extracted_results.append(result)

        return extracted_results

    def _build_path(self, path_template: str, params: dict[str, Any]) -> str:
        """Build path by replacing {param} placeholders with URL-encoded values.

        Args:
            path_template: Path with placeholders (e.g., /v1/customers/{id})
            params: Parameters containing values for placeholders

        Returns:
            Completed path with URL-encoded values (e.g., /v1/customers/cus_123)

        Raises:
            MissingParameterError: If required path parameter is missing
        """
        placeholders = re.findall(r"\{(\w+)\}", path_template)

        path = path_template
        for placeholder in placeholders:
            if placeholder not in params:
                raise MissingParameterError(
                    f"Missing required path parameter '{placeholder}' for path '{path_template}'. Provided parameters: {list(params.keys())}"
                )

            # Validate parameter value is not None or empty string
            value = params[placeholder]
            if value is None or (isinstance(value, str) and value.strip() == ""):
                raise InvalidParameterError(f"Path parameter '{placeholder}' cannot be None or empty string")

            encoded_value = quote(str(value), safe="")
            path = path.replace(f"{{{placeholder}}}", encoded_value)

        return path

    def _extract_query_params(self, allowed_params: list[str], params: dict[str, Any]) -> dict[str, Any]:
        """Extract query parameters from params.

        Args:
            allowed_params: List of allowed query parameter names
            params: All parameters

        Returns:
            Dictionary of query parameters
        """
        return {key: value for key, value in params.items() if key in allowed_params}

    def _extract_body(self, allowed_fields: list[str], params: dict[str, Any]) -> dict[str, Any]:
        """Extract body fields from params, filtering out None values.

        Args:
            allowed_fields: List of allowed body field names
            params: All parameters

        Returns:
            Dictionary of body fields with None values filtered out
        """
        return {key: value for key, value in params.items() if key in allowed_fields and value is not None}

    def _serialize_deep_object_params(self, params: dict[str, Any], deep_object_param_names: list[str]) -> dict[str, Any]:
        """Serialize deepObject parameters to bracket notation format.

        Converts nested dict parameters to the deepObject format expected by APIs
        like Stripe. For example:
        - Input: {'created': {'gte': 123, 'lte': 456}}
        - Output: {'created[gte]': 123, 'created[lte]': 456}

        Args:
            params: Query parameters dict (may contain nested dicts)
            deep_object_param_names: List of parameter names that use deepObject style

        Returns:
            Dictionary with deepObject params serialized to bracket notation
        """
        serialized = {}

        for key, value in params.items():
            if key in deep_object_param_names and isinstance(value, dict):
                # Serialize nested dict to bracket notation
                for subkey, subvalue in value.items():
                    if subvalue is not None:  # Skip None values
                        serialized[f"{key}[{subkey}]"] = subvalue
            else:
                # Keep non-deepObject params as-is (already validated by _extract_query_params)
                serialized[key] = value

        return serialized

    @staticmethod
    def _extract_download_url(
        response: dict[str, Any],
        file_field: str,
        entity: str,
    ) -> str:
        """Extract download URL from metadata response using x-airbyte-file-url.

        Supports both simple dot notation (e.g., "article.content_url") and array
        indexing with bracket notation (e.g., "calls[0].media.audioUrl").

        Args:
            response: Metadata response containing file reference
            file_field: JSON path to file URL field (from x-airbyte-file-url)
            entity: Entity name (for error messages)

        Returns:
            Extracted file URL

        Raises:
            ExecutorError: If file field not found or invalid
        """
        # Navigate nested path (e.g., "article_attachment.content_url" or "calls[0].media.audioUrl")
        parts = file_field.split(".")
        current = response

        for i, part in enumerate(parts):
            # Check if part has array indexing (e.g., "calls[0]")
            array_match = re.match(r"^(\w+)\[(\d+)\]$", part)

            if array_match:
                field_name = array_match.group(1)
                index = int(array_match.group(2))

                # Navigate to the field
                if not isinstance(current, dict):
                    raise ExecutorError(
                        f"Cannot extract download URL for {entity}: Expected dict at '{'.'.join(parts[:i])}', got {type(current).__name__}"
                    )

                if field_name not in current:
                    raise ExecutorError(
                        f"Cannot extract download URL for {entity}: "
                        f"Field '{field_name}' not found in response. Available fields: {list(current.keys())}"
                    )

                # Get the array
                array_value = current[field_name]
                if not isinstance(array_value, list):
                    raise ExecutorError(
                        f"Cannot extract download URL for {entity}: Expected list at '{field_name}', got {type(array_value).__name__}"
                    )

                # Check index bounds
                if index >= len(array_value):
                    raise ExecutorError(
                        f"Cannot extract download URL for {entity}: Index {index} out of bounds for '{field_name}' (length: {len(array_value)})"
                    )

                current = array_value[index]
            else:
                # Regular dict navigation
                if not isinstance(current, dict):
                    raise ExecutorError(
                        f"Cannot extract download URL for {entity}: Expected dict at '{'.'.join(parts[:i])}', got {type(current).__name__}"
                    )

                if part not in current:
                    raise ExecutorError(
                        f"Cannot extract download URL for {entity}: Field '{part}' not found in response. Available fields: {list(current.keys())}"
                    )

                current = current[part]

        if not isinstance(current, str):
            raise ExecutorError(f"Cannot extract download URL for {entity}: Expected string at '{file_field}', got {type(current).__name__}")

        return current

    @staticmethod
    def _substitute_file_field_params(
        file_field: str,
        params: dict[str, Any],
    ) -> str:
        """Substitute template variables in file_field with parameter values.

        Uses Jinja2 with custom delimiters to support OpenAPI-style syntax like
        "attachments[{index}].url" where {index} is replaced with params["index"].

        Args:
            file_field: File field path with optional template variables
            params: Parameters from execute() call

        Returns:
            File field with template variables substituted

        Example:
            >>> _substitute_file_field_params("attachments[{attachment_index}].url", {"attachment_index": 0})
            "attachments[0].url"
        """

        # Use custom delimiters to match OpenAPI path parameter syntax {var}
        # StrictUndefined raises clear error if a template variable is missing
        env = Environment(
            variable_start_string="{",
            variable_end_string="}",
            undefined=StrictUndefined,
        )
        template = env.from_string(file_field)
        return template.render(params)

    def _build_request_body(self, endpoint: EndpointDefinition, params: dict[str, Any]) -> dict[str, Any] | None:
        """Build request body (GraphQL or standard).

        Args:
            endpoint: Endpoint definition
            params: Parameters from execute() call

        Returns:
            Request body dict or None if no body needed
        """
        if endpoint.graphql_body:
            # Extract defaults from query_params_schema for GraphQL variable interpolation
            param_defaults = {name: schema.get("default") for name, schema in endpoint.query_params_schema.items() if "default" in schema}
            return self._build_graphql_body(endpoint.graphql_body, params, param_defaults)
        elif endpoint.body_fields:
            return self._extract_body(endpoint.body_fields, params)
        return None

    def _flatten_form_data(self, data: dict[str, Any], parent_key: str = "") -> dict[str, Any]:
        """Flatten nested dict/list structures into bracket notation for form encoding.

        Stripe and similar APIs require nested arrays/objects to be encoded using bracket
        notation when using application/x-www-form-urlencoded content type.

        Args:
            data: Nested dict with arrays/objects to flatten
            parent_key: Parent key for nested structures (used in recursion)

        Returns:
            Flattened dict with bracket notation keys

        Examples:
            >>> _flatten_form_data({"items": [{"price": "p1", "qty": 1}]})
            {"items[0][price]": "p1", "items[0][qty]": 1}

            >>> _flatten_form_data({"customer": "cus_123", "metadata": {"key": "value"}})
            {"customer": "cus_123", "metadata[key]": "value"}
        """
        flattened = {}

        for key, value in data.items():
            new_key = f"{parent_key}[{key}]" if parent_key else key

            if isinstance(value, dict):
                # Recursively flatten nested dicts
                flattened.update(self._flatten_form_data(value, new_key))
            elif isinstance(value, list):
                # Flatten arrays with indexed bracket notation
                for i, item in enumerate(value):
                    indexed_key = f"{new_key}[{i}]"
                    if isinstance(item, dict):
                        # Nested dict in array - recurse
                        flattened.update(self._flatten_form_data(item, indexed_key))
                    elif isinstance(item, list):
                        # Nested list in array - recurse
                        flattened.update(self._flatten_form_data({str(i): item}, new_key))
                    else:
                        # Primitive value in array
                        flattened[indexed_key] = item
            else:
                # Primitive value - add directly
                flattened[new_key] = value

        return flattened

    def _determine_request_format(self, endpoint: EndpointDefinition, body: dict[str, Any] | None) -> dict[str, Any]:
        """Determine json/data parameters for HTTP request.

        GraphQL always uses JSON, regardless of content_type setting.
        For form-encoded requests, nested structures are flattened into bracket notation.

        Args:
            endpoint: Endpoint definition
            body: Request body dict or None

        Returns:
            Dict with 'json' and/or 'data' keys for http_client.request()
        """
        if not body:
            return {}

        is_graphql = endpoint.graphql_body is not None

        if is_graphql or endpoint.content_type.value == "application/json":
            return {"json": body}
        elif endpoint.content_type.value == "application/x-www-form-urlencoded":
            # Flatten nested structures for form encoding
            flattened_body = self._flatten_form_data(body)
            return {"data": flattened_body}

        return {}

    def _process_graphql_fields(self, query: str, graphql_config: dict[str, Any], params: dict[str, Any]) -> str:
        """Process GraphQL query field selection.

        Handles:
        - Dynamic fields from params['fields']
        - Default fields from config
        - String vs list format for default_fields

        Args:
            query: GraphQL query string (may contain {{ fields }} placeholder)
            graphql_config: GraphQL configuration dict
            params: Parameters from execute() call

        Returns:
            Processed query string with fields injected
        """
        if "{{ fields }}" not in query:
            return query

        # Check for explicit fields parameter
        if "fields" in params and params["fields"]:
            return self._inject_graphql_fields(query, params["fields"])

        # Use default fields if available
        if "default_fields" not in graphql_config:
            return query  # Placeholder remains (could raise error in the future)

        default_fields = graphql_config["default_fields"]
        if isinstance(default_fields, str):
            # Already in GraphQL format - direct replacement
            return query.replace("{{ fields }}", default_fields)
        elif isinstance(default_fields, list):
            # List format - convert to GraphQL
            return self._inject_graphql_fields(query, default_fields)

        return query

    def _build_graphql_body(
        self,
        graphql_config: dict[str, Any],
        params: dict[str, Any],
        param_defaults: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        """Build GraphQL request body with variable substitution and field selection.

        Args:
            graphql_config: GraphQL configuration from x-airbyte-body-type extension
            params: Parameters from execute() call
            param_defaults: Default values for params from query_params_schema

        Returns:
            GraphQL request body: {"query": "...", "variables": {...}}
        """
        query = graphql_config["query"]

        # Process field selection (dynamic fields or default fields)
        query = self._process_graphql_fields(query, graphql_config, params)

        body = {"query": query}

        # Substitute variables from params
        if "variables" in graphql_config and graphql_config["variables"]:
            body["variables"] = self._interpolate_variables(graphql_config["variables"], params, param_defaults)

        # Add operation name if specified
        if "operationName" in graphql_config:
            body["operationName"] = graphql_config["operationName"]

        return body

    def _convert_nested_field_to_graphql(self, field: str) -> str:
        """Convert dot-notation field to GraphQL field selection.

        Example: "primaryLanguage.name" -> "primaryLanguage { name }"

        Args:
            field: Field name in dot notation (e.g., "primaryLanguage.name")

        Returns:
            GraphQL field selection string
        """
        if "." not in field:
            return field

        parts = field.split(".")
        result = parts[0]
        for part in parts[1:]:
            result += f" {{ {part}"
        result += " }" * (len(parts) - 1)
        return result

    def _inject_graphql_fields(self, query: str, fields: list[str]) -> str:
        """Inject field selection into GraphQL query.

        Replaces field selection placeholders ({{ fields }}) with actual field list.
        Supports nested fields using dot notation (e.g., "primaryLanguage.name").

        Args:
            query: GraphQL query string (may contain {{ fields }} placeholder)
            fields: List of fields to select (e.g., ["id", "name", "primaryLanguage.name"])

        Returns:
            GraphQL query with fields injected

        Example:
            Input query: "query { repository { {{ fields }} } }"
            Fields: ["id", "name", "primaryLanguage { name }"]
            Output: "query { repository { id name primaryLanguage { name } } }"
        """
        # Check if query has field placeholder
        if "{{ fields }}" not in query:
            # No placeholder - return query as-is (backward compatible)
            return query

        # Convert field list to GraphQL field selection
        graphql_fields = [self._convert_nested_field_to_graphql(field) for field in fields]

        # Replace placeholder with field list
        fields_str = " ".join(graphql_fields)
        return query.replace("{{ fields }}", fields_str)

    def _interpolate_variables(
        self,
        variables: dict[str, Any],
        params: dict[str, Any],
        param_defaults: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        """Recursively interpolate variables using params.

        Preserves types (doesn't stringify everything).

        Supports:
        - Direct replacement: "{{ owner }}" → params["owner"] (preserves type)
        - Nested objects: {"input": {"name": "{{ name }}"}}
        - Arrays: [{"id": "{{ id }}"}]
        - Default values: "{{ per_page }}" → param_defaults["per_page"] if not in params
        - Unsubstituted placeholders: "{{ states }}" → None (for optional params without defaults)

        Args:
            variables: Variables dict with template placeholders
            params: Parameters to substitute
            param_defaults: Default values for params from query_params_schema

        Returns:
            Interpolated variables dict with types preserved
        """
        defaults = param_defaults or {}

        def interpolate_value(value: Any) -> Any:
            if isinstance(value, str):
                # Check for exact template match (preserve type)
                for key, param_value in params.items():
                    placeholder = f"{{{{ {key} }}}}"
                    if value == placeholder:
                        return param_value  # Return actual value (int, list, etc.)
                    elif placeholder in value:
                        # Partial match - do string replacement
                        value = value.replace(placeholder, str(param_value))

                # Check if any unsubstituted placeholders remain
                if re.search(r"\{\{\s*\w+\s*\}\}", value):
                    # Extract placeholder name and check for default value
                    match = re.search(r"\{\{\s*(\w+)\s*\}\}", value)
                    if match:
                        param_name = match.group(1)
                        if param_name in defaults:
                            # Use default value (preserves type)
                            return defaults[param_name]
                    # No default found - return None (for optional params)
                    return None

                return value
            elif isinstance(value, dict):
                return {k: interpolate_value(v) for k, v in value.items()}
            elif isinstance(value, list):
                return [interpolate_value(item) for item in value]
            else:
                return value

        return interpolate_value(variables)

    def _wrap_primitives(self, data: Any) -> dict[str, Any] | list[dict[str, Any]] | None:
        """Wrap primitive values in dict format for consistent response structure.

        Transforms primitive API responses into dict format so downstream code
        can always expect dict-based data structures.

        Args:
            data: Response data (could be primitive, list, dict, or None)

        Returns:
            - If data is a primitive (str, int, float, bool): {"value": data}
            - If data is a list: wraps all non-dict elements as {"value": item}
            - If data is already a dict or list of dicts: unchanged
            - If data is None: None

        Examples:
            >>> executor._wrap_primitives(42)
            {"value": 42}
            >>> executor._wrap_primitives([1, 2, 3])
            [{"value": 1}, {"value": 2}, {"value": 3}]
            >>> executor._wrap_primitives([1, {"id": 2}, 3])
            [{"value": 1}, {"id": 2}, {"value": 3}]
            >>> executor._wrap_primitives([[1, 2], 3])
            [{"value": [1, 2]}, {"value": 3}]
            >>> executor._wrap_primitives({"id": 1})
            {"id": 1}  # unchanged
        """
        if data is None:
            return None

        # Handle primitive scalars
        if isinstance(data, (bool, str, int, float)):
            return {"value": data}

        # Handle lists - wrap non-dict elements
        if isinstance(data, list):
            if not data:
                return []  # Empty list unchanged

            wrapped = []
            for item in data:
                if isinstance(item, dict):
                    wrapped.append(item)
                else:
                    wrapped.append({"value": item})
            return wrapped

        # Dict - return unchanged
        if isinstance(data, dict):
            return data

        # Unknown type - wrap for safety
        return {"value": data}

    def _extract_records(
        self,
        response_data: Any,
        endpoint: EndpointDefinition,
    ) -> dict[str, Any] | list[dict[str, Any]] | None:
        """Extract records from response using record extractor.

        Type inference based on action:
        - list, search: Returns array ([] if not found)
        - get, create, update, delete: Returns single record (None if not found)

        Automatically wraps primitive values (int, str, float, bool) in {"value": primitive}
        format to ensure consistent dict-based responses for downstream code.

        Args:
            response_data: Full API response (can be dict, list, primitive, or None)
            endpoint: Endpoint with optional record extractor and action

        Returns:
            - Extracted data if extractor configured and path found
            - [] or None if path not found (based on action)
            - Original response if no extractor configured or on error
            - Primitives are wrapped as {"value": primitive}
        """
        # Check if endpoint has record extractor
        extractor = endpoint.record_extractor
        if not extractor:
            return self._wrap_primitives(response_data)

        # Determine if this action returns array or single record
        action = endpoint.action
        if not action:
            return self._wrap_primitives(response_data)

        is_array_action = action in (Action.LIST, Action.API_SEARCH)

        try:
            # Parse and apply JSONPath expression
            jsonpath_expr = parse_jsonpath(extractor)
            matches = [match.value for match in jsonpath_expr.find(response_data)]

            if not matches:
                # Path not found - return empty based on action
                return [] if is_array_action else None

            # Return extracted data with primitive wrapping
            if is_array_action:
                # For array actions, return the array (or list of matches)
                result = matches[0] if len(matches) == 1 else matches
            else:
                # For single record actions, return first match
                result = matches[0]

            return self._wrap_primitives(result)

        except Exception as e:
            logging.warning(f"Failed to apply record extractor '{extractor}': {e}. Returning original response.")
            return self._wrap_primitives(response_data)

    def _extract_metadata(
        self,
        response_data: dict[str, Any],
        endpoint: EndpointDefinition,
    ) -> dict[str, Any] | None:
        """Extract metadata from response using meta extractor.

        Each field in meta_extractor dict is independently extracted using JSONPath.
        Missing or invalid paths result in None for that field (no crash).

        Args:
            response_data: Full API response (before record extraction)
            endpoint: Endpoint with optional meta extractor configuration

        Returns:
            - Dict of extracted metadata if extractor configured
            - None if no extractor configured
            - Dict with None values for failed extractions

        Example:
            meta_extractor = {
                "pagination": "$.records",
                "request_id": "$.requestId"
            }
            Returns: {
                "pagination": {"cursor": "abc", "total": 100},
                "request_id": "xyz123"
            }
        """
        # Check if endpoint has meta extractor
        if endpoint.meta_extractor is None:
            return None

        extracted_meta: dict[str, Any] = {}

        # Extract each field independently
        for field_name, jsonpath_expr_str in endpoint.meta_extractor.items():
            try:
                # Parse and apply JSONPath expression
                jsonpath_expr = parse_jsonpath(jsonpath_expr_str)
                matches = [match.value for match in jsonpath_expr.find(response_data)]

                if matches:
                    # Return first match (most common case)
                    extracted_meta[field_name] = matches[0]
                else:
                    # Path not found - set to None
                    extracted_meta[field_name] = None

            except Exception as e:
                # Log error but continue with other fields
                logging.warning(f"Failed to apply meta extractor for field '{field_name}' with path '{jsonpath_expr_str}': {e}. Setting to None.")
                extracted_meta[field_name] = None

        return extracted_meta

    def _validate_required_body_fields(self, endpoint: Any, params: dict[str, Any], action: Action, entity: str) -> None:
        """Validate that required body fields are present for CREATE/UPDATE operations.

        Args:
            endpoint: Endpoint definition
            params: Parameters provided
            action: Operation action
            entity: Entity name

        Raises:
            MissingParameterError: If required body fields are missing
        """
        # Only validate for operations that typically have required body fields
        if action not in (Action.CREATE, Action.UPDATE):
            return

        # Get the request schema to find truly required fields
        request_schema = endpoint.request_schema
        if not request_schema:
            return

        # Only validate fields explicitly marked as required in the schema
        required_fields = request_schema.get("required", [])
        missing_fields = [field for field in required_fields if field not in params]

        if missing_fields:
            raise MissingParameterError(
                f"Missing required body fields for {entity}.{action.value}: {missing_fields}. Provided parameters: {list(params.keys())}"
            )

    async def close(self):
        """Close async HTTP client and logger."""
        self.tracker.track_session_end()
        await self.http_client.close()
        self.logger.close()

    async def __aenter__(self):
        """Async context manager entry."""
        return self

    async def __aexit__(self, exc_type, exc_val, exc_tb):
        """Async context manager exit."""
        await self.close()


# =============================================================================
# Operation Handlers
# =============================================================================


class _StandardOperationHandler:
    """Handler for standard REST operations (GET, LIST, CREATE, UPDATE, DELETE, API_SEARCH, AUTHORIZE)."""

    def __init__(self, context: _OperationContext):
        self.ctx = context

    def can_handle(self, action: Action) -> bool:
        """Check if this handler can handle the given action."""
        return action in {
            Action.GET,
            Action.LIST,
            Action.CREATE,
            Action.UPDATE,
            Action.DELETE,
            Action.API_SEARCH,
            Action.AUTHORIZE,
        }

    async def execute_operation(self, entity: str, action: Action, params: dict[str, Any]) -> StandardExecuteResult:
        """Execute standard REST operation with full telemetry and error handling."""
        tracer = trace.get_tracer("airbyte.connector-sdk.executor.local")

        with tracer.start_as_current_span("airbyte.local_executor.execute_operation") as span:
            # Add span attributes
            span.set_attribute("connector.name", self.ctx.executor.model.name)
            span.set_attribute("connector.entity", entity)
            span.set_attribute("connector.action", action.value)
            if params:
                span.set_attribute("connector.param_keys", list(params.keys()))

            # Increment operation counter
            self.ctx.session.increment_operations()

            # Track operation timing and status
            start_time = time.time()
            error_type = None
            status_code = None

            try:
                # O(1) entity lookup
                entity_def = self.ctx.entity_index.get(entity)
                if not entity_def:
                    available_entities = list(self.ctx.entity_index.keys())
                    raise EntityNotFoundError(f"Entity '{entity}' not found in connector. Available entities: {available_entities}")

                # Check if action is supported
                if action not in entity_def.actions:
                    supported_actions = [a.value for a in entity_def.actions]
                    raise ActionNotSupportedError(
                        f"Action '{action.value}' not supported for entity '{entity}'. Supported actions: {supported_actions}"
                    )

                # O(1) operation lookup
                endpoint = self.ctx.operation_index.get((entity, action))
                if not endpoint:
                    raise ExecutorError(f"No endpoint defined for {entity}.{action.value}. This is a configuration error.")

                # Validate required body fields for CREATE/UPDATE operations
                self.ctx.validate_required_body_fields(endpoint, params, action, entity)

                # Build request parameters
                # Use path_override if available, otherwise use the OpenAPI path
                actual_path = endpoint.path_override.path if endpoint.path_override else endpoint.path
                path = self.ctx.build_path(actual_path, params)
                query_params = self.ctx.extract_query_params(endpoint.query_params, params)

                # Serialize deepObject parameters to bracket notation
                if endpoint.deep_object_params:
                    query_params = self.ctx.executor._serialize_deep_object_params(query_params, endpoint.deep_object_params)

                # Build request body (GraphQL or standard)
                body = self.ctx.build_request_body(endpoint, params)

                # Determine request format (json/data parameters)
                request_kwargs = self.ctx.determine_request_format(endpoint, body)

                # Execute async HTTP request
                response = await self.ctx.http_client.request(
                    method=endpoint.method,
                    path=path,
                    params=query_params if query_params else None,
                    json=request_kwargs.get("json"),
                    data=request_kwargs.get("data"),
                )

                # Extract metadata from original response (before record extraction)
                metadata = self.ctx.executor._extract_metadata(response, endpoint)

                # Extract records if extractor configured
                response = self.ctx.extract_records(response, endpoint)

                # Assume success with 200 status code if no exception raised
                status_code = 200

                # Mark span as successful
                span.set_attribute("connector.success", True)
                span.set_attribute("http.status_code", status_code)

                # Return StandardExecuteResult with data and metadata
                return StandardExecuteResult(data=response, metadata=metadata)

            except (EntityNotFoundError, ActionNotSupportedError) as e:
                # Validation errors - record in span
                error_type = type(e).__name__
                span.set_attribute("connector.success", False)
                span.set_attribute("connector.error_type", error_type)
                span.record_exception(e)
                raise

            except Exception as e:
                # Capture error details
                error_type = type(e).__name__

                # Try to get status code from HTTP errors
                if hasattr(e, "response") and hasattr(e.response, "status_code"):
                    status_code = e.response.status_code
                    span.set_attribute("http.status_code", status_code)

                span.set_attribute("connector.success", False)
                span.set_attribute("connector.error_type", error_type)
                span.record_exception(e)
                raise

            finally:
                # Always track operation (success or failure)
                timing_ms = (time.time() - start_time) * 1000
                self.ctx.tracker.track_operation(
                    entity=entity,
                    action=action.value if isinstance(action, Action) else action,
                    status_code=status_code,
                    timing_ms=timing_ms,
                    error_type=error_type,
                )


class _DownloadOperationHandler:
    """Handler for download operations.

    Supports two modes:
    - Two-step (with x-airbyte-file-url): metadata request → extract URL → stream file
    - One-step (without x-airbyte-file-url): stream file directly from endpoint
    """

    def __init__(self, context: _OperationContext):
        self.ctx = context

    def can_handle(self, action: Action) -> bool:
        """Check if this handler can handle the given action."""
        return action == Action.DOWNLOAD

    async def execute_operation(self, entity: str, action: Action, params: dict[str, Any]) -> AsyncIterator[bytes]:
        """Execute download operation (one-step or two-step) with full telemetry."""
        tracer = trace.get_tracer("airbyte.connector-sdk.executor.local")

        with tracer.start_as_current_span("airbyte.local_executor.execute_operation") as span:
            # Add span attributes
            span.set_attribute("connector.name", self.ctx.executor.model.name)
            span.set_attribute("connector.entity", entity)
            span.set_attribute("connector.action", action.value)
            if params:
                span.set_attribute("connector.param_keys", list(params.keys()))

            # Increment operation counter
            self.ctx.session.increment_operations()

            # Track operation timing and status
            start_time = time.time()
            error_type = None
            status_code = None

            try:
                # Look up entity
                entity_def = self.ctx.entity_index.get(entity)
                if not entity_def:
                    raise EntityNotFoundError(f"Entity '{entity}' not found in connector. Available entities: {list(self.ctx.entity_index.keys())}")

                # Look up operation
                operation = self.ctx.operation_index.get((entity, action))
                if not operation:
                    raise ActionNotSupportedError(
                        f"Action '{action.value}' not supported for entity '{entity}'. Supported actions: {[a.value for a in entity_def.actions]}"
                    )

                # Common setup for both download modes
                actual_path = operation.path_override.path if operation.path_override else operation.path
                path = self.ctx.build_path(actual_path, params)
                query_params = self.ctx.extract_query_params(operation.query_params, params)

                # Serialize deepObject parameters to bracket notation
                if operation.deep_object_params:
                    query_params = self.ctx.executor._serialize_deep_object_params(query_params, operation.deep_object_params)

                # Prepare headers (with optional Range support)
                range_header = params.get("range_header")
                headers = {"Accept": "*/*"}
                if range_header is not None:
                    headers["Range"] = range_header

                # Check download mode: two-step (with file_field) or one-step (without)
                file_field = operation.file_field

                if file_field:
                    # Substitute template variables in file_field (e.g., "attachments[{index}].url")
                    file_field = LocalExecutor._substitute_file_field_params(file_field, params)

                if file_field:
                    # Two-step download: metadata → extract URL → stream file
                    # Step 1: Get metadata (standard request)
                    request_body = self.ctx.build_request_body(
                        endpoint=operation,
                        params=params,
                    )
                    request_format = self.ctx.determine_request_format(operation, request_body)
                    self.ctx.validate_required_body_fields(operation, params, action, entity)

                    metadata_response = await self.ctx.http_client.request(
                        method=operation.method,
                        path=path,
                        params=query_params,
                        **request_format,
                    )

                    # Step 2: Extract file URL from metadata
                    file_url = LocalExecutor._extract_download_url(
                        response=metadata_response,
                        file_field=file_field,
                        entity=entity,
                    )

                    # Step 3: Stream file from extracted URL
                    file_response = await self.ctx.http_client.request(
                        method="GET",
                        path=file_url,
                        headers=headers,
                        stream=True,
                    )
                else:
                    # One-step direct download: stream file directly from endpoint
                    file_response = await self.ctx.http_client.request(
                        method=operation.method,
                        path=path,
                        params=query_params,
                        headers=headers,
                        stream=True,
                    )

                # Assume success once we start streaming
                status_code = 200

                # Mark span as successful
                span.set_attribute("connector.success", True)
                span.set_attribute("http.status_code", status_code)

                # Stream file chunks
                default_chunk_size = 8 * 1024 * 1024  # 8 MB
                async for chunk in file_response.original_response.aiter_bytes(chunk_size=default_chunk_size):
                    # Log each chunk for cassette recording
                    self.ctx.logger.log_chunk_fetch(chunk)
                    yield chunk

            except (EntityNotFoundError, ActionNotSupportedError) as e:
                # Validation errors - record in span
                error_type = type(e).__name__
                span.set_attribute("connector.success", False)
                span.set_attribute("connector.error_type", error_type)
                span.record_exception(e)

                # Track the failed operation before re-raising
                timing_ms = (time.time() - start_time) * 1000
                self.ctx.tracker.track_operation(
                    entity=entity,
                    action=action.value,
                    status_code=status_code,
                    timing_ms=timing_ms,
                    error_type=error_type,
                )
                raise

            except Exception as e:
                # Capture error details
                error_type = type(e).__name__

                # Try to get status code from HTTP errors
                if hasattr(e, "response") and hasattr(e.response, "status_code"):
                    status_code = e.response.status_code
                    span.set_attribute("http.status_code", status_code)

                span.set_attribute("connector.success", False)
                span.set_attribute("connector.error_type", error_type)
                span.record_exception(e)

                # Track the failed operation before re-raising
                timing_ms = (time.time() - start_time) * 1000
                self.ctx.tracker.track_operation(
                    entity=entity,
                    action=action.value,
                    status_code=status_code,
                    timing_ms=timing_ms,
                    error_type=error_type,
                )
                raise

            finally:
                # Track successful operation (if no exception was raised)
                # Note: For generators, this runs after all chunks are yielded
                if error_type is None:
                    timing_ms = (time.time() - start_time) * 1000
                    self.ctx.tracker.track_operation(
                        entity=entity,
                        action=action.value,
                        status_code=status_code,
                        timing_ms=timing_ms,
                        error_type=None,
                    )
