python-etcd3-async 0.1.0__py3-none-any.whl

etcd3/async_client.py

@@ -0,0 +1,1495 @@
+"""Async etcd3 client implementation using grpc.aio.
+
+This module provides asynchronous client classes for interacting with etcd v3 API
+using the asynchronous gRPC client from grpcio package.
+"""
+
+import asyncio
+import functools
+import random
+import threading
+from dataclasses import dataclass, field
+from typing import Optional, Literal, Any
+
+import grpc
+import etcdrpc
+
+from etcd3 import exceptions
+from etcd3 import utils
+from etcd3 import transactions
+from etcd3.async_endpoint import AsyncEndpoint
+from etcd3.shared import (
+    KVMetadata,
+    EXCEPTIONS_BY_CODE,
+    FAILED_EP_CODES,
+    Transactions,
+    EtcdTokenCallCredentials,
+    RequestBuilder,
+)
+from etcd3.async_managers import (
+    AsyncWatchManager,
+    AsyncClusterManager,
+    AsyncMaintenanceManager,
+)
+from etcd3.exporters.prometheus import get_metrics_interface, monitor_request
+from etcd3.log import log_operation_async
+from etcd3.async_client_extensions import (
+    AsyncKVOperations,
+    AsyncLeaseOperations,
+    AsyncLockOperations,
+    AsyncClusterOperations,
+    AsyncMaintenanceOperations,
+    AsyncWatchOperations,
+)
+
+
+@dataclass(kw_only=True)
+class RangeRequestConfig:
+    """Configuration for range request.
+
+    :param range_end: End of the key range
+    :type range_end: str or bytes
+    :param limit: Maximum number of keys to return
+    :type limit: int
+    :param revision: Revision to get
+    :type revision: int
+    :param sort_order: Sort order ('ascend' or 'descend')
+    :type sort_order: str
+    :param sort_target: Sort target ('key', 'version', 'create', 'mod')
+    :type sort_target: str
+    :param serializable: Whether to use serializable read
+    :type serializable: bool
+    :param keys_only: Whether to return only keys
+    :type keys_only: bool
+    :param count_only: Whether to return only count
+    :type count_only: bool
+    :param min_mod_revision: Minimum modification revision
+    :type min_mod_revision: int
+    :param max_mod_revision: Maximum modification revision
+    :type max_mod_revision: int
+    :param min_create_revision: Minimum creation revision
+    :type min_create_revision: int
+    :param max_create_revision: Maximum creation revision
+    :type max_create_revision: int
+    """
+
+    range_end: Optional[bytes | str] = None
+    limit: Optional[int] = None
+    revision: Optional[int] = None
+    sort_order: Optional[Literal["ascend", "descend"]] = None
+    sort_target: Literal["key", "version", "create", "mod"] = "key"
+    serializable: bool = False
+    keys_only: bool = False
+    count_only: bool = False
+    min_mod_revision: Optional[int] = None
+    max_mod_revision: Optional[int] = None
+    min_create_revision: Optional[int] = None
+    max_create_revision: Optional[int] = None
+
+    def __post_init__(self):
+        if self.limit is not None and self.limit < 1:
+            raise ValueError("limit must be a positive integer")
+        if self.revision is not None and self.revision < 0:
+            raise ValueError("revision must be a non-negative integer")
+        if self.min_mod_revision is not None and self.min_mod_revision < 0:
+            raise ValueError("min_mod_revision must be a non-negative integer")
+        if self.max_mod_revision is not None and self.max_mod_revision < 0:
+            raise ValueError("max_mod_revision must be a non-negative integer")
+        if self.min_create_revision is not None and self.min_create_revision < 0:
+            raise ValueError("min_create_revision must be a non-negative integer")
+        if self.max_create_revision is not None and self.max_create_revision < 0:
+            raise ValueError("max_create_revision must be a non-negative integer")
+
+
+@dataclass(kw_only=True)
+class AsyncClientConfig:
+    """Configuration for async client creation.
+
+    :param host: etcd host
+    :type host: str
+    :param port: etcd port
+    :type port: int
+    :param ca_cert: CA certificate path
+    :type ca_cert: str
+    :param cert_key: client certificate key path
+    :type cert_key: str
+    :param cert_cert: client certificate path
+    :type cert_cert: str
+    :param timeout: request timeout in seconds
+    :type timeout: int or float
+    :param user: username for authentication
+    :type user: str
+    :param password: password for authentication
+    :type password: str
+    :param grpc_options: additional gRPC options
+    :type grpc_options: dict[str, Any]
+    """
+
+    host: str = "localhost"
+    port: int = 2379
+    ca_cert: Optional[str] = None
+    cert_key: Optional[str] = None
+    cert_cert: Optional[str] = None
+    timeout: Optional[float] = None
+    user: Optional[str] = None
+    password: Optional[str] = None
+    grpc_options: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        if self.port < 1 or self.port > 65535:
+            raise ValueError("port must be between 1 and 65535")
+        if self.timeout is not None and self.timeout <= 0:
+            raise ValueError("timeout must be a positive number")
+
+
+@dataclass(kw_only=True)
+class AsyncMultiEndpointConfig:
+    """Configuration for AsyncMultiEndpointEtcd3Client creation.
+
+    :param endpoints: Endpoints to use
+    :type endpoints: Iterable[Endpoint]
+    :param timeout: Timeout for all RPC in seconds
+    :type timeout: float, optional
+    :param user: Username for authentication
+    :type user: str, optional
+    :param password: Password for authentication
+    :type password: str, optional
+    :param failover: Failover between endpoints, default False
+    :type failover: bool
+    :param max_retries: Maximum number of retries for transient errors
+    :type max_retries: int
+    :param retry_backoff: Initial backoff time in seconds for retries
+    :type retry_backoff: float
+    :param retry_max_backoff: Maximum backoff time in seconds for retries
+    :type retry_max_backoff: float
+    :param load_balancer: Load balancing strategy
+    :type load_balancer: LoadBalancerStrategy
+    :param health_check_interval: Health check interval in seconds
+    :type health_check_interval: float
+    """
+
+    endpoints: Optional[list] = None
+    timeout: Optional[float] = None
+    user: Optional[str] = None
+    password: Optional[str] = None
+    failover: bool = False
+    max_retries: int = 3
+    retry_backoff: float = 0.1
+    retry_max_backoff: float = 10.0
+    load_balancer: utils.LoadBalancerStrategy = utils.LoadBalancerStrategy.PRIORITY
+    health_check_interval: float = 30.0
+
+    def __post_init__(self):
+        if self.max_retries < 0:
+            raise ValueError("max_retries must be a non-negative integer")
+        if self.retry_backoff < 0:
+            raise ValueError("retry_backoff must be a non-negative number")
+        if self.retry_max_backoff < 0:
+            raise ValueError("retry_max_backoff must be a non-negative number")
+        if self.retry_backoff > self.retry_max_backoff:
+            raise ValueError("retry_backoff must not exceed retry_max_backoff")
+        if self.health_check_interval <= 0:
+            raise ValueError("health_check_interval must be a positive number")
+
+
+class AsyncMultiEndpointEtcd3Client:
+    """
+    Async etcd v3 API client with multiple endpoints.
+
+    When failover is enabled, requests still will not be auto-retried.
+    Instead, the application may retry the request, and the ``Etcd3Client``
+    will then attempt to send it to a different endpoint that has not recently
+    failed. If all configured endpoints have failed and are not ready to be
+    retried, an ``exceptions.NoServerAvailableError`` will be raised.
+
+    :param endpoints: Endpoints to use in lieu of host and port
+    :type endpoints: Iterable(Endpoint), optional
+    :param timeout: Timeout for all RPC in seconds
+    :type timeout: int or float, optional
+    :param user: Username for authentication
+    :type user: str, optional
+    :param password: Password for authentication
+    :type password: str, optional
+    :param bool failover: Failover between endpoints, default False
+    :param int max_retries: Maximum number of retries for transient errors
+    :param float retry_backoff: Initial backoff time in seconds for retries
+    :param float retry_max_backoff: Maximum backoff time in seconds for retries
+    """
+
+    def __init__(
+        self,
+        config: Optional[AsyncMultiEndpointConfig] = None,
+        endpoints: Optional[list] = None,
+        timeout: Optional[float] = None,
+        user: Optional[str] = None,
+        password: Optional[str] = None,
+        failover: bool = False,
+        max_retries: int = 3,
+        retry_backoff: float = 0.1,
+        retry_max_backoff: float = 10.0,
+        load_balancer: utils.LoadBalancerStrategy = utils.LoadBalancerStrategy.PRIORITY,
+        health_check_interval: float = 30.0,
+    ):
+        if config is not None:
+            endpoints = config.endpoints
+            timeout = config.timeout
+            user = config.user
+            password = config.password
+            failover = config.failover
+            max_retries = config.max_retries
+            retry_backoff = config.retry_backoff
+            retry_max_backoff = config.retry_max_backoff
+            load_balancer = config.load_balancer
+            health_check_interval = config.health_check_interval
+
+        if endpoints is None:
+            raise ValueError("Endpoints must be provided")
+
+        if not endpoints:
+            raise ValueError("Endpoints list cannot be empty")
+
+        self.metadata = None
+        self.failover = failover
+        self.max_retries = max_retries
+        self.load_balancer = load_balancer
+        self.health_check_interval = health_check_interval
+        self._rr_index = 0  # Round-robin index
+        self.retry_backoff = retry_backoff
+        self.retry_max_backoff = retry_max_backoff
+
+        # Lock for synchronous code (setter, property access)
+        self._endpoint_lock = threading.Lock()
+        # Lock for asynchronous operations in _get_channel
+        self._async_endpoint_lock = asyncio.Lock()
+
+        self.endpoints = {ep.netloc: ep for ep in endpoints}
+        self._current_ep_label = random.choice(list(self.endpoints.keys()))
+
+        self._auth_done = False
+        self._auth_lock = asyncio.Lock()
+
+        self.timeout = timeout
+        self.call_credentials = None
+        cred_params = [c is not None for c in (user, password)]
+
+        if all(cred_params):
+            self._user = user
+            self._password = password
+        elif any(cred_params):
+            raise ValueError(
+                "if using authentication credentials both user and password "
+                "must be specified."
+            )
+        else:
+            self._user = None
+            self._password = None
+
+        self.watch_manager = AsyncWatchManager(self)
+        self.cluster_manager = AsyncClusterManager(self)
+        self.maintenance_manager = AsyncMaintenanceManager(self)
+
+        self.metrics = get_metrics_interface()
+
+        self.kv = AsyncKVOperations(self)
+        self.lease_ops = AsyncLeaseOperations(self)
+        self.lock_ops = AsyncLockOperations(self)
+        self.cluster_ops = AsyncClusterOperations(self)
+        self.maintenance_ops = AsyncMaintenanceOperations(self)
+        self.watch_ops = AsyncWatchOperations(self)
+        self.transactions = Transactions()
+
+    async def _init_auth(self):
+        """Initialize authentication asynchronously."""
+        if self._auth_done:
+            return
+
+        async with self._auth_lock:
+            if self._auth_done:
+                return
+
+            if self._user and self._password:
+                # Create auth stub with auto-reconnection
+                channel = await self._get_channel()
+                auth_stub = etcdrpc.AuthStub(channel)
+
+                auth_request = etcdrpc.AuthenticateRequest(
+                    name=self._user, password=self._password
+                )
+
+                resp = await auth_stub.Authenticate(auth_request, timeout=self.timeout)
+                self.metadata = (("token", resp.token),)
+                self.call_credentials = grpc.metadata_call_credentials(
+                    EtcdTokenCallCredentials(resp.token)
+                )
+
+            self._auth_done = True
+
+    @property
+    def _current_endpoint_label(self):
+        return self._current_ep_label
+
+    @_current_endpoint_label.setter
+    def _current_endpoint_label(self, value):
+        with self._endpoint_lock:
+            self._current_ep_label = value
+
+    @property
+    def endpoint_in_use(self):
+        """Get the current endpoint in use."""
+        if self._current_endpoint_label is None:
+            return None
+        return self.endpoints[self._current_endpoint_label]
+
+    @property
+    def channel(self):
+        """
+        Get an available channel on the first node that's not failed.
+
+        This property supports automatic reconnection when the
+        connection becomes stale (e.g., after etcd server restart).
+        If the current endpoint's channel is not healthy, it will
+        be rebuilt automatically.
+
+        Raises an exception if no node is available
+        """
+        with self._endpoint_lock:
+            try:
+                endpoint = self.endpoint_in_use
+                if endpoint is None:
+                    raise ValueError("No current endpoint")
+
+                channel = endpoint.use()
+                # Record endpoint usage
+                self.metrics.record_endpoint_usage(str(self.endpoint_in_use))
+                return channel
+            except ValueError:
+                if not self.failover:
+                    raise
+            for label, endpoint in self.endpoints.items():
+                if endpoint.is_failed():
+                    continue
+                self._current_ep_label = label
+                channel = self.endpoint_in_use.use()
+                # Record endpoint usage for the new endpoint
+                self.metrics.record_endpoint_usage(str(self.endpoint_in_use))
+                return channel
+            raise exceptions.NoServerAvailableError(
+                "No endpoint available and not failed"
+            )
+
+    def _get_next_endpoint(self):
+        """Get the next endpoint based on load balancing strategy.
+
+        :returns: A tuple of (endpoint_label, endpoint) or (None, None)
+                  if no healthy endpoint
+        """
+        healthy_endpoints = [
+            (label, ep) for label, ep in self.endpoints.items() if not ep.is_failed()
+        ]
+
+        if not healthy_endpoints:
+            return None, None
+
+        if self.load_balancer == utils.LoadBalancerStrategy.ROUND_ROBIN:
+            # Round-robin: select next endpoint in order
+            if not hasattr(self, "_rr_index"):
+                self._rr_index = 0
+            self._rr_index = (self._rr_index + 1) % len(healthy_endpoints)
+            return healthy_endpoints[self._rr_index - 1]
+
+        elif self.load_balancer == utils.LoadBalancerStrategy.RANDOM:
+            # Random: select random endpoint
+            import random
+
+            return random.choice(healthy_endpoints)
+
+        elif self.load_balancer == utils.LoadBalancerStrategy.STICKY:
+            # Sticky: keep current endpoint if healthy
+            current = self.endpoint_in_use
+            if current is not None and not current.is_failed():
+                return self._current_ep_label, current
+            # Fallback to first healthy endpoint
+            return healthy_endpoints[0]
+
+        else:
+            # PRIORITY (default): keep current endpoint if healthy
+            current = self.endpoint_in_use
+            if current is not None and not current.is_failed():
+                return self._current_ep_label, current
+            # Fallback to first healthy endpoint
+            return healthy_endpoints[0]
+
+    async def _try_rebuild_channel(self, endpoint):
+        """尝试重建通道，成功返回 True，失败返回 False"""
+        try:
+            await endpoint.rebuild_channel()
+            return True
+        except Exception:
+            return False
+
+    async def _get_channel(self):
+        """获取可用通道，支持自动重连。
+
+        采用两段式锁策略：
+        1. 锁内快速检查状态
+        2. 锁外执行 I/O 操作
+        3. 锁内更新状态
+        """
+        # 阶段1：快速检查状态（锁内）
+        async with self._async_endpoint_lock:
+            endpoint = self.endpoint_in_use
+            if endpoint is None:
+                raise ValueError("No current endpoint")
+
+            # 检查 endpoint 是否已恢复健康
+            if endpoint.is_failed() and endpoint.is_healthy():
+                # 恢复健康状态，重置失败标记
+                endpoint.last_failed = 0
+                endpoint.in_use = True
+                self.metrics.record_endpoint_recovery(str(endpoint))
+                channel = endpoint.channel
+                self.metrics.record_endpoint_usage(str(endpoint))
+                return channel
+
+            needs_rebuild = endpoint.is_failed()
+
+        # 阶段2：在锁外执行 I/O（关键优化）
+        rebuild_success = False
+        if needs_rebuild:
+            rebuild_success = await self._try_rebuild_channel(endpoint)
+            if not rebuild_success:
+                raise exceptions.NoServerAvailableError("Failed to rebuild connection")
+
+        # 阶段3：更新状态（再次获取锁）
+        async with self._async_endpoint_lock:
+            # 双重检查：确认在锁外期间状态未被其他协程修改
+            if endpoint.is_failed() and endpoint.is_healthy():
+                # 状态已恢复
+                endpoint.last_failed = 0
+                endpoint.in_use = True
+                self.metrics.record_endpoint_recovery(str(endpoint))
+            elif needs_rebuild and not endpoint.is_failed():
+                # 重建成功后的状态
+                endpoint.in_use = True
+                self.metrics.record_endpoint_recovery(str(endpoint))
+
+            channel = endpoint.channel
+            self.metrics.record_endpoint_usage(str(endpoint))
+            return channel
+
+    async def _check_all_health_parallel(self, timeout=5.0):
+        """Parallel health check for all endpoints using TaskGroup.
+
+        Uses asyncio.TaskGroup for efficient concurrent health checks.
+
+        :param timeout: Maximum time to wait for all health checks in seconds
+        :type timeout: float
+        :returns: Dictionary of endpoint label to health status
+        :rtype: dict[str, bool]
+        """
+        health_results = {}
+
+        async def check_endpoint(label, endpoint):
+            """Check health of a single endpoint."""
+            try:
+                # Use asyncio timeout for individual check
+                async with asyncio.timeout(timeout):
+                    is_healthy = await endpoint.health_check_async()
+                health_results[label] = is_healthy
+            except (asyncio.TimeoutError, Exception):
+                health_results[label] = False
+
+        # Use TaskGroup for parallel execution (Python 3.11+)
+        try:
+            async with asyncio.TaskGroup() as tg:
+                for label, endpoint in self.endpoints.items():
+                    tg.create_task(check_endpoint(label, endpoint))
+        except* (asyncio.TimeoutError, Exception):
+            # Individual task errors are already handled
+            pass
+
+        return health_results
+
+    async def _get_healthy_endpoints_parallel(self, timeout=3.0):
+        """Get list of healthy endpoints using parallel health check.
+
+        :param timeout: Maximum time for health checks in seconds
+        :type timeout: float
+        :returns: List of (label, endpoint) tuples for healthy endpoints
+        :rtype: list[tuple[str, AsyncEndpoint]]
+        """
+        health_results = await self._check_all_health_parallel(timeout=timeout)
+        return [
+            (label, ep)
+            for label, ep in self.endpoints.items()
+            if health_results.get(label, False)
+        ]
+
+    async def close(self):
+        """Call the GRPC channel close semantics."""
+        for endpoint in self.endpoints.values():
+            await endpoint.close()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()
+
+    def context(self, **kwargs):
+        """Create a context manager for tracking request context.
+
+        This method returns a context manager that sets up request context
+        for tracking operations across the etcd client.
+
+        Example usage:
+
+        .. code-block:: python
+
+            async with etcd.context(operation="batch_put", source="worker_1"):
+                await etcd.kv.batch_put({f"key_{i}": f"value_{i}" for i in range(100)})
+
+            # Inside any callback, get the context:
+            ctx = get_request_context()
+            if ctx:
+                print(f"Operation: {ctx.get('operation')}")
+
+        :param kwargs: Key-value pairs to store in the context
+        :returns: A context manager
+        """
+        from etcd3.async_client_extensions import _request_context
+
+        class RequestContextManager:
+            def __init__(self, client, **context_kwargs):
+                self.client = client
+                self.context_kwargs = context_kwargs
+                self.token = None
+
+            async def __aenter__(self):
+                # Store context with start time and endpoint info
+                start_time = asyncio.get_event_loop().time()
+                endpoint = self.client.endpoint_in_use
+                context_data = {
+                    "start_time": start_time,
+                    "endpoint": str(endpoint.netloc) if endpoint else None,
+                    **self.context_kwargs,
+                }
+                self.token = _request_context.set(context_data)
+                return self
+
+            async def __aexit__(self, *args):
+                if self.token is not None:
+                    _request_context.reset(self.token)
+
+        return RequestContextManager(self, **kwargs)
+
+    @staticmethod
+    def get_secure_creds(ca_cert, cert_key=None, cert_cert=None):
+        cert_key_file = None
+        cert_cert_file = None
+
+        with open(ca_cert, "rb") as f:
+            ca_cert_file = f.read()
+
+        if cert_key is not None:
+            with open(cert_key, "rb") as f:
+                cert_key_file = f.read()
+
+        if cert_cert is not None:
+            with open(cert_cert, "rb") as f:
+                cert_cert_file = f.read()
+
+        return grpc.ssl_channel_credentials(ca_cert_file, cert_key_file, cert_cert_file)
+
+    def _manage_grpc_errors(self, exc):
+        code = exc.code()
+        if code in FAILED_EP_CODES:
+            with self._endpoint_lock:
+                endpoint = self.endpoint_in_use
+                if endpoint is not None:
+                    # Mark endpoint as failed, will retry after time_retry
+                    endpoint.fail()
+                    # Record endpoint failure
+                    self.metrics.record_endpoint_failure(str(endpoint))
+        exception = EXCEPTIONS_BY_CODE.get(code)
+        if exception is None:
+            raise exc
+        raise exception()
+
+    def _should_retry(self, exc):
+        """Check if the error is retryable."""
+        code = getattr(exc, "code", lambda: None)()
+        if code in [
+            grpc.StatusCode.UNAVAILABLE,
+            grpc.StatusCode.DEADLINE_EXCEEDED,
+            grpc.StatusCode.INTERNAL,
+            grpc.StatusCode.RESOURCE_EXHAUSTED,
+        ]:
+            return True
+        return False
+
+    async def _retry_with_backoff(self, func, *args, **kwargs):
+        """Retry function with exponential backoff."""
+        retries = 0
+        backoff = self.retry_backoff
+
+        while retries <= self.max_retries:
+            try:
+                return await func(*args, **kwargs)
+            except grpc.RpcError as exc:
+                if not self._should_retry(exc) or retries >= self.max_retries:
+                    raise
+
+                retries += 1
+                if retries > self.max_retries:
+                    raise
+
+                # Record retry
+                self.metrics.record_retry(func.__name__, "unknown")
+
+                # Exponential backoff with jitter
+                backoff_time = min(
+                    backoff * (2 ** (retries - 1)), self.retry_max_backoff
+                )
+                jitter = random.uniform(0, backoff_time * 0.1)
+                await asyncio.sleep(backoff_time + jitter)
+            except exceptions.Etcd3Exception as exc:
+                # Check if this is a retryable etcd exception
+                if not self._should_retry(exc) or retries >= self.max_retries:
+                    raise
+
+                retries += 1
+                if retries > self.max_retries:
+                    raise
+
+                # Record retry
+                self.metrics.record_retry(func.__name__, "unknown")
+
+                # Exponential backoff with jitter
+                backoff_time = min(
+                    backoff * (2 ** (retries - 1)), self.retry_max_backoff
+                )
+                jitter = random.uniform(0, backoff_time * 0.1)
+                await asyncio.sleep(backoff_time + jitter)
+
+    @staticmethod
+    def _handle_errors(payload):
+        """Decorator to handle gRPC errors.
+
+        :param payload: The function to decorate
+        :return: Decorated function with error handling
+        """
+
+        @functools.wraps(payload)
+        async def handler(self_inner, *args, **kwargs):
+            # Only initialize auth if not already done
+            if not self_inner._auth_done:
+                await self_inner._init_auth()
+
+            try:
+                result = await self_inner._retry_with_backoff(
+                    payload, self_inner, *args, **kwargs
+                )
+                return result
+            except grpc.RpcError as exc:
+                self_inner._manage_grpc_errors(exc)
+
+        return handler
+
+    @staticmethod
+    def _handle_generator_errors(payload):
+        """Decorator to handle gRPC errors in generators.
+
+        :param payload: The generator function to decorate
+        :return: Decorated generator with error handling
+        """
+
+        @functools.wraps(payload)
+        async def handler(self_inner, *args, **kwargs):
+            # Only initialize auth if not already done
+            if not self_inner._auth_done:
+                await self_inner._init_auth()
+
+            try:
+                async for item in payload(self_inner, *args, **kwargs):
+                    yield item
+            except grpc.RpcError as exc:
+                self_inner._manage_grpc_errors(exc)
+
+        return handler
+
+    def _build_get_range_request(self, key, config=None, **kwargs):
+        """Build a range request.
+
+        :param key: The key to get
+        :type key: str or bytes
+        :param config: Range request configuration
+        :type config: RangeRequestConfig
+        :param kwargs: Additional keyword arguments for backward compatibility
+        :return: RangeRequest instance
+        """
+        # Use config object if provided, otherwise use kwargs or defaults
+        if config is None:
+            # Create config from kwargs for backward compatibility
+            config = RangeRequestConfig(
+                range_end=kwargs.get("range_end"),
+                limit=kwargs.get("limit"),
+                revision=kwargs.get("revision"),
+                sort_order=kwargs.get("sort_order"),
+                sort_target=kwargs.get("sort_target", "key"),
+                serializable=kwargs.get("serializable", False),
+                keys_only=kwargs.get("keys_only", False),
+                count_only=kwargs.get("count_only", False),
+                min_mod_revision=kwargs.get("min_mod_revision"),
+                max_mod_revision=kwargs.get("max_mod_revision"),
+                min_create_revision=kwargs.get("min_create_revision"),
+                max_create_revision=kwargs.get("max_create_revision"),
+            )
+
+        return RequestBuilder.build_get_range_request(
+            key=key,
+            range_end=config.range_end,
+            limit=config.limit,
+            revision=config.revision,
+            sort_order=config.sort_order,
+            sort_target=config.sort_target,
+            serializable=config.serializable,
+            keys_only=config.keys_only,
+            count_only=config.count_only,
+            min_mod_revision=config.min_mod_revision,
+            max_mod_revision=config.max_mod_revision,
+            min_create_revision=config.min_create_revision,
+            max_create_revision=config.max_create_revision,
+        )
+
+    @_handle_errors
+    @monitor_request("kv.get_response", is_async=True)
+    @log_operation_async("kv.get")
+    async def get_response(self, key, **kwargs):
+        """Get the value of a key from etcd.
+
+        :param key: key in etcd to get
+        :type key: str or bytes
+        :param kwargs: Additional arguments (revision, limit, sort_order, etc.)
+        :returns: RangeResponse from etcd
+        """
+        return await self.kv.get_response(key, **kwargs)
+
+    async def get(self, key, **kwargs):
+        """
+        Get the value of a key from etcd.
+
+        example usage:
+
+        .. code-block:: python
+
+            >>> import etcd3
+            >>> etcd = etcd3.async_client()
+            >>> await etcd.get('/thing/key')
+            'hello world'
+
+        :param key: key in etcd to get
+        :returns: value of key and metadata
+        :rtype: bytes, ``KVMetadata``
+        """
+        return await self.kv.get(key, **kwargs)
+
+    @_handle_errors
+    async def get_prefix_response(self, key_prefix, **kwargs):
+        """Get a range of keys with a prefix."""
+        return await self.kv.get_prefix_response(key_prefix, **kwargs)
+
+    async def get_prefix(self, key_prefix, **kwargs):
+        """
+        Get a range of keys with a prefix.
+
+        :param key_prefix: first key in range
+        :param keys_only: if True, retrieve only the keys, not the values
+
+        :returns: sequence of (value, metadata) tuples
+        """
+        async for item in self.kv.get_prefix(key_prefix, **kwargs):
+            yield item
+
+    @_handle_errors
+    async def get_range_response(
+        self, range_start, range_end, sort_order=None, sort_target="key", **kwargs
+    ):
+        """Get a range of keys."""
+        return await self.kv.get_range_response(
+            range_start,
+            range_end,
+            sort_order=sort_order,
+            sort_target=sort_target,
+            **kwargs,
+        )
+
+    async def get_range(self, range_start, range_end, **kwargs):
+        """
+        Get a range of keys.
+
+        :param range_start: first key in range
+        :param range_end: last key in range
+        :returns: sequence of (value, metadata) tuples
+        """
+        async for item in self.kv.get_range(range_start, range_end, **kwargs):
+            yield item
+
+    @_handle_errors
+    async def get_all_response(
+        self, sort_order=None, sort_target="key", keys_only=False
+    ):
+        """Get all keys currently stored in etcd."""
+        return await self.kv.get_all_response(
+            sort_order=sort_order, sort_target=sort_target, keys_only=keys_only
+        )
+
+    async def get_all(self, **kwargs):
+        """
+        Get all keys currently stored in etcd.
+
+        :param keys_only: if True, retrieve only the keys, not the values
+        :returns: sequence of (value, metadata) tuples
+        """
+        async for item in self.kv.get_all(**kwargs):
+            yield item
+
+    @_handle_errors
+    @monitor_request("kv.put", is_async=True)
+    @log_operation_async("kv.put")
+    async def put(
+        self,
+        key,
+        value=None,
+        lease=None,
+        prev_kv=False,
+        ignore_value=False,
+        ignore_lease=False,
+    ):
+        """
+        Save a value to etcd.
+
+        Example usage:
+
+        .. code-block:: python
+
+            >>> import etcd3
+            >>> etcd = etcd3.async_client()
+            >>> await etcd.put('/thing/key', 'hello world')
+
+        :param key: key in etcd to set
+        :param value: value to set key to
+        :type value: bytes
+        :param lease: Lease to associate with this key.
+        :type lease: either :class:`.Lease`, or int (ID of lease)
+        :param prev_kv: return the previous key-value pair
+        :type prev_kv: bool
+        :param ignore_value: if True, update the key using the current value
+        :type ignore_value: bool
+        :param ignore_lease: if True, update the key using the current lease
+        :type ignore_lease: bool
+        :returns: a response containing a header and the prev_kv
+        :rtype: :class:`.rpc_pb2.PutResponse`
+        """
+        return await self.kv.put(
+            key,
+            value=value,
+            lease=lease,
+            prev_kv=prev_kv,
+            ignore_value=ignore_value,
+            ignore_lease=ignore_lease,
+        )
+
+    @_handle_errors
+    async def put_if_not_exists(self, key, value, lease=None):
+        """
+        Atomically puts a value only if the key previously had no value.
+
+        This is the etcdv3 equivalent to setting a key with the etcdv2
+        parameter prevExist=false.
+
+        :param key: key in etcd to put
+        :param value: value to be written to key
+        :type value: bytes
+        :param lease: Lease to associate with this key.
+        :type lease: either :class:`.Lease`, or int (ID of lease)
+        :returns: state of transaction, ``True`` if the put was successful,
+                  ``False`` otherwise
+        :rtype: bool
+        """
+        return await self.kv.put_if_not_exists(key, value, lease=lease)
+
+    @_handle_errors
+    async def replace(self, key, initial_value, new_value):
+        """
+        Atomically replace the value of a key with a new value.
+
+        This compares the current value of a key, then replaces it with a new
+        value if it is equal to a specified value. This operation takes place
+        in a transaction.
+
+        :param key: key in etcd to replace
+        :param initial_value: old value to replace
+        :type initial_value: bytes
+        :param new_value: new value of the key
+        :type new_value: bytes
+        :returns: status of transaction, ``True`` if the replace was
+                  successful, ``False`` otherwise
+        :rtype: bool
+        """
+        return await self.kv.replace(key, initial_value, new_value)
+
+    def _ops_to_requests(self, ops):
+        """
+        Return a list of grpc requests.
+
+        Returns list from an input list of etcd3.transactions.{Put, Get,
+        Delete, Txn} objects.
+        """
+        request_ops = []
+        for op in ops:
+            if isinstance(op, transactions.Put):
+                put_request = etcdrpc.PutRequest()
+                put_request.key = utils.to_bytes(op.key)
+                put_request.value = utils.to_bytes(op.value)
+                put_request.lease = utils.lease_to_id(getattr(op, "lease", None))
+                put_request.prev_kv = getattr(op, "prev_kv", False)
+                request_op = etcdrpc.RequestOp(request_put=put_request)
+                request_ops.append(request_op)
+
+            elif isinstance(op, transactions.Get):
+                range_request = self._build_get_range_request(op.key, op.range_end)
+                request_op = etcdrpc.RequestOp(request_range=range_request)
+                request_ops.append(request_op)
+
+            elif isinstance(op, transactions.Delete):
+                delete_request = etcdrpc.DeleteRangeRequest()
+                delete_request.key = utils.to_bytes(op.key)
+                delete_request.prev_kv = op.prev_kv
+                if op.range_end is not None:
+                    delete_request.range_end = utils.to_bytes(op.range_end)
+                request_op = etcdrpc.RequestOp(request_delete_range=delete_request)
+                request_ops.append(request_op)
+
+            elif isinstance(op, transactions.Txn):
+                compare = [c.build_message() for c in op.compare]
+                success_ops = self._ops_to_requests(op.success)
+                failure_ops = self._ops_to_requests(op.failure)
+                txn_request = etcdrpc.TxnRequest(
+                    compare=compare, success=success_ops, failure=failure_ops
+                )
+                request_op = etcdrpc.RequestOp(request_txn=txn_request)
+                request_ops.append(request_op)
+
+            else:
+                raise ValueError(f"Unknown request type: {op.__class__}")
+        return request_ops
+
+    @_handle_errors
+    @monitor_request("kv.transaction", is_async=True)
+    @log_operation_async("kv.transaction")
+    async def transaction(self, compare, success=None, failure=None):
+        """
+        Perform a transaction.
+
+        Example usage:
+
+        .. code-block:: python
+
+            await etcd.transaction(
+                compare=[
+                    etcd.transactions.value('/doot/testing') == 'doot',
+                    etcd.transactions.version('/doot/testing') > 0,
+                ],
+                success=[
+                    etcd.transactions.put('/doot/testing', 'success'),
+                ],
+                failure=[
+                    etcd.transactions.put('/doot/testing', 'failure'),
+                ]
+            )
+
+        :param compare: A list of comparisons to make
+        :param success: A list of operations to perform if all the comparisons
+                        are true
+        :param failure: A list of operations to perform if any of the
+                        comparisons are false
+        :return: A tuple of (operation status, responses)
+        """
+        compare = [c.build_message() for c in compare]
+
+        success_ops = self._ops_to_requests(success or [])
+        failure_ops = self._ops_to_requests(failure or [])
+
+        transaction_request = etcdrpc.TxnRequest(
+            compare=compare, success=success_ops, failure=failure_ops
+        )
+
+        # Create KV stub with auto-reconnection
+        channel = await self._get_channel()
+        kv_stub = etcdrpc.KVStub(channel)
+        txn_response = await kv_stub.Txn(
+            transaction_request,
+            timeout=self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+        responses = []
+        for response in txn_response.responses:
+            response_type = response.WhichOneof("response")
+            if response_type == "response_range":
+                responses.append(
+                    [
+                        (kv.value, KVMetadata(kv, txn_response.header))
+                        for kv in response.response_range.kvs
+                    ]
+                )
+            elif response_type == "response_put":
+                responses.append(response.response_put)
+            elif response_type == "response_delete_range":
+                responses.append(response.response_delete_range)
+            elif response_type == "response_txn":
+                responses.append(response.response_txn)
+            else:
+                # Unknown response type - raise error for visibility
+                raise exceptions.InternalServerError(
+                    f"Unknown transaction response type: {response_type}"
+                )
+
+        return txn_response.succeeded, responses
+
+    @_handle_errors
+    @monitor_request("kv.delete", is_async=True)
+    @log_operation_async("kv.delete")
+    async def delete(self, key, prev_kv=False, return_response=False, range_end=None):
+        """
+        Delete a key or range of keys in etcd.
+
+        :param key: key in etcd to delete
+        :type key: str or bytes
+        :param prev_kv: return the deleted key-value pair
+        :type prev_kv: bool
+        :param return_response: return the full response
+        :type return_response: bool
+        :param range_end: End of the key range (for range deletes)
+        :type range_end: str or bytes, optional
+        :returns: True if the key has been deleted when
+                  ``return_response`` is False and a response containing
+                  a header, the number of deleted keys and prev_kvs when
+                  ``return_response`` is True
+        """
+        return await self.kv.delete(
+            key, prev_kv=prev_kv, return_response=return_response, range_end=range_end
+        )
+
+    @_handle_errors
+    @monitor_request("kv.delete_prefix", is_async=True)
+    @log_operation_async("kv.delete_prefix")
+    async def delete_prefix(self, prefix):
+        """Delete a range of keys with a prefix in etcd."""
+        return await self.kv.delete_prefix(prefix)
+
+    @_handle_errors
+    @monitor_request("lease.create", is_async=True)
+    @log_operation_async("lease.create")
+    async def lease(self, ttl, lease_id=None):
+        """
+        Create a new lease.
+
+        All keys attached to this lease will be expired and deleted if the
+        lease expires. A lease can be sent keep alive messages to refresh the
+        ttl.
+
+        :param ttl: Requested time to live
+        :param lease_id: Requested ID for the lease
+
+        :returns: new lease
+        :rtype: :class:`.AsyncLease`
+        """
+        return await self.lease_ops.lease(ttl, lease_id=lease_id)
+
+    @_handle_errors
+    @monitor_request("lease.revoke", is_async=True)
+    @log_operation_async("lease.revoke")
+    async def revoke_lease(self, lease_id):
+        """
+        Revoke a lease.
+
+        :param lease_id: ID of the lease to revoke.
+        """
+        return await self.lease_ops.revoke_lease(lease_id)
+
+    @_handle_generator_errors
+    async def refresh_lease(self, lease_id):
+        """
+        Refresh a lease.
+
+        :param lease_id: ID of the lease to refresh.
+        :returns: Async generator of keep alive responses
+        """
+        async for response in self.lease_ops.refresh_lease(lease_id):
+            yield response
+
+    @_handle_errors
+    @monitor_request("lease.get_info", is_async=True)
+    @log_operation_async("lease.get_info")
+    async def get_lease_info(self, lease_id):
+        """
+        Get lease information.
+
+        :param lease_id: ID of the lease to get information about.
+        :returns: Lease information
+        """
+        return await self.lease_ops.get_lease_info(lease_id)
+
+    @_handle_errors
+    async def lock(self, name, ttl=60):
+        """
+        Create a new async lock.
+
+        :param name: name of the lock
+        :type name: string or bytes
+        :param ttl: length of time for the lock to live for in seconds. The
+                    lock will be released after this time elapses, unless
+                    refreshed
+        :type ttl: int
+        :returns: new async lock
+        :rtype: :class:`.AsyncLock`
+        """
+        return await self.lock_ops.lock(name, ttl=ttl)
+
+    async def add_member(self, urls):
+        """
+        Add a member into the cluster.
+
+        :returns: new member
+        :rtype: :class:`.Member`
+        """
+        return await self.cluster_ops.add_member(urls)
+
+    async def remove_member(self, member_id):
+        """
+        Remove an existing member from the cluster.
+
+        :param member_id: ID of the member to remove
+        """
+        return await self.cluster_ops.remove_member(member_id)
+
+    async def update_member(self, member_id, peer_urls):
+        """
+        Update the configuration of an existing member in the cluster.
+
+        :param member_id: ID of the member to update
+        :param peer_urls: new list of peer urls the member will use to
+                          communicate with the cluster
+        """
+        return await self.cluster_ops.update_member(member_id, peer_urls)
+
+    async def members(self):
+        """
+        List of all members associated with the cluster.
+
+        :type: sequence of :class:`.Member`
+
+        """
+        async for member in self.cluster_ops.members():
+            yield member
+
+    async def status(self):
+        """Get the status of the responding member."""
+        return await self.maintenance_ops.status()
+
+    @_handle_errors
+    @monitor_request("maintenance.compact", is_async=True)
+    @log_operation_async("maintenance.compact")
+    async def compact(self, revision, physical=False):
+        """
+        Compact the event history in etcd up to a given revision.
+
+        All superseded keys with a revision less than the compaction revision
+        will be removed.
+
+        :param revision: revision for the compaction operation
+        :param physical: if set to True, the request will wait until the
+                         compaction is physically applied to the local database
+                         such that compacted entries are totally removed from
+                         the backend database
+        """
+        return await self.maintenance_ops.compact(revision, physical=physical)
+
+    async def defragment(self):
+        """Defragment a member's backend database to recover storage space."""
+        return await self.maintenance_ops.defragment()
+
+    async def hash(self):
+        """
+        Return the hash of the local KV state.
+
+        :returns: kv state hash
+        :rtype: int
+        """
+        return await self.maintenance_ops.hash()
+
+    async def create_alarm(self, member_id=0):
+        """Create an alarm.
+
+        If no member id is given, the alarm is activated for all the
+        members of the cluster. Only the `no space` alarm can be raised.
+
+        :param member_id: The cluster member id to create an alarm to.
+                          If 0, the alarm is created for all the members
+                          of the cluster.
+        :returns: list of :class:`.Alarm`
+        """
+        return await self.maintenance_ops.create_alarm(member_id)
+
+    @_handle_generator_errors
+    async def list_alarms(self, member_id=0, alarm_type="none"):
+        """List the activated alarms.
+
+        :param member_id:
+        :param alarm_type: The cluster member id to create an alarm to.
+                           If 0, the alarm is created for all the members
+                           of the cluster.
+        :returns: sequence of :class:`.Alarm`
+        """
+        async for alarm in self.maintenance_ops.list_alarms(member_id, alarm_type):
+            yield alarm
+
+    async def disarm_alarm(self, member_id=0):
+        """Cancel an alarm.
+
+        :param member_id: The cluster member id to cancel an alarm.
+                          If 0, the alarm is canceled for all the members
+                          of the cluster.
+        :returns: List of :class:`.Alarm`
+        """
+        return await self.maintenance_ops.disarm_alarm(member_id)
+
+    async def snapshot(self, file_obj):
+        """Take a snapshot of the database.
+
+        :param file_obj: A file-like object to write the database contents in.
+        """
+        return await self.maintenance_ops.snapshot(file_obj)
+
+    @monitor_request("watch.add_callback", is_async=True)
+    @log_operation_async("watch.add_callback")
+    async def add_watch_callback(self, *args, **kwargs):
+        """
+        Watch a key or range of keys and call a callback on every response.
+
+        If timeout was declared during the client initialization and
+        the watch cannot be created during that time the method raises
+        a ``WatchTimedOut`` exception.
+
+        :param key: key to watch
+        :param callback: callback function
+
+        :returns: watch_id. Later it could be used for cancelling watch.
+        """
+        return await self.watch_ops.add_watch_callback(*args, **kwargs)
+
+    async def add_watch_prefix_callback(self, key_prefix, callback, **kwargs):
+        """
+        Watch a prefix and call a callback on every response.
+
+        If timeout was declared during the client initialization and
+        the watch cannot be created during that time the method raises
+        a ``WatchTimedOut`` exception.
+
+        :param key_prefix: prefix to watch
+        :param callback: callback function
+
+        :returns: watch_id. Later it could be used for cancelling watch.
+        """
+        return await self.watch_ops.add_watch_prefix_callback(
+            key_prefix, callback, **kwargs
+        )
+
+    async def watch_response(self, key, **kwargs):
+        """
+        Watch a key.
+
+        Example usage:
+
+        .. code-block:: python
+
+            responses_iterator, cancel = await etcd.watch_response('/doot/key')
+            async for response in responses_iterator:
+                print(response)
+
+        :param key: key to watch
+
+        :returns: tuple of ``responses_iterator`` and ``cancel``.
+                  Use ``responses_iterator`` to get the watch responses,
+                  each of which contains a header and a list of events.
+                  Use ``cancel`` to cancel the watch request.
+        """
+        return await self.watch_ops.watch_response(key, **kwargs)
+
+    async def watch(self, key, **kwargs):
+        """
+        Watch a key.
+
+        Example usage:
+
+        .. code-block:: python
+
+            events_iterator, cancel = await etcd.watch('/doot/key')
+            async for event in events_iterator:
+                print(event)
+
+        :param key: key to watch
+
+        :returns: tuple of ``events_iterator`` and ``cancel``.
+                  Use ``events_iterator`` to get the events of key changes
+                  and ``cancel`` to cancel the watch request.
+        """
+        return await self.watch_ops.watch(key, **kwargs)
+
+    async def watch_prefix_response(self, key_prefix, **kwargs):
+        """
+        Watch a range of keys with a prefix.
+
+        :param key_prefix: prefix to watch
+
+        :returns: tuple of ``responses_iterator`` and ``cancel``.
+        """
+        return await self.watch_ops.watch_prefix_response(key_prefix, **kwargs)
+
+    async def watch_prefix(self, key_prefix, **kwargs):
+        """
+        Watch a range of keys with a prefix.
+
+        :param key_prefix: prefix to watch
+
+        :returns: tuple of ``events_iterator`` and ``cancel``.
+        """
+        return await self.watch_ops.watch_prefix(key_prefix, **kwargs)
+
+    async def watch_once_response(self, key, timeout=None, **kwargs):
+        """
+        Watch a key and stop after the first response.
+
+        If the timeout was specified and response didn't arrive method
+        will raise ``WatchTimedOut`` exception.
+
+        :param key: key to watch
+        :param timeout: (optional) timeout in seconds.
+
+        :returns: ``WatchResponse``
+        """
+        return await self.watch_ops.watch_once_response(key, timeout=timeout, **kwargs)
+
+    async def watch_once(self, key, timeout=None, **kwargs):
+        """
+        Watch a key and stop after the first event.
+
+        If the timeout was specified and event didn't arrive method
+        will raise ``WatchTimedOut`` exception.
+
+        :param key: key to watch
+        :param timeout: (optional) timeout in seconds.
+
+        :returns: ``Event``
+        """
+        return await self.watch_ops.watch_once(key, timeout=timeout, **kwargs)
+
+    async def watch_prefix_once_response(self, key_prefix, timeout=None, **kwargs):
+        """
+        Watch a range of keys with a prefix and stop after the first response.
+
+        If the timeout was specified and response didn't arrive method
+        will raise ``WatchTimedOut`` exception.
+        """
+        return await self.watch_ops.watch_prefix_once_response(
+            key_prefix, timeout=timeout, **kwargs
+        )
+
+    async def watch_prefix_once(self, key_prefix, timeout=None, **kwargs):
+        """
+        Watch a range of keys with a prefix and stop after the first event.
+
+        If the timeout was specified and event didn't arrive method
+        will raise ``WatchTimedOut`` exception.
+        """
+        return await self.watch_ops.watch_prefix_once(
+            key_prefix, timeout=timeout, **kwargs
+        )
+
+    @monitor_request("watch.cancel", is_async=True)
+    @log_operation_async("watch.cancel")
+    async def cancel_watch(self, watch_id):
+        """
+        Stop watching a key or range of keys.
+
+        :param watch_id: watch_id returned by ``add_watch_callback`` method
+        """
+        return await self.watch_ops.cancel_watch(watch_id)
+
+
+async def async_client(
+    config=None,
+    host="localhost",
+    port=2379,
+    ca_cert=None,
+    cert_key=None,
+    cert_cert=None,
+    timeout=None,
+    user=None,
+    password=None,
+    grpc_options=None,
+):
+    """Return an instance of an AsyncEtcd3Client.
+
+    :param config: AsyncClientConfig object with client configuration
+    :param host: etcd host (ignored if config is provided)
+    :param port: etcd port (ignored if config is provided)
+    :param ca_cert: CA certificate path (ignored if config is provided)
+    :param cert_key: client certificate key path (ignored if config is provided)
+    :param cert_cert: client certificate path (ignored if config is provided)
+    :param timeout: request timeout in seconds (ignored if config is provided)
+    :param user: username for authentication (ignored if config is provided)
+    :param password: password for authentication (ignored if config is provided)
+    :param grpc_options: additional gRPC options (ignored if config is provided)
+    :return: AsyncEtcd3Client instance
+    """
+    # Auto-initialize observability
+    from etcd3.observability import auto_init
+
+    auto_init()
+
+    # Use config object if provided, otherwise use individual parameters
+    if config is not None:
+        host = config.host
+        port = config.port
+        ca_cert = config.ca_cert
+        cert_key = config.cert_key
+        cert_cert = config.cert_cert
+        timeout = config.timeout
+        user = config.user
+        password = config.password
+        grpc_options = config.grpc_options
+
+    credentials = None
+    secure = True
+
+    if ca_cert is not None:
+        credentials = AsyncMultiEndpointEtcd3Client.get_secure_creds(
+            ca_cert, cert_key, cert_cert
+        )
+    else:
+        secure = False
+
+    endpoint = AsyncEndpoint(
+        host=host, port=port, secure=secure, creds=credentials, opts=grpc_options
+    )
+    return AsyncMultiEndpointEtcd3Client(
+        endpoints=[endpoint], timeout=timeout, user=user, password=password
+    )
+
+
+# Create alias for backward compatibility
+AsyncEtcd3Client = AsyncMultiEndpointEtcd3Client