ondewo-client-utils 4.0.0__py3-none-any.whl

ondewo/__init__.py

@@ -0,0 +1,7 @@
+"""Namespace package root for the ``ondewo`` distribution family.
+
+Extends ``__path__`` via :func:`pkgutil.extend_path` so that sibling ``ondewo.*``
+distributions installed in separate locations share the single ``ondewo`` namespace.
+"""
+
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)  # type: ignore

ondewo/utils/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2020-2026 ONDEWO GmbH
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Utilities and abstract base classes shared by ONDEWO gRPC Python clients."""

ondewo/utils/async_base_client.py

@@ -0,0 +1,164 @@
+# Copyright 2017-2026 ONDEWO GmbH
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Abstract base class for asynchronous ONDEWO gRPC Python clients.
+
+Provides the async counterpart of ``BaseClient`` with awaitable ``connect`` and
+``disconnect`` methods that manage the lifecycle of the underlying gRPC channels.
+"""
+
+import dataclasses
+from abc import (
+    ABC,
+    abstractmethod,
+)
+from typing import (
+    Any,
+    Optional,
+    Set,
+    Tuple,
+)
+
+from ondewo.utils.base_client_config import BaseClientConfig
+from ondewo.utils.base_service_container import BaseServicesContainer
+
+
+class AsyncBaseClient(ABC):
+    """
+    Abstract base class for async ONDEWO clients.
+
+    Attributes:
+        services: A container for the service clients initialized by the client.
+    """
+
+    def __init__(
+        self,
+        config: BaseClientConfig,
+        use_secure_channel: bool = True,
+        options: Optional[Set[Tuple[str, Any]]] = None,
+    ) -> None:
+        """
+        Initialize the async client and its service clients.
+
+        Args:
+            config (BaseClientConfig):
+                Configuration for the client.
+            use_secure_channel (bool):
+                Whether to use a secure gRPC channel. Defaults to ``True``.
+            options (Optional[Set[Tuple[str, Any]]]):
+                Additional options for the gRPC channel. Defaults to ``None``.
+
+        Raises:
+            ValueError:
+                If the ``services`` attribute is not defined after initialization.
+        """
+        self.services: Optional[BaseServicesContainer] = None
+        self._initialize_services(
+            config=config,
+            use_secure_channel=use_secure_channel,
+            options=options,
+        )
+
+        if not self.services:
+            raise ValueError(f"The attribute `services` must be defined in class {self.__class__.__name__}.")
+
+    @abstractmethod
+    def _initialize_services(
+        self,
+        config: BaseClientConfig,
+        use_secure_channel: bool,
+        options: Optional[Set[Tuple[str, Any]]] = None,
+    ) -> None:
+        """
+        Initialize the service clients.
+
+        Args:
+            config (BaseClientConfig):
+                Configuration for the client.
+            use_secure_channel (bool):
+                Whether to use a secure gRPC channel.
+            options (Optional[Set[Tuple[str, Any]]]):
+                Additional options for the gRPC channel. Defaults to ``None``.
+        """
+        pass
+
+    async def connect(
+        self,
+        config: BaseClientConfig,
+        use_secure_channel: bool,
+        options: Optional[Set[Tuple[str, Any]]] = None,
+    ) -> None:
+        """
+        Establish a connection to the services.
+
+        Args:
+            config (BaseClientConfig):
+                Configuration for the client.
+            use_secure_channel (bool):
+                Whether to use a secure gRPC channel.
+            options (Optional[Set[Tuple[str, Any]]]):
+                Additional options for the gRPC channel. Defaults to ``None``.
+
+        Raises:
+            ConnectionError:
+                If a connection is already established.
+        """
+        if self.services:
+            raise ConnectionError("The current client already has an open connection.")
+
+        self._initialize_services(
+            config=config,
+            use_secure_channel=use_secure_channel,
+            options=options,
+        )
+
+    async def disconnect(self) -> None:
+        """
+        Asynchronously close every service's gRPC channel and clear the services.
+
+        Every field of the services dataclass is visited, inherited ones included, and a channel
+        shared by several services (see ``build_shared_channel``) is closed exactly once. A
+        ``close()`` that raises does not leave the remaining channels open: every channel is
+        attempted, ``services`` is cleared regardless, and the first error is re-raised.
+
+        Raises:
+            AttributeError:
+                If the ``services`` attribute is not defined.
+            Exception:
+                The first exception raised by a channel's ``close()``, after all channels were
+                attempted.
+        """
+        if not self.services:
+            raise AttributeError("The attribute `services` is not defined.")
+
+        first_error: Optional[BaseException] = None
+        closed: Set[int] = set()
+        try:
+            # dataclasses.fields() and not __annotations__: on Python 3.14 an instance has no
+            # __annotations__ (PEP 649), and on every version __annotations__ omits the fields a
+            # parent container declares, so their channels leaked.
+            for service_field in dataclasses.fields(self.services):
+                channel: Any = getattr(self.services, service_field.name).grpc_channel
+                if id(channel) in closed:
+                    continue
+                closed.add(id(channel))
+                try:
+                    await channel.close(grace=None)
+                except Exception as error:
+                    first_error = first_error or error
+        finally:
+            self.services = None
+        if first_error is not None:
+            raise first_error

ondewo/utils/async_base_services_interface.py

@@ -0,0 +1,283 @@
+# Copyright 2020-2026 ONDEWO GmbH
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Async gRPC service interface base classes and channel factory helpers.
+
+Async counterpart of ``base_services_interface`` built on ``grpc.aio``: it
+provides channel factory helpers and the abstract ``AsyncBaseServicesInterface``.
+"""
+
+import logging
+import struct
+from abc import (
+    ABC,
+    abstractmethod,
+)
+from functools import lru_cache
+from typing import (
+    Any,
+    Dict,
+    List,
+    Optional,
+    Set,
+    Tuple,
+    Union,
+)
+
+import grpc
+
+from ondewo.utils.base_client_config import BaseClientConfig
+from ondewo.utils.grpc_retry_policy import (
+    build_service_config_json,
+    service_config_json_for,
+    service_config_json_for_classes,
+)
+
+# A module logger, never the root one: logging.warning() at module level runs basicConfig() and
+# installs a stderr handler on the HOST application's root logger.
+_LOGGER: logging.Logger = logging.getLogger(__name__)
+
+MAX_MESSAGE_LENGTH: int = 2 ** (struct.Struct("i").size * 8 - 1) - 1
+
+# The default channel options are constant and assembled once at import time so that
+# building a client with many services stays cheap (ultra low latency). The retry policy is
+# per service: only idempotent methods are retried (see ``ondewo.utils.grpc_retry_policy``).
+# ``_SERVICE_CONFIG_JSON`` is the config for a class whose services cannot be found, i.e. no
+# method retried beyond gRPC's transparent retries; ``_grpc_options_items_for`` swaps in the
+# per-class config, built once per class and cached.
+_SERVICE_CONFIG_JSON: str = build_service_config_json([])
+
+_DEFAULT_GRPC_OPTIONS: Dict[str, Any] = {
+    "grpc.max_send_message_length": MAX_MESSAGE_LENGTH,
+    "grpc.max_receive_message_length": MAX_MESSAGE_LENGTH,
+    # Keepalive keeps long-lived streaming RPCs warm and detects half-open connections while
+    # data flows. Pings fire only during active calls (permit_without_calls stays False), and
+    # stop after 2 pings without data (gRPC's default): a default grpc-core server
+    # (min_recv_ping_interval_without_data 5 min, max_ping_strikes 2) answers a client that
+    # keeps pinging a silent stream with GOAWAY ENHANCE_YOUR_CALM "too_many_pings", which
+    # tears down the shared connection (measured: UNAVAILABLE after ~50 s at a 10 s keepalive
+    # with 0 = unlimited; the same silent stream completed with 2).
+    "grpc.keepalive_time_ms": 30000,
+    "grpc.keepalive_timeout_ms": 60000,
+    "grpc.keepalive_permit_without_calls": False,
+    "grpc.http2.max_pings_without_data": 2,
+    # "grpc.dns_enable_srv_queries" is deliberately NOT set: it only discovers deprecated grpclb
+    # balancers, which no ONDEWO deployment uses, and cost ~14 ms per channel (median channel
+    # creation + first unary call to 127.0.0.1: 15.9 ms with it, 1.4 ms without). A caller
+    # that runs grpclb can still pass it in ``options``.
+    "grpc.enable_retries": 1,
+    "grpc.service_config": _SERVICE_CONFIG_JSON,
+}
+
+
+@lru_cache(maxsize=None)
+def _grpc_options_items_for(service_class: type) -> List[Tuple[str, Any]]:
+    """
+    Return the default channel options for a service-interface class, built once per class.
+
+    Args:
+        service_class (type):
+            The concrete service-interface class being instantiated.
+
+    Returns:
+        List[Tuple[str, Any]]:
+            The default options with ``grpc.service_config`` set to the class's retry policy.
+    """
+    options: Dict[str, Any] = dict(_DEFAULT_GRPC_OPTIONS)
+    options["grpc.service_config"] = service_config_json_for(service_class)
+    return list(options.items())
+
+
+def get_secure_channel(
+    host: str,
+    cert: Union[str, bytes],
+    options: Optional[List[Tuple[str, Any]]] = None,
+) -> grpc.aio.Channel:
+    """
+    Create a secure asynchronous gRPC channel to the given host.
+
+    Args:
+        host (str):
+            Target address in the form "host:port" to connect to.
+        cert (Union[str, bytes]):
+            Root certificate used to establish the TLS connection. A ``str`` is encoded to
+            ``bytes`` before being handed to gRPC; ``BaseClientConfig.__post_init__`` already
+            supplies ``bytes``.
+        options (Optional[List[Tuple[str, Any]]]):
+            Optional list of gRPC channel options as (key, value) tuples.
+
+    Returns:
+        grpc.aio.Channel:
+            A secure asynchronous gRPC channel connected to the target host.
+    """
+    root_certificates: bytes = cert.encode() if isinstance(cert, str) else cert
+    credentials: grpc.ChannelCredentials = grpc.ssl_channel_credentials(root_certificates=root_certificates)
+    return grpc.aio.secure_channel(
+        target=host,
+        credentials=credentials,
+        options=options,
+    )
+
+
+def _get_grpc_channel(
+    config: BaseClientConfig,
+    use_secure_channel: bool,
+    options: Optional[List[Tuple[str, Any]]] = None,
+) -> grpc.aio.Channel:
+    """
+    Build an asynchronous gRPC channel, secure or insecure, from a client config.
+
+    Args:
+        config (BaseClientConfig):
+            Client configuration providing the host, port and optional certificate.
+        use_secure_channel (bool):
+            Whether to create a secure (TLS) channel. If False an insecure channel
+            is created instead.
+        options (Optional[List[Tuple[str, Any]]]):
+            Optional list of gRPC channel options as (key, value) tuples.
+
+    Returns:
+        grpc.aio.Channel:
+            A secure or insecure asynchronous gRPC channel.
+
+    Raises:
+        ValueError:
+            If a secure channel is requested but the config has no gRPC certificate.
+    """
+    if not use_secure_channel:
+        _LOGGER.warning("Using an INSECURE (plaintext) gRPC channel to %s.", config.host_and_port)
+        return grpc.aio.insecure_channel(target=config.host_and_port, options=options)
+
+    if not config.grpc_cert:
+        # Never interpolate the config itself: a downstream subclass may carry a password field.
+        raise ValueError(
+            f"No grpc certificate found on {type(config).__name__} for {config.host_and_port}; "
+            "pass grpc_cert or use_secure_channel=False."
+        )
+
+    return get_secure_channel(
+        host=config.host_and_port,
+        cert=config.grpc_cert,
+        options=options,
+    )
+
+
+def build_shared_channel(
+    config: BaseClientConfig,
+    use_secure_channel: bool,
+    service_classes: Tuple[type, ...],
+    options: Optional[Set[Tuple[str, Any]]] = None,
+) -> grpc.aio.Channel:
+    """
+    Open ONE channel for several service interfaces: one connection, one TLS handshake, one resolution.
+
+    By default every ``AsyncBaseServicesInterface`` opens its own channel, so a client with N services
+    opens N connections and pays N name resolutions and N TLS handshakes. Build one channel here
+    and hand it to each service with ``grpc_channel=``. The channel's retry policy is the union of
+    the per-class policies (:func:`ondewo.utils.grpc_retry_policy.service_config_json_for_classes`),
+    which gives every method exactly the policy its own channel would have had.
+
+    Args:
+        config (BaseClientConfig):
+            Client configuration providing the host, port and optional gRPC certificate.
+        use_secure_channel (bool):
+            If ``True`` open a secure (TLS) channel; if ``False`` open an insecure channel.
+        service_classes (Tuple[type, ...]):
+            The service-interface classes that will share the channel.
+        options (Optional[Set[Tuple[str, Any]]]):
+            Optional channel option overrides merged on top of the defaults, exactly as
+            ``AsyncBaseServicesInterface.__init__`` merges them; a caller ``grpc.service_config`` wins.
+
+    Returns:
+        grpc.aio.Channel:
+            The shared channel. Closing it (e.g. through ``disconnect``) closes it for every service.
+
+    Raises:
+        ValueError:
+            If a secure channel is requested but the config has no gRPC certificate.
+    """
+    merged_options: Dict[str, Any] = dict(_DEFAULT_GRPC_OPTIONS)
+    merged_options["grpc.service_config"] = service_config_json_for_classes(tuple(service_classes))
+    if options:
+        merged_options.update(dict(options))
+    return _get_grpc_channel(
+        config=config,
+        use_secure_channel=use_secure_channel,
+        options=list(merged_options.items()),
+    )
+
+
+class AsyncBaseServicesInterface(ABC):
+    """
+    Abstract base class for async ONDEWO gRPC service interfaces.
+
+    Attributes:
+        grpc_channel (grpc.aio.Channel):
+            The asynchronous gRPC channel used to communicate with the service.
+    """
+
+    def __init__(
+        self,
+        config: BaseClientConfig,
+        use_secure_channel: bool,
+        options: Optional[Set[Tuple[str, Any]]] = None,
+        *,
+        grpc_channel: Optional[grpc.aio.Channel] = None,
+    ) -> None:
+        """
+        Initialize the async service interface and open its gRPC channel.
+
+        Args:
+            config (BaseClientConfig):
+                Client configuration providing the host, port and optional certificate.
+            use_secure_channel (bool):
+                Whether to create a secure (TLS) channel.
+            options (Optional[Set[Tuple[str, Any]]]):
+                Optional set of gRPC channel options as (key, value) tuples that
+                override the default options. Passing ``("grpc.service_config", <json>)``
+                replaces the default retry policy, which retries idempotent methods only (see
+                ``ondewo.utils.grpc_retry_policy``).
+            grpc_channel (Optional[grpc.aio.Channel]):
+                An already open channel to use instead of opening one, e.g. from
+                :func:`build_shared_channel`. When given, ``config``, ``use_secure_channel`` and
+                ``options`` are ignored and nothing is built. Defaults to ``None``.
+        """
+        if grpc_channel is not None:
+            self.grpc_channel: grpc.aio.Channel = grpc_channel
+            return
+
+        default_options: List[Tuple[str, Any]] = _grpc_options_items_for(type(self))
+        if options:
+            merged_options: Dict[str, Any] = dict(default_options)
+            merged_options.update(dict(options))
+            updated_options: List[Tuple[str, Any]] = list(merged_options.items())
+        else:
+            updated_options = default_options
+
+        self.grpc_channel = _get_grpc_channel(
+            config=config,
+            use_secure_channel=use_secure_channel,
+            options=updated_options,
+        )
+
+    @property
+    @abstractmethod
+    def stub(self) -> Any:
+        """
+        Return the concrete gRPC stub used to issue RPC calls.
+
+        Returns:
+            Any:
+                The gRPC service stub implemented by the concrete subclass.
+        """
+        pass

ondewo/utils/base_client.py

@@ -0,0 +1,160 @@
+# Copyright 2017-2026 ONDEWO GmbH
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Abstract base class providing the synchronous scaffolding for ONDEWO gRPC clients."""
+
+import dataclasses
+from abc import (
+    ABC,
+    abstractmethod,
+)
+from typing import (
+    Any,
+    Optional,
+    Set,
+    Tuple,
+)
+
+from ondewo.utils.base_client_config import BaseClientConfig
+from ondewo.utils.base_service_container import BaseServicesContainer
+
+
+class BaseClient(ABC):
+    """
+    Abstract base class for ONDEWO clients.
+
+    Attributes:
+        services (Optional[BaseServicesContainer]):
+            A container for the service clients initialized by the client, or ``None`` when the
+            client is not connected.
+    """
+
+    def __init__(
+        self,
+        config: BaseClientConfig,
+        use_secure_channel: bool = True,
+        options: Optional[Set[Tuple[str, Any]]] = None,
+    ) -> None:
+        """
+        Initialize the client and its service clients.
+
+        Args:
+            config (BaseClientConfig):
+                Configuration for the client.
+            use_secure_channel (bool):
+                Whether to use a secure gRPC channel. Defaults to ``True``.
+            options (Optional[Set[Tuple[str, Any]]]):
+                Additional options for the gRPC channel. Defaults to ``None``.
+
+        Raises:
+            ValueError:
+                If ``_initialize_services`` does not populate the ``services`` attribute.
+        """
+        self.services: Optional[BaseServicesContainer] = None
+        self._initialize_services(
+            config=config,
+            use_secure_channel=use_secure_channel,
+            options=options,
+        )
+
+        if not self.services:
+            raise ValueError(f"The attribute `services` must be defined in class {self.__class__.__name__}.")
+
+    @abstractmethod
+    def _initialize_services(
+        self,
+        config: BaseClientConfig,
+        use_secure_channel: bool,
+        options: Optional[Set[Tuple[str, Any]]] = None,
+    ) -> None:
+        """
+        Initialize the service clients.
+
+        Args:
+            config (BaseClientConfig):
+                Configuration for the client.
+            use_secure_channel (bool):
+                Whether to use a secure gRPC channel.
+            options (Optional[Set[Tuple[str, Any]]]):
+                Additional options for the gRPC channel.
+        """
+        pass
+
+    def connect(
+        self,
+        config: BaseClientConfig,
+        use_secure_channel: bool,
+        options: Optional[Set[Tuple[str, Any]]] = None,
+    ) -> None:
+        """
+        Establish a connection to the services.
+
+        Args:
+            config (BaseClientConfig):
+                Configuration for the client.
+            use_secure_channel (bool):
+                Whether to use a secure gRPC channel.
+            options (Optional[Set[Tuple[str, Any]]]):
+                Additional options for the gRPC channel.
+
+        Raises:
+            ConnectionError: If a connection is already established.
+        """
+        if self.services:
+            raise ConnectionError("The current client already has an open connection.")
+
+        self._initialize_services(
+            config=config,
+            use_secure_channel=use_secure_channel,
+            options=options,
+        )
+
+    def disconnect(self) -> None:
+        """
+        Close every service's gRPC channel and clear the services.
+
+        Every field of the services dataclass is visited, inherited ones included, and a channel
+        shared by several services (see ``build_shared_channel``) is closed exactly once. A
+        ``close()`` that raises does not leave the remaining channels open: every channel is
+        attempted, ``services`` is cleared regardless, and the first error is re-raised.
+
+        Raises:
+            AttributeError:
+                If the ``services`` attribute is not defined.
+            Exception:
+                The first exception raised by a channel's ``close()``, after all channels were
+                attempted.
+        """
+        if not self.services:
+            raise AttributeError("The attribute `services` is not defined.")
+
+        first_error: Optional[BaseException] = None
+        closed: Set[int] = set()
+        try:
+            # dataclasses.fields() and not __annotations__: on Python 3.14 an instance has no
+            # __annotations__ (PEP 649), and on every version __annotations__ omits the fields a
+            # parent container declares, so their channels leaked.
+            for service_field in dataclasses.fields(self.services):
+                channel: Any = getattr(self.services, service_field.name).grpc_channel
+                if id(channel) in closed:
+                    continue
+                closed.add(id(channel))
+                try:
+                    channel.close()
+                except Exception as error:
+                    first_error = first_error or error
+        finally:
+            self.services = None
+        if first_error is not None:
+            raise first_error