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

clearskies_aws/backends/sqs_backend.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from clearskies import Model
+from clearskies.query import Query
+from types_boto3_sqs import SQSClient
+
+from clearskies_aws.backends import backend
+
+
+class SqsBackend(backend.Backend):
+    """
+    SQS backend for clearskies.
+
+    There's not too much to this.  Just set it on your model and set the table name equal to the SQS url.
+
+    This doesn't support setting message attributes.  The SQS call is simple enough that if you need
+    those you may as well just invoke the boto3 SDK yourself.
+
+    Note that this is a *write-only* backend.  Reading from an SQS queue is different enough from
+    the way that clearskies models works that it doesn't make sense to try to make those happen here.
+
+    See the SQS context in this library for processing your queue data.
+    """
+
+    _sqs: SQSClient
+
+    @property
+    def sqs(self) -> SQSClient:
+        if not hasattr(self, "_sqs"):
+            if not self.environment.get("AWS_REGION", True):
+                raise ValueError("To use SQS you must use set AWS_REGION in the .env file or an environment variable")
+
+            self._sqs = self.boto3.client("sqs", region_name=self.environment.get("AWS_REGION", True))
+
+        return self._sqs
+
+    def create(self, data: dict[str, Any], model: Model) -> dict[str, Any]:
+        self.sqs.send_message(
+            QueueUrl=model.destination_name(),
+            MessageBody=json.dumps(data),
+        )
+        return {**data}
+
+    def update(self, id: int | str, data: dict[str, Any], model: Model) -> dict[str, Any]:
+        raise ValueError("The SQS backend only supports the create operation")
+
+    def delete(self, id: int | str, model: Model) -> bool:
+        raise ValueError("The SQS backend only supports the create operation")
+
+    def count(self, query: Query) -> int:
+        raise ValueError("The SQS backend only supports the create operation")
+
+    def records(
+        self,
+        query: Query,
+        next_page_data: dict[str, str | int] | None = None,
+    ) -> list[dict[str, Any]]:
+        raise ValueError("The SQS backend only supports the create operation")

clearskies_aws/contexts/__init__.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from clearskies_aws.contexts.cli_web_socket_mock import CliWebSocketMock
+from clearskies_aws.contexts.lambda_alb import LambdaAlb
+from clearskies_aws.contexts.lambda_api_gateway import LambdaApiGateway
+from clearskies_aws.contexts.lambda_api_gateway_web_socket import (
+    LambdaApiGatewayWebSocket,
+)
+from clearskies_aws.contexts.lambda_invocation import LambdaInvocation
+from clearskies_aws.contexts.lambda_sns import LambdaSns
+from clearskies_aws.contexts.lambda_sqs_standard_partial_batch import (
+    LambdaSqsStandardPartialBatch,
+)
+
+__all__ = [
+    "CliWebSocketMock",
+    "LambdaAlb",
+    "LambdaApiGateway",
+    "LambdaApiGatewayWebSocket",
+    "LambdaInvocation",
+    "LambdaSns",
+    "LambdaSqsStandardPartialBatch",
+]

clearskies_aws/contexts/cli_web_socket_mock.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from clearskies.contexts import cli
+
+from clearskies_aws.input_outputs import CliWebSocketMock as CliWebSocketMockInputOutput
+
+
+class CliWebSocketMock(cli.Cli):
+    """
+    Help assist with testing websockets locally.
+
+    The LambdaApiGatewayWebSocket context makes it easy to run websocket applications, but testing
+    these locally is literally impossible.  This context provides a close analogue to the way
+    the LambdaApiGatewayWebSocket context works to give some testing capabilities when running
+    locally.
+    """
+
+    def __call__(self):
+        return self.execute_application(CliWebSocketMockInputOutput())

clearskies_aws/contexts/lambda_alb.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from typing import Any
+
+from clearskies.contexts.context import Context
+
+from clearskies_aws.input_outputs import LambdaAlb as LambdaAlbInputOutput
+
+
+class LambdaAlb(Context):
+    """
+    Run a clearskies application in a lambda behind an application load balancer.
+
+    There's nothing special here: just build your application, use the LambdaAlb context in a standard AWS lambda
+    handler, and attach your lambda to an ALB.  This generally expects that the ALB will forward all requests to
+    the clearskies application, which will therefore handle all routing.  However, you can also use path-based
+    routing in your target group to forward some subset of requests to separate lambdas, each using this same
+    context.  When you do this, keep in mind that AWS still passes along the full path (including the part handled
+    by the ALB), so you want to make sure that your clearskies application is configured with the full URL as well.
+
+    Per AWS norms, you should create the context in the "root" of your python application, and then invoke it
+    inside a standard lambda handler function.  This will allow AWS to cache the full application, improving
+    performance.  If you create and invoke the context inside of your lambda handler, it will effectively turn
+    off any caching.  In addition, clearskies does a fair amount of configuration validation when you create the
+    context, so this work will be repeated on every call.
+
+    ```
+    import clearskies
+    import clearskies_aws
+    from clearskies.validators import Required, Unique
+    from clearskies import columns
+
+
+    class User(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = columns.Uuid()
+        name = columns.String(validators=[Required()])
+        username = columns.String(
+            validators=[
+                Required(),
+                Unique(),
+            ]
+        )
+        age = columns.Integer(validators=[Required()])
+        created_at = columns.Created()
+        updated_at = columns.Updated()
+
+
+    application = clearskies_aws.contexts.LambdaAlb(
+        clearskies.endpoints.RestfulApi(
+            url="users",
+            model_class=User,
+            readable_column_names=["id", "name", "username", "age", "created_at", "updated_at"],
+            writeable_column_names=["name", "username", "age"],
+            sortable_column_names=["id", "name", "username", "age", "created_at", "updated_at"],
+            searchable_column_names=["id", "name", "username", "age", "created_at", "updated_at"],
+            default_sort_column_name="name",
+        )
+    )
+
+
+    def lambda_handler(event, context):
+        return application(event, context)
+    ```
+
+    ### Context for Callables
+
+    When using this context, two additional named arguments become available to any callables invoked by clearskies:
+    `event` and `context`.  These correspond to the original `event` and `context` variables provided by AWS to
+    the lambda.
+    """
+
+    def __call__(self, event: dict[str, Any], context: dict[str, Any]) -> Any:  # type: ignore[override]
+        return self.execute_application(LambdaAlbInputOutput(event, context))

clearskies_aws/contexts/lambda_api_gateway.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import Any
+
+from clearskies.contexts.context import Context
+
+from clearskies_aws.input_outputs import LambdaApiGateway as LambdaApiGatewayInputOutput
+
+
+class LambdaApiGateway(Context):
+    """
+    Run a clearskies application in a lambda behind an API Gateway (v1 or v2).
+
+    There's nothing special here: just build your application, use the LambdaApiGateway context in a standard AWS
+    lambda handler, and attach your lambda to an Api Gateway.  Per AWS norms, you should create the context in
+    the "root" of your python application, and then invoke it inside a standard lambda handler function.  This
+    will allow AWS to cache the full application, improving performance.  If you create and invoke the context
+    inside of your lambda handler, it will effectively turn off any caching.  In addition, clearskies does a fair
+    amount of configuration validation when you create the context, so this work will be repeated on every call.
+
+    ```
+    import clearskies
+    import clearskies_aws
+    from clearskies.validators import Required, Unique
+    from clearskies import columns
+
+
+    class User(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = columns.Uuid()
+        name = columns.String(validators=[Required()])
+        username = columns.String(
+            validators=[
+                Required(),
+                Unique(),
+            ]
+        )
+        age = columns.Integer(validators=[Required()])
+        created_at = columns.Created()
+        updated_at = columns.Updated()
+
+
+    application = clearskies_aws.contexts.LambdaApiGateway(
+        clearskies.endpoints.RestfulApi(
+            url="users",
+            model_class=User,
+            readable_column_names=["id", "name", "username", "age", "created_at", "updated_at"],
+            writeable_column_names=["name", "username", "age"],
+            sortable_column_names=["id", "name", "username", "age", "created_at", "updated_at"],
+            searchable_column_names=["id", "name", "username", "age", "created_at", "updated_at"],
+            default_sort_column_name="name",
+        )
+    )
+
+
+    def lambda_handler(event, context):
+        return application(event, context)
+    ```
+
+    ### Context for Callables
+
+    When using this context, a number of additional named arguments become available to any callables invoked by
+    clearskies:
+
+     1. `event`
+     2. `context`
+     3. `resource`
+     4. `stage`
+     5. `request_id`
+     6. `api_id`
+     7. `api_version` (v1 or v2)
+    """
+
+    def __call__(self, event: dict[str, Any], context: dict[str, Any]) -> Any:  # type: ignore[override]
+        return self.execute_application(LambdaApiGatewayInputOutput(event, context))

clearskies_aws/contexts/lambda_api_gateway_web_socket.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any
+
+from clearskies.contexts.context import Context
+
+from clearskies_aws.input_outputs import (
+    LambdaApiGatewayWebSocket as LambdaApiGatewayWebSocketInputOutput,
+)
+
+
+class LambdaApiGatewayWebSocket(Context):
+    """
+    Run a clearskies application behind an API Gateway that is configured for use as a websocket.
+
+    Websockets work much differently than standard API endpoints.  Most importantly, none of the standard HTTP
+    concepts exist.  Websockets requests don't have any of:
+
+     1. URL Path
+     2. Query Parameters
+     3. HTTP Headers
+     4. Response Headers
+     5. An HTTP Response
+
+    So in short, everything works completely differently.  The reason is because a websocket is a
+    two-way communication channel that's created over a TCP/IP connection.  It does start with an HTTP request,
+    but this is a one time request when the communication channel is first created.  Later messages (which
+    are where the bulk of the communication happens) travel over the already-open connection, so
+    the communication looks nothing like HTTP.  Usually, the data traveling over this connection is
+    a JSON payload, and since the connection is already opened it doesn't have any of the metadata associated
+    with an HTTP request (hence the lack of url/query/headers).  In addition, the communication is no longer
+    transactional - messages from the client to the server do not come with a direct response, and the server
+    can send messages to the client without needing the former to initiate the conversation.
+
+    Routing and authorization are usually handled in-band, which means that the routing parameters or authentication
+    data are added directly to the JSON body sent over the open connection.  This often results in applications
+    having to handle such things themselves, since the typical standards of web frameworks won't match up.  In
+    the case of routing with an API Gateway, it has its own suggested standard of setting a routekey where the
+    API gateway will check for an application-defined route parameter in the request body and use this to route
+    to an appropriate lambda.  With clearskies, you can also use the `clearskies.endpoints.JsonParamEndpointGroup`
+    to accomplish the same.
+
+    With a websocket through API Gateway, headers are available during the `on_connect` phase, so you can always
+    perform authentication then and record the result with the connection id (which can be used much like a
+    session id).  Otherwise, authentication is typically handled by including the authentication token in every
+    message payload.
+
+    ### Sending Messages
+
+    An important part of using websockets is being able to manage and send messages to clients.  To help with this,
+    there is a base model class in `clearskies_aws.models.WebSocketConnectionModel`.  Check the documentation for
+    this class to understand how this is managed and see a "starter" websocket application.
+
+    """
+
+    def __call__(self, event: dict[str, Any], context: dict[str, Any], url: str = "") -> Any:  # type: ignore[override]
+        return self.execute_application(LambdaApiGatewayWebSocketInputOutput(event, context, url))

clearskies_aws/contexts/lambda_invocation.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any
+
+from clearskies.authentication import Public
+from clearskies.contexts.context import Context
+
+from clearskies_aws.input_outputs import LambdaInvocation as LambdaInvocationInputOutput
+
+
+class LambdaInvocation(Context):
+
+    def __call__(self, event: dict[str, Any], context: dict[str, Any]) -> Any:  # type: ignore[override]
+        return self.execute_application(
+            LambdaInvocationInputOutput(
+                event,
+                context,
+            )
+        )

clearskies_aws/contexts/lambda_sns.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from clearskies.authentication import Public
+from clearskies.contexts.context import Context
+
+from clearskies_aws.input_outputs import LambdaSns as LambdaSnsInputOutput
+
+
+class LambdaSns(Context):
+    def __call__(self, event, context, method=None, url=None):
+        if self.execute_application is None:
+            raise ValueError("Cannot execute LambdaSnsEvent context without first configuring it")
+
+        try:
+            return self.execute_application(LambdaSnsInputOutput(event, context, method=method, url=url))
+        except Exception as e:
+            print("Failed message " + event["Records"][0]["Sns"]["MessageId"] + ". Error error: " + str(e))
+            raise e

clearskies_aws/contexts/lambda_sqs_standard_partial_batch.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import traceback
+
+from clearskies.authentication import Public
+from clearskies.contexts.context import Context
+
+from clearskies_aws.input_outputs import LambdaSqsStandard as LambdaSqsStandardInputOutput
+
+
+class LambdaSqsStandardPartialBatch(Context):
+    def __call__(self, event, context, url="", method="POST"):
+        item_failures = []
+        for record in event["Records"]:
+            print("Processing message " + record["messageId"], record["body"])
+            try:
+                self.execute_application(
+                    LambdaSqsStandardInputOutput(record["body"], event, context, url=url, method=method)
+                )
+            except Exception as e:
+                print("Failed message " + record["messageId"] + " being returned for retry.  Error error: " + str(e))
+                traceback.print_tb(e.__traceback__)
+                item_failures.append({"itemIdentifier": record["messageId"]})
+
+        if item_failures:
+            return {
+                "batchItemFailures": item_failures,
+            }
+        return {}

clearskies_aws/di/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from clearskies_aws.di import inject
+from clearskies_aws.di.aws_additional_config_auto_import import AwsAdditionalConfigAutoImport
+
+__all__ = ["inject", "AwsAdditionalConfigAutoImport"]

clearskies_aws/di/aws_additional_config_auto_import.py

@@ -0,0 +1,37 @@
+import datetime
+from types import ModuleType
+from typing import Any
+
+import boto3 as boto3_module
+from clearskies import Environment
+from clearskies.di import AdditionalConfigAutoImport
+from clearskies.di.additional_config import AdditionalConfig
+
+from clearskies_aws.secrets import ParameterStore
+
+
+class AwsAdditionalConfigAutoImport(AdditionalConfigAutoImport):
+    """
+    Provide a DI with AWS modules built-in.
+
+    This DI auto injects boto3, boto3 Session and the parameter store.
+    """
+
+    def provide_boto3(self) -> ModuleType:
+        import boto3
+
+        return boto3
+
+    def provide_parameter_store(self) -> ParameterStore:
+        # This is just here so that we can auto-inject the secrets into the environment without having
+        # to force the developer to define a secrets manager
+        return ParameterStore()
+
+    def provide_boto3_session(self, boto3: ModuleType, environment: Environment) -> boto3_module.session.Session:
+        if not environment.get("AWS_REGION", True):
+            raise ValueError(
+                "To use AWS Session you must use set AWS_REGION in the .env file or an environment variable"
+            )
+
+        session = boto3.session.Session(region_name=environment.get("AWS_REGION", True))
+        return session

clearskies_aws/di/inject/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from clearskies_aws.di.inject.boto3 import Boto3
+from clearskies_aws.di.inject.boto3_session import Boto3Session
+
+__all__ = ["Boto3", "Boto3Session"]

clearskies_aws/di/inject/boto3.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from types import ModuleType
+
+from clearskies.di.injectable import Injectable
+
+
+class Boto3(Injectable):
+    def __init__(self, cache: bool = True):
+        self.cache = cache
+
+    def __get__(self, instance, parent) -> ModuleType:
+        if instance is None:
+            return self  # type: ignore
+        return self._di.build_from_name("boto3", cache=self.cache)

clearskies_aws/di/inject/boto3_session.py

@@ -0,0 +1,13 @@
+from types import ModuleType
+
+from clearskies.di.injectable import Injectable
+
+
+class Boto3Session(Injectable):
+    def __init__(self, cache: bool = True):
+        self.cache = cache
+
+    def __get__(self, instance, parent) -> ModuleType:
+        if instance is None:
+            return self  # type: ignore
+        return self._di.build_from_name("boto3_session", cache=self.cache)

clearskies_aws/di/inject/parameter_store.py

@@ -0,0 +1,15 @@
+from clearskies.di.injectable import Injectable
+
+from clearskies_aws.secrets.parameter_store import (
+    ParameterStore as ParameterStoreDependency,
+)
+
+
+class ParameterStore(Injectable):
+    def __init__(self, cache: bool = True):
+        self.cache = cache
+
+    def __get__(self, instance, parent) -> ParameterStoreDependency:
+        if instance is None:
+            return self  # type: ignore
+        return self._di.build_from_name("parameter_store", cache=self.cache)

clearskies_aws/endpoints/__init__.py

@@ -0,0 +1,2 @@
+from .secrets_manager_rotation import SecretsManagerRotation
+from .simple_body_routing import SimpleBodyRouting