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

package/out/tsc/src/aws-layer-manager.d.ts

@@ -15,7 +15,8 @@
  * @module aws-layer-manager
  */
 import { LambdaClientConfig } from '@aws-sdk/client-lambda';
-import { LayerManager, LayerInfo, LayerSearchOptions, LayerRequirements, LayerCreationOptions, Logger } from './nodejs-layer-manager';
+import { S3ClientConfig } from '@aws-sdk/client-s3';
+import { LayerCreationOptions, LayerInfo, LayerManager, LayerRequirements, LayerSearchOptions, Logger, MultiArchitectureDeploymentResult, NodejsLayerDeploymentOptions, NodejsLayerDeploymentResult } from './nodejs-layer-manager';
 /**
  * Configuration options for AWSLayerManager.
  */
@@ -25,6 +26,11 @@ export interface AWSLayerManagerOptions {
      * If not provided, uses default AWS SDK configuration.
      */
     awsSdkConfig?: LambdaClientConfig;
+    /**
+     * AWS SDK configuration for S3 client.
+     * If not provided, uses the same configuration as Lambda client.
+     */
+    s3SdkConfig?: S3ClientConfig;
     /**
      * Logger for debugging and monitoring.
      * If not provided, uses createDefaultLogger().
@@ -64,6 +70,12 @@ export interface AWSLayerManagerOptions {
      * Default: 2
      */
     circuitBreakerSuccessThreshold?: number;
+    /**
+     * Enable S3 support for large layer uploads.
+     * If true, creates S3Client for handling layers >50MB.
+     * Default: true
+     */
+    enableS3Support?: boolean;
 }
 /**
  * AWS Lambda Layer Manager implementation using AWS SDK v3.
@@ -91,9 +103,10 @@ export interface AWSLayerManagerOptions {
  *   }
  * });
  * ```
-                */
+ */
 export declare class AWSLayerManager implements LayerManager {
     private readonly lambdaClient;
+    private readonly s3Client;
     private readonly logger;
     private readonly maxLayerAge;
     private readonly maxRetries;
@@ -170,6 +183,103 @@ export declare class AWSLayerManager implements LayerManager {
      * @throws NodeRuntimeLayerError if creation fails
      */
     private performLayerCreation;
+    /**
+     * Deploys a pre-built Node.js Lambda Layer from ZIP file.
+     *
+     * This method bypasses Docker binary extraction and deploys existing
+     * layer ZIP files directly to AWS Lambda. Handles large layers via S3
+     * temporary bucket upload with automatic cleanup.
+     *
+     * Process:
+     * 1. Validate input parameters and architecture
+     * 2. Search for existing layer ZIP files with fallback naming patterns
+     * 3. Read and validate layer ZIP file size
+     * 4. Deploy via direct upload (<50MB) or S3 upload (≥50MB)
+     * 5. Clean up temporary S3 resources if used
+     * 6. Return deployment result with layer ARN and metadata
+     *
+     * @param options - Deployment configuration
+     * @returns Promise resolving to deployment result
+     * @throws NodeRuntimeLayerError if deployment fails
+     */
+    deployNodejsLayer(options: NodejsLayerDeploymentOptions): Promise<NodejsLayerDeploymentResult>;
+    /**
+     * Deploys Node.js layers for all supported architectures.
+     *
+     * Attempts to deploy layers for both arm64 and x86_64 architectures,
+     * continuing on individual failures to maximize successful deployments.
+     * This matches the behavior of the Python deployment script.
+     *
+     * @param options - Base deployment configuration (architecture will be overridden)
+     * @returns Promise resolving to multi-architecture deployment results
+     */
+    deployAllArchitectures(options: Omit<NodejsLayerDeploymentOptions, 'architecture'>): Promise<MultiArchitectureDeploymentResult>;
+    /**
+     * Generates a standard layer name for the given architecture.
+     *
+     * @param architecture - Target architecture
+     * @returns Standard layer name following the pattern: nodejs-18-{architecture}
+     */
+    private generateLayerName;
+    /**
+     * Searches for layer ZIP files with fallback naming patterns.
+     *
+     * Implements the same search logic as the Python script with multiple
+     * naming conventions for maximum compatibility.
+     *
+     * @param architecture - Target architecture
+     * @param baseDirectory - Directory to search in
+     * @returns Promise resolving to ZIP file path or null if not found
+     */
+    private findLayerZipFile;
+    /**
+     * Deploys a large layer (>50MB) via S3 temporary bucket.
+     *
+     * Creates a temporary S3 bucket, uploads the layer, publishes from S3,
+     * and cleans up the bucket. Implements the same logic as the Python script.
+     *
+     * @param layerName - Name of the layer
+     * @param layerContent - ZIP file content
+     * @param architecture - Target architecture
+     * @param region - AWS region
+     * @param description - Optional layer description
+     * @param zipFilePath - Original ZIP file path for metadata
+     * @returns Promise resolving to deployment result
+     */
+    private deployLargeLayerViaS3;
+    /**
+     * Deploys a layer directly to Lambda (for layers <50MB).
+     *
+     * @param layerName - Name of the layer
+     * @param layerContent - ZIP file content
+     * @param architecture - Target architecture
+     * @param description - Optional layer description
+     * @param zipFilePath - Original ZIP file path for metadata
+     * @returns Promise resolving to deployment result
+     */
+    private deployLayerDirect;
+    /**
+     * Creates an S3 bucket for temporary layer storage.
+     *
+     * @param bucketName - Name of the bucket to create
+     * @param region - AWS region
+     */
+    private createS3Bucket;
+    /**
+     * Uploads layer content to S3.
+     *
+     * @param bucketName - S3 bucket name
+     * @param keyName - S3 object key
+     * @param layerContent - Layer ZIP content
+     */
+    private uploadLayerToS3;
+    /**
+     * Cleans up S3 resources (bucket and objects).
+     *
+     * @param bucketName - S3 bucket name
+     * @param keyName - S3 object key
+     */
+    private cleanupS3Resources;
     /**
      * Validates whether a layer meets the specified requirements.
      *
@@ -320,17 +430,42 @@ export declare class AWSLayerManager implements LayerManager {
     /**
      * Optimizes Node.js binary to reduce size while preserving functionality.
      *
-     * Applies size optimization techniques:
-     * 1. Strip debug symbols using 'strip' command (reduces size by 30-50%)
-     * 2. Verify binary functionality after optimization
-     * 3. Fallback to original binary if optimization fails
+     * Multi-stage optimization approach:
+     * 1. Strip debug symbols using 'strip' command (30-50% reduction)
+     * 2. UPX compression if still >50MB (50-70% additional reduction)
+     * 3. System Node.js replacement if still >60MB
+     * 4. Verify binary functionality after each stage
+     * 5. Fallback to original if within 250MB limit
      *
      * @param originalBinaryPath - Path to the original Node.js binary
      * @param tempDir - Temporary directory for optimization work
      * @returns Promise resolving to path of optimized binary
-     * @throws Error if optimization fails and fallback is not viable
+     * @throws Error if optimization fails and original exceeds 250MB limit
      */
     private optimizeNodeBinary;
+    /**
+     * Attempts strip-based optimization with progressive aggressiveness.
+     *
+     * @param originalBinaryPath - Path to original binary
+     * @param tempDir - Working directory
+     * @returns Path to stripped binary or original if stripping fails
+     */
+    private tryStripOptimization;
+    /**
+     * Attempts UPX compression optimization.
+     *
+     * @param binaryPath - Path to binary to compress
+     * @param tempDir - Working directory
+     * @returns Path to compressed binary or null if UPX unavailable/fails
+     */
+    private tryUPXOptimization;
+    /**
+     * Attempts to use system Node.js binary as replacement.
+     *
+     * @param tempDir - Working directory
+     * @returns Path to system Node.js copy or null if unavailable/unsuitable
+     */
+    private trySystemNodeReplacement;
     /**
      * Verifies that a Node.js binary is functional after optimization.
      *
@@ -341,14 +476,26 @@ export declare class AWSLayerManager implements LayerManager {
      * @throws Error if verification fails
      */
     private verifyNodeBinary;
+    /**
+     * Verifies Node.js binary with graceful fallback for spawn errors.
+     *
+     * This method attempts full verification but falls back to basic checks
+     * if spawn fails (e.g., error -8). This prevents blocking deployment for
+     * binaries that are valid but fail verification due to system issues.
+     *
+     * @param binaryPath - Path to the Node.js binary to verify
+     * @returns Promise resolving to verification result with success flag and optional error
+     */
+    private verifyNodeBinaryWithFallback;
     /**
      * Creates the proper Lambda Layer directory structure.
      *
      * Lambda Layers for Node.js binary should use minimal structure:
-     * - bin/node (not /opt/nodejs/bin/node)
+     * - bin/node (uncompressed binary)
+     * - bin/node.gz (compressed binary with decompression script)
      *
      * @param tempDir - Base temporary directory
-     * @param nodeBinaryPath - Path to the Node.js binary
+     * @param nodeBinaryPath - Path to the Node.js binary (may be compressed)
      * @returns Promise resolving to the layer directory path
      * @throws Error if directory creation fails
      */
@@ -374,7 +521,10 @@ export declare class AWSLayerManager implements LayerManager {
      */
     private calculateDirectorySize;
     /**
-     * Fallback ZIP creation using system zip command.
+     * Fallback ZIP creation using system zip command with streaming.
+     *
+     * This method uses the system 'zip' command which handles large files
+     * efficiently without loading them into memory.
      *
      * @param layerDir - Directory containing the layer contents
      * @param zipFilePath - Target ZIP file path
@@ -447,6 +597,9 @@ export declare class AWSLayerManager implements LayerManager {
     /**
      * Executes a system command with timeout and error handling.
      *
+     * Enhanced with EPIPE error handling to prevent broken pipe errors
+     * when child process terminates unexpectedly.
+     *
      * @param command - Command to execute
      * @param args - Command arguments
      * @param options - Execution options including working directory

package/out/tsc/src/docker-runtime-detector.d.ts

@@ -1,4 +1,4 @@
-import { RuntimeDetector, NodeVersionInfo, Logger } from './nodejs-layer-manager';
+import { Logger, NodeVersionInfo, RuntimeDetector } from './nodejs-layer-manager';
 /**
  * Configuration options for DockerRuntimeDetector.
  */

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

@@ -21,9 +21,12 @@ export { KataProps, LicensingResponse, TransformationConfig } from './types';
 export { LicensingService, HttpLicensingService, createLicensingService, isValidAccountId, } from './licensing';
 export { MockLicensingService, createMockLicensingService, } from './mock-licensing';
 export { resolveAccountId, resolveAccountIdWithSource, isValidAccountIdFormat, AccountResolutionError, AccountResolutionResult, AccountResolverOptions, } from './account-resolver';
-export { kata, kataWithAccountId, applyTransformation, handleUnlicensed, isKataTransformed, getKataPromise, KataWrapperOptions, KataResult, } from './kata-wrapper';
+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, 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, } from './nodejs-layer-manager';
+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';
 export { NoOpLogger, ConsoleLogger, createDefaultLogger, OperationTimer, } from './logger';

package/out/tsc/src/kata-wrapper.d.ts

@@ -2,6 +2,7 @@ import { Function as LambdaFunction } from 'aws-cdk-lib/aws-lambda';
 import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
 import { KataProps, LicensingResponse, TransformationConfig } from './types';
 import { LicensingService } from './licensing';
+import { LicensingService as NativeLicensingServiceInterface } from '@lambda-kata/licensing';
 /**
  * Options for the kata wrapper, extending KataProps with internal options.
  */
@@ -12,6 +13,12 @@ export interface KataWrapperOptions extends KataProps {
      * @internal
      */
     licensingService?: LicensingService;
+    /**
+     * Optional: Custom synchronous licensing service for testing.
+     * Must implement checkEntitlementSync(accountId: string): LicensingResponse
+     * @internal
+     */
+    syncLicensingService?: NativeLicensingServiceInterface;
     /**
      * Custom bundle path.
      * If not specified, uses the default /opt/js_runtime/bundle.js
@@ -47,6 +54,15 @@ export interface KataWrapperOptions extends KataProps {
     handlerResolver?: (bundle: unknown, context: {
         originalHandler: string;
     }) => Function;
+    /**
+     * Skip Node.js runtime layer deployment.
+     * When true, only the core transformation is applied without deploying
+     * the Node.js runtime layer. Useful for faster synthesis when the layer
+     * is already deployed or not needed.
+     *
+     * Default: false
+     */
+    skipNodejsLayer?: boolean;
 }
 /**
  * Result of the kata transformation.
@@ -68,12 +84,15 @@ export interface KataResult {
 /**
  * Transforms a Node.js Lambda function to run via the Lambda Kata runtime.
  *
- * This function performs the following steps:
+ * This function performs the following steps SYNCHRONOUSLY:
  * 1. Resolves the target AWS account ID
  * 2. Calls the licensing service to validate entitlement
  * 3. If entitled, applies transformations (runtime, handler, layer, env vars)
  * 4. If not entitled, handles according to unlicensedBehavior option
  *
+ * IMPORTANT: This function is SYNCHRONOUS to work correctly with CDK synthesis.
+ * All licensing checks and transformations are applied immediately before returning.
+ *
  * @param lambda - The Node.js Lambda function to transform (NodejsFunction or Function)
  * @param props - Optional configuration for the transformation
  * @returns The same Lambda construct (modified if licensed)
@@ -110,12 +129,37 @@ export declare function kata<T extends NodejsFunction | LambdaFunction>(lambda:
  *
  * @param lambda - The Node.js Lambda function to transform
  * @param accountId - The AWS account ID to use for licensing check
+ * @param region - The AWS region for deployment (from Stack.of(lambda).region)
  * @param props - Optional configuration for the transformation
  * @returns Promise resolving to the transformation result
  *
  * @internal
  */
-export declare function kataWithAccountId<T extends NodejsFunction | LambdaFunction>(lambda: T, accountId: string, props?: KataWrapperOptions): Promise<KataResult>;
+export declare function kataWithAccountId<T extends NodejsFunction | LambdaFunction>(lambda: T, accountId: string, region: string, props?: KataWrapperOptions): Promise<KataResult>;
+/**
+ * Lambda task root directory where function code is deployed.
+ * This is the standard AWS Lambda directory for function code.
+ *
+ * @deprecated C-lang Lambda Kata makes its own decision for either absolute or relative path
+ */
+/**
+ * Extracts the bundle path from a Lambda handler string.
+ *
+ * The handler format is "<module>.<function>" or "<path/module>.<function>".
+ * This function extracts the module path, appends ".js" extension,
+ * and prepends the Lambda task root directory (/var/task).
+ *
+ * @param handler - The Lambda handler string (e.g., "index.handler", "src/app.myHandler")
+ * @returns The absolute bundle path in Lambda environment (e.g., "/var/task/index.js")
+ *
+ * @example
+ * extractBundlePathFromHandler("index.handler") // => "/var/task/index.js"
+ * extractBundlePathFromHandler("src/app.myHandler") // => "/var/task/src/app.js"
+ * extractBundlePathFromHandler("dist/handlers/api.handler") // => "/var/task/dist/handlers/api.js"
+ *
+ * @internal
+ */
+export declare function extractBundlePathFromHandler(handler: string): string;
 /**
  * Gets the original runtime from a Lambda function before transformation.
  *
@@ -143,32 +187,6 @@ export declare function isNodejsRuntime(lambda: NodejsFunction | LambdaFunction)
  * @internal
  */
 export declare function getLambdaArchitecture(lambda: NodejsFunction | LambdaFunction): 'x86_64' | 'arm64';
-/**
- * Applies the Lambda Kata transformation to a Lambda function.
- *
- * This function modifies the Lambda construct in-place to:
- * 1. Create and attach a config layer with the original handler path
- * 2. Change the runtime to Python 3.12
- * 3. Set the handler to the Lambda Kata handler
- * 4. Attach the customer-specific Lambda Layer
- * 5. Add additional environment variables for the Lambda Kata runtime
- *
- * @param lambda - The Lambda function to transform
- * @param config - The transformation configuration
- *
- * @remarks
- * Validates: Requirements 2.2, 2.3, 2.4, 3.3, 3.4, 4.1, 4.2, 5.4
- * - 2.2: THE kata_Wrapper SHALL change the Lambda runtime from Node.js to Python 3.12
- * - 2.3: THE kata_Wrapper SHALL set the Lambda handler to `lambdakata.optimized_handler.lambda_handler`
- * - 2.4: THE kata_Wrapper SHALL attach the customer-specific Lambda_Layer ARN to the Lambda
- * - 3.3: THE kata_Wrapper SHALL attach the Config_Layer to the transformed Lambda
- * - 3.4: THE kata_Wrapper SHALL NOT set the `JS_HANDLER_PATH` environment variable
- * - 4.1: THE kata_Wrapper SHALL NOT add the `JS_HANDLER_PATH` environment variable to transformed Lambdas
- * - 4.2: WHEN `bundlePath` is specified, THE kata_Wrapper SHALL write it to the Config_Layer JSON as `bundle_path`
- * - 5.4: THE compiled middleware SHALL be included in the Config_Layer at `/opt/.kata/middleware.js`
- *
- * @internal
- */
 export declare function applyTransformation(lambda: NodejsFunction | LambdaFunction, config: TransformationConfig): void;
 /**
  * Handles the case when an account is not licensed.

package/out/tsc/src/mock-licensing.d.ts

@@ -68,6 +68,10 @@ export declare class MockLicensingService implements LicensingService {
      * Custom error message when simulating service errors.
      */
     private serviceErrorMessage;
+    /**
+     * Flag to simulate entitled response without layerArn (service issue).
+     */
+    private simulateEntitledWithoutLayerArn;
     /**
      * Sets an account as entitled with a specific Layer ARN.
      *
@@ -147,6 +151,20 @@ export declare class MockLicensingService implements LicensingService {
      * ```
      */
     setSimulateServiceError(simulate: boolean, errorMessage?: string): void;
+    /**
+     * Configures the mock to simulate entitled response without layerArn.
+     * This simulates a licensing service issue where the account is entitled
+     * but the service fails to return the layer ARN.
+     *
+     * @param simulate - Whether to simulate entitled without layerArn
+     *
+     * @example
+     * ```typescript
+     * // Simulate service returning entitled: true but no layerArn
+     * mockService.setSimulateEntitledWithoutLayerArn(true);
+     * ```
+     */
+    setSimulateEntitledWithoutLayerArn(simulate: boolean): void;
     /**
      * Check if an AWS account is entitled to use Lambda Kata.
      *

package/out/tsc/src/nodejs-layer-manager.d.ts

@@ -275,6 +275,27 @@ export interface LayerManager {
      * @throws NodeRuntimeLayerError if creation fails
      */
     createNodeLayer(options: LayerCreationOptions): Promise<LayerInfo>;
+    /**
+     * Deploys a pre-built Node.js Lambda Layer from ZIP file.
+     *
+     * This method bypasses Docker binary extraction and deploys existing
+     * layer ZIP files directly to AWS Lambda. Handles large layers via S3.
+     *
+     * @param options - Deployment configuration
+     * @returns Promise resolving to deployment result
+     * @throws NodeRuntimeLayerError if deployment fails
+     */
+    deployNodejsLayer(options: NodejsLayerDeploymentOptions): Promise<NodejsLayerDeploymentResult>;
+    /**
+     * Deploys Node.js layers for all supported architectures.
+     *
+     * Attempts to deploy layers for both arm64 and x86_64 architectures,
+     * continuing on individual failures to maximize successful deployments.
+     *
+     * @param options - Base deployment configuration (architecture will be overridden)
+     * @returns Promise resolving to multi-architecture deployment results
+     */
+    deployAllArchitectures(options: Omit<NodejsLayerDeploymentOptions, 'architecture'>): Promise<MultiArchitectureDeploymentResult>;
     /**
      * Validates whether a layer meets the specified requirements.
      *
@@ -417,3 +438,110 @@ export interface LayerMetadata {
      */
     licenseInfo?: string;
 }
+/**
+ * Configuration options for deploying pre-built Node.js Lambda Layers.
+ *
+ * Used to deploy existing layer ZIP files instead of creating layers from Docker images.
+ * This bypasses the binary extraction process that can fail with large Node.js binaries.
+ */
+export interface NodejsLayerDeploymentOptions {
+    /**
+     * The AWS region where the layer should be deployed.
+     */
+    region: string;
+    /**
+     * Optional AWS profile name for authentication.
+     * If not provided, uses default AWS credentials.
+     */
+    profile?: string;
+    /**
+     * The target architecture for deployment.
+     * If not specified, defaults to 'arm64'.
+     */
+    architecture?: 'arm64' | 'x86_64';
+    /**
+     * Base directory to search for layer ZIP files.
+     * Defaults to current working directory.
+     */
+    baseDirectory?: string;
+    /**
+     * Custom layer name override.
+     * If not provided, uses standard naming: nodejs-18-{architecture}
+     */
+    layerName?: string;
+    /**
+     * Custom layer description.
+     * If not provided, generates standard description.
+     */
+    description?: string;
+}
+/**
+ * Result of Node.js layer deployment operation.
+ *
+ * Contains information about the deployed layer and deployment metadata.
+ */
+export interface NodejsLayerDeploymentResult {
+    /**
+     * The full ARN of the deployed layer version.
+     */
+    layerVersionArn: string;
+    /**
+     * The base ARN of the layer (without version).
+     */
+    layerArn: string;
+    /**
+     * The name of the deployed layer.
+     */
+    layerName: string;
+    /**
+     * The version number of the deployed layer.
+     */
+    version: number;
+    /**
+     * The architecture of the deployed layer.
+     */
+    architecture: 'arm64' | 'x86_64';
+    /**
+     * The size of the deployed layer ZIP file in bytes.
+     */
+    layerSize: number;
+    /**
+     * The path to the ZIP file that was deployed.
+     */
+    zipFilePath: string;
+    /**
+     * Whether the layer was uploaded via S3 (true) or direct upload (false).
+     */
+    uploadedViaS3: boolean;
+}
+/**
+ * Result of deploying layers for all architectures.
+ *
+ * Contains deployment results for each architecture attempted.
+ */
+export interface MultiArchitectureDeploymentResult {
+    /**
+     * Deployment results by architecture.
+     * Key is architecture name, value is result or null if deployment failed.
+     */
+    results: Record<'arm64' | 'x86_64', NodejsLayerDeploymentResult | null>;
+    /**
+     * Overall success status.
+     * True if at least one architecture deployed successfully.
+     */
+    success: boolean;
+    /**
+     * Summary of successful deployments.
+     */
+    successful: Array<{
+        architecture: 'arm64' | 'x86_64';
+        layerVersionArn: string;
+    }>;
+    /**
+     * Summary of failed deployments.
+     */
+    failed: Array<{
+        architecture: 'arm64' | 'x86_64';
+        error: string;
+    }>;
+}