feat(lambda): allow running a build file

.vscode/launch.json

@@ -5,19 +5,15 @@
   "version": "0.2.0",
   "configurations": [
     {
-      // Has convenient settings for attaching to a NodeJS process for debugging purposes
-      // that are NOT the default and otherwise every developers has to configure for
-      // themselves again and again.
       "type": "node",
-      "request": "attach",
-      "name": "Attach to NodeJS",
-      // If we don't do this, every step-into into an async function call will go into
-      // NodeJS internals which are hard to step out of.
-      "skipFiles": [
-        "<node_internals>/**"
-      ],
-      // Saves some button-pressing latency on attaching
-      "stopOnEntry": false
+      "request": "launch",
+      "args": ["jest", "--runTestsByPath", "/Users/bergjak/workplace/CDK/aws-cdk/packages/aws-cdk-lib/aws-lambda-nodejs/test/function.test.ts"],
+      "name": "debug unit test",
+      "program": "/opt/homebrew/bin/yarn",
+      "cwd": "/Users/bergjak/workplace/CDK/aws-cdk/packages/aws-cdk-lib",
+      "console": "integratedTerminal",
+      "sourceMaps": true,
+      "skipFiles": [ "<node_internals>/**/*" ],
     }
   ]
 }

packages/aws-cdk-lib/aws-lambda-nodejs/lib/function.ts

@@ -27,8 +27,12 @@ export interface NodejsFunctionProps extends lambda.FunctionOptions {
   /**
    * The name of the exported handler in the entry file.
    *
-   * The handler is prefixed with `index.` unless the specified handler value contains a `.`,
-   * in which case it is used as-is.
+   * * If the `code` property is supplied, then you must include the `handler` property. The handler should be the name of the file
+   * that contains the exported handler and the function that should be called when the AWS Lambda is invoked. For example, if
+   * you had a file called `myLambda.js` and the function to be invoked was `myHandler`, then you should input `handler` property as `myLambda.myHandler`.
+   *
+   * * If the `code` property is not supplied and the handler input does not contain a `.`, then the handler is prefixed with `index.` (index period). Otherwise,
+   * the handler property is not modified.
    *
    * @default handler
    */
@@ -83,6 +87,17 @@ export interface NodejsFunctionProps extends lambda.FunctionOptions {
    * @default - the directory containing the `depsLockFilePath`
    */
   readonly projectRoot?: string;
+
+  /**
+   * The code that will be deployed to the Lambda Handler. If included, then properties related to
+   * bundling of the code are ignored. In the constructor of NodeJsFunction, where the Super is called,
+   * you can see which bundling properties are ignored.
+   *
+   * * If the `code` field is specified, then you must include the `handler` property.
+   *
+   * @default - the code is bundled by esbuild
+   */
+  readonly code?: lambda.Code;
 }
 
 /**
@@ -94,27 +109,41 @@ export class NodejsFunction extends lambda.Function {
       throw new Error('Only `NODEJS` runtimes are supported.');
     }
 
-    // Entry and defaults
-    const entry = path.resolve(findEntry(id, props.entry));
-    const handler = props.handler ?? 'handler';
-    const architecture = props.architecture ?? Architecture.X86_64;
-    const depsLockFilePath = findLockFile(props.depsLockFilePath);
-    const projectRoot = props.projectRoot ?? path.dirname(depsLockFilePath);
     const runtime = getRuntime(scope, props);
 
-    super(scope, id, {
-      ...props,
-      runtime,
-      code: Bundling.bundle(scope, {
-        ...props.bundling ?? {},
-        entry,
+    if (props.code !== undefined) {
+      if (props.handler === undefined) {
+        throw new Error('Cannot determine handler when `code` property is specified. Use `handler` property to specify a handler.');
+      }
+
+      super(scope, id, {
+        ...props,
         runtime,
-        architecture,
-        depsLockFilePath,
-        projectRoot,
-      }),
-      handler: handler.indexOf('.') !== -1 ? `${handler}` : `index.${handler}`,
-    });
+        code: props.code,
+        handler: props.handler!,
+      });
+    } else {
+      // Entry and defaults
+      const entry = path.resolve(findEntry(id, props.entry));
+      const architecture = props.architecture ?? Architecture.X86_64;
+      const depsLockFilePath = findLockFile(props.depsLockFilePath);
+      const projectRoot = props.projectRoot ?? path.dirname(depsLockFilePath);
+      const handler = props.handler ?? 'handler';
+
+      super(scope, id, {
+        ...props,
+        runtime,
+        code: Bundling.bundle(scope, {
+          ...props.bundling ?? {},
+          entry,
+          runtime,
+          architecture,
+          depsLockFilePath,
+          projectRoot,
+        }),
+        handler: handler.indexOf('.') !== -1 ? `${handler}` : `index.${handler}`,
+      });
+    }
 
     // Enable connection reuse for aws-sdk
     if (props.awsSdkConnectionReuse ?? true) {

packages/aws-cdk-lib/aws-lambda-nodejs/test/function.test.ts

@@ -1,7 +1,8 @@
+import * as child_process from 'child_process';
 import { bockfs } from '@aws-cdk/cdk-build-tools';
 import { Template, Match } from '../../assertions';
 import { Vpc } from '../../aws-ec2';
-import { CodeConfig, Runtime } from '../../aws-lambda';
+import { Code, CodeConfig, Runtime } from '../../aws-lambda';
 import { App, Stack } from '../../core';
 import { LAMBDA_NODEJS_USE_LATEST_RUNTIME } from '../../cx-api';
 import { NodejsFunction } from '../lib';
@@ -50,6 +51,7 @@ bockfs({
   '/home/project/function.test.handler4.mts': '// nothing',
   '/home/project/function.test.handler5.cts': '// nothing',
   '/home/project/function.test.handler6.cjs': '// nothing',
+  '/home/project/function.test.handler7.zip': '// nothing',
   '/home/project/aws-lambda-nodejs/lib/index.ts': '// nothing',
 });
 const bockPath = bockfs.workingDirectory('/home/project');
@@ -78,6 +80,49 @@ test('NodejsFunction with .ts handler', () => {
   });
 });
 
+describe('lambda.Code.fromCustomCommand', () => {
+  // GIVEN
+  beforeEach(() => {
+    jest.spyOn(child_process, 'spawnSync').mockReturnValue({
+      status: 0,
+      stderr: Buffer.from('stderr'),
+      stdout: Buffer.from('stdout'),
+      pid: 123,
+      output: ['stdout', 'stderr'],
+      signal: null,
+    });
+  });
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test('if code property is included without handler property, then error is thrown', () => {
+    // WHEN
+    const handlerName = undefined;
+
+    // THEN
+    expect(() => new NodejsFunction(stack, 'handler1', {
+      handler: handlerName,
+      code: Code.fromCustomCommand('function.test.handler7.zip', ['node'], undefined),
+    })).toThrow('Cannot determine handler when `code` property is specified. Use `handler` property to specify a handler.');
+  });
+
+  test('if code and handler properties are included, the template can be synthesized', () => {
+    // WHEN
+    new NodejsFunction(stack, 'handler1', {
+      handler: 'Random.Name',
+      runtime: Runtime.NODEJS_18_X,
+      code: Code.fromCustomCommand('function.test.handler7.zip', ['node'], undefined),
+    });
+
+    // THEN
+    Template.fromStack(stack).hasResourceProperties('AWS::Lambda::Function', {
+      Handler: 'Random.Name',
+      Runtime: 'nodejs18.x',
+    });
+  });
+});
+
 test('NodejsFunction with overridden handler - no dots', () => {
   // WHEN
   new NodejsFunction(stack, 'handler1', {

packages/aws-cdk-lib/aws-lambda/lib/code.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from 'child_process';
 import { Construct } from 'constructs';
 import * as ecr from '../../aws-ecr';
 import * as ecr_assets from '../../aws-ecr-assets';
@@ -54,6 +55,44 @@ export abstract class Code {
     return new AssetCode(path, options);
   }
 
+  /**
+   * Runs a command to build the code asset that will be used.
+   *
+   * @param output Where the output of the command will be directed, either a directory or a .zip file with the output Lambda code bundle
+   * * For example, if you use the command to run a build script (e.g., [ 'node', 'bundle_code.js' ]), and the build script generates a directory `/my/lambda/code`
+   * containing code that should be ran in a Lambda function, then output should be set to `/my/lambda/code`
+   * @param command The command which will be executed to generate the output, for example, [ 'node', 'bundle_code.js' ]
+   * @param assetOptions The same options that are available for `Code.fromAsset` -- but bundling options are not allowed
+   * @param commandOptions Options that are passed to the spawned process, which determine the characteristics of the spawned process.
+   * * See `child_process.SpawnSyncOptions` for possible inputs and defaults (https://nodejs.org/api/child_process.html#child_processspawnsynccommand-args-options).
+   */
+  public static fromCustomCommand(
+    output: string,
+    command: string[],
+    commandOptions?: {[option: string]: any}, // jsii build fails if the type is SpawnSyncOptions... so best we can do is point user to those options.
+    assetOptions?: s3_assets.AssetOptions,
+  ): AssetCode {
+    if (command.length === 0) {
+      throw new Error('command must contain at least one argument. For example, ["node", "buildFile.js"].');
+    }
+
+    const cmd = command[0];
+    const commandArguments = command.splice(1);
+
+    const proc = commandOptions === undefined
+      ? spawnSync(cmd, commandArguments) // use the default spawnSyncOptions
+      : spawnSync(cmd, commandArguments, commandOptions);
+
+    if (proc.error) {
+      throw new Error(`Failed to execute custom command: ${proc.error}`);
+    }
+    if (proc.status !== 0) {
+      throw new Error(`${command.join(' ')} exited with status: ${proc.status}\n\nstdout: ${proc.stdout?.toString().trim()}\n\nstderr: ${proc.stderr?.toString().trim()}`);
+    }
+
+    return new AssetCode(output, assetOptions);
+  }
+
   /**
    * Loads the function code from an asset created by a Docker build.
    *

packages/aws-cdk-lib/aws-lambda/test/code.test.ts

@@ -1,3 +1,4 @@
+import * as child_process from 'child_process';
 import * as path from 'path';
 import { Match, Template } from '../../assertions';
 import * as ecr from '../../aws-ecr';
@@ -15,6 +16,78 @@ describe('code', () => {
     });
   });
 
+  describe('lambda.Code.fromCustomCommand', () => {
+    let spawnSyncMock: jest.SpyInstance;
+    beforeEach(() => {
+      spawnSyncMock = jest.spyOn(child_process, 'spawnSync').mockReturnValue({
+        status: 0,
+        stderr: Buffer.from('stderr'),
+        stdout: Buffer.from('stdout'),
+        pid: 123,
+        output: ['stdout', 'stderr'],
+        signal: null,
+      });
+    });
+    afterEach(() => {
+      jest.restoreAllMocks();
+    });
+
+    test('fails if command is empty', () => {
+      // GIVEN
+      const command = [];
+
+      // THEN
+      expect(() => lambda.Code.fromCustomCommand('', command)).toThrow('command must contain at least one argument. For example, ["node", "buildFile.js"].');
+    });
+    test('properly splices arguments', () => {
+      // GIVEN
+      const command = 'node is a great command, wow'.split(' ');
+      lambda.Code.fromCustomCommand('', command);
+
+      // THEN
+      expect(spawnSyncMock).toHaveBeenCalledWith(
+        'node',
+        ['is', 'a', 'great', 'command,', 'wow'],
+      );
+    });
+    test('properly splices arguments when commandOptions are included', () => {
+      // GIVEN
+      const command = 'node is a great command, wow'.split(' ');
+      const commandOptions = { cwd: '/tmp', env: { SOME_KEY: 'SOME_VALUE' } };
+      lambda.Code.fromCustomCommand('', command, commandOptions);
+
+      // THEN
+      expect(spawnSyncMock).toHaveBeenCalledWith(
+        'node',
+        ['is', 'a', 'great', 'command,', 'wow'],
+        commandOptions,
+      );
+    });
+    test('throws custom error message when spawnSync errors', () => {
+      // GIVEN
+      jest.restoreAllMocks(); // use the real spawnSync, which doesn't work in unit tests.
+      const command = ['whatever'];
+
+      // THEN
+      expect(() => lambda.Code.fromCustomCommand('', command)).toThrow(/Failed to execute custom command: .*/);
+    });
+    test('throws custom error message when spawnSync exits with non-zero status code', () => {
+      // GIVEN
+      const command = ['whatever'];
+      spawnSyncMock = jest.spyOn(child_process, 'spawnSync').mockReturnValue({
+        status: 1,
+        stderr: Buffer.from('stderr'),
+        stdout: Buffer.from('stdout'),
+        pid: 123,
+        output: ['stdout', 'stderr'],
+        signal: null,
+      });
+
+      // THEN
+      expect(() => lambda.Code.fromCustomCommand('', command)).toThrow('whatever exited with status: 1\n\nstdout: stdout\n\nstderr: stderr');
+    });
+  });
+
   describe('lambda.Code.fromAsset', () => {
     test('fails if path is empty', () => {
       // GIVEN