Add AWS SAM integration

Why these changes are being introduced:

AWS SAM is a way to run the Lambda as a container in a
way that simulates much of the deployed context: HTTP requests,
memory resources, etc.

How this addresses that need:
* Adds new 'sam' module in tests
* Adds documentation and Makefile commands to support testing
the lambda function with AWS SAM

Side effects of this change:
* None

Relevant ticket(s):
* None

Author: ghukill

.gitignore

@@ -136,4 +136,8 @@ dmypy.json
 .vscode/
 
 # jetbrains
-.idea/
+.idea/
+
+# SAM
+.aws-sam/
+tests/sam/env.json

Makefile

@@ -64,4 +64,18 @@ black-apply: # Apply changes with 'black'
 	uv run black .
 
 ruff-apply: # Resolve 'fixable errors' with 'ruff'
-	uv run ruff check --fix .
+	uv run ruff check --fix .
+
+####################################
+# SAM Lambda
+####################################
+sam-build: # Build SAM image for running Lambda locally
+	sam build --template tests/sam/template.yaml
+
+sam-http-run: # Run lambda locally as an HTTP server
+	sam local start-api --template tests/sam/template.yaml --env-vars tests/sam/env.json
+
+sam-http-ping: # Send curl command to SAM HTTP server
+	curl --location 'http://localhost:3000/myapp' \
+	--header 'Content-Type: application/json' \
+	--data '{"msg":"in a bottle"}'

README.md

@@ -32,42 +32,78 @@ Description of the function/functions.
 - To run unit tests: `make test`
 - To lint the repo: `make lint`
 
-## Running Locally with Docker
+## Testing Locally with AWS SAM
 
-<https://docs.aws.amazon.com/lambda/latest/dg/images-test.html>
+### SAM Installation
 
-- Build the container:
+Ensure that AWS SAM CLI is installed: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html.
 
-  ```bash
-  docker build -t my_function:latest .
-  ```
+All following actions and commands should be performed from the root of the project (i.e. same directory as the `Dockerfile`).
 
-- Run the default handler for the container:
+### Building and Configuration
 
-  ```bash
-  docker run -e WORKSPACE=dev -p 9000:8080 my_function:latest
-  ```
+1- Create a JSON file for SAM that has environment variables for the container 
 
-- Post to the container:
+- copy `tests/sam/env.json.template` to `tests/sam/env.json` (which is git ignored)
+- fill in missing sensitive env vars
 
-  ```bash
-  curl -XPOST "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'
-  ```
+**NOTE:** AWS credentials are automatically passed from the terminal context that runs `make sam-run`; they do not need to be explicitly set as env vars.
 
-- Observe output:
+2- Build Docker image:
+```shell
+make sam-build
+```
+
+### Invoking Lambda via HTTP requests
 
-  ```
-  "You have successfully called this lambda!"
-  ```
+The following outlines how to run the Lambda SAM docker image as an HTTP endpoint, accepting requests and returning respnoses similar to a lambda behind an ALB, Function URL, or API Gateway.
 
-## Running a Specific Handler Locally with Docker
+1- Ensure any required AWS credentials set in terminal, and any other env vars in `tests/sam/env.json` up-to-date.
+ 
+2- Run HTTP server:
+```shell
+make sam-http-run
+```
 
-If this repo contains multiple lambda functions, you can call any handler you copy into the container (see Dockerfile) by name as part of the `docker run` command:
+This starts a server at `http://localhost:3000`.  Requests must include a path, e.g. `/myapp`, but are arbitrary insofar as the lambda does not utilize them in the request payload. 
 
-```bash
-docker run -p 9000:8080 my_function:latest lambdas.<a-different-module>.lambda_handler
+3- In another terminal, perform an HTTP request via another `Makefile` command:
+```shell
+make sam-http-ping
 ```
 
+Response should have an HTTP status of `200` and respond with:
+```json
+{
+    "response": "pong"
+}
+```
+
+### Invoking Lambda directly
+
+While Lambdas can be invoked via HTTP methods (ALB, Function URL, etc.), they are also often invoked directly with an `event` payload.  To do so with SAM, you do **not** need to first start an HTTP server with `make sam-run`, you can invoke the function image directly:
+
+```shell
+echo '{"action": "ping","challenge_secret":"totally-local-archival-packaging"}' | sam local invoke -e -
+```
+
+Response:
+```text
+{"statusCode": 200, "statusDescription": "200 OK", "headers": {"Content-Type": "application/json"}, "isBase64Encoded": false, "body": "{\"response\": \"pong\"}"}
+```
+
+As you can see from this response, the lambda is still returning a dictionary that _would_ work for an HTTP response, but is actually just a dictionary with the required information.
+
+It's unknown at this time if APT will get invoked via non-HTTP methods, but SAM will be helpful for testing and development if so.
+
+### Troubleshoot
+
+#### Encounter error `botocore.exceptions.TokenRetrievalError`
+
+When running a Lambda via SAM, it attempts to parse and setup AWS credentials just like a real Lambda would establish them.  Depending on how you setup AWS credentials on your host machine, if they are stale or invalid, you may encounter this error when making your first requests of the Lambda.
+
+**Solution:** Stop the SAM container, refresh AWS credentials, and restart it.
+
 ## Environment Variables
 
 ### Required

tests/sam/env.json.template

@@ -0,0 +1,3 @@
+{
+  "MyApp": {}
+}

tests/sam/template.yaml

@@ -0,0 +1,28 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Resources:
+  MyApp:
+    Type: AWS::Serverless::Function
+    Properties:
+      PackageType: Image
+      Timeout: 900
+      MemorySize: 1024
+      Events:
+        BagitApi:
+          Type: HttpApi
+          Properties:
+            Path: /{proxy+}
+            Method: ANY
+      ImageUri: myapp:latest
+      Environment:
+        # While tests/sam/env.json is required for sensitive env vars, ALL env vars
+        # used in the lambda must exist here as well, even just as "..." placeholders.
+        Variables:
+          WORKSPACE: "dev"
+          WARNING_ONLY_LOGGERS: "asyncio,botocore,urllib3,s3transfer,boto3"
+          #SENTRY_DSN: "None"
+    Metadata:
+      DockerContext: ../../. # Build Lambda Dockerfile
+      DockerTag: latest
+      Dockerfile: Dockerfile
+      SamResourceId: MyApp