@lambda-kata/cdk 0.1.3-rc.1 → 0.1.3-rc.10

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, } 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;
+}

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

@@ -0,0 +1,419 @@
+/**
+ * Node.js Runtime-Aware Lambda Layer Management
+ *
+ * This module provides TypeScript-only orchestration for detecting Node.js Lambda
+ * runtime versions and managing corresponding Node.js Lambda Layers. The system
+ * automatically ensures the correct Node.js binaries are available at execution time
+ * by creating or reusing Lambda Layers that contain Node.js runtime binaries matching
+ * the exact versions used in AWS Lambda runtime images.
+ *
+ * Key features:
+ * - Detects exact Node.js versions from AWS Lambda Docker images
+ * - Creates minimal Lambda Layers with only Node.js binaries
+ * - Supports both x86_64 and arm64 architectures
+ * - Implements idempotent operations with layer reuse
+ * - Provides comprehensive error handling and logging
+ *
+ * @module nodejs-layer-manager
+ */
+import { LambdaClientConfig } from '@aws-sdk/client-lambda';
+/**
+ * Configuration options for ensuring a Node.js runtime layer exists.
+ *
+ * @example
+ * ```typescript
+ * const options: EnsureNodeRuntimeLayerOptions = {
+ *   runtimeName: 'nodejs20.x',
+ *   architecture: 'x86_64',
+ *   region: 'us-east-1',
+ *   accountId: '123456789012'
+ * };
+ * ```
+ */
+export interface EnsureNodeRuntimeLayerOptions {
+    /**
+     * The AWS Lambda runtime name (e.g., "nodejs18.x", "nodejs20.x", "nodejs22.x").
+     * This determines which Node.js major version to use.
+     */
+    runtimeName: string;
+    /**
+     * The target architecture for the Lambda function and layer.
+     * Must be either "x86_64" or "arm64".
+     */
+    architecture: 'x86_64' | 'arm64';
+    /**
+     * The AWS region where the layer should be created or found.
+     */
+    region: string;
+    /**
+     * The AWS account ID where the layer should be created or found.
+     */
+    accountId: string;
+    /**
+     * Optional AWS SDK configuration for custom authentication, region, or endpoint settings.
+     * If not provided, the default AWS SDK configuration will be used.
+     */
+    awsSdkConfig?: LambdaClientConfig;
+    /**
+     * Optional logger for debugging and monitoring layer operations.
+     * If not provided, a no-op logger will be used.
+     */
+    logger?: Logger;
+}
+/**
+ * Result of ensuring a Node.js runtime layer exists.
+ *
+ * Contains all information about the layer that was created or found,
+ * including metadata for debugging and monitoring.
+ */
+export interface EnsureNodeRuntimeLayerResult {
+    /**
+     * The ARN of the Lambda Layer that contains the Node.js runtime.
+     * This ARN can be attached to Lambda functions.
+     */
+    layerArn: string;
+    /**
+     * The name of the Lambda Layer.
+     * Follows the pattern: lambda-kata-nodejs-${runtimeName}-${architecture}
+     */
+    layerName: string;
+    /**
+     * The original runtime name that was requested.
+     */
+    runtimeName: string;
+    /**
+     * The exact Node.js version detected from the AWS Lambda runtime image.
+     * Format: semantic version string (e.g., "20.10.0")
+     */
+    nodeVersion: string;
+    /**
+     * The architecture of the layer and Node.js binary.
+     */
+    architecture: 'x86_64' | 'arm64';
+    /**
+     * Whether a new layer was created (true) or an existing layer was reused (false).
+     * Useful for monitoring and debugging layer management operations.
+     */
+    created: boolean;
+}
+/**
+ * Information about a detected Node.js version from AWS Lambda runtime images.
+ *
+ * This interface represents the result of querying AWS Lambda Docker images
+ * to determine the exact Node.js version used by a specific runtime.
+ */
+export interface NodeVersionInfo {
+    /**
+     * The exact Node.js version string (e.g., "20.10.0").
+     * Extracted from `node --version` within the AWS Lambda runtime Docker image.
+     */
+    version: string;
+    /**
+     * The original runtime name that was queried.
+     */
+    runtimeName: string;
+    /**
+     * The Docker image that was used to detect the version.
+     * Format: public.ecr.aws/lambda/nodejs:{majorVersion}-{architecture}
+     */
+    dockerImage: string;
+}
+/**
+ * Information about a Lambda Layer containing Node.js runtime.
+ *
+ * This interface represents metadata about existing or newly created
+ * Node.js Lambda Layers for compatibility checking and management.
+ */
+export interface LayerInfo {
+    /**
+     * The full ARN of the Lambda Layer version.
+     */
+    arn: string;
+    /**
+     * The name of the Lambda Layer.
+     */
+    name: string;
+    /**
+     * The version number of the Lambda Layer.
+     */
+    version: number;
+    /**
+     * The Node.js version contained in this layer.
+     */
+    nodeVersion: string;
+    /**
+     * The architecture this layer is compatible with.
+     */
+    architecture: string;
+    /**
+     * When this layer version was created.
+     */
+    createdDate: Date;
+}
+/**
+ * Options for searching existing Lambda Layers.
+ *
+ * Used internally by LayerManager to find compatible existing layers.
+ */
+export interface LayerSearchOptions {
+    /**
+     * The expected layer name to search for.
+     */
+    layerName: string;
+    /**
+     * Requirements that the layer must meet to be considered compatible.
+     */
+    requirements: LayerRequirements;
+}
+/**
+ * Requirements that a Lambda Layer must meet to be considered compatible.
+ *
+ * Used for validating whether an existing layer can be reused.
+ */
+export interface LayerRequirements {
+    /**
+     * The required Node.js version.
+     */
+    nodeVersion: string;
+    /**
+     * The required architecture.
+     */
+    architecture: string;
+    /**
+     * Maximum age for the layer to be considered fresh.
+     * Layers older than this may be recreated.
+     */
+    maxAge?: number;
+}
+/**
+ * Options for creating a new Lambda Layer.
+ *
+ * Contains all information needed to build and publish a Node.js layer.
+ */
+export interface LayerCreationOptions {
+    /**
+     * The name for the new layer.
+     */
+    layerName: string;
+    /**
+     * The Node.js version to include in the layer.
+     */
+    nodeVersion: string;
+    /**
+     * The target architecture.
+     */
+    architecture: 'x86_64' | 'arm64';
+    /**
+     * The AWS region where the layer should be created.
+     */
+    region: string;
+    /**
+     * Optional description for the layer.
+     */
+    description?: string;
+}
+/**
+ * Logger interface for debugging and monitoring layer operations.
+ *
+ * Provides structured logging with different severity levels and optional metadata.
+ */
+export interface Logger {
+    /**
+     * Log debug information for detailed troubleshooting.
+     */
+    debug(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log informational messages about normal operations.
+     */
+    info(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log warning messages about potential issues.
+     */
+    warn(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log error messages about failures and exceptions.
+     */
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Interface for detecting Node.js versions from AWS Lambda runtime images.
+ *
+ * Implementations should use Docker to pull AWS Lambda runtime images
+ * and extract the exact Node.js version using `node --version`.
+ */
+export interface RuntimeDetector {
+    /**
+     * Detects the exact Node.js version for a given runtime and architecture.
+     *
+     * @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>;
+}
+/**
+ * Interface for managing Lambda Layers containing Node.js runtime.
+ *
+ * Implementations should handle layer creation, searching, and compatibility validation
+ * using AWS SDK v3 Lambda client operations.
+ */
+export interface LayerManager {
+    /**
+     * Searches for an existing compatible Node.js layer.
+     *
+     * @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.
+     *
+     * @param options - Layer creation configuration
+     * @returns Promise resolving to information about the created layer
+     * @throws NodeRuntimeLayerError if creation fails
+     */
+    createNodeLayer(options: LayerCreationOptions): Promise<LayerInfo>;
+    /**
+     * Validates whether a layer meets the specified 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;
+    /**
+     * Gets the current circuit breaker state for monitoring and debugging.
+     *
+     * @returns Object containing circuit breaker state information
+     */
+    getCircuitBreakerState(): {
+        state: string;
+        failureCount: number;
+        successCount: number;
+    };
+    /**
+     * Destroys the layer manager and cleans up resources.
+     *
+     * Should be called when the manager is no longer needed to prevent
+     * resource leaks.
+     */
+    destroy(): void;
+}
+/**
+ * Error codes for Node.js runtime layer management operations.
+ *
+ * These codes provide structured error classification for different failure scenarios.
+ */
+export declare enum ErrorCodes {
+    /**
+     * Docker is not available or cannot be executed.
+     */
+    DOCKER_UNAVAILABLE = "DOCKER_UNAVAILABLE",
+    /**
+     * The specified runtime is not supported.
+     */
+    RUNTIME_UNSUPPORTED = "RUNTIME_UNSUPPORTED",
+    /**
+     * AWS API operation failed.
+     */
+    AWS_API_ERROR = "AWS_API_ERROR",
+    /**
+     * Layer creation operation failed.
+     */
+    LAYER_CREATION_FAILED = "LAYER_CREATION_FAILED",
+    /**
+     * The specified architecture is not supported.
+     */
+    INVALID_ARCHITECTURE = "INVALID_ARCHITECTURE",
+    /**
+     * Node.js version detection failed.
+     */
+    VERSION_DETECTION_FAILED = "VERSION_DETECTION_FAILED",
+    /**
+     * Layer size exceeds AWS limits.
+     */
+    LAYER_SIZE_EXCEEDED = "LAYER_SIZE_EXCEEDED",
+    /**
+     * AWS account quota exceeded.
+     */
+    QUOTA_EXCEEDED = "QUOTA_EXCEEDED",
+    /**
+     * Internal error or unexpected failure.
+     */
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+}
+/**
+ * Specialized error class for Node.js runtime layer management operations.
+ *
+ * Provides structured error information with error codes, descriptive messages,
+ * and optional cause chaining for debugging.
+ */
+export declare class NodeRuntimeLayerError extends Error {
+    readonly code: ErrorCodes;
+    readonly cause?: Error | undefined;
+    /**
+     * Creates a new NodeRuntimeLayerError.
+     *
+     * @param message - Human-readable error message
+     * @param code - Structured error code for programmatic handling
+     * @param cause - Optional underlying error that caused this error
+     */
+    constructor(message: string, code: ErrorCodes, cause?: Error | undefined);
+}
+/**
+ * Cache entry for storing detected Node.js version information.
+ *
+ * Used internally to avoid repeated Docker operations for the same runtime.
+ */
+export interface VersionCacheEntry {
+    /**
+     * The detected Node.js version.
+     */
+    version: string;
+    /**
+     * The runtime name that was queried.
+     */
+    runtimeName: string;
+    /**
+     * The Docker image that was used.
+     */
+    dockerImage: string;
+    /**
+     * When this entry was cached.
+     */
+    cachedAt: Date;
+    /**
+     * Time-to-live in milliseconds.
+     */
+    ttl: number;
+}
+/**
+ * Metadata for Lambda Layer creation and management.
+ *
+ * Contains information needed for AWS Lambda Layer operations.
+ */
+export interface LayerMetadata {
+    /**
+     * The name of the Lambda Layer.
+     */
+    layerName: string;
+    /**
+     * Human-readable description of the layer.
+     */
+    description: string;
+    /**
+     * Compatible Lambda runtimes.
+     * For Lambda Kata, this is typically ["python3.12"].
+     */
+    compatibleRuntimes: string[];
+    /**
+     * Compatible architectures.
+     */
+    compatibleArchitectures: string[];
+    /**
+     * Optional license information.
+     */
+    licenseInfo?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lambda-kata/cdk",
-  "version": "0.1.3-rc.1",
+  "version": "0.1.3-rc.10",
   "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",
@@ -11,8 +11,8 @@
     "build:minify": "yarn run build:config && node dist/utils/build.js",
     "build:config": "esbuild --bundle --platform=node utils/esbuild/esbuild.build.ts --outfile=dist/utils/build.js --external:esbuild",
     "watch": "tsc -w",
-    "test": "jest",
-    "test:watch": "jest --watch",
+    "test": "npx jest --runInBand --colors --verbose --testTimeout=30000 --forceExit --detectOpenHandles",
+    "test:watch": "npx jest --watch --testTimeout=30000 --runInBand",
     "lint": "eslint src/ test/ --ext .ts",
     "clean": "rm -rf lib coverage",
     "docs": "yarn run docs:md && yarn run docs:html",
@@ -26,7 +26,7 @@
   ],
   "exports": {
     ".": {
-      "types": "./out/tsc/index.d.ts",
+      "types": "./out/tsc/src/index.d.ts",
       "default": "./out/dist/index.js"
     }
   },
@@ -39,11 +39,11 @@
     "python",
     "serverless"
   ],
-  "author": "Lambda Kata",
+  "author": "Raman Marozau, raman@worktif.com",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/LambdaKata/cdk.git"
+    "url": "https://github.com/lambda-kata/cdk.git"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -53,6 +53,7 @@
     "constructs": "^10.0.0"
   },
   "dependencies": {
+    "@aws-sdk/client-lambda": "^3.500.0",
     "@aws-sdk/client-sts": "^3.500.0",
     "dotenv": "^17.2.3",
     "reflect-metadata": "^0.2.2"