@gradientedge/cdk-utils-aws 2.3.0 → 2.4.1

package/dist/src/construct/event-handler/main.js

@@ -37,6 +37,9 @@ export class EventHandler extends CommonConstruct {
         this.id = id;
         this.handler = new Handler();
     }
+    /**
+     * @summary Initialise and provision resources
+     */
     initResources() {
         this.createSQSEventSource();
         this.createWorkflow();
@@ -107,13 +110,17 @@ export class EventHandler extends CommonConstruct {
      * @summary Method to create an event archive if the event rule is not a scheduled one.
      */
     createEventArchive() {
-        /* do not enable for scheduled events */
+        /* Skip archiving when:
+           - no event rule is configured
+           - the rule is schedule-based (scheduled events are not worth archiving)
+           - archiving is explicitly disabled */
         if (!this.props.eventRule ||
             this.props.eventRule.schedule ||
             this.props.eventRuleSchedule ||
             !this.props.eventRuleArchiveEnabled)
             return;
         this.handler.archive = new Archive(this, `${this.id}-archive`, {
+            /* Strip the stack name prefix from the archive name to keep it concise */
             archiveName: `${this.props.eventRule.ruleName}-${this.props.stage}`.replace(`${this.node.tryGetContext('stackName')}-`, ''),
             description: `Archive of events for ${this.props.eventRule.ruleName}`,
             eventPattern: this.handler.rulePattern,
@@ -145,6 +152,10 @@ export class EventHandler extends CommonConstruct {
      * @summary Method to create the workflow definition.
      */
     createWorkflowDefinition() {
+        /* When useMapState is true, the workflow uses a Map state to iterate over
+           the entire input payload (which must be an array at runtime). The
+           eventWorkflowDefinition becomes the iterator (inner step) of the Map
+           rather than the top-level state machine definition. */
         if (this.useMapState) {
             this.handler.workflowMapState = new Map(this, `Map Iterator`, {
                 ...this.props.workflowMapState,

package/dist/src/construct/lambda-with-iam-access/main.d.ts

@@ -43,10 +43,25 @@ export declare class LambdaWithIamAccess extends CommonConstruct {
      * @summary Initialise and provision resources
      */
     initResources(): void;
+    /**
+     * @summary Resolve the VPC for the Lambda function if a VPC name is provided
+     */
     protected resolveVpc(): void;
+    /**
+     * @summary Resolve the security groups for the Lambda function from an exported value
+     */
     protected resolveSecurityGroups(): void;
+    /**
+     * @summary Resolve the EFS access point for the Lambda function. Override to provide an access point.
+     */
     protected resolveAccessPoint(): void;
+    /**
+     * @summary Resolve the EFS mount path for the Lambda function. Override to provide a mount path.
+     */
     protected resolveMountPath(): void;
+    /**
+     * @summary Resolve the VPC subnets for the Lambda function. Override to provide specific subnets.
+     */
     protected resolveVpcSubnets(): void;
     /**
      * @summary Method to create iam policy for Lambda function

package/dist/src/construct/lambda-with-iam-access/main.js

@@ -61,11 +61,17 @@ export class LambdaWithIamAccess extends CommonConstruct {
         this.createIamUserForLambdaFunction();
         this.createIamSecretForLambdaFunction();
     }
+    /**
+     * @summary Resolve the VPC for the Lambda function if a VPC name is provided
+     */
     resolveVpc() {
         if (this.props.vpcName) {
             this.lambdaVpc = this.vpcManager.retrieveCommonVpc(`${this.id}-vpc`, this, this.props.vpcName);
         }
     }
+    /**
+     * @summary Resolve the security groups for the Lambda function from an exported value
+     */
     resolveSecurityGroups() {
         if (this.props.securityGroupExportName) {
             const lambdaSecurityGroup = SecurityGroup.fromSecurityGroupId(this, `${this.id}-security-group`, Fn.importValue(this.props.securityGroupExportName));
@@ -73,8 +79,17 @@ export class LambdaWithIamAccess extends CommonConstruct {
             this.lambdaSecurityGroups = [lambdaSecurityGroup];
         }
     }
+    /**
+     * @summary Resolve the EFS access point for the Lambda function. Override to provide an access point.
+     */
     resolveAccessPoint() { }
+    /**
+     * @summary Resolve the EFS mount path for the Lambda function. Override to provide a mount path.
+     */
     resolveMountPath() { }
+    /**
+     * @summary Resolve the VPC subnets for the Lambda function. Override to provide specific subnets.
+     */
     resolveVpcSubnets() { }
     /**
      * @summary Method to create iam policy for Lambda function
@@ -140,6 +155,8 @@ export class LambdaWithIamAccess extends CommonConstruct {
         this.lambdaIamUser = new User(this, `${this.id}-lambda-user`, {
             userName: this.resourceNameFormatter.format(`${this.id}-user`),
         });
+        /* The wildcard suffix on the ARN is needed to match alias-qualified ARNs
+           (e.g. arn:...:function:name:aliasName) for InvokeFunction permission */
         new Policy(this, `${this.id}-lambda-user-policy`, {
             policyName: this.resourceNameFormatter.format(`${this.id}-policy`),
             statements: [
@@ -167,6 +184,8 @@ export class LambdaWithIamAccess extends CommonConstruct {
                 });
             });
         }
+        /* Stage is included in the logical ID to avoid collisions when deploying
+           multiple stages to the same AWS account */
         this.lambdaUserAccessKey = new CfnAccessKey(this, `${this.id}-access-key-${this.props.stage}`, {
             userName: this.lambdaIamUser.userName,
         });
@@ -176,6 +195,9 @@ export class LambdaWithIamAccess extends CommonConstruct {
      */
     createIamSecretForLambdaFunction() {
         this.lambdaUserAccessSecret = this.secretsManager.createSecret(`${this.id}-lambda-user-secret-${this.props.stage}`, this, this.props.lambdaSecret);
+        /* Override the L1 CfnSecret to disable auto-generated secret string and inject
+           the IAM access key credentials instead. We use a template literal (not JSON.stringify)
+           because the values contain CloudFormation Ref/GetAtt tokens that must not be escaped. */
         const cfnSecret = this.lambdaUserAccessSecret.node.defaultChild;
         cfnSecret.generateSecretString = undefined;
         cfnSecret.secretString = `{ "ACCESS_KEY_ID": "${this.lambdaUserAccessKey.ref}", "ACCESS_KEY_SECRET": "${this.lambdaUserAccessKey.attrSecretAccessKey}" }`;

package/dist/src/construct/piped-event-handler/main.d.ts

@@ -23,6 +23,9 @@ export declare class PipedEventHandler extends EventHandler {
     pipedDlq: IQueue;
     pipedQueue: IQueue;
     protected constructor(parent: Construct, id: string, props: PipedEventHandlerProps);
+    /**
+     * @summary Initialise and provision resources
+     */
     initResources(): void;
     /**
      * @summary Method to create the piped queue and dlq.

package/dist/src/construct/piped-event-handler/main.js

@@ -28,6 +28,9 @@ export class PipedEventHandler extends EventHandler {
         this.useMapState = true;
         this.provisionTarget = false;
     }
+    /**
+     * @summary Initialise and provision resources
+     */
     initResources() {
         this.createPipedQueue();
         this.handler.sqsTargets = [new SqsQueue(this.pipedQueue)];

package/dist/src/construct/rest-api-lambda/main.js

@@ -76,6 +76,9 @@ export class RestApiLambda extends CommonConstruct {
      * @summary Method to resolve a certificate based on attributes
      */
     resolveCertificate() {
+        /* ACM certificates for CloudFront must be in us-east-1, which may differ from the
+           stack's region. When an SSM parameter name and region are provided, the ARN is
+           read cross-region and mutated onto the props before certificate resolution. */
         if (this.props.restApiCertificate.useExistingCertificate &&
             this.props.restApiCertificate.certificateSsmName &&
             this.props.restApiCertificate.certificateRegion) {

package/dist/src/construct/rest-api-lambda-with-cache/main.d.ts

@@ -29,6 +29,9 @@ export declare abstract class RestApiLambdaWithCache extends RestApiLambda {
     restApiSecurityGroup: ISecurityGroup;
     restApiSecurityGroupExportName: string;
     protected constructor(parent: Construct, id: string, props: RestApiLambdaWithCacheProps);
+    /**
+     * @summary Initialise and provision resources
+     */
     initResources(): void;
     /**
      * Create VPC

package/dist/src/construct/rest-api-lambda-with-cache/main.js

@@ -36,6 +36,9 @@ export class RestApiLambdaWithCache extends RestApiLambda {
         this.props = props;
         this.id = id;
     }
+    /**
+     * @summary Initialise and provision resources
+     */
     initResources() {
         this.resolveVpc();
         this.resolveSecurityGroup();

package/dist/src/construct/site-with-ecs-backend/main.d.ts

@@ -75,7 +75,13 @@ export declare class SiteWithEcsBackend extends CommonConstruct {
      * @summary Method to resolve a certificate based on attributes
      */
     protected resolveCertificate(): void;
+    /**
+     * @summary Resolve the global (edge) SSL certificate, optionally reading the ARN from SSM
+     */
     protected resolveGlobalCertificate(): void;
+    /**
+     * @summary Resolve the regional SSL certificate, optionally reading the ARN from SSM
+     */
     protected resolveRegionalCertificate(): void;
     /**
      * @summary Method to resolve secrets from SecretsManager
@@ -126,11 +132,32 @@ export declare class SiteWithEcsBackend extends CommonConstruct {
      * Method to create log bucket for site distribution
      */
     protected createSiteLogBucket(): void;
+    /**
+     * @summary Create a CloudFront cache policy with the specified TTL and behaviour settings
+     * @param id scoped id of the resource
+     * @param siteCachePolicy the cache policy properties
+     */
     protected createSiteCachePolicy(id: string, siteCachePolicy: SiteCachePolicyProps): CachePolicy;
+    /**
+     * @summary Create the cache policy for the site origin and assign it to the default behaviour
+     */
     protected createSiteOriginCachePolicy(): void;
+    /**
+     * @summary Create the origin request policy for the site distribution
+     */
     protected createSiteOriginRequestPolicy(): void;
+    /**
+     * @summary Create a CloudFront response headers policy with security headers
+     * @param props the response headers policy properties
+     */
     protected createResponseHeaderPolicy(props: SiteResponseHeadersPolicyProps): ResponseHeadersPolicy | undefined;
+    /**
+     * @summary Create the response headers policy for the site origin and assign it to the default behaviour
+     */
     protected createSiteOriginResponseHeadersPolicy(): void;
+    /**
+     * @summary Create the HTTP origin pointing to the ECS backend service
+     */
     protected createSiteOrigin(): void;
     /**
      * @summary Method to create a site cloudfront function

package/dist/src/construct/site-with-ecs-backend/main.js

@@ -102,6 +102,9 @@ export class SiteWithEcsBackend extends CommonConstruct {
         this.resolveGlobalCertificate();
         this.resolveRegionalCertificate();
     }
+    /**
+     * @summary Resolve the global (edge) SSL certificate, optionally reading the ARN from SSM
+     */
     resolveGlobalCertificate() {
         if (this.props.siteCertificate.useExistingCertificate &&
             this.props.siteCertificate.certificateSsmName &&
@@ -110,6 +113,9 @@ export class SiteWithEcsBackend extends CommonConstruct {
         }
         this.siteCertificate = this.acmManager.resolveCertificate(`${this.id}-certificate`, this, this.props.siteCertificate);
     }
+    /**
+     * @summary Resolve the regional SSL certificate, optionally reading the ARN from SSM
+     */
     resolveRegionalCertificate() {
         if (this.props.siteRegionalCertificate.useExistingCertificate &&
             this.props.siteRegionalCertificate.certificateSsmName &&
@@ -257,6 +263,8 @@ export class SiteWithEcsBackend extends CommonConstruct {
         this.siteEcsLoadBalancer = fargateService.loadBalancer;
         this.siteEcsTargetGroup = fargateService.targetGroup;
         fargateService.loadBalancer.logAccessLogs(this.siteLogBucket, 'alb');
+        /* Configure auto-scaling policies — each scaling dimension is independent
+           and only enabled when its corresponding threshold is set in props */
         if (this.props.siteTask.siteScaling) {
             const scalableTaskCount = this.siteEcsService.autoScaleTaskCount({
                 maxCapacity: this.props.siteTask.siteScaling.maxCapacity ?? 4,
@@ -285,7 +293,8 @@ export class SiteWithEcsBackend extends CommonConstruct {
         /* if enabled, add efs with access point and mount */
         if (this.props.siteFileSystem) {
             this.siteFileSystem = this.efsManager.createFileSystem(`${this.id}-fs`, this, this.props.siteFileSystem, this.siteVpc, this.props.siteFileSystemAccessPoints);
-            /* allow access to/from EFS from Fargate ECS service */
+            /* Allow bidirectional NFS traffic between EFS and the Fargate service —
+               both directions are required for the EFS mount to function correctly */
             this.siteFileSystem.connections.allowDefaultPortFrom(this.siteEcsService.connections);
             this.siteFileSystem.connections.allowDefaultPortTo(this.siteEcsService.connections);
             /* add EFS permissions to ECS Role */
@@ -322,6 +331,11 @@ export class SiteWithEcsBackend extends CommonConstruct {
     createSiteLogBucket() {
         this.siteLogBucket = this.s3Manager.createS3Bucket(`${this.id}-site-logs`, this, this.props.siteLogBucket);
     }
+    /**
+     * @summary Create a CloudFront cache policy with the specified TTL and behaviour settings
+     * @param id scoped id of the resource
+     * @param siteCachePolicy the cache policy properties
+     */
     createSiteCachePolicy(id, siteCachePolicy) {
         if (!siteCachePolicy.cachePolicyName)
             throw new Error(`SiteCachePolicy cachePolicyName undefined for ${id}`);
@@ -337,6 +351,9 @@ export class SiteWithEcsBackend extends CommonConstruct {
             queryStringBehavior: siteCachePolicy.queryStringBehavior,
         });
     }
+    /**
+     * @summary Create the cache policy for the site origin and assign it to the default behaviour
+     */
     createSiteOriginCachePolicy() {
         if (!this.props.siteCachePolicy)
             return;
@@ -345,6 +362,9 @@ export class SiteWithEcsBackend extends CommonConstruct {
             cachePolicy: this.siteCachePolicy,
         });
     }
+    /**
+     * @summary Create the origin request policy for the site distribution
+     */
     createSiteOriginRequestPolicy() {
         if (!this.props.siteOriginRequestPolicy)
             return;
@@ -361,6 +381,10 @@ export class SiteWithEcsBackend extends CommonConstruct {
             originRequestPolicy: this.siteOriginRequestPolicy,
         });
     }
+    /**
+     * @summary Create a CloudFront response headers policy with security headers
+     * @param props the response headers policy properties
+     */
     createResponseHeaderPolicy(props) {
         if (!props)
             return undefined;
@@ -379,6 +403,9 @@ export class SiteWithEcsBackend extends CommonConstruct {
             },
         });
     }
+    /**
+     * @summary Create the response headers policy for the site origin and assign it to the default behaviour
+     */
     createSiteOriginResponseHeadersPolicy() {
         if (!this.props.siteOriginResponseHeadersPolicy)
             return;
@@ -387,6 +414,9 @@ export class SiteWithEcsBackend extends CommonConstruct {
             responseHeadersPolicy: this.siteOriginResponseHeadersPolicy,
         });
     }
+    /**
+     * @summary Create the HTTP origin pointing to the ECS backend service
+     */
     createSiteOrigin() {
         this.siteOrigin = new HttpOrigin(this.siteInternalDomainName, {
             httpPort: this.props.siteTask.listenerPort,

package/dist/src/construct/site-with-lambda-backend/main.d.ts

@@ -64,7 +64,13 @@ export declare class SiteWithLambdaBackend extends CommonConstruct {
      * @summary Method to resolve a certificate based on attributes
      */
     protected resolveCertificate(): void;
+    /**
+     * @summary Resolve the global (edge) SSL certificate, optionally reading the ARN from SSM
+     */
     protected resolveGlobalCertificate(): void;
+    /**
+     * @summary Resolve the regional SSL certificate, optionally reading the ARN from SSM
+     */
     protected resolveRegionalCertificate(): void;
     /**
      * @summary Method to resolve secrets from SecretsManager
@@ -79,20 +85,68 @@ export declare class SiteWithLambdaBackend extends CommonConstruct {
      * Method to create log bucket for site distribution
      */
     protected createSiteLogBucket(): void;
+    /**
+     * @summary Create a CloudFront cache policy with the specified TTL and behaviour settings
+     * @param id scoped id of the resource
+     * @param siteCachePolicy the cache policy properties
+     */
     protected createSiteCachePolicy(id: string, siteCachePolicy: SiteWithLambdaBackendCachePolicyProps): CachePolicy;
+    /**
+     * @summary Create the cache policy for the site origin and assign it to the default behaviour
+     */
     protected createSiteOriginCachePolicy(): void;
+    /**
+     * @summary Create the origin request policy for the site distribution
+     */
     protected createSiteOriginRequestPolicy(): void;
+    /**
+     * @summary Create a CloudFront response headers policy with security headers
+     * @param props the response headers policy properties
+     */
     protected createResponseHeaderPolicy(props: SiteWithLambdaBackendResponseHeadersPolicyProps): ResponseHeadersPolicy | undefined;
+    /**
+     * @summary Create the response headers policy for the site origin and assign it to the default behaviour
+     */
     protected createSiteOriginResponseHeadersPolicy(): void;
+    /**
+     * @summary Create the HTTP origin backed by the Lambda function URL
+     */
     protected createSiteOrigin(): void;
+    /**
+     * @summary Orchestrate creation of all Lambda-based origin resources
+     */
     protected createSiteOriginResources(): void;
+    /**
+     * @summary Create static asset deployment. Override to provide a deployment.
+     */
     protected createSiteStaticAssetDeployment(): void;
+    /**
+     * @summary Create the IAM policy for the site Lambda function
+     */
     protected createSiteLambdaPolicy(): void;
+    /**
+     * @summary Create the IAM role for the site Lambda function
+     */
     protected createSiteLambdaRole(): void;
+    /**
+     * @summary Create the environment variables for the site Lambda function including Web Adapter config
+     */
     protected createSiteLambdaEnvironment(): void;
+    /**
+     * @summary Create the Lambda Web Adapter layers for the site function
+     */
     protected createSiteLambdaLayers(): void;
+    /**
+     * @summary Create the Lambda application code. Override to provide custom application code.
+     */
     protected createSiteLambdaApplication(): void;
+    /**
+     * @summary Create the site Lambda function with the configured role, layers, and environment
+     */
     protected createSiteLambda(): void;
+    /**
+     * @summary Create the Lambda function URL used as the CloudFront origin, with optional alias support
+     */
     protected createSiteLambdaUrl(): void;
     /**
      * @summary Method to create a site cloudfront function

package/dist/src/construct/site-with-lambda-backend/main.js

@@ -87,6 +87,9 @@ export class SiteWithLambdaBackend extends CommonConstruct {
         this.resolveGlobalCertificate();
         this.resolveRegionalCertificate();
     }
+    /**
+     * @summary Resolve the global (edge) SSL certificate, optionally reading the ARN from SSM
+     */
     resolveGlobalCertificate() {
         if (this.props.siteCertificate.useExistingCertificate &&
             this.props.siteCertificate.certificateSsmName &&
@@ -95,6 +98,9 @@ export class SiteWithLambdaBackend extends CommonConstruct {
         }
         this.siteCertificate = this.acmManager.resolveCertificate(`${this.id}-certificate`, this, this.props.siteCertificate);
     }
+    /**
+     * @summary Resolve the regional SSL certificate, optionally reading the ARN from SSM
+     */
     resolveRegionalCertificate() {
         if (this.props.siteRegionalCertificate.useExistingCertificate &&
             this.props.siteRegionalCertificate.certificateSsmName &&
@@ -130,6 +136,11 @@ export class SiteWithLambdaBackend extends CommonConstruct {
     createSiteLogBucket() {
         this.siteLogBucket = this.s3Manager.createS3Bucket(`${this.id}-site-logs`, this, this.props.siteLogBucket);
     }
+    /**
+     * @summary Create a CloudFront cache policy with the specified TTL and behaviour settings
+     * @param id scoped id of the resource
+     * @param siteCachePolicy the cache policy properties
+     */
     createSiteCachePolicy(id, siteCachePolicy) {
         if (!siteCachePolicy.cachePolicyName)
             throw new Error(`SiteCachePolicy cachePolicyName undefined for ${id}`);
@@ -145,6 +156,9 @@ export class SiteWithLambdaBackend extends CommonConstruct {
             queryStringBehavior: siteCachePolicy.queryStringBehavior,
         });
     }
+    /**
+     * @summary Create the cache policy for the site origin and assign it to the default behaviour
+     */
     createSiteOriginCachePolicy() {
         if (!this.props.siteCachePolicy)
             return;
@@ -153,6 +167,9 @@ export class SiteWithLambdaBackend extends CommonConstruct {
             cachePolicy: this.siteCachePolicy,
         });
     }
+    /**
+     * @summary Create the origin request policy for the site distribution
+     */
     createSiteOriginRequestPolicy() {
         if (!this.props.siteOriginRequestPolicy)
             return;
@@ -169,6 +186,10 @@ export class SiteWithLambdaBackend extends CommonConstruct {
             originRequestPolicy: this.siteOriginRequestPolicy,
         });
     }
+    /**
+     * @summary Create a CloudFront response headers policy with security headers
+     * @param props the response headers policy properties
+     */
     createResponseHeaderPolicy(props) {
         if (!props)
             return undefined;
@@ -187,6 +208,9 @@ export class SiteWithLambdaBackend extends CommonConstruct {
             },
         });
     }
+    /**
+     * @summary Create the response headers policy for the site origin and assign it to the default behaviour
+     */
     createSiteOriginResponseHeadersPolicy() {
         if (!this.props.siteOriginResponseHeadersPolicy)
             return;
@@ -195,6 +219,9 @@ export class SiteWithLambdaBackend extends CommonConstruct {
             responseHeadersPolicy: this.siteOriginResponseHeadersPolicy,
         });
     }
+    /**
+     * @summary Create the HTTP origin backed by the Lambda function URL
+     */
     createSiteOrigin() {
         this.createSiteOriginResources();
         this.siteOrigin = new HttpOrigin(Fn.select(2, Fn.split('/', this.siteLambdaUrl.url)), {
@@ -203,6 +230,9 @@ export class SiteWithLambdaBackend extends CommonConstruct {
             protocolPolicy: OriginProtocolPolicy.HTTPS_ONLY,
         });
     }
+    /**
+     * @summary Orchestrate creation of all Lambda-based origin resources
+     */
     createSiteOriginResources() {
         this.createSiteStaticAssetDeployment();
         this.createSiteLambdaPolicy();
@@ -213,7 +243,13 @@ export class SiteWithLambdaBackend extends CommonConstruct {
         this.createSiteLambda();
         this.createSiteLambdaUrl();
     }
+    /**
+     * @summary Create static asset deployment. Override to provide a deployment.
+     */
     createSiteStaticAssetDeployment() { }
+    /**
+     * @summary Create the IAM policy for the site Lambda function
+     */
     createSiteLambdaPolicy() {
         this.siteLambdaPolicy = new PolicyDocument({
             statements: [
@@ -225,9 +261,15 @@ export class SiteWithLambdaBackend extends CommonConstruct {
             ],
         });
     }
+    /**
+     * @summary Create the IAM role for the site Lambda function
+     */
     createSiteLambdaRole() {
         this.siteLambdaRole = this.iamManager.createRoleForLambda(`${this.id}-role`, this, this.siteLambdaPolicy);
     }
+    /**
+     * @summary Create the environment variables for the site Lambda function including Web Adapter config
+     */
     createSiteLambdaEnvironment() {
         this.siteLambdaEnvironment = {
             AWS_LAMBDA_EXEC_WRAPPER: this.props.siteExecWrapperPath ?? '/opt/bootstrap',
@@ -240,15 +282,31 @@ export class SiteWithLambdaBackend extends CommonConstruct {
             TZ: this.props.timezone,
         };
     }
+    /**
+     * @summary Create the Lambda Web Adapter layers for the site function
+     */
     createSiteLambdaLayers() {
         this.siteLambdaLayers = this.lambdaManager.createWebAdapterLayer(`${this.id}-web-adapter`, this);
     }
+    /**
+     * @summary Create the Lambda application code. Override to provide custom application code.
+     */
     createSiteLambdaApplication() { }
+    /**
+     * @summary Create the site Lambda function with the configured role, layers, and environment
+     */
     createSiteLambda() {
         this.siteLambdaFunction = this.lambdaManager.createLambdaFunction(`${this.id}-lambda`, this, this.props.siteLambda, this.siteLambdaRole, this.siteLambdaLayers, this.siteLambdaApplication, this.props.siteLambda.handler, this.siteLambdaEnvironment);
     }
+    /**
+     * @summary Create the Lambda function URL used as the CloudFront origin, with optional alias support
+     */
     createSiteLambdaUrl() {
+        /* Check if a 'current' alias is configured — when present, the function URL
+           points to the alias ARN (functionArn:aliasName) instead of $LATEST */
         const lambdaAlias = _.find(this.props.siteLambda.lambdaAliases, alias => alias.aliasName === LAMBDA_ALIAS_NAME_CURRENT);
+        /* When using an alias, import the function with sameEnvironment: true to
+           prevent CDK from generating cross-account/cross-region permissions */
         const lambdaFn = lambdaAlias
             ? Function.fromFunctionAttributes(this, `${this.id}-fn-alias`, {
                 functionArn: `${this.siteLambdaFunction.functionArn}:${lambdaAlias.aliasName}`,
@@ -256,11 +314,14 @@ export class SiteWithLambdaBackend extends CommonConstruct {
             })
             : this.siteLambdaFunction;
         lambdaFn.node.addDependency(this.siteLambdaFunction);
+        /* Explicit dependencies ensure the function and alias exist before the URL is created */
         this.siteLambdaUrl = lambdaFn.addFunctionUrl({
             authType: FunctionUrlAuthType.NONE,
         });
         this.siteLambdaUrl.node.addDependency(this.siteLambdaFunction);
         this.siteLambdaUrl.node.addDependency(lambdaFn);
+        /* Grant public invoke access — the resource-based policy is applied via
+           grantInvokeUrl, restricted by the FunctionUrlAuthType condition */
         const principal = new AnyPrincipal();
         principal.addToPolicy(new PolicyStatement({
             actions: ['lambda:InvokeFunctionUrl'],

package/dist/src/construct/static-asset-deployment/main.js

@@ -71,6 +71,8 @@ export class StaticAssetDeployment extends CommonConstruct {
      * @summary Deploy the static assets into the static asset bucket
      */
     deployStaticAssets() {
+        /* Sources can be provided as either string paths (resolved relative to the
+           project root) or pre-built ISource objects for more flexibility */
         let sources = [];
         if (Array.isArray(this.props.staticAssetSources) &&
             this.props.staticAssetSources.length > 0 &&
@@ -83,6 +85,8 @@ export class StaticAssetDeployment extends CommonConstruct {
         else {
             sources = this.props.staticAssetSources;
         }
+        /* Build optional config objects as empty objects and conditionally populate them,
+           then spread into the deployment — this avoids setting undefined properties */
         let distributionOptions = {};
         if (this.cloudfrontDistribution) {
             distributionOptions = {

package/dist/src/services/api-gateway/main.js

@@ -105,6 +105,8 @@ export class ApiManager {
      */
     createApiResource(id, scope, parent, path, integration, addProxy, authorizer, allowedOrigins, allowedMethods, allowedHeaders, methodRequestParameters, proxyIntegration, enableDefaultCors, mockIntegration, mockMethodResponses) {
         const methods = allowedMethods ?? Cors.ALL_METHODS;
+        /* enableDefaultCors uses strict equality — only `false` disables CORS.
+           When CORS is disabled, OPTIONS requests are routed to the mock integration instead. */
         let defaultCorsPreflightOptions;
         if (enableDefaultCors === false) {
             defaultCorsPreflightOptions = undefined;
@@ -120,6 +122,8 @@ export class ApiManager {
         const resource = parent.addResource(path, {
             defaultCorsPreflightOptions: defaultCorsPreflightOptions,
         });
+        /* When CORS is disabled, route OPTIONS to the mock integration for manual
+           CORS handling; all other methods use the real integration */
         _.forEach(methods, method => {
             if (enableDefaultCors === false && mockIntegration && method === 'OPTIONS') {
                 resource.addMethod(method, mockIntegration, {
@@ -136,6 +140,8 @@ export class ApiManager {
             }
         });
         createCfnOutput(`${id}-${path}ResourceId`, scope, resource.resourceId);
+        /* Create a greedy proxy resource ({path+}) to catch all sub-paths.
+           Uses proxyIntegration if provided, otherwise falls back to the main integration. */
         if (addProxy) {
             const resourceProxy = resource.addResource(`{${path}+}`, {
                 defaultCorsPreflightOptions: defaultCorsPreflightOptions,

package/dist/src/services/certificate-manager/main.js

@@ -43,6 +43,9 @@ export class AcmManager {
             throw new Error(`Certificate props undefined for ${id}`);
         let certificate;
         if (props.useExistingCertificate) {
+            /* When importing an existing certificate, the ARN can be provided directly
+               or constructed from account/region/id — falls back to the current stack's
+               account and region when not explicitly specified */
             let certificateArn = props.certificateArn;
             if (!certificateArn) {
                 const certificateAccount = props.certificateAccount ? props.certificateAccount : Stack.of(scope).account;

package/dist/src/services/cloudfront/main.d.ts

@@ -35,6 +35,12 @@ import { CloudfrontFunctionProps, DistributionProps } from './types.js';
  * @category Service
  */
 export declare class CloudFrontManager {
+    /**
+     * @summary Method to create a CloudFront Origin Access Identity
+     * @param id scoped id of the resource
+     * @param scope scope in which this resource is defined
+     * @param accessBucket optional S3 bucket to grant read access to the OAI
+     */
     createOriginAccessIdentity(id: string, scope: CommonConstruct, accessBucket?: IBucket): cf.OriginAccessIdentity;
     /**
      * Method to create a CloudFront distribution with S3 Origin
@@ -93,5 +99,10 @@ export declare class CloudFrontManager {
      * @param props
      */
     createCloudfrontFunction(id: string, scope: CommonConstruct, props: CloudfrontFunctionProps): cf.Function;
+    /**
+     * @summary Method to resolve an existing CloudFront distribution by its attributes
+     * @param scope scope in which this resource is defined
+     * @param props the distribution attributes to look up
+     */
     resolveDistribution(scope: CommonConstruct, props: DistributionAttributes): IDistribution;
 }