manta-common-core 0.5b0.dev3__py3-none-any.whl

manta_common/base_client.py

@@ -0,0 +1,892 @@
+"""
+Base Client Architecture for gRPC services.
+
+This module provides the abstract base class for all gRPC clients in the system,
+standardizing connection management, stub creation, and resource cleanup.
+"""
+
+import abc
+import asyncio
+import contextlib
+import ssl
+import sys
+import traceback
+from dataclasses import dataclass
+from logging import Logger, getLogger
+from pathlib import Path
+from typing import Any  # TypeAlias, # need 3.10 or use type in 3.12
+from typing import AsyncIterator, Optional, Type, TypeVar, Union
+
+from betterproto import ServiceStub
+from grpclib.client import Channel
+from grpclib.config import Configuration
+from grpclib.exceptions import GRPCError, StreamTerminatedError
+
+from .decorators import with_retry, with_streaming_retry
+from .errors import MantaError, wrap_exception
+from .retry import DefaultRetryPolicy, RetryPolicy, StreamingRetryPolicy
+from .traces import Tracer
+
+# Type for metadata
+MetadataDict = dict[str, str]
+
+# TypeVar for self-referencing return types
+T = TypeVar("T", bound="GrpcClientBase")
+
+__all__ = ["GrpcClientBase", "ConnectionKey", "MetadataDict"]
+
+
+@dataclass(frozen=True)
+class ConnectionKey:
+    """
+    Immutable key for connection identification.
+    """
+
+    host: str
+    port: int
+    secure: bool = False
+
+    def __str__(self) -> str:
+        scheme = "secure" if self.secure else "insecure"
+        return f"{scheme}://{self.host}:{self.port}"
+
+
+class GrpcClientBase(abc.ABC):
+    """
+    Abstract base class for all gRPC clients.
+
+    This class provides standardized channel lifecycle management and
+    common utilities for all gRPC client implementations.
+    """
+
+    #: Default host for the gRPC service
+    DEFAULT_HOST: str = "localhost"
+
+    #: Default port for the gRPC service
+    DEFAULT_PORT: int = 50051
+
+    #: Default channel options for gRPC connections
+    DEFAULT_CHANNEL_OPTIONS: dict[str, Any] = {
+        "_keepalive_time": 30.0,  # 30s
+        "_keepalive_timeout": 20.0,  # 20s
+        "_keepalive_permit_without_calls": False,
+        "_http2_max_pings_without_data": 2,
+        "_http2_min_sent_ping_interval_without_data": 300.0,  # 300s
+        "http2_connection_window_size": 4194304,  # 4MB
+        "http2_stream_window_size": 4194304,  # 4MB
+    }
+
+    #: Default metadata to include in each request
+    DEFAULT_METADATA: MetadataDict = {}
+
+    #: Default retry policy for regular methods
+    DEFAULT_RETRY_POLICY: RetryPolicy = DefaultRetryPolicy(
+        max_retries=3,
+        initial_delay=0.2,
+        max_delay=5.0,
+        backoff_factor=2.0,
+        jitter_factor=0.2,
+    )
+
+    #: Default retry policy for streaming methods
+    DEFAULT_STREAMING_RETRY_POLICY: RetryPolicy = StreamingRetryPolicy(
+        max_retries=3,
+        initial_delay=0.2,
+        max_delay=5.0,
+        backoff_factor=2.0,
+        jitter_factor=0.2,
+        retry_if_no_items_processed=True,
+    )
+
+    @abc.abstractmethod
+    def _get_stub_class(self) -> Type[ServiceStub]:
+        """
+        Get the stub class for this client.
+
+        This method must be implemented by all subclasses to return
+        the appropriate stub class.
+
+        Returns
+        -------
+        Type[ServiceStub]
+            The stub class
+        """
+        pass
+
+    @property
+    def ssl_context(self):
+        """
+        Get the SSL context for the client.
+
+        Returns SSL context for secure connections, None for insecure.
+        """
+        if not self.secure:
+            return None
+
+        if hasattr(self, "_ssl_context"):
+            return self._ssl_context
+
+        # If no custom cert folder is specified and connecting to port 443,
+        # use system default SSL context (for public HTTPS/gRPC endpoints)
+        if self.cert_folder is None and self.port == 443:
+            import certifi
+
+            self.tracer.info(
+                f"Using system default SSL context for public endpoint {self.host}:443"
+            )
+            # Create system default SSL context that trusts system CA bundle (including Let's Encrypt)
+            self._ssl_context = ssl.create_default_context(
+                ssl.Purpose.SERVER_AUTH, cafile=certifi.where()
+            )
+            # CRITICAL: Enable HTTP/2 via ALPN for gRPC over TLS
+            # This is required for gRPC connections through NGINX Ingress
+            self._ssl_context.set_alpn_protocols(["h2"])
+            return self._ssl_context
+
+        # Create SSL context based on custom certificate configuration
+        from .cert_loader import create_ssl_context
+
+        self._ssl_context = create_ssl_context(
+            component_name=self.component_name,
+            environment=self.environment,
+            cert_folder=self.cert_folder,
+            verify_mode=(
+                ssl.CERT_REQUIRED if self.environment != "dev" else ssl.CERT_NONE
+            ),
+        )
+
+        return self._ssl_context
+
+    @property
+    def metadata(self) -> MetadataDict:
+        """
+        Get metadata for gRPC requests.
+
+        Subclasses can override this property to provide custom metadata.
+        Similar to ssl_context property pattern.
+
+        Returns
+        -------
+        MetadataDict
+            Metadata dictionary for gRPC requests
+        """
+        return {}
+
+    def __init__(
+        self,
+        host: Optional[str] = None,
+        port: Optional[int] = None,
+        secure: bool = False,
+        channel_options: Optional[dict[str, Any]] = None,
+        tracer: Optional[Union[Tracer, Logger]] = None,
+        retry_policy: Optional[RetryPolicy] = None,
+        streaming_retry_policy: Optional[RetryPolicy] = None,
+        component_name: str = "manta-sdk",
+        environment: Optional[str] = None,
+        cert_folder: Optional[Union[str, Path]] = None,
+    ):
+        """
+        Initialize the gRPC client.
+
+        Parameters
+        ----------
+        host : Optional[str]
+            The host to connect to
+        port : Optional[int]
+            The port to connect to
+        secure : bool
+            Whether to use a secure channel
+        channel_options : Optional[dict[str, Any]]
+            Optional channel configuration
+        tracer : Optional[Union[Tracer, Logger]]
+            Logger to use for tracing (if None, a default logger will be created)
+        retry_policy : Optional[RetryPolicy]
+            Retry policy for regular methods
+        streaming_retry_policy : Optional[RetryPolicy]
+            Retry policy for streaming methods
+        component_name : Optional[str]
+            Component name for certificate loading (e.g., 'manta-sdk', 'manta-node')
+        environment : Optional[str]
+            Environment name for certificate loading (e.g., 'dev', 'staging', 'prod')
+        cert_folder : Optional[Union[str, Path]]
+            Custom certificate folder path
+        """
+        self.host = host or self.DEFAULT_HOST
+        self.port = port or self.DEFAULT_PORT
+        self.secure = secure
+
+        # Certificate configuration
+        self.component_name = component_name
+        self.environment = environment
+        self.cert_folder = cert_folder
+
+        final_channel_options = self.DEFAULT_CHANNEL_OPTIONS.copy()
+        if channel_options:
+            final_channel_options.update(channel_options)
+        self.config = Configuration(**final_channel_options)
+
+        self.connection_key = ConnectionKey(
+            host=self.host, port=self.port, secure=self.secure
+        )
+
+        self._channel = None
+        self._is_connected = False
+
+        # Initialize tracer from provided logger or create a new one
+        if tracer is None:
+            self.tracer = Tracer(
+                getLogger(f"{self.__class__.__module__}.{self.__class__.__name__}")
+            )
+        else:
+            self.tracer = tracer
+
+        self.tracer.debug(f"Initialized client for {self.connection_key}")
+
+        # Set up retry policies
+        self.retry_policy = retry_policy or self.DEFAULT_RETRY_POLICY
+        self.streaming_retry_policy = (
+            streaming_retry_policy or self.DEFAULT_STREAMING_RETRY_POLICY
+        )
+
+        # Initialize connection-related attributes
+        self._active_calls: list[asyncio.Task] = []
+
+    async def connect(self) -> Channel:
+        """
+        Connect to the gRPC service and create a stub.
+
+        This method should be called before making any service calls.
+        If already connected, returns the existing channel.
+
+        Returns
+        -------
+        Channel
+            The gRPC channel for making RPC calls
+
+        Examples
+        --------
+        >>> client = MyServiceClient("localhost", 50051)
+        >>> channel = await client.connect()
+        >>> await client.disconnect()
+        """
+        if self.is_connected and self._channel is not None:
+            self.tracer.debug(f"Already connected to {self.connection_key}")
+            return self._channel
+
+        self.tracer.debug(f"Connecting to {self.connection_key}")
+        self._channel = Channel(
+            self.host, self.port, config=self.config, ssl=self.ssl_context
+        )
+        self._is_connected = True
+        return self._channel
+
+    async def disconnect(self) -> None:
+        """
+        Disconnect from the gRPC service and clean up resources.
+
+        This method should be called after all service calls are completed.
+        """
+        if not self.is_connected and self._channel is None:
+            self.tracer.debug(
+                f"Already disconnected or channel is None for {self.connection_key}."
+            )
+            return
+
+        self.tracer.debug(f"Disconnecting from {self.connection_key}...")
+
+        # Asynchronously cancel active calls and allow them to process
+        # Create a list of tasks that are not done yet to attempt cancellation
+        tasks_to_cancel = [task for task in self._active_calls if not task.done()]
+
+        if tasks_to_cancel:
+            self.tracer.debug(
+                f"Attempting to cancel {len(tasks_to_cancel)} active call(s) for {self.connection_key}."
+            )
+            for task in tasks_to_cancel:
+                task.cancel()  # Schedule cancellation
+
+            # Wait for the tasks to acknowledge cancellation or complete WITH TIMEOUT
+            # This allows tasks to run their cleanup code (e.g., finally blocks)
+            task_cleanup_timeout = 2.0  # 2 seconds to complete cancellation
+            try:
+                results = await asyncio.wait_for(
+                    asyncio.gather(*tasks_to_cancel, return_exceptions=True),
+                    timeout=task_cleanup_timeout,
+                )
+                for i, result in enumerate(results):
+                    task_ref = tasks_to_cancel[i]
+                    if isinstance(result, asyncio.CancelledError):
+                        self.tracer.debug(
+                            f"Task {task_ref} was successfully cancelled."
+                        )
+                    elif isinstance(result, Exception):
+                        self.tracer.error(
+                            f"Task {task_ref} raised an exception during/after cancellation: {result}",
+                            exc_info=result,
+                        )  # Log with exc_info if it's an actual exception
+                    else:
+                        self.tracer.debug(
+                            f"Task {task_ref} completed (result: {result}) before cancellation fully processed or was not cancelled."
+                        )
+            except asyncio.TimeoutError:
+                self.tracer.warning(
+                    f"Task cancellation timed out after {task_cleanup_timeout}s for {self.connection_key}. "
+                    f"Forcefully clearing {len(tasks_to_cancel)} task(s)."
+                )
+
+        # Clear the list of active calls after attempting to process them
+        self._active_calls.clear()
+
+        # CRITICAL FIX: channel.close() is SYNCHRONOUS and can block the event loop
+        # in selectors.select() when there are pending operations.
+        # Run it in a thread executor with aggressive timeout to prevent hanging.
+        if self._channel:
+            self.tracer.debug(f"Closing channel for {self.connection_key}...")
+            loop = asyncio.get_running_loop()
+            try:
+                # Run synchronous channel.close() in executor thread with 500ms timeout
+                await asyncio.wait_for(
+                    loop.run_in_executor(None, self._channel.close),
+                    timeout=0.5,  # Fail fast - don't wait more than 500ms
+                )
+                self.tracer.debug(
+                    f"Channel closed successfully for {self.connection_key}"
+                )
+            except asyncio.TimeoutError:
+                # Channel close timed out - likely blocked in selectors.select()
+                # Don't wait - let OS cleanup the socket when process exits
+                self.tracer.warning(
+                    f"Channel close timed out after 500ms for {self.connection_key}. "
+                    "Proceeding without waiting - OS will cleanup socket on process exit."
+                )
+            except Exception as e:
+                self.tracer.warning(
+                    f"Warning closing channel for {self.connection_key}: {e}. "
+                    "Proceeding - OS will cleanup socket on process exit."
+                )
+            finally:
+                # Always reset state, even if close failed
+                self._channel = None
+                self._is_connected = False
+
+        self.tracer.debug(f"Disconnect completed for {self.connection_key}")
+
+    def _finalize_cleanup_resources(self) -> None:
+        """
+        Synchronously attempts to cancel active calls and close the channel.
+        This method is designed to be safe to call multiple times and from __del__.
+        """
+        # Request cancellation of active calls
+        if self._active_calls:
+            self.tracer.debug(
+                f"Requesting cancellation for {len(self._active_calls)} active call(s) during cleanup for {self.connection_key}."
+            )
+            for task in list(self._active_calls):  # Iterate over a copy
+                if not task.done():
+                    try:
+                        task.cancel()
+                        # Note: Actual cancellation processing depends on the event loop.
+                    except Exception as e:
+                        self.tracer.error(
+                            f"Error requesting task cancellation for {task} during cleanup: {e}",
+                            exc_info=True,
+                        )
+            self._active_calls.clear()
+
+        # Close the channel
+        if self._channel:
+            self.tracer.debug(
+                f"Closing channel for {self.connection_key} during cleanup."
+            )
+            try:
+                self._channel.close()  # This is synchronous
+            except Exception as e:
+                self.tracer.error(
+                    f"Error closing channel for {self.connection_key} during cleanup: {e}",
+                    exc_info=True,
+                )
+            finally:
+                self._is_connected = False
+
+        # Reset state
+        self._channel = None
+        self._is_connected = False
+        self.tracer.debug(f"Resource cleanup finalized for {self.connection_key}.")
+
+    def __del__(self):
+        """
+        Destructor to attempt resource cleanup as a last resort.
+        It's best practice to explicitly call `disconnect()` or use the async context manager.
+        """
+        # Check if Python is shutting down - if so, skip cleanup to avoid ImportError
+        try:
+            if sys.meta_path is None:
+                return
+        except ImportError:
+            # Python is shutting down, skip cleanup
+            return
+
+        # Check if object is properly initialized before accessing attributes
+        # During testing or shutdown, attributes may not exist
+        try:
+            is_connected = self.is_connected
+            active_calls = self._active_calls
+        except AttributeError:
+            # Object not fully initialized, skip cleanup
+            return
+
+        if is_connected or active_calls:
+            try:
+                self.tracer.warning(
+                    f"Client for {self.connection_key} was not explicitly disconnected. "
+                    f"Attempting synchronous cleanup in __del__. Active calls: {len(self._active_calls)}"
+                )
+            except (ImportError, AttributeError, ValueError):
+                # During shutdown, modules might be unavailable or logging streams closed
+                # ValueError: I/O operation on closed file (during pytest teardown)
+                pass
+
+            # Check if an event loop is available and running
+            # If not, skip cleanup to avoid blocking on channel.close()
+            try:
+                asyncio.get_running_loop()
+                # Event loop exists, safe to cleanup
+                self._finalize_cleanup_resources()
+            except RuntimeError:  # No running event loop
+                try:
+                    self.tracer.warning(
+                        f"No running event loop detected in __del__ for {self.connection_key}. "
+                        "Skipping channel cleanup to avoid blocking. Python shutdown will handle resource cleanup."
+                    )
+                except (ImportError, AttributeError, ValueError):
+                    # During shutdown, logging streams might be closed
+                    pass
+                # DO NOT call _finalize_cleanup_resources() without an event loop
+                # channel.close() will block indefinitely in selectors.select()
+                # Let Python's shutdown mechanism handle the cleanup
+
+    @property
+    def is_connected(self) -> bool:
+        """
+        Check if the client is connected.
+
+        Returns
+        -------
+        bool
+            True if connected, False otherwise
+        """
+        return self._is_connected
+
+    async def __aenter__(self) -> "GrpcClientBase":
+        """
+        Enter the context manager.
+
+        Returns
+        -------
+        GrpcClientBase
+            The client instance
+        """
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """
+        Exit the context manager and clean up resources.
+
+        This method ensures the connection is properly closed even if an
+        exception is raised within the context.
+        """
+        await self.disconnect()
+
+    @contextlib.asynccontextmanager
+    async def with_stub(self):
+        """
+        Context manager for executing operations with a managed stub.
+
+        Yields
+        ------
+        StubT
+            The service stub for making RPC calls
+
+        Examples
+        --------
+        >>> client = MyServiceClient("localhost", 50051)
+        >>> async with client.with_stub("get_data") as stub:
+        ...     response = await stub.get_data(request)
+        """
+        stub_class = self._get_stub_class()
+        channel = await self.connect()
+        stub = stub_class(channel)
+        yield stub
+
+    async def _ensure_connected(self) -> None:
+        """
+        Ensure that the client is connected to the server.
+
+        This internal method is used by service methods to ensure that a connection
+        exists before making service calls.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        ConnectionError
+            If a connection cannot be established
+        """
+        if not self.is_connected:
+            await self.connect()
+
+    async def _reset_channel(self) -> None:
+        """Close the dead channel and clear state so the next call reconnects."""
+        if self._channel:
+            loop = asyncio.get_running_loop()
+            try:
+                await asyncio.wait_for(
+                    loop.run_in_executor(None, self._channel.close),
+                    timeout=0.5,
+                )
+            except (asyncio.TimeoutError, Exception) as e:
+                self.tracer.debug(f"Channel close during GOAWAY reset: {e}")
+            finally:
+                self._channel = None
+                self._is_connected = False
+        else:
+            self._is_connected = False
+
+    async def health_check(self) -> bool:
+        """
+        Check if the service is healthy and responding.
+
+        This is a basic implementation that simply checks if a connection can be made.
+        Subclasses may override to implement service-specific health checks.
+
+        Returns
+        -------
+        bool
+            True if the service is healthy, False otherwise
+        """
+        try:
+            await self._ensure_connected()
+            return True
+        except Exception as e:
+            self.tracer.debug(f"Health check failed: {e}")
+            return False
+
+    def create_metadata(
+        self, extra_metadata: Optional[MetadataDict] = None
+    ) -> MetadataDict:
+        """
+        Create metadata for a gRPC call by merging the default metadata with any extra metadata.
+
+        Parameters
+        ----------
+        extra_metadata : Optional[MetadataDict]
+            Extra metadata to add to the call
+
+        Returns
+        -------
+        MetadataDict
+            The merged metadata
+        """
+        # Start with metadata from the property
+        md = self.metadata.copy() if self.metadata else {}
+
+        # Add extra metadata
+        if extra_metadata:
+            md.update(extra_metadata)
+
+        return md
+
+    @contextlib.asynccontextmanager
+    async def _track_service_call(self):
+        """
+        Context manager to track active service calls.
+
+        This allows for graceful cancellation of ongoing calls during disconnect.
+
+        Yields
+        ------
+        None
+        """
+        # Get the current task
+        current_task = asyncio.current_task()
+        if current_task is not None:
+            self._active_calls.append(current_task)
+
+        try:
+            yield
+        finally:
+            # Remove the task from active calls if it exists
+            if current_task is not None and current_task in self._active_calls:
+                self._active_calls.remove(current_task)
+
+    @classmethod
+    async def create(
+        cls: Type[T],
+        host: Optional[str] = None,
+        port: Optional[int] = None,
+        **kwargs,
+    ) -> T:
+        """
+        Factory method to create and connect a client.
+
+        Parameters
+        ----------
+        host : Optional[str]
+            The hostname of the gRPC server
+        port : Optional[int]
+            The port number of the gRPC server
+        **kwargs
+            Additional arguments to pass to the constructor
+
+        Returns
+        -------
+        GrpcClientBase
+            A connected client instance
+        """
+        client = cls(host=host, port=port, **kwargs)
+        await client.connect()
+        return client
+
+    async def call_service_method(
+        self,
+        method_name: str,
+        request: Any,
+        metadata: Optional[MetadataDict] = None,
+        retry_policy: Optional[RetryPolicy] = None,
+        error_class: Optional[Type[MantaError]] = None,
+        include_operation: bool = True,
+        include_request: bool = True,
+        include_metadata: bool = True,
+        log_call_stack: bool = False,
+    ) -> Any:
+        """
+        Call a service method with retries.
+
+        This method handles connecting to the service, execution with retries,
+        and proper error handling.
+
+        Parameters
+        ----------
+        method_name : str
+            The name of the method to call
+        request : Any
+            The request object to pass to the method
+        metadata : Optional[MetadataDict]
+            Additional metadata to include with the request
+        retry_policy : Optional[RetryPolicy]
+            Retry policy to use (falls back to client's policy if None)
+        error_class : Optional[Type[Exception]]
+            The exception class to wrap the error in
+        include_operation : bool
+            Whether to include the operation name in the log
+        include_request : bool
+            Whether to include the request in the log
+        log_call_stack : bool
+            Whether to log the call stack
+
+        Returns
+        -------
+        Message
+            The response from the service method
+
+        Raises
+        ------
+        MantaError
+            If the service call fails after retries
+        """
+        # Set up retry policy from parameters or defaults
+        policy = retry_policy or self.retry_policy
+
+        @with_retry(
+            tracer=self.tracer,
+            policy=policy,
+            operation_name=f"{self.__class__.__name__}.{method_name}",
+        )
+        async def _execute_call():
+            try:
+                async with self._track_service_call():
+                    async with self.with_stub() as stub:
+                        method = getattr(stub, method_name)
+
+                        final_metadata = self.create_metadata(metadata)
+
+                        # Log information about the request
+                        message = f"Calling {method_name}"
+                        if include_request:
+                            message += f" with {request}"
+                        if include_metadata:
+                            message += f" with metadata {final_metadata}"
+                        if include_operation:
+                            self.tracer.debug(message)
+
+                        result = await method(request, metadata=final_metadata)
+
+                        # Log completion of the call
+                        if include_operation:
+                            self.tracer.debug(f"Completed {method_name}")
+
+                        return result
+            except StreamTerminatedError:
+                self.tracer.warning(
+                    f"GOAWAY received during {method_name}, resetting channel for reconnect"
+                )
+                await self._reset_channel()
+                raise
+            except GRPCError as e:
+                # Add enhanced error logging
+                self.tracer.error(
+                    f"GRPC Error in {method_name}: status={e.status}, message={e.message}"
+                )
+                if hasattr(e, "details") and e.details:
+                    self.tracer.error(f"Error details: {e.details}")
+
+                # Include stack trace
+                if log_call_stack:
+                    self.tracer.error(f"Call stack: {traceback.format_exc()}")
+
+                raise wrap_exception(
+                    e,
+                    message=f"Error in {method_name}",
+                    error_class=error_class,
+                )
+            except Exception as e:
+                self.tracer.exception(f"Unexpected error in {method_name}: {str(e)}")
+                if log_call_stack:
+                    self.tracer.error(f"Call stack: {traceback.format_exc()}")
+                raise wrap_exception(
+                    e,
+                    message=f"Error in {method_name}",
+                    error_class=error_class,
+                )
+
+        return await _execute_call()
+
+    async def stream_service_method(
+        self,
+        method_name: str,
+        request: Any,
+        metadata: Optional[MetadataDict] = None,
+        retry_policy: Optional[RetryPolicy] = None,
+        error_class: Optional[Type[MantaError]] = None,
+        log_call_stack: bool = False,
+        include_operation: bool = True,
+        include_request: bool = True,
+        include_metadata: bool = True,
+    ) -> AsyncIterator[Any]:
+        """
+        Execute a streaming service method with retry and error handling.
+
+        This helper method simplifies making streaming service calls with proper
+        connection management, error handling, and retry logic.
+
+        Parameters
+        ----------
+        method_name : str
+            The name of the service method to call
+        request : Any
+            The request object to pass to the method
+        metadata : Optional[MetadataDict]
+            Additional metadata to include in the request
+        retry_policy : Optional[RetryPolicy]
+            Custom retry policy for this call (uses instance streaming policy if None)
+        error_class : Optional[Type[MantaError]]
+            The exception class to wrap the error in
+        log_call_stack : bool
+            Whether to log the call stack
+        include_operation : bool
+            Whether to include the operation name in the log
+        include_request : bool
+            Whether to include the request in the log
+        include_metadata : bool
+            Whether to include the metadata in the log
+
+        Yields
+        ------
+        Any
+            Each response item from the streaming service method
+
+        Raises
+        ------
+        MantaError
+            If an error occurs during the service call
+        """
+        # Use the specified retry policy or the client's default for streaming
+        policy = retry_policy or self.streaming_retry_policy
+
+        # Execute the call with streaming retry
+        @with_streaming_retry(
+            tracer=self.tracer,
+            policy=policy,
+            operation_name=f"{self.__class__.__name__}.{method_name}",
+        )
+        async def _execute_streaming_call() -> AsyncIterator[Any]:
+            async with self._track_service_call():
+                try:
+                    async with self.with_stub() as stub:
+                        method = getattr(stub, method_name)
+
+                        final_metadata = self.create_metadata(metadata)
+
+                        # Log information about the request
+                        message = f"Streaming {method_name}"
+                        if include_request:
+                            message += f" with {request}"
+                        if include_metadata:
+                            message += f" with metadata {final_metadata}"
+                        if include_operation:
+                            self.tracer.debug(message)
+
+                        response_count = 0
+
+                        async for response in method(request, metadata=final_metadata):
+                            self.tracer.debug(f"Received response from {method_name}")
+                            response_count += 1
+                            yield response
+
+                        # Log completion of the call
+                        if include_operation:
+                            self.tracer.debug(
+                                f"Completed streaming {method_name} with {response_count} items"
+                            )
+
+                except StreamTerminatedError:
+                    self.tracer.warning(
+                        f"GOAWAY received during streaming {method_name}, resetting channel for reconnect"
+                    )
+                    await self._reset_channel()
+                    raise
+                except GRPCError as e:
+                    # Add enhanced error logging
+                    self.tracer.error(
+                        f"GRPC Error in streaming {method_name}: status={e.status}, message={e.message}"
+                    )
+                    if hasattr(e, "details") and e.details:
+                        self.tracer.error(f"Error details: {e.details}")
+
+                    # Include stack trace
+                    if log_call_stack:
+                        self.tracer.error(f"Call stack: {traceback.format_exc()}")
+
+                    raise wrap_exception(
+                        e,
+                        message=f"Error in streaming {method_name}",
+                        error_class=error_class,
+                    )
+                except Exception as e:
+                    self.tracer.exception(
+                        f"Unexpected error in {method_name}: {str(e)}"
+                    )
+                    if log_call_stack:
+                        self.tracer.error(f"Call stack: {traceback.format_exc()}")
+                    raise wrap_exception(
+                        e,
+                        message=f"Error in streaming {method_name}",
+                        error_class=error_class,
+                    )
+
+        # Get all responses and yield them one by one
+        async for response in _execute_streaming_call():
+            yield response