aws-python-helper 0.30.1__tar.gz → 0.32.0__tar.gz

{aws_python_helper-0.30.1 → aws_python_helper-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aws-python-helper
-Version: 0.30.1
+Version: 0.32.0
 Summary: AWS Python Helper Framework
 Author-email: Fabian Claros <neufabiae@gmail.com>
 License: MIT
@@ -29,6 +29,7 @@ Mini-framework to create REST APIs, SQS Consumers, SNS Publishers, Fargate Tasks
 - **OOP structure**: Object-oriented programming for your code
 - **Flexible MongoDB**: Direct access to multiple databases without models
 - **External MongoDB**: Connect to multiple MongoDB clusters simultaneously
+- **Multi-state routing**: Automatic `constitution-state` propagation across the entire call chain for per-state database routing
 - **SQS Consumers**: Same pattern to process SQS messages (single or batch mode)
 - **SNS Publishers**: Same pattern to publish messages to SNS topics
 - **Fargate Tasks**: Same pattern to run tasks in Fargate containers
@@ -60,6 +61,9 @@ All available classes and functions:
 | `FargateTask` | `aws_python_helper.fargate.task_base` | Base class for Fargate tasks |
 | `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 |
+| `get_state` | `aws_python_helper` | Read the current constitution-state from async context |
+| `set_state` | `aws_python_helper` | Set the current constitution-state in async context |
 | `MongoJSONEncoder` | `aws_python_helper.utils.json_encoder` | JSON encoder for MongoDB types |
 | `mongo_json_dumps` | `aws_python_helper.utils.json_encoder` | Helper to serialize MongoDB types |
 | `serialize_mongo_types` | `aws_python_helper.utils.serializer` | Recursively serialize MongoDB types |
@@ -268,6 +272,7 @@ response = lambda_client.invoke(
     FunctionName='GenerateRouteLambda',
     InvocationType='RequestResponse',
     Payload=json.dumps({
+        'constitution-state': 'connecticut',  # Required
         'data': {
             'shipping_id': '507f1f77bcf86cd799439011'
         }
@@ -291,6 +296,7 @@ lambda_client.invoke(
     FunctionName='GenerateRouteLambda',
     InvocationType='Event',  # Asynchronous
     Payload=json.dumps({
+        'constitution-state': 'connecticut',  # Required
         'data': {
             'shipping_id': '507f1f77bcf86cd799439011'
         }
@@ -434,6 +440,7 @@ from aws_python_helper.fargate.executor import FargateExecutor
 
 def handler(event, context):
     executor = FargateExecutor()
+    # constitution-state is auto-propagated as CONSTITUTION_STATE env var in the container
     task_arn = executor.run_task(
         'search-tax-by-town',
         envs={'TOWN': 'Norwalk', 'ONLY_TAX': 'true'}
@@ -489,6 +496,219 @@ class AddressAPI(API):
 
 `self.external_db` is available in `API`, `SQSConsumer`, `Lambda`, and `FargateTask`.
 
+## 🗂️ Repository Pattern
+
+The framework provides a `Repository` base class that eliminates repetitive boilerplate in data access layers. Each repository only declares what collection it uses, whether it belongs to an external cluster, and what indexes to create. The base class handles the MongoDB connection and index creation automatically.
+
+### Properties to override
+
+| Property | Type | Default | Required |
+|----------|------|---------|----------|
+| `collection_name` | `str` | — | **Yes** |
+| `database_key` | `str \| None` | `None` | No — if `None`, uses `constitution-state` from context |
+| `is_external` | `bool` | `False` | No |
+| `cluster_name` | `str` | `None` | Only if `is_external=True` |
+| `indexes` | `list` | `[]` | No |
+
+**`database_key` controls how the database is resolved:**
+- `database_key = "core"` (or any string) → always connects to that specific database.
+- `database_key = None` (default) → reads `constitution-state` from the async context automatically. This makes the repository **state-scoped**: it connects to `"connecticut"`, `"new_jersey"`, etc. depending on the current request.
+
+Collections are cached per `(database_name, collection_name)` key — state-scoped repositories correctly isolate state between concurrent requests.
+
+### Index format
+
+```python
+@property
+def indexes(self):
+    return [
+        {"key": [("field", 1)]},                               # simple ASC
+        {"key": [("field", -1)]},                              # simple DESC
+        {"key": [("f1", 1), ("f2", -1)], "unique": True},     # compound + unique
+        {"key": [("expires_at", 1)], "expireAfterSeconds": 0}, # TTL index
+    ]
+```
+
+Indexes are created automatically in the background on first collection access — no need to call any initialization method.
+
+### Repository with a fixed database
+
+```python
+from aws_python_helper import Repository
+
+class TownsRepository(Repository):
+
+    @property
+    def collection_name(self):
+        return "towns"
+
+    @property
+    def database_key(self):
+        return "core"  # always connects to the "core" database
+
+    @property
+    def indexes(self):
+        return [
+            {"key": [("name", 1)]},
+            {"key": [("platform", 1)]},
+        ]
+
+    async def get_available(self, platforms):
+        return await self.collection.find(
+            {"platform": {"$in": platforms}},
+            {"name": 1, "platform": 1}
+        ).to_list(length=None)
+
+    async def find_by_name(self, name):
+        return await self.collection.find_one({"name": name})
+```
+
+### State-scoped repository (no `database_key`)
+
+When `database_key` is not set, the repository reads the current `constitution-state` from context and uses it as the database name. The same repository instance connects to `"connecticut"` for one request and to `"new_jersey"` for another — automatically.
+
+```python
+from aws_python_helper import Repository
+
+class LandRecordsRepository(Repository):
+
+    @property
+    def collection_name(self):
+        return "records"
+
+    # No database_key → uses get_state() automatically
+    # If constitution-state = "connecticut" → connects to DB "connecticut"
+    # If constitution-state = "new_jersey"  → connects to DB "new_jersey"
+
+    @property
+    def indexes(self):
+        return [
+            {"key": [("unique_id", 1)]},
+            {"key": [("owner", 1), ("town", 1)]},
+        ]
+
+    async def bulk_upsert(self, records):
+        from pymongo import UpdateOne
+        operations = [
+            UpdateOne({"unique_id": r["unique_id"]}, {"$set": r}, upsert=True)
+            for r in records
+        ]
+        result = await self.collection.bulk_write(operations)
+        return {"upserted": result.upserted_count, "modified": result.modified_count}
+```
+
+> **Note:** A `ValueError` is raised at runtime if `database_key` is `None` and `constitution-state` has not been set in the context. This is prevented automatically by the framework at every entry point (API, Lambda, SQS, Fargate).
+
+### Repository on an external cluster
+
+```python
+from aws_python_helper import Repository
+
+class AddressRepository(Repository):
+
+    @property
+    def database_key(self):
+        return "smart_data"
+
+    @property
+    def collection_name(self):
+        return "address"
+
+    @property
+    def is_external(self):
+        return True
+
+    @property
+    def cluster_name(self):
+        return "ClusterDockets"  # Must match a name in EXTERNAL_MONGODB_CONNECTIONS
+
+    async def find_by_query(self, query, limit=None):
+        cursor = self.collection.find(query)
+        if limit:
+            cursor = cursor.limit(limit)
+        return await cursor.to_list(length=None)
+```
+
+### Instantiation — no `db` argument needed
+
+```python
+class MyAPI(API):
+
+    @property
+    def towns_repository(self):
+        if not self._towns_repository:
+            self._towns_repository = TownsRepository()  # no args!
+        return self._towns_repository
+
+    async def process(self):
+        towns = await self.towns_repository.get_available(["platform_a", "platform_b"])
+        self.set_body({"towns": towns})
+```
+
+The repository connects itself using the already-initialized `MongoManager` singleton — the same one used by `self.db`. No need to pass `self.db` or any connection object.
+
+## 🌐 Constitution State
+
+The framework uses a `constitution-state` value to support **multi-state database routing** — connecting each request to the correct database based on the state it belongs to (e.g., `"connecticut"`, `"new_jersey"`). This value is propagated automatically across the entire async call chain using Python's `contextvars.ContextVar`, so you never need to pass it manually between layers.
+
+### How the framework injects it at each entry point
+
+| Entry point | How `constitution-state` is read |
+|-------------|----------------------------------|
+| **API Gateway** | HTTP header `constitution-state` — **required**, returns `400` if missing |
+| **Standalone Lambda** | Field `constitution-state` in the event payload — **required**, raises `ValueError` if missing |
+| **SQS Consumer (single mode)** | Per-record: reads from SNS `MessageAttributes['constitution-state']`, falls back to `body.constitution_state` |
+| **SQS Consumer (batch mode)** | Groups records by state; calls `process_batch()` once per group with the correct state in context |
+| **Fargate Task** | Env var `CONSTITUTION_STATE` — auto-injected by `FargateExecutor` |
+
+### How the framework propagates it to downstream services
+
+| Downstream service | Propagation mechanism |
+|--------------------|-----------------------|
+| **SNS Publisher** | Auto-injects `constitution-state` as a `MessageAttribute` on every published message |
+| **FargateExecutor** | Auto-injects `CONSTITUTION_STATE` as an env var when launching Fargate containers |
+
+This means that an API call with `constitution-state: connecticut` will automatically carry that state through SNS → SQS → Fargate without any code changes in your consumers or tasks.
+
+### State-scoped repositories
+
+Repositories with no `database_key` (default) read `constitution-state` from context to resolve the target database automatically. See the [Repository Pattern](#️-repository-pattern) section for details.
+
+### Manual access
+
+If you need to read or set the state manually (e.g., in tests or utility code):
+
+```python
+from aws_python_helper import get_state, set_state
+
+state = get_state()      # e.g. "connecticut", or None if not set
+set_state("new_jersey")  # set manually (the framework does this automatically)
+```
+
+### API example — `constitution-state` header
+
+```
+GET /constitutions HTTP/1.1
+constitution-state: connecticut
+Authorization: Bearer <token>
+```
+
+### Lambda invocation example — `constitution-state` in event
+
+```python
+import boto3, json
+
+lambda_client = boto3.client('lambda')
+lambda_client.invoke(
+    FunctionName='MyLambdaFunction',
+    InvocationType='RequestResponse',
+    Payload=json.dumps({
+        'constitution-state': 'connecticut',   # Required
+        'data': {'key': 'value'}
+    })
+)
+```
+
 ## 🔄 Routing Convention
 
 The framework uses convention over configuration for the routing:
@@ -880,6 +1100,7 @@ environment_variables = {
 | `AUTH_BYPASS_TOKEN` | Optional | Master token to bypass authentication |
 | `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 |
 | `AWS_REGION` | Fargate/SNS/SQS | AWS region |
 | `AWS_ACCOUNT_ID` | SQS `get_queue_url` | AWS account ID |
 | `SERVICE_NAME` | SQS `get_queue_url` | Service name prefix for queue name |
@@ -890,7 +1111,11 @@ environment_variables = {
 
 ### SQS Consumer - Batch Mode
 
-By default, consumers process messages one by one (`"single"` mode). Use `"batch"` mode when you need to group or bulk-process messages:
+By default, consumers process messages one by one (`"single"` mode). Use `"batch"` mode when you need to group or bulk-process messages.
+
+**Constitution-state handling in SQS:**
+- **Single mode**: the framework extracts `constitution-state` from each record automatically (from SNS `MessageAttributes`, then from `body.constitution_state`) and sets it in context before calling `process_record()`. You do not need to extract it yourself.
+- **Batch mode**: the framework groups the incoming records by `constitution-state` and calls `process_batch()` once per group, with the correct state in context for each group. This ensures that state-scoped repositories resolve to the right database even when a batch contains records from different states.
 
 ```python
 from aws_python_helper.sqs.consumer_base import SQSConsumer
@@ -939,10 +1164,13 @@ class OrderConsumer(SQSConsumer):
 
 ### SNS Publisher - Batch Publishing
 
+The `SNSPublisher` automatically injects the current `constitution-state` as a `MessageAttribute` on every published message. SQS consumers built with this framework will then extract it automatically, ensuring the state flows end-to-end through the SNS → SQS chain without any manual code.
+
 ```python
 topic = TitleIndexedTopic()
 
 # Publish multiple messages in a single call
+# constitution-state is auto-injected as a MessageAttribute on each message
 await topic.publish([
     {'content': {'id': 'id1', 'title': 'Title 1'}, 'attributes': {'type': 'created'}},
     {'content': {'id': 'id2', 'title': 'Title 2'}, 'attributes': {'type': 'updated'}},

{aws_python_helper-0.30.1 → aws_python_helper-0.32.0}/README.md

@@ -9,6 +9,7 @@ Mini-framework to create REST APIs, SQS Consumers, SNS Publishers, Fargate Tasks
 - **OOP structure**: Object-oriented programming for your code
 - **Flexible MongoDB**: Direct access to multiple databases without models
 - **External MongoDB**: Connect to multiple MongoDB clusters simultaneously
+- **Multi-state routing**: Automatic `constitution-state` propagation across the entire call chain for per-state database routing
 - **SQS Consumers**: Same pattern to process SQS messages (single or batch mode)
 - **SNS Publishers**: Same pattern to publish messages to SNS topics
 - **Fargate Tasks**: Same pattern to run tasks in Fargate containers
@@ -40,6 +41,9 @@ All available classes and functions:
 | `FargateTask` | `aws_python_helper.fargate.task_base` | Base class for Fargate tasks |
 | `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 |
+| `get_state` | `aws_python_helper` | Read the current constitution-state from async context |
+| `set_state` | `aws_python_helper` | Set the current constitution-state in async context |
 | `MongoJSONEncoder` | `aws_python_helper.utils.json_encoder` | JSON encoder for MongoDB types |
 | `mongo_json_dumps` | `aws_python_helper.utils.json_encoder` | Helper to serialize MongoDB types |
 | `serialize_mongo_types` | `aws_python_helper.utils.serializer` | Recursively serialize MongoDB types |
@@ -248,6 +252,7 @@ response = lambda_client.invoke(
     FunctionName='GenerateRouteLambda',
     InvocationType='RequestResponse',
     Payload=json.dumps({
+        'constitution-state': 'connecticut',  # Required
         'data': {
             'shipping_id': '507f1f77bcf86cd799439011'
         }
@@ -271,6 +276,7 @@ lambda_client.invoke(
     FunctionName='GenerateRouteLambda',
     InvocationType='Event',  # Asynchronous
     Payload=json.dumps({
+        'constitution-state': 'connecticut',  # Required
         'data': {
             'shipping_id': '507f1f77bcf86cd799439011'
         }
@@ -414,6 +420,7 @@ from aws_python_helper.fargate.executor import FargateExecutor
 
 def handler(event, context):
     executor = FargateExecutor()
+    # constitution-state is auto-propagated as CONSTITUTION_STATE env var in the container
     task_arn = executor.run_task(
         'search-tax-by-town',
         envs={'TOWN': 'Norwalk', 'ONLY_TAX': 'true'}
@@ -469,6 +476,219 @@ class AddressAPI(API):
 
 `self.external_db` is available in `API`, `SQSConsumer`, `Lambda`, and `FargateTask`.
 
+## 🗂️ Repository Pattern
+
+The framework provides a `Repository` base class that eliminates repetitive boilerplate in data access layers. Each repository only declares what collection it uses, whether it belongs to an external cluster, and what indexes to create. The base class handles the MongoDB connection and index creation automatically.
+
+### Properties to override
+
+| Property | Type | Default | Required |
+|----------|------|---------|----------|
+| `collection_name` | `str` | — | **Yes** |
+| `database_key` | `str \| None` | `None` | No — if `None`, uses `constitution-state` from context |
+| `is_external` | `bool` | `False` | No |
+| `cluster_name` | `str` | `None` | Only if `is_external=True` |
+| `indexes` | `list` | `[]` | No |
+
+**`database_key` controls how the database is resolved:**
+- `database_key = "core"` (or any string) → always connects to that specific database.
+- `database_key = None` (default) → reads `constitution-state` from the async context automatically. This makes the repository **state-scoped**: it connects to `"connecticut"`, `"new_jersey"`, etc. depending on the current request.
+
+Collections are cached per `(database_name, collection_name)` key — state-scoped repositories correctly isolate state between concurrent requests.
+
+### Index format
+
+```python
+@property
+def indexes(self):
+    return [
+        {"key": [("field", 1)]},                               # simple ASC
+        {"key": [("field", -1)]},                              # simple DESC
+        {"key": [("f1", 1), ("f2", -1)], "unique": True},     # compound + unique
+        {"key": [("expires_at", 1)], "expireAfterSeconds": 0}, # TTL index
+    ]
+```
+
+Indexes are created automatically in the background on first collection access — no need to call any initialization method.
+
+### Repository with a fixed database
+
+```python
+from aws_python_helper import Repository
+
+class TownsRepository(Repository):
+
+    @property
+    def collection_name(self):
+        return "towns"
+
+    @property
+    def database_key(self):
+        return "core"  # always connects to the "core" database
+
+    @property
+    def indexes(self):
+        return [
+            {"key": [("name", 1)]},
+            {"key": [("platform", 1)]},
+        ]
+
+    async def get_available(self, platforms):
+        return await self.collection.find(
+            {"platform": {"$in": platforms}},
+            {"name": 1, "platform": 1}
+        ).to_list(length=None)
+
+    async def find_by_name(self, name):
+        return await self.collection.find_one({"name": name})
+```
+
+### State-scoped repository (no `database_key`)
+
+When `database_key` is not set, the repository reads the current `constitution-state` from context and uses it as the database name. The same repository instance connects to `"connecticut"` for one request and to `"new_jersey"` for another — automatically.
+
+```python
+from aws_python_helper import Repository
+
+class LandRecordsRepository(Repository):
+
+    @property
+    def collection_name(self):
+        return "records"
+
+    # No database_key → uses get_state() automatically
+    # If constitution-state = "connecticut" → connects to DB "connecticut"
+    # If constitution-state = "new_jersey"  → connects to DB "new_jersey"
+
+    @property
+    def indexes(self):
+        return [
+            {"key": [("unique_id", 1)]},
+            {"key": [("owner", 1), ("town", 1)]},
+        ]
+
+    async def bulk_upsert(self, records):
+        from pymongo import UpdateOne
+        operations = [
+            UpdateOne({"unique_id": r["unique_id"]}, {"$set": r}, upsert=True)
+            for r in records
+        ]
+        result = await self.collection.bulk_write(operations)
+        return {"upserted": result.upserted_count, "modified": result.modified_count}
+```
+
+> **Note:** A `ValueError` is raised at runtime if `database_key` is `None` and `constitution-state` has not been set in the context. This is prevented automatically by the framework at every entry point (API, Lambda, SQS, Fargate).
+
+### Repository on an external cluster
+
+```python
+from aws_python_helper import Repository
+
+class AddressRepository(Repository):
+
+    @property
+    def database_key(self):
+        return "smart_data"
+
+    @property
+    def collection_name(self):
+        return "address"
+
+    @property
+    def is_external(self):
+        return True
+
+    @property
+    def cluster_name(self):
+        return "ClusterDockets"  # Must match a name in EXTERNAL_MONGODB_CONNECTIONS
+
+    async def find_by_query(self, query, limit=None):
+        cursor = self.collection.find(query)
+        if limit:
+            cursor = cursor.limit(limit)
+        return await cursor.to_list(length=None)
+```
+
+### Instantiation — no `db` argument needed
+
+```python
+class MyAPI(API):
+
+    @property
+    def towns_repository(self):
+        if not self._towns_repository:
+            self._towns_repository = TownsRepository()  # no args!
+        return self._towns_repository
+
+    async def process(self):
+        towns = await self.towns_repository.get_available(["platform_a", "platform_b"])
+        self.set_body({"towns": towns})
+```
+
+The repository connects itself using the already-initialized `MongoManager` singleton — the same one used by `self.db`. No need to pass `self.db` or any connection object.
+
+## 🌐 Constitution State
+
+The framework uses a `constitution-state` value to support **multi-state database routing** — connecting each request to the correct database based on the state it belongs to (e.g., `"connecticut"`, `"new_jersey"`). This value is propagated automatically across the entire async call chain using Python's `contextvars.ContextVar`, so you never need to pass it manually between layers.
+
+### How the framework injects it at each entry point
+
+| Entry point | How `constitution-state` is read |
+|-------------|----------------------------------|
+| **API Gateway** | HTTP header `constitution-state` — **required**, returns `400` if missing |
+| **Standalone Lambda** | Field `constitution-state` in the event payload — **required**, raises `ValueError` if missing |
+| **SQS Consumer (single mode)** | Per-record: reads from SNS `MessageAttributes['constitution-state']`, falls back to `body.constitution_state` |
+| **SQS Consumer (batch mode)** | Groups records by state; calls `process_batch()` once per group with the correct state in context |
+| **Fargate Task** | Env var `CONSTITUTION_STATE` — auto-injected by `FargateExecutor` |
+
+### How the framework propagates it to downstream services
+
+| Downstream service | Propagation mechanism |
+|--------------------|-----------------------|
+| **SNS Publisher** | Auto-injects `constitution-state` as a `MessageAttribute` on every published message |
+| **FargateExecutor** | Auto-injects `CONSTITUTION_STATE` as an env var when launching Fargate containers |
+
+This means that an API call with `constitution-state: connecticut` will automatically carry that state through SNS → SQS → Fargate without any code changes in your consumers or tasks.
+
+### State-scoped repositories
+
+Repositories with no `database_key` (default) read `constitution-state` from context to resolve the target database automatically. See the [Repository Pattern](#️-repository-pattern) section for details.
+
+### Manual access
+
+If you need to read or set the state manually (e.g., in tests or utility code):
+
+```python
+from aws_python_helper import get_state, set_state
+
+state = get_state()      # e.g. "connecticut", or None if not set
+set_state("new_jersey")  # set manually (the framework does this automatically)
+```
+
+### API example — `constitution-state` header
+
+```
+GET /constitutions HTTP/1.1
+constitution-state: connecticut
+Authorization: Bearer <token>
+```
+
+### Lambda invocation example — `constitution-state` in event
+
+```python
+import boto3, json
+
+lambda_client = boto3.client('lambda')
+lambda_client.invoke(
+    FunctionName='MyLambdaFunction',
+    InvocationType='RequestResponse',
+    Payload=json.dumps({
+        'constitution-state': 'connecticut',   # Required
+        'data': {'key': 'value'}
+    })
+)
+```
+
 ## 🔄 Routing Convention
 
 The framework uses convention over configuration for the routing:
@@ -860,6 +1080,7 @@ environment_variables = {
 | `AUTH_BYPASS_TOKEN` | Optional | Master token to bypass authentication |
 | `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 |
 | `AWS_REGION` | Fargate/SNS/SQS | AWS region |
 | `AWS_ACCOUNT_ID` | SQS `get_queue_url` | AWS account ID |
 | `SERVICE_NAME` | SQS `get_queue_url` | Service name prefix for queue name |
@@ -870,7 +1091,11 @@ environment_variables = {
 
 ### SQS Consumer - Batch Mode
 
-By default, consumers process messages one by one (`"single"` mode). Use `"batch"` mode when you need to group or bulk-process messages:
+By default, consumers process messages one by one (`"single"` mode). Use `"batch"` mode when you need to group or bulk-process messages.
+
+**Constitution-state handling in SQS:**
+- **Single mode**: the framework extracts `constitution-state` from each record automatically (from SNS `MessageAttributes`, then from `body.constitution_state`) and sets it in context before calling `process_record()`. You do not need to extract it yourself.
+- **Batch mode**: the framework groups the incoming records by `constitution-state` and calls `process_batch()` once per group, with the correct state in context for each group. This ensures that state-scoped repositories resolve to the right database even when a batch contains records from different states.
 
 ```python
 from aws_python_helper.sqs.consumer_base import SQSConsumer
@@ -919,10 +1144,13 @@ class OrderConsumer(SQSConsumer):
 
 ### SNS Publisher - Batch Publishing
 
+The `SNSPublisher` automatically injects the current `constitution-state` as a `MessageAttribute` on every published message. SQS consumers built with this framework will then extract it automatically, ensuring the state flows end-to-end through the SNS → SQS chain without any manual code.
+
 ```python
 topic = TitleIndexedTopic()
 
 # Publish multiple messages in a single call
+# constitution-state is auto-injected as a MessageAttribute on each message
 await topic.publish([
     {'content': {'id': 'id1', 'title': 'Title 1'}, 'attributes': {'type': 'created'}},
     {'content': {'id': 'id2', 'title': 'Title 2'}, 'attributes': {'type': 'updated'}},

{aws_python_helper-0.30.1 → aws_python_helper-0.32.0}/aws_python_helper/__init__.py

@@ -24,6 +24,12 @@ from .lambda_standalone.handler import lambda_handler
 from .utils.json_encoder import MongoJSONEncoder, mongo_json_dumps
 from .utils.serializer import serialize_mongo_types
 
+# Repository
+from .repository.base import Repository
+
+# Context
+from .context.state import get_state, set_state
+
 
 __all__ = [
     'API',
@@ -34,6 +40,7 @@ __all__ = [
     'FargateTask',
     'FargateExecutor',
     'Lambda',
+    'Repository',
     'fargate_handler',
     'api_handler',
     'sqs_handler',
@@ -41,5 +48,7 @@ __all__ = [
     'MongoJSONEncoder',
     'mongo_json_dumps',
     'serialize_mongo_types',
+    'get_state',
+    'set_state',
 ]
 

{aws_python_helper-0.30.1 → aws_python_helper-0.32.0}/aws_python_helper/api/dispatcher.py

@@ -12,6 +12,7 @@ from .base import API
 from .exceptions import UnauthorizedError, ForbiddenError, AuthenticationError
 from .auth_middleware import AuthMiddleware
 from .auth_validators import TokenValidator
+from ..context.state import set_state
 
 logger = logging.getLogger(__name__)
 
@@ -78,7 +79,20 @@ class Dispatcher:
             require_auth = os.getenv('REQUIRE_AUTH', 'false').lower() == 'true'
             if require_auth:
                 await self._authenticate(api)
-            
+
+            # 2.5 Setup constitution-state context
+            state = self.headers.get('constitution-state')
+            if not state:
+                return {
+                    'code': 400,
+                    'body': {
+                        'error': 'Bad Request',
+                        'message': "Header 'constitution-state' is required"
+                    },
+                    'headers': {}
+                }
+            set_state(state)
+
             # 3. Validate
             await api.validate()
             

aws_python_helper-0.32.0/aws_python_helper/context/__init__.py

@@ -0,0 +1,3 @@
+from .state import get_state, set_state
+
+__all__ = ['get_state', 'set_state']

aws_python_helper-0.32.0/aws_python_helper/context/state.py

@@ -0,0 +1,22 @@
+"""
+Constitution State Context - Manages request-scoped state for multi-state database routing.
+
+Uses Python's contextvars to propagate the current constitution-state across async call chains.
+Set automatically by the framework at every entry point (API, Lambda, SQS Consumer, Fargate Task).
+Read automatically by state-scoped repositories (database_key = None) to resolve the target database.
+"""
+
+from contextvars import ContextVar
+from typing import Optional
+
+_constitution_state: ContextVar[Optional[str]] = ContextVar('constitution_state', default=None)
+
+
+def get_state() -> Optional[str]:
+    """Get the current constitution state from async context."""
+    return _constitution_state.get()
+
+
+def set_state(state: str) -> None:
+    """Set the current constitution state in async context."""
+    _constitution_state.set(state)