pygrestqlambda 0.0.2__tar.gz → 0.0.4__tar.gz

{pygrestqlambda-0.0.2 → pygrestqlambda-0.0.4}/.github/workflows/publish.yml

@@ -4,6 +4,9 @@ on:
   push:
     tags: [ '*.*.*' ]
 
+env:
+  PROJECT_VERSION: ${{ github.ref_name }}
+
 jobs:
   publish:
     runs-on: ubuntu-latest
@@ -19,6 +22,10 @@ jobs:
         with:
           python-version: '3.11'
 
+      # Run pre-publish step to update project version number to tag
+      - name: Pre-build
+        run: ./scripts/pre-publish.sh
+
       # Re-run validation and build
       - name: Validate
         run: ./scripts/validate.sh

pygrestqlambda-0.0.4/.gitignore

@@ -0,0 +1,10 @@
+# Python
+__pycache__
+
+# Pytest
+/,pytest_cache
+/.coverage*
+/htmlcov
+
+# Build
+/dist

pygrestqlambda-0.0.4/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: pygrestqlambda
+Version: 0.0.4
+Summary: PostgreSQL REST API framework for AWS Lambda functions
+Project-URL: Homepage, https://github.com/mesogate/pygrestqlambda
+Project-URL: Issues, https://github.com/mesogate/pygrestqlambda/issues
+Author-email: Voquis Limited <opensource@voquis.com>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: aws-xray-sdk
+Requires-Dist: boto3
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: docker; extra == 'dev'
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: psycopg[binary]; extra == 'dev'
+Requires-Dist: pylint; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest-xdist; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Python PostgreSQL REST API framework for AWS Lambda functions
+> [!NOTE]
+> Project status: `Alpha`
+
+A REST API web framework for persisting records in a PostgreSQL database.
+
+## Supported features
+- Automatic creation of `uid` fields
+- Automatic setting of `created_at` and `last_updated_at` timestamps
+- Automatic setting of `creator_uid` and `last_updater_uid`
+- RDS with IAM credentials
+
+## Examples
+See [Examples docs directory](./docs/examples/)
+
+## Sequence diagrams
+
+### High-level infrastructure
+
+This sequence diagram shows how a lambda function running this library is intended to be deployed.
+
+```mermaid
+sequenceDiagram
+    # Set up actors and participants
+    actor User
+    participant APIGW as API Gateway
+    participant Cognito as Cognito
+    box Purple This library
+        participant Lambda as Lambda Function
+    end
+    participant RDS as RDS Database
+
+    # Set up Sequences
+    User ->> APIGW: HTTP /resource
+    activate APIGW
+        APIGW -->> Cognito: Authenticate
+        activate Cognito
+            Cognito ->> APIGW: Authenticated
+        deactivate Cognito
+        APIGW ->> Lambda: Send proxy integration request
+        activate Lambda
+            Lambda ->> RDS: Fetch/mutate
+            activate RDS
+                RDS -->> Lambda: Return records
+            deactivate RDS
+            Lambda -->> APIGW: Return response
+        deactivate Lambda
+        APIGW -->> User: Return response
+    deactivate APIGW
+```
+
+### Low-level architecture
+
+This sequence diagram shows the layers within the library that handle request and response processing.
+
+```mermaid
+sequenceDiagram
+
+    Participant APIGW as API Gateway
+    box Purple This library as a deployed Lambda Function
+        Participant CONT as Controller
+        Participant REQM as Request Mapper
+        Participant RESOURCEM as Resource Mapper
+        Participant DBM as Database  Mapper
+        Participant RESPONSEM as Response Mapper
+    end
+    Participant RDS
+
+    APIGW ->> CONT: Send `event` dict
+    activate CONT
+        CONT ->> REQM: Map request
+        activate REQM
+            REQM ->> CONT: Mapped request
+        deactivate REQM
+
+        CONT ->> RESOURCEM: Map resource
+        activate RESOURCEM
+            RESOURCEM -->> CONT: Mapped resource
+        deactivate RESOURCEM
+
+        CONT ->> DBM: Request resource operation
+        activate DBM
+            DBM ->> RDS: Perform resource operation
+            activate RDS
+                RDS -->> DBM: Return resources
+            deactivate RDS
+            DBM -->> CONT: Return resource
+        deactivate DBM
+
+        CONT ->> RESPONSEM: Map response
+        activate RESPONSEM
+            RESPONSEM -->> CONT: Mapped response
+        deactivate RESPONSEM
+
+        CONT -->> APIGW: Return response
+    deactivate CONT
+```

pygrestqlambda-0.0.4/README.md

@@ -0,0 +1,97 @@
+# Python PostgreSQL REST API framework for AWS Lambda functions
+> [!NOTE]
+> Project status: `Alpha`
+
+A REST API web framework for persisting records in a PostgreSQL database.
+
+## Supported features
+- Automatic creation of `uid` fields
+- Automatic setting of `created_at` and `last_updated_at` timestamps
+- Automatic setting of `creator_uid` and `last_updater_uid`
+- RDS with IAM credentials
+
+## Examples
+See [Examples docs directory](./docs/examples/)
+
+## Sequence diagrams
+
+### High-level infrastructure
+
+This sequence diagram shows how a lambda function running this library is intended to be deployed.
+
+```mermaid
+sequenceDiagram
+    # Set up actors and participants
+    actor User
+    participant APIGW as API Gateway
+    participant Cognito as Cognito
+    box Purple This library
+        participant Lambda as Lambda Function
+    end
+    participant RDS as RDS Database
+
+    # Set up Sequences
+    User ->> APIGW: HTTP /resource
+    activate APIGW
+        APIGW -->> Cognito: Authenticate
+        activate Cognito
+            Cognito ->> APIGW: Authenticated
+        deactivate Cognito
+        APIGW ->> Lambda: Send proxy integration request
+        activate Lambda
+            Lambda ->> RDS: Fetch/mutate
+            activate RDS
+                RDS -->> Lambda: Return records
+            deactivate RDS
+            Lambda -->> APIGW: Return response
+        deactivate Lambda
+        APIGW -->> User: Return response
+    deactivate APIGW
+```
+
+### Low-level architecture
+
+This sequence diagram shows the layers within the library that handle request and response processing.
+
+```mermaid
+sequenceDiagram
+
+    Participant APIGW as API Gateway
+    box Purple This library as a deployed Lambda Function
+        Participant CONT as Controller
+        Participant REQM as Request Mapper
+        Participant RESOURCEM as Resource Mapper
+        Participant DBM as Database  Mapper
+        Participant RESPONSEM as Response Mapper
+    end
+    Participant RDS
+
+    APIGW ->> CONT: Send `event` dict
+    activate CONT
+        CONT ->> REQM: Map request
+        activate REQM
+            REQM ->> CONT: Mapped request
+        deactivate REQM
+
+        CONT ->> RESOURCEM: Map resource
+        activate RESOURCEM
+            RESOURCEM -->> CONT: Mapped resource
+        deactivate RESOURCEM
+
+        CONT ->> DBM: Request resource operation
+        activate DBM
+            DBM ->> RDS: Perform resource operation
+            activate RDS
+                RDS -->> DBM: Return resources
+            deactivate RDS
+            DBM -->> CONT: Return resource
+        deactivate DBM
+
+        CONT ->> RESPONSEM: Map response
+        activate RESPONSEM
+            RESPONSEM -->> CONT: Mapped response
+        deactivate RESPONSEM
+
+        CONT -->> APIGW: Return response
+    deactivate CONT
+```

{pygrestqlambda-0.0.2 → pygrestqlambda-0.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ requires = ["hatchling"]
 
 [project]
 name = "pygrestqlambda"
-version = "0.0.2"
+version = "0.0.4"
 description = "PostgreSQL REST API framework for AWS Lambda functions"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -25,9 +25,13 @@ dependencies = [
 [project.optional-dependencies]
 dev = [
   "build",
+  "docker",
+  "httpx",
+  "psycopg[binary]",
   "pylint",
   "pytest",
   "pytest-cov",
+  "pytest-xdist",
   "ruff",
   "twine"
 ]

pygrestqlambda-0.0.4/scripts/pre-publish.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+
+# Override pyproject version if environment variable is set
+PROJECT_VERSION=${PROJECT_VERSION:=0.0.0}
+echo "Setting project version: ${PROJECT_VERSION}"
+sed -i -e "s/version.*=.*\".*\"/version = \"${PROJECT_VERSION}\"/" pyproject.toml

{pygrestqlambda-0.0.2 → pygrestqlambda-0.0.4}/scripts/validate.sh

@@ -20,9 +20,12 @@ pylint src tests
 # Run tests and generate coverage reports
 echo "Running pytest"
 pytest --cov="$PACKAGE_NAME" \
+  -n auto \
   --cov-report term \
   --cov-report html \
-  --cov-fail-under=100.00
+  --cov-fail-under=100.00 \
+   -o log_cli=true \
+   --log-cli-level=INFO
 
 # Check the build
 python -m build

pygrestqlambda-0.0.4/src/pygrestqlambda/aws/lambda_function/json_transform.py

@@ -0,0 +1,29 @@
+"""
+JSON output transformer for non-serialisable values
+"""
+
+from datetime import date, datetime
+from decimal import Decimal
+from uuid import UUID
+
+def to_string(value: object) -> str:
+    """
+    Calculates the string version of an object to return in a JSON response
+    """
+
+    # Handle UUIDs
+    if isinstance(value, UUID):
+        value = str(value)
+
+    # Handle date/timestamps
+    if isinstance(value, datetime):
+        value = value.isoformat()
+
+    if isinstance(value, date):
+        value = value.isoformat()
+
+    # Handle decimals
+    if isinstance(value, Decimal):
+        value = float(value)
+
+    return value

pygrestqlambda-0.0.4/src/pygrestqlambda/aws/lambda_function/rest_api_gateway_proxy_integration.py

@@ -0,0 +1,149 @@
+"""
+Receives payload in format sent by AWS REST API Gateway
+https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format
+
+Returns payload structure expected by REST API Gateway
+https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-output-format
+"""
+
+from base64 import b64encode, b64decode
+from dataclasses import dataclass
+import json
+import logging
+from pygrestqlambda.aws.lambda_function.json_transform import to_string
+
+
+@dataclass
+class Response:
+    """
+    Lambda function proxy response for REST API Gateway
+    """
+    is_base64_encoded: bool | None = False
+    status_code: int | None = 401
+    headers: dict | None = None
+    multi_value_headers: dict | None = None
+    body: str | dict | None = None
+
+    def get_payload(self) -> dict:
+        """
+        Gets payload to send to REST API Gateway
+        """
+
+        is_json = False
+        if isinstance(self.body, dict):
+            is_json = True
+
+        # Set headers
+        if self.headers is None:
+            self.headers = {}
+
+        if "Content-Type" not in self.headers:
+            logging.debug("No content type header set")
+            if is_json:
+                logging.debug("Using application/json for content-type")
+                self.headers["Content-Type"] = "application/json"
+            else:
+                logging.debug("Using text/plain for content-type")
+                self.headers["Content-Type"] = "text/plain"
+
+        # Calculate body
+        if self.is_base64_encoded:
+            body = b64encode(self.body).decode("utf-8")
+        else:
+            if is_json:
+                logging.debug("Body is a JSON object")
+                body = json.dumps(self.body, default=to_string)
+            else:
+                logging.debug("Body is plain text")
+                body = self.body
+
+        logging.debug("Transforming dataclass dictionary to JSON")
+        data = {
+            "isBase64Encoded": self.is_base64_encoded,
+            "statusCode": self.status_code,
+            "headers": self.headers,
+            "multiValueHeaders": self.multi_value_headers,
+            "body": body,
+        }
+
+        return data
+
+# pylint: disable=too-many-instance-attributes
+class Request:
+    """
+    Lambda function proxy integration request
+    """
+
+    def __init__(self, event: dict):
+        self.event = event
+        # Extract authorisation information
+        self.cognito_uid = self.get_cognito_uid()
+        # Extract headers needed for body and response
+        self.accept: str = self.get_header('accept')
+        self.content_type: str = self.get_header('content-type')
+        # Extract resource
+        self.resource = event.get('resource')
+        self.method = event.get('httpMethod')
+        # Extract parameters
+        self.query_params = event.get('multiValueQueryStringParameters')
+        self.path_params = event.get('pathParameters')
+        # Extract body
+        self.body = self.get_body()
+
+
+    def get_body(self):
+        """
+        Returns body from request, decodes from base64 if necessary
+        """
+
+        body = self.event.get('body')
+        content = body
+        if self.event.get('isBase64Encoded'):
+            if body:
+                content = b64decode(body)
+
+        # Handle no content type
+        if self.content_type is None:
+            return content
+
+        # Handle plain text
+        if self.content_type.lower() == 'text/plain':
+            return str(content)
+
+        # Handle JSON
+        if self.content_type.lower() == 'application/json':
+            return json.loads(content)
+
+        return content
+
+
+    def get_cognito_uid(self):
+        """
+        Retrieve Cognito UID from supplied claim
+        """
+        claims = self.event.get('requestContext', {}).get('authorizer', {}).get('claims')
+
+        if claims is None:
+            logging.info('No claims in event request context authoriser')
+            return None
+
+        cognito_uid = claims.get('sub')
+
+        return cognito_uid
+
+
+    def get_header(self, header_name: str):
+        """
+        Retrieve Accept header
+        """
+
+        headers = self.event.get('headers')
+        if headers is None:
+            return None
+
+        # Lowercase all the headers
+        headers_lower = {k.lower():v for k,v in headers.items()}
+
+        accept = headers_lower.get(header_name.lower())
+
+        return accept

pygrestqlambda-0.0.4/tests/integration/conftest.py

@@ -0,0 +1,39 @@
+"""
+Pytest configuration file, sets up fixtures to be re-used and set up pre-test
+configuration.
+Uses [docker](https://docker-py.readthedocs.io/en/stable/index.html) python
+client to manage container.
+"""
+
+from pytest import fixture
+from tests.integration.utils.constants import POSTGRES_NAME, LAMBDA_FUNCTION_NAME
+from tests.integration.utils.db_postgres import get_postgres_connection
+from tests.integration.utils.lambda_function import get_base_url
+from tests.integration.utils.docker import remove_container
+
+@fixture(scope="session")
+def postgres():
+    """
+    Return a psycopg database connection
+    """
+
+    return get_postgres_connection()
+
+
+@fixture(scope="session")
+def lambda_function_url():
+    """
+    Return a lambda function for making requests to
+    """
+
+    return get_base_url()
+
+
+def pytest_sessionfinish():
+    """
+    Runs after all tests have completed
+    Tear down containers.
+    """
+
+    remove_container(POSTGRES_NAME)
+    remove_container(LAMBDA_FUNCTION_NAME)

pygrestqlambda-0.0.4/tests/integration/test_database.py

@@ -0,0 +1,13 @@
+"""
+Database connection tests
+"""
+
+from psycopg.connection import Connection
+
+def test_postgres(postgres: Connection):
+    """
+    Test whether a connection to a local postgres Docker container can be established.
+    """
+
+    result = postgres.execute("select 8 + 4 AS twelve").fetchone()
+    assert result['twelve'] == 12

pygrestqlambda-0.0.4/tests/integration/test_lambda_function.py

@@ -0,0 +1,14 @@
+"""
+Database connection tests
+"""
+
+import httpx
+
+def test_lambda_function(lambda_function_url: str):
+    """
+    Test whether a connection to a built local lambda function can be established
+    """
+
+
+    response = httpx.post(url=lambda_function_url, json={})
+    assert response.json()['body'] == 'hello world'

pygrestqlambda-0.0.4/tests/integration/utils/constants.py

@@ -0,0 +1,15 @@
+"""
+Integration testing constants, e.g. database connection parameters used by database server
+containers and test clients.
+"""
+
+from uuid import uuid4
+
+UID = str(uuid4())
+POSTGRES_NAME = f'pytest-postgres-{UID}'
+MYSQL_NAME = f'pytest-mysql-{UID}'
+LAMBDA_FUNCTION_NAME = f'pytest-lambda-{UID}'
+
+DB_NAME = 'pytest'
+USERNAME = 'pytest'
+PASSWORD = 'pytest'

pygrestqlambda-0.0.4/tests/integration/utils/db_postgres.py

@@ -0,0 +1,85 @@
+"""
+Postgres database Docker integration testing utilities for set up and tear down
+"""
+
+import docker
+from docker.models.containers import Container
+from docker.errors import NotFound
+import psycopg
+from psycopg.connection import Connection
+from psycopg.rows import dict_row
+from tests.integration.utils.constants import POSTGRES_NAME, DB_NAME, USERNAME, PASSWORD
+from tests.integration.utils.docker import wait_for_healthy_container
+
+
+def create_postgres_container() -> Container:
+    """
+    Create a postgres container
+    """
+
+    # Create postgres container
+    client = docker.from_env()
+    container = client.containers.run(
+        image='postgres:17',
+        name=POSTGRES_NAME,
+        detach=True,
+        ports={'5432/tcp': None},
+        environment={
+            'POSTGRES_DB': DB_NAME,
+            'POSTGRES_USER': USERNAME,
+            'POSTGRES_PASSWORD': PASSWORD,
+        },
+        healthcheck={
+            "test": "psql -h localhost -U $POSTGRES_USER -c 'select 3 + 2;'",
+            "interval": 1000000000, # 1 second in nanoseconds
+            "retries": 20,
+        },
+        command="""
+            -c ssl=on
+            -c ssl_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem
+            -c ssl_key_file=/etc/ssl/private/ssl-cert-snakeoil.key
+        """
+    )
+
+    return container
+
+
+def get_postgres_container(create: bool = True) -> Container | None:
+    """
+    Return the running postgres Docker container, starting one if none exist
+    """
+
+    client = docker.from_env()
+
+    try:
+        container = client.containers.get(container_id=POSTGRES_NAME)
+    except NotFound:
+        if create:
+            container = create_postgres_container()
+        else:
+            return None
+
+    wait_for_healthy_container(container=container)
+
+    return container
+
+
+def get_postgres_connection() -> Connection:
+    """
+    Return a connection to the running postgres container
+    """
+
+    container = get_postgres_container()
+
+    connection = psycopg.connect(
+        host='127.0.0.1',
+        port=container.ports['5432/tcp'][0]['HostPort'],
+        user=USERNAME,
+        password=PASSWORD,
+        dbname=DB_NAME,
+        sslmode='require',
+    )
+
+    connection.row_factory = dict_row
+
+    return connection