wexample-queue 1.1.0__tar.gz → 2.0.0__tar.gz

{wexample_queue-1.1.0 → wexample_queue-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wexample-queue
-Version: 1.1.0
+Version: 2.0.0
 Summary: Manage Queuing
 Author-Email: weeger <contact@wexample.com>
 License: MIT
@@ -9,8 +9,8 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Requires-Dist: pika>=1.3.0
-Requires-Dist: wexample-app>=19.2.0
-Requires-Dist: wexample-helpers>=20.0.0
+Requires-Dist: wexample-app>=19.3.0
+Requires-Dist: wexample-helpers>=20.1.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -18,7 +18,7 @@ Description-Content-Type: text/markdown
 
 # queue
 
-Version: 1.1.0
+Version: 2.0.0
 
 `wexample-queue` is what a worker needs to live on a RabbitMQ queue and nothing more: a connector holding the broker connection, and a service base whose whole subject is one queue. A subclass writes the name of the queue and what to do with a message; connecting, declaring, decoding, acknowledging and giving up are the same for every worker and are already written.
 
@@ -203,8 +203,8 @@ Visit the [Wexample Suite documentation](https://docs.wexample.com) for the comp
 ## Dependencies
 
 - pika: >=1.3.0
-- wexample-app: >=19.2.0
-- wexample-helpers: >=20.0.0
+- wexample-app: >=19.3.0
+- wexample-helpers: >=20.1.0
 
 ## Versioning & Compatibility Policy
 

{wexample_queue-1.1.0 → wexample_queue-2.0.0}/README.md

@@ -1,6 +1,6 @@
 # queue
 
-Version: 1.1.0
+Version: 2.0.0
 
 `wexample-queue` is what a worker needs to live on a RabbitMQ queue and nothing more: a connector holding the broker connection, and a service base whose whole subject is one queue. A subclass writes the name of the queue and what to do with a message; connecting, declaring, decoding, acknowledging and giving up are the same for every worker and are already written.
 
@@ -185,8 +185,8 @@ Visit the [Wexample Suite documentation](https://docs.wexample.com) for the comp
 ## Dependencies
 
 - pika: >=1.3.0
-- wexample-app: >=19.2.0
-- wexample-helpers: >=20.0.0
+- wexample-app: >=19.3.0
+- wexample-helpers: >=20.1.0
 
 ## Versioning & Compatibility Policy
 

{wexample_queue-1.1.0 → wexample_queue-2.0.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "wexample-queue"
-version = "1.1.0"
+version = "2.0.0"
 description = "Manage Queuing"
 authors = [
     { name = "weeger", email = "contact@wexample.com" },
@@ -19,8 +19,8 @@ classifiers = [
 ]
 dependencies = [
     "pika>=1.3.0",
-    "wexample-app>=19.2.0",
-    "wexample-helpers>=20.0.0",
+    "wexample-app>=19.3.0",
+    "wexample-helpers>=20.1.0",
 ]
 
 [project.readme]

{wexample_queue-1.1.0 → wexample_queue-2.0.0}/src/wexample_queue/connector/rabbitmq_external_connector.py

@@ -10,10 +10,9 @@ from wexample_helpers.classes.field import public_field
 from wexample_helpers.decorator.base_class import base_class
 
 if TYPE_CHECKING:
-    from collections.abc import Callable
-
     from wexample_helpers.const.types import StringsList
 
+RABBITMQ_ENV_KEY_HEARTBEAT = "RABBITMQ_HEARTBEAT"
 RABBITMQ_ENV_KEY_HOST = "RABBITMQ_HOST"
 RABBITMQ_ENV_KEY_PASSWORD = "RABBITMQ_PASSWORD"
 RABBITMQ_ENV_KEY_PORT = "RABBITMQ_PORT"
@@ -45,11 +44,27 @@ class RabbitmqExternalConnector(AbstractExternalConnector):
         default="rabbitmq",
         description="Name this connector answers to",
     )
+    thread_id: int | None = public_field(
+        default=None,
+        description="The thread that opened the connection, the only one allowed to use it",
+    )
+
+    def ack(self, delivery_tag: int) -> None:
+        self.channel.basic_ack(delivery_tag)
 
     def connect(self) -> None:
         if self.connected:
             return
 
+        import os
+        import threading
+
+        parameters: dict[str, Any] = {}
+        # Seconds between two signs of life; the broker's proposal when unset.
+        heartbeat = os.environ.get(RABBITMQ_ENV_KEY_HEARTBEAT)
+        if heartbeat:
+            parameters["heartbeat"] = int(heartbeat)
+
         self.connection = pika.BlockingConnection(
             pika.ConnectionParameters(
                 host=self._env(RABBITMQ_ENV_KEY_HOST),
@@ -58,17 +73,12 @@ class RabbitmqExternalConnector(AbstractExternalConnector):
                     self._env(RABBITMQ_ENV_KEY_USER),
                     self._env(RABBITMQ_ENV_KEY_PASSWORD),
                 ),
+                **parameters,
             )
         )
         self.channel = self.connection.channel()
         self.connected = True
-
-    def consume(self, queue_name: str, callback: Callable) -> None:
-        """Hands the channel over to the callback until consumption is stopped."""
-        self.channel.basic_consume(
-            queue=queue_name, on_message_callback=callback
-        )
-        self.channel.start_consuming()
+        self.thread_id = threading.get_ident()
 
     def declare_queue(self, queue_name: str) -> None:
         """Makes sure the queue is there, durable, whoever gets there first.
@@ -83,11 +93,26 @@ class RabbitmqExternalConnector(AbstractExternalConnector):
         if not self.connected:
             return
 
-        self.connection.close()
+        # A connection the broker already dropped cannot be closed again.
+        if self.connection.is_open:
+            self.connection.close()
         self.connection = None
         self.channel = None
         self.connected = False
 
+    def get(self, queue_name: str) -> tuple[int, bytes] | None:
+        """Takes the next message off the queue, or nothing when it is empty.
+
+        Pulled one at a time rather than pushed: a message the broker pushes
+        while the previous one is still being worked on would wait unacknowledged
+        in the client, and be dropped by the broker's delivery timeout long
+        before its turn came.
+        """
+        method, _properties, body = self.channel.basic_get(queue=queue_name)
+        if method is None:
+            return None
+        return method.delivery_tag, body
+
     def get_expected_env_keys(self) -> StringsList:
         return [
             RABBITMQ_ENV_KEY_HOST,
@@ -96,13 +121,29 @@ class RabbitmqExternalConnector(AbstractExternalConnector):
             RABBITMQ_ENV_KEY_PASSWORD,
         ]
 
+    def nack(self, delivery_tag: int) -> None:
+        """Gives a message up, without putting it back on the queue."""
+        self.channel.basic_nack(delivery_tag, requeue=False)
+
     def publish(self, queue_name: str, payload: dict[str, Any]) -> None:
         """Puts one message on the queue, marked to survive a broker restart.
 
         It goes through the default exchange, whose routing key is the queue
         name — which is also where a Symfony Messenger transport declaring that
         queue binds its own exchange, so both land in the same place.
+
+        Callable from any thread: a connection belongs to the thread that opened
+        it, so from another one the publication is handed over to that thread,
+        which sends it the next time it tends the connection.
         """
+        import threading
+
+        if threading.get_ident() != self.thread_id:
+            self.connection.add_callback_threadsafe(
+                lambda: self.publish(queue_name, payload)
+            )
+            return
+
         import json
 
         self.channel.basic_publish(
@@ -112,8 +153,10 @@ class RabbitmqExternalConnector(AbstractExternalConnector):
             properties=pika.BasicProperties(delivery_mode=2),
         )
 
-    def stop_consuming(self) -> None:
-        self.channel.stop_consuming()
+    def sleep(self, seconds: float) -> None:
+        """Waits while keeping the connection alive — heartbeats answered, and
+        what other threads handed over sent."""
+        self.connection.sleep(seconds)
 
     def _env(self, key: str) -> str:
         """One of the four keys, from the process environment or from wex's own.

wexample_queue-2.0.0/src/wexample_queue/service/abstract_queue_service.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from wexample_app.service.abstract_service import AbstractService
+from wexample_helpers.classes.abstract_method import abstract_method
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+
+if TYPE_CHECKING:
+    from wexample_queue.connector.rabbitmq_external_connector import (
+        RabbitmqExternalConnector,
+    )
+
+
+@base_class
+class AbstractQueueService(AbstractService):
+    """A service whose work is whatever arrives on one queue.
+
+    All a subclass writes is the name of the queue and what to do with a
+    message. Connecting, taking, decoding, acknowledging, keeping the connection
+    alive and coming back after losing it are the same for every worker, so they
+    are here.
+
+    A message may take hours. It is worked on in a thread of its own while this
+    one tends the connection — answering the broker's heartbeats, sending what
+    the work publishes — so the broker never takes a long job for a dead worker.
+    """
+
+    ACKNOWLEDGE_ON_RECEIPT: ClassVar[bool] = False
+    """Acknowledge a message as soon as it is taken, rather than once done.
+
+    For work longer than the broker allows a message to stay unacknowledged
+    (`consumer_timeout`, 30 minutes by default), and whose outcome is recorded
+    somewhere else: a message acknowledged at once is never delivered twice,
+    and nothing the work does can make the broker put it back.
+    """
+    POLL_INTERVAL: ClassVar[float] = 1.0
+    """Seconds between two looks at an empty queue."""
+    RECONNECT_DELAY: ClassVar[float] = 5.0
+    """Seconds before trying again once the connection is lost."""
+    connector: RabbitmqExternalConnector | None = public_field(
+        default=None,
+        description="The broker connection, opened when the service starts",
+    )
+    queue_name: str = public_field(
+        description="Name of the queue this service consumes",
+    )
+
+    def on_idle(self) -> None:
+        """Called each time the queue is found empty. Nothing by default."""
+
+    def on_tick(self, message: dict[str, Any]) -> None:
+        """Called about once a second while a message is being worked on, from the
+        thread that tends the connection. Nothing by default."""
+
+    @abstract_method
+    def process_message(self, message: dict[str, Any]) -> None:
+        """What to do with one message, already decoded — in a thread of its own.
+
+        Returning means the message is acknowledged. Raising means it is given
+        up on — so a subclass that wants a message tried again has to say so by
+        putting it back itself. With `ACKNOWLEDGE_ON_RECEIPT`, it is acknowledged
+        before this is called, whatever comes of it.
+        """
+
+    def start(self) -> None:
+        self._connect()
+
+        super().start()
+
+    def stop(self) -> None:
+        if self.connector:
+            self.connector.disconnect()
+
+        super().stop()
+
+    def _connect(self) -> None:
+        from wexample_queue.connector.rabbitmq_external_connector import (
+            RabbitmqExternalConnector,
+        )
+
+        self.connector = RabbitmqExternalConnector(kernel=self.kernel)
+        self.connector.connect()
+        self.connector.declare_queue(self.queue_name)
+
+    def _decode(self, body: bytes) -> dict[str, Any] | None:
+        import json
+
+        try:
+            return json.loads(body.decode())
+        except json.JSONDecodeError as exception:
+            self.io.error(
+                f"[{self.get_snake_short_class_name()}] Message is not JSON: {exception}",
+                fatal=False,
+            )
+            return None
+
+    def _handle(self, delivery_tag: int, body: bytes) -> None:
+        """Works one message through, keeping the connection alive meanwhile.
+
+        A message that cannot be read, or that the service could not get
+        through, is rejected without being put back: requeueing it would be
+        asking for the same failure at once and for ever.
+        """
+        import threading
+
+        message = self._decode(body)
+        if message is None:
+            self.connector.nack(delivery_tag)
+            return
+
+        if self.ACKNOWLEDGE_ON_RECEIPT:
+            self.connector.ack(delivery_tag)
+
+        outcome: dict[str, Any] = {}
+
+        def work() -> None:
+            try:
+                self.process_message(message)
+            except Exception as exception:
+                import traceback
+
+                outcome["error"] = exception
+                self.io.debug(traceback.format_exc())
+
+        import time
+
+        from pika.exceptions import AMQPError
+
+        worker = threading.Thread(target=work, name=f"{self.queue_name}-message")
+        worker.start()
+
+        # Losing the connection does not stop the work: it is let finish, the
+        # connection being opened again afterwards, and nothing else is taken
+        # meanwhile.
+        lost: AMQPError | None = None
+        while worker.is_alive():
+            if lost is None:
+                try:
+                    self.connector.sleep(self.POLL_INTERVAL)
+                except AMQPError as exception:
+                    lost = exception
+            else:
+                time.sleep(self.POLL_INTERVAL)
+            self.on_tick(message)
+
+        if lost is not None:
+            # An unacknowledged message is given back by the broker with the
+            # connection it was delivered on; one acknowledged on receipt is done.
+            raise lost
+
+        if "error" in outcome:
+            self.io.error(
+                f"[{self.get_snake_short_class_name()}] Message failed: {outcome['error']}",
+                fatal=False,
+            )
+
+        if not self.ACKNOWLEDGE_ON_RECEIPT:
+            if "error" in outcome:
+                self.connector.nack(delivery_tag)
+            else:
+                self.connector.ack(delivery_tag)
+
+    def _run(self) -> None:
+        """One turn: the next message worked through, or a short wait.
+
+        A lost connection is opened again rather than ending the service: a
+        worker left running for a night outlives the odd network hiccup, and a
+        broker restarted under it.
+        """
+        from pika.exceptions import AMQPError
+
+        try:
+            if not self.connector or not self.connector.connected:
+                self._connect()
+                self.log(f"Consuming messages on queue « {self.queue_name} »...")
+
+            delivery = self.connector.get(self.queue_name)
+            if delivery is None:
+                self.on_idle()
+                self.connector.sleep(self.POLL_INTERVAL)
+                return
+
+            self._handle(*delivery)
+        except AMQPError as exception:
+            self.io.error(
+                f"[{self.get_snake_short_class_name()}] Connection lost: "
+                f"{type(exception).__name__}: {exception}. Reconnecting in "
+                f"{self.RECONNECT_DELAY:.0f}s.",
+                fatal=False,
+            )
+            if self.connector:
+                self.connector.connected = False
+            import time
+
+            time.sleep(self.RECONNECT_DELAY)

wexample_queue-1.1.0/src/wexample_queue/service/abstract_queue_service.py

@@ -1,99 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any
-
-from wexample_app.service.abstract_service import AbstractService
-from wexample_helpers.classes.abstract_method import abstract_method
-from wexample_helpers.classes.field import public_field
-from wexample_helpers.decorator.base_class import base_class
-
-if TYPE_CHECKING:
-    from wexample_queue.connector.rabbitmq_external_connector import (
-        RabbitmqExternalConnector,
-    )
-
-
-@base_class
-class AbstractQueueService(AbstractService):
-    """A service whose work is whatever arrives on one queue.
-
-    All a subclass writes is the name of the queue and what to do with a
-    message. Connecting, declaring, decoding, acknowledging and giving up are
-    the same for every worker, so they are here.
-    """
-
-    connector: RabbitmqExternalConnector | None = public_field(
-        default=None,
-        description="The broker connection, opened when the service starts",
-    )
-    queue_name: str = public_field(
-        description="Name of the queue this service consumes",
-    )
-
-    @abstract_method
-    def process_message(self, message: dict[str, Any]) -> None:
-        """What to do with one message, already decoded.
-
-        Returning means the message is acknowledged. Raising means it is given
-        up on — so a subclass that wants a message tried again has to say so by
-        putting it back itself.
-        """
-
-    def start(self) -> None:
-        from wexample_queue.connector.rabbitmq_external_connector import (
-            RabbitmqExternalConnector,
-        )
-
-        self.connector = RabbitmqExternalConnector(kernel=self.kernel)
-        self.connector.connect()
-        self.connector.declare_queue(self.queue_name)
-
-        super().start()
-
-    def stop(self) -> None:
-        if self.connector:
-            self.connector.stop_consuming()
-            self.connector.disconnect()
-
-        super().stop()
-
-    def _on_message(self, channel, method_frame, header_frame, body) -> None:
-        """Decodes one delivery and answers the broker for it.
-
-        A message that cannot be read, or that the service could not get
-        through, is rejected without being put back: requeueing it would be
-        asking for the same failure at once and for ever. Where it goes then is
-        the broker's business — a dead letter exchange if the queue has one,
-        nowhere if it has not.
-        """
-        import json
-
-        try:
-            message = json.loads(body.decode())
-        except json.JSONDecodeError as exception:
-            self.io.error(
-                f"[{self.get_snake_short_class_name()}] Message is not JSON: {exception}",
-                fatal=False,
-            )
-            channel.basic_nack(method_frame.delivery_tag, requeue=False)
-            return
-
-        try:
-            self.process_message(message)
-        except Exception as exception:
-            import traceback
-
-            self.io.error(
-                f"[{self.get_snake_short_class_name()}] Message failed: {exception}",
-                fatal=False,
-            )
-            self.io.debug(traceback.format_exc())
-            channel.basic_nack(method_frame.delivery_tag, requeue=False)
-            return
-
-        channel.basic_ack(method_frame.delivery_tag)
-
-    def _run(self) -> None:
-        self.log(f"Consuming messages on queue « {self.queue_name} »...")
-
-        self.connector.consume(self.queue_name, self._on_message)