django-lambda-tasks 0.1.5__tar.gz → 0.2.0__tar.gz

django_lambda_tasks-0.2.0/.kiro/specs/ssm-environment-loader/.config.kiro

@@ -0,0 +1 @@
+{"specId": "293fc556-56fb-43f9-971a-68228fd351a8", "workflowType": "requirements-first", "specType": "feature"}

django_lambda_tasks-0.2.0/.kiro/specs/ssm-environment-loader/design.md

@@ -0,0 +1,225 @@
+# Design Document: SSM Environment Loader
+
+## Overview
+
+This feature adds a new module `ssm_environment_loader.py` to the `lambda_tasks` package that reads an AWS SSM Parameter Store parameter at Lambda cold start and sets its JSON content as environment variables. It follows the same pattern as the existing `secret_loader.py` — a module-level cached function called before `django.setup()` in `handler.py`.
+
+The module exposes a single public function `resolve_ssm_environment()` that:
+1. Checks for the `LAMBDA_TASKS_SSM_ENVIRONMENT` env var
+2. If present, fetches the named SSM parameter via boto3
+3. Parses the parameter value as a flat JSON object (`dict[str, str]`)
+4. Sets each key-value pair in `os.environ`
+5. Caches the result so subsequent calls are no-ops
+
+This runs **before** `resolve_secrets_into_env()` in the cold-start sequence, allowing SSM-loaded env vars to be referenced by the secret loader.
+
+## Architecture
+
+```mermaid
+sequenceDiagram
+    participant Lambda as Lambda Container
+    participant SSM as ssm_environment_loader
+    participant Secret as secret_loader
+    participant Django as django.setup()
+
+    Lambda->>SSM: resolve_ssm_environment()
+    alt LAMBDA_TASKS_SSM_ENVIRONMENT is set
+        SSM->>SSM: Check module-level cache
+        alt Not cached
+            SSM->>AWS: ssm.get_parameter(Name=param_name, WithDecryption=True)
+            AWS-->>SSM: Parameter value (JSON string)
+            SSM->>SSM: Validate JSON (flat str→str object)
+            SSM->>SSM: Set os.environ for each key-value pair
+            SSM->>SSM: Store in module-level cache
+        end
+    end
+    Lambda->>Secret: resolve_secrets_into_env()
+    Lambda->>Lambda: Check DJANGO_SETTINGS_MODULE
+    alt DJANGO_SETTINGS_MODULE is set and apps not ready
+        Lambda->>Django: django.setup()
+    end
+```
+
+Both loaders run **unconditionally** before the `DJANGO_SETTINGS_MODULE` check — they are both idempotent and cached. The SSM parameter may provide `DJANGO_SETTINGS_MODULE` itself, and secrets may reference SSM-loaded vars.
+
+## Components and Interfaces
+
+### Module: `lambda_tasks/ssm_environment_loader.py`
+
+**Public API:**
+
+```python
+def resolve_ssm_environment() -> None:
+    """Load SSM parameter content into os.environ.
+
+    Reads the parameter named by LAMBDA_TASKS_SSM_ENVIRONMENT,
+    parses it as a flat JSON object, and sets each key-value pair
+    as an environment variable. Idempotent — cached after first call.
+
+    Raises:
+        ValueError: If the parameter content is not valid JSON,
+                    not a flat string→string mapping, or contains
+                    an empty string key.
+    """
+```
+
+**Internal helpers (keyword-only args, fully typed):**
+
+```python
+def _fetch_parameter(*, parameter_name: str) -> str:
+    """Fetch a single SSM parameter value using boto3."""
+
+def _validate_and_parse(*, raw_value: str, parameter_name: str) -> dict[str, str]:
+    """Parse JSON and validate it is a flat str→str mapping.
+
+    Raises ValueError with descriptive messages on failure.
+    """
+```
+
+**Module-level state:**
+
+```python
+_cache: dict[str, str] | None = None  # None = not yet loaded; dict = loaded content
+_loaded: bool = False  # Sentinel to distinguish "loaded empty" from "not loaded"
+```
+
+### Integration point: `lambda_tasks/handler.py`
+
+The cold-start block changes from:
+
+```python
+if os.environ.get("DJANGO_SETTINGS_MODULE") and not apps.ready:
+    resolve_secrets_into_env()
+    django.setup()
+```
+
+To:
+
+```python
+from lambda_tasks.ssm_environment_loader import resolve_ssm_environment
+
+# Both loaders are idempotent and run unconditionally before the
+# DJANGO_SETTINGS_MODULE check — SSM may provide that var, and
+# secrets may depend on SSM-loaded vars.
+resolve_ssm_environment()
+resolve_secrets_into_env()
+
+if os.environ.get("DJANGO_SETTINGS_MODULE") and not apps.ready:
+    django.setup()
+```
+
+## Data Models
+
+### SSM Parameter Content Format
+
+The SSM parameter value must be a JSON object where all keys and values are strings:
+
+```json
+{
+  "DATABASE_URL": "postgres://user:pass@host:5432/db",
+  "REDIS_URL": "redis://host:6379/0",
+  "DJANGO_SECRET_KEY": "some-secret-key"
+}
+```
+
+**Validation rules:**
+1. Must be valid JSON (parseable by `json.loads`)
+2. Must be a JSON object (top-level `dict`)
+3. All values must be strings (no nested objects, arrays, numbers, booleans, or null)
+4. No empty string keys
+
+### Module-level Cache
+
+```python
+_loaded: bool = False
+```
+
+A simple boolean sentinel. Once `resolve_ssm_environment()` completes successfully, `_loaded` is set to `True`. Subsequent calls check this flag and return immediately. This is simpler than caching the parsed dict since we only need to know "did we already run?"
+
+## Correctness Properties
+
+*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
+
+### Property 1: Parameter content round-trip into environment
+
+*For any* valid flat JSON object (where all keys are non-empty strings and all values are strings), when the SSM parameter returns that JSON, calling `resolve_ssm_environment()` SHALL result in every key-value pair from the JSON being present in `os.environ` with the correct value.
+
+**Validates: Requirements 1.3**
+
+### Property 2: Invalid JSON rejection
+
+*For any* string that is not valid JSON, when the SSM parameter returns that string, calling `resolve_ssm_environment()` SHALL raise a `ValueError` whose message contains the parameter name.
+
+**Validates: Requirements 2.1**
+
+### Property 3: Non-flat JSON rejection with key identification
+
+*For any* valid JSON object containing at least one non-string value (int, float, list, dict, bool, or null), calling `resolve_ssm_environment()` SHALL raise a `ValueError` whose message contains the names of all offending keys.
+
+**Validates: Requirements 2.2**
+
+### Property 4: Idempotent execution
+
+*For any* valid SSM parameter content, calling `resolve_ssm_environment()` N times (where N ≥ 1) SHALL result in exactly one SSM API call, with all subsequent calls returning immediately without contacting AWS.
+
+**Validates: Requirements 3.1, 3.2**
+
+## Error Handling
+
+| Condition | Behaviour | Rationale |
+|---|---|---|
+| `LAMBDA_TASKS_SSM_ENVIRONMENT` not set | Return immediately, no API call | Opt-in behaviour; no-op when not configured |
+| SSM parameter not found (boto3 `ParameterNotFound`) | Let exception propagate | Fail fast at cold start; misconfiguration should crash the container |
+| SSM API error (network, permissions) | Let exception propagate | Fail fast; boto3 exceptions propagate per project convention |
+| Parameter value is not valid JSON | Raise `ValueError` with parameter name | Fail fast with actionable error message |
+| JSON is not a flat object | Raise `ValueError` listing offending keys | Fail fast; identify exactly what's wrong |
+| JSON contains empty string key | Raise `ValueError` | Empty env var names are invalid on all platforms |
+
+**Design decision:** SSM keys override existing env vars without conflict detection. This differs from `secret_loader.py` which raises on conflicts. The rationale is that SSM parameters represent the canonical environment configuration — they are expected to override deployment-time defaults. This keeps the mental model simple: "SSM wins."
+
+## Testing Strategy
+
+### Property-Based Tests (Hypothesis)
+
+The project already uses Hypothesis (`.hypothesis/` directory exists, `hypothesis` in dev dependencies). Each correctness property maps to a Hypothesis test with minimum 100 iterations.
+
+| Property | Generator Strategy | Assertion |
+|---|---|---|
+| 1: Content round-trip | `st.dictionaries(keys=st.text(min_size=1, ...), values=st.text())` | All pairs present in `os.environ` |
+| 2: Invalid JSON rejection | `st.text().filter(lambda s: not is_valid_json(s))` | `ValueError` raised, parameter name in message |
+| 3: Non-flat JSON rejection | `st.dictionaries(...)` with at least one non-string value | `ValueError` raised, offending keys in message |
+| 4: Idempotent execution | Valid content + `st.integers(min_value=2, max_value=10)` for call count | API called exactly once |
+
+**Property test configuration:**
+- Library: `hypothesis` (already installed)
+- Minimum iterations: 100 (Hypothesis default is higher, which is fine)
+- Tag format: `# Feature: ssm-environment-loader, Property {N}: {title}`
+
+### Unit Tests (Example-Based)
+
+| Scenario | Type |
+|---|---|
+| Env var not set → no-op, no boto3 client created | Example (Req 1.2) |
+| Empty string key in JSON → ValueError | Edge case (Req 2.3) |
+| Handler cold-start ordering (SSM → secrets → Django) | Integration (Req 1.4, 1.5) |
+| Module importable from `lambda_tasks.ssm_environment_loader` | Smoke (Req 4.2) |
+| `resolve_ssm_environment` callable with no args | Smoke (Req 4.1) |
+| SSM parameter override of existing env var | Example (confirms override behaviour) |
+
+### Test File
+
+Tests live in `tests/test_ssm_environment_loader.py` following the project convention of one test file per source module.
+
+### Mocking Strategy
+
+- boto3 SSM client is mocked at the module level (same pattern as `test_secret_loader.py`)
+- `os.environ` manipulation via `monkeypatch` (pytest fixture)
+- Module-level cache (`_loaded`) reset via autouse fixture between tests
+- No real AWS calls in any test
+
+### TDD Approach
+
+Following the project's TDD convention:
+1. Write a failing test for each property/example
+2. Implement the minimum code to make it pass
+3. Refactor while keeping tests green

django_lambda_tasks-0.2.0/.kiro/specs/ssm-environment-loader/requirements.md

@@ -0,0 +1,56 @@
+# Requirements Document
+
+## Introduction
+
+This feature adds SSM Parameter Store environment loading to the Lambda cold-start sequence. When the environment variable `LAMBDA_TASKS_SSM_ENVIRONMENT` is set, the Lambda handler reads the named SSM parameter, parses its JSON content as a flat key-value mapping, and sets the resulting pairs as environment variables. This happens before `django.setup()` and only on cold start, following the same pattern as the existing `resolve_secrets_into_env()` in `secret_loader.py`.
+
+## Glossary
+
+- **SSM_Environment_Loader**: The module responsible for reading an SSM Parameter Store parameter and setting its JSON content as environment variables
+- **SSM_Parameter**: An AWS Systems Manager Parameter Store parameter containing a JSON object whose keys and values are strings
+- **Cold_Start**: The first invocation of a Lambda container, before `django.setup()` has been called
+- **Handler**: The Lambda entry point in `handler.py` that orchestrates cold-start setup and SQS record processing
+
+## Requirements
+
+### Requirement 1: Load SSM parameter on cold start
+
+**User Story:** As a developer deploying Lambda tasks, I want environment variables loaded from an SSM parameter at cold start, so that I can manage environment configuration centrally in Parameter Store without baking values into the Lambda deployment package.
+
+#### Acceptance Criteria
+
+1. WHEN the environment variable `LAMBDA_TASKS_SSM_ENVIRONMENT` is set and the Lambda container is performing cold start, THE SSM_Environment_Loader SHALL retrieve the SSM parameter whose name matches the value of `LAMBDA_TASKS_SSM_ENVIRONMENT`
+2. WHEN the environment variable `LAMBDA_TASKS_SSM_ENVIRONMENT` is not set, THE SSM_Environment_Loader SHALL take no action and make no AWS API calls
+3. WHEN the SSM parameter is retrieved successfully, THE SSM_Environment_Loader SHALL parse the parameter value as a JSON object and set each key-value pair as an environment variable in `os.environ`
+4. THE SSM_Environment_Loader SHALL execute before the `os.environ.get("DJANGO_SETTINGS_MODULE")` check in the handler cold-start block
+5. THE SSM_Environment_Loader SHALL execute before `resolve_secrets_into_env()` is called during cold start
+6. THE SSM_Environment_Loader SHALL execute before `django.setup()` is called during cold start
+
+### Requirement 2: Validate SSM parameter content
+
+**User Story:** As a developer, I want the loader to fail fast on invalid parameter content, so that misconfiguration is caught immediately at cold start rather than causing subtle runtime errors.
+
+#### Acceptance Criteria
+
+1. IF the SSM parameter value is not valid JSON, THEN THE SSM_Environment_Loader SHALL raise a `ValueError` with a descriptive message including the parameter name
+2. IF the SSM parameter JSON is not a flat object (i.e. contains non-string values), THEN THE SSM_Environment_Loader SHALL raise a `ValueError` with a descriptive message identifying the offending keys
+3. IF the SSM parameter JSON contains an empty string as a key, THEN THE SSM_Environment_Loader SHALL raise a `ValueError` with a descriptive message
+
+### Requirement 3: Idempotent execution
+
+**User Story:** As a developer, I want the loader to be safe to call multiple times, so that warm invocations pay no extra cost and the function can be called defensively.
+
+#### Acceptance Criteria
+
+1. WHEN the SSM_Environment_Loader has already successfully loaded the parameter, THE SSM_Environment_Loader SHALL skip the AWS API call on subsequent invocations and return immediately
+2. THE SSM_Environment_Loader SHALL use a module-level cache to store the fetched parameter value for the lifetime of the Lambda container
+
+### Requirement 4: Function signature conventions
+
+**User Story:** As a maintainer, I want the loader to follow the project's coding conventions, so that the codebase remains consistent.
+
+#### Acceptance Criteria
+
+1. THE SSM_Environment_Loader SHALL expose a single public function `resolve_ssm_environment()` that takes no arguments
+2. THE SSM_Environment_Loader SHALL reside in a module named `ssm_environment_loader.py` within the `lambda_tasks` package
+3. THE SSM_Environment_Loader SHALL use keyword-only arguments for all internal helper functions with full type annotations

django_lambda_tasks-0.2.0/.kiro/specs/ssm-environment-loader/tasks.md

@@ -0,0 +1,124 @@
+# Implementation Plan: SSM Environment Loader
+
+## Overview
+
+Implement a new module `lambda_tasks/ssm_environment_loader.py` that reads an AWS SSM Parameter Store parameter at Lambda cold start and sets its JSON content as environment variables. Follow TDD: write failing tests first, then implement the minimum code to pass. Integrate into `handler.py` so SSM loading runs before secrets and Django setup.
+
+## Tasks
+
+- [x] 1. Create module skeleton and test infrastructure
+  - [x] 1.1 Create `lambda_tasks/ssm_environment_loader.py` with module docstring, imports, module-level `_loaded` sentinel, and stub `resolve_ssm_environment()` that does nothing
+    - Define `_loaded: bool = False`
+    - Import `os`, `json`, `logging`, `boto3`
+    - Stub `resolve_ssm_environment() -> None` with `pass` body
+    - Stub `_fetch_parameter(*, parameter_name: str) -> str` with `pass` body
+    - Stub `_validate_and_parse(*, raw_value: str, parameter_name: str) -> dict[str, str]` with `pass` body
+    - All functions use keyword-only args and full type annotations
+    - _Requirements: 4.1, 4.2, 4.3_
+
+  - [x] 1.2 Create `tests/test_ssm_environment_loader.py` with test scaffolding
+    - Add autouse fixture to reset `_loaded` sentinel between tests
+    - Add fixture to patch boto3 SSM client at module level (same pattern as `test_secret_loader.py`)
+    - Add monkeypatch-based env var helpers
+    - Verify module is importable and `resolve_ssm_environment` is callable with no args
+    - _Requirements: 4.1, 4.2_
+
+- [x] 2. Implement validation logic (`_validate_and_parse`)
+  - [x] 2.1 Write unit tests for `_validate_and_parse` covering invalid JSON, non-flat objects, and empty keys
+    - Test: invalid JSON string raises `ValueError` with parameter name in message
+    - Test: JSON with non-string values raises `ValueError` listing offending keys
+    - Test: JSON with empty string key raises `ValueError`
+    - Test: valid flat JSON returns `dict[str, str]`
+    - _Requirements: 2.1, 2.2, 2.3_
+
+  - [x] 2.2 Implement `_validate_and_parse` to pass all validation tests
+    - Parse with `json.loads`; catch `json.JSONDecodeError` and raise `ValueError` with parameter name
+    - Check top-level is a `dict`; raise if not
+    - Check all values are `str`; collect offending keys and raise `ValueError` listing them
+    - Check no empty string keys; raise `ValueError` if found
+    - Return validated `dict[str, str]`
+    - _Requirements: 2.1, 2.2, 2.3_
+
+  - [x] 2.3 Write property test for invalid JSON rejection
+    - **Property 2: Invalid JSON rejection**
+    - Generate arbitrary strings that are not valid JSON
+    - Assert `_validate_and_parse` raises `ValueError` with parameter name in message
+    - **Validates: Requirements 2.1**
+
+  - [x] 2.4 Write property test for non-flat JSON rejection with key identification
+    - **Property 3: Non-flat JSON rejection with key identification**
+    - Generate JSON objects with at least one non-string value (int, float, list, dict, bool, None)
+    - Assert `_validate_and_parse` raises `ValueError` whose message contains all offending key names
+    - **Validates: Requirements 2.2**
+
+- [x] 3. Implement core loading logic (`resolve_ssm_environment`)
+  - [x] 3.1 Write unit tests for `resolve_ssm_environment` no-op behaviour
+    - Test: when `LAMBDA_TASKS_SSM_ENVIRONMENT` is not set, no boto3 client is created and no API call is made
+    - Test: when `LAMBDA_TASKS_SSM_ENVIRONMENT` is not set, `os.environ` is unchanged
+    - _Requirements: 1.2_
+
+  - [x] 3.2 Write unit tests for `resolve_ssm_environment` happy path
+    - Test: when SSM parameter contains valid flat JSON, all key-value pairs are set in `os.environ`
+    - Test: SSM keys override existing env vars (no conflict detection)
+    - Test: `_fetch_parameter` calls `ssm.get_parameter(Name=param_name, WithDecryption=True)`
+    - _Requirements: 1.1, 1.3_
+
+  - [x] 3.3 Implement `_fetch_parameter` and `resolve_ssm_environment`
+    - `_fetch_parameter`: create boto3 SSM client, call `get_parameter(Name=parameter_name, WithDecryption=True)`, return `Parameter.Value`
+    - `resolve_ssm_environment`: check `LAMBDA_TASKS_SSM_ENVIRONMENT` env var; if not set, return immediately; if `_loaded` is True, return immediately; call `_fetch_parameter`, call `_validate_and_parse`, set each key in `os.environ`, set `_loaded = True`
+    - _Requirements: 1.1, 1.2, 1.3_
+
+  - [x] 3.4 Write property test for parameter content round-trip into environment
+    - **Property 1: Parameter content round-trip into environment**
+    - Generate arbitrary flat `dict[str, str]` (non-empty keys, string values)
+    - Mock SSM to return `json.dumps(generated_dict)`
+    - Assert every key-value pair from the dict is present in `os.environ` after calling `resolve_ssm_environment()`
+    - **Validates: Requirements 1.3**
+
+- [x] 4. Implement idempotency
+  - [x] 4.1 Write unit tests for idempotent execution
+    - Test: calling `resolve_ssm_environment()` twice results in only one boto3 API call
+    - Test: no boto3 client created on second call when `_loaded` is True
+    - _Requirements: 3.1, 3.2_
+
+  - [x] 4.2 Verify idempotency implementation passes (already implemented via `_loaded` flag in 3.3)
+    - Confirm `_loaded` sentinel prevents re-execution
+    - _Requirements: 3.1, 3.2_
+
+  - [x] 4.3 Write property test for idempotent execution
+    - **Property 4: Idempotent execution**
+    - Generate valid SSM content and a call count N (2 to 10)
+    - Call `resolve_ssm_environment()` N times
+    - Assert boto3 `get_parameter` was called exactly once
+    - **Validates: Requirements 3.1, 3.2**
+
+- [x] 5. Checkpoint - Ensure all tests pass
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [x] 6. Integrate into handler and verify ordering
+  - [x] 6.1 Write integration test for handler cold-start ordering
+    - Test: `resolve_ssm_environment()` is called before `resolve_secrets_into_env()`
+    - Test: both loaders run unconditionally before the `DJANGO_SETTINGS_MODULE` check
+    - Test: `django.setup()` is only called when `DJANGO_SETTINGS_MODULE` is set and `apps.ready` is False
+    - _Requirements: 1.4, 1.5, 1.6_
+
+  - [x] 6.2 Modify `lambda_tasks/handler.py` to integrate SSM loader
+    - Add `from lambda_tasks.ssm_environment_loader import resolve_ssm_environment`
+    - Move `resolve_secrets_into_env()` outside the `if` block
+    - Add `resolve_ssm_environment()` call before `resolve_secrets_into_env()`
+    - Keep `django.setup()` inside the `if os.environ.get("DJANGO_SETTINGS_MODULE") and not apps.ready:` conditional
+    - _Requirements: 1.4, 1.5, 1.6_
+
+- [x] 7. Final checkpoint - Ensure all tests pass
+  - Ensure all tests pass, ask the user if questions arise.
+
+## Notes
+
+- Tasks marked with `*` are optional and can be skipped for faster MVP
+- Each task references specific requirements for traceability
+- Checkpoints ensure incremental validation
+- Property tests validate universal correctness properties from the design document
+- Unit tests validate specific examples and edge cases
+- Follow TDD: write failing tests first (tasks X.1, X.2), then implement (tasks X.3)
+- All functions use keyword-only arguments and full type annotations per project conventions
+- boto3 is mocked in all tests — no real AWS calls

{django_lambda_tasks-0.1.5 → django_lambda_tasks-0.2.0}/.kiro/steering/product.md

@@ -135,11 +135,26 @@ class SQSLambdaTaskMessage(BaseModel):
 - Returns `{"batchItemFailures": [...]}` for partial-batch failure reporting
 - Only pre-execution failures (malformed message, import error, misconfiguration) are reported as `batchItemFailures` — task logic failures are caught and recorded as `FAILED` TaskRecords without raising
 - Recommended SQS queue settings: `maxReceiveCount=1` with a DLQ configured; automatic retries are not useful since task failures are not re-driven by design
-- Calls `resolve_secrets_into_env()` before `django.setup()` at cold start to populate env vars from AWS Secrets Manager
+- Cold-start sequence: `resolve_ssm_environment()` → `resolve_secrets_into_env()` → conditional `django.setup()`
+- Both loaders run unconditionally (outside the `DJANGO_SETTINGS_MODULE` check) — SSM may provide that var, and secrets may depend on SSM-loaded vars
+
+## SSM Environment Loader
+
+`resolve_ssm_environment()` in `ssm_environment_loader.py` runs once at Lambda cold start, before `resolve_secrets_into_env()` and `django.setup()`.
+
+When the environment variable `LAMBDA_TASKS_SSM_ENVIRONMENT` is set, the loader fetches the named SSM parameter, parses its JSON content as a flat key-value mapping, and sets the resulting pairs as environment variables.
+
+Behaviour:
+- If `LAMBDA_TASKS_SSM_ENVIRONMENT` is not set, does nothing (no AWS API calls)
+- Fetches the parameter with `WithDecryption=True`
+- Validates the parameter value is a flat JSON object (all values must be strings, no empty keys)
+- Sets each key-value pair in `os.environ` — existing env vars are overridden (no conflict detection)
+- Idempotent via a module-level `_loaded` sentinel — subsequent calls are free no-ops
+- Invalid JSON, non-flat objects, or empty keys raise `ValueError` at cold start
 
 ## Secret Loader
 
-`resolve_secrets_into_env()` in `secret_loader.py` runs once at Lambda cold start, before `django.setup()`.
+`resolve_secrets_into_env()` in `secret_loader.py` runs once at Lambda cold start, after `resolve_ssm_environment()` and before `django.setup()`.
 
 Any env var prefixed `LAMBDA_TASKS_SECRET_` is treated as a Secrets Manager reference. The unprefixed name is the target env var.
 

{django_lambda_tasks-0.1.5 → django_lambda_tasks-0.2.0}/.kiro/steering/structure.md

@@ -18,6 +18,7 @@ django-lambda-tasks/
 │   ├── models.py               # TaskRecord, SQSLambdaTaskMessage, SQSLambdaTask
 │   ├── settings.py             # LambdaTasksSettings (lazy Django settings reader)
 │   ├── secret_loader.py        # Resolves LAMBDA_TASKS_SECRET_* env vars at cold start
+│   ├── ssm_environment_loader.py # Loads env vars from SSM Parameter Store at cold start
 │   ├── tasks.py                # Built-in maintenance tasks (cleanup_task_records)
 │   ├── timeouts.py             # TimeoutContext implementation
 │   └── migrations/             # Django migrations for TaskRecord
@@ -39,8 +40,9 @@ django-lambda-tasks/
 
 - `decorators.py` — defines `@lambda_task`; enforces kwargs-only at decoration time
 - `models.py` — `TaskRecord` (Django ORM), `SQSLambdaTaskMessage` (Pydantic, SQS schema + execution logic), `SQSLambdaTask` (Pydantic, holds message + routing; `_execute()` publishes to SQS or executes eagerly; `execute_on_commit()` registers `_execute` with `transaction.on_commit`)
-- `handler.py` — Lambda entry point; calls `resolve_secrets_into_env()` then `django.setup()` at cold start; processes SQS records independently; returns `batchItemFailures`
-- `secret_loader.py` — resolves `LAMBDA_TASKS_SECRET_*` env vars from Secrets Manager before Django starts; validates format, detects conflicts, batches API calls, caches results in-process
+- `handler.py` — Lambda entry point; calls `resolve_ssm_environment()` then `resolve_secrets_into_env()` then conditionally `django.setup()` at cold start; processes SQS records independently; returns `batchItemFailures`
+- `ssm_environment_loader.py` — loads env vars from an SSM Parameter Store parameter at cold start; validates flat JSON format; idempotent via `_loaded` sentinel
+- `secret_loader.py` — resolves `LAMBDA_TASKS_SECRET_*` env vars from Secrets Manager before Django starts; validates format, detects conflicts, batches API calls; idempotent via `_loaded` sentinel
 - `logging.py` — `task_logger` singleton; `message_id` set/cleared around each task execution
 - `settings.py` — `LambdaTasksSettings` instantiated fresh per use (reads live Django settings)
 - `admin.py` — Django admin registration for `TaskRecord`

{django_lambda_tasks-0.1.5 → django_lambda_tasks-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-lambda-tasks
-Version: 0.1.5
+Version: 0.2.0
 Summary: Run async tasks in a lambda function
 Requires-Python: >=3.10
 Requires-Dist: awslambdaric
@@ -437,6 +437,12 @@ lambda_tasks.handler.handler
 
 Ensure the Lambda execution environment has `DJANGO_SETTINGS_MODULE` set and that all task modules are importable (i.e. your application code is on the Python path).
 
+| Environment Variable | Required | Description |
+|---|---|---|
+| `DJANGO_SETTINGS_MODULE` | Yes | Django settings module path (e.g. `myapp.settings.production`). |
+| `LAMBDA_TASKS_SSM_ENVIRONMENT` | No | SSM Parameter Store parameter name to load as environment variables at cold start. |
+| `LAMBDA_TASKS_SECRET_*` | No | Secrets Manager references resolved into env vars at cold start (see below). |
+
 ### Resolving Django settings from AWS Secrets Manager
 
 The Lambda handler supports loading secret values from AWS Secrets Manager into the environment before Django starts. This lets your Django settings file read from `os.environ` as normal while keeping secrets out of plaintext environment variables.
@@ -487,6 +493,46 @@ The following all raise `ValueError` at cold start, preventing the Lambda contai
 - The named JSON key does not exist in the fetched secret
 - The secret value is not valid JSON
 
+### Loading environment variables from SSM Parameter Store
+
+The Lambda handler supports loading environment variables from an AWS SSM Parameter Store parameter at cold start. This lets you manage environment configuration centrally in Parameter Store without baking values into the Lambda deployment package.
+
+Set the `LAMBDA_TASKS_SSM_ENVIRONMENT` environment variable to the name of an SSM parameter:
+
+```
+LAMBDA_TASKS_SSM_ENVIRONMENT=/myapp/prod/environment
+```
+
+The parameter value must be a flat JSON object where all keys and values are strings:
+
+```json
+{
+  "DATABASE_URL": "postgres://user:pass@host:5432/db",
+  "REDIS_URL": "redis://host:6379/0",
+  "DJANGO_SETTINGS_MODULE": "myapp.settings.production"
+}
+```
+
+At cold start, before `resolve_secrets_into_env()` and `django.setup()`, the handler calls `resolve_ssm_environment()` which:
+
+1. Checks for the `LAMBDA_TASKS_SSM_ENVIRONMENT` env var — if not set, does nothing
+2. Fetches the named parameter via `ssm.get_parameter(Name=..., WithDecryption=True)`
+3. Validates the parameter value is a flat JSON object (all values must be strings, no empty keys)
+4. Sets each key-value pair in `os.environ` — existing env vars are overridden
+5. Caches the result via a module-level sentinel — subsequent calls are free no-ops
+
+Because SSM loading runs first, the parameter can provide `DJANGO_SETTINGS_MODULE` itself, and secrets loaded by `resolve_secrets_into_env()` can reference SSM-loaded values.
+
+#### Validation errors
+
+The following raise `ValueError` at cold start, preventing the Lambda container from starting:
+
+- Parameter value is not valid JSON
+- JSON is not a flat object (contains non-string values) — error message lists the offending keys
+- JSON contains an empty string key
+
+AWS errors (parameter not found, permission denied) propagate as boto3 exceptions and crash the container at cold start.
+
 ---
 
 ## Built-in tasks

{django_lambda_tasks-0.1.5 → django_lambda_tasks-0.2.0}/README.md

@@ -425,6 +425,12 @@ lambda_tasks.handler.handler
 
 Ensure the Lambda execution environment has `DJANGO_SETTINGS_MODULE` set and that all task modules are importable (i.e. your application code is on the Python path).
 
+| Environment Variable | Required | Description |
+|---|---|---|
+| `DJANGO_SETTINGS_MODULE` | Yes | Django settings module path (e.g. `myapp.settings.production`). |
+| `LAMBDA_TASKS_SSM_ENVIRONMENT` | No | SSM Parameter Store parameter name to load as environment variables at cold start. |
+| `LAMBDA_TASKS_SECRET_*` | No | Secrets Manager references resolved into env vars at cold start (see below). |
+
 ### Resolving Django settings from AWS Secrets Manager
 
 The Lambda handler supports loading secret values from AWS Secrets Manager into the environment before Django starts. This lets your Django settings file read from `os.environ` as normal while keeping secrets out of plaintext environment variables.
@@ -475,6 +481,46 @@ The following all raise `ValueError` at cold start, preventing the Lambda contai
 - The named JSON key does not exist in the fetched secret
 - The secret value is not valid JSON
 
+### Loading environment variables from SSM Parameter Store
+
+The Lambda handler supports loading environment variables from an AWS SSM Parameter Store parameter at cold start. This lets you manage environment configuration centrally in Parameter Store without baking values into the Lambda deployment package.
+
+Set the `LAMBDA_TASKS_SSM_ENVIRONMENT` environment variable to the name of an SSM parameter:
+
+```
+LAMBDA_TASKS_SSM_ENVIRONMENT=/myapp/prod/environment
+```
+
+The parameter value must be a flat JSON object where all keys and values are strings:
+
+```json
+{
+  "DATABASE_URL": "postgres://user:pass@host:5432/db",
+  "REDIS_URL": "redis://host:6379/0",
+  "DJANGO_SETTINGS_MODULE": "myapp.settings.production"
+}
+```
+
+At cold start, before `resolve_secrets_into_env()` and `django.setup()`, the handler calls `resolve_ssm_environment()` which:
+
+1. Checks for the `LAMBDA_TASKS_SSM_ENVIRONMENT` env var — if not set, does nothing
+2. Fetches the named parameter via `ssm.get_parameter(Name=..., WithDecryption=True)`
+3. Validates the parameter value is a flat JSON object (all values must be strings, no empty keys)
+4. Sets each key-value pair in `os.environ` — existing env vars are overridden
+5. Caches the result via a module-level sentinel — subsequent calls are free no-ops
+
+Because SSM loading runs first, the parameter can provide `DJANGO_SETTINGS_MODULE` itself, and secrets loaded by `resolve_secrets_into_env()` can reference SSM-loaded values.
+
+#### Validation errors
+
+The following raise `ValueError` at cold start, preventing the Lambda container from starting:
+
+- Parameter value is not valid JSON
+- JSON is not a flat object (contains non-string values) — error message lists the offending keys
+- JSON contains an empty string key
+
+AWS errors (parameter not found, permission denied) propagate as boto3 exceptions and crash the container at cold start.
+
 ---
 
 ## Built-in tasks

{django_lambda_tasks-0.1.5 → django_lambda_tasks-0.2.0}/lambda_tasks/handler.py

@@ -13,23 +13,26 @@ import django
 from django.apps import apps
 
 from lambda_tasks.secret_loader import resolve_secrets_into_env
+from lambda_tasks.ssm_environment_loader import resolve_ssm_environment
+
+# Both loaders are idempotent and run unconditionally before the
+# DJANGO_SETTINGS_MODULE check — SSM may provide that var, and
+# secrets may depend on SSM-loaded vars.
+resolve_ssm_environment()
+resolve_secrets_into_env()
 
-# Cold-start Django setup — runs once per Lambda container.
-# Secrets are resolved first so Django settings can reference the populated
-# env vars. resolve_secrets_into_env() is idempotent and caches fetched
-# secrets in-process, so subsequent invocations pay no extra cost.
 if os.environ.get("DJANGO_SETTINGS_MODULE") and not apps.ready:
-    resolve_secrets_into_env()
     django.setup()
 
 
 logger = logging.getLogger(__name__)
 
 
-def handler(*, event: dict, context: object) -> dict:
+def handler(event: dict, context: object) -> dict:
     """AWS Lambda entry point. Processes a batch of SQS records.
 
     Returns a partial-batch failure report so AWS only re-drives failed records.
+    Signature is fixed by AWS and uses two args only.
     """
     # Local import due to AppRegistryNotReady
     from lambda_tasks.models import SQSLambdaTaskMessage

{django_lambda_tasks-0.1.5 → django_lambda_tasks-0.2.0}/lambda_tasks/secret_loader.py

@@ -37,6 +37,10 @@ logger = logging.getLogger(__name__)
 
 _PREFIX = "LAMBDA_TASKS_SECRET_"
 
+# Module-level sentinel: once resolve_secrets_into_env() completes successfully,
+# subsequent calls return immediately without re-scanning or re-resolving.
+_loaded: bool = False
+
 # Module-level cache: (arn, version_stage, version_id) → raw secret string.
 # Populated on first call; reused for the lifetime of the Lambda container.
 _secret_cache: dict[tuple[str, str, str], dict[str, str]] = {}
@@ -139,8 +143,14 @@ def resolve_secrets_into_env() -> None:
       ``FOO``, not both
 
     This function is idempotent — calling it multiple times is safe and cheap
-    because resolved secrets are cached after the first fetch.
+    because a module-level sentinel prevents re-execution after the first
+    successful call.
     """
+    global _loaded
+
+    if _loaded:
+        return
+
     references: dict[str, _SecretReference] = {}  # target_name → _SecretReference
 
     for key, value in os.environ.items():
@@ -181,3 +191,5 @@ def resolve_secrets_into_env() -> None:
         os.environ[target] = secret_value
 
         logger.info(f"Resolved {target} from secret {ref}")
+
+    _loaded = True