@lambda-kata/cdk 0.1.3-rc.2 → 0.1.3-rc.21

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

@@ -0,0 +1,640 @@
+/**
+ * AWS Lambda Layer Manager with SDK v3 Integration
+ *
+ * This module provides AWS Lambda Layer management functionality using AWS SDK v3.
+ * It handles layer creation, searching, and compatibility validation for Node.js
+ * runtime layers used by Lambda Kata.
+ *
+ * Key features:
+ * - AWS SDK v3 Lambda client integration with configurable options
+ * - Automatic pagination handling for layer listing operations
+ * - Layer compatibility validation based on Node.js version and architecture
+ * - Comprehensive error handling with retry logic
+ * - Idempotent operations to prevent duplicate layer creation
+ *
+ * @module aws-layer-manager
+ */
+import { LambdaClientConfig } from '@aws-sdk/client-lambda';
+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.
+ */
+export interface AWSLayerManagerOptions {
+    /**
+     * AWS SDK configuration for Lambda client.
+     * 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().
+     */
+    logger?: Logger;
+    /**
+     * Maximum age in milliseconds for layers to be considered fresh.
+     * Layers older than this may be recreated.
+     * Default: 7 days (604800000ms)
+     */
+    maxLayerAge?: number;
+    /**
+     * Maximum number of retries for AWS API operations.
+     * Default: 3
+     */
+    maxRetries?: number;
+    /**
+     * Base delay in milliseconds for exponential backoff.
+     * Default: 1000ms (1 second)
+     */
+    retryBaseDelay?: number;
+    /**
+     * Circuit breaker failure threshold.
+     * Number of consecutive failures before opening the circuit.
+     * Default: 5
+     */
+    circuitBreakerFailureThreshold?: number;
+    /**
+     * Circuit breaker timeout in milliseconds.
+     * How long to wait before transitioning from OPEN to HALF_OPEN.
+     * Default: 60000ms (1 minute)
+     */
+    circuitBreakerTimeout?: number;
+    /**
+     * Circuit breaker success threshold for HALF_OPEN state.
+     * Number of consecutive successes needed to close the circuit.
+     * 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.
+ *
+ * Provides comprehensive layer management functionality including:
+ * - Layer searching with pagination support
+ * - Layer compatibility validation
+ * - Layer creation with proper metadata
+ * - Error handling with exponential backoff retry logic
+ * - Circuit breaker pattern for AWS API resilience
+ * - Concurrent operation coordination to prevent duplicate layer creation
+ *
+ * @example
+ * ```typescript
+ * const manager = new AWSLayerManager({
+ *   awsSdkConfig: { region: 'us-east-1' },
+ *   logger: new ConsoleLogger()
+ * });
+ *
+ * const layer = await manager.findExistingLayer({
+ *   layerName: 'lambda-kata-nodejs-nodejs20.x-x86_64',
+ *   requirements: {
+ *     nodeVersion: '20.10.0',
+ *     architecture: 'x86_64'
+ *   }
+ * });
+ * ```
+ */
+export declare class AWSLayerManager implements LayerManager {
+    private readonly lambdaClient;
+    private readonly s3Client;
+    private readonly logger;
+    private readonly maxLayerAge;
+    private readonly maxRetries;
+    private readonly retryBaseDelay;
+    private readonly circuitBreaker;
+    /**
+     * Map of layer names to in-progress creation operations.
+     * Used to coordinate concurrent calls and prevent duplicate layer creation.
+     */
+    private readonly layerCreationLocks;
+    /**
+     * AWS Lambda Layer size limits (in bytes).
+     * These are AWS service limits that cannot be exceeded.
+     */
+    private static readonly MAX_LAYER_SIZE_UNZIPPED;
+    private static readonly MAX_LAYER_SIZE_ZIPPED;
+    /**
+     * Docker operation timeout in milliseconds.
+     */
+    private static readonly DOCKER_TIMEOUT;
+    constructor(options?: AWSLayerManagerOptions);
+    /**
+     * Searches for an existing compatible Node.js layer.
+     *
+     * Uses AWS SDK v3 pagination to efficiently search through all layers
+     * in the account and region. Validates compatibility based on layer
+     * metadata and requirements.
+     *
+     * @param options - Search criteria and requirements
+     * @returns Promise resolving to layer info if found, null otherwise
+     * @throws NodeRuntimeLayerError if search fails
+     */
+    findExistingLayer(options: LayerSearchOptions): Promise<LayerInfo | null>;
+    /**
+     * Creates a new Node.js Lambda Layer with concurrent operation coordination.
+     *
+     * This method extracts the Node.js binary from the corresponding AWS Lambda
+     * Docker image, packages it in the proper Lambda Layer directory structure,
+     * and publishes it to AWS Lambda with appropriate metadata.
+     *
+     * Enhanced with concurrent operation coordination to prevent duplicate layer
+     * creation when multiple calls are made with identical parameters. If a layer
+     * creation is already in progress for the same layer name, subsequent calls
+     * will wait for the existing operation to complete rather than starting a
+     * duplicate operation.
+     *
+     * Process:
+     * 1. Check for existing in-progress layer creation operation
+     * 2. If operation exists, wait for its completion
+     * 3. If no operation exists, start new layer creation with lock
+     * 4. Create temporary directory for layer contents
+     * 5. Extract Node.js binary from Docker container
+     * 6. Create proper Lambda Layer directory structure (/opt/nodejs/bin/)
+     * 7. Create ZIP archive with correct permissions
+     * 8. Validate size limits
+     * 9. Publish to AWS Lambda
+     * 10. Clean up temporary files and release lock
+     *
+     * Enhanced with comprehensive resource cleanup on failure to prevent orphaned resources.
+     *
+     * @param options - Layer creation configuration
+     * @returns Promise resolving to information about the created layer
+     * @throws NodeRuntimeLayerError if creation fails
+     */
+    createNodeLayer(options: LayerCreationOptions): Promise<LayerInfo>;
+    /**
+     * Performs the actual layer creation operation without concurrent coordination.
+     *
+     * This is the core layer creation logic extracted from the original createNodeLayer
+     * method to separate concerns between concurrent coordination and actual creation.
+     *
+     * @param options - Layer creation configuration
+     * @returns Promise resolving to information about the created layer
+     * @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.
+     *
+     * Checks layer compatibility based on:
+     * - Node.js version exact match
+     * - Architecture compatibility
+     * - Layer age (if maxAge is specified in requirements)
+     *
+     * @param layer - The layer to validate
+     * @param requirements - The requirements to check against
+     * @returns true if the layer is compatible, false otherwise
+     */
+    validateLayerCompatibility(layer: LayerInfo, requirements: LayerRequirements): boolean;
+    /**
+     * Lists layers by name using AWS SDK v3 pagination with retry logic.
+     *
+     * Efficiently searches through all layers in the account and region
+     * to find layers matching the specified name pattern. Uses retry logic
+     * to handle transient pagination failures.
+     *
+     * @param layerName - The layer name to search for
+     * @returns Promise resolving to array of matching layers
+     * @throws Error if AWS API operations fail
+     */
+    private listLayersByName;
+    /**
+     * Gets detailed information about a specific layer version.
+     *
+     * Retrieves layer metadata and extracts Node.js version and architecture
+     * information from the layer description or other metadata.
+     *
+     * @param layerName - The name of the layer
+     * @param version - The version number of the layer
+     * @returns Promise resolving to LayerInfo
+     * @throws Error if layer information cannot be retrieved
+     */
+    private getLayerInfo;
+    /**
+     * Parses layer metadata to extract Node.js version and architecture.
+     *
+     * Attempts to extract information from layer description or falls back
+     * to parsing the layer name if description doesn't contain the required data.
+     *
+     * @param description - The layer description
+     * @param layerName - The layer name as fallback
+     * @returns Object containing nodeVersion and architecture
+     */
+    private parseLayerMetadata;
+    /**
+     * Executes an AWS API operation with exponential backoff retry logic and circuit breaker protection.
+     *
+     * Implements retry logic for transient AWS API failures with exponential
+     * backoff and jitter to avoid thundering herd problems. Uses circuit breaker
+     * pattern to prevent cascading failures during AWS service outages.
+     *
+     * @param operation - The async operation to execute
+     * @returns Promise resolving to the operation result
+     * @throws Error if all retries are exhausted or circuit breaker is open
+     */
+    private executeWithRetry;
+    /**
+     * Determines if an error is retryable.
+     *
+     * @param error - The error to check
+     * @returns true if the error is retryable, false otherwise
+     */
+    private isRetryableError;
+    /**
+     * Checks if an error is a network-related error that should be retried.
+     *
+     * @param error - The error to check
+     * @returns true if it's a retryable network error
+     */
+    private isNetworkError;
+    /**
+     * Calculates retry delay with exponential backoff and jitter.
+     *
+     * @param attempt - The current attempt number (0-based)
+     * @returns Delay in milliseconds
+     */
+    private calculateRetryDelay;
+    /**
+     * Sleeps for the specified number of milliseconds.
+     *
+     * @param ms - Milliseconds to sleep
+     * @returns Promise that resolves after the delay
+     */
+    private sleep;
+    /**
+     * Gets the current circuit breaker state for monitoring and debugging.
+     *
+     * @returns Object containing circuit breaker state information
+     */
+    getCircuitBreakerState(): {
+        state: string;
+        failureCount: number;
+        successCount: number;
+    };
+    /**
+     * Gets the current concurrent operation state for monitoring and debugging.
+     *
+     * @returns Object containing information about in-progress layer creation operations
+     */
+    getConcurrentOperationState(): {
+        activeOperations: number;
+        operations: Array<{
+            layerName: string;
+            startTime: number;
+            duration: number;
+            waiters: number;
+            nodeVersion: string;
+            architecture: string;
+        }>;
+    };
+    /**
+     * Destroys the AWS Lambda client and cleans up resources.
+     *
+     * Should be called when the manager is no longer needed to prevent
+     * resource leaks. Also cleans up any remaining concurrent operation locks.
+     */
+    destroy(): void;
+    /**
+     * Creates a temporary directory for layer creation operations.
+     *
+     * @returns Promise resolving to the temporary directory path
+     * @throws Error if directory creation fails
+     */
+    private createTempDirectory;
+    /**
+     * Extracts Node.js binary from AWS Lambda Docker image with resource tracking.
+     *
+     * Uses ONLY AWS Lambda Docker images to extract the Node.js binary from the
+     * official Lambda runtime environment. This ensures compatibility with the
+     * Lambda execution environment while extracting only the minimal binary needed.
+     *
+     * CRITICAL: Uses ONLY AWS Lambda Docker images as required by user specifications.
+     * Docker image format: public.ecr.aws/lambda/nodejs:{version}-{arch}
+     * Extracts ONLY: /var/lang/bin/node
+     *
+     * @param nodeVersion - The Node.js version (e.g., "20.10.0")
+     * @param architecture - The target architecture
+     * @param tempDir - Temporary directory for extraction
+     * @param resourceTracker - Resource tracker for cleanup
+     * @returns Promise resolving to the path of the extracted binary
+     * @throws NodeRuntimeLayerError if extraction fails
+     */
+    private extractNodeBinaryFromDockerWithTracking;
+    /**
+     * Optimizes Node.js binary to reduce size while preserving functionality.
+     *
+     * 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 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.
+     *
+     * Runs basic Node.js commands to ensure the binary works correctly.
+     * This prevents shipping broken binaries after optimization.
+     *
+     * @param binaryPath - Path to the Node.js binary to verify
+     * @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 (uncompressed binary)
+     * - bin/node.gz (compressed binary with decompression script)
+     *
+     * @param tempDir - Base temporary directory
+     * @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
+     */
+    private createLayerDirectoryStructure;
+    /**
+     * Creates a ZIP archive of the layer contents with compression optimization.
+     *
+     * Uses Python's zipfile module to create a properly compressed ZIP file with
+     * file permissions preserved for the Node.js binary. Implements compression
+     * optimization to minimize storage and transfer costs.
+     *
+     * @param layerDir - Directory containing the layer contents
+     * @param layerName - Name of the layer (used for ZIP filename)
+     * @returns Promise resolving to the ZIP file path
+     * @throws Error if ZIP creation fails
+     */
+    private createLayerZipArchive;
+    /**
+     * Calculates the total size of all files in a directory.
+     *
+     * @param dirPath - Directory path to analyze
+     * @returns Promise resolving to total size in bytes
+     */
+    private calculateDirectorySize;
+    /**
+     * Fallback ZIP creation using system zip command.
+     *
+     * @param layerDir - Directory containing the layer contents
+     * @param zipFilePath - Target ZIP file path
+     * @returns Promise resolving to the ZIP file path
+     * @throws Error if ZIP creation fails
+     */
+    private createZipFallback;
+    /**
+     * Validates that the layer ZIP file meets AWS size limits.
+     *
+     * AWS Lambda has strict size limits for layers:
+     * - 50MB for zipped layer
+     * - 250MB for unzipped layer
+     *
+     * Enhanced to check both zipped and unzipped sizes with comprehensive
+     * error reporting and optimization suggestions.
+     *
+     * @param zipFilePath - Path to the ZIP file
+     * @throws NodeRuntimeLayerError if size limits are exceeded
+     */
+    private preValidateLayerContent;
+    /**
+     * Validates layer size limits after ZIP creation.
+     *
+     * @param zipFilePath - Path to the ZIP file
+     * @throws NodeRuntimeLayerError if size limits are exceeded
+     */
+    private validateLayerSize;
+    /**
+     * Calculates the unzipped size of a ZIP file by examining its contents.
+     *
+     * Uses Python's zipfile module to read ZIP metadata and calculate
+     * the total uncompressed size without extracting files.
+     *
+     * @param zipFilePath - Path to the ZIP file
+     * @returns Promise resolving to unzipped size in bytes
+     * @throws Error if size calculation fails
+     */
+    private calculateUnzippedSize;
+    /**
+     * Publishes the layer to AWS Lambda.
+     *
+     * Uses the AWS SDK v3 Lambda client to publish the layer with proper
+     * metadata including compatible runtimes and architectures.
+     *
+     * @param options - Layer creation options
+     * @param zipFilePath - Path to the ZIP file
+     * @returns Promise resolving to LayerInfo
+     * @throws NodeRuntimeLayerError if publishing fails
+     */
+    private publishLayerToAWS;
+    /**
+     * Executes a Docker command with timeout and error handling.
+     *
+     * @param args - Docker command arguments
+     * @returns Promise that resolves when command completes successfully
+     * @throws Error if command fails
+     */
+    private executeDockerCommand;
+    /**
+     * Executes a system command with timeout and error handling, capturing output.
+     *
+     * @param command - Command to execute
+     * @param args - Command arguments
+     * @param options - Execution options including working directory
+     * @returns Promise resolving to command output (stdout and stderr)
+     * @throws Error if command fails
+     */
+    private executeCommandWithOutput;
+    /**
+     * Executes a system command with timeout and error handling.
+     *
+     * @param command - Command to execute
+     * @param args - Command arguments
+     * @param options - Execution options including working directory
+     * @returns Promise that resolves when command completes successfully
+     * @throws Error if command fails
+     */
+    private executeCommand;
+    /**
+     * Legacy cleanup method for backward compatibility.
+     *
+     * @deprecated Use performComprehensiveCleanup with ResourceTracker instead
+     * @param tempDir - Temporary directory to remove (if exists)
+     * @param zipFilePath - ZIP file to remove (if exists)
+     */
+    private cleanupTempResources;
+    /**
+     * Legacy Docker extraction method for backward compatibility.
+     *
+     * @deprecated Use extractNodeBinaryFromDockerWithTracking instead
+     */
+    private extractNodeBinaryFromDocker;
+    /**
+     * Creates an enhanced error with cleanup context preservation.
+     *
+     * Preserves the original error while adding context about the layer creation
+     * operation that failed. This maintains debugging capability while providing
+     * additional context for troubleshooting.
+     *
+     * @param originalError - The original error that occurred
+     * @param options - Layer creation options for context
+     * @returns Enhanced NodeRuntimeLayerError with preserved context
+     */
+    private createEnhancedError;
+    /**
+     * Performs comprehensive cleanup of all tracked resources.
+     *
+     * Cleans up Docker containers, temporary directories, and ZIP files.
+     * Cleanup failures are logged as warnings but do not prevent the cleanup
+     * of other resources or mask the original error.
+     *
+     * @param resourceTracker - Tracker containing all resources to clean up
+     */
+    private performComprehensiveCleanup;
+}