velocity-python 0.1.126__tar.gz → 0.1.129__tar.gz

{velocity_python-0.1.126 → velocity_python-0.1.129}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.126
+Version: 0.1.129
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT
@@ -34,9 +34,7 @@ Requires-Dist: odfpy>=1.4.0; extra == "ods"
 Provides-Extra: templates
 Requires-Dist: jinja2>=3.1.0; extra == "templates"
 Provides-Extra: pdf
-Requires-Dist: pdfkit>=1.0.0; extra == "pdf"
-Provides-Extra: pdf-weasyprint
-Requires-Dist: weasyprint>=60.0; extra == "pdf-weasyprint"
+Requires-Dist: weasyprint>=60.0; extra == "pdf"
 Provides-Extra: http
 Requires-Dist: requests>=2.32.0; extra == "http"
 Provides-Extra: mysql

{velocity_python-0.1.126 → velocity_python-0.1.129}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.126"
+version = "0.1.129"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]
@@ -54,11 +54,8 @@ ods = [
 templates = [
   "jinja2>=3.1.0",
 ]
+# HTML→PDF via WeasyPrint; native libs (Pango/Cairo) come from the OS or a layer.
 pdf = [
-  "pdfkit>=1.0.0",
-]
-# Maintained HTML→PDF engine; native libs (Pango/Cairo) come from the OS or a layer.
-pdf-weasyprint = [
   "weasyprint>=60.0",
 ]
 http = [

{velocity_python-0.1.126 → velocity_python-0.1.129}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.126"
+__version__ = version = "0.1.129"
 
 import importlib as _importlib
 

{velocity_python-0.1.126 → velocity_python-0.1.129}/src/velocity/aws/amplify.py

@@ -1,5 +1,4 @@
 import boto3
-import time
 from collections.abc import Mapping, Sequence
 
 
@@ -190,31 +189,23 @@ class AmplifyProject:
         )
 
     def check_policies(self, function):
-        # Attach a role policy
-        iam_client = boto3.client("iam")
-        response = iam_client.list_attached_role_policies(
-            RoleName=function["Role"].split("/")[1]
+        """Attach the shared ENI baseline (AWS-managed
+        AWSLambdaVPCAccessExecutionRole) to the function's role.
+
+        No longer attaches the account-wide ``lambda-vpc-execution`` policy or
+        AmazonSQSFullAccess (AWS-1); app grants come from
+        velocity.aws.deploy.run_deployment's per-app, per-stage policy.
+        """
+        from velocity.aws.deploy.policies import (
+            SHARED_BASELINE_POLICY_ARNS,
+            attach_role_policies,
+        )
+
+        attach_role_policies(
+            boto3.client("iam"),
+            function["Role"].split("/")[-1],
+            SHARED_BASELINE_POLICY_ARNS,
         )
-        has_policy_attached = False
-        for policy in response["AttachedPolicies"]:
-            if policy["PolicyName"] == "lambda-vpc-execution":
-                has_policy_attached = True
-        if not has_policy_attached:
-            account_id = self.get_account_id()
-            iam_client.attach_role_policy(
-                PolicyArn=f"arn:aws:iam::{account_id}:policy/lambda-vpc-execution",
-                RoleName=function["Role"].split("/")[1],
-            )
-            time.sleep(15)
-        has_policy_attached = False
-        for policy in response["AttachedPolicies"]:
-            if policy["PolicyName"] == "AmazonSQSFullAccess":
-                has_policy_attached = True
-        if not has_policy_attached:
-            iam_client.attach_role_policy(
-                PolicyArn="arn:aws:iam::aws:policy/AmazonSQSFullAccess",
-                RoleName=function["Role"].split("/")[1],
-            )
 
     def sync(self, branch):
         raise RuntimeError(

{velocity_python-0.1.126 → velocity_python-0.1.129}/src/velocity/aws/amplify_build.py

@@ -5,9 +5,10 @@ package (config / targets / policies / operations / reconcile). This module
 keeps every name and signature the existing project build.py files import,
 with pre-refactor behavior:
 
-- run_backend_deployment() runs in "legacy-union" policy mode (config extras
-  unioned into the shared lambda-vpc-execution policy). Projects migrated to
-  velocity.aws.deploy.run_deployment() get per-app reconciled policies.
+- run_backend_deployment() delegates to velocity.aws.deploy.run_deployment()
+  (per-app, per-stage declarative policies). The former "legacy-union" mode,
+  which unioned every app's extras into the shared lambda-vpc-execution
+  policy, was removed (AWS-1): no consumer used it.
 
 New projects should import from velocity.aws.deploy directly.
 """
@@ -80,33 +81,15 @@ def ensure_lambda_policies_and_attach(
     config: Optional[DeploymentConfig] = None,
     iam_client=None,
 ) -> None:
-    """Legacy per-function policy ensure: union document into the shared
-    lambda-vpc-execution policy, then attach it + AmazonSQSFullAccess."""
-    if iam_client is None:
-        iam_client = boto3.client("iam")
-
-    account_id = app.get_account_id()
-    policy_arn = f"arn:aws:iam::{account_id}:policy/lambda-vpc-execution"
-    policy_document = baseline_lambda_policy_document(account_id)
-    if config is not None:
-        policy_document = config.build_lambda_policy_document(policy_document)
-
-    try:
-        retryable_call(iam_client.get_policy, PolicyArn=policy_arn)
-    except iam_client.exceptions.NoSuchEntityException:
-        _ensure_policy_document_size("lambda-vpc-execution", policy_document)
-        print("Creating policy lambda-vpc-execution")
-        retryable_call(
-            iam_client.create_policy,
-            PolicyName="lambda-vpc-execution",
-            PolicyDocument=_serialize_policy_document(policy_document),
-        )
-        time.sleep(10)
-    else:
-        sync_managed_policy_document(iam_client, policy_arn, policy_document)
-
-    role_name = function["Role"].split("/")[-1]
-    attach_role_policies(iam_client, role_name, [policy_arn, AWS_SQS_FULL_ACCESS_ARN])
+    """Removed: this unioned app grants into the account-wide
+    lambda-vpc-execution policy and attached AmazonSQSFullAccess (AWS-1).
+    Use velocity.aws.deploy.run_deployment(), which reconciles a per-app,
+    per-stage policy declaratively."""
+    del app, function, config, iam_client
+    raise RuntimeError(
+        "ensure_lambda_policies_and_attach was removed (it granted account-wide "
+        "SSM/Cognito/SQS access); use velocity.aws.deploy.run_deployment()"
+    )
 
 
 def set_cloudwatch_logging(
@@ -141,7 +124,6 @@ def run_backend_deployment(
     run_deployment(
         target,
         config,
-        policy_mode="legacy-union",
         lambda_client=lambda_client,
         logs_client=logs_client,
     )

{velocity_python-0.1.126 → velocity_python-0.1.129}/src/velocity/aws/capabilities/jobs.py

@@ -53,7 +53,30 @@ class Jobs(Capability):
                         where={"sys_id": job["sys_id"]},
                     )
                     expired += 1
+                    _report_after_commit(tx, job, status)
 
         days = int(config.get("job_retention_days") or 30)
         purged = jobs.purge({"<sys_created": now - datetime.timedelta(days=days)})
         return {"expired": expired, "purged": purged}
+
+
+def _report_after_commit(tx, job, status):
+    """A job whose worker died never reached onError, so nothing reported it:
+    publish a ``source="job"`` failure event once the sweep commits."""
+    from velocity.aws import failures
+
+    job_id = job.get("job_id")
+    action = job.get("action")
+
+    def _send():
+        failures.report(
+            None,
+            failures.JobWorkerDied(
+                f"job {job_id} stuck in {status}: {STALE_FAILURE['error']}"
+            ),
+            source="job",
+            action=action,
+            job_id=job_id,
+        )
+
+    tx.on_commit(_send)

{velocity_python-0.1.126 → velocity_python-0.1.129}/src/velocity/aws/deploy/__init__.py

@@ -17,11 +17,15 @@ See docs/deploy.md in the velocity-python repo.
 
 from velocity.aws.deploy.config import BackendDeploymentConfig, DeploymentConfig
 from velocity.aws.deploy.policies import (
+    AWS_LAMBDA_VPC_ACCESS_ARN,
     IAM_MANAGED_POLICY_MAX_CHARS,
     ManagedPolicySizeError,
     app_policy_name,
+    app_runtime_statements,
     baseline_lambda_policy_document,
     ensure_app_policy,
+    reconcile_role_policies,
+    retire_policy,
     sync_managed_policy_document,
 )
 from velocity.aws.deploy.operations import (
@@ -29,7 +33,9 @@ from velocity.aws.deploy.operations import (
     ensure_cloudwatch_log_group,
     ensure_dlq,
     ensure_identity_pool_developer_provider,
+    ensure_queue_event_source_mapping,
     list_functions_by_tag,
+    queue_visibility_timeout,
     resolve_latest_layer_arns,
     retryable_call,
     set_cloudwatch_logging,
@@ -48,6 +54,7 @@ from velocity.aws.deploy.reconcile import (
 )
 
 __all__ = [
+    "AWS_LAMBDA_VPC_ACCESS_ARN",
     "AmplifyTarget",
     "BackendDeploymentConfig",
     "DeploymentConfig",
@@ -55,16 +62,21 @@ __all__ = [
     "ManagedPolicySizeError",
     "PlainTarget",
     "app_policy_name",
+    "app_runtime_statements",
     "baseline_lambda_policy_document",
     "ensure_api_cors_header",
     "ensure_app_policy",
     "ensure_cloudwatch_log_group",
     "ensure_dlq",
     "ensure_identity_pool_developer_provider",
+    "ensure_queue_event_source_mapping",
     "get_amplify_app_id_and_branch",
     "initialize_build_environment",
     "list_functions_by_tag",
+    "queue_visibility_timeout",
+    "reconcile_role_policies",
     "resolve_latest_layer_arns",
+    "retire_policy",
     "retryable_call",
     "run_deployment",
     "set_cloudwatch_logging",

velocity_python-0.1.129/src/velocity/aws/deploy/config.py

@@ -0,0 +1,115 @@
+"""Declarative deployment configuration for velocity.aws.deploy.
+
+DeploymentConfig describes everything a project's backend deployment needs:
+queue naming, VPC placement, per-function timeout/memory overrides, and the
+project's IAM policy statements. It is platform-neutral — nothing here assumes
+Amplify.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Mapping, Optional, Sequence, Tuple
+
+
+@dataclass(frozen=True)
+class DeploymentConfig:
+    queue_name_template: str
+    subnet_ids: Tuple[str, ...] = field(default_factory=tuple)
+    security_group_ids: Tuple[str, ...] = field(default_factory=tuple)
+    short_timeout_seconds: int = 60
+    default_timeout_seconds: int = 900
+    short_timeout_tokens: Tuple[str, ...] = (
+        "Events",
+        "Data",
+        "Public",
+        "WebHooks",
+    )
+    memory_size_by_token: Mapping[str, int] = field(default_factory=dict)
+    extra_lambda_policy_statements: Tuple[Mapping[str, Any], ...] = field(
+        default_factory=tuple
+    )
+    use_reserved_concurrency: bool = True
+
+    # ── Per-app/stage generated IAM (see policies.app_runtime_statements) ──
+    # SSM read is scoped to /{ssm_project_name}/{stage}/* and /Global/{stage}/*.
+    # ssm_project_name is the runtime ProjectName (e.g. "Donor" for the donors
+    # app); None falls back to the deploy target's app name.
+    ssm_project_name: Optional[str] = None
+    ssm_read_global: bool = True
+    # Extra SSM read prefixes, "{stage}" substituted (e.g. "/Donor/{stage}").
+    extra_ssm_read_prefixes: Tuple[str, ...] = field(default_factory=tuple)
+    # Cognito user pools this app's functions call, per stage ("*" = every
+    # stage): pool ids ("us-east-1_AbC123") or user-pool ARNs.
+    cognito_user_pools: Mapping[str, Tuple[str, ...]] = field(default_factory=dict)
+    # Config keys resolved at deploy time to pool ids
+    # (/{ssm_project_name}/{stage}/{key}, then /Global/{stage}/{key}).
+    cognito_user_pool_config_keys: Tuple[str, ...] = field(default_factory=tuple)
+    # cognito-idp actions granted on those pools. The default is what
+    # velocity's own runtime needs (Context.get_cognito_user).
+    cognito_actions: Tuple[str, ...] = (
+        "cognito-idp:AdminGetUser",
+        "cognito-idp:ListUsers",
+    )
+    # Other queues this app sends to ("{branch}"/"{raw_branch}" substituted).
+    extra_send_queue_templates: Tuple[str, ...] = field(default_factory=tuple)
+    # SNS topic for velocity.aws.failures (the FailureTopicArn config key);
+    # "{stage}", "{region}", "{account}" substituted. Grants sns:Publish.
+    failure_topic_arn: Optional[str] = None
+
+    # ── Work queue (setup_sqs_queue_and_permissions) ──
+    # VisibilityTimeout = clamp(handler timeout x multiplier, 30 s, 12 h).
+    queue_visibility_timeout_multiplier: int = 6
+    queue_dlq_enabled: bool = True
+    queue_dlq_max_receive_count: int = 3
+    queue_batch_size: int = 1
+
+    def resolve_ssm_project_name(self, app_name: str) -> str:
+        return self.ssm_project_name or app_name
+
+    def resolve_cognito_user_pools(self, stage: str) -> Tuple[str, ...]:
+        pools = list(self.cognito_user_pools.get("*", ()))
+        for key in (stage, stage.lower()):
+            for pool in self.cognito_user_pools.get(key, ()):
+                if pool not in pools:
+                    pools.append(pool)
+        return tuple(pools)
+
+    def resolve_send_queue_names(self, stage: str) -> Tuple[str, ...]:
+        return tuple(
+            template.format(branch=stage.lower(), raw_branch=stage)
+            for template in self.extra_send_queue_templates
+        )
+
+    def resolve_queue_name(self, stage: str) -> str:
+        return self.queue_name_template.format(branch=stage.lower(), raw_branch=stage)
+
+    def resolve_timeout(self, function_name: str) -> int:
+        if any(token in function_name for token in self.short_timeout_tokens):
+            return self.short_timeout_seconds
+        return self.default_timeout_seconds
+
+    def resolve_memory_size(self, function_name: str) -> Optional[int]:
+        for token, memory_size in self.memory_size_by_token.items():
+            if token in function_name:
+                return memory_size
+        return None
+
+    def build_lambda_policy_document(
+        self, base_policy_document: Mapping[str, Any]
+    ) -> Dict[str, Any]:
+        """Legacy helper: base document + this config's extra statements.
+
+        The shared-union policy mode it served was removed (no consumer used
+        it); kept for importers. Deployments read
+        extra_lambda_policy_statements directly into the per-app policy.
+        """
+        policy_document = dict(base_policy_document)
+        statements = list(policy_document.get("Statement", []))
+        statements.extend(
+            dict(statement) for statement in self.extra_lambda_policy_statements
+        )
+        policy_document["Statement"] = statements
+        return policy_document
+
+
+# Backwards-compatible name used by existing build.py files.
+BackendDeploymentConfig = DeploymentConfig

{velocity_python-0.1.126 → velocity_python-0.1.129}/src/velocity/aws/deploy/operations.py

@@ -376,6 +376,113 @@ def build_sqs_queue_policy(
     )
 
 
+MAX_VISIBILITY_TIMEOUT_SECONDS = 12 * 60 * 60
+MIN_VISIBILITY_TIMEOUT_SECONDS = 30
+REPORT_BATCH_ITEM_FAILURES = "ReportBatchItemFailures"
+
+
+def queue_visibility_timeout(
+    function_timeout: Optional[int], multiplier: int = 6
+) -> int:
+    """AWS guidance for an SQS event source: visibility timeout of at least
+    six times the function timeout, clamped to [30 s, 12 h]."""
+    seconds = int(function_timeout or 0) * int(multiplier)
+    return max(
+        MIN_VISIBILITY_TIMEOUT_SECONDS, min(seconds, MAX_VISIBILITY_TIMEOUT_SECONDS)
+    )
+
+
+def _queue_url_or_none(sqs_client, queue_name: str) -> Optional[str]:
+    try:
+        return sqs_client.get_queue_url(QueueName=queue_name)["QueueUrl"]
+    except sqs_client.exceptions.QueueDoesNotExist:
+        return None
+
+
+def _ensure_dlq_queue(sqs_client, dlq_name: str, retention_seconds: int) -> str:
+    """Create ``dlq_name`` if missing; return its ARN."""
+    dlq_url = _queue_url_or_none(sqs_client, dlq_name)
+    if dlq_url is None:
+        dlq_url = sqs_client.create_queue(
+            QueueName=dlq_name,
+            Attributes={"MessageRetentionPeriod": str(retention_seconds)},
+        )["QueueUrl"]
+        print(f"[INFO] Created DLQ: {dlq_name}")
+    return sqs_client.get_queue_attributes(
+        QueueUrl=dlq_url, AttributeNames=["QueueArn"]
+    )["Attributes"]["QueueArn"]
+
+
+def _normalized_attribute(name: str, value: Optional[str]) -> Any:
+    if value is None:
+        return None
+    if name in ("Policy", "RedrivePolicy"):
+        try:
+            return json.loads(value)
+        except (TypeError, ValueError):
+            return value
+    return str(value)
+
+
+def ensure_queue_event_source_mapping(
+    lambda_client,
+    *,
+    queue_arn: str,
+    function_name: str,
+    batch_size: int = 1,
+) -> dict:
+    """Create or correct the SQS -> Lambda mapping.
+
+    The mapping must report partial batch failures
+    (``FunctionResponseTypes=["ReportBatchItemFailures"]``), otherwise the
+    handler's ``batchItemFailures`` response is ignored and failed records
+    are deleted as if they succeeded. Existing mappings are updated in place
+    (batch size and response types); ``Enabled`` is left as found. Prints and
+    returns the diff.
+    """
+    mappings = []
+    paginator = lambda_client.get_paginator("list_event_source_mappings")
+    for page in paginator.paginate(
+        EventSourceArn=queue_arn, FunctionName=function_name
+    ):
+        mappings.extend(page.get("EventSourceMappings", []))
+
+    if not mappings:
+        print(
+            f"  + event source mapping {queue_arn.rsplit(':', 1)[-1]} -> {function_name} "
+            f"(BatchSize={batch_size}, FunctionResponseTypes=[{REPORT_BATCH_ITEM_FAILURES}])"
+        )
+        lambda_client.create_event_source_mapping(
+            EventSourceArn=queue_arn,
+            FunctionName=function_name,
+            Enabled=True,
+            BatchSize=batch_size,
+            FunctionResponseTypes=[REPORT_BATCH_ITEM_FAILURES],
+        )
+        return {"created": True, "updated": []}
+
+    updated = []
+    for mapping in mappings:
+        changes = {}
+        response_types = list(mapping.get("FunctionResponseTypes") or [])
+        if REPORT_BATCH_ITEM_FAILURES not in response_types:
+            changes["FunctionResponseTypes"] = response_types + [
+                REPORT_BATCH_ITEM_FAILURES
+            ]
+        if mapping.get("BatchSize") != batch_size:
+            changes["BatchSize"] = batch_size
+        if not changes:
+            continue
+        for key, value in changes.items():
+            print(
+                f"  ~ event source mapping {mapping['UUID']}: {key} "
+                f"{mapping.get(key)!r} -> {value!r}"
+            )
+        lambda_client.update_event_source_mapping(UUID=mapping["UUID"], **changes)
+        updated.append(mapping["UUID"])
+    return {"created": False, "updated": updated}
+
+
 def setup_sqs_queue_and_permissions(
     *,
     account_id: str,
@@ -389,11 +496,28 @@ def setup_sqs_queue_and_permissions(
     sqs_resource=None,
     lambda_client=None,
     policy_json: Optional[str] = None,
-) -> None:
+    function_timeout: Optional[int] = None,
+    visibility_timeout_multiplier: int = 6,
+    dlq_enabled: bool = True,
+    dlq_max_receive_count: int = 3,
+    dlq_retention_seconds: int = 1209600,
+    batch_size: int = 1,
+) -> dict:
+    """Reconcile the work queue, its DLQ and the handler's mapping.
+
+    - DLQ ``{queue_name}-dlq`` created by default, redrive maxReceiveCount 3;
+    - VisibilityTimeout = clamp(handler timeout x 6, 30 s, 12 h) — the
+      handler's ``Timeout`` unless ``function_timeout`` is given;
+    - queue policy scoped to the producer and handler roles;
+    - mapping with ``ReportBatchItemFailures`` (created or corrected).
+
+    The attribute diff is printed. ``sqs_resource`` is accepted for
+    backwards compatibility and unused. Returns
+    ``{"queue_arn", "dlq_arn", "attributes_changed", "mapping"}``.
+    """
+    del sqs_resource
     if sqs_client is None:
         sqs_client = boto3.client("sqs")
-    if sqs_resource is None:
-        sqs_resource = boto3.resource("sqs")
     if lambda_client is None:
         lambda_client = boto3.client("lambda")
 
@@ -401,28 +525,58 @@ def setup_sqs_queue_and_permissions(
         policy_json = build_sqs_queue_policy(
             account_id, region, queue_name, queue_producers, queue_handler
         )
+    if function_timeout is None:
+        function_timeout = queue_handler.get("Timeout") or 900
+    visibility = queue_visibility_timeout(
+        function_timeout, visibility_timeout_multiplier
+    )
 
-    try:
-        queue = sqs_resource.get_queue_by_name(QueueName=queue_name)
-        sqs_client.set_queue_attributes(
-            QueueUrl=queue.url,
-            Attributes={"Policy": policy_json, "VisibilityTimeout": "900"},
+    desired = {"Policy": policy_json, "VisibilityTimeout": str(visibility)}
+    dlq_arn = None
+    if dlq_enabled:
+        dlq_arn = _ensure_dlq_queue(
+            sqs_client, f"{queue_name}-dlq", dlq_retention_seconds
         )
-    except sqs_client.exceptions.QueueDoesNotExist:
-        queue = sqs_resource.create_queue(
-            QueueName=queue_name,
-            Attributes={"Policy": policy_json, "VisibilityTimeout": "900"},
+        desired["RedrivePolicy"] = json.dumps(
+            {"maxReceiveCount": dlq_max_receive_count, "deadLetterTargetArn": dlq_arn}
         )
 
-    try:
-        lambda_client.create_event_source_mapping(
-            EventSourceArn=f"arn:aws:sqs:{region}:{account_id}:{queue_name}",
-            FunctionName=queue_handler["FunctionName"],
-            Enabled=True,
-            BatchSize=1,
-        )
-    except lambda_client.exceptions.ResourceConflictException:
-        pass
+    queue_url = _queue_url_or_none(sqs_client, queue_name)
+    changed = []
+    if queue_url is None:
+        print(f"  + queue {queue_name}: {sorted(desired)}")
+        queue_url = sqs_client.create_queue(QueueName=queue_name, Attributes=desired)[
+            "QueueUrl"
+        ]
+        changed = sorted(desired)
+    else:
+        current = sqs_client.get_queue_attributes(
+            QueueUrl=queue_url, AttributeNames=["All"]
+        ).get("Attributes", {})
+        delta = {
+            name: value
+            for name, value in desired.items()
+            if _normalized_attribute(name, current.get(name))
+            != _normalized_attribute(name, value)
+        }
+        for name in sorted(delta):
+            if name == "Policy":
+                print(f"  ~ queue {queue_name}: Policy updated")
+            else:
+                print(
+                    f"  ~ queue {queue_name}: {name} {current.get(name)!r} -> {delta[name]!r}"
+                )
+        if delta:
+            sqs_client.set_queue_attributes(QueueUrl=queue_url, Attributes=delta)
+        changed = sorted(delta)
+
+    queue_arn = f"arn:aws:sqs:{region}:{account_id}:{queue_name}"
+    mapping = ensure_queue_event_source_mapping(
+        lambda_client,
+        queue_arn=queue_arn,
+        function_name=queue_handler["FunctionName"],
+        batch_size=batch_size,
+    )
 
     if use_reserved_concurrency:
         reserved = 10 if stage == "production" else 3
@@ -443,6 +597,13 @@ def setup_sqs_queue_and_permissions(
         except Exception:
             pass
 
+    return {
+        "queue_arn": queue_arn,
+        "dlq_arn": dlq_arn,
+        "attributes_changed": changed,
+        "mapping": mapping,
+    }
+
 
 def ensure_dlq(
     queue_name: str,
@@ -453,30 +614,18 @@ def ensure_dlq(
 ) -> Optional[str]:
     """Idempotently create `{queue_name}-dlq` and attach a redrive policy to
     the work queue. Returns the DLQ ARN, or None when the main queue is absent.
+
+    ``setup_sqs_queue_and_permissions`` now does this itself by default; this
+    stays for build scripts that call it directly.
     """
     if sqs_client is None:
         sqs_client = boto3.client("sqs")
 
     dlq_name = f"{queue_name}-dlq"
+    dlq_arn = _ensure_dlq_queue(sqs_client, dlq_name, retention_seconds)
 
-    try:
-        dlq_url = sqs_client.get_queue_url(QueueName=dlq_name)["QueueUrl"]
-        print(f"[INFO] DLQ already exists: {dlq_name}")
-    except sqs_client.exceptions.QueueDoesNotExist:
-        resp = sqs_client.create_queue(
-            QueueName=dlq_name,
-            Attributes={"MessageRetentionPeriod": str(retention_seconds)},
-        )
-        dlq_url = resp["QueueUrl"]
-        print(f"[INFO] Created DLQ: {dlq_name}")
-
-    dlq_arn = sqs_client.get_queue_attributes(
-        QueueUrl=dlq_url, AttributeNames=["QueueArn"]
-    )["Attributes"]["QueueArn"]
-
-    try:
-        main_url = sqs_client.get_queue_url(QueueName=queue_name)["QueueUrl"]
-    except sqs_client.exceptions.QueueDoesNotExist:
+    main_url = _queue_url_or_none(sqs_client, queue_name)
+    if main_url is None:
         print(f"[WARN] Main queue {queue_name!r} not found; skipping redrive policy.")
         return None