clear-skies-aws 2.0.1__py3-none-any.whl → 2.0.3__py3-none-any.whl

clearskies_aws/input_outputs/lambda_api_gateway.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from typing import Any
+
+from clearskies.configs import String
+from clearskies.input_outputs import Headers
+
+from clearskies_aws.input_outputs import lambda_input_output
+
+
+class LambdaApiGateway(lambda_input_output.LambdaInputOutput):
+    """API Gateway v1 and v2 Lambda input/output handler."""
+
+    resource = String(default="")
+
+    def __init__(self, event: dict, context: dict[str, Any]):
+        # Call parent constructor
+        super().__init__(event, context)
+
+        # Determine API Gateway version and parse accordingly
+        version = self._detect_version(event)
+        if version == "1.0":
+            self._parse_event_v1(event)
+        elif version == "2.0":
+            self._parse_event_v2(event)
+        else:
+            raise ValueError(f"Unsupported API Gateway event version: {version}")
+
+    def _detect_version(self, event: dict) -> str:
+        """Detect API Gateway version from event structure."""
+        if "version" in event:
+            return event["version"]
+        elif "httpMethod" in event:
+            return "1.0"  # v1 has httpMethod at root level
+        elif "requestContext" in event and "http" in event["requestContext"]:
+            return "2.0"  # v2 has http in requestContext
+        else:
+            raise ValueError("Unable to determine API Gateway version from event structure")
+
+    def _parse_event_v1(self, event: dict) -> None:
+        """Parse API Gateway v1 event structure."""
+        self.request_method = event.get("httpMethod", "GET").upper()
+        self.path = event.get("path", "/")
+        self.resource = event.get("resource", "")
+
+        # Extract query parameters (v1 has both single and multi-value)
+        self.query_parameters = {
+            **(event.get("queryStringParameters") or {}),
+            **(event.get("multiValueQueryStringParameters") or {}),
+        }
+
+        # Extract headers (v1 has both single and multi-value)
+        headers_dict = {}
+        for key, value in {
+            **event.get("headers", {}),
+            **event.get("multiValueHeaders", {}),
+        }.items():
+            headers_dict[key.lower()] = str(value)
+
+        self.request_headers = Headers(headers_dict)
+
+    def _parse_event_v2(self, event: dict) -> None:
+        """Parse API Gateway v2 event structure."""
+        request_context = event.get("requestContext", {})
+        http_context = request_context.get("http", {})
+
+        self.request_method = http_context.get("method", "GET").upper()
+        self.path = http_context.get("path", "/")
+        # v2 doesn't have resource field
+        self.resource = ""
+
+        # Extract query parameters (v2 only has single values)
+        self.query_parameters = event.get("queryStringParameters") or {}
+
+        # Extract headers (v2 only has single value headers)
+        headers_dict = {}
+        for key, value in event.get("headers", {}).items():
+            headers_dict[key.lower()] = str(value)
+
+        self.request_headers = Headers(headers_dict)
+
+    def get_client_ip(self) -> str:
+        """Get the client IP address from API Gateway event."""
+        request_context = self.event.get("requestContext", {})
+
+        # Try v1 format first (identity.sourceIp)
+        identity = request_context.get("identity", {})
+        if "sourceIp" in identity:
+            return identity["sourceIp"]
+
+        # Try v2 format (http.sourceIp)
+        http_context = request_context.get("http", {})
+        if "sourceIp" in http_context:
+            return http_context["sourceIp"]
+
+        raise ValueError("Unable to find the client ip inside the API Gateway")
+
+    def get_protocol(self) -> str:
+        """Get the protocol from API Gateway request context."""
+        request_context = self.event.get("requestContext", {})
+
+        # Try v2 format first (has explicit protocol)
+        http_context = request_context.get("http", {})
+        if "protocol" in http_context:
+            protocol = http_context["protocol"]
+            return "https" if protocol.upper().startswith("HTTPS") else "http"
+
+        # v1 defaults to HTTPS
+        return "https"
+
+    def context_specifics(self) -> dict[str, Any]:
+        """Provide API Gateway specific context data."""
+        request_context = self.event.get("requestContext", {})
+        http_context = request_context.get("http", {})
+
+        return {
+            **super().context_specifics(),
+            "resource": self.resource,
+            "stage": request_context.get("stage"),
+            "request_id": request_context.get("requestId"),
+            "api_id": request_context.get("apiId"),
+            "api_version": self._detect_version(self.event),
+        }

clearskies_aws/input_outputs/lambda_api_gateway_web_socket.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from clearskies.configs import String
+from clearskies.input_outputs import Headers
+
+from clearskies_aws.input_outputs import lambda_input_output
+
+
+class LambdaApiGatewayWebSocket(lambda_input_output.LambdaInputOutput):
+    """Api Gateway WebSocket specific Lambda input/output handler."""
+
+    route_key = String(default="")
+    connection_id = String(default="")
+
+    def __init__(self, event: dict[str, Any], context: dict[str, Any], url: str = ""):
+        # Call parent constructor
+        super().__init__(event, context)
+
+        self.path = url
+
+        # WebSocket specific initialization
+        request_context = event.get("requestContext", {})
+
+        # WebSocket uses route_key, but doesn't have either a route or a method
+        self.route_key = request_context.get("routeKey", "GET")
+        self.request_method = self.route_key.upper()  # For compatibility
+
+        # WebSocket connection ID
+        self.connection_id = request_context.get("connectionId", "")
+
+        # These will only be available, at monst, during the on-connect step
+        self.query_parameters = event.get("queryStringParameters") or {}
+        headers_dict = {}
+        for key, value in event.get("headers", {}).items():
+            headers_dict[key.lower()] = str(value)
+        self.request_headers = Headers(headers_dict)
+
+    def get_client_ip(self) -> str:
+        """Get the client IP address from WebSocket request context."""
+        request_context = self.event.get("requestContext", {})
+        identity = request_context.get("identity", {})
+
+        if "sourceIp" in identity:
+            return identity["sourceIp"]
+
+        raise ValueError("Unable to find the client ip inside the API Gateway")
+
+    def respond(self, body: Any, status_code: int = 200) -> None:
+        # since there is no response to the client, we want to raise an exception for any non-200 status code so
+        # the lambda execution itself will be marked as a failure.
+        if status_code > 299:
+            if not isinstance(body, str):
+                body = json.dumps(body)
+            raise Exception(f"Non-200 Status code returned by application: {status_code}.  Response: '{body}'")
+
+    def context_specifics(self) -> dict[str, Any]:
+        """Provide WebSocket specific context data."""
+        request_context = self.event.get("requestContext", {})
+
+        return {
+            **super().context_specifics(),
+            "connection_id": self.connection_id,
+            "route_key": self.route_key,
+            "stage": request_context.get("stage"),
+            "request_id": request_context.get("requestId"),
+            "api_id": request_context.get("apiId"),
+            "domain_name": request_context.get("domainName"),
+            "event_type": request_context.get("eventType"),
+            "connected_at": request_context.get("connectedAt"),
+        }

clearskies_aws/input_outputs/lambda_input_output.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import base64
+import json
+from abc import abstractmethod
+from typing import Any, cast
+from urllib.parse import urlencode
+
+from clearskies.configs import AnyDict, String
+from clearskies.input_outputs import InputOutput
+
+
+class LambdaInputOutput(InputOutput):
+    """Base class for Lambda input/output handlers that provides common Lambda functionality."""
+
+    event = AnyDict(default={})
+    context = AnyDict(default={})
+    path = String(default="/")
+
+    _cached_body = None
+    _body_was_cached = False
+
+    def __init__(
+        self, event: dict[str, Any], context: dict[str, Any], url: str | None = "", request_method: str | None = ""
+    ):
+        # Store event and context
+        self.event = event
+        self.context = context
+
+        # Initialize the base class
+        super().__init__()
+
+    def respond(self, body: Any, status_code: int = 200) -> dict[str, Any] | None:
+        """Create standard Lambda HTTP response format."""
+        if "content-type" not in self.response_headers:
+            self.response_headers.content_type = "application/json; charset=UTF-8"
+
+        is_base64 = False
+
+        if isinstance(body, bytes):
+            is_base64 = True
+            final_body = base64.encodebytes(body).decode("utf8")
+        elif isinstance(body, str):
+            final_body = body
+        else:
+            final_body = json.dumps(body)
+
+        return {
+            "isBase64Encoded": is_base64,
+            "statusCode": status_code,
+            "headers": dict(self.response_headers),
+            "body": final_body,
+        }
+
+    def has_body(self) -> bool:
+        return bool(self.get_body())
+
+    def get_body(self) -> str:
+        """Get request body with base64 decoding if needed."""
+        if not self._body_was_cached:
+            self._body_was_cached = True
+            self._cached_body = self.event.get("body", "")
+            if (
+                self._cached_body is not None
+                and self.event.get("isBase64Encoded", False)
+                and isinstance(self._cached_body, str)
+            ):
+                self._cached_body = base64.decodebytes(self._cached_body.encode("utf-8")).decode("utf-8")
+        return self._cached_body or ""
+
+    def get_client_ip(self) -> str:
+        """Get client IP - can be overridden by subclasses for event-specific logic."""
+        return "127.0.0.1"
+
+    def get_protocol(self) -> str:
+        """Get protocol."""
+        # Default to HTTPS for most Lambda HTTP events
+        return "https"
+
+    def get_full_path(self) -> str:
+        """Get full path."""
+        return self.path
+
+    def context_specifics(self) -> dict[str, Any]:
+        """Provide Lambda-specific context."""
+        return {
+            "event": self.event,
+            "context": self.context,
+        }

clearskies_aws/input_outputs/lambda_invoke.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from clearskies.exceptions import ClientError
+from clearskies.input_outputs import Headers
+
+from clearskies_aws.input_outputs import lambda_input_output
+
+
+class LambdaInvoke(lambda_input_output.LambdaInputOutput):
+    """Direct Lambda invocation specific input/output handler."""
+
+    def __init__(
+        self,
+        event: dict[str, Any],
+        context: dict[str, Any],
+        request_method: str = "",
+        url: str = "",
+    ):
+        # Call parent constructor
+        super().__init__(event, context)
+
+        # Direct invocation specific initialization
+        if url:
+            self.path = url
+        else:
+            self.supports_url = True
+        if request_method:
+            self.request_method = request_method.upper()
+        else:
+            self.supports_request_method = False
+
+        # Direct invocations don't have headers
+        self.request_headers = Headers({})
+
+    def has_body(self) -> bool:
+        """Direct invocations always have a body (the event itself)."""
+        return True
+
+    def get_body(self) -> str:
+        """Get the entire event as the body."""
+        if isinstance(self.event, (dict, list)):
+            return json.dumps(self.event)
+        return str(self.event)
+
+    def respond(self, body: Any, status_code: int = 200) -> Any:
+        """Return the response directly for direct invocations."""
+        if isinstance(body, bytes):
+            return body.decode("utf-8")
+        return body
+
+    def get_client_ip(self) -> str:
+        """Direct invocations don't have client IP information."""
+        return "127.0.0.1"
+
+    def get_protocol(self) -> str:
+        """Direct invocations don't have a protocol."""
+        return "lambda"
+
+    def get_full_path(self) -> str:
+        """Return the configured path."""
+        return self.path
+
+    def context_specifics(self) -> dict[str, Any]:
+        """Provide direct invocation specific context data."""
+        return {
+            **super().context_specifics(),
+            "invocation_type": "direct",
+            "function_name": self.context.get("function_name"),
+            "function_version": self.context.get("function_version"),
+            "request_id": self.context.get("aws_request_id"),
+        }
+
+    @property
+    def request_data(self) -> dict[str, Any] | list[Any] | None:
+        """Return the event directly as request data."""
+        return self.event
+
+    def json_body(
+        self, required: bool = True, allow_non_json_bodies: bool = False
+    ) -> dict[str, Any] | list[Any] | None:
+        """Get the event as JSON data."""
+        # For direct invocations, the event is already an object, not a JSON string
+        if required and not self.event:
+            raise ClientError("Request body was not valid JSON")
+        return self.event

clearskies_aws/input_outputs/lambda_sns.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from clearskies.exceptions import ClientError
+from clearskies.input_outputs import Headers
+
+from clearskies_aws.input_outputs import lambda_input_output
+
+
+class LambdaSns(lambda_input_output.LambdaInputOutput):
+    """SNS specific Lambda input/output handler."""
+
+    record: dict[str, Any]
+
+    def __init__(self, event: dict, context: dict[str, Any], url: str = "", request_method: str = ""):
+        # Call parent constructor
+        super().__init__(event, context)
+
+        # SNS specific initialization
+        if url:
+            self.path = url
+        else:
+            self.supports_url = False
+        if request_method:
+            self.request_method = request_method.upper()
+        else:
+            self.supports_request_method = False
+
+        # SNS events don't have headers
+        self.request_headers = Headers({})
+
+        # Extract SNS message from event
+        try:
+            record = event["Records"][0]["Sns"]["Message"]
+            self.record = json.loads(record)
+        except (KeyError, IndexError, json.JSONDecodeError) as e:
+            raise ClientError(
+                "The message from AWS was not a valid SNS event with serialized JSON. "
+                "The lambda_sns context for clearskies only accepts serialized JSON."
+            )
+
+    def respond(self, body: Any, status_code: int = 200) -> None:
+        """Respond to the client, but SNS has no client."""
+        # since there is no response to the client, we want to raise an exception for any non-200 status code so
+        # the lambda execution itself will be marked as a failure.
+        if status_code > 299:
+            if not isinstance(body, str):
+                body = json.dumps(body)
+            raise Exception(f"Non-200 Status code returned by application: {status_code}.  Response: '{body}'")
+
+    def get_body(self) -> str:
+        """Get the SNS message as a JSON string."""
+        return json.dumps(self.record) if self.record else ""
+
+    def has_body(self) -> bool:
+        """Check if SNS message exists."""
+        return bool(self.record)
+
+    def get_client_ip(self) -> str:
+        """SNS events don't have client IP information."""
+        return "127.0.0.1"
+
+    def get_protocol(self) -> str:
+        """SNS events don't have a protocol."""
+        return "sns"
+
+    def get_full_path(self) -> str:
+        """Return the configured path."""
+        return self.path
+
+    def context_specifics(self) -> dict[str, Any]:
+        """Provide SNS specific context data."""
+        sns_record = self.event.get("Records", [{}])[0].get("Sns", {})
+
+        return {
+            **super().context_specifics(),
+            "message_id": sns_record.get("MessageId"),
+            "topic_arn": sns_record.get("TopicArn"),
+            "subject": sns_record.get("Subject"),
+            "timestamp": sns_record.get("Timestamp"),
+        }
+
+    @property
+    def request_data(self) -> dict[str, Any] | list[Any] | None:
+        """Return the SNS message data directly."""
+        return self.record

clearskies_aws/input_outputs/lambda_sqs_standard.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from clearskies.configs import AnyDict, String
+from clearskies.exceptions import ClientError
+from clearskies.input_outputs import Headers
+
+from clearskies_aws.input_outputs import lambda_input_output
+
+
+class LambdaSqsStandard(lambda_input_output.LambdaInputOutput):
+    """SQS standard queue specific Lambda input/output handler."""
+
+    record = AnyDict(default={})
+    path = String(default="/")
+
+    def __init__(
+        self,
+        record: dict[str, Any],
+        event: dict[str, Any],
+        context: dict[str, Any],
+        url: str = "",
+        request_method: str = "",
+    ):
+        # Call parent constructor with the full event
+        super().__init__(event, context)
+
+        # Store the individual SQS record
+        self.record = record
+        # SQS specific initialization
+        if url:
+            self.path = url
+        else:
+            self.supports_url = False
+
+        if request_method:
+            self.request_method = request_method.upper()
+        else:
+            self.supports_request_method = False
+
+        # SQS events don't have headers
+        self.request_headers = Headers({})
+
+    def respond(self, body: Any, status_code: int = 200) -> None:
+        """Respond to the client, but SQS has no client."""
+        # since there is no response to the client, we want to raise an exception for any non-200 status code so
+        # the lambda execution itself will be marked as a failure.
+        if status_code > 299:
+            if not isinstance(body, str):
+                body = json.dumps(body)
+            raise Exception(f"Non-200 Status code returned by application: {status_code}.  Response: '{body}'")
+
+    def get_body(self) -> str:
+        """Get request body with base64 decoding if needed."""
+        return self.record["body"]
+
+    def has_body(self) -> bool:
+        """Check if SQS message has a body."""
+        return True
+
+    def get_client_ip(self) -> str:
+        """SQS events don't have client IP information."""
+        return "127.0.0.1"
+
+    def get_protocol(self) -> str:
+        """SQS events don't have a protocol."""
+        return "sqs"
+
+    def get_full_path(self) -> str:
+        """Return the configured path."""
+        return self.path
+
+    def context_specifics(self) -> dict[str, Any]:
+        """Provide SQS specific context data."""
+        return {
+            **super().context_specifics(),
+            "message_id": self.record.get("messageId"),
+            "receipt_handle": self.record.get("receiptHandle"),
+            "source_arn": self.record.get("eventSourceARN"),
+            "sent_timestamp": self.record.get("attributes", {}).get("SentTimestamp"),
+            "approximate_receive_count": self.record.get("attributes", {}).get("ApproximateReceiveCount"),
+            "message_attributes": self.record.get("messageAttributes", {}),
+            "record": self.record,
+        }

clearskies_aws/mocks/__init__.py

@@ -0,0 +1 @@
+from . import actions

clearskies_aws/mocks/actions/__init__.py

@@ -0,0 +1,6 @@
+from .ses import SES
+from .sns import SNS
+from .sqs import SQS
+from .step_function import StepFunction
+
+__all__ = ["SES", "SNS", "SQS", "StepFunction"]

clearskies_aws/mocks/actions/ses.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Any
+
+from clearskies import Model
+from types_boto3_ses import SESClient
+
+from clearskies_aws.actions.ses import SES as BaseSES
+
+
+class SES(BaseSES):
+    calls: list[dict[str, Any]] | None = None
+
+    @classmethod
+    def mock(cls, di):
+        cls.calls = []
+        di.mock_class(BaseSES, SES)
+
+    def _execute_action(self, client: SESClient, model: Model) -> None:
+        """Send a notification as configured."""
+        if SES.calls is None:
+            SES.calls = []
+        utcnow = self.di.build("utcnow")
+
+        SES.calls.append(
+            {
+                "from": self.sender,
+                "to": self._resolve_destination("to", model),
+                "cc": self._resolve_destination("cc", model),
+                "bcc": self._resolve_destination("bcc", model),
+                "subject": self._resolve_subject(model, utcnow),
+                "message": self._resolve_message_as_html(model, utcnow),
+            }
+        )

clearskies_aws/mocks/actions/sns.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import Any
+
+from clearskies import Model
+from types_boto3_sns import SNSClient
+
+from clearskies_aws.actions.sns import SNS as BaseSNS
+
+
+class SNS(BaseSNS):
+    calls: list[dict[str, Any]] | None = None
+
+    @classmethod
+    def mock(cls, di):
+        cls.calls = []
+        di.mock_class(BaseSNS, SNS)
+
+    def _execute_action(self, client: SNSClient, model: Model) -> None:
+        """Send a notification as configured."""
+        if SNS.calls is None:
+            SNS.calls = []
+
+        SNS.calls.append(
+            {
+                "TopicArn": self.get_topic_arn(model),
+                "Message": self.get_message_body(model),
+            }
+        )

clearskies_aws/mocks/actions/sqs.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import Any
+
+from clearskies import Model
+from types_boto3_sqs import SQSClient
+
+from clearskies_aws.actions.sqs import SQS as BaseSQS
+
+
+class SQS(BaseSQS):
+    calls: list[dict[str, Any]] | None = None
+
+    @classmethod
+    def mock(cls, di):
+        cls.calls = []
+        di.mock_class(BaseSQS, SQS)
+
+    def _execute_action(self, client: SQSClient, model: Model) -> None:
+        """Send a notification as configured."""
+        if SQS.calls is None:
+            SQS.calls = []
+
+        SQS.calls.append(
+            {
+                "QueueUrl": self.get_queue_url(model),
+                "MessageBody": self.get_message_body(model),
+            }
+        )

clearskies_aws/mocks/actions/step_function.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Any
+
+from clearskies import Model
+from types_boto3_stepfunctions import SFNClient
+
+from clearskies_aws.actions.step_function import StepFunction as BaseStepFunction
+
+
+class StepFunction(BaseStepFunction):
+    calls: list[dict[str, Any]] | None = None
+
+    @classmethod
+    def mock(cls, di):
+        cls.calls = []
+        di.mock_class(BaseStepFunction, StepFunction)
+
+    def _execute_action(self, client: SFNClient, model: Model) -> None:
+        """Send a notification as configured."""
+        if StepFunction.calls is None:
+            StepFunction.calls = []
+
+        StepFunction.calls.append(
+            {
+                "stateMachineArn": self.get_arn(model),
+                "input": self.get_message_body(model),
+            }
+        )
+
+        if self.column_to_store_execution_arn:
+            model.save({self.column_to_store_execution_arn: "mock_execution_arn"})