fix: lambda-nodejs default runtime regression

[MrArnoldPalmer]

Previously we changed the default version of the lambda-nodejs Function construct to go from using the builtInNodeJsCustomResourceRuntime, a map of regions to available versions, to lambda.Runtime.NODEJS_18_X. The default externalModule configuration excluded the aws-sdk version based on the runtime passed, excluding v2 for Node16 and under, and v3 for Node18 and up, but users can pass their own bundling configuration excluding aws-sdk while not explicitly passing a runtime, which caused their functions to break.

Adds a new lambda.Runtime value for NODEJS_LATEST. This is central reference for the latest version of NodeJS provided by the lamdba service. It also includes a new property isLatest which can be used to indicate that the runtime version may change over time. This can used to indicate that relying on packages shipped with the environment may not be relied upon if the version changes. We default to using the NODEJS_LATEST runtime only if the feature flag is enabled. If the flag is not enabled, use NODEJS_16_X to keep supporting users current bundling configurations.

Additionally, add a warning to tell users if they are excluding a package from their bundling that we know doesn't exist within the runtime they are using. IE, if using NODEJS_18_X and the exclude list includes aws-sdk, warn users that it won't be present.

Fixes #26732

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[aws-cdk-automation]

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

[rix0rrr]

Since this is kind of important to get out quickly, I'm doing a conditional approval so you don't need to wait for another round from me.

I am a little concerned though about the current behavior of the feature flag chosen just recreating the same problem again when Node24/SDKv4 rolls around, and so while helping right now it feels a little like kicking the can down the road; and also around us needing to document the chosen behavior better in the README.

I'll leave you to decide what you think is best.

[rix0rrr]

This solves the problem for now, but isn't this going to cause the exact same problem on the next Node version upgrade?

Effectively, the implicit behavior today was "latest NodeJS version" (because we updated the version from under people without them changing anything), and it broke users in ways they didn't expect.

We can use a flag to make the "hop" between Node <=16 and Node >= 18 an explicit action, but effectively this just keeps the de-facto original behavior of transparently upgrading aws-lambda-nodejs versions out from under users.

Can we do one of the following:

• Name this @aws-cdk/aws-lambda-nodejs:useSdkV3Runtime (or similar) and make it very clear in the README with a big fat warning block that we will always transparently pick the latest runtime for you if you don't give us one, and you should write your config to be robust against that; OR

• Name this @aws-cdk/aws-lambda-nodejs:requireRuntime and use that to make the runtime flag effectively a required property via runtime checking. Then, people will need to make a conscious choice whether they want the auto-upgrading behavior or no (when they pick NODEJS_LATEST or NODEJS_XX), and update all the README examples to use NODEJS_LATEST (while dropping a line saying that this may have an effect if they rely on provided packages by the runtime).

In fact we could always drop a warning if people pick NODEJS_LATEST combined with externalModules...?

[MrArnoldPalmer]

I think I want to go with

Name this @aws-cdk/aws-lambda-nodejs:useSdkV3Runtime (or similar) and make it very clear in the README with a big fat warning block that we will always transparently pick the latest runtime for you if you don't give us one, and you should write your config to be robust against that

But also keep the naming of @aws-cdk/aws-lambda-nodejs:useLatestRuntimeVersion since we should be in theory able to keep updating into sdkv4 environments.

In fact we could always drop a warning if people pick NODEJS_LATEST combined with externalModules...?

Adding a warning when externalModules has anything and using NODEJS_LATEST.

[MrArnoldPalmer]

I think the solution here is pretty good now, except that the warning we emit may be too aggressive for users that are using NODEJS_LATEST with externalModules that they may be including via layers. However, the warning itself says

When using NODEJS_LATEST the runtime version may change as new runtimes are released, this may affect the availability of packages shipped with the environment. Ensure that any external dependencies are available through layers or specify a specific runtime version.

If a user does see this consistently and wish to silence it, they can pass their own runtime as stated.

Also created #26778 which describes what we need to be able to emit the warning only when layers are not specified. However without knowing that specific layers contain specific external packages, an acknowledgement may be better anyway instead of us just not emitting it when layers.length > 0. That ticket also potentially covers acknowledging annotations in addition to removal.

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
• Commit ID: 9203317
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).