async-lambda-unstable 0.6.12__tar.gz → 0.6.13__tar.gz

async_lambda_unstable-0.6.12/README.md → async_lambda_unstable-0.6.13/PKG-INFO

@@ -1,3 +1,15 @@
+Metadata-Version: 2.5
+Name: async-lambda-unstable
+Version: 0.6.13
+Summary: A framework for creating AWS Lambda Async Workflows. - Unstable Branch
+Author-email: "Nuclei, Inc" <engineering@nuclei.ai>
+Requires-Dist: click>=8.0.0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: local
+Requires-Dist: boto3; extra == 'local'
+Requires-Dist: flask<3.0.0,>=2.3.0; extra == 'local'
+Description-Content-Type: text/markdown
+
 # async-lambda
 
 Async-lambda is a Python framework for building scalable, event-driven AWS Lambda applications with first-class support for asynchronous invocation via SQS queues. It provides a high-level abstraction for orchestrating Lambda functions, managing event triggers, and handling complex workflows with minimal boilerplate.
@@ -406,6 +418,25 @@ def task(event: ManagedSQSEvent):
         ...
 ```
 
+### Shared Function Role
+
+By default each task declares `Policies`, so SAM generates one `AWS::IAM::Role` per task.
+
+`config_set_shared_function_role()` emits a single `AsyncLambdaSharedFunctionRole` and points every task's `Role` at it instead:
+
+```python
+from async_lambda import config_set_shared_function_role
+
+config_set_shared_function_role()
+```
+
+The shared role carries everything the per-task roles carried, with one difference: SQS consume access is granted on the app's queue-name prefix (`{name}-*`) rather than each task's own queues. Unmanaged SQS queues are still listed individually, since they're named by their producer.
+
+Two caveats:
+
+- A task with task-specific `policies` keeps its own generated role, since the shared role is built from app-wide and stage-wide config only.
+- Every app-wide policy must be either a managed policy ARN or a `{"Statement": [...]}` document. SAM policy templates can't be expressed in a plain IAM role and will fail the build.
+
 ## Known Limitations
 
 - Not all Lambda configuration options are supported (see code for extension points)

async_lambda_unstable-0.6.12/PKG-INFO → async_lambda_unstable-0.6.13/README.md

@@ -1,15 +1,3 @@
-Metadata-Version: 2.4
-Name: async-lambda-unstable
-Version: 0.6.12
-Summary: A framework for creating AWS Lambda Async Workflows. - Unstable Branch
-Author-email: "Nuclei, Inc" <engineering@nuclei.ai>
-Requires-Dist: click>=8.0.0
-Requires-Dist: typing-extensions>=4.0.0
-Provides-Extra: local
-Requires-Dist: boto3; extra == 'local'
-Requires-Dist: flask<3.0.0,>=2.3.0; extra == 'local'
-Description-Content-Type: text/markdown
-
 # async-lambda
 
 Async-lambda is a Python framework for building scalable, event-driven AWS Lambda applications with first-class support for asynchronous invocation via SQS queues. It provides a high-level abstraction for orchestrating Lambda functions, managing event triggers, and handling complex workflows with minimal boilerplate.
@@ -418,6 +406,25 @@ def task(event: ManagedSQSEvent):
         ...
 ```
 
+### Shared Function Role
+
+By default each task declares `Policies`, so SAM generates one `AWS::IAM::Role` per task.
+
+`config_set_shared_function_role()` emits a single `AsyncLambdaSharedFunctionRole` and points every task's `Role` at it instead:
+
+```python
+from async_lambda import config_set_shared_function_role
+
+config_set_shared_function_role()
+```
+
+The shared role carries everything the per-task roles carried, with one difference: SQS consume access is granted on the app's queue-name prefix (`{name}-*`) rather than each task's own queues. Unmanaged SQS queues are still listed individually, since they're named by their producer.
+
+Two caveats:
+
+- A task with task-specific `policies` keeps its own generated role, since the shared role is built from app-wide and stage-wide config only.
+- Every app-wide policy must be either a managed policy ARN or a `{"Statement": [...]}` document. SAM policy templates can't be expressed in a plain IAM role and will fail the build.
+
 ## Known Limitations
 
 - Not all Lambda configuration options are supported (see code for extension points)

{async_lambda_unstable-0.6.12 → async_lambda_unstable-0.6.13}/async_lambda/__init__.py

@@ -2,6 +2,7 @@ from .config import config_set_default_task_memory as config_set_default_task_me
 from .config import config_set_name as config_set_name
 from .config import config_set_runtime as config_set_runtime
 from .config import config_set_s3_payload_retention as config_set_s3_payload_retention
+from .config import config_set_shared_function_role as config_set_shared_function_role
 from .controller import AsyncLambdaController as AsyncLambdaController
 from .controller import BatchInvokeException as BatchInvokeException
 from .defer import Defer as Defer
@@ -21,4 +22,4 @@ from .models.events.managed_sqs_event import ManagedSQSEvent as ManagedSQSEvent
 from .models.events.scheduled_event import ScheduledEvent as ScheduledEvent
 from .models.events.unmanaged_sqs_event import UnmanagedSQSEvent as UnmanagedSQSEvent
 
-__version__ = "0.6.12"
+__version__ = "0.6.13"

{async_lambda_unstable-0.6.12 → async_lambda_unstable-0.6.13}/async_lambda/config.py

@@ -11,6 +11,7 @@ class AsyncLambdaConfig:
         s3_payload_retention (int): Days to retain payloads in S3. Defaults to 30.
         default_task_memory (int): Default memory allocation (MB) for tasks. Defaults to 128.
         default_task_ephemeral_storage (int): Default disk allocation (MB) for tasks. Defaults to 512.
+        shared_function_role (bool): Whether tasks share a single execution role. Defaults to False.
     """
 
     name: str = "async-lambda"
@@ -18,6 +19,7 @@ class AsyncLambdaConfig:
     s3_payload_retention: Optional[int] = 180
     default_task_memory: int = 128
     default_task_ephemeral_storage: int = 512
+    shared_function_role: bool = False
 
 
 config = AsyncLambdaConfig()
@@ -71,3 +73,19 @@ def config_set_default_task_ephemeral_storage(ephemeral_storage: int = 512):
         ephemeral_storage (int, optional): Disk storage in megabytes to set as default for tasks. Defaults to 512.
     """
     config.default_task_ephemeral_storage = ephemeral_storage
+
+
+def config_set_shared_function_role(enabled: bool = True):
+    """
+    Use a single execution role for every task instead of one role per task.
+
+    SAM generates an IAM role per function when a function declares `Policies`. Sharing one
+    role trades per-task SQS scoping (the shared role can consume any of the app's own queues)
+    for one CloudFormation resource instead of one per task.
+
+    Tasks with task-specific `policies` keep their own role.
+
+    Args:
+        enabled (bool, optional): Whether to share a single execution role. Defaults to True.
+    """
+    config.shared_function_role = enabled

{async_lambda_unstable-0.6.12 → async_lambda_unstable-0.6.13}/async_lambda/controller.py

@@ -20,7 +20,7 @@ from typing import (
 from uuid import uuid4
 
 from . import env
-from .build_config import get_build_config_for_stage
+from .build_config import AsyncLambdaBuildConfig, get_build_config_for_stage
 from .client import get_s3_client, get_scheduler_client, get_sqs_client
 from .config import config
 from .middleware import MET, RT, MiddlewareFunction, MiddlewareRegistration
@@ -33,7 +33,12 @@ from .models.events.scheduled_event import ScheduledEvent
 from .models.events.unmanaged_sqs_event import UnmanagedSQSEvent
 from .models.mock.mock_context import MockLambdaContext
 from .models.mock.mock_event import MockSQSLambdaEvent
-from .models.task import MANAGED_SQS_TASK_TYPES, AsyncLambdaTask, TaskTriggerType
+from .models.task import (
+    MANAGED_SQS_TASK_TYPES,
+    SHARED_FUNCTION_ROLE_LOGICAL_ID,
+    AsyncLambdaTask,
+    TaskTriggerType,
+)
 from .payload_encoder import PayloadEncoder
 from .util import make_cf_tags
 
@@ -180,32 +185,26 @@ class AsyncLambdaController:
         self.delete_s3_payloads = delete_s3_payloads
         self.controller_name = controller_name
 
-    # itertools.batched is much cleaner but only available in python 3.12+
-    @staticmethod
-    def _batched(items: Sequence[dict], batch_size: int) -> List[List[dict]]:
-        if batch_size <= 0:
-            raise ValueError("batch_size must be greater than 0")
-        return [
-            list(items[i : i + batch_size]) for i in range(0, len(items), batch_size)
-        ]
-
     @classmethod
     def _build_send_to_all_async_lambda_queues_policies(
         cls,
-        managed_tasks_resources: List[dict],
-        policy_batch_size: int = 30,
+        queue_resources: List[dict],
     ) -> Dict[str, dict]:
-        task_ref_policies: Dict[str, dict] = {}
-        for chunk_index, resource_chunk in enumerate(
-            cls._batched(items=managed_tasks_resources, batch_size=policy_batch_size),
-            start=0,
-        ):
-            policy_id = f"SendToAllAsyncLambdaQueuesPolicy{chunk_index}"
-            task_ref_policies[policy_id] = {
+        """
+        Builds the managed policy granting send access to every managed queue in this app.
+
+        This app's own queues are covered by a single name-prefix wildcard rather than an
+        enumeration, so the policy stays one resource and one document regardless of task
+        count. External tasks don't share the prefix, so their ARNs are listed explicitly.
+        """
+        if len(queue_resources) == 0:
+            return {}
+        return {
+            "SendToAllAsyncLambdaQueuesPolicy": {
                 "Type": "AWS::IAM::ManagedPolicy",
                 "Properties": {
                     "ManagedPolicyName": {
-                        "Fn::Sub": f"${{AWS::StackName}}-send-to-all-queues-{chunk_index}"
+                        "Fn::Sub": "${AWS::StackName}-send-to-all-queues"
                     },
                     "PolicyDocument": {
                         "Version": "2012-10-17",
@@ -214,13 +213,142 @@ class AsyncLambdaController:
                                 "Sid": "SendToAllQueues",
                                 "Effect": "Allow",
                                 "Action": ["sqs:SendMessage"],
-                                "Resource": resource_chunk,
+                                "Resource": queue_resources,
                             },
                         ],
                     },
                 },
             }
-        return task_ref_policies
+        }
+
+    @staticmethod
+    def _managed_queue_arn_wildcard() -> dict:
+        """
+        An ARN pattern matching every managed queue this app creates.
+        """
+        return {
+            "Fn::Sub": "arn:aws:sqs:${AWS::Region}:${AWS::AccountId}:"
+            + f"{config.name}-*"
+        }
+
+    @classmethod
+    def _build_shared_function_role(
+        cls,
+        task_list: List[AsyncLambdaTask],
+        build_config: AsyncLambdaBuildConfig,
+        task_ref_policy_ids: List[str],
+    ) -> dict:
+        """
+        Builds a single execution role shared by every task.
+        """
+        sqs_resources: List[Union[str, dict]] = []
+        if any(task.trigger_type in MANAGED_SQS_TASK_TYPES for task in task_list):
+            sqs_resources.append(cls._managed_queue_arn_wildcard())
+        # Unmanaged queues are named by whoever produces to them, so they fall outside the
+        # app-name prefix and have to be listed.
+        sqs_resources.extend(
+            resource
+            for task in task_list
+            if task.trigger_type == TaskTriggerType.UNMANAGED_SQS
+            for resource in task.get_policy_sqs_resources()
+        )
+
+        statements: List[dict] = [
+            {
+                "Effect": "Allow",
+                "Action": ["s3:DeleteObject", "s3:PutObject", "s3:GetObject"],
+                "Resource": {
+                    "Fn::Join": [
+                        "",
+                        [
+                            "arn:aws:s3:::",
+                            {"Ref": "AsyncLambdaPayloadBucket"},
+                            "/*",
+                        ],
+                    ]
+                },
+            },
+        ]
+        if len(sqs_resources) > 0:
+            statements.append(
+                {
+                    "Effect": "Allow",
+                    "Action": [
+                        "sqs:ChangeMessageVisibility",
+                        "sqs:DeleteMessage",
+                        "sqs:GetQueueAttributes",
+                        "sqs:GetQueueUrl",
+                        "sqs:ReceiveMessage",
+                    ],
+                    "Resource": sqs_resources,
+                }
+            )
+
+        inline_policies: List[dict] = [
+            {
+                "PolicyName": "AsyncLambdaTaskPolicy",
+                "PolicyDocument": {
+                    "Version": "2012-10-17",
+                    "Statement": statements,
+                },
+            }
+        ]
+        managed_policy_arns: List[Union[str, dict]] = [
+            "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
+        ]
+        if "VpcConfig" in build_config.function_properties:
+            managed_policy_arns.append(
+                "arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole"
+            )
+        # SAM attaches this to any lambda function with an SQS event source. Without it, they
+        # lose their SQS polling permissions.
+        if len(sqs_resources) > 0:
+            managed_policy_arns.append(
+                "arn:aws:iam::aws:policy/service-role/AWSLambdaSQSQueueExecutionRole"
+            )
+
+        for index, policy in enumerate(build_config.policies):
+            if isinstance(policy, str):
+                managed_policy_arns.append(policy)
+            elif isinstance(policy, dict) and set(policy.keys()) == {"Statement"}:
+                inline_policies.append(
+                    {
+                        "PolicyName": f"AsyncLambdaBuildConfigPolicy{index}",
+                        "PolicyDocument": {
+                            "Version": "2012-10-17",
+                            "Statement": policy["Statement"],
+                        },
+                    }
+                )
+            else:
+                raise Exception(
+                    f"Unable to build a shared function role. The policy {policy!r} is "
+                    "neither a managed policy ARN nor a single-key 'Statement' document."
+                    "SAM policy templates cannot be expressed in a plain IAM role."
+                    "Rewrite the policy in one of those two forms, or turn off config_set_shared_function_role."
+                )
+
+        managed_policy_arns.extend(
+            {"Ref": policy_id} for policy_id in task_ref_policy_ids
+        )
+
+        return {
+            "Type": "AWS::IAM::Role",
+            "Properties": {
+                "AssumeRolePolicyDocument": {
+                    "Version": "2012-10-17",
+                    "Statement": [
+                        {
+                            "Effect": "Allow",
+                            "Principal": {"Service": ["lambda.amazonaws.com"]},
+                            "Action": ["sts:AssumeRole"],
+                        }
+                    ],
+                },
+                "ManagedPolicyArns": managed_policy_arns,
+                "Policies": inline_policies,
+            },
+        }
 
     def add_middleware(
         self, event_types: List[Type[BaseEvent]], func: MiddlewareFunction[MET, RT]
@@ -525,22 +653,20 @@ class AsyncLambdaController:
             },
         }
         _task_list = list(self.tasks.values())
-        managed_tasks_resources = [
-            resource
-            for task in _task_list
-            if task.trigger_type in MANAGED_SQS_TASK_TYPES
-            for resource in task.get_policy_sqs_resources()
-        ] + [
+        send_all_queue_resources: List[dict] = []
+        if any(task.trigger_type in MANAGED_SQS_TASK_TYPES for task in _task_list):
+            send_all_queue_resources.append(self._managed_queue_arn_wildcard())
+        send_all_queue_resources.extend(
             resource
             for external_async_task_id in self.external_async_tasks
             for resource in AsyncLambdaTask.get_policy_external_task_resources(
                 external_async_task_id
             )
-        ]
+        )
 
         send_all_queues_task_ref_policies = (
             self._build_send_to_all_async_lambda_queues_policies(
-                managed_tasks_resources
+                send_all_queue_resources
             )
         )
         for key in send_all_queues_task_ref_policies.keys():
@@ -593,6 +719,15 @@ class AsyncLambdaController:
             ],
         }
 
+        if config.shared_function_role:
+            template["Resources"][SHARED_FUNCTION_ROLE_LOGICAL_ID] = (
+                self._build_shared_function_role(
+                    task_list=_task_list,
+                    build_config=build_config,
+                    task_ref_policy_ids=list(task_ref_policies.keys()),
+                )
+            )
+
         has_api_tasks = False
         for task in _task_list:
             if task.trigger_type == TaskTriggerType.API_EVENT:

{async_lambda_unstable-0.6.12 → async_lambda_unstable-0.6.13}/async_lambda/models/task.py

@@ -57,6 +57,8 @@ MANAGED_SQS_TASK_TYPES = {
     TaskTriggerType.MANAGED_SQS_BATCH,
 }
 
+SHARED_FUNCTION_ROLE_LOGICAL_ID = "AsyncLambdaSharedFunctionRole"
+
 EventType = TypeVar(
     "EventType",
     bound=Union[
@@ -610,23 +612,32 @@ class AsyncLambdaTask(Generic[EventType, RT]):
             *[{"Ref": policy_id} for policy_id in task_ref_policy_ids],
         ]
 
+        function_properties = {
+            "Environment": {
+                "Variables": {
+                    "ASYNC_LAMBDA_TASK_ID": self.task_id,
+                    **override_config.environment_variables,
+                }
+            },
+            "FunctionName": self.get_function_name(),
+            "Timeout": self.timeout,
+            "Events": events,
+            "CodeUri": ".async_lambda/build/deployment.zip",
+        }
+
+        # cannot use shared role if the task has its own policies
+        if config.shared_function_role and len(override_config.policies) == 0:
+            function_properties["Role"] = {
+                "Fn::GetAtt": [SHARED_FUNCTION_ROLE_LOGICAL_ID, "Arn"]
+            }
+        else:
+            function_properties["Policies"] = policies
+        function_properties.update(override_config.function_properties)
+
         template = {
             self.get_function_logical_id(): {
                 "Type": "AWS::Serverless::Function",
-                "Properties": {
-                    "Environment": {
-                        "Variables": {
-                            "ASYNC_LAMBDA_TASK_ID": self.task_id,
-                            **override_config.environment_variables,
-                        }
-                    },
-                    "FunctionName": self.get_function_name(),
-                    "Timeout": self.timeout,
-                    "Events": events,
-                    "Policies": policies,
-                    "CodeUri": ".async_lambda/build/deployment.zip",
-                    **override_config.function_properties,
-                },
+                "Properties": function_properties,
             }
         }
         if self.memory is not None: