intersect-sdk 0.6.1a1__tar.gz

intersect_sdk-0.6.1a1/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.1
+Name: intersect-sdk
+Version: 0.6.1a1
+Summary: Python SDK to interact with INTERSECT
+Keywords: intersect
+Author-Email: Lance Drane <dranelt@ornl.gov>, Marshall McDonnell <mcdonnellmt@ornl.gov>, Seth Hitefield <hitefieldsd@ornl.gov>, Andrew Ayres <ayresaf@ornl.gov>, Gregory Cage <cagege@ornl.gov>, Jesse McGaha <mcgahajr@ornl.gov>, Robert Smith <smithrw@ornl.gov>, Gavin Wiggins <wigginsg@ornl.gov>
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: <4.0,>=3.8.10
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: retrying<2.0.0,>=1.3.4
+Requires-Dist: paho-mqtt<2.0.0,>=1.6.1
+Requires-Dist: minio>=7.2.3
+Requires-Dist: jsonschema[format-nongpl]>=4.21.1
+Requires-Dist: pika<2.0.0,>=1.3.2; extra == "amqp"
+Requires-Dist: eval-type-backport>=0.1.3; extra == "py38"
+Provides-Extra: amqp
+Provides-Extra: py38
+Description-Content-Type: text/markdown
+
+# INTERSECT-SDK
+
+The INTERSECT-SDK is a framework for microservices to integrate themselves into the wider INTERSECT ecosystem.
+
+Please note that this README is currently a work in progress.
+
+## What is INTERSECT?
+
+INTERSECT was designed as a specific usecase - as an open federated hardware/software architecture for the laboratory of the future, which connects scientific instruments, robot-controlled laboratories and edge/center computing/data resources to enable autonomous experiments, self-driving laboratories, smart manufacturing, and AI-driven design, discovery and evaluation.
+
+## What are the core design philosophies of the SDK?
+
+- Event-driven architecture
+- Support core interaction types: request/response, events, commands, statuses
+- Borrows several concepts from [AsyncAPI](https://www.asyncapi.com/docs/reference/specification/latest), and intends to support multiple different protocols. Currently, we support MQTT 3.1.1 and AMQP 0.9.1, but other protocols will be supported as well.
+- Users automatically generate schema from code; schemas are part of the core contract of an INTERSECT microservice, and both external inputs and microservice outputs are required to uphold this contract.

intersect_sdk-0.6.1a1/README.md

@@ -0,0 +1,16 @@
+# INTERSECT-SDK
+
+The INTERSECT-SDK is a framework for microservices to integrate themselves into the wider INTERSECT ecosystem.
+
+Please note that this README is currently a work in progress.
+
+## What is INTERSECT?
+
+INTERSECT was designed as a specific usecase - as an open federated hardware/software architecture for the laboratory of the future, which connects scientific instruments, robot-controlled laboratories and edge/center computing/data resources to enable autonomous experiments, self-driving laboratories, smart manufacturing, and AI-driven design, discovery and evaluation.
+
+## What are the core design philosophies of the SDK?
+
+- Event-driven architecture
+- Support core interaction types: request/response, events, commands, statuses
+- Borrows several concepts from [AsyncAPI](https://www.asyncapi.com/docs/reference/specification/latest), and intends to support multiple different protocols. Currently, we support MQTT 3.1.1 and AMQP 0.9.1, but other protocols will be supported as well.
+- Users automatically generate schema from code; schemas are part of the core contract of an INTERSECT microservice, and both external inputs and microservice outputs are required to uphold this contract.

intersect_sdk-0.6.1a1/pyproject.toml

@@ -0,0 +1,222 @@
+[project]
+name = "intersect-sdk"
+description = "Python SDK to interact with INTERSECT"
+authors = [
+    { name = "Lance Drane", email = "dranelt@ornl.gov" },
+    { name = "Marshall McDonnell", email = "mcdonnellmt@ornl.gov" },
+    { name = "Seth Hitefield", email = "hitefieldsd@ornl.gov" },
+    { name = "Andrew Ayres", email = "ayresaf@ornl.gov" },
+    { name = "Gregory Cage", email = "cagege@ornl.gov" },
+    { name = "Jesse McGaha", email = "mcgahajr@ornl.gov" },
+    { name = "Robert Smith", email = "smithrw@ornl.gov" },
+    { name = "Gavin Wiggins", email = "wigginsg@ornl.gov" },
+]
+readme = "README.md"
+requires-python = ">=3.8.10,<4.0"
+keywords = [
+    "intersect",
+]
+version = "0.6.1a1"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+]
+dependencies = [
+    "pydantic>=2.7.0",
+    "retrying>=1.3.4,<2.0.0",
+    "paho-mqtt>=1.6.1,<2.0.0",
+    "minio>=7.2.3",
+    "jsonschema[format-nongpl]>=4.21.1",
+]
+
+[project.optional-dependencies]
+amqp = [
+    "pika>=1.3.2,<2.0.0",
+]
+py38 = [
+    "eval-type-backport>=0.1.3",
+]
+
+[tool.pdm.dev-dependencies]
+lint = [
+    "pre-commit>=3.3.1",
+    "ruff>=0.4.2",
+    "mypy>=1.10.0",
+    "types-paho-mqtt>=1.6.0.20240106",
+]
+test = [
+    "pytest>=7.3.2",
+    "pytest-cov>=4.1.0",
+    "httpretty>=1.1.4",
+]
+doc = [
+    "sphinx>=5.3.0",
+    "furo>=2023.3.27",
+]
+":lint" = []
+
+[tool.pdm.scripts]
+test-all = "pytest tests/ --cov=src/intersect_sdk/ --cov-fail-under=80 --cov-report=html:reports/htmlcov/ --cov-report=xml:reports/coverage_report.xml --junitxml=reports/junit.xml"
+test-all-debug = "pytest tests/ --cov=src/intersect_sdk/ --cov-fail-under=80 --cov-report=html:reports/htmlcov/ --cov-report=xml:reports/coverage_report.xml --junitxml=reports/junit.xml -s"
+test-unit = "pytest tests/unit --cov=src/intersect_sdk/"
+lint-format = "ruff format"
+lint-ruff = "ruff check --fix"
+lint-mypy = "mypy src/intersect_sdk/"
+
+[tool.pdm.scripts.lint]
+composite = [
+    "lint-format",
+    "lint-ruff",
+    "lint-mypy",
+]
+
+[tool.pdm.build]
+package-dir = "src"
+
+[tool.pdm.version]
+source = "file"
+path = "src/intersect_sdk/version.py"
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.ruff.lint]
+extend-select = [
+    "C90",
+    "I",
+    "N",
+    "D",
+    "UP",
+    "YTT",
+    "ANN",
+    "ASYNC",
+    "S",
+    "BLE",
+    "B",
+    "A",
+    "COM",
+    "C4",
+    "DTZ",
+    "T10",
+    "EM",
+    "FA",
+    "ISC",
+    "ICN",
+    "G",
+    "INP",
+    "PIE",
+    "T20",
+    "PYI",
+    "PT",
+    "Q",
+    "RSE",
+    "RET",
+    "SLF",
+    "SLOT",
+    "SIM",
+    "TCH",
+    "ARG",
+    "PTH",
+    "PGH",
+    "PL",
+    "TRY",
+    "FLY",
+    "RUF",
+]
+ignore = [
+    "COM812",
+    "ISC001",
+    "SIM105",
+    "ANN101",
+    "ANN102",
+    "ANN401",
+    "PLR2004",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = [
+    "src",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.flake8-quotes]
+inline-quotes = "single"
+multiline-quotes = "double"
+
+[tool.ruff.lint.mccabe]
+max-complexity = 20
+
+[tool.ruff.lint.pylint]
+max-args = 10
+max-branches = 20
+max-returns = 10
+
+[tool.ruff.lint.extend-per-file-ignores]
+"__init__.py" = [
+    "F401",
+]
+"docs/*" = [
+    "D",
+    "INP001",
+]
+"examples/*" = [
+    "N999",
+    "T20",
+    "S106",
+    "D100",
+    "D104",
+    "TRY002",
+    "FA100",
+]
+"tests/*" = [
+    "S101",
+    "S106",
+    "S311",
+    "SLF001",
+    "ANN",
+    "ARG",
+    "D",
+    "FA100",
+]
+
+[tool.mypy]
+strict = true
+ignore_missing_imports = true
+disallow_untyped_decorators = false
+plugins = [
+    "pydantic.mypy",
+]
+
+[tool.pydantic-mypy]
+init_forbid_extra = true
+init_typed = true
+warn_required_dynamic_aliases = true
+warn_untyped_fields = true
+
+[tool.pytest.ini_options]
+log_cli = true
+addopts = "-ra"
+
+[tool.coverage.report]
+omit = [
+    "*__init__*",
+]
+exclude_also = [
+    "pragma: no-cover",
+    "if (typing\\\\.)?TYPE_CHECKING:",
+    "@(abc\\\\.)?abstractmethod",
+]
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"

intersect_sdk-0.6.1a1/src/intersect_sdk/__init__.py

@@ -0,0 +1,64 @@
+"""The root module contains the intended public API for users of the INTERSECT-SDK.
+
+Users should not need to import anything outside of the root.
+
+In general, most breaking changes on version updates will relate to:
+  - Configuration classes (both adding and removing new config models). These configuration classes are relevant to the next point.
+  - When a new data service is integrated into INTERSECT, ALL adapters will need to update to support this data service, which will include new dependencies.
+"""
+
+from .app_lifecycle import default_intersect_lifecycle_loop
+from .capability.base import IntersectBaseCapabilityImplementation
+from .client import IntersectClient
+from .client_callback_definitions import (
+    INTERSECT_CLIENT_EVENT_CALLBACK_TYPE,
+    INTERSECT_CLIENT_RESPONSE_CALLBACK_TYPE,
+    INTERSECT_JSON_VALUE,
+    IntersectClientCallback,
+    IntersectClientMessageParams,
+)
+from .config.client import IntersectClientConfig
+from .config.service import IntersectServiceConfig
+from .config.shared import (
+    ControlPlaneConfig,
+    DataStoreConfig,
+    DataStoreConfigMap,
+    HierarchyConfig,
+)
+from .core_definitions import IntersectDataHandler, IntersectMimeType
+from .schema import get_schema_from_capability_implementation
+from .service import IntersectService
+from .service_definitions import (
+    IntersectEventDefinition,
+    intersect_event,
+    intersect_message,
+    intersect_status,
+)
+from .version import __version__, version_info
+
+__all__ = [
+    'IntersectDataHandler',
+    'IntersectEventDefinition',
+    'IntersectMimeType',
+    'intersect_event',
+    'intersect_message',
+    'intersect_status',
+    'get_schema_from_capability_implementation',
+    'IntersectService',
+    'IntersectClient',
+    'IntersectClientCallback',
+    'IntersectClientMessageParams',
+    'INTERSECT_CLIENT_RESPONSE_CALLBACK_TYPE',
+    'INTERSECT_CLIENT_EVENT_CALLBACK_TYPE',
+    'INTERSECT_JSON_VALUE',
+    'IntersectBaseCapabilityImplementation',
+    'default_intersect_lifecycle_loop',
+    'IntersectClientConfig',
+    'IntersectServiceConfig',
+    'HierarchyConfig',
+    'ControlPlaneConfig',
+    'DataStoreConfig',
+    'DataStoreConfigMap',
+    '__version__',
+    'version_info',
+]

intersect_sdk-0.6.1a1/src/intersect_sdk/_internal/__init__.py

@@ -0,0 +1,4 @@
+"""NOTE: It's not advised for users to import anything in this module. These are internal definitions essential for INTERSECT's functions.
+
+THERE IS NO GUARANTEE ANY API DEFINED HERE REMAINS STABLE.
+"""

intersect_sdk-0.6.1a1/src/intersect_sdk/_internal/compression.py.tmp

@@ -0,0 +1,38 @@
+"""Compression logic used inside INTERSECT.
+
+Our current compression algorithm is Brotli - see https://stackoverflow.com/a/59255343 for a fairly comprehensive overview of serialization formats compatible with generic JSON.
+Zstd is worth considering for instances where data isn't being persisted for long, as it is generally faster than Brotli (especially for decompression) - however, Zstd requires multithreading to maximize its potential.
+
+Currently, we will ALWAYS compress the following:
+  - The schemas sent as part of the lifecycle message
+  - The PAYLOADS of UserspaceMessages *if the data itself is being sent in UserspaceMessages* 
+
+We do NOT want to compress message headers, though.  
+
+MINIO should always handle compression itself, see https://min.io/docs/minio/linux/administration/object-management/data-compression.html for details.
+
+TODO - how should the data API handle compression?
+
+TODO - We should consider NOT compressing audio, video, image, or any data which is already compressed.
+"""
+
+import brotli
+
+
+def intersect_compress(message: bytes) -> bytes:
+    """Compress MESSAGE using the compression algorithm, and return compression result.
+    
+    Current compression algorithm is Brotli with the highest level quality.
+    """
+    return brotli.compress(message, quality=11) # type: ignore[no-any-return]
+
+def intersect_decompress(compressed: bytes) -> bytes:
+    """Decompress COMPRESSED using the decompression algorithm, and return decompressed message.
+    
+    Current decompression algorithm is Brotli.
+    """
+    try:
+        return brotli.decompress(compressed) # type: ignore[no-any-return]
+    except brotli.error:
+        # if the parameters weren't compressed with Brotli, just return the input
+        return compressed

intersect_sdk-0.6.1a1/src/intersect_sdk/_internal/constants.py

@@ -0,0 +1,10 @@
+BASE_RESPONSE_ATTR = '__is_intersect_response__'
+BASE_STATUS_ATTR = '__is_intersect_status__'
+BASE_EVENT_ATTR = '__is_intersect_event__'
+# in theory, as long as the next attributes are unique, they can be any string
+REQUEST_CONTENT = '__request_content_type__'
+RESPONSE_CONTENT = '__response_content_type__'
+RESPONSE_DATA = '__response_data_transfer_handler__'
+STRICT_VALIDATION = '__strict_validation__'
+SHUTDOWN_KEYS = '__ignore_message__'
+EVENT_ATTR_KEY = '__intersect_sdk_events__'

intersect_sdk-0.6.1a1/src/intersect_sdk/_internal/control_plane/brokers/amqp_client.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+import functools
+import threading
+import uuid
+from typing import TYPE_CHECKING, Callable
+
+import pika
+from retrying import retry
+
+from .broker_client import BrokerClient
+
+if TYPE_CHECKING:
+    from collections import defaultdict
+
+    from pika.channel import Channel
+    from pika.frame import Frame
+    from pika.spec import Basic, BasicProperties
+
+
+class AMQPClient(BrokerClient):
+    """Client for performing broker actions backed by a AMQP broker.
+
+    NOTE: Currently, thread safety has been attempted, but may not be guaranteed
+
+    Attributes:
+        id: A string representation of the client's UUID.
+        _connection_params: connection information to the AMQP broker (includes credentials)
+        _publish_connection: AMQP connection dedicated to publishing messages
+        _consume_connection: AMQP connection dedicated to consuming messages
+        _topics_to_handlers: Dictionary of string topic names to lists of
+            Callables to invoke for messages on that topic.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        username: str,
+        password: str,
+        topics_to_handlers: Callable[[], defaultdict[str, set[Callable[[bytes], None]]]],
+        uid: str | None = None,
+    ) -> None:
+        """The default constructor.
+
+        Args:
+            host: String for hostname of AMQP broker
+            port: port number of AMQP broker
+            username: username credentials for AMQP broker
+            password: password credentials for AMQP broker
+            topics_to_handlers: callback function which gets the topic to handler map from the channel manager
+            uid: String for the client's UUID.
+        """
+        self.uid = uid if uid else str(uuid.uuid4())
+
+        self._connection_params = pika.ConnectionParameters(
+            host=host,
+            port=port,
+            virtual_host='/',
+            credentials=pika.PlainCredentials(username, password),
+            blocked_connection_timeout=1,
+        )
+
+        # The pika connection to the broker
+        self._publish_connection: pika.adapters.BlockingConnection = None
+        self._consume_connection: pika.adapters.SelectConnection = None
+        self._consume_connection_ready_event = threading.Event()
+        self._consume_subscription_ready_event = threading.Event()
+
+        # Callback to the topics_to_handler list inside of
+        self._topics_to_handlers = topics_to_handlers
+        # mapping of topics to callables which can unsubscribe from the topic
+        self._topics_to_channel_cancel_callbacks: dict[str, Callable[[], None]] = {}
+        self._consumer_thread = None
+
+    @retry(
+        stop_max_attempt_number=5,
+        wait_exponential_multiplier=1000,
+        wait_exponential_max=60000,
+    )
+    def connect(self) -> None:
+        """Connect to the defined broker.
+
+        Try to connect to the broker, performing exponential backoff if connection fails.
+        """
+        # need deamon=True otherwise if tests fails it hangs trying to acquire lock
+        self.thread = threading.Thread(target=self._start_consuming, daemon=True)
+        self.thread.start()
+        self._publish_connection = pika.adapters.BlockingConnection(self._connection_params)
+        self._consume_connection_ready_event.wait(timeout=5)
+
+    def disconnect(self) -> None:
+        """Close all connections.
+
+        Close both the public and consume connections and stop the consuming thread.
+        """
+        self._publish_connection.close()
+        self._publish_connection = None
+        self._consume_connection.ioloop.add_callback_threadsafe(self._close_consume_connection)
+        # as soon as connection is closed, the ioloop.stop will be
+        # called which in turn will terminate the consuming thread
+        self.thread.join(5)
+        self._consume_connection = None
+
+    def is_connected(self) -> bool:
+        """Check if there is an active connection to the broker.
+
+        Returns:
+            A boolean. True if there is a connection, False if not.
+        """
+        # We are connected to the broker if either the publish or consume connections is open
+        return (self._publish_connection is not None and self._publish_connection.is_open) or (
+            self._consume_connection is not None and self._consume_connection.is_open
+        )
+
+    def publish(self, topic: str, payload: bytes) -> None:
+        """Publish the given message.
+
+        Publish payload with the pre-existing connection (via connect()) on topic.
+
+        Args:
+            topic: The topic on which to publish the message as a string
+            payload: The message to publish, as raw bytes.
+        """
+        channel = self._publish_connection.channel()
+        channel.exchange_declare(topic, exchange_type='fanout', durable=True)
+        # this will send the message to topic exchange and distribute to all
+        # queues that subscribed to it
+        channel.basic_publish(
+            exchange=topic,
+            routing_key=topic,
+            body=payload,
+            properties=pika.BasicProperties(content_type='text/plain'),
+        )
+        channel.close()
+
+    def subscribe(self, topic: str) -> None:
+        self._consume_subscription_ready_event.clear()
+        self._subscribe_to_queue(topic)
+        self._consume_subscription_ready_event.wait()
+
+    def unsubscribe(self, topic: str) -> None:
+        old_channel = self._topics_to_channel_cancel_callbacks.get(topic, None)
+        if old_channel:
+            old_channel()
+            del self._topics_to_channel_cancel_callbacks[topic]
+
+    def _start_consuming(self) -> None:
+        """Start consuming messages from broker.
+
+        Open the consuming connection and start its io loop.
+        """
+        self._consume_connection = pika.adapters.SelectConnection(
+            parameters=self._connection_params,
+            on_close_callback=(
+                lambda _connection, _exception: self._consume_connection.ioloop.stop()
+            ),
+            on_open_callback=lambda _connection: self._consume_connection_ready_event.set(),
+        )
+
+        self._consume_connection.ioloop.start()
+
+    def _subscribe_to_queue(self, topic: str) -> None:
+        """Start consuming from the given topic.
+
+        Declares the correct exchange and queue on the broker if needed, then starts
+        consuming messages on that queue.
+
+        Args:
+            topic: Name of the topic on the broker to subscribe to as a string.
+        """
+        # in consumer thread: open channel-> declare queue (need that if we starte
+        # consuming  before message is published (no queue yet)) -> start consuming
+        cb = functools.partial(self._open_channel, topic=topic)
+        self._consume_connection.ioloop.add_callback_threadsafe(cb)
+
+    def _open_channel(self, topic: str) -> None:
+        """Open a channel for the given topic.
+
+        Args:
+            topic: The topic to open a channel for as a string.
+        """
+        cb = functools.partial(self._on_channel_open, topic=topic)
+        self._consume_connection.channel(on_open_callback=cb)
+
+    def _on_channel_open(self, channel: Channel, topic: str) -> None:
+        """Create an exchange on the broker.
+
+        Used as a listener on channel open.
+
+        Args:
+            channel: The Channel being instantiated.
+            topic: The string name for the Channel on the broker.
+        """
+        cb = functools.partial(self._on_exchange_declareok, channel=channel, topic=topic)
+        channel.exchange_declare(exchange=topic, exchange_type='fanout', durable=True, callback=cb)
+
+    def _on_exchange_declareok(self, _unused_frame: Frame, channel: Channel, topic: str) -> None:
+        """Create a queue on the broker.
+
+        Used as a listener on exchange declaration.
+
+        Args:
+            _unused_frame: Object from pika. Ignored.
+            channel: The Channel being instantiated.
+            topic: The string name for the Channel on the broker.
+        """
+        cb = functools.partial(self._on_queue_declareok, channel=channel, topic=topic)
+        channel.queue_declare(queue=topic + '.' + self.uid, durable=True, callback=cb)
+
+    def _on_queue_declareok(self, _unused_frame: Frame, channel: Channel, topic: str) -> None:
+        """Begins listening on the given queue.
+
+        Used as a listener on queue declaration.
+
+        Args:
+            _unused_frame: Object from pika. Ignored.
+            channel: The Channel being instantiated.
+            topic: The string name for the Channel on the broker.
+        """
+        cb = functools.partial(self._on_queue_bindok, channel=channel, topic=topic)
+        channel.queue_bind(topic + '.' + self.uid, topic, routing_key=topic, callback=cb)
+
+    def _on_queue_bindok(self, _unused_frame: Frame, channel: Channel, topic: str) -> None:
+        """Consumes a message from the given channel.
+
+        Used as a listener on queue binding.
+
+        Args:
+            _unused_frame: Object from pika. Ignored.
+            channel: The Channel being instantiated.
+            topic: The string name for the Channel on the broker.
+        """
+        cb = functools.partial(self._on_consume_ok)
+        consumer_tag = channel.basic_consume(
+            queue=topic + '.' + self.uid,
+            auto_ack=True,
+            on_message_callback=self._consume_message,
+            callback=cb,
+        )
+        self._topics_to_channel_cancel_callbacks[topic] = lambda: channel.basic_cancel(consumer_tag)
+
+    def _on_consume_ok(self, _unused_frame: Frame) -> None:
+        """Sets the consume subscription ready even.
+
+        Used as a listener on consuming an initial message on a channel.
+
+        Args:
+            _unused_frame: Object from pika. Ignored.
+            topic: The string name for the Channel on the broker.
+        """
+        self._consume_subscription_ready_event.set()
+
+    def _consume_message(
+        self,
+        _unused_channel: Channel,
+        basic_deliver: Basic.Deliver,
+        _properties: BasicProperties,
+        body: bytes,
+    ) -> None:
+        """Handles incoming messages.
+
+        Looks up all handlers for the topic and delegates message handling to them.
+
+        Args:
+            _unused_channel: The Pika channel the message was received on. Ignored
+            basic_deliver: Contains internal Pika delivery information - i.e. the routing key.
+            _properties: Object from the Pika call. Ignored.
+            body: the pika message to be handled.
+        """
+        for handler in self._topics_to_handlers().get(basic_deliver.routing_key, []):
+            handler(body)
+
+    def _close_consume_connection(self) -> None:
+        """Closes the consume connection.
+
+        Used as a listener on the connection loop to safely shutdown.
+        """
+        self._consume_connection.close()
+        self._topics_to_channel_cancel_callbacks.clear()