clear-skies-aws 2.0.1__py3-none-any.whl → 2.0.3__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_invoke import LambdaInvoke
+from clearskies_aws.contexts.lambda_sns import LambdaSns
+from clearskies_aws.contexts.lambda_sqs_standard import (
+    LambdaSqsStandard,
+)
+
+__all__ = [
+    "CliWebSocketMock",
+    "LambdaAlb",
+    "LambdaApiGateway",
+    "LambdaApiGatewayWebSocket",
+    "LambdaInvoke",
+    "LambdaSns",
+    "LambdaSqsStandard",
+]

clearskies_aws/contexts/cli_web_socket_mock.py

@@ -0,0 +1,20 @@
+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.  It works identically to `clearskies.contexts.Cli` but you have to provide a
+    `connection_id` property in the JSON body.
+    """
+
+    def __call__(self):
+        return self.execute_application(CLIWebSocketMockInputOutput())

clearskies_aws/contexts/lambda_alb.py

@@ -0,0 +1,81 @@
+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 Specifics
+
+    When using this context, two additional named arguments become available to any callables invoked by clearskies:
+
+    ```
+    |      Name     |       Type       | Description                      |
+    |:-------------:|:----------------:|----------------------------------|
+    |    `event`    | `dict[str, Any]` | The lambda `event` object        |
+    |   `context`   | `dict[str, Any]` | The lambda `context` object      |
+    ```
+    """
+
+    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,81 @@
+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 Specifics
+
+    When using this context, a number of additional named arguments become available to any callables invoked by
+    clearskies:
+
+    ```
+    |      Name     |       Type       | Description                      |
+    |:-------------:|:----------------:|----------------------------------|
+    |   ` event`    | `dict[str, Any]` | The lambda `event` object        |
+    |   `context`   | `dict[str, Any]` | The lambda `context` object      |
+    |   `resource`  |       `str`      | The route resource               |
+    |    `stage`    |       `str`      | The stage of the lambda function |
+    |  `request_id` |       `str`      | The AWS request id for the call  |
+    |    `api_id`   |       `str`      | The id of the API                |
+    | `api_version` |       `str`      | "v1" or "v2"                     |
+    ```
+    """
+
+    def __call__(self, event: dict[str, Any], context: dict[str, Any]) -> dict[str, Any]:  # type: ignore[override]
+        return self.execute_application(LambdaApiGatewayInputOutput(event, context))

clearskies_aws/contexts/lambda_api_gateway_web_socket.py

@@ -0,0 +1,79 @@
+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.BodyParameterRouting`
+    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.
+
+    ### Context Specifics
+
+    The following parameters are made available by name to any function invoked by clearskies when using
+    this context:
+
+    ```
+    |       Name      |       Type       | Description                                      |
+    |:---------------:|:----------------:|--------------------------------------------------|
+    |     `event`     | `dict[str, Any]` | The lambda `event` object                        |
+    |    `context`    | `dict[str, Any]` | The lambda `context` object                      |
+    | `connection_id` |       `str`      | The Connection ID                                |
+    |   `route_key`   |       `str`      | The value of the route key, as determined by AWS |
+    |     `stage`     |       `str`      | The stage of the lambda function                 |
+    |   `request_id`  |       `str`      | The AWS request id for the call                  |
+    |     `api_id`    |       `str`      | The id of the API                                |
+    |  `domain_name`  |       `str`      | The domain name                                  |
+    |   `event_type`  |       `str`      | One of "MESSAGE", "CONNECT", or "DISCONNECT"     |
+    |  `connected_at` |       `str`      | The connection time                              |
+    ```
+
+    """
+
+    def __call__(
+        self, event: dict[str, Any], context: dict[str, Any], url: str = "", request_method: str = ""
+    ) -> dict[str, Any]:  # type: ignore[override]
+        return self.execute_application(LambdaApiGatewayWebSocketInputOutput(event, context, url))

clearskies_aws/contexts/lambda_invoke.py

@@ -0,0 +1,138 @@
+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 LambdaInvoke as LambdaInvokeInputOutput
+
+
+class LambdaInvoke(Context):
+    """
+    Execute a lambda directly.
+
+    This context is used when your clearskies application is running in a lambda that is executed
+    directly by some variation of `aws lambda invoke`.  For this context, the `event` object passed
+    to the lambda handler becomes the request body in the clearskies application.  Note that, unlike
+    other lambda execution strategies (ALB, Api Gateway, etc...) the event object is exactly equal
+    to the body sent in with the lambda function.
+
+    ### Usage
+
+    Here's a simple example:
+
+    ```
+    import clearskies
+
+
+    def my_function(request_data):
+        return request_data
+
+
+    lambda_invoke = clearskies_aws.contexts.LambdaInvoke(
+        clearskies.endpoints.Callable(
+            my_function,
+            return_standard_response=False,
+        )
+    )
+
+
+    def lambda_handler(event, context):
+        return lambda_invoke(event, context)
+    ```
+
+    You can attach this to a lambda and might invoke it like so, with the following response:
+
+    ```
+    $ aws lambda invoke --function-name [function_name] --cli-binary-format raw-in-base64-out --payload '{"some":"data"}' | jq
+    { "Payload": {"some": "data"} }
+    ```
+
+    Invoking a lambda doesn't happen from an http context, so there is no URL/request method/headers/etc.
+    This typically means that clearskies applications in this context don't do routing and don't have
+    authentication configured.  If you wanted to though, you could use `clearskies.endpoints.BodyParameterRouting`
+    to setup some basic routing and let the invoking client choose a route by providing a parameter in the
+    payload passed to lambda invoke.
+
+    You can pass a URL/request method into the context when you invoke it, which is often used to simplify
+    configuration: you can setup a standard clearskies applications with multiple endpoints, and then
+    use that one application in multiple lambdas, specifying which endpoint to call for each lambda.
+    This can also be helpful if you already have a clearskies application prepared for a standard http context
+    and want to execute some subset of those endpoints in a lambda invoke context.  It looks something like this:
+
+    ```
+    import clearskies
+
+
+    def some_function(request_data):
+        return request_data
+
+
+    def some_other_function(request_data):
+        return request_data
+
+
+    def something_else(request_data):
+        return request_data
+
+
+    lambda_invoke = clearskies_aws.contexts.LambdaInvoke(
+        clearskies.endpoints.EndpointGroup(
+            [
+                clearskies.endpoints.Callable(
+                    some_function,
+                    url="some_function",
+                ),
+                clearskies.endpoints.Callable(
+                    some_other_function,
+                    url="some_other_function",
+                ),
+                clearskies.endpoints.Callable(
+                    something_else,
+                    url="something_else",
+                ),
+            ]
+        )
+    )
+
+
+    def some_function_handler(event, context):
+        return lambda_invoke(event, context, url="some_function")
+
+
+    def some_other_function_handler(event, context):
+        return lambda_invoke(event, context, url="some_other_function")
+
+
+    def something_else_handler(event, context):
+        return lambda_invoke(event, context, url="something_else")
+    ```
+
+    ### Context Specifics
+
+    When using the lambda_invoke context, it exposes a few context specific parameters which can be injected into
+    any function called by clearskies:
+
+    |       Name         |        Type      |           Description           |
+    |:------------------:|:----------------:|:-------------------------------:|
+    |       `event`      | `dict[str, Any]` | The lambda `event` object       |
+    |      `context`     | `dict[str, Any]` | The lambda `context` object     |
+    |  `invocation_type` |      `str`       |        Always `"direct"`        |
+    |   `function_name`  |      `str`       | The name of the lambda function |
+    | `function_version` |      `str`       |       The function version      |
+    |    `request_id`    |      `str`       | The AWS request id for the call |
+
+    """
+
+    def __call__(
+        self, event: dict[str, Any], context: dict[str, Any], request_method: str = "", url: str = ""
+    ) -> dict[str, Any]:  # type: ignore[override]
+        return self.execute_application(
+            LambdaInvokeInputOutput(
+                event,
+                context,
+                request_method=request_method,
+                url=url,
+            )
+        )

clearskies_aws/contexts/lambda_sns.py

@@ -0,0 +1,124 @@
+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 LambdaSns as LambdaSnsInputOutput
+
+
+class LambdaSns(Context):
+    """
+    Execute a clearskies application when attached to a lambda triggered by SNS.
+
+    This one is very straight-forward: just attach your clearskies application to work with an
+    SNS-triggered lambda.  `request_data` provided to the clearskies application will be the
+    message sent to the SNS.  Since this is no longer an http context, the various http parameters
+    (url, request method, headers, and even responses) do not exist.  Routing won't exist unless
+    you use `clearskies.endpoints.BodyParameterRouting` and include the route parameter in your
+    SNS message body.
+
+    ### Usage
+
+    Here's a simple example:
+
+    ```
+    import clearskies
+
+
+    def my_function(request_data):
+        print(request_data)
+
+
+    lambda_invoke = clearskies_aws.contexts.LambdaInvoke(
+        clearskies.endpoints.Callable(
+            my_function,
+            return_standard_response=False,
+        )
+    )
+
+
+    def lambda_handler(event, context):
+        return lambda_invoke(event, context)
+    ```
+
+    Note the lack of a return value.  You can return a value if you want, but it will be ignored
+    because SNS has no concept of a return response.
+
+    If you have a number of Lambda/SNS handlers, you can bundle them together for ease-of-management
+    and specify the URL when you invoke them:
+
+    ```
+    import clearskies
+
+
+    def some_function(request_data):
+        return request_data
+
+
+    def some_other_function(request_data):
+        return request_data
+
+
+    def something_else(request_data):
+        return request_data
+
+
+    lambda_invoke = clearskies_aws.contexts.LambdaSns(
+        clearskies.endpoints.EndpointGroup(
+            [
+                clearskies.endpoints.Callable(
+                    some_function,
+                    url="some_function",
+                ),
+                clearskies.endpoints.Callable(
+                    some_other_function,
+                    url="some_other_function",
+                ),
+                clearskies.endpoints.Callable(
+                    something_else,
+                    url="something_else",
+                ),
+            ]
+        )
+    )
+
+
+    def some_function_handler(event, context):
+        return lambda_invoke(event, context, url="some_function")
+
+
+    def some_other_function_handler(event, context):
+        return lambda_invoke(event, context, url="some_other_function")
+
+
+    def something_else_handler(event, context):
+        return lambda_invoke(event, context, url="something_else")
+    ```
+
+    ### Context Specifics
+
+    When you use the LambdaSns context, it makes the following named parameters available
+    to any callable that is invoked by clearskies:
+
+    ```
+    |    Name      |      Type        | Description                                    |
+    |:------------:|:----------------:|------------------------------------------------|
+    |    `event`   | `dict[str, Any]` | The lambda `event` object                      |
+    |   `context`  | `dict[str, Any]` | The lambda `context` object                    |
+    | `message_id` |       `str`      | The AWS message id                             |
+    |  `topic_arn` |       `str`      | The ARN of the SNS topic that sent the message |
+    |   `subject`  |       `str`      | Any subject attached to the SNS message        |
+    |  `timestamp` |       `str`      | The timestamp when the message was sent        |
+    ```
+    """
+
+    def __call__(self, event: dict[str, Any], context: dict[str, Any], request_method: str = "", url: str = ""):  # type: ignore[override]
+        try:
+            return self.execute_application(
+                LambdaSnsInputOutput(event, context, request_method=request_method, url=url)
+            )
+        except Exception as e:
+            print("Failed message " + event["Records"][0]["Sns"]["MessageId"] + ". Error error: " + str(e))
+            raise e