aws-python-helper 0.31.0__tar.gz → 0.33.0__tar.gz

{aws_python_helper-0.31.0 → aws_python_helper-0.33.0}/PKG-INFO

@@ -1,16 +1,15 @@
 Metadata-Version: 2.4
 Name: aws-python-helper
-Version: 0.31.0
+Version: 0.33.0
 Summary: AWS Python Helper Framework
 Author-email: Fabian Claros <neufabiae@gmail.com>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/fabiae/aws-python-framework
 Project-URL: Source Code, https://github.com/fabiae/aws-python-framework
 Project-URL: Bug Tracker, https://github.com/fabiae/aws-python-framework/issues
 Project-URL: Documentation, https://github.com/fabiae/aws-python-framework/blob/main/README.md
 Keywords: aws,python,framework,helper,mongodb,sqs,sns,fargate,lambda
 Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -29,6 +28,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
+- **Session propagation**: Automatic `Session` (state + user) 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
@@ -61,6 +61,9 @@ 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 |
+| `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 |
 | `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 |
@@ -269,6 +272,7 @@ response = lambda_client.invoke(
     FunctionName='GenerateRouteLambda',
     InvocationType='RequestResponse',
     Payload=json.dumps({
+        'session': {'state': 'connecticut'},  # Required
         'data': {
             'shipping_id': '507f1f77bcf86cd799439011'
         }
@@ -292,6 +296,7 @@ lambda_client.invoke(
     FunctionName='GenerateRouteLambda',
     InvocationType='Event',  # Asynchronous
     Payload=json.dumps({
+        'session': {'state': 'connecticut'},  # Required
         'data': {
             'shipping_id': '507f1f77bcf86cd799439011'
         }
@@ -435,6 +440,7 @@ from aws_python_helper.fargate.executor import FargateExecutor
 
 def handler(event, context):
     executor = FargateExecutor()
+    # session is auto-propagated as SESSION env var (JSON) in the container
     task_arn = executor.run_task(
         'search-tax-by-town',
         envs={'TOWN': 'Norwalk', 'ONLY_TAX': 'true'}
@@ -499,11 +505,17 @@ The framework provides a `Repository` base class that eliminates repetitive boil
 | Property | Type | Default | Required |
 |----------|------|---------|----------|
 | `collection_name` | `str` | — | **Yes** |
-| `database_name` | `str` | `"core"` | No |
+| `database_key` | `str \| None` | `None` | No — if `None`, uses `session.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 `session.state` from 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
@@ -519,7 +531,7 @@ def indexes(self):
 
 Indexes are created automatically in the background on first collection access — no need to call any initialization method.
 
-### Repository on the main cluster (`database_name` defaults to `"core"`)
+### Repository with a fixed database
 
 ```python
 from aws_python_helper import Repository
@@ -530,6 +542,10 @@ class TownsRepository(Repository):
     def collection_name(self):
         return "towns"
 
+    @property
+    def database_key(self):
+        return "core"  # always connects to the "core" database
+
     @property
     def indexes(self):
         return [
@@ -547,21 +563,23 @@ class TownsRepository(Repository):
         return await self.collection.find_one({"name": name})
 ```
 
-### Repository on a different database (not `"core"`)
+### State-scoped repository (no `database_key`)
+
+When `database_key` is not set, the repository reads `session.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 database_name(self):
-        return "land_data"
-
     @property
     def collection_name(self):
         return "records"
 
+    # No database_key → uses session.state automatically
+    # If session.state = "connecticut" → connects to DB "connecticut"
+    # If session.state = "new_jersey"  → connects to DB "new_jersey"
+
     @property
     def indexes(self):
         return [
@@ -579,6 +597,8 @@ class LandRecordsRepository(Repository):
         return {"upserted": result.upserted_count, "modified": result.modified_count}
 ```
 
+> **Note:** A `ValueError` is raised at runtime if `database_key` is `None` and `session.state` has not been set. This is prevented automatically by the framework at every entry point (API, Lambda, SQS, Fargate).
+
 ### Repository on an external cluster
 
 ```python
@@ -587,7 +607,7 @@ from aws_python_helper import Repository
 class AddressRepository(Repository):
 
     @property
-    def database_name(self):
+    def database_key(self):
         return "smart_data"
 
     @property
@@ -627,6 +647,84 @@ class MyAPI(API):
 
 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.
 
+## 🌐 Session Context
+
+The framework propagates a `Session` object automatically across the entire async call chain using Python's `contextvars.ContextVar`. The session holds `state` (for multi-state DB routing) and `user` (authenticated user from the auth middleware).
+
+### How the framework injects it at each entry point
+
+| Entry point | How the session is read |
+|-------------|-------------------------|
+| **API Gateway** | `constitution-state` header → `session.state` (when `AUTHORIZATION` includes `state`); auth middleware → `session.user` (when includes `user`). Returns `400` if required header is missing |
+| **Standalone Lambda** | `session` dict in the event payload — **required** (must include `state`), raises `ValueError` if missing |
+| **SQS Consumer (single mode)** | Per-record: reads `session` from SNS `MessageAttributes` (JSON), falls back to legacy `body.constitution_state` |
+| **SQS Consumer (batch mode)** | Groups records by `session.state`; calls `process_batch()` once per group with the correct session in context |
+| **Fargate Task** | `SESSION` env var (JSON) — auto-injected by `FargateExecutor` |
+
+### How the framework propagates it to downstream services
+
+| Downstream service | Propagation mechanism |
+|--------------------|-----------------------|
+| **SNS Publisher** | Auto-injects the full session as a `session` `MessageAttribute` (JSON string) on every published message |
+| **FargateExecutor** | Auto-injects `SESSION` as a JSON env var when launching Fargate containers |
+
+This means that an API call with `constitution-state: connecticut` will automatically carry the full session (state + user) through SNS → SQS → Fargate without any code changes in your consumers or tasks.
+
+### Accessing the session in handlers
+
+All handler base classes expose a `self.session` property:
+
+```python
+class MyAPI(API):
+    async def process(self):
+        state = self.session.state   # e.g. "connecticut"
+        user  = self.session.user    # authenticated user dict, or None
+```
+
+Available in `API`, `SQSConsumer`, `Lambda`, and `FargateTask`.
+
+### State-scoped repositories
+
+Repositories with no `database_key` (default) read `session.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 session manually (e.g., in tests or utility code):
+
+```python
+from aws_python_helper import Session, get_session, set_session
+
+session = get_session()         # returns current Session (creates empty one if not set)
+session.state                   # e.g. "connecticut", or None if not set
+session.user                    # authenticated user dict, or None
+
+set_session(Session(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 — `session` in event
+
+```python
+import boto3, json
+
+lambda_client = boto3.client('lambda')
+lambda_client.invoke(
+    FunctionName='MyLambdaFunction',
+    InvocationType='RequestResponse',
+    Payload=json.dumps({
+        'session': {'state': 'connecticut'},  # Required
+        'data': {'key': 'value'}
+    })
+)
+```
+
 ## 🔄 Routing Convention
 
 The framework uses convention over configuration for the routing:
@@ -662,6 +760,7 @@ All properties and methods available inside an `API` subclass:
 | `self.query_parameters` | `dict` | Query string parameters |
 | `self.db` | `DatabaseProxy` | Access to main MongoDB cluster |
 | `self.external_db` | `ExternalDatabaseProxy` | Access to external MongoDB clusters |
+| `self.session` | `Session` | Request-scoped session (`session.state`, `session.user`) |
 | `self.current_user` | `dict \| None` | Authenticated user document (requires `REQUIRE_AUTH=true`) |
 | `self.is_authenticated` | `bool` | Whether the request is authenticated |
 | `self.auth_data` | `dict \| None` | Full authentication data |
@@ -710,14 +809,14 @@ The framework includes a built-in token-based authentication middleware.
 ### Configuration
 
 ```bash
-REQUIRE_AUTH=true            # Enable authentication (default: false)
+AUTHORIZATION=full           # Authorization mode: 'user', 'state', or 'full' (default: empty/disabled)
 AUTH_DB_NAME=my_database     # MongoDB database where tokens are stored
 AUTH_BYPASS_TOKEN=secret123  # Master token to bypass auth (for internal use)
 ```
 
 ### Using the authenticated user
 
-When `REQUIRE_AUTH=true`, every request must include a valid `Authorization: Bearer <token>` header. The authenticated user is available via `self.current_user`:
+When `AUTHORIZATION` is `user` or `full`, every request must include a valid `Authorization: Bearer <token>` header. The authenticated user is available via `self.current_user`:
 
 ```python
 class OrderListAPI(API):
@@ -1018,6 +1117,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 |
@@ -1028,7 +1128,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
@@ -1077,10 +1181,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.31.0 → aws_python_helper-0.33.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
+- **Session propagation**: Automatic `Session` (state + user) 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
@@ -41,6 +42,9 @@ 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 |
+| `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 |
 | `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 |
@@ -249,6 +253,7 @@ response = lambda_client.invoke(
     FunctionName='GenerateRouteLambda',
     InvocationType='RequestResponse',
     Payload=json.dumps({
+        'session': {'state': 'connecticut'},  # Required
         'data': {
             'shipping_id': '507f1f77bcf86cd799439011'
         }
@@ -272,6 +277,7 @@ lambda_client.invoke(
     FunctionName='GenerateRouteLambda',
     InvocationType='Event',  # Asynchronous
     Payload=json.dumps({
+        'session': {'state': 'connecticut'},  # Required
         'data': {
             'shipping_id': '507f1f77bcf86cd799439011'
         }
@@ -415,6 +421,7 @@ from aws_python_helper.fargate.executor import FargateExecutor
 
 def handler(event, context):
     executor = FargateExecutor()
+    # session is auto-propagated as SESSION env var (JSON) in the container
     task_arn = executor.run_task(
         'search-tax-by-town',
         envs={'TOWN': 'Norwalk', 'ONLY_TAX': 'true'}
@@ -479,11 +486,17 @@ The framework provides a `Repository` base class that eliminates repetitive boil
 | Property | Type | Default | Required |
 |----------|------|---------|----------|
 | `collection_name` | `str` | — | **Yes** |
-| `database_name` | `str` | `"core"` | No |
+| `database_key` | `str \| None` | `None` | No — if `None`, uses `session.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 `session.state` from 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
@@ -499,7 +512,7 @@ def indexes(self):
 
 Indexes are created automatically in the background on first collection access — no need to call any initialization method.
 
-### Repository on the main cluster (`database_name` defaults to `"core"`)
+### Repository with a fixed database
 
 ```python
 from aws_python_helper import Repository
@@ -510,6 +523,10 @@ class TownsRepository(Repository):
     def collection_name(self):
         return "towns"
 
+    @property
+    def database_key(self):
+        return "core"  # always connects to the "core" database
+
     @property
     def indexes(self):
         return [
@@ -527,21 +544,23 @@ class TownsRepository(Repository):
         return await self.collection.find_one({"name": name})
 ```
 
-### Repository on a different database (not `"core"`)
+### State-scoped repository (no `database_key`)
+
+When `database_key` is not set, the repository reads `session.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 database_name(self):
-        return "land_data"
-
     @property
     def collection_name(self):
         return "records"
 
+    # No database_key → uses session.state automatically
+    # If session.state = "connecticut" → connects to DB "connecticut"
+    # If session.state = "new_jersey"  → connects to DB "new_jersey"
+
     @property
     def indexes(self):
         return [
@@ -559,6 +578,8 @@ class LandRecordsRepository(Repository):
         return {"upserted": result.upserted_count, "modified": result.modified_count}
 ```
 
+> **Note:** A `ValueError` is raised at runtime if `database_key` is `None` and `session.state` has not been set. This is prevented automatically by the framework at every entry point (API, Lambda, SQS, Fargate).
+
 ### Repository on an external cluster
 
 ```python
@@ -567,7 +588,7 @@ from aws_python_helper import Repository
 class AddressRepository(Repository):
 
     @property
-    def database_name(self):
+    def database_key(self):
         return "smart_data"
 
     @property
@@ -607,6 +628,84 @@ class MyAPI(API):
 
 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.
 
+## 🌐 Session Context
+
+The framework propagates a `Session` object automatically across the entire async call chain using Python's `contextvars.ContextVar`. The session holds `state` (for multi-state DB routing) and `user` (authenticated user from the auth middleware).
+
+### How the framework injects it at each entry point
+
+| Entry point | How the session is read |
+|-------------|-------------------------|
+| **API Gateway** | `constitution-state` header → `session.state` (when `AUTHORIZATION` includes `state`); auth middleware → `session.user` (when includes `user`). Returns `400` if required header is missing |
+| **Standalone Lambda** | `session` dict in the event payload — **required** (must include `state`), raises `ValueError` if missing |
+| **SQS Consumer (single mode)** | Per-record: reads `session` from SNS `MessageAttributes` (JSON), falls back to legacy `body.constitution_state` |
+| **SQS Consumer (batch mode)** | Groups records by `session.state`; calls `process_batch()` once per group with the correct session in context |
+| **Fargate Task** | `SESSION` env var (JSON) — auto-injected by `FargateExecutor` |
+
+### How the framework propagates it to downstream services
+
+| Downstream service | Propagation mechanism |
+|--------------------|-----------------------|
+| **SNS Publisher** | Auto-injects the full session as a `session` `MessageAttribute` (JSON string) on every published message |
+| **FargateExecutor** | Auto-injects `SESSION` as a JSON env var when launching Fargate containers |
+
+This means that an API call with `constitution-state: connecticut` will automatically carry the full session (state + user) through SNS → SQS → Fargate without any code changes in your consumers or tasks.
+
+### Accessing the session in handlers
+
+All handler base classes expose a `self.session` property:
+
+```python
+class MyAPI(API):
+    async def process(self):
+        state = self.session.state   # e.g. "connecticut"
+        user  = self.session.user    # authenticated user dict, or None
+```
+
+Available in `API`, `SQSConsumer`, `Lambda`, and `FargateTask`.
+
+### State-scoped repositories
+
+Repositories with no `database_key` (default) read `session.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 session manually (e.g., in tests or utility code):
+
+```python
+from aws_python_helper import Session, get_session, set_session
+
+session = get_session()         # returns current Session (creates empty one if not set)
+session.state                   # e.g. "connecticut", or None if not set
+session.user                    # authenticated user dict, or None
+
+set_session(Session(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 — `session` in event
+
+```python
+import boto3, json
+
+lambda_client = boto3.client('lambda')
+lambda_client.invoke(
+    FunctionName='MyLambdaFunction',
+    InvocationType='RequestResponse',
+    Payload=json.dumps({
+        'session': {'state': 'connecticut'},  # Required
+        'data': {'key': 'value'}
+    })
+)
+```
+
 ## 🔄 Routing Convention
 
 The framework uses convention over configuration for the routing:
@@ -642,6 +741,7 @@ All properties and methods available inside an `API` subclass:
 | `self.query_parameters` | `dict` | Query string parameters |
 | `self.db` | `DatabaseProxy` | Access to main MongoDB cluster |
 | `self.external_db` | `ExternalDatabaseProxy` | Access to external MongoDB clusters |
+| `self.session` | `Session` | Request-scoped session (`session.state`, `session.user`) |
 | `self.current_user` | `dict \| None` | Authenticated user document (requires `REQUIRE_AUTH=true`) |
 | `self.is_authenticated` | `bool` | Whether the request is authenticated |
 | `self.auth_data` | `dict \| None` | Full authentication data |
@@ -690,14 +790,14 @@ The framework includes a built-in token-based authentication middleware.
 ### Configuration
 
 ```bash
-REQUIRE_AUTH=true            # Enable authentication (default: false)
+AUTHORIZATION=full           # Authorization mode: 'user', 'state', or 'full' (default: empty/disabled)
 AUTH_DB_NAME=my_database     # MongoDB database where tokens are stored
 AUTH_BYPASS_TOKEN=secret123  # Master token to bypass auth (for internal use)
 ```
 
 ### Using the authenticated user
 
-When `REQUIRE_AUTH=true`, every request must include a valid `Authorization: Bearer <token>` header. The authenticated user is available via `self.current_user`:
+When `AUTHORIZATION` is `user` or `full`, every request must include a valid `Authorization: Bearer <token>` header. The authenticated user is available via `self.current_user`:
 
 ```python
 class OrderListAPI(API):
@@ -998,6 +1098,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 |
@@ -1008,7 +1109,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
@@ -1057,10 +1162,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.31.0 → aws_python_helper-0.33.0}/aws_python_helper/__init__.py

@@ -27,6 +27,9 @@ from .utils.serializer import serialize_mongo_types
 # Repository
 from .repository.base import Repository
 
+# Context
+from .context.session import Session, get_session, set_session
+
 
 __all__ = [
     'API',
@@ -45,5 +48,8 @@ __all__ = [
     'MongoJSONEncoder',
     'mongo_json_dumps',
     'serialize_mongo_types',
+    'Session',
+    'get_session',
+    'set_session',
 ]
 

{aws_python_helper-0.31.0 → aws_python_helper-0.33.0}/aws_python_helper/api/base.py

@@ -9,6 +9,7 @@ from ..database.mongo_manager import MongoManager
 from ..database.database_proxy import DatabaseProxy
 from ..database.external_mongo_manager import ExternalMongoManager
 from ..database.external_database_proxy import ExternalDatabaseProxy
+from ..context.session import get_session
 
 
 class API(ABC):
@@ -136,17 +137,31 @@ class API(ABC):
             self._external_db = ExternalDatabaseProxy()
         return self._external_db
     
+    @property
+    def session(self):
+        """
+        Request-scoped session with state, user, and extensible properties.
+
+        Populated automatically by the dispatcher from the request headers
+        and authentication middleware.
+
+        Usage:
+            state = self.session.state          # constitution-state
+            user = self.session.user            # authenticated user dict
+        """
+        return get_session()
+
     @property
     def current_user(self) -> Optional[Dict[str, Any]]:
         """
         Current authenticated user or None if not authenticated
-        
+
         This property is populated by the authentication middleware
-        when REQUIRE_AUTH=true.
-        
+        when AUTHORIZATION is 'user' or 'full'.
+
         Returns:
             Dict with user data (email, role, name, etc.) or None
-        
+
         Example:
             if self.is_authenticated:
                 user_email = self.current_user['email']

{aws_python_helper-0.31.0 → aws_python_helper-0.33.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.session import get_session
 
 logger = logging.getLogger(__name__)
 
@@ -74,11 +75,35 @@ class Dispatcher:
             # 1. Prepare - Load controller and inject properties
             api = self._prepare()
             
-            # 2. Authenticate (if required)
-            require_auth = os.getenv('REQUIRE_AUTH', 'false').lower() == 'true'
-            if require_auth:
+            # 2. Authorization based on mode
+            authorization = os.getenv('AUTHORIZATION', '').lower()
+            requires_user = authorization in ('user', 'full')
+            requires_state = authorization in ('state', 'full')
+
+            # 2a. Authenticate (if mode requires user)
+            if requires_user:
                 await self._authenticate(api)
-            
+
+            # 2b. Validate state header (if mode requires state)
+            if requires_state:
+                state = self.headers.get('constitution-state')
+                if not state:
+                    return {
+                        'code': 400,
+                        'body': {
+                            'error': 'Bad Request',
+                            'message': "Header 'constitution-state' is required"
+                        },
+                        'headers': {}
+                    }
+                session = get_session()
+                session.state = state
+
+            # 2c. Inject user into session (if authenticated)
+            if api._current_user:
+                session = get_session()
+                session.user = api._current_user
+
             # 3. Validate
             await api.validate()
             

aws_python_helper-0.33.0/aws_python_helper/context/__init__.py

@@ -0,0 +1,3 @@
+from .session import Session, get_session, set_session
+
+__all__ = ['Session', 'get_session', 'set_session']