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

clearskies_aws/input_outputs/lambda_invocation.py

@@ -0,0 +1,85 @@
+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 LambdaInvocation(lambda_input_output.LambdaInputOutput):
+    """Direct Lambda invocation specific input/output handler."""
+
+    def __init__(
+        self,
+        event: dict[str, Any],
+        context: dict[str, Any],
+        method: str = "POST",
+        url: str = "",
+    ):
+        # Call parent constructor
+        super().__init__(event, context)
+
+        # Direct invocation specific initialization
+        self.path = url
+        self.request_method = method.upper()
+
+        # Direct invocations don't have query parameters or path parameters
+        self.query_parameters = {}
+
+        # 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,79 @@
+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."""
+
+    def __init__(self, event: dict, context: dict[str, Any], url: str = "", method: str = "POST"):
+        # Call parent constructor
+        super().__init__(event, context)
+
+        # SNS specific initialization
+        self.path = url
+        self.request_method = method.upper()
+
+        # SNS events don't have query parameters or path parameters
+        self.query_parameters = {}
+
+        # 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) -> dict[str, Any]:
+        """SNS events don't return responses."""
+        return {}
+
+    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(),
+            "sns_message_id": sns_record.get("MessageId"),
+            "sns_topic_arn": sns_record.get("TopicArn"),
+            "sns_subject": sns_record.get("Subject"),
+            "sns_timestamp": sns_record.get("Timestamp"),
+            "sns_message": self._record,
+        }
+
+    @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,84 @@
+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: str, event: dict[str, Any], context: dict[str, Any], url: str = "", method: str = "POST"
+    ):
+        # Call parent constructor with the full event
+        super().__init__(event, context)
+
+        # Store the individual SQS record
+        self.record = json.loads(record)
+        print("SQS record:", self.record)
+        # SQS specific initialization
+        self.path = url if url else "/"
+        self.request_method = method.upper() if method else "POST"
+
+        # SQS events don't have query parameters or path parameters
+        self.query_parameters = {}
+
+        # SQS events don't have headers
+        self.request_headers = Headers({})
+
+    def respond(self, body: Any, status_code: int = 200) -> dict[str, Any]:
+        """SQS events don't return responses."""
+        return {}
+
+    def get_body(self) -> str:
+        """Get the SQS message body."""
+        return json.dumps(self.record)
+
+    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(),
+            "sqs_message_id": self.record.get("messageId"),
+            "sqs_receipt_handle": self.record.get("receiptHandle"),
+            "sqs_source_arn": self.record.get("eventSourceARN"),
+            "sqs_sent_timestamp": self.record.get("attributes", {}).get("SentTimestamp"),
+            "sqs_approximate_receive_count": self.record.get("attributes", {}).get("ApproximateReceiveCount"),
+            "sqs_message_attributes": self.record.get("messageAttributes", {}),
+            "sqs_record": self.record,
+        }
+
+    @property
+    def request_data(self) -> dict[str, Any]:
+        """Return the SQS message body as parsed JSON."""
+        body = self.get_body()
+        if not body:
+            return {}
+        try:
+            return json.loads(body)
+        except json.JSONDecodeError:
+            raise ClientError("SQS message body was not valid JSON")

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"})

clearskies_aws/models/web_socket_connection_model.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import json
+
+import clearskies
+
+import clearskies_aws
+
+
+class WebSocketConnectionModel(clearskies.Model):
+    """
+    Help manage message sending to websocket connections.
+
+    ## Working with Websockets
+
+    This is a partial model class to help send messages to websocket connections in an API gateway.
+    With a API Gateway managed websocket, the API gateway assigns an id to every connection, and you
+    send messages to the API gateway itself flagged for some client, via its connection id.  It
+    helps to understand that you don't need to be connected to the websocket itself to send messages
+    to the things connected to it.  Instead, you just need the necessary permission on the API gateway
+    and you need to know the connection id of the client you want to send a message to.  For reference,
+    the necessary AWS permission is:
+
+    ```
+    {
+        "Version": "2012-10-17",
+        "Statement": [
+            {
+                "Effect": "Allow",
+                "Action": ["execute-api:ManageConnections"],
+                "Resource": "arn:aws:execute-api:${aws_region_name}:${aws_account_id}:${api_gateway_id}/{stage}/*",
+            }
+        ],
+    }
+    ```
+
+    A simple flow that reproduces a pub/sub approach is:
+
+     1. Client connects to the API gateway via a websocket, and the backend records the connection id
+        in a backend somewhere
+     2. Client sends a message through the websocket to "register"/"subscribe" for some resource, and
+         the backend service updates the record for the connection to record what resource it is
+         subscribed to
+     3. If a server needs to send a message to everyone subscribed to a resource, it queries the backends
+        for all records connected to the resource in question and sends a message to their connection ids
+        through the backend.
+     4. If a client needs to send a message to everyone subscribed to a resource, it sends a message
+        through the websocket to some backend service which then passes the message along to the appropriate
+        connections, just as in #3 above.
+
+    Most examples with Websockets and API Gateway use dynamodb for storage.  You can, of course, use whatever
+    backend you want.  Still, below is an example pub/sub application to demonstrate how to build a basic
+    websocket app:
+
+    ```
+    import clearskies
+    import clearskies_aws
+
+    #####################
+    ## Our model class ##
+    #####################
+
+    class Client(clearskies_aws.models.WebSocketConnectionModel):
+        backend = clearskies_aws.backends.DynamoDbBackend()
+
+        # the base WebSocketConnectionModel class defines a string
+        # column called `connection_id` and sets it as the id column,
+        # so those are already set.  We just need any additional columns
+        resource_id = clearskies.columns.String()
+
+    ###########################
+    ## Our application logic ##
+    ###########################
+
+    def on_connect(clients, connection_id):
+        clients.create({"connection_id": connection_id})
+
+    def on_subscribe(clients, connection_id, request_data):
+        client = clients.find(f"connection_id={connection_id}")
+        if client.exists:
+            # we blindly save the request id, which makes it user-generated.  This also
+            # allows the client to "unsubscribe" by sending up a blank resource
+            client.save({"resource_id": request_data["resource_id"])
+
+    def on_publish(clients, connection_id, request_data):
+        my_client = clients.find(f"connection_id={connection_id}")
+        message = request_data.get("message")
+
+        # The problem with our standard input validation is that we can't return a response
+        # to the client with an error message.  This is not a transactional system.  Instead,
+        # we would have to send the client a new message with the error in it, which is not
+        # something the clearskies endpoints are designed for.
+        if not message or not my_client.resource_id:
+            return
+
+        for client in clients.where(f"resource_id={my_client.resource_id}").paginate_all():
+            if client.connection_id == my_client.connection_id:
+                continue
+
+            # the send function is provided by clearskies_aws.models.WebSocketConnectionModel
+            client.send({"message": message})
+
+    def on_disconnect(clients, connection_id):
+        clients.find(f"connection_id={connection_id}").delete(except_if_not_exists=False)
+
+    ######################################
+    ## Wiring it all up with clearskies ##
+    ######################################
+
+    # We're going to build one application, even though each action gets it's own lambda.
+    # The URLs aren't used for routing, but simply to allow us to select which function
+    # is associated with each lambda.  Actual routing still happens in the API Gateway
+    websocket_application = clearskies_aws.contexts.LambdaApiGatewayWebSocket(
+        clearskies.EndpointGroup([
+            clearskies.endpoints.Callable(
+                on_connect,
+                url="on_connect",
+            ),
+            clearskies.endpoints.Callable(
+                on_subscribe,
+                url="on_subscribe",
+            ),
+            clearskies.endpoints.Callable(
+                on_publish,
+                url="on_publish",
+            ),
+            clearskies.endpoints.Callable(
+                on_disconnect,
+                url="on_disconnect",
+            ),
+        ]),
+        classes=[Client],
+    )
+
+    ################################
+    ## The actual lambda handlers ##
+    ################################
+
+    def on_connect_handler(event, context):
+        return websocket_application(url="on_connect")
+
+    def on_subscribe_handler(event, context):
+        return websocket_application(url="on_subscribe")
+
+    def on_publish_handler(event, context):
+        return websocket_application(url="on_publish")
+
+    def on_disconnect_handler(event, context):
+        return websocket_application(url="on_disconnect")
+    ```
+
+    """
+
+    id_column_name = "connection_id"
+
+    boto3 = clearskies_aws.di.inject.Boto3()
+    connection_id = clearskies.columns.String()
+    input_output = clearskies.di.inject.InputOutput()
+
+    def send(self, message):
+        if not self:
+            raise ValueError("Cannot send message to non-existent connection.")
+        if not self.connection_id:
+            raise ValueError(
+                f"Hmmm... I couldn't find the connection id for the {self.__class__.__name__}.  I'm picky about id column names.  Can you please make sure I have a column called connection_id and that it contains the connection id?"
+            )
+
+        domain = self.input_output.context_specifics()["domain"]
+        stage = self.input_output.context_specifics()["stage"]
+        # only include the stage if we're using the default AWS domain - not with a custom domain
+        if ".amazonaws.com" in domain:
+            endpoint_url = f"https://{domain}/{stage}"
+        else:
+            endpoint_url = f"https://{domain}"
+        api_gateway = self.boto3.client("apigatewaymanagementapi", endpoint_url=endpoint_url)
+
+        bytes_message = json.dumps(message).encode("utf-8")
+        try:
+            response = api_gateway.post_to_connection(Data=bytes_message, ConnectionId=self.connection_id)
+        except api_gateway.exceptions.GoneException:
+            self.delete()
+        return response

clearskies_aws/secrets/__init__.py

@@ -0,0 +1,13 @@
+from clearskies_aws.secrets import additional_configs
+from clearskies_aws.secrets.akeyless_with_ssm_cache import AkeylessWithSsmCache
+from clearskies_aws.secrets.parameter_store import ParameterStore
+from clearskies_aws.secrets.secrets import Secrets
+from clearskies_aws.secrets.secrets_manager import SecretsManager
+
+__all__ = [
+    "Secrets",
+    "ParameterStore",
+    "SecretsManager",
+    "AkeylessWithSsmCache",
+    "additional_configs",
+]

clearskies_aws/secrets/additional_configs/__init__.py

@@ -0,0 +1,62 @@
+from .iam_db_auth import IAMDBAuth
+from .iam_db_auth_with_ssm import IAMDBAuthWithSSM
+from .mysql_connection_dynamic_producer_via_ssh_cert_bastion import MySQLConnectionDynamicProducerViaSSHCertBastion
+from .mysql_connection_dynamic_producer_via_ssm_bastion import MySQLConnectionDynamicProducerViaSSMBastion
+
+
+def mysql_connection_dynamic_producer_via_ssh_cert_bastion(
+    producer_name=None,
+    bastion_host=None,
+    bastion_name=None,
+    bastion_region=None,
+    bastion_username=None,
+    public_key_file_path=None,
+    cert_issuer_name=None,
+    database_host=None,
+    database_name=None,
+    local_proxy_port=None,
+):
+    return MySQLConnectionDynamicProducerViaSSHCertBastion(
+        producer_name=producer_name,
+        bastion_host=bastion_host,
+        bastion_name=bastion_name,
+        bastion_region=bastion_region,
+        bastion_username=bastion_username,
+        cert_issuer_name=cert_issuer_name,
+        public_key_file_path=public_key_file_path,
+        database_host=database_host,
+        database_name=database_name,
+        local_proxy_port=local_proxy_port,
+    )
+
+
+def mysql_connection_dynamic_producer_via_ssm_bastion(
+    producer_name=None,
+    bastion_instance_id=None,
+    bastion_name=None,
+    bastion_region=None,
+    bastion_username=None,
+    public_key_file_path=None,
+    database_host=None,
+    database_name=None,
+    local_proxy_port=None,
+):
+    return MySQLConnectionDynamicProducerViaSSMBastion(
+        producer_name=producer_name,
+        bastion_instance_id=bastion_instance_id,
+        bastion_name=bastion_name,
+        bastion_region=bastion_region,
+        bastion_username=bastion_username,
+        public_key_file_path=public_key_file_path,
+        database_host=database_host,
+        database_name=database_name,
+        local_proxy_port=local_proxy_port,
+    )
+
+
+def iam_db_auth():
+    return IAMDBAuth()
+
+
+def iam_db_auth_with_ssm():
+    return IAMDBAuthWithSSM()