aws-python-helper 1.0.0__tar.gz → 1.0.3__tar.gz

{aws_python_helper-1.0.0 → aws_python_helper-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aws-python-helper
-Version: 1.0.0
+Version: 1.0.3
 Summary: AWS Python Helper Framework
 Author-email: Fabian Claros <neufabiae@gmail.com>
 License-Expression: MIT
@@ -39,6 +39,7 @@ Mini-framework to create REST APIs, SQS Consumers, SNS Publishers, Fargate Tasks
 - **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
+- **ModelIndexSyncLambda**: Base class for index-synchronization Lambdas — declare your `repositories` and the framework creates the declared indexes **and prunes orphans** across the `core` database and all active state databases, idempotently and in parallel, in a single run (run once per deploy)
 - **JSON utilities**: Automatic serialization of MongoDB types
 - **Type hints**: Modern Python with type annotations
 - **Async/await**: Full support for asynchronous operations
@@ -67,6 +68,7 @@ All available classes and functions:
 | `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 |
+| `ModelIndexSyncLambda` | `aws_python_helper` | Index-sync Lambda base class (creates declared indexes + prunes orphans across `core` + all state DBs, in parallel) |
 | `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 |
@@ -77,6 +79,8 @@ All available classes and functions:
 | `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 |
+| `StateValidator` | `aws_python_helper` | Validates a state against `core.states` (cached, active states only) |
+| `InvalidStateError` | `aws_python_helper` | Raised when a state is not found or not active |
 | `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 |
@@ -250,6 +254,15 @@ class GenerateRouteLambda(Lambda):
         }
 ```
 
+> **`requires_state` (session requirement)** — By default (`requires_state = True`) the framework requires the event to carry a `session` with a valid `state` and validates it against `core.states` before running. Override `requires_state` to return `False` for Lambdas that operate across **all** states and must not be tied to a single one (e.g. index synchronization) — the `session`/`state` then becomes optional. See [ModelIndexSyncLambda](#-modelindexsynclambda).
+>
+> ```python
+> class SyncAllStatesLambda(Lambda):
+>     @property
+>     def requires_state(self) -> bool:
+>         return False  # no session.state required; runs across every state
+> ```
+
 **2. Configure the handler** in `src/handlers/lambda_handler.py`:
 
 ```python
@@ -511,7 +524,9 @@ class AddressAPI(API):
 
 ## 🗂️ 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.
+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 it needs. The base class handles the MongoDB connection automatically.
+
+> **Index creation is not triggered at request time.** Declaring `indexes` only *describes* the indexes; it does not create them on collection access (this avoids per-request overhead and half-finished index builds in short-lived Lambda/API runtimes). Indexes are created by the [`ModelIndexSyncLambda`](#-modelindexsynclambda) — run once per deploy — or by calling `await repo.ensure_indexes()` explicitly.
 
 ### Properties to override
 
@@ -542,7 +557,15 @@ def indexes(self):
     ]
 ```
 
-Indexes are created automatically in the background on first collection access — no need to call any initialization method.
+These definitions are consumed by `ensure_indexes()`, which the [`ModelIndexSyncLambda`](#-modelindexsynclambda) runs across the relevant databases at deploy time. `ensure_indexes()` is idempotent (safe to re-run) and accepts an explicit `database_name` so the same state-scoped repository can be materialized in every state database:
+
+```python
+# Create this repository's indexes in a specific database (what the index-sync Lambda does):
+await repo.ensure_indexes(database_name="connecticut")
+
+# Or, with no argument, in the repository's resolved database (database_key or session.state):
+await repo.ensure_indexes()
+```
 
 ### Repository with a fixed database
 
@@ -669,7 +692,7 @@ The framework propagates a `Session` object automatically across the entire asyn
 | 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 |
+| **Standalone Lambda** | `session` dict in the event payload — **required by default** (must include `state`), raises `ValueError` if missing. A Lambda can opt out via `requires_state = False` (e.g. `ModelIndexSyncLambda`), making the session optional |
 | **SQS Consumer (single mode)** | Per-record: reads `session` from SNS `MessageAttributes` (Base64-encoded JSON) |
 | **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` |
@@ -1179,13 +1202,15 @@ Create `src/lambda/model-query/main.py` in the microservice that owns the data:
 ```python
 from aws_python_helper import ModelQueryLambda
 
-class ModelQueryLambda(ModelQueryLambda):
+class OrdersModelQueryLambda(ModelQueryLambda):
 
     @property
     def allowed_collections(self) -> list:
         return ["orders", "customers"]  # whitelist — unlisted collections are rejected
 ```
 
+> **Class discovery:** name your subclass distinctly from the imported base (e.g. `OrdersModelQueryLambda`, not `ModelQueryLambda`). The framework loads the class **defined in the file** — not the imported base — so subclassing an imported concrete base (`ModelQueryLambda`, `ModelIndexSyncLambda`) works without name collisions.
+
 Register the handler in `src/handlers/lambda_handler.py`:
 
 ```python
@@ -1333,6 +1358,132 @@ Always pass `self.session.to_dict()` when calling from an API or Lambda to ensur
 
 ---
 
+## 🧱 ModelIndexSyncLambda
+
+`ModelIndexSyncLambda` is a ready-to-use base class for **synchronizing all of a service's MongoDB indexes deterministically**, in one run. Because index creation is no longer triggered at request time (see the [Repository Pattern](#️-repository-pattern) note), this Lambda is the single source of truth for materializing indexes — typically invoked **once per deploy**.
+
+**Why:** in short-lived Lambda/API runtimes, creating indexes lazily on first access often never finishes (the function responds and freezes). This Lambda creates every declared index up front, `await`-ing each one, idempotently — and across **every** active state database, not just the one of the current request.
+
+It does a **two-way sync** per collection: it creates the declared indexes **and prunes orphans** — any index present in MongoDB that is no longer declared in the repository's `indexes` is dropped (the default `_id_` index and special text/geo/hashed indexes are always preserved).
+
+> ⚠️ **Orphan pruning drops indexes not declared in code.** Indexes created out-of-band (by a DBA, Atlas, or another tool) that aren't in any repository's `indexes` will be removed on every run. Declare every index you want to keep.
+
+**Concurrency & fault tolerance:** each `(collection, database)` unit is synced **in parallel** (bounded by `max_concurrency`, default 10); index work *within* a unit stays sequential. A failure in one unit is **captured and isolated** — it never aborts the others, so a single broken collection doesn't stop the rest of the sync. The top-level response is always `success: true`; per-unit outcomes are reported in `results[].success`.
+
+### Creating an index-sync Lambda
+
+Create `src/lambda/model-index-sync/main.py` and declare which repositories to sync:
+
+```python
+import aws_python_helper
+
+from repositories.parcels import ParcelsRepository   # state-scoped (database_key = None)
+from repositories.users import UsersRepository       # core (database_key = "core")
+from repositories.tokens import TokensRepository     # core
+
+class OrdersModelIndexSyncLambda(aws_python_helper.ModelIndexSyncLambda):
+
+    @property
+    def repositories(self) -> list:
+        return [ParcelsRepository, UsersRepository, TokensRepository]
+```
+
+Register the handler in `src/handlers/lambda_handler.py`:
+
+```python
+from aws_python_helper.lambda_standalone.handler import lambda_handler
+
+index_sync_handler = lambda_handler('model-index-sync')
+
+__all__ = ["index_sync_handler"]
+```
+
+> Declare repositories **explicitly** (don't auto-discover) so the synced set is intentional. List your own collections; **external** repositories (`is_external = True`) belong to another cluster/service and are typically excluded.
+
+### How it routes each repository
+
+For every repository in the list, the Lambda decides where to create its indexes:
+
+| Repository kind | `database_key` | Target databases |
+|-----------------|----------------|------------------|
+| **Core / fixed** | `"core"` (or any string) | that single database |
+| **State-scoped** | `None` | **every active state**, read from `core.states` where `is_active = true` (e.g. `connecticut`, `new_jersey`, …) |
+
+A state-scoped collection such as `parcels` therefore gets its indexes created in `connecticut`, `new_jersey`, and any other active state — automatically. Creation is idempotent, so re-running it is safe.
+
+This Lambda sets `requires_state = False`: it is not tied to a single state and does not require a `session` in the event.
+
+### Response format
+
+The top-level `success` is **always `true`** (a failing collection no longer aborts the run). Inspect `data.summary` for the OK/failed counts and `data.results[].success` for each unit; failed units include an `error` field.
+
+```json
+{
+  "success": true,
+  "data": {
+    "summary": { "total": 4, "succeeded": 3, "failed": 1 },
+    "results": [
+      {"repository": "ParcelsRepository", "database": "connecticut", "collection": "parcels", "indexes": ["parcel_id_1", "..."], "orphan_indexes_dropped": ["old_field_1"], "success": true},
+      {"repository": "ParcelsRepository", "database": "new_jersey",  "collection": "parcels", "indexes": ["parcel_id_1", "..."], "orphan_indexes_dropped": [], "success": true},
+      {"repository": "UsersRepository",   "database": "core",        "collection": "users",   "indexes": ["email_1"], "orphan_indexes_dropped": [], "success": true},
+      {"repository": "TokensRepository",  "database": "core",        "collection": "tokens",  "indexes": [], "orphan_indexes_dropped": [], "success": false, "error": "..."}
+    ]
+  }
+}
+```
+
+### Properties to override / configure
+
+| Property | Default | Purpose |
+|----------|---------|---------|
+| `repositories` | `[]` | **Required.** List of `Repository` subclasses (the classes, not instances) to sync. Empty raises a validation error |
+| `states_database` | `"core"` | Database holding the states collection |
+| `states_collection` | `"states"` | Collection listing the states (filtered by `is_active = true`, field `name`) |
+| `max_concurrency` | `10` | Max `(collection, database)` units synced in parallel. `0` (or negative) = unlimited |
+| `requires_state` | `False` | Inherited override — the Lambda runs across all states, no session required |
+
+### Running it once per deploy (Terraform)
+
+Since deploys are applied manually with Terraform, attach an `aws_lambda_invocation` that runs **on every `apply`**, right after the function code is updated. `timestamp()` changes on every plan, so it always re-runs (creation is idempotent and also picks up any newly-activated state).
+
+> **Detecting failures in the deploy.** The top-level `success` is now **always `true`** — a single failed collection no longer aborts the run, so checking `success` alone won't catch partial failures. If you want the `apply` to fail when any collection failed, point the `postcondition` at `data.summary.failed` instead (shown below). If you'd rather the deploy never fail on index errors and only review them afterward (in the response/logs), simply omit the `lifecycle` block.
+
+```hcl
+module "lambda" {
+  source         = "../../../../../modules/lambda"
+  function_name  = "${...service_name}${var.lambda_name}-${...env}"
+  source_handler = "handlers.lambda_handler.index_sync_handler"
+  timeout        = 300
+  memory_size    = 512
+  # ... mongo + vpc config (same as any other Lambda)
+}
+
+resource "aws_lambda_invocation" "sync_on_deploy" {
+  function_name = module.lambda.lambda_function_name
+  input         = jsonencode({ _invoked_at = timestamp() })  # always changes → always re-runs
+
+  depends_on = [module.lambda]                                # run after the code is updated
+
+  # Optional: fail the apply if any collection failed to sync.
+  # Omit this whole lifecycle block if you prefer the deploy to never fail on
+  # index errors (review data.results[].success / logs instead).
+  lifecycle {
+    postcondition {
+      condition     = try(jsondecode(self.result).data.summary.failed, 1) == 0
+      error_message = "Index sync had failures during apply: ${self.result}"
+    }
+  }
+}
+```
+
+You can also invoke it manually at any time (e.g. after activating a new state without a code deploy):
+
+```bash
+aws lambda invoke --function-name MyServiceModelIndexSync-dev out.json
+```
+
+---
+
 ## 🏗️ Architecture Overview
 
 Typical flow for event-driven architectures using this framework:

{aws_python_helper-1.0.0 → aws_python_helper-1.0.3}/README.md

@@ -19,6 +19,7 @@ Mini-framework to create REST APIs, SQS Consumers, SNS Publishers, Fargate Tasks
 - **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
+- **ModelIndexSyncLambda**: Base class for index-synchronization Lambdas — declare your `repositories` and the framework creates the declared indexes **and prunes orphans** across the `core` database and all active state databases, idempotently and in parallel, in a single run (run once per deploy)
 - **JSON utilities**: Automatic serialization of MongoDB types
 - **Type hints**: Modern Python with type annotations
 - **Async/await**: Full support for asynchronous operations
@@ -47,6 +48,7 @@ All available classes and functions:
 | `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 |
+| `ModelIndexSyncLambda` | `aws_python_helper` | Index-sync Lambda base class (creates declared indexes + prunes orphans across `core` + all state DBs, in parallel) |
 | `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 |
@@ -57,6 +59,8 @@ All available classes and functions:
 | `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 |
+| `StateValidator` | `aws_python_helper` | Validates a state against `core.states` (cached, active states only) |
+| `InvalidStateError` | `aws_python_helper` | Raised when a state is not found or not active |
 | `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 |
@@ -230,6 +234,15 @@ class GenerateRouteLambda(Lambda):
         }
 ```
 
+> **`requires_state` (session requirement)** — By default (`requires_state = True`) the framework requires the event to carry a `session` with a valid `state` and validates it against `core.states` before running. Override `requires_state` to return `False` for Lambdas that operate across **all** states and must not be tied to a single one (e.g. index synchronization) — the `session`/`state` then becomes optional. See [ModelIndexSyncLambda](#-modelindexsynclambda).
+>
+> ```python
+> class SyncAllStatesLambda(Lambda):
+>     @property
+>     def requires_state(self) -> bool:
+>         return False  # no session.state required; runs across every state
+> ```
+
 **2. Configure the handler** in `src/handlers/lambda_handler.py`:
 
 ```python
@@ -491,7 +504,9 @@ class AddressAPI(API):
 
 ## 🗂️ 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.
+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 it needs. The base class handles the MongoDB connection automatically.
+
+> **Index creation is not triggered at request time.** Declaring `indexes` only *describes* the indexes; it does not create them on collection access (this avoids per-request overhead and half-finished index builds in short-lived Lambda/API runtimes). Indexes are created by the [`ModelIndexSyncLambda`](#-modelindexsynclambda) — run once per deploy — or by calling `await repo.ensure_indexes()` explicitly.
 
 ### Properties to override
 
@@ -522,7 +537,15 @@ def indexes(self):
     ]
 ```
 
-Indexes are created automatically in the background on first collection access — no need to call any initialization method.
+These definitions are consumed by `ensure_indexes()`, which the [`ModelIndexSyncLambda`](#-modelindexsynclambda) runs across the relevant databases at deploy time. `ensure_indexes()` is idempotent (safe to re-run) and accepts an explicit `database_name` so the same state-scoped repository can be materialized in every state database:
+
+```python
+# Create this repository's indexes in a specific database (what the index-sync Lambda does):
+await repo.ensure_indexes(database_name="connecticut")
+
+# Or, with no argument, in the repository's resolved database (database_key or session.state):
+await repo.ensure_indexes()
+```
 
 ### Repository with a fixed database
 
@@ -649,7 +672,7 @@ The framework propagates a `Session` object automatically across the entire asyn
 | 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 |
+| **Standalone Lambda** | `session` dict in the event payload — **required by default** (must include `state`), raises `ValueError` if missing. A Lambda can opt out via `requires_state = False` (e.g. `ModelIndexSyncLambda`), making the session optional |
 | **SQS Consumer (single mode)** | Per-record: reads `session` from SNS `MessageAttributes` (Base64-encoded JSON) |
 | **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` |
@@ -1159,13 +1182,15 @@ Create `src/lambda/model-query/main.py` in the microservice that owns the data:
 ```python
 from aws_python_helper import ModelQueryLambda
 
-class ModelQueryLambda(ModelQueryLambda):
+class OrdersModelQueryLambda(ModelQueryLambda):
 
     @property
     def allowed_collections(self) -> list:
         return ["orders", "customers"]  # whitelist — unlisted collections are rejected
 ```
 
+> **Class discovery:** name your subclass distinctly from the imported base (e.g. `OrdersModelQueryLambda`, not `ModelQueryLambda`). The framework loads the class **defined in the file** — not the imported base — so subclassing an imported concrete base (`ModelQueryLambda`, `ModelIndexSyncLambda`) works without name collisions.
+
 Register the handler in `src/handlers/lambda_handler.py`:
 
 ```python
@@ -1313,6 +1338,132 @@ Always pass `self.session.to_dict()` when calling from an API or Lambda to ensur
 
 ---
 
+## 🧱 ModelIndexSyncLambda
+
+`ModelIndexSyncLambda` is a ready-to-use base class for **synchronizing all of a service's MongoDB indexes deterministically**, in one run. Because index creation is no longer triggered at request time (see the [Repository Pattern](#️-repository-pattern) note), this Lambda is the single source of truth for materializing indexes — typically invoked **once per deploy**.
+
+**Why:** in short-lived Lambda/API runtimes, creating indexes lazily on first access often never finishes (the function responds and freezes). This Lambda creates every declared index up front, `await`-ing each one, idempotently — and across **every** active state database, not just the one of the current request.
+
+It does a **two-way sync** per collection: it creates the declared indexes **and prunes orphans** — any index present in MongoDB that is no longer declared in the repository's `indexes` is dropped (the default `_id_` index and special text/geo/hashed indexes are always preserved).
+
+> ⚠️ **Orphan pruning drops indexes not declared in code.** Indexes created out-of-band (by a DBA, Atlas, or another tool) that aren't in any repository's `indexes` will be removed on every run. Declare every index you want to keep.
+
+**Concurrency & fault tolerance:** each `(collection, database)` unit is synced **in parallel** (bounded by `max_concurrency`, default 10); index work *within* a unit stays sequential. A failure in one unit is **captured and isolated** — it never aborts the others, so a single broken collection doesn't stop the rest of the sync. The top-level response is always `success: true`; per-unit outcomes are reported in `results[].success`.
+
+### Creating an index-sync Lambda
+
+Create `src/lambda/model-index-sync/main.py` and declare which repositories to sync:
+
+```python
+import aws_python_helper
+
+from repositories.parcels import ParcelsRepository   # state-scoped (database_key = None)
+from repositories.users import UsersRepository       # core (database_key = "core")
+from repositories.tokens import TokensRepository     # core
+
+class OrdersModelIndexSyncLambda(aws_python_helper.ModelIndexSyncLambda):
+
+    @property
+    def repositories(self) -> list:
+        return [ParcelsRepository, UsersRepository, TokensRepository]
+```
+
+Register the handler in `src/handlers/lambda_handler.py`:
+
+```python
+from aws_python_helper.lambda_standalone.handler import lambda_handler
+
+index_sync_handler = lambda_handler('model-index-sync')
+
+__all__ = ["index_sync_handler"]
+```
+
+> Declare repositories **explicitly** (don't auto-discover) so the synced set is intentional. List your own collections; **external** repositories (`is_external = True`) belong to another cluster/service and are typically excluded.
+
+### How it routes each repository
+
+For every repository in the list, the Lambda decides where to create its indexes:
+
+| Repository kind | `database_key` | Target databases |
+|-----------------|----------------|------------------|
+| **Core / fixed** | `"core"` (or any string) | that single database |
+| **State-scoped** | `None` | **every active state**, read from `core.states` where `is_active = true` (e.g. `connecticut`, `new_jersey`, …) |
+
+A state-scoped collection such as `parcels` therefore gets its indexes created in `connecticut`, `new_jersey`, and any other active state — automatically. Creation is idempotent, so re-running it is safe.
+
+This Lambda sets `requires_state = False`: it is not tied to a single state and does not require a `session` in the event.
+
+### Response format
+
+The top-level `success` is **always `true`** (a failing collection no longer aborts the run). Inspect `data.summary` for the OK/failed counts and `data.results[].success` for each unit; failed units include an `error` field.
+
+```json
+{
+  "success": true,
+  "data": {
+    "summary": { "total": 4, "succeeded": 3, "failed": 1 },
+    "results": [
+      {"repository": "ParcelsRepository", "database": "connecticut", "collection": "parcels", "indexes": ["parcel_id_1", "..."], "orphan_indexes_dropped": ["old_field_1"], "success": true},
+      {"repository": "ParcelsRepository", "database": "new_jersey",  "collection": "parcels", "indexes": ["parcel_id_1", "..."], "orphan_indexes_dropped": [], "success": true},
+      {"repository": "UsersRepository",   "database": "core",        "collection": "users",   "indexes": ["email_1"], "orphan_indexes_dropped": [], "success": true},
+      {"repository": "TokensRepository",  "database": "core",        "collection": "tokens",  "indexes": [], "orphan_indexes_dropped": [], "success": false, "error": "..."}
+    ]
+  }
+}
+```
+
+### Properties to override / configure
+
+| Property | Default | Purpose |
+|----------|---------|---------|
+| `repositories` | `[]` | **Required.** List of `Repository` subclasses (the classes, not instances) to sync. Empty raises a validation error |
+| `states_database` | `"core"` | Database holding the states collection |
+| `states_collection` | `"states"` | Collection listing the states (filtered by `is_active = true`, field `name`) |
+| `max_concurrency` | `10` | Max `(collection, database)` units synced in parallel. `0` (or negative) = unlimited |
+| `requires_state` | `False` | Inherited override — the Lambda runs across all states, no session required |
+
+### Running it once per deploy (Terraform)
+
+Since deploys are applied manually with Terraform, attach an `aws_lambda_invocation` that runs **on every `apply`**, right after the function code is updated. `timestamp()` changes on every plan, so it always re-runs (creation is idempotent and also picks up any newly-activated state).
+
+> **Detecting failures in the deploy.** The top-level `success` is now **always `true`** — a single failed collection no longer aborts the run, so checking `success` alone won't catch partial failures. If you want the `apply` to fail when any collection failed, point the `postcondition` at `data.summary.failed` instead (shown below). If you'd rather the deploy never fail on index errors and only review them afterward (in the response/logs), simply omit the `lifecycle` block.
+
+```hcl
+module "lambda" {
+  source         = "../../../../../modules/lambda"
+  function_name  = "${...service_name}${var.lambda_name}-${...env}"
+  source_handler = "handlers.lambda_handler.index_sync_handler"
+  timeout        = 300
+  memory_size    = 512
+  # ... mongo + vpc config (same as any other Lambda)
+}
+
+resource "aws_lambda_invocation" "sync_on_deploy" {
+  function_name = module.lambda.lambda_function_name
+  input         = jsonencode({ _invoked_at = timestamp() })  # always changes → always re-runs
+
+  depends_on = [module.lambda]                                # run after the code is updated
+
+  # Optional: fail the apply if any collection failed to sync.
+  # Omit this whole lifecycle block if you prefer the deploy to never fail on
+  # index errors (review data.results[].success / logs instead).
+  lifecycle {
+    postcondition {
+      condition     = try(jsondecode(self.result).data.summary.failed, 1) == 0
+      error_message = "Index sync had failures during apply: ${self.result}"
+    }
+  }
+}
+```
+
+You can also invoke it manually at any time (e.g. after activating a new state without a code deploy):
+
+```bash
+aws lambda invoke --function-name MyServiceModelIndexSync-dev out.json
+```
+
+---
+
 ## 🏗️ Architecture Overview
 
 Typical flow for event-driven architectures using this framework:

{aws_python_helper-1.0.0 → aws_python_helper-1.0.3}/aws_python_helper/__init__.py

@@ -2,7 +2,7 @@
 AWS Python Framework
 """
 
-__version__ = "0.1.0"
+__version__ = "1.0.2"
 
 # All classes
 from .api.base import API
@@ -34,6 +34,9 @@ from .context.state_validator import StateValidator, InvalidStateError
 # Model Query
 from .model_query import ModelQueryLambda
 
+# Model Index Sync
+from .model_index_sync import ModelIndexSyncLambda
+
 # Invoker
 from .invoker import (
     LambdaInvoker,
@@ -69,6 +72,7 @@ __all__ = [
     'StateValidator',
     'InvalidStateError',
     'ModelQueryLambda',
+    'ModelIndexSyncLambda',
     'LambdaInvoker',
     'ApiClient',
     'LambdaInvocationError',

{aws_python_helper-1.0.0 → aws_python_helper-1.0.3}/aws_python_helper/api/fetcher.py

@@ -190,9 +190,10 @@ class Fetcher:
         controller_class = None
         for item_name in dir(module):
             item = getattr(module, item_name)
-            if (isinstance(item, type) and 
-                hasattr(item, 'process') and 
-                item.__name__ not in ['API', 'ABC']):
+            if (isinstance(item, type) and
+                hasattr(item, 'process') and
+                item.__name__ not in ['API', 'ABC'] and
+                item.__module__ == module.__name__):
                 controller_class = item
                 break
         

{aws_python_helper-1.0.0 → aws_python_helper-1.0.3}/aws_python_helper/fargate/fetcher.py

@@ -98,9 +98,10 @@ class FargateTaskFetcher:
         task_class = None
         for item_name in dir(module):
             item = getattr(module, item_name)
-            if (isinstance(item, type) and 
-                hasattr(item, 'execute') and 
-                item.__name__ not in ['FargateTask', 'ABC']):
+            if (isinstance(item, type) and
+                hasattr(item, 'execute') and
+                item.__name__ not in ['FargateTask', 'ABC'] and
+                item.__module__ == module.__name__):
                 task_class = item
                 break
         

{aws_python_helper-1.0.0 → aws_python_helper-1.0.3}/aws_python_helper/lambda_standalone/base.py

@@ -47,6 +47,21 @@ class Lambda(ABC):
         """
         return get_session()
 
+    @property
+    def requires_state(self) -> bool:
+        """
+        Whether this Lambda requires a valid 'state' in the session.
+
+        Default True: run() enforces that the event carries session.state and
+        validates it against core.states before processing.
+
+        Override to return False for Lambdas that operate across all states and
+        must not be tied to a single one (e.g. index synchronization). When
+        False, a session is still set if provided, but state is not required
+        nor validated.
+        """
+        return True
+
     @property
     def schema(self):
         """
@@ -188,11 +203,15 @@ class Lambda(ABC):
         try:
             # Step 0: Setup session context
             session_data = self.event.get('session')
-            if not session_data or not session_data.get('state'):
-                raise ValueError("'session' with 'state' is required in the event")
-            session = Session.from_dict(session_data)
-            await StateValidator.validate(session.state)
-            set_session(session)
+            if self.requires_state:
+                if not session_data or not session_data.get('state'):
+                    raise ValueError("'session' with 'state' is required in the event")
+                session = Session.from_dict(session_data)
+                await StateValidator.validate(session.state)
+                set_session(session)
+            elif session_data:
+                # state not required, but honor a session if one was provided
+                set_session(Session.from_dict(session_data))
 
             # Step 1: Schema validation (automatic, if schema property is defined)
             if self.schema is not None:

{aws_python_helper-1.0.0 → aws_python_helper-1.0.3}/aws_python_helper/lambda_standalone/fetcher.py

@@ -100,9 +100,10 @@ class LambdaFetcher:
         lambda_class = None
         for item_name in dir(module):
             item = getattr(module, item_name)
-            if (isinstance(item, type) and 
-                issubclass(item, Lambda) and 
-                item.__name__ not in ['Lambda', 'ABC']):
+            if (isinstance(item, type) and
+                issubclass(item, Lambda) and
+                item.__name__ not in ['Lambda', 'ABC'] and
+                item.__module__ == module.__name__):
                 lambda_class = item
                 break
         

aws_python_helper-1.0.3/aws_python_helper/model_index_sync/__init__.py

@@ -0,0 +1,3 @@
+from .base import ModelIndexSyncLambda
+
+__all__ = ["ModelIndexSyncLambda"]