async-lambda-unstable 0.6.14__tar.gz → 0.6.16__tar.gz

{async_lambda_unstable-0.6.14 → async_lambda_unstable-0.6.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: async-lambda-unstable
-Version: 0.6.14
+Version: 0.6.16
 Summary: A framework for creating AWS Lambda Async Workflows. - Unstable Branch
 Author-email: "Nuclei, Inc" <engineering@nuclei.ai>
 Requires-Dist: click>=8.0.0
@@ -249,6 +249,38 @@ and merging is done thru concatenation.
 
 [The value is passed to the `Layers` property on `SAM::Serverless::Function`](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html#sam-function-layers)
 
+### image_uri
+
+```
+"ACCOUNT.dkr.ecr.REGION.amazonaws.com/REPOSITORY:TAG"
+```
+
+Package the functions as a Lambda container image instead of a zip bundle, which raises the
+package size limit from 250 MB (unzipped) to 10 GB.
+
+When set, every function gets `PackageType: Image`, `ImageUri`, and `ImageConfig.Command` set to
+`<module>.lambda_handler` in place of `CodeUri`, `Handler`, and `Runtime`, and `async-lambda build`
+writes only the template (no `deployment.zip`). The image is built and pushed separately; it must
+be based on an AWS Lambda Python base image (or implement the Lambda runtime interface) and contain
+the app module, `src/`, and its dependencies.
+
+`async-lambda build app --image-uri <uri>` sets this for a single build, overriding the config (including
+stage-level values), so a CI pipeline can pin the image it just pushed.
+
+Image functions are named `<name>-<task_id>-image`. Lambda cannot change an existing function's package
+type, so adding or removing `image_uri` replaces each function, and CloudFormation cannot replace a
+function under the same custom name. The suffix lets the new function be created before the old one is
+deleted, so switching needs no manual deletion or downtime. Queue and schedule names are unchanged.
+
+Lambda layers are not supported on container images, so `layers` raises an error at build time when
+`image_uri` is set. SnapStart (`snap_start=True`) is supported on container images that use an AWS
+base image for Python 3.12+, Java 11+, or .NET 8+.
+
+SnapStart only applies to published versions, never `$LATEST`. A task with `snap_start=True` sets
+`AutoPublishAlias: live` and `AutoPublishAliasAllProperties: true`, so each deploy that changes any
+function property (such as `Timeout` or `EphemeralStorage`) publishes a version. SAM points the task's event sources
+(API Gateway, SQS, schedules) at the `live` alias. This works for ZIP and image functions.
+
 ### subnet_ids
 
 ```

{async_lambda_unstable-0.6.14 → async_lambda_unstable-0.6.16}/README.md

@@ -237,6 +237,38 @@ and merging is done thru concatenation.
 
 [The value is passed to the `Layers` property on `SAM::Serverless::Function`](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html#sam-function-layers)
 
+### image_uri
+
+```
+"ACCOUNT.dkr.ecr.REGION.amazonaws.com/REPOSITORY:TAG"
+```
+
+Package the functions as a Lambda container image instead of a zip bundle, which raises the
+package size limit from 250 MB (unzipped) to 10 GB.
+
+When set, every function gets `PackageType: Image`, `ImageUri`, and `ImageConfig.Command` set to
+`<module>.lambda_handler` in place of `CodeUri`, `Handler`, and `Runtime`, and `async-lambda build`
+writes only the template (no `deployment.zip`). The image is built and pushed separately; it must
+be based on an AWS Lambda Python base image (or implement the Lambda runtime interface) and contain
+the app module, `src/`, and its dependencies.
+
+`async-lambda build app --image-uri <uri>` sets this for a single build, overriding the config (including
+stage-level values), so a CI pipeline can pin the image it just pushed.
+
+Image functions are named `<name>-<task_id>-image`. Lambda cannot change an existing function's package
+type, so adding or removing `image_uri` replaces each function, and CloudFormation cannot replace a
+function under the same custom name. The suffix lets the new function be created before the old one is
+deleted, so switching needs no manual deletion or downtime. Queue and schedule names are unchanged.
+
+Lambda layers are not supported on container images, so `layers` raises an error at build time when
+`image_uri` is set. SnapStart (`snap_start=True`) is supported on container images that use an AWS
+base image for Python 3.12+, Java 11+, or .NET 8+.
+
+SnapStart only applies to published versions, never `$LATEST`. A task with `snap_start=True` sets
+`AutoPublishAlias: live` and `AutoPublishAliasAllProperties: true`, so each deploy that changes any
+function property (such as `Timeout` or `EphemeralStorage`) publishes a version. SAM points the task's event sources
+(API Gateway, SQS, schedules) at the `live` alias. This works for ZIP and image functions.
+
 ### subnet_ids
 
 ```

{async_lambda_unstable-0.6.14 → async_lambda_unstable-0.6.16}/async_lambda/__init__.py

@@ -22,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.14"
+__version__ = "0.6.16"

{async_lambda_unstable-0.6.14 → async_lambda_unstable-0.6.16}/async_lambda/build_config.py

@@ -75,6 +75,7 @@ class AsyncLambdaBuildConfig:
         certificate_arn (Optional[str]): ARN of the SSL certificate for the domain.
         hosted_zone_id (Optional[str]): Hosted zone name for the Lambda/API.
         auto_create_acm_certificate (bool): Whether or not to auto create a certificate in ACM for the domain name. Must be used in conjunction with hosted_zone_id and domain_name to be used.
+        image_uri (Optional[str]): URI of a Lambda container image. When set, functions are packaged as container images instead of a zip bundle.
 
     Methods:
         new(config: dict) -> AsyncLambdaBuildConfig:
@@ -99,6 +100,7 @@ class AsyncLambdaBuildConfig:
     hosted_zone_id: Optional[str] = None
     auto_create_acm_certificate: Optional[bool] = None
     queue_age_alarm: Optional[QueueAgeAlarmConfig] = None
+    image_uri: Optional[str] = None
 
     @classmethod
     def new(cls, config: dict) -> "AsyncLambdaBuildConfig":
@@ -121,6 +123,7 @@ class AsyncLambdaBuildConfig:
                 - tls_version (str, optional): TLS version to use.
                 - certificate_arn (str, optional): ARN of the SSL certificate.
                 - hosted_zone_id (str, optional): Hosted zone ID for the Lambda/API.
+                - image_uri (str, optional): URI of the Lambda container image.
 
         Returns:
             AsyncLambdaBuildConfig: A new instance configured with the provided options.
@@ -145,6 +148,7 @@ class AsyncLambdaBuildConfig:
             certificate_arn=config.get("certificate_arn"),
             hosted_zone_id=config.get("hosted_zone_id"),
             auto_create_acm_certificate=config.get("auto_create_acm_certificate"),
+            image_uri=config.get("image_uri"),
         )
 
     def merge(self, other: "AsyncLambdaBuildConfig"):
@@ -168,6 +172,8 @@ class AsyncLambdaBuildConfig:
             self.auto_create_acm_certificate = other.auto_create_acm_certificate
         if other.queue_age_alarm is not None:
             self.queue_age_alarm = other.queue_age_alarm
+        if other.image_uri is not None:
+            self.image_uri = other.image_uri
 
     @property
     def function_properties(self):

{async_lambda_unstable-0.6.14 → async_lambda_unstable-0.6.16}/async_lambda/cli.py

@@ -108,8 +108,16 @@ def import_module_get_controller(module_name: str, config, stage: Optional[str])
 @click.option(
     "-e", "--extras", help="The path to a json file to merge the output template with."
 )
+@click.option(
+    "--image-uri",
+    help="Package the functions as this Lambda container image instead of a zip bundle. Overrides `image_uri` in the config.",
+)
 def build(
-    module: str, output: str, stage: Optional[str] = None, extras: Optional[str] = None
+    module: str,
+    output: str,
+    stage: Optional[str] = None,
+    extras: Optional[str] = None,
+    image_uri: Optional[str] = None,
 ):
     """
     Builds/generates the SAM template for the given module.
@@ -119,6 +127,10 @@ def build(
     config_file = dir.joinpath(".async_lambda/config.json")
     if config_file.exists():
         config = json.loads(config_file.read_bytes())
+    if image_uri is not None:
+        config["image_uri"] = image_uri
+        for stage_config in config.get("stages", {}).values():
+            stage_config.pop("image_uri", None)
     controller = import_module_get_controller(
         module_name=module, config=config, stage=stage
     )
@@ -157,6 +169,11 @@ def build(
 
     if os.path.exists(".async_lambda/build"):
         shutil.rmtree(".async_lambda/build")
+
+    if get_build_config_for_stage(config, stage).image_uri is not None:
+        click.echo("Container image configured, skipping zip bundle.")
+        return
+
     os.makedirs(".async_lambda/build/packages", exist_ok=True)
 
     if dir.joinpath("requirements.txt").exists():

{async_lambda_unstable-0.6.14 → async_lambda_unstable-0.6.16}/async_lambda/controller.py

@@ -620,6 +620,20 @@ class AsyncLambdaController:
         Generates the SAM Template for this project.
         """
         build_config = get_build_config_for_stage(config_dict, stage)
+        if build_config.image_uri is not None and len(build_config.layers) > 0:
+            raise Exception(
+                "Lambda layers cannot be used with container images (image_uri is set)."
+            )
+        # SAM Globals does not accept PackageType or ImageConfig, so image functions
+        # carry their package properties individually (see AsyncLambdaTask.get_sam_template).
+        package_properties = (
+            {}
+            if build_config.image_uri is not None
+            else {
+                "Handler": f"{module}.lambda_handler",
+                "Runtime": config.runtime,
+            }
+        )
         s3_bucket_properties = {}
         if config.s3_payload_retention:
             s3_bucket_properties["LifecycleConfiguration"] = {
@@ -638,8 +652,7 @@ class AsyncLambdaController:
             "Globals": {
                 "Function": {
                     "Tags": build_config.tags,
-                    "Handler": f"{module}.lambda_handler",
-                    "Runtime": config.runtime,
+                    **package_properties,
                     "Environment": {
                         "Variables": {
                             "ASYNC_LAMBDA_PAYLOAD_S3_BUCKET": {
@@ -829,6 +842,7 @@ class AsyncLambdaController:
                 task_ref_policy_ids=list(task_ref_policies.keys()),
                 config_dict=config_dict,
                 stage=stage,
+                module=module,
             ).items():
                 template["Resources"][logical_id] = resource
 

{async_lambda_unstable-0.6.14 → async_lambda_unstable-0.6.16}/async_lambda/models/task.py

@@ -14,7 +14,11 @@ from typing import (
 )
 
 from .. import env
-from ..build_config import get_build_config_for_task, get_override_build_config_for_task
+from ..build_config import (
+    get_build_config_for_stage,
+    get_build_config_for_task,
+    get_override_build_config_for_task,
+)
 from ..config import config
 from ..util import make_cf_tags
 
@@ -28,6 +32,8 @@ from .events.managed_sqs_event import ManagedSQSEvent
 from .events.scheduled_event import ScheduledEvent
 from .events.unmanaged_sqs_event import UnmanagedSQSEvent
 
+IMAGE_FUNCTION_NAME_SUFFIX = "-image"
+
 
 class TaskTriggerType(Enum):
     """
@@ -548,6 +554,7 @@ class AsyncLambdaTask(Generic[EventType, RT]):
         task_ref_policy_ids: List[str],
         config_dict: dict,
         stage: Optional[str] = None,
+        module: Optional[str] = None,
     ) -> dict:
         """
         Generate an AWS SAM (Serverless Application Model) template for the current async lambda task.
@@ -568,6 +575,19 @@ class AsyncLambdaTask(Generic[EventType, RT]):
         override_config = get_override_build_config_for_task(
             config=config_dict, task_id=self.task_id, stage=stage
         )
+        if override_config.image_uri is not None:
+            raise Exception(
+                f"Task {self.task_id}: image_uri can only be set at the app or stage level, "
+                "because every task is packaged the same way."
+            )
+        image_uri = get_build_config_for_stage(config_dict, stage).image_uri
+        if image_uri is not None:
+            if len(build_config.layers) > 0:
+                raise Exception(
+                    f"Task {self.task_id}: Lambda layers cannot be used with container images (image_uri is set)."
+                )
+            if module is None:
+                raise Exception("A module name is required to build image functions.")
         events = self.get_template_events()
         policy_sqs_resources = self.get_policy_sqs_resources()
 
@@ -622,8 +642,20 @@ class AsyncLambdaTask(Generic[EventType, RT]):
             "FunctionName": self.get_function_name(),
             "Timeout": self.timeout,
             "Events": events,
-            "CodeUri": ".async_lambda/build/deployment.zip",
         }
+        if image_uri is not None:
+            # Lambda cannot change a function's package type in place, so switching between zip
+            # and image replaces the function, and a replacement cannot reuse the old name.
+            function_properties["FunctionName"] = (
+                f"{self.get_function_name()}{IMAGE_FUNCTION_NAME_SUFFIX}"
+            )
+            function_properties["PackageType"] = "Image"
+            function_properties["ImageUri"] = image_uri
+            function_properties["ImageConfig"] = {
+                "Command": [f"{module}.lambda_handler"]
+            }
+        else:
+            function_properties["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:
@@ -652,6 +684,12 @@ class AsyncLambdaTask(Generic[EventType, RT]):
             template[self.get_function_logical_id()]["Properties"]["SnapStart"] = {
                 "ApplyOn": "PublishedVersions"
             }
+            template[self.get_function_logical_id()]["Properties"][
+                "AutoPublishAlias"
+            ] = "live"
+            template[self.get_function_logical_id()]["Properties"][
+                "AutoPublishAliasAllProperties"
+            ] = True
 
         if self.trigger_type in MANAGED_SQS_TASK_TYPES:
             dlq_task = self.get_dlq_task()