reach_commons 0.18.26__tar.gz → 0.18.27__tar.gz

{reach_commons-0.18.26 → reach_commons-0.18.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reach_commons
-Version: 0.18.26
+Version: 0.18.27
 Summary: Reach Commons is a versatile utility library designed to streamline and enhance development workflows within the Reach ecosystem.
 License: MIT
 Author: Engineering

{reach_commons-0.18.26 → reach_commons-0.18.27}/pyproject.toml

@@ -1,7 +1,7 @@
 # isort .; black .; poetry build; poetry publish
 [tool.poetry]
 name = "reach_commons"
-version = "0.18.26"
+version = "0.18.27"
 description = "Reach Commons is a versatile utility library designed to streamline and enhance development workflows within the Reach ecosystem."
 authors = ["Engineering <engineering@getreach.ai>"]
 license = "MIT"

{reach_commons-0.18.26 → reach_commons-0.18.27}/reach_commons/reach_aws/sqs.py

@@ -146,38 +146,61 @@ class SQSClient(BaseSQSClient):
 
         return True
 
-    def get_visible_messages_count(self) -> int:
+    def get_queue_metrics(self) -> dict:
+        """
+        Retorna métricas aproximadas da fila SQS.
+
+        {
+            "visible": int,
+            "in_flight": int,
+            "delayed": int,
+            "oldest_age_seconds": int,
+        }
+        """
         try:
             resp = self.client.get_queue_attributes(
                 QueueUrl=self.topic_name,
                 AttributeNames=[
-                    "ApproximateNumberOfMessages",
-                    "ApproximateNumberOfMessagesNotVisible",
-                    "ApproximateNumberOfMessagesDelayed",
+                    "ApproximateNumberOfMessages",  # visible
+                    "ApproximateNumberOfMessagesNotVisible",  # in-flight
+                    "ApproximateNumberOfMessagesDelayed",  # delayed
+                    "ApproximateAgeOfOldestMessage",
                 ],
             )
-            visible = int(resp["Attributes"].get("ApproximateNumberOfMessages", 0))
-            in_flight = int(
-                resp["Attributes"].get("ApproximateNumberOfMessagesNotVisible", 0)
-            )
-            delayed = int(
-                resp["Attributes"].get("ApproximateNumberOfMessagesDelayed", 0)
-            )
 
-            return visible, in_flight, delayed
+            attrs = resp.get("Attributes", {})
+
+            visible = int(attrs.get("ApproximateNumberOfMessages", 0))
+            in_flight = int(attrs.get("ApproximateNumberOfMessagesNotVisible", 0))
+            delayed = int(attrs.get("ApproximateNumberOfMessagesDelayed", 0))
+            oldest_age_seconds = int(attrs.get("ApproximateAgeOfOldestMessage", 0))
+
+            return {
+                "visible": visible,
+                "in_flight": in_flight,
+                "delayed": delayed,
+                "oldest_age_seconds": oldest_age_seconds,
+            }
+
         except ClientError as exc:
             self.logger.error(
                 "error_fetching_queue_attributes, topic_name=%s, error=%s",
                 self.topic_name,
                 str(exc),
             )
-            # If there's an error, return 0 so as not to block the caller.
-            return 0, 0, 0
+
+            return {
+                "visible": 0,
+                "in_flight": 0,
+                "delayed": 0,
+                "oldest_age_seconds": 0,
+            }
 
     def publish_with_capacity_guard(
         self,
         message_data: dict,
-        max_capacity: int,
+        max_visible_capacity: int,
+        max_total_capacity: int = None,
         delay_seconds: int = 60,
         message_attributes: dict = None,
     ) -> dict:
@@ -185,44 +208,56 @@ class SQSClient(BaseSQSClient):
         Attempts to publish a message while enforcing an approximate queue capacity limit.
 
         Behavior:
-            - If the queue is below `max_capacity`, the message is published normally.
-            - If the queue is at or above `max_capacity`, the message is NOT published.
+            - If the queue is below `max_visible_capacity` (and optional `max_total_capacity`),
+              the message is published normally.
+            - If the queue is at or above the threshold(s), the message is NOT published.
 
         Returns a dict with:
-            - posted: bool        -> whether the message was actually published
-            - visible_count: int  -> ApproximateNumberOfMessages at publication time
-            - max_capacity: int   -> the capacity threshold used
-
-        Example:
-            sqs = SQSClient(topic_name="<enviroment>-messages-queue")
-
-            Result = sqs.publish_with_capacity_guard(
-                message_data={"foo": "bar"},
-                max_capacity=100_000,
-                delay_seconds=30,
-                message_attributes={"service_name": "TestClient"},
-            )
-
-            if not Result["posted"]:
-                print("Queue is over capacity:", Result)
+            - posted: bool
+            - visible_count: int
+            - in_flight_count: int
+            - delayed_count: int
+            - oldest_age_seconds: int
+            - max_visible_capacity: int
+            - max_total_capacity: int | None
         """
-        (
-            visible_count,
-            in_flight_count,
-            delayed_count,
-        ) = self.get_visible_messages_count()
+        metrics = self.get_queue_metrics()
+        visible = metrics["visible"]
+        in_flight = metrics["in_flight"]
+        delayed = metrics["delayed"]
+        oldest_age_seconds = metrics["oldest_age_seconds"]
+
+        total_active = visible + in_flight
+
+        over_visible = visible >= max_visible_capacity
+        over_total = (
+            max_total_capacity is not None and total_active >= max_total_capacity
+        )
 
-        if visible_count >= max_capacity:
+        if over_visible or over_total:
             self.logger.warning(
-                "queue_over_capacity, topic_name=%s, visible=%s, max_capacity=%s",
+                (
+                    "queue_over_capacity, topic_name=%s, "
+                    "visible=%s, in_flight=%s, delayed=%s, oldest_age_seconds=%s, "
+                    "total_active=%s, max_visible_capacity=%s, max_total_capacity=%s"
+                ),
                 self.topic_name,
-                visible_count,
-                max_capacity,
+                visible,
+                in_flight,
+                delayed,
+                oldest_age_seconds,
+                total_active,
+                max_visible_capacity,
+                max_total_capacity,
             )
             return {
                 "posted": False,
-                "visible_count": visible_count,
-                "max_capacity": max_capacity,
+                "visible_count": visible,
+                "in_flight_count": in_flight,
+                "delayed_count": delayed,
+                "oldest_age_seconds": oldest_age_seconds,
+                "max_visible_capacity": max_visible_capacity,
+                "max_total_capacity": max_total_capacity,
             }
 
         self.publish(
@@ -233,10 +268,12 @@ class SQSClient(BaseSQSClient):
 
         return {
             "posted": True,
-            "visible_count": visible_count,
-            "in_flight_count": in_flight_count,
-            "delayed_count": delayed_count,
-            "max_capacity": max_capacity,
+            "visible_count": visible,
+            "in_flight_count": in_flight,
+            "delayed_count": delayed,
+            "oldest_age_seconds": oldest_age_seconds,
+            "max_visible_capacity": max_visible_capacity,
+            "max_total_capacity": max_total_capacity,
         }