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

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

@@ -0,0 +1,168 @@
+import { Logger, NodeVersionInfo, RuntimeDetector } from './nodejs-layer-manager';
+/**
+ * Configuration options for DockerRuntimeDetector.
+ */
+export interface DockerRuntimeDetectorOptions {
+    /**
+     * Cache TTL in milliseconds. Default: 1 hour (3600000ms)
+     */
+    cacheTtl?: number;
+    /**
+     * Docker command timeout in milliseconds. Default: 60 seconds (60000ms)
+     */
+    dockerTimeout?: number;
+    /**
+     * Logger for debugging and monitoring. Default: createDefaultLogger()
+     */
+    logger?: Logger;
+    /**
+     * Whether to enable fallback to known version mappings when Docker fails.
+     * Default: true
+     */
+    enableFallback?: boolean;
+}
+/**
+ * Docker-based implementation of RuntimeDetector.
+ *
+ * Uses official AWS Lambda runtime Docker images to detect exact Node.js versions.
+ * Implements caching to avoid repeated Docker operations and provides fallback
+ * version mappings when Docker is unavailable.
+ *
+ * @example
+ * ```typescript
+ * const detector = new DockerRuntimeDetector();
+ * const versionInfo = await detector.detectNodeVersion('nodejs20.x', 'x86_64');
+ * console.log(`Node.js version: ${versionInfo.version}`);
+ * ```
+ */
+export declare class DockerRuntimeDetector implements RuntimeDetector {
+    private readonly versionCache;
+    private readonly cacheTtl;
+    private readonly dockerTimeout;
+    private readonly logger;
+    private readonly enableFallback;
+    /**
+     * Known fallback version mappings for when Docker is unavailable.
+     * These are based on AWS Lambda runtime documentation and should be
+     * updated when AWS releases new runtime versions.
+     */
+    private static readonly FALLBACK_VERSIONS;
+    /**
+     * Supported AWS Lambda Node.js runtimes.
+     */
+    private static readonly SUPPORTED_RUNTIMES;
+    /**
+     * Supported architectures.
+     */
+    private static readonly SUPPORTED_ARCHITECTURES;
+    constructor(options?: DockerRuntimeDetectorOptions);
+    /**
+     * Detects the exact Node.js version for a given runtime and architecture.
+     *
+     * First checks the cache for existing version information. If not cached or expired,
+     * attempts to detect the version using Docker. Falls back to known version mappings
+     * if Docker operations fail and fallback is enabled.
+     *
+     * @param runtimeName - The AWS Lambda runtime (e.g., "nodejs20.x")
+     * @param architecture - The target architecture ("x86_64" or "arm64")
+     * @returns Promise resolving to Node.js version information
+     * @throws NodeRuntimeLayerError if detection fails
+     */
+    detectNodeVersion(runtimeName: string, architecture: string): Promise<NodeVersionInfo>;
+    /**
+     * Validates input parameters for runtime name and architecture.
+     *
+     * @param runtimeName - The runtime name to validate
+     * @param architecture - The architecture to validate
+     * @throws NodeRuntimeLayerError if inputs are invalid
+     */
+    private validateInputs;
+    /**
+     * Retrieves cached version information if available and not expired.
+     *
+     * @param cacheKey - The cache key to look up
+     * @returns Cached version entry if valid, null otherwise
+     */
+    private getCachedVersion;
+    /**
+     * Caches version information with TTL.
+     *
+     * @param cacheKey - The cache key to store under
+     * @param versionInfo - The version information to cache
+     */
+    private cacheVersion;
+    /**
+     * Detects Node.js version using Docker by pulling AWS Lambda runtime image
+     * and executing `node --version` within a container.
+     *
+     * @param runtimeName - The AWS Lambda runtime name
+     * @param architecture - The target architecture
+     * @returns Promise resolving to version information
+     * @throws NodeRuntimeLayerError if Docker operations fail
+     */
+    private detectVersionFromDocker;
+    /**
+     * Builds the Docker image name for AWS Lambda runtime.
+     *
+     * @param runtimeName - The AWS Lambda runtime name (e.g., "nodejs20.x")
+     * @param architecture - The target architecture
+     * @returns Docker image name (e.g., "public.ecr.aws/lambda/nodejs:20-x86_64")
+     */
+    private buildDockerImageName;
+    /**
+     * Checks if Docker image exists locally before pulling.
+     *
+     * @param dockerImage - The Docker image to check
+     * @returns Promise<boolean> - true if image exists locally
+     */
+    private checkDockerImageExists;
+    /**
+     * Pulls a Docker image using the docker pull command.
+     * Optimized to skip pull if image already exists locally.
+     *
+     * @param dockerImage - The Docker image to pull
+     * @returns Promise that resolves when the image is pulled
+     * @throws Error if docker pull fails
+     */
+    private pullDockerImage;
+    /**
+     * Extracts Node.js version by running `node --version` in a Docker container.
+     *
+     * @param dockerImage - The Docker image to run
+     * @returns Promise resolving to the Node.js version string
+     * @throws Error if container execution fails
+     */
+    private extractNodeVersionFromContainer;
+    /**
+     * Validates that a version string follows semantic versioning format.
+     *
+     * @param version - The version string to validate
+     * @returns true if the version is valid, false otherwise
+     */
+    private isValidSemanticVersion;
+    /**
+     * Provides fallback version information when Docker detection fails.
+     *
+     * @param runtimeName - The AWS Lambda runtime name
+     * @param architecture - The target architecture
+     * @returns NodeVersionInfo with fallback version
+     * @throws NodeRuntimeLayerError if no fallback is available
+     */
+    private getFallbackVersion;
+    /**
+     * Clears the version cache.
+     * Useful for testing or when cache invalidation is needed.
+     */
+    clearCache(): void;
+    /**
+     * Gets the current cache size.
+     * Useful for monitoring and debugging.
+     */
+    getCacheSize(): number;
+    /**
+     * Checks if Docker is available on the system.
+     *
+     * @returns Promise resolving to true if Docker is available, false otherwise
+     */
+    isDockerAvailable(): Promise<boolean>;
+}

package/out/tsc/src/ensure-node-runtime-layer.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Main API function for Node.js runtime layer management
+ *
+ * This module provides the primary entry point for ensuring Node.js runtime layers
+ * exist in AWS Lambda. It coordinates between runtime detection and layer management
+ * components to provide a seamless experience for CDK integration.
+ *
+ * @module ensure-node-runtime-layer
+ */
+import { EnsureNodeRuntimeLayerOptions, EnsureNodeRuntimeLayerResult } from './nodejs-layer-manager';
+/**
+ * Ensures a Node.js runtime layer exists for the specified configuration.
+ *
+ * This is the main API function that coordinates runtime detection and layer management
+ * to ensure the correct Node.js binaries are available for Lambda Kata execution.
+ *
+ * The function performs the following operations:
+ * 1. Validates all input parameters
+ * 2. Detects the exact Node.js version for the runtime
+ * 3. Searches for existing compatible layers
+ * 4. Creates a new layer if none exists or is compatible
+ * 5. Returns comprehensive result information
+ *
+ * @param options - Configuration options for layer management
+ * @returns Promise resolving to layer information and metadata
+ * @throws NodeRuntimeLayerError for validation failures or operational errors
+ *
+ * @example
+ * ```typescript
+ * const result = await ensureNodeRuntimeLayer({
+ *   runtimeName: 'nodejs20.x',
+ *   architecture: 'x86_64',
+ *   region: 'us-east-1',
+ *   accountId: '123456789012'
+ * });
+ *
+ * console.log(`Layer ARN: ${result.layerArn}`);
+ * console.log(`Node.js version: ${result.nodeVersion}`);
+ * console.log(`Created new layer: ${result.created}`);
+ * ```
+ */
+export declare function ensureNodeRuntimeLayer(options: EnsureNodeRuntimeLayerOptions): Promise<EnsureNodeRuntimeLayerResult>;

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

@@ -23,3 +23,8 @@ export { MockLicensingService, createMockLicensingService, } from './mock-licens
 export { resolveAccountId, resolveAccountIdWithSource, isValidAccountIdFormat, AccountResolutionError, AccountResolutionResult, AccountResolverOptions, } from './account-resolver';
 export { kata, kataWithAccountId, applyTransformation, handleUnlicensed, isKataTransformed, getKataPromise, KataWrapperOptions, KataResult, } from './kata-wrapper';
 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';
+export { NoOpLogger, ConsoleLogger, createDefaultLogger, OperationTimer, } from './logger';
+export { ensureNodeRuntimeLayer } from './ensure-node-runtime-layer';

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

@@ -1,17 +1,3 @@
-/**
- * Kata Wrapper for Lambda Kata CDK Integration
- *
- * This module provides the main `kata()` function that transforms Node.js Lambda
- * functions to run via the Lambda Kata runtime. The transformation includes:
- * - Changing the runtime to Python 3.12
- * - Setting the handler to the Lambda Kata handler
- * - Attaching the customer-specific Lambda Layer
- * - Preserving the original handler path in a config layer
- *
- * Licensing is validated at CDK synthesis/deploy time only—no runtime network calls.
- *
- * @module kata-wrapper
- */
 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';
@@ -130,6 +116,33 @@ export declare function kata<T extends NodejsFunction | LambdaFunction>(lambda:
  * @internal
  */
 export declare function kataWithAccountId<T extends NodejsFunction | LambdaFunction>(lambda: T, accountId: string, props?: KataWrapperOptions): Promise<KataResult>;
+/**
+ * Gets the original runtime from a Lambda function before transformation.
+ *
+ * @param lambda - The Lambda function
+ * @returns The original runtime name (e.g., "nodejs20.x")
+ *
+ * @internal
+ */
+export declare function getOriginalRuntime(lambda: NodejsFunction | LambdaFunction): string;
+/**
+ * Detects if a Lambda function uses a Node.js runtime.
+ *
+ * @param lambda - The Lambda function to check
+ * @returns true if the function uses a supported Node.js runtime
+ *
+ * @internal
+ */
+export declare function isNodejsRuntime(lambda: NodejsFunction | LambdaFunction): boolean;
+/**
+ * Gets the architecture of a Lambda function.
+ *
+ * @param lambda - The Lambda function
+ * @returns The architecture ("x86_64" or "arm64")
+ *
+ * @internal
+ */
+export declare function getLambdaArchitecture(lambda: NodejsFunction | LambdaFunction): 'x86_64' | 'arm64';
 /**
  * Applies the Lambda Kata transformation to a Lambda function.
  *

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

@@ -0,0 +1,88 @@
+/**
+ * Logger implementations for Node.js Layer Management
+ *
+ * Provides different logger implementations for various use cases:
+ * - NoOpLogger: Silent logger for production use
+ * - ConsoleLogger: Console-based logger for development and debugging
+ *
+ * @module logger
+ */
+import { Logger } from './nodejs-layer-manager';
+/**
+ * No-operation logger that silently discards all log messages.
+ *
+ * This is the default logger used when no custom logger is provided.
+ * Useful for production environments where logging overhead should be minimized.
+ */
+export declare class NoOpLogger implements Logger {
+    debug(_message: string, _meta?: Record<string, unknown>): void;
+    info(_message: string, _meta?: Record<string, unknown>): void;
+    warn(_message: string, _meta?: Record<string, unknown>): void;
+    error(_message: string, _meta?: Record<string, unknown>): void;
+}
+/**
+ * Console-based logger for development and debugging.
+ *
+ * Outputs structured log messages to the console with timestamps and metadata.
+ * Useful for development environments and troubleshooting.
+ */
+export declare class ConsoleLogger implements Logger {
+    private readonly prefix;
+    private readonly logLevel;
+    constructor(prefix?: string, logLevel?: 'debug' | 'info' | 'warn' | 'error');
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    private shouldLog;
+    private log;
+}
+/**
+ * Creates a default logger instance.
+ *
+ * Returns a NoOpLogger by default, but can be configured to return
+ * a ConsoleLogger based on environment variables or other configuration.
+ *
+ * @returns A logger instance
+ */
+export declare function createDefaultLogger(): Logger;
+/**
+ * Utility class for measuring operation timing with structured logging.
+ *
+ * Provides consistent timing measurement and logging across all operations.
+ * Ensures operation start/completion logging with timing information.
+ */
+export declare class OperationTimer {
+    private readonly startTime;
+    private readonly logger;
+    private readonly operationType;
+    private readonly operationMetadata;
+    constructor(logger: Logger, operationType: string, operationMetadata?: Record<string, unknown>);
+    /**
+     * Completes the operation timing and logs success.
+     *
+     * @param resultMetadata - Additional metadata about the operation result
+     */
+    complete(resultMetadata?: Record<string, unknown>): void;
+    /**
+     * Completes the operation timing and logs failure.
+     *
+     * @param error - The error that caused the operation to fail
+     * @param errorMetadata - Additional metadata about the error
+     */
+    fail(error: unknown, errorMetadata?: Record<string, unknown>): void;
+    /**
+     * Extracts AWS request ID from error objects.
+     *
+     * @param error - The error to extract request ID from
+     * @returns AWS request ID if found, undefined otherwise
+     */
+    private extractAwsRequestId;
+    /**
+     * Generates troubleshooting context based on error type.
+     *
+     * @param error - The error to generate context for
+     * @returns Troubleshooting guidance
+     */
+    private generateTroubleshootingContext;
+}