aws-python-helper 0.35.0__tar.gz → 0.37.0__tar.gz

{aws_python_helper-0.35.0 → aws_python_helper-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aws-python-helper
-Version: 0.35.0
+Version: 0.37.0
 Summary: AWS Python Helper Framework
 Author-email: Fabian Claros <neufabiae@gmail.com>
 License-Expression: MIT
@@ -15,6 +15,8 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: motor==3.3.2
 Requires-Dist: pymongo==4.6.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: httpx>=0.27.0
 
 # AWS Python Framework
 
@@ -33,6 +35,10 @@ Mini-framework to create REST APIs, SQS Consumers, SNS Publishers, Fargate Tasks
 - **Fargate Tasks**: Same pattern to run tasks in Fargate containers
 - **Standalone Lambdas**: Create lambdas invocable directly with AWS SDK
 - **Authentication middleware**: Built-in token-based authentication
+- **Pydantic schema validation**: Declare a `schema` property on any `API` or `Lambda` and the framework validates automatically before `validate()` — returns 400 on failure
+- **LambdaInvoker**: Invoke other Lambda functions (sync or async) with built-in error handling
+- **ApiClient**: HTTP client for inter-service communication — resolves service URLs and auth token from environment variables automatically
+- **ModelQueryLambda**: Base class for MongoDB query-proxy Lambdas — declare an `allowed_collections` whitelist and the framework handles `find` and `aggregate` operations generically
 - **JSON utilities**: Automatic serialization of MongoDB types
 - **Type hints**: Modern Python with type annotations
 - **Async/await**: Full support for asynchronous operations
@@ -60,6 +66,14 @@ All available classes and functions:
 | `FargateExecutor` | `aws_python_helper.fargate.executor` | Launches Fargate tasks from Lambda |
 | `fargate_handler` | `aws_python_helper.fargate.handler` | Entry point handler for Fargate |
 | `Repository` | `aws_python_helper.repository.base` | Base class for MongoDB repositories |
+| `ModelQueryLambda` | `aws_python_helper` | Generic MongoDB query-proxy Lambda base class |
+| `LambdaInvoker` | `aws_python_helper` | Invoke Lambda functions (sync/async) with error handling |
+| `ApiClient` | `aws_python_helper` | HTTP client for inter-service communication |
+| `LambdaInvocationError` | `aws_python_helper` | Raised when boto3 fails to invoke a Lambda |
+| `LambdaResponseError` | `aws_python_helper` | Raised when a Lambda returns a FunctionError |
+| `ServiceNotConfiguredError` | `aws_python_helper` | Raised when a service name is not in MICROSERVICE_URLS |
+| `ApiClientError` | `aws_python_helper` | Raised when an HTTP request fails (network/timeout) |
+| `ApiResponseError` | `aws_python_helper` | Raised when a remote API returns 4xx/5xx |
 | `Session` | `aws_python_helper` | Request-scoped session object (state + user) |
 | `get_session` | `aws_python_helper` | Read the current Session from async context |
 | `set_session` | `aws_python_helper` | Set the current Session in async context |
@@ -897,19 +911,21 @@ Here's a complete example showing how an API can invoke a standalone lambda:
 **1. The API endpoint** (`src/api/shippings/post.py`):
 
 ```python
-from aws_python_helper.api.base import API
-import boto3
-import json
+from pydantic import BaseModel
+from aws_python_helper import API, LambdaInvoker
+
+class ShippingSchema(BaseModel):
+    customer_id: str
+    address: str
+    items: list[str]
 
 class ShippingPostAPI(API):
-    async def validate(self):
-        required_fields = ['customer_id', 'address', 'items']
-        for field in required_fields:
-            if field not in self.data:
-                raise ValueError(f"{field} is required")
+
+    @property
+    def schema(self):
+        return ShippingSchema  # automatic validation → 400 on failure
 
     async def process(self):
-        # Create shipping in database
         shipping = {
             'customer_id': self.data['customer_id'],
             'address': self.data['address'],
@@ -921,15 +937,11 @@ class ShippingPostAPI(API):
         result = await self.db.deliveries.shippings.insert_one(shipping)
         shipping_id = str(result.inserted_id)
 
-        # Invoke standalone lambda asynchronously to generate route
-        lambda_client = boto3.client('lambda')
-        lambda_client.invoke(
-            FunctionName='GenerateRouteLambda',
-            InvocationType='Event',  # Asynchronous
-            Payload=json.dumps({
-                'data': {'shipping_id': shipping_id}
-            })
-        )
+        # Invoke standalone lambda asynchronously (fire-and-forget)
+        invoker = LambdaInvoker()
+        invoker.invoke_async('GenerateRouteLambda', payload={
+            'data': {'shipping_id': shipping_id}
+        })
 
         self.set_code(201)
         self.set_body({
@@ -1008,6 +1020,290 @@ __all__ = ['generate_route_handler']
 - Can retry lambda independently if it fails
 - Scalable architecture
 
+## ✅ Pydantic Schema Validation
+
+The framework supports automatic request validation via [Pydantic](https://docs.pydantic.dev/) v2. Override the `schema` property on any `API` or `Lambda` subclass to declare the expected shape of `self.data`. The framework validates before calling `validate()` and replaces `self.data` with the coerced output — the property name stays the same.
+
+### In an API endpoint
+
+For `POST`/`PUT`, `self.data` is the request body. For `GET`/`LIST`, it is the query parameters. Both are validated the same way.
+
+```python
+from pydantic import BaseModel
+from aws_python_helper import API
+
+class SearchSchema(BaseModel):
+    keys: list[str]
+    state: str
+    limit: int = 100
+
+class SearchPostAPI(API):
+
+    @property
+    def schema(self):
+        return SearchSchema  # ← that's all
+
+    async def process(self):
+        keys  = self.data["keys"]   # self.data is validated and coerced
+        limit = self.data["limit"]  # default applied by Pydantic
+        ...
+```
+
+**On validation failure the framework automatically returns HTTP 400** — no extra code needed.
+
+### In a Standalone Lambda
+
+Same property, same behavior. On failure a `ValueError` is raised, which the handler returns as `{"success": False, "error": "..."}`.
+
+```python
+from pydantic import BaseModel
+from aws_python_helper import Lambda
+
+class SyncSchema(BaseModel):
+    shipping_id: str
+    carrier_id: str
+
+class SyncCarrierLambda(Lambda):
+
+    @property
+    def schema(self):
+        return SyncSchema
+
+    async def process(self):
+        shipping_id = self.data["shipping_id"]  # validated
+        ...
+```
+
+### Without a schema
+
+If `schema` is not overridden (returns `None`, the default), the behavior is identical to before — no change.
+
+---
+
+## 🔗 Inter-Service Communication
+
+The framework provides two utilities for calling other services: `LambdaInvoker` for direct Lambda invocations and `ApiClient` for HTTP API calls.
+
+### LambdaInvoker
+
+Wraps `boto3` Lambda invocations with proper error handling. Never returns `None` — raises typed exceptions instead.
+
+```python
+from aws_python_helper import LambdaInvoker, LambdaInvocationError, LambdaResponseError
+
+invoker = LambdaInvoker()
+
+# Synchronous — waits for result
+result = invoker.invoke("my-function-name", payload={"key": "value"})
+# result is the parsed dict returned by the Lambda
+
+# Asynchronous fire-and-forget
+invoker.invoke_async("my-function-name", payload={"key": "value"})
+```
+
+**Exceptions:**
+
+| Exception | When |
+|-----------|------|
+| `LambdaInvocationError` | boto3 could not reach the function (network, permissions, etc.) |
+| `LambdaResponseError` | The function itself raised an unhandled exception (`FunctionError` in the response) |
+
+**Note:** `boto3` is part of the AWS Lambda Python runtime — no installation needed. For Fargate containers, add `boto3` to your `requirements.txt`.
+
+### ApiClient
+
+HTTP client for service-to-service calls. Resolves the target URL and auth token automatically from environment variables — no hardcoded URLs or tokens in code.
+
+```python
+from aws_python_helper import ApiClient
+
+client = ApiClient("dockets")                               # service name only
+result = await client.post("/search", body={"keys": [...]})
+result = await client.get("/dockets/123")
+result = await client.list("/dockets", params={"state": "CT"})
+result = await client.put("/dockets/123", body={"status": "active"})
+result = await client.patch("/dockets/123", body={"reviewed": True})
+result = await client.delete("/dockets/123")
+
+# Extra headers merged with the defaults (token is always injected automatically)
+client = ApiClient("dockets", headers={"constitution-state": "CT"})
+```
+
+**How URL and token are resolved:**
+
+| Env var | Purpose |
+|---------|---------|
+| `MICROSERVICE_URLS` | JSON map: `{"dockets": "https://api.example.com/", "title-search": "https://..."}` |
+| `INTER_SERVICE_TOKEN` | Bearer token injected as `Authorization: Bearer <token>` |
+| `AUTH_BYPASS_TOKEN` | Fallback if `INTER_SERVICE_TOKEN` is not set |
+
+**Exceptions:**
+
+| Exception | When |
+|-----------|------|
+| `ServiceNotConfiguredError` | Service name not found in `MICROSERVICE_URLS` |
+| `ApiClientError` | Network error or timeout |
+| `ApiResponseError` | Remote API returned 4xx or 5xx (has `.status_code` and `.response_body` attributes) |
+
+**Terraform configuration** — set once per environment in Secrets Manager with keys `inter_service_token` and `microservice_urls`. The Lambda and Fargate modules pick them up automatically from infrastructure outputs; no extra variables needed in resource files beyond passing them through:
+
+```hcl
+# In AWS Secrets Manager secret (JSON):
+# {
+#   "inter_service_token": "my-secret-token",
+#   "microservice_urls": "{\"dockets\": \"https://api-dockets.execute-api.us-east-2.amazonaws.com/\"}",
+#   ...
+# }
+
+# In Terraform module call (already handled by the modules):
+module "my_lambda" {
+  source              = "../modules/lambda"
+  inter_service_token = data.terraform_remote_state.infrastructure.outputs.inter_service_token
+  microservice_urls   = data.terraform_remote_state.infrastructure.outputs.microservice_urls
+  ...
+}
+```
+
+---
+
+## 🔍 ModelQueryLambda
+
+`ModelQueryLambda` is a ready-to-use base class for creating MongoDB query-proxy Lambdas. Instead of writing a custom Lambda every time another microservice needs to read data from your MongoDB, you subclass `ModelQueryLambda`, declare an `allowed_collections` whitelist, and the framework exposes both `find` and `aggregate` operations automatically.
+
+**Use case:** microservice A needs to query data owned by microservice B. Microservice B deploys one `model-query` Lambda; microservice A calls it via `LambdaInvoker` passing the collection name and query parameters.
+
+### Creating a model-query Lambda
+
+Create `src/lambda/model-query/main.py` in the microservice that owns the data:
+
+```python
+from aws_python_helper import ModelQueryLambda
+
+class ModelQueryLambda(ModelQueryLambda):
+
+    @property
+    def allowed_collections(self) -> list:
+        return ["orders", "customers"]  # whitelist — unlisted collections are rejected
+```
+
+Register the handler in `src/handlers/lambda_handler.py`:
+
+```python
+from aws_python_helper.lambda_standalone.handler import lambda_handler
+
+model_query_handler = lambda_handler('model-query')
+
+__all__ = ["model_query_handler"]
+```
+
+### Query modes
+
+#### Aggregate pipeline
+
+Pass a `pipeline` list to run a MongoDB aggregation:
+
+```python
+invoker.invoke("ServiceModelQuery-dev", payload={
+    "session": self.session.to_dict(),
+    "collection": "orders",
+    "pipeline": [
+        {"$match": {"status": "pending"}},
+        {"$sort": {"created_at": -1}},
+        {"$limit": 50},
+    ],
+})
+```
+
+#### Find with filter
+
+Pass `filter`, `fields`, `limit`, and/or `skip` to run a `find`:
+
+```python
+invoker.invoke("ServiceModelQuery-dev", payload={
+    "session": self.session.to_dict(),
+    "collection": "orders",
+    "filter": {"customer_id": "abc123", "status": "active"},
+    "fields": {"_id": 1, "total": 1, "status": 1},  # projection
+    "limit": 20,
+    "skip": 0,
+})
+```
+
+**Note:** `pipeline` and `fields` are mutually exclusive — the framework rejects payloads that include both.
+
+### Payload reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `session` | `dict` | Yes | Session dict from `self.session.to_dict()` — drives state-scoped DB routing |
+| `collection` | `str` | Yes | Collection name (must be in `allowed_collections`) |
+| `pipeline` | `list` | One of | MongoDB aggregation pipeline |
+| `filter` | `dict` | One of | MongoDB filter document (defaults to `{}`) |
+| `fields` | `dict` | No | MongoDB projection (only valid with `filter` mode) |
+| `limit` | `int` | No | Max documents to return |
+| `skip` | `int` | No | Documents to skip (default `0`) |
+
+### Response format
+
+The Lambda always returns the standard framework envelope:
+
+```json
+{
+  "success": true,
+  "data": [ ... ]
+}
+```
+
+On validation error (unknown collection, invalid payload):
+
+```json
+{
+  "success": false,
+  "error": "Collection 'unknown' is not allowed. Allowed: orders, customers"
+}
+```
+
+### Calling it from another microservice
+
+```python
+import os
+from aws_python_helper import LambdaInvoker, LambdaInvocationError
+
+class OrdersPostAPI(API):
+
+    async def process(self):
+        try:
+            response = LambdaInvoker().invoke(
+                os.getenv("ORDERS_MODEL_QUERY_LAMBDA_NAME"),
+                payload={
+                    "session": self.session.to_dict(),
+                    "collection": "orders",
+                    "filter": {"status": "pending"},
+                    "limit": 100,
+                },
+            )
+        except LambdaInvocationError as e:
+            self.logger.error(f"model-query invocation failed: {e}")
+            raise ValueError("Could not retrieve orders. Please try again later.")
+
+        if not response.get("success"):
+            raise ValueError("Could not retrieve orders. Please try again later.")
+
+        orders = response.get("data", [])
+        self.set_body({"orders": orders})
+```
+
+### Session and database routing
+
+The `session` field in the payload is required. The `ModelQueryLambda` uses `session.state` to resolve the target database — the same state-scoped routing used by all framework components. This means:
+
+- `{"session": {"state": "connecticut"}, ...}` → queries the `connecticut` database
+- `{"session": {"state": "new_jersey"}, ...}` → queries the `new_jersey` database
+
+Always pass `self.session.to_dict()` when calling from an API or Lambda to ensure state propagates correctly.
+
+---
+
 ## 🏗️ Architecture Overview
 
 Typical flow for event-driven architectures using this framework:
@@ -1114,6 +1410,8 @@ environment_variables = {
 | `REQUIRE_AUTH` | Optional | Enable authentication middleware (`true`/`false`) |
 | `AUTH_DB_NAME` | If `REQUIRE_AUTH=true` | MongoDB database for token validation |
 | `AUTH_BYPASS_TOKEN` | Optional | Master token to bypass authentication |
+| `INTER_SERVICE_TOKEN` | Optional | Bearer token for `ApiClient` service-to-service calls |
+| `MICROSERVICE_URLS` | Optional | JSON map of service name → base URL used by `ApiClient` |
 | `ECS_CLUSTER` | Fargate only | ECS cluster name for `FargateExecutor` |
 | `ECS_SUBNETS` | Fargate only | Comma-separated subnet IDs for Fargate tasks |
 | `CONSTITUTION_STATE` | Fargate only (auto) | State injected automatically by `FargateExecutor` — do not set manually |