Limitations

The following boundaries are confirmed by the current implementation or its tests. They describe observable behavior, not a promise that the behavior is intentional or permanent.

Source discovery and AST analysis

The CDK package scans Python files below lambda_path, parses them with Python's AST, and inspects only top-level synchronous def functions. Nested functions, classes, async def, and files without a recognized route decorator are not discovered as Lambda handlers.

Route and configuration values needed during discovery must be literals. For example, @GET("/items") is resolvable, while a path or decorator argument calculated from a variable, function call, or expanded keyword mapping cannot be resolved statically and raises a validation error or is not recognized. The recognized route decorators are direct names: GET, POST, PUT, DELETE, and ANY. The source layout guide contains the discovery and naming rules.

HTTP methods and API families

REST routes support GET, POST, PUT, DELETE, and ANY. HTTP routes currently support the first four through the complete discovery path. Although the HTTP emission table contains PATCH, OPTIONS, and HEAD, the source parser does not discover decorators for them. ANY has no HTTP mapping and fails when used with an HTTP LambdaApi.

The API family must match the CDK object supplied to LambdaApi. REST APIs use aws_apigateway authorizers and HTTP APIs use aws_apigatewayv2 route authorizers; a registered authorizer from the wrong family is rejected. A concrete apigatewayv2.HttpApi can be reused, but an HTTP API returned by HttpApi.from_http_api_attributes is currently rejected because the wrapper checks for the concrete class. See Using an existing API.

Packaging and source layouts

SourceLayout.ROOT packages handlers relative to the lambda_path root. SourceLayout.SERVICE requires every handler to be below a first-level service directory; a Python file directly under lambda_path raises ValueError. Both layouts are passed to CDK's PythonFunction, so handler directories and module filenames need normal importable Python names. The source layout is not a mechanism for packaging arbitrary non-Python layouts.

When layers_path is used, only visible child directories are considered for autodiscovered layers. Autodiscovered layers require a concrete Python Lambda runtime, and explicit layers are checked against their declared compatible runtimes. Lambda source and these layers are packaged through Docker by CDK. Without Docker available, synthesis or the corresponding infrastructure tests cannot complete; the example tests skip with that reason when Docker is unavailable. See Layers and Source layouts.

Roles, permissions, and authorizers

The decorators record configuration; the CDK package resolves the referenced roles, VPCs, layers, security groups, environments, DynamoDB tables, S3 buckets, and authorizers from its registries. A missing logical key is an error. If no default authorizer is configured, routes without an explicit authorizer are public and CDK emits a diagnostic warning. @public overrides a default authorizer, while @authorizer("key") selects a registered key.

current_user(event) is not an authentication or authorization mechanism. It only reads claims already placed in a supported API Gateway authorizer context: REST claims or HTTP API JWT claims. A non-empty sub claim is required; missing or malformed context raises CurrentUserError. The helper returns a read-only claims snapshot and does not validate tokens or permissions. See the identity API reference and permissions API reference.

Resources and event sources

The current builder creates Lambda functions, API Gateway routes and integrations, and the configured Lambda-related resources described by its registries. It has explicit convenience support for DynamoDB and S3 grants, but no current discovery or builder API for arbitrary Lambda event sources such as queues, streams, schedules, or event buses. Those integrations must be created separately in the surrounding CDK application. This project also does not claim support for non-AWS providers or non-CDK IaC backends; those are outside the current implementation scope described in Status and roadmap.