@lambda-kata/cdk 0.1.3-rc.9 → 0.1.3-rc.91

package/out/tsc/src/snapstart-activator.d.ts

@@ -0,0 +1,145 @@
+/**
+ * SnapStart Activator - Custom Resource Handler
+ *
+ * This module provides the Lambda handler for a CloudFormation Custom Resource
+ * that enables SnapStart on Lambda functions after deployment. SnapStart requires
+ * asynchronous waiting for snapshot creation, which cannot be done during CDK synthesis.
+ *
+ * The activation process:
+ * 1. Wait for function to be Active
+ * 2. Enable SnapStart configuration
+ * 3. Wait for configuration update
+ * 4. Publish new version (triggers snapshot creation)
+ * 5. Wait for snapshot to be ready (up to 3 minutes)
+ * 6. Create/update 'kata' alias pointing to the new version
+ *
+ * @module snapstart-activator
+ */
+import { LambdaClient } from '@aws-sdk/client-lambda';
+/**
+ * Custom Resource event from CloudFormation.
+ */
+export interface CustomResourceEvent {
+    RequestType: 'Create' | 'Update' | 'Delete';
+    ServiceToken: string;
+    ResponseURL: string;
+    StackId: string;
+    RequestId: string;
+    ResourceType: string;
+    LogicalResourceId: string;
+    PhysicalResourceId?: string;
+    ResourceProperties: {
+        ServiceToken: string;
+        FunctionName: string;
+        AliasName?: string;
+    };
+    OldResourceProperties?: {
+        FunctionName: string;
+        AliasName?: string;
+    };
+}
+/**
+ * Custom Resource response to CloudFormation.
+ */
+export interface CustomResourceResponse {
+    Status: 'SUCCESS' | 'FAILED';
+    Reason?: string;
+    PhysicalResourceId: string;
+    StackId: string;
+    RequestId: string;
+    LogicalResourceId: string;
+    Data?: {
+        Version?: string;
+        AliasName?: string;
+        AliasArn?: string;
+        OptimizationStatus?: string;
+    };
+}
+/**
+ * Result of a successful SnapStart activation cycle.
+ *
+ * Returned by {@link activateSnapStart} after enabling SnapStart,
+ * publishing a version, waiting for snapshot readiness, and creating/updating an alias.
+ *
+ * @see {@link SnapStartActivatorConfig} for configuration options
+ */
+export interface SnapStartActivationResult {
+    /** The published Lambda version number (e.g. "42"). */
+    version: string;
+    /** The alias name that was created or updated (e.g. "kata"). */
+    aliasName: string;
+    /** The full ARN of the alias (e.g. "arn:aws:lambda:us-east-1:123456789012:function:my-fn:kata"). */
+    aliasArn: string;
+    /** The SnapStart optimization status of the published version ("On", "Off", or "Unknown"). */
+    optimizationStatus: string;
+}
+/**
+ * Configuration options for the SnapStart activation cycle.
+ *
+ * All properties are optional and fall back to sensible defaults.
+ *
+ * @see {@link activateSnapStart} for the function that consumes this config
+ */
+export interface SnapStartActivatorConfig {
+    /**
+     * Maximum time in seconds to wait for snapshot creation before proceeding.
+     * If exceeded, a warning is logged and alias creation continues.
+     * @default 180
+     */
+    snapshotTimeoutSeconds?: number;
+    /**
+     * Interval in seconds between polling attempts for snapshot readiness.
+     * @default 2
+     */
+    pollingIntervalSeconds?: number;
+    /**
+     * The Lambda alias name to create or update after publishing a version.
+     * @default 'kata'
+     */
+    aliasName?: string;
+    /**
+     * @internal Override pre-publish delay in milliseconds (for testing only).
+     * @default 3000
+     */
+    _prePublishDelayMs?: number;
+    /**
+     * @internal Override retry delay in milliseconds (for testing only).
+     * @default 5000
+     */
+    _retryDelayMs?: number;
+}
+/**
+ * Sleep for specified milliseconds.
+ * @internal Exported for testability — tests can jest.spyOn to avoid real delays.
+ */
+export declare const _testable: {
+    sleep(ms: number): Promise<void>;
+};
+/**
+ * Activates SnapStart on a Lambda function.
+ *
+ * This function performs the full SnapStart activation cycle:
+ * 1. Ensures function is Active
+ * 2. Enables SnapStart configuration
+ * 3. Waits for configuration update
+ * 4. Publishes new version (with retry on snapshot failure)
+ * 5. Waits for snapshot creation
+ * 6. Creates/updates alias
+ *
+ * Steps 3+4 are wrapped in a retry loop: on State: Failed, a new version
+ * is published (up to MAX_PUBLISH_RETRIES attempts) to handle transient
+ * initialization failures during snapshot creation.
+ *
+ * @param lambdaClient - AWS Lambda client
+ * @param functionName - Name or ARN of the Lambda function
+ * @param config - Optional configuration
+ * @returns Activation result with version and alias information
+ */
+export declare function activateSnapStart(lambdaClient: LambdaClient, functionName: string, config?: SnapStartActivatorConfig): Promise<SnapStartActivationResult>;
+/**
+ * Lambda handler for CloudFormation Custom Resource.
+ *
+ * This handler is invoked by CloudFormation when the custom resource
+ * is created, updated, or deleted.
+ */
+export declare function handler(event: CustomResourceEvent): Promise<CustomResourceResponse>;

package/out/tsc/src/snapstart-construct.d.ts

@@ -0,0 +1,112 @@
+/**
+ * SnapStart Construct - CDK Custom Resource for SnapStart Activation
+ *
+ * This module provides a CDK construct that creates a Custom Resource
+ * to enable SnapStart on Lambda functions after deployment. The construct
+ * handles the asynchronous nature of SnapStart snapshot creation.
+ *
+ * @module snapstart-construct
+ */
+import { Construct } from 'constructs';
+import { CustomResource } from 'aws-cdk-lib';
+import { IFunction } from 'aws-cdk-lib/aws-lambda';
+/**
+ * Properties for the {@link SnapStartActivator} construct.
+ *
+ * @see {@link SnapStartActivator} for the construct that consumes these properties
+ */
+export interface SnapStartActivatorProps {
+    /**
+     * The Lambda function to enable SnapStart on.
+     * The construct will add a dependency so the Custom Resource runs after this function is created.
+     */
+    targetFunction: IFunction;
+    /**
+     * The alias name to create or update after publishing a SnapStart-enabled version.
+     * @default 'kata'
+     */
+    aliasName?: string;
+    /**
+     * Maximum time in seconds to wait for SnapStart snapshot creation.
+     * The Custom Resource handler timeout is set to this value plus a 60-second buffer.
+     * @default 180
+     */
+    snapshotTimeoutSeconds?: number;
+}
+/**
+ * CDK Construct that enables SnapStart on a Lambda function after deployment.
+ *
+ * Creates a CloudFormation Custom Resource backed by a Lambda handler that
+ * performs the full SnapStart activation cycle during stack deployment:
+ *
+ * 1. Waits for the target function to reach Active state
+ * 2. Enables SnapStart configuration (`ApplyOn: PublishedVersions`)
+ * 3. Publishes a new version (triggers snapshot creation)
+ * 4. Polls until the snapshot is ready (or timeout is reached)
+ * 5. Creates or updates an alias pointing to the new version
+ *
+ * After deployment, the published version number and alias ARN are available
+ * as CloudFormation attributes via {@link versionRef} and {@link aliasArnRef}.
+ *
+ * @example
+ * ```typescript
+ * const myFunction = new lambda.Function(this, 'MyFunction', { ... });
+ *
+ * const snapStart = new SnapStartActivator(this, 'SnapStart', {
+ *   targetFunction: myFunction,
+ *   aliasName: 'kata',
+ *   snapshotTimeoutSeconds: 180,
+ * });
+ *
+ * // Reference outputs after deployment
+ * new CfnOutput(this, 'Version', { value: snapStart.versionRef });
+ * new CfnOutput(this, 'AliasArn', { value: snapStart.aliasArnRef });
+ * ```
+ *
+ * @see {@link SnapStartActivatorProps} for configuration options
+ */
+export declare class SnapStartActivator extends Construct {
+    /**
+     * The alias name that was created or updated (e.g. "kata").
+     *
+     * This is a static property set at synthesis time from {@link SnapStartActivatorProps.aliasName}.
+     */
+    readonly aliasName: string;
+    /**
+     * The Custom Resource that manages SnapStart activation during deployment.
+     *
+     * Use this to add additional dependencies or access CloudFormation attributes.
+     */
+    readonly resource: CustomResource;
+    /**
+     * The version number created by SnapStart activation (CloudFormation attribute).
+     *
+     * This value is resolved at deployment time when the Custom Resource handler
+     * publishes a new Lambda version. Use it in `CfnOutput` or other constructs
+     * that need to reference the published version.
+     */
+    readonly versionRef: string;
+    /**
+     * The alias ARN created by SnapStart activation (CloudFormation attribute).
+     *
+     * This value is resolved at deployment time when the Custom Resource handler
+     * creates or updates the alias. Use it in `CfnOutput` or other constructs
+     * that need to reference the alias.
+     */
+    readonly aliasArnRef: string;
+    constructor(scope: Construct, id: string, props: SnapStartActivatorProps);
+    /**
+     * Creates the Lambda function that handles Custom Resource events.
+     * Permissions are passed via initialPolicy to ensure they are part of the
+     * role creation (not a separate AWS::IAM::Policy resource), preventing
+     * IAM propagation race conditions.
+     */
+    private createProviderFunction;
+    /**
+     * Generates the inline handler code for the Custom Resource.
+     *
+     * This is a self-contained version of the snapstart-activator logic
+     * that can be deployed as inline Lambda code.
+     */
+    private generateHandlerCode;
+}

package/out/tsc/src/sync-account-resolver.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Synchronous Account ID Resolution for Lambda Kata CDK Integration
+ *
+ * This module provides synchronous account ID resolution for use during
+ * CDK synthesis, which requires synchronous operations.
+ *
+ * Resolution strategies (in order of precedence):
+ * 1. CDK context value (explicit configuration)
+ * 2. Stack account (if not a token/unresolved)
+ * 3. Environment variables (AWS_ACCOUNT_ID, CDK_DEFAULT_ACCOUNT)
+ * 4. STS GetCallerIdentity via execSync (fallback)
+ *
+ * @module sync-account-resolver
+ */
+import { Construct } from 'constructs';
+/**
+ * Error thrown when account ID cannot be resolved through any strategy.
+ */
+export declare class SyncAccountResolutionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Result of account ID resolution, including the source of the resolution.
+ */
+export interface SyncAccountResolutionResult {
+    accountId: string;
+    source: 'context' | 'stack' | 'env' | 'sts';
+}
+/**
+ * Options for synchronous account ID resolution.
+ */
+export interface SyncAccountResolverOptions {
+    /**
+     * Whether to skip the STS fallback (useful for testing).
+     * Default: false
+     */
+    skipStsFallback?: boolean;
+}
+/**
+ * Resolves the target AWS account ID synchronously.
+ *
+ * This function attempts to determine the AWS account ID using multiple
+ * strategies in order of precedence:
+ *
+ * 1. **CDK Context**: Checks for `aws:cdk:account` context value
+ * 2. **Stack Account**: Uses the Stack's account if it's not a token
+ * 3. **Environment Variables**: Checks AWS_ACCOUNT_ID, CDK_DEFAULT_ACCOUNT
+ * 4. **STS Fallback**: Calls AWS CLI sts get-caller-identity
+ *
+ * @param scope - The CDK construct scope to resolve the account for
+ * @param options - Optional configuration for resolution behavior
+ * @returns The AWS account ID (12-digit string)
+ * @throws SyncAccountResolutionError if account cannot be resolved
+ */
+export declare function resolveAccountIdSync(scope: Construct, options?: SyncAccountResolverOptions): string;
+/**
+ * Resolves the target AWS account ID synchronously with source information.
+ */
+export declare function resolveAccountIdSyncWithSource(scope: Construct, options?: SyncAccountResolverOptions): SyncAccountResolutionResult;
+/**
+ * Resolves the deployment region synchronously.
+ */
+export declare function resolveRegionSync(scope: Construct): string;

package/out/tsc/src/types.d.ts

@@ -41,10 +41,19 @@ export interface LicensingResponse {
      */
     entitled: boolean;
     /**
-     * Customer-specific Lambda Layer ARN containing the Lambda Kata runtime.
+     * Base Lambda Layer ARN (without version number).
      * Only present if the account is entitled.
+     * @deprecated Use layerVersionArn for attaching to Lambda functions
      */
     layerArn?: string;
+    /**
+     * Full Lambda Layer Version ARN (with version number).
+     * This is the ARN that should be used when attaching layers to Lambda functions.
+     * Only present if the account is entitled.
+     *
+     * @example "arn:aws:lambda:eu-central-1:113258654684:layer:lambda-kata-euc:1"
+     */
+    layerVersionArn?: string;
     /**
      * Human-readable status message
      */
@@ -67,6 +76,11 @@ export interface TransformationConfig {
      * This will be stored in the config layer.
      */
     originalHandler: string;
+    /**
+     * The original Node.js runtime (e.g., "nodejs20.x").
+     * Used to create the appropriate Node.js runtime layer.
+     */
+    originalRuntime?: string;
     /**
      * The target runtime for the transformed Lambda.
      * Always Runtime.PYTHON_3_12 for Lambda Kata.
@@ -74,7 +88,7 @@ export interface TransformationConfig {
     targetRuntime: Runtime;
     /**
      * The handler path for the Lambda Kata runtime.
-     * Always "lambdakata.optimized_handler.lambda_handler"
+     * Always "handler.lambda_handler"
      */
     targetHandler: string;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lambda-kata/cdk",
-  "version": "0.1.3-rc.9",
+  "version": "0.1.3-rc.91",
   "description": "AWS CDK integration for Lambda Kata - Node.js Lambdas running via Lambda Kata runtime",
   "main": "out/dist/index.js",
   "types": "out/tsc/src/index.d.ts",
@@ -18,7 +18,7 @@
     "docs": "yarn run docs:md && yarn run docs:html",
     "docs:md": "typedoc --options ./docs/docs.config/typedoc.md.json",
     "docs:html": "typedoc --options ./docs/docs.config/typedoc.html.json",
-    "npm:publish": "npm publish --access public"
+    "npm:publish": "yarn run build && npm publish --access public"
   },
   "files": [
     "out/dist/**/*",
@@ -50,11 +50,14 @@
   },
   "peerDependencies": {
     "aws-cdk-lib": "^2.0.0",
-    "constructs": "^10.0.0"
+    "constructs": "^10.0.0",
+    "esbuild": "^0.23.0"
   },
   "dependencies": {
     "@aws-sdk/client-lambda": "^3.500.0",
+    "@aws-sdk/client-s3": "^3.500.0",
     "@aws-sdk/client-sts": "^3.500.0",
+    "@lambda-kata/licensing": "0.1.32",
     "dotenv": "^17.2.3",
     "reflect-metadata": "^0.2.2"
   },
@@ -73,5 +76,10 @@
     "ts-jest": "^29.1.2",
     "tsc-alias": "^1.8.16",
     "typescript": "^5.3.3"
+  },
+  "peerDependenciesMeta": {
+    "esbuild": {
+      "optional": true
+    }
   }
 }