@lambda-kata/cdk 0.1.3-rc.85 → 0.1.3-rc.86

package/out/tsc/src/config-layer.d.ts

@@ -119,37 +119,6 @@ export declare const HANDLER_CONFIG_KEY = "original_js_handler";
  * The name of the compiled middleware file within the .kata directory.
  */
 export declare const MIDDLEWARE_FILE_NAME = "middleware.js";
-/**
- * Bootstrap handler module name.
- * The compiled .pyc is at src/python/dist/kata_bootstrap.pyc and is placed
- * in the config layer at /opt/python/kata_bootstrap.pyc so the Python 3.12
- * runtime resolves it via PYTHONPATH.
- *
- * Using a pre-compiled bootstrap handler prevents SnapStart snapshot failures
- * caused by import errors in the Lambda Kata Layer (C-bridge, Node.js binary, etc.).
- * Source: src/python/kata_bootstrap.py — compiled via `yarn build:python`.
- */
-export declare const BOOTSTRAP_HANDLER_MODULE = "kata_bootstrap";
-/**
- * Full handler path for the bootstrap handler.
- * Format: "<module>.<function>" as required by Lambda handler configuration.
- */
-export declare const BOOTSTRAP_HANDLER_PATH = "kata_bootstrap.handler";
-/**
- * Resolves the absolute path to the bootstrap handler .py source file.
- *
- * Two resolution paths:
- * 1. Production (bundled JS / npm package): out/dist/python/kata_bootstrap.py
- *    __dirname = out/dist/ → __dirname/python/kata_bootstrap.py
- * 2. Development (ts-jest / source): src/python/kata_bootstrap.py
- *    __dirname = src/ → __dirname/python/kata_bootstrap.py
- *
- * @returns Absolute path to kata_bootstrap.py
- * @throws Error if the source file is not found
- *
- * @internal
- */
-export declare function resolveBootstrapPyPath(): string;
 /**
  * Creates a Lambda Layer containing the kata configuration.
  *

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

@@ -24,8 +24,8 @@ export { resolveAccountId, resolveAccountIdWithSource, isValidAccountIdFormat, A
 export { resolveAccountIdSync, resolveAccountIdSyncWithSource, resolveRegionSync, SyncAccountResolutionError, SyncAccountResolutionResult, SyncAccountResolverOptions, } from './sync-account-resolver';
 export { kata, kataWithAccountId, applyTransformation, handleUnlicensed, isKataTransformed, getKataPromise, extractBundlePathFromHandler, KataWrapperOptions, KataResult, } from './kata-wrapper';
 export { SnapStartActivator, SnapStartActivatorProps, } from './snapstart-construct';
-export { activateSnapStart, handler as snapStartHandler, SnapStartActivationResult, SnapStartActivatorConfig, CustomResourceEvent, CustomResourceResponse, } from './snapstart-activator';
-export { createKataConfigLayer, generateConfigContent, resolveBootstrapPyPath, KataConfigLayerProps, CONFIG_DIR_NAME, CONFIG_FILE_NAME, HANDLER_CONFIG_KEY, BOOTSTRAP_HANDLER_MODULE, BOOTSTRAP_HANDLER_PATH, } from './config-layer';
+export { activateSnapStart, SnapStartActivationResult, SnapStartActivatorConfig, } from './snapstart-activator';
+export { createKataConfigLayer, generateConfigContent, KataConfigLayerProps, CONFIG_DIR_NAME, CONFIG_FILE_NAME, HANDLER_CONFIG_KEY, } from './config-layer';
 export { EnsureNodeRuntimeLayerOptions, EnsureNodeRuntimeLayerResult, NodeVersionInfo, LayerInfo, LayerSearchOptions, LayerRequirements, LayerCreationOptions, Logger, RuntimeDetector, LayerManager, ErrorCodes, NodeRuntimeLayerError, VersionCacheEntry, LayerMetadata, NodejsLayerDeploymentOptions, NodejsLayerDeploymentResult, MultiArchitectureDeploymentResult, } from './nodejs-layer-manager';
 export { DockerRuntimeDetector, DockerRuntimeDetectorOptions, } from './docker-runtime-detector';
 export { AWSLayerManager, AWSLayerManagerOptions, } from './aws-layer-manager';

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

@@ -1,7 +1,9 @@
 /**
  * SnapStart Activator - Custom Resource Handler
  *
- * Enables SnapStart on Lambda functions after deployment via CloudFormation Custom Resource.
+ * 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
@@ -9,11 +11,14 @@
  * 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 alias pointing to the new version — ALWAYS, regardless of snapshot outcome
+ * 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;
@@ -33,6 +38,9 @@ export interface CustomResourceEvent {
         AliasName?: string;
     };
 }
+/**
+ * Custom Resource response to CloudFormation.
+ */
 export interface CustomResourceResponse {
     Status: 'SUCCESS' | 'FAILED';
     Reason?: string;
@@ -47,43 +55,91 @@ export interface CustomResourceResponse {
         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 */ _prePublishDelayMs?: number;
-    /** @internal */ _retryDelayMs?: number;
+    /**
+     * @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;
 }
-/** @internal Exported for testability — tests can jest.spyOn to avoid real delays. */
+/**
+ * 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.
  *
- * Matches the proven deploy_lambda.py logic:
- * 1. Ensure function is Active
- * 2. Enable SnapStart (ApplyOn: PublishedVersions)
- * 3. Wait for configuration update
- * 4. Publish ONE version
- * 5. Poll until snapshot is Active, Failed, or timeout
- * 6. Create/update alias — ALWAYS, regardless of snapshot outcome
+ * 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.
  *
- * No retries. No throws on Failed. Alias is always created.
+ * @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>;
 /**
- * Custom Resource handler for CloudFormation.
+ * Lambda handler for CloudFormation Custom Resource.
  *
- * - Delete → SUCCESS immediately (no action)
- * - Create/Update → run activateSnapStart → SUCCESS with data
- * - On error + Update → SUCCESS (prevent rollback deadlock)
- * - On error + Create → FAILED
+ * 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

@@ -43,7 +43,7 @@ export interface SnapStartActivatorProps {
  * 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 — ALWAYS, regardless of snapshot outcome
+ * 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}.
@@ -107,12 +107,6 @@ export declare class SnapStartActivator extends Construct {
      *
      * This is a self-contained version of the snapstart-activator logic
      * that can be deployed as inline Lambda code.
-     *
-     * Matches the proven deploy_lambda.py reference:
-     * - ONE publish, poll, ALWAYS create alias regardless of snapshot outcome
-     * - No retries on Failed state
-     * - On Update errors → return SUCCESS (prevent rollback deadlock)
-     * - On Create errors → throw (return FAILED)
      */
     private generateHandlerCode;
 }

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@lambda-kata/cdk",
-  "version": "0.1.3-rc.85",
+  "version": "0.1.3-rc.86",
   "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",
   "scripts": {
-    "build:python": "python3 src/python/compile.py && mkdir -p out/dist/python && cp src/python/kata_bootstrap.py out/dist/python/kata_bootstrap.py",
-    "build": "rm -rf ./dist && rm -rf ./out && rm -rf ./lib && yarn run build:cdk && yarn run types && yarn run build:python",
+    "build": "rm -rf ./dist && rm -rf ./out && rm -rf ./lib && yarn run build:cdk && yarn run types",
     "types": "tsc --emitDeclarationOnly && tsc-alias",
     "build:cdk": "yarn run build:config && node dist/utils/build.js --target=cdk",
     "build:minify": "yarn run build:config && node dist/utils/build.js",

package/out/dist/python/kata_bootstrap.py

@@ -1,82 +0,0 @@
-"""
-Lambda Kata Bootstrap Handler
-
-Resilient entry point that delegates to lambdakata.optimized_handler
-from the Lambda Kata Layer. Ensures SnapStart snapshot creation succeeds
-by catching init errors gracefully.
-
-Copyright (C) 2025-present Raman Marozau, Work Target Insight Function.
-SPDX-License-Identifier: Apache-2.0
-"""
-
-import json
-import os
-import sys
-import traceback
-
-
-# ---------------------------------------------------------------------------
-# INIT PHASE — executed once during cold start / SnapStart snapshot creation
-# ---------------------------------------------------------------------------
-
-_real_handler = None
-_init_error = None
-_init_diagnostics = {}
-
-try:
-    _init_diagnostics = {
-        "python_version": sys.version,
-        "opt_contents": sorted(os.listdir("/opt")) if os.path.isdir("/opt") else [],
-        "opt_python_exists": os.path.isdir("/opt/python"),
-        "lambdakata_in_opt": (
-            os.path.isdir("/opt/lambdakata")
-            or os.path.isdir("/opt/python/lambdakata")
-        ),
-    }
-
-    from lambdakata.optimized_handler import lambda_handler as _real_handler  # type: ignore[import-untyped]
-
-except ImportError as exc:
-    _init_error = exc
-    _init_diagnostics["import_error"] = str(exc)
-    _init_diagnostics["traceback"] = traceback.format_exc()
-    print(
-        f"[Lambda Kata] WARNING: Failed to import lambdakata.optimized_handler: {exc}",
-        file=sys.stderr,
-    )
-
-except Exception as exc:  # noqa: BLE001 — intentional broad catch for resilience
-    _init_error = exc
-    _init_diagnostics["init_error"] = str(exc)
-    _init_diagnostics["error_type"] = type(exc).__name__
-    _init_diagnostics["traceback"] = traceback.format_exc()
-    print(
-        f"[Lambda Kata] WARNING: Init error: {type(exc).__name__}: {exc}",
-        file=sys.stderr,
-    )
-
-
-# ---------------------------------------------------------------------------
-# HANDLER
-# ---------------------------------------------------------------------------
-
-def handler(event, context):
-    """Delegate to the real Lambda Kata handler, or return diagnostics."""
-    if _real_handler is not None:
-        return _real_handler(event, context)
-
-    body = {
-        "error": "Lambda Kata runtime initialization failed",
-        "message": str(_init_error) if _init_error else "Unknown",
-        "error_type": type(_init_error).__name__ if _init_error else "Unknown",
-        "diagnostics": {
-            "lambdakata_in_opt": _init_diagnostics.get("lambdakata_in_opt", False),
-            "opt_python_exists": _init_diagnostics.get("opt_python_exists", False),
-            "opt_contents": _init_diagnostics.get("opt_contents", []),
-        },
-    }
-    print(
-        f"[Lambda Kata] Runtime not initialized: {json.dumps(body)}",
-        file=sys.stderr,
-    )
-    return {"statusCode": 503, "body": json.dumps(body)}