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

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

@@ -135,26 +135,29 @@ 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
-- 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
+- Cold-start sequence: `resolve_environment()` → `resolve_secrets_into_env()` → conditional `django.setup()`
+- Both loaders run unconditionally (outside the `DJANGO_SETTINGS_MODULE` check) — the environment secret may provide that var, and individual secrets may depend on environment-loaded vars
 
-## SSM Environment Loader
+## Environment Loader
 
-`resolve_ssm_environment()` in `ssm_environment_loader.py` runs once at Lambda cold start, before `resolve_secrets_into_env()` and `django.setup()`.
+`resolve_environment()` in `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.
+When the environment variable `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` is set, the loader parses the reference, fetches the named Secrets Manager secret, parses its JSON content as a flat key-value mapping, and sets the resulting pairs as environment variables.
+
+Required format: `<arn>:<version-stage>:<version-id>` (9 colon-separated segments — the ARN is 7 segments, plus version-stage and version-id). Both suffix fields must be non-empty.
 
 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)
+- If `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` is not set, does nothing (no AWS API calls)
+- Validates the reference format before any AWS call — malformed references raise `ValueError` immediately
+- Fetches the secret via `secretsmanager.get_secret_value(SecretId=..., VersionStage=..., VersionId=...)`
+- Validates the secret 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
+- Invalid reference format, 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, after `resolve_ssm_environment()` and before `django.setup()`.
+`resolve_secrets_into_env()` in `secret_loader.py` runs once at Lambda cold start, after `resolve_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.2.0 → django_lambda_tasks-0.2.1}/.kiro/steering/structure.md

@@ -18,7 +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
+│   ├── environment_loader.py    # Loads env vars from Secrets Manager at cold start
 │   ├── tasks.py                # Built-in maintenance tasks (cleanup_task_records)
 │   ├── timeouts.py             # TimeoutContext implementation
 │   └── migrations/             # Django migrations for TaskRecord
@@ -40,8 +40,8 @@ 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_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
+- `handler.py` — Lambda entry point; calls `resolve_environment()` then `resolve_secrets_into_env()` then conditionally `django.setup()` at cold start; processes SQS records independently; returns `batchItemFailures`
+- `environment_loader.py` — loads env vars from a Secrets Manager secret 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)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-lambda-tasks
-Version: 0.2.0
+Version: 0.2.1
 Summary: Run async tasks in a lambda function
 Requires-Python: >=3.10
 Requires-Dist: awslambdaric
@@ -440,7 +440,7 @@ Ensure the Lambda execution environment has `DJANGO_SETTINGS_MODULE` set and tha
 | 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_ENVIRONMENT_SECRETS_MANAGER_ARN` | No | Secrets Manager reference (`<arn>:<version-stage>:<version-id>`) 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
@@ -493,17 +493,19 @@ 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
+### Loading environment variables from Secrets Manager
 
-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.
+The Lambda handler supports loading environment variables from an AWS Secrets Manager secret at cold start. This lets you manage environment configuration centrally in Secrets Manager without baking values into the Lambda deployment package.
 
-Set the `LAMBDA_TASKS_SSM_ENVIRONMENT` environment variable to the name of an SSM parameter:
+Set the `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` environment variable to a full reference including version stage and version ID:
 
 ```
-LAMBDA_TASKS_SSM_ENVIRONMENT=/myapp/prod/environment
+LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN=arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod/environment:AWSCURRENT:v1
 ```
 
-The parameter value must be a flat JSON object where all keys and values are strings:
+The format is `<arn>:<version-stage>:<version-id>` (9 colon-separated segments — the ARN is 7 segments, plus version-stage and version-id). Both suffix fields must be non-empty.
+
+The secret value must be a flat JSON object where all keys and values are strings:
 
 ```json
 {
@@ -513,25 +515,27 @@ The parameter value must be a flat JSON object where all keys and values are str
 }
 ```
 
-At cold start, before `resolve_secrets_into_env()` and `django.setup()`, the handler calls `resolve_ssm_environment()` which:
+At cold start, before `resolve_secrets_into_env()` and `django.setup()`, the handler calls `resolve_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
+1. Checks for the `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` env var — if not set, does nothing
+2. Parses and validates the reference format (9 segments, non-empty version-stage and version-id)
+3. Fetches the secret via `secretsmanager.get_secret_value(SecretId=..., VersionStage=..., VersionId=...)`
+4. Validates the secret value is a flat JSON object (all values must be strings, no empty keys)
+5. Sets each key-value pair in `os.environ` — existing env vars are overridden
+6. 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.
+Because environment loading runs first, the secret can provide `DJANGO_SETTINGS_MODULE` itself, and individual secrets loaded by `resolve_secrets_into_env()` can reference environment-loaded values.
 
 #### Validation errors
 
 The following raise `ValueError` at cold start, preventing the Lambda container from starting:
 
-- Parameter value is not valid JSON
+- Reference format is invalid (wrong segment count, empty version-stage or version-id)
+- Secret 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.
+AWS errors (secret not found, permission denied) propagate as boto3 exceptions and crash the container at cold start.
 
 ---
 

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

@@ -428,7 +428,7 @@ Ensure the Lambda execution environment has `DJANGO_SETTINGS_MODULE` set and tha
 | 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_ENVIRONMENT_SECRETS_MANAGER_ARN` | No | Secrets Manager reference (`<arn>:<version-stage>:<version-id>`) 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
@@ -481,17 +481,19 @@ 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
+### Loading environment variables from Secrets Manager
 
-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.
+The Lambda handler supports loading environment variables from an AWS Secrets Manager secret at cold start. This lets you manage environment configuration centrally in Secrets Manager without baking values into the Lambda deployment package.
 
-Set the `LAMBDA_TASKS_SSM_ENVIRONMENT` environment variable to the name of an SSM parameter:
+Set the `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` environment variable to a full reference including version stage and version ID:
 
 ```
-LAMBDA_TASKS_SSM_ENVIRONMENT=/myapp/prod/environment
+LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN=arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod/environment:AWSCURRENT:v1
 ```
 
-The parameter value must be a flat JSON object where all keys and values are strings:
+The format is `<arn>:<version-stage>:<version-id>` (9 colon-separated segments — the ARN is 7 segments, plus version-stage and version-id). Both suffix fields must be non-empty.
+
+The secret value must be a flat JSON object where all keys and values are strings:
 
 ```json
 {
@@ -501,25 +503,27 @@ The parameter value must be a flat JSON object where all keys and values are str
 }
 ```
 
-At cold start, before `resolve_secrets_into_env()` and `django.setup()`, the handler calls `resolve_ssm_environment()` which:
+At cold start, before `resolve_secrets_into_env()` and `django.setup()`, the handler calls `resolve_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
+1. Checks for the `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` env var — if not set, does nothing
+2. Parses and validates the reference format (9 segments, non-empty version-stage and version-id)
+3. Fetches the secret via `secretsmanager.get_secret_value(SecretId=..., VersionStage=..., VersionId=...)`
+4. Validates the secret value is a flat JSON object (all values must be strings, no empty keys)
+5. Sets each key-value pair in `os.environ` — existing env vars are overridden
+6. 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.
+Because environment loading runs first, the secret can provide `DJANGO_SETTINGS_MODULE` itself, and individual secrets loaded by `resolve_secrets_into_env()` can reference environment-loaded values.
 
 #### Validation errors
 
 The following raise `ValueError` at cold start, preventing the Lambda container from starting:
 
-- Parameter value is not valid JSON
+- Reference format is invalid (wrong segment count, empty version-stage or version-id)
+- Secret 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.
+AWS errors (secret not found, permission denied) propagate as boto3 exceptions and crash the container at cold start.
 
 ---
 

django_lambda_tasks-0.2.1/lambda_tasks/environment_loader.py

@@ -0,0 +1,155 @@
+"""
+Resolves environment variables from an AWS Secrets Manager secret.
+
+When the environment variable ``LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN``
+is set, this module fetches the named secret, parses its value as a flat JSON
+object (all keys and values must be strings), and sets each key-value pair in
+``os.environ``.
+
+Required value format::
+
+    LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN=arn:aws:secretsmanager:eu-west-1:123:secret:my-env:AWSCURRENT:v1
+
+That is: ``<arn>:<version-stage>:<version-id>`` (9 colon-separated segments).
+The ARN is 7 segments, plus version-stage and version-id.
+
+This runs at Lambda cold start — before ``resolve_secrets_into_env()`` and
+before ``django.setup()`` — so that environment variables loaded from the
+secret are available to both the secret loader and Django configuration.
+
+The result is cached at module level via a ``_loaded`` sentinel so that
+subsequent calls (warm invocations) are free no-ops.
+"""
+
+import json
+import logging
+import os
+from typing import NamedTuple
+
+import boto3
+
+logger = logging.getLogger(__name__)
+
+_loaded: bool = False
+
+
+class _EnvironmentSecretReference(NamedTuple):
+    arn: str
+    version_stage: str
+    version_id: str
+
+
+def resolve_environment() -> None:
+    """Load secret content into os.environ.
+
+    Reads the secret identified by LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN,
+    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 env var format is invalid, the secret content
+                    is not valid JSON, not a flat string→string mapping,
+                    or contains an empty string key.
+    """
+    global _loaded
+
+    raw_reference = os.environ.get("LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN")
+    if not raw_reference:
+        return
+
+    if _loaded:
+        return
+
+    ref = _parse_reference(value=raw_reference)
+    raw_value = _fetch_secret(ref=ref)
+    parsed = _validate_and_parse(raw_value=raw_value, secret_arn=ref.arn)
+
+    for key, value in parsed.items():
+        os.environ[key] = value
+
+    _loaded = True
+
+
+def _parse_reference(*, value: str) -> _EnvironmentSecretReference:
+    """Parse and validate the environment secret reference.
+
+    Expected format::
+
+        <arn>:<version-stage>:<version-id>
+
+    The ARN itself is 7 colon-separated segments, plus 2 suffix segments
+    (version-stage, version-id) = 9 total.
+    Both suffix fields must be non-empty.
+
+    Raises ``ValueError`` if the format is invalid.
+    """
+    parts = value.split(":")
+
+    if len(parts) != 9:
+        raise ValueError(
+            "LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN has an invalid format. "
+            "Expected <arn>:<version-stage>:<version-id> "
+            f"(9 colon-separated segments), got {len(parts)}: {value!r}"
+        )
+
+    arn = ":".join(parts[:7])
+    version_stage = parts[7]
+    version_id = parts[8]
+
+    for field, field_value in (
+        ("version-stage", version_stage),
+        ("version-id", version_id),
+    ):
+        if not field_value:
+            raise ValueError(
+                f"LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN is missing the "
+                f"{field} segment: {value!r}"
+            )
+
+    return _EnvironmentSecretReference(
+        arn=arn,
+        version_stage=version_stage,
+        version_id=version_id,
+    )
+
+
+def _fetch_secret(*, ref: _EnvironmentSecretReference) -> str:
+    """Fetch a secret string from Secrets Manager using boto3."""
+    client = boto3.client("secretsmanager")
+    response = client.get_secret_value(
+        SecretId=ref.arn,
+        VersionStage=ref.version_stage,
+        VersionId=ref.version_id,
+    )
+    return response["SecretString"]
+
+
+def _validate_and_parse(*, raw_value: str, secret_arn: str) -> dict[str, str]:
+    """Parse JSON and validate it is a flat str→str mapping.
+
+    Raises ValueError with descriptive messages on failure.
+    """
+    try:
+        parsed = json.loads(raw_value)
+    except json.JSONDecodeError as exc:
+        raise ValueError(
+            f"Secret {secret_arn} does not contain valid JSON: {exc}"
+        ) from exc
+
+    if not isinstance(parsed, dict):
+        raise ValueError(
+            f"Secret {secret_arn} must be a JSON object, got {type(parsed).__name__}"
+        )
+
+    non_string_keys = [
+        key for key, value in parsed.items() if not isinstance(value, str)
+    ]
+    if non_string_keys:
+        raise ValueError(
+            f"Secret {secret_arn} contains non-string values for keys: {non_string_keys}"
+        )
+
+    if "" in parsed:
+        raise ValueError(f"Secret {secret_arn} contains an empty string key")
+
+    return parsed

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

@@ -12,13 +12,13 @@ import os
 import django
 from django.apps import apps
 
+from lambda_tasks.environment_loader import resolve_environment
 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()
+# DJANGO_SETTINGS_MODULE check — the environment secret may provide
+# that var, and individual secrets may depend on environment-loaded vars.
+resolve_environment()
 resolve_secrets_into_env()
 
 if os.environ.get("DJANGO_SETTINGS_MODULE") and not apps.ready:

{django_lambda_tasks-0.2.0 → django_lambda_tasks-0.2.1}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["lambda_tasks"]
 
 [project]
 name = "django-lambda-tasks"
-version = "0.2.0"
+version = "0.2.1"
 description = "Run async tasks in a lambda function"
 readme = "README.md"
 requires-python = ">=3.10"