feat: scaffolding for improved pass-throughs in schema

samtranslator/internal/schema_source/aws_serverless_function.py

@@ -13,6 +13,7 @@
     ResourceAttributes,
     SamIntrinsicable,
     get_prop,
+    passthrough_prop,
 )
 
 alexaskilleventproperties = get_prop("sam-property-function-alexaskill")
@@ -501,8 +502,8 @@ class Properties(BaseModel):
     DeadLetterQueue: Optional[DeadLetterQueueType] = prop("DeadLetterQueue")
     DeploymentPreference: Optional[DeploymentPreference] = prop("DeploymentPreference")
     Description: Optional[Description] = prop("Description")
-    Environment: Optional[Environment] = prop("Environment")
-    EphemeralStorage: Optional[EphemeralStorage] = prop("EphemeralStorage")
+    Environment: Optional[Environment] = passthrough_prop("AWS::Lambda::Function", "Environment")
+    EphemeralStorage: Optional[EphemeralStorage] = passthrough_prop("AWS::Lambda::Function", "EphemeralStorage")
     EventInvokeConfig: Optional[EventInvokeConfig] = prop("EventInvokeConfig")
     Events: Optional[
         Dict[
@@ -531,7 +532,7 @@ class Properties(BaseModel):
         ]
     ] = prop("Events")
     FileSystemConfigs: Optional[PassThroughProp] = prop("FileSystemConfigs")
-    FunctionName: Optional[PassThroughProp] = prop("FunctionName")
+    FunctionName: Optional[PassThroughProp] = passthrough_prop("AWS::Lambda::Function", "FunctionName")
     FunctionUrlConfig: Optional[FunctionUrlConfig] = prop("FunctionUrlConfig")
     Handler: Optional[Handler] = prop("Handler")
     ImageConfig: Optional[PassThroughProp] = prop("ImageConfig")
@@ -566,7 +567,7 @@ class Globals(BaseModel):
     MemorySize: Optional[MemorySize] = prop("MemorySize")
     Timeout: Optional[Timeout] = prop("Timeout")
     VpcConfig: Optional[VpcConfig] = prop("VpcConfig")
-    Environment: Optional[Environment] = prop("Environment")
+    Environment: Optional[Environment] = passthrough_prop("AWS::Lambda::Function", "Environment")
     Tags: Optional[Tags] = prop("Tags")
     Tracing: Optional[Tracing] = prop("Tracing")
     KmsKeyArn: Optional[KmsKeyArn] = prop("KmsKeyArn")
@@ -580,7 +581,7 @@ class Globals(BaseModel):
     AssumeRolePolicyDocument: Optional[AssumeRolePolicyDocument] = prop("AssumeRolePolicyDocument")
     EventInvokeConfig: Optional[EventInvokeConfig] = prop("EventInvokeConfig")
     Architectures: Optional[Architectures] = prop("Architectures")
-    EphemeralStorage: Optional[EphemeralStorage] = prop("EphemeralStorage")
+    EphemeralStorage: Optional[EphemeralStorage] = passthrough_prop("AWS::Lambda::Function", "EphemeralStorage")
     SnapStart: Optional[SnapStart] = prop("SnapStart")
     RuntimeManagementConfig: Optional[RuntimeManagementConfig] = prop("RuntimeManagementConfig")
 

samtranslator/internal/schema_source/common.py

@@ -40,6 +40,19 @@ def get_prop(stem: str) -> Any:
     return partial(_get_prop, stem)
 
 
+def passthrough_prop(resource_type: str, path: str) -> Any:
+    """
+    Specifies a pass-through field, where resource_type is the CloudFormation
+    resource type, and path is a `.`-delimitated path to the property.
+    """
+    prop_path = f"definitions.{resource_type}.properties.Properties.properties.{path}"
+    return Field(
+        # We add a custom value to the schema containing the path to the pass-through
+        # documentation; the dict containing the value is replaced in the final schema
+        __samPassThroughPath=prop_path,
+    )
+
+
 def _get_prop(stem: str, name: str) -> Any:
     docs = _DOCS["properties"][stem][name]
     return Field(

samtranslator/internal/schema_source/schema.py

@@ -3,7 +3,7 @@
 import argparse
 import json
 from pathlib import Path
-from typing import Any, Dict, Optional, Type, Union
+from typing import Any, Callable, Dict, Optional, Type, Union
 
 import pydantic
 
@@ -79,6 +79,30 @@ def json_dumps(obj: Any) -> str:
     return json.dumps(obj, indent=2, sort_keys=True) + "\n"
 
 
+def _replace_in_dict(d: Dict[str, Any], keyword: str, replace: Callable[[Dict[str, Any]], Any]) -> Dict[str, Any]:
+    """
+    Replace any dict containing keyword.
+
+    replace() takes the containing dict as input, and returns its replacement.
+    """
+    if keyword in d:
+        d = replace(d)
+    for k, v in d.items():
+        if isinstance(v, dict):
+            d[k] = _replace_in_dict(v, keyword, replace)
+    return d
+
+
+def _deep_get(d: Dict[str, Any], path: str) -> Dict[str, Any]:
+    """
+    Returns value at path, where `.` in path delimitates the keys.
+    """
+    keys = path.split(".")
+    for k in keys:
+        d = d[k]
+    return d
+
+
 def _add_embedded_connectors(schema: Dict[str, Any]) -> None:
     """
     Add embedded Connectors resource attribute to supported CloudFormation resources.
@@ -124,6 +148,13 @@ def extend_with_cfn_schema(sam_schema: Dict[str, Any], cfn_schema: Dict[str, Any
 
     _add_embedded_connectors(sam_schema)
 
+    # Inject CloudFormation documentation to SAM pass-through properties
+    _replace_in_dict(
+        sam_schema,
+        "__samPassThroughPath",
+        lambda d: _deep_get(cfn_schema, d["__samPassThroughPath"]),
+    )
+
     # The unified schema should include all supported properties
     sam_schema["additionalProperties"] = False
 

samtranslator/schema/schema.json

@@ -200646,23 +200646,13 @@
           "title": "Description"
         },
         "Environment": {
-          "allOf": [
-            {
-              "$ref": "#/definitions/PassThroughProp"
-            }
-          ],
-          "description": "The configuration for the runtime environment\\.  \n*Type*: [Environment](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-environment.html)  \n*Required*: No  \n*AWS CloudFormation compatibility*: This property is passed directly to the [`Environment`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-environment.html) property of an `AWS::Lambda::Function` resource\\.",
-          "markdownDescription": "The configuration for the runtime environment\\.  \n*Type*: [Environment](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-environment.html)  \n*Required*: No  \n*AWS CloudFormation compatibility*: This property is passed directly to the [`Environment`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-environment.html) property of an `AWS::Lambda::Function` resource\\.",
+          "$ref": "#/definitions/AWS::Lambda::Function.Environment",
+          "markdownDescription": "Environment variables that are accessible from function code during execution\\.  \n*Required*: No  \n*Type*: [Environment](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-environment.html)  \n*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)",
           "title": "Environment"
         },
         "EphemeralStorage": {
-          "allOf": [
-            {
-              "$ref": "#/definitions/PassThroughProp"
-            }
-          ],
-          "description": "An object that specifies the disk space, in MB, available to your Lambda function in `/tmp`\\.  \nFor more information about this property, see [Lambda execution environment](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-context.html) in the *AWS Lambda Developer Guide*\\.  \n*Type*: [EphemeralStorage](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-ephemeralstorage)  \n*Required*: No  \n*AWS CloudFormation compatibility*: This property is passed directly to the [`EphemeralStorage`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-ephemeralstorage) property of an `AWS::Lambda::Function` resource\\.",
-          "markdownDescription": "An object that specifies the disk space, in MB, available to your Lambda function in `/tmp`\\.  \nFor more information about this property, see [Lambda execution environment](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-context.html) in the *AWS Lambda Developer Guide*\\.  \n*Type*: [EphemeralStorage](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-ephemeralstorage)  \n*Required*: No  \n*AWS CloudFormation compatibility*: This property is passed directly to the [`EphemeralStorage`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-ephemeralstorage) property of an `AWS::Lambda::Function` resource\\.",
+          "$ref": "#/definitions/AWS::Lambda::Function.EphemeralStorage",
+          "markdownDescription": "The size of the function's `/tmp` directory in MB\\. The default value is 512, but it can be any whole number between 512 and 10,240 MB\\.  \n*Required*: No  \n*Type*: [EphemeralStorage](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-ephemeralstorage.html)  \n*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)",
           "title": "EphemeralStorage"
         },
         "EventInvokeConfig": {
@@ -200943,23 +200933,13 @@
           "title": "Description"
         },
         "Environment": {
-          "allOf": [
-            {
-              "$ref": "#/definitions/PassThroughProp"
-            }
-          ],
-          "description": "The configuration for the runtime environment\\.  \n*Type*: [Environment](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-environment.html)  \n*Required*: No  \n*AWS CloudFormation compatibility*: This property is passed directly to the [`Environment`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-environment.html) property of an `AWS::Lambda::Function` resource\\.",
-          "markdownDescription": "The configuration for the runtime environment\\.  \n*Type*: [Environment](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-environment.html)  \n*Required*: No  \n*AWS CloudFormation compatibility*: This property is passed directly to the [`Environment`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-environment.html) property of an `AWS::Lambda::Function` resource\\.",
+          "$ref": "#/definitions/AWS::Lambda::Function.Environment",
+          "markdownDescription": "Environment variables that are accessible from function code during execution\\.  \n*Required*: No  \n*Type*: [Environment](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-environment.html)  \n*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)",
           "title": "Environment"
         },
         "EphemeralStorage": {
-          "allOf": [
-            {
-              "$ref": "#/definitions/PassThroughProp"
-            }
-          ],
-          "description": "An object that specifies the disk space, in MB, available to your Lambda function in `/tmp`\\.  \nFor more information about this property, see [Lambda execution environment](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-context.html) in the *AWS Lambda Developer Guide*\\.  \n*Type*: [EphemeralStorage](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-ephemeralstorage)  \n*Required*: No  \n*AWS CloudFormation compatibility*: This property is passed directly to the [`EphemeralStorage`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-ephemeralstorage) property of an `AWS::Lambda::Function` resource\\.",
-          "markdownDescription": "An object that specifies the disk space, in MB, available to your Lambda function in `/tmp`\\.  \nFor more information about this property, see [Lambda execution environment](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-context.html) in the *AWS Lambda Developer Guide*\\.  \n*Type*: [EphemeralStorage](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-ephemeralstorage)  \n*Required*: No  \n*AWS CloudFormation compatibility*: This property is passed directly to the [`EphemeralStorage`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-ephemeralstorage) property of an `AWS::Lambda::Function` resource\\.",
+          "$ref": "#/definitions/AWS::Lambda::Function.EphemeralStorage",
+          "markdownDescription": "The size of the function's `/tmp` directory in MB\\. The default value is 512, but it can be any whole number between 512 and 10,240 MB\\.  \n*Required*: No  \n*Type*: [EphemeralStorage](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-ephemeralstorage.html)  \n*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)",
           "title": "EphemeralStorage"
         },
         "EventInvokeConfig": {
@@ -201050,14 +201030,9 @@
           "title": "FileSystemConfigs"
         },
         "FunctionName": {
-          "allOf": [
-            {
-              "$ref": "#/definitions/PassThroughProp"
-            }
-          ],
-          "description": "A name for the function\\. If you don't specify a name, a unique name is generated for you\\.  \n*Type*: String  \n*Required*: No  \n*AWS CloudFormation compatibility*: This property is passed directly to the [`FunctionName`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-functionname) property of an `AWS::Lambda::Function` resource\\.",
-          "markdownDescription": "A name for the function\\. If you don't specify a name, a unique name is generated for you\\.  \n*Type*: String  \n*Required*: No  \n*AWS CloudFormation compatibility*: This property is passed directly to the [`FunctionName`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-functionname) property of an `AWS::Lambda::Function` resource\\.",
-          "title": "FunctionName"
+          "markdownDescription": "The name of the Lambda function, up to 64 characters in length\\. If you don't specify a name, AWS CloudFormation generates one\\.  \nIf you specify a name, you cannot perform updates that require replacement of this resource\\. You can perform updates that require no or some interruption\\. If you must replace the resource, specify a new name\\.  \n*Required*: No  \n*Type*: String  \n*Update requires*: [Replacement](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement)",
+          "title": "FunctionName",
+          "type": "string"
         },
         "FunctionUrlConfig": {
           "allOf": [