nui-python-shared-utils 2.2__tar.gz → 2.3__tar.gz

{nui_python_shared_utils-2.2 → nui_python_shared_utils-2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nui-python-shared-utils
-Version: 2.2
+Version: 2.3
 Summary: Shared Python utilities for AWS Lambda, CLI tools, and agents with Slack, Elasticsearch, and monitoring integrations
 Home-page: https://github.com/nuimarkets/nui-python-shared-utils
 Author: NUI Markets

{nui_python_shared_utils-2.2 → nui_python_shared_utils-2.3}/docs/guides/powertools-integration.md

@@ -179,6 +179,22 @@ def powertools_handler(
     """
 ```
 
+### When the Handler Raises
+
+The decorator logs the exception and sends the Slack alert (if configured), then:
+
+- **SQS events** (`Records[0].eventSource == "aws:sqs"`, checked before the handler runs):
+  re-raises. A returned error dict tells the event source mapping the batch succeeded (with
+  `ReportBatchItemFailures`, a response without `batchItemFailures` means every record did),
+  so the batch would be deleted. Re-raising leaves it on the queue for redelivery; it moves
+  to a DLQ after `maxReceiveCount` only if the queue has a redrive policy. The whole batch
+  comes back, records the handler already processed included, so a handler with
+  `batchSize` above 1 must be idempotent or catch per record. On a FIFO queue the message
+  group waits until the batch succeeds or redrives, and the Slack alert fires on every
+  receive. For per-record retries, enable `ReportBatchItemFailures` on the mapping and
+  return `{"batchItemFailures": [...]}` from the handler; the decorator passes it through.
+- **Every other event**: returns `{"statusCode": 500, "body": "Internal Server Error"}`.
+
 ### Basic Usage (Logging Only)
 
 ```python

{nui_python_shared_utils-2.2 → nui_python_shared_utils-2.3}/nui_shared_utils/powertools_helpers.py

@@ -145,6 +145,17 @@ def get_powertools_logger(
     return powertools_logger
 
 
+def _is_sqs_event(event: Any) -> bool:
+    """True when ``event`` is a batch delivered by an SQS event source mapping."""
+    if not isinstance(event, dict):
+        return False
+    records = event.get("Records")
+    if not isinstance(records, list) or not records:
+        return False
+    first = records[0]
+    return isinstance(first, dict) and first.get("eventSource") == "aws:sqs"
+
+
 def powertools_handler(
     service_name: str,
     metrics_namespace: Optional[str] = None,
@@ -199,8 +210,17 @@ def powertools_handler(
         ...     return {"statusCode": 200}
 
     Note:
-        The decorated handler must return a dict with statusCode and optional body.
-        On exception, returns: {"statusCode": 500, "body": "Internal Server Error"}
+        The handler's return value passes through unchanged: a ``statusCode`` dict
+        for API Gateway, ``{"batchItemFailures": [...]}`` for an SQS mapping with
+        ``ReportBatchItemFailures``.
+
+        On exception, returns ``{"statusCode": 500, "body": "Internal Server Error"}``,
+        except for SQS events, where the exception is re-raised after logging and
+        alerting. A returned value tells the SQS mapping the batch succeeded (with
+        ``ReportBatchItemFailures``, a response without ``batchItemFailures`` means
+        every record did), so the 500 dict would delete the batch. Re-raising leaves
+        it on the queue for redelivery, and in the DLQ after ``maxReceiveCount``
+        when the queue has a redrive policy.
     """
 
     def decorator(func: Callable) -> Callable:
@@ -231,6 +251,9 @@ def powertools_handler(
             if slack_client:
                 slack_client.set_handler_context(context)
 
+            # Classify before the handler runs: it may consume or mutate event["Records"].
+            is_sqs = _is_sqs_event(event)
+
             try:
                 # Apply logger context injection
                 # Note: inject_lambda_context is added dynamically to logging.Logger (line 95)
@@ -274,6 +297,10 @@ def powertools_handler(
                     except Exception as slack_error:
                         logger.warning("Failed to send Slack alert: %s", slack_error)
 
+                # Re-raise for SQS so the batch stays on the queue; see the Note above.
+                if is_sqs:
+                    raise
+
                 # Return proper Lambda error response
                 return {
                     "statusCode": 500,

{nui_python_shared_utils-2.2 → nui_python_shared_utils-2.3}/tests/test_powertools_helpers.py

@@ -334,6 +334,153 @@ class TestPowertoolsHandler:
         assert result["body"] == "Internal Server Error"
 
 
+def _sqs_event(*message_ids):
+    return {"Records": [{"messageId": mid, "eventSource": "aws:sqs", "body": "{}"} for mid in message_ids]}
+
+
+class TestPowertoolsHandlerSqs:
+    """An SQS batch must stay on the queue when the handler raises.
+
+    Any value returned to an SQS event source mapping counts as success, so
+    returning the 500 dict deletes the batch: no redelivery, no DLQ.
+    """
+
+    def test_sqs_exception_is_reraised(self, monkeypatch):
+        monkeypatch.delenv("AWS_LAMBDA_RUNTIME_API", raising=False)
+
+        from nui_shared_utils.powertools_helpers import powertools_handler
+
+        error = ConnectionError("Error reading SSH protocol banner")
+
+        @powertools_handler(service_name="test-service")
+        def handler(event, context):
+            raise error
+
+        with pytest.raises(ConnectionError) as excinfo:
+            handler(_sqs_event("m-1", "m-2"), MagicMock())
+
+        assert excinfo.value is error
+
+    def test_sqs_exception_alerts_slack_before_reraising(self, monkeypatch):
+        monkeypatch.delenv("AWS_LAMBDA_RUNTIME_API", raising=False)
+
+        mock_slack_client = MagicMock()
+
+        with patch("nui_shared_utils.powertools_helpers.SLACK_CLIENT_AVAILABLE", True):
+            with patch("nui_shared_utils.powertools_helpers.SlackClient", return_value=mock_slack_client):
+                from nui_shared_utils.powertools_helpers import powertools_handler
+
+                @powertools_handler(service_name="test-service", slack_alert_channel="#errors")
+                def handler(event, context):
+                    raise ValueError("Test error")
+
+                with pytest.raises(ValueError):
+                    handler(_sqs_event("m-1"), MagicMock())
+
+                mock_slack_client.send_message.assert_called_once()
+
+    def test_sqs_reraises_original_exception_when_slack_fails(self, monkeypatch):
+        """A failed alert must not replace the handler's exception or swallow it."""
+        monkeypatch.delenv("AWS_LAMBDA_RUNTIME_API", raising=False)
+
+        mock_slack_client = MagicMock()
+        mock_slack_client.send_message.side_effect = RuntimeError("Slack API error")
+
+        with patch("nui_shared_utils.powertools_helpers.SLACK_CLIENT_AVAILABLE", True):
+            with patch("nui_shared_utils.powertools_helpers.SlackClient", return_value=mock_slack_client):
+                from nui_shared_utils.powertools_helpers import powertools_handler
+
+                @powertools_handler(service_name="test-service", slack_alert_channel="#errors")
+                def handler(event, context):
+                    raise ValueError("Test error")
+
+                with pytest.raises(ValueError, match="Test error"):
+                    handler(_sqs_event("m-1"), MagicMock())
+
+    def test_sqs_detected_before_the_handler_consumes_records(self, monkeypatch):
+        monkeypatch.delenv("AWS_LAMBDA_RUNTIME_API", raising=False)
+
+        from nui_shared_utils.powertools_helpers import powertools_handler
+
+        @powertools_handler(service_name="test-service")
+        def handler(event, context):
+            event.pop("Records")
+            raise ValueError("Test error")
+
+        with pytest.raises(ValueError):
+            handler(_sqs_event("m-1"), MagicMock())
+
+    def test_sqs_reraises_after_metrics_flush(self, monkeypatch):
+        monkeypatch.delenv("AWS_LAMBDA_RUNTIME_API", raising=False)
+
+        flushed = []
+
+        def log_metrics(func):
+            def inner(event, context):
+                try:
+                    return func(event, context)
+                finally:
+                    flushed.append(True)
+
+            return inner
+
+        mock_metrics = MagicMock()
+        mock_metrics.log_metrics = log_metrics
+
+        with patch("nui_shared_utils.powertools_helpers.POWERTOOLS_AVAILABLE", True):
+            with patch("nui_shared_utils.powertools_helpers.Metrics", return_value=mock_metrics):
+                from nui_shared_utils.powertools_helpers import powertools_handler
+
+                @powertools_handler(service_name="test-service", metrics_namespace="Test/Metrics")
+                def handler(event, context):
+                    raise ValueError("Test error")
+
+                with pytest.raises(ValueError):
+                    handler(_sqs_event("m-1"), MagicMock())
+
+        assert flushed == [True]
+
+    def test_sqs_success_returns_handler_result(self, monkeypatch):
+        monkeypatch.delenv("AWS_LAMBDA_RUNTIME_API", raising=False)
+
+        from nui_shared_utils.powertools_helpers import powertools_handler
+
+        @powertools_handler(service_name="test-service")
+        def handler(event, context):
+            return {"batchItemFailures": [{"itemIdentifier": "m-2"}]}
+
+        result = handler(_sqs_event("m-1", "m-2"), MagicMock())
+
+        assert result == {"batchItemFailures": [{"itemIdentifier": "m-2"}]}
+
+    @pytest.mark.parametrize(
+        "event",
+        [
+            {"Records": [{"EventSource": "aws:sns", "Sns": {}}]},
+            {"Records": [{"eventSource": "aws:kinesis", "kinesis": {}}]},
+            {"Records": [{"eventSource": "aws:dynamodb", "dynamodb": {}}]},
+            {"Records": [{"eventSource": "aws:s3", "s3": {}}]},
+            {"Records": []},
+            {"Records": "not-a-list"},
+            {"source": "aws.events", "detail-type": "Scheduled Event"},
+            ["not", "a", "dict"],
+        ],
+        ids=["sns", "kinesis", "dynamodb", "s3", "empty-records", "records-not-list", "scheduled", "non-dict"],
+    )
+    def test_non_sqs_events_keep_returning_500(self, monkeypatch, event):
+        monkeypatch.delenv("AWS_LAMBDA_RUNTIME_API", raising=False)
+
+        from nui_shared_utils.powertools_helpers import powertools_handler
+
+        @powertools_handler(service_name="test-service")
+        def handler(event, context):
+            raise ValueError("Test error")
+
+        result = handler(event, MagicMock())
+
+        assert result == {"statusCode": 500, "body": "Internal Server Error"}
+
+
 class TestOptionalImports:
     """Tests for graceful degradation of optional dependencies"""