Merge branch 'main' into scheduler-alpha-module-graduation

Author: gracelu0

packages/aws-cdk-lib/.eslintrc.js

@@ -50,6 +50,7 @@ const enableNoThrowDefaultErrorIn = [
   'aws-docdb',
   'aws-dynamodb',
   'aws-ecr',
+  'aws-ecr-assets',
   'aws-efs',
   'aws-elasticloadbalancing',
   'aws-elasticloadbalancingv2',

packages/aws-cdk-lib/aws-ec2/lib/prefix-list.ts

@@ -1,8 +1,7 @@
 import { Construct } from 'constructs';
-import { ValidationError } from 'jsonschema';
 import { CfnPrefixList } from './ec2.generated';
 import * as cxschema from '../../cloud-assembly-schema';
-import { IResource, Lazy, Resource, Names, ContextProvider, Token } from '../../core';
+import { IResource, Lazy, Resource, Names, ContextProvider, Token, ValidationError } from '../../core';
 import { addConstructMetadata } from '../../core/lib/metadata-resource';
 
 /**

packages/aws-cdk-lib/aws-ecr-assets/lib/image-asset.ts

@@ -3,7 +3,7 @@ import * as path from 'path';
 import { Construct } from 'constructs';
 import { FingerprintOptions, FollowMode, IAsset } from '../../assets';
 import * as ecr from '../../aws-ecr';
-import { Annotations, AssetStaging, FeatureFlags, FileFingerprintOptions, IgnoreMode, Stack, SymlinkFollowMode, Token, Stage, CfnResource } from '../../core';
+import { Annotations, AssetStaging, FeatureFlags, FileFingerprintOptions, IgnoreMode, Stack, SymlinkFollowMode, Token, Stage, CfnResource, ValidationError, UnscopedValidationError } from '../../core';
 import * as cxapi from '../../cx-api';
 
 /**
@@ -435,14 +435,14 @@ export class DockerImageAsset extends Construct implements IAsset {
     // resolve full path
     const dir = path.resolve(props.directory);
     if (!fs.existsSync(dir)) {
-      throw new Error(`Cannot find image directory at ${dir}`);
+      throw new ValidationError(`Cannot find image directory at ${dir}`, this);
     }
 
     // validate the docker file exists
     this.dockerfilePath = props.file || 'Dockerfile';
     const file = path.join(dir, this.dockerfilePath);
     if (!fs.existsSync(file)) {
-      throw new Error(`Cannot find file at ${file}`);
+      throw new ValidationError(`Cannot find file at ${file}`, this);
     }
 
     const defaultIgnoreMode = FeatureFlags.of(this).isEnabled(cxapi.DOCKER_IGNORE_SUPPORT)
@@ -582,7 +582,7 @@ export class DockerImageAsset extends Construct implements IAsset {
 function validateProps(props: DockerImageAssetProps) {
   for (const [key, value] of Object.entries(props)) {
     if (Token.isUnresolved(value)) {
-      throw new Error(`Cannot use Token as value of '${key}': this value is used before deployment starts`);
+      throw new UnscopedValidationError(`Cannot use Token as value of '${key}': this value is used before deployment starts`);
     }
   }
 
@@ -593,7 +593,7 @@ function validateProps(props: DockerImageAssetProps) {
 function validateBuildProps(buildPropName: string, buildProps?: { [key: string]: string }) {
   for (const [key, value] of Object.entries(buildProps || {})) {
     if (Token.isUnresolved(key) || Token.isUnresolved(value)) {
-      throw new Error(`Cannot use tokens in keys or values of "${buildPropName}" since they are needed before deployment`);
+      throw new UnscopedValidationError(`Cannot use tokens in keys or values of "${buildPropName}" since they are needed before deployment`);
     }
   }
 }

packages/aws-cdk-lib/aws-ecr-assets/lib/tarball-asset.ts

@@ -3,7 +3,7 @@ import * as path from 'path';
 import { Construct } from 'constructs';
 import { IAsset } from '../../assets';
 import * as ecr from '../../aws-ecr';
-import { AssetStaging, Stack, Stage } from '../../core';
+import { AssetStaging, Stack, Stage, ValidationError } from '../../core';
 
 /**
  * Options for TarballImageAsset
@@ -60,7 +60,7 @@ export class TarballImageAsset extends Construct implements IAsset {
     super(scope, id);
 
     if (!fs.existsSync(props.tarballFile)) {
-      throw new Error(`Cannot find file at ${props.tarballFile}`);
+      throw new ValidationError(`Cannot find file at ${props.tarballFile}`, this);
     }
 
     const stagedTarball = new AssetStaging(this, 'Staging', { sourcePath: props.tarballFile });

packages/aws-cdk-lib/aws-kms/lib/key.ts

@@ -741,7 +741,7 @@ export class Key extends KeyBase {
       dummyValue: {
         keyId: Key.DEFAULT_DUMMY_KEY_ID,
       },
-      ignoreErrorOnMissingContext: options.returnDummyKeyOnMissing,
+      mustExist: !options.returnDummyKeyOnMissing,
     }).value;
 
     return new Import(attributes.keyId,

packages/aws-cdk-lib/aws-ssm/lib/parameter.ts

@@ -585,7 +585,7 @@ export class StringParameter extends ParameterBase implements IStringParameter {
       provider: cxschema.ContextProvider.SSM_PARAMETER_PROVIDER,
       props: { parameterName },
       dummyValue: defaultValue || `dummy-value-for-${parameterName}`,
-      ignoreErrorOnMissingContext: defaultValue !== undefined,
+      mustExist: defaultValue === undefined,
     }).value;
 
     return value;

packages/aws-cdk-lib/core/lib/context-provider.ts

@@ -30,16 +30,70 @@ export interface GetContextKeyOptions {
  */
 export interface GetContextValueOptions extends GetContextKeyOptions {
   /**
-   * The value to return if the context value was not found and a missing
-   * context is reported.
+   * The value to return if the lookup has not yet been performed.
+   *
+   * Upon first synthesis, the lookups has not yet been performed. The
+   * `getValue()` operation returns this value instead, so that synthesis can
+   * proceed. After synthesis completes the first time, the actual lookup will
+   * be performed and synthesis will run again with the *real* value.
+   *
+   * Dummy values should preferably have valid shapes so that downstream
+   * consumers of lookup values don't throw validation exceptions if they
+   * encounter a dummy value (or all possible downstream consumers need to
+   * effectively check for the well-known shape of the dummy value); throwing an
+   * exception would error out the synthesis operation and prevent the lookup
+   * and the second, real, synthesis from happening.
+   *
+   * ## Connection to mustExist
+   *
+   * `dummyValue` is also used as the official value to return if the lookup has
+   * failed and `mustExist == false`.
    */
   readonly dummyValue: any;
 
   /**
-   * When True, the context provider will not throw an error if missing context
-   * is reported
+   * Whether the resource must exist
+   *
+   * If this is set (the default), the query fails if the value or resource we
+   * tried to look up doesn't exist.
+   *
+   * If this is `false` and the value we tried to look up could not be found, the
+   * failure is suppressed and `dummyValue` is officially returned instead.
+   *
+   * When this happens, `dummyValue` is encoded into cached context and it will
+   * never be refreshed anymore until the user runs `cdk context --reset <key>`.
+   *
+   * Note that it is not possible for the CDK app code to make a distinction
+   * between "the lookup has not been performed yet" and "the lookup didn't
+   * find anything and we returned a default value instead".
+   *
+   * ## Context providers
+   *
+   * This feature must explicitly be supported by context providers. It is
+   * currently supported by:
+   *
+   * - KMS key provider
+   * - SSM parameter provider
+   *
+   * ## Note to implementors
+   *
+   * The dummy value should not be returned for all SDK lookup failures. For
+   * example, "no network" or "no credentials" or "malformed query" should
+   * not lead to the dummy value being returned. Only the case of "no such
+   * resource" should.
+   *
+   * @default true
+   */
+  readonly mustExist?: boolean;
+
+  /**
+   * Ignore a lookup failure and return the `dummyValue` instead
+   *
+   * `mustExist` is the recommended alias for this deprecated
+   * property (note that its value is reversed).
    *
    * @default false
+   * @deprecated Use mustExist instead
    */
   readonly ignoreErrorOnMissingContext?: boolean;
 }
@@ -92,6 +146,10 @@ export class ContextProvider {
   }
 
   public static getValue(scope: Construct, options: GetContextValueOptions): GetContextValueResult {
+    if ((options.mustExist !== undefined) && (options.ignoreErrorOnMissingContext !== undefined)) {
+      throw new Error('Only supply one of \'mustExist\' and \'ignoreErrorOnMissingContext\'');
+    }
+
     const stack = Stack.of(scope);
 
     if (Token.isUnresolved(stack.account) || Token.isUnresolved(stack.region)) {
@@ -108,10 +166,19 @@ export class ContextProvider {
     // if context is missing or an error occurred during context retrieval,
     // report and return a dummy value.
     if (value === undefined || providerError !== undefined) {
+      // Render 'ignoreErrorOnMissingContext' iff one of the parameters is supplied.
+      const ignoreErrorOnMissingContext = options.mustExist !== undefined || options.ignoreErrorOnMissingContext !== undefined
+        ? (options.mustExist !== undefined ? !options.mustExist : options.ignoreErrorOnMissingContext)
+        : undefined;
+
       // build a version of the props which includes the dummyValue and ignoreError flag
       const extendedProps: { [p: string]: any } = {
         dummyValue: options.dummyValue,
-        ignoreErrorOnMissingContext: options.ignoreErrorOnMissingContext,
+
+        // Even though we renamed the user-facing property, the field in the
+        // cloud assembly still has the original name, which is somewhat wrong
+        // because it's not about missing context.
+        ignoreErrorOnMissingContext,
         ...props,
       };