chore: add new interfaces for Assets (#12700)

In V2, we want to get rid of the `@aws-cdk/assets` module, as it's considered deprecated in V1.
Unfortunately, the module contains an interface, `CopyOptions`, that is used, through interface inheritance, in the public API of many stable CDK modules like ECS, Lambda, ECR, CodeBuild, etc.

While we have a `CopyOptions` interface in `@aws-cdk/core`, it unfortunately shares the same name, `follow`, with the property in the "old" `CopyOptions`. But the two different `follow` properties have different types.

For that reason, if we're going to remove the "old" `CopyOptions` using JSII's "strip deprecated" option, we can't use the "new" `CopyOptions` in the inheritance hierarchy alongside the "old" `CopyOptions`, as the two definitions of `follow` would conflict.

Because of that, create a new `FileCopyOptions` interface which renames the `follow` property to `followSymlinks`. Also add a `FileFingerprintOptions` interface that does a similar trick to the `FingerprintOptions` interface (which extends `CopyOptions`), which is used in the public API of modules that use Docker assets.

Also extract a few module-private interfaces to avoid duplication of properties between all of these interfaces.

After this change, an interface from one of the non-deprecated assets libraries (S3 or ECR) using `FileOptions` from `@aws-cdk/assets` will look like this:

```ts
// this is in @aws-cdk/aws-s3-assets
export interface AssetOptions extends assets.CopyOptions, cdk.FileCopyOptions, cdk.AssetOptions {
  // ...
```

Then, when we enable stripping the deprecated elements using JSII on the V2 branch, this will be turned to:

```ts
export interface AssetOptions extends cdk.FileCopyOptions, cdk.AssetOptions {
  // ...
```

Allowing us to deprecate the `@aws-cdk/assets` module, and not ship it with `aws-cdk-lib`.

----

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

packages/@aws-cdk/assets/lib/fs/options.ts

@@ -10,6 +10,7 @@ export interface CopyOptions {
  * A strategy for how to handle symlinks.
  *
  * @default Never
+ * @deprecated use `followSymlinks` instead
  */
  readonly follow?: FollowMode;
 

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

@@ -2,14 +2,16 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as assets from '@aws-cdk/assets';
 import * as ecr from '@aws-cdk/aws-ecr';
-import { Annotations, Construct as CoreConstruct, FeatureFlags, IgnoreMode, Stack, Token } from '@aws-cdk/core';
+import {
+ Annotations, AssetStaging, Construct as CoreConstruct, FeatureFlags, FileFingerprintOptions, IgnoreMode, Stack, SymlinkFollowMode, Token,
+} from '@aws-cdk/core';
 import * as cxapi from '@aws-cdk/cx-api';
 import { Construct } from 'constructs';
 
 /**
  * Options for DockerImageAsset
  */
-export interface DockerImageAssetOptions extends assets.FingerprintOptions {
+export interface DockerImageAssetOptions extends assets.FingerprintOptions, FileFingerprintOptions {
  /**
  * ECR repository name
  *
@@ -137,8 +139,9 @@ export class DockerImageAsset extends CoreConstruct implements assets.IAsset {
  // deletion of the ECR repository the app used).
  extraHash.version = '1.21.0';
 
- const staging = new assets.Staging(this, 'Staging', {
+ const staging = new AssetStaging(this, 'Staging', {
  ...props,
+ follow: props.followSymlinks ?? toSymlinkFollow(props.follow),
  exclude,
  ignoreMode,
  sourcePath: dir,
@@ -181,3 +184,13 @@ function validateBuildArgs(buildArgs?: { [key: string]: string }) {
  }
  }
 }
+
+function toSymlinkFollow(follow?: assets.FollowMode): SymlinkFollowMode | undefined {
+ switch (follow) {
+ case undefined: return undefined;
+ case assets.FollowMode.NEVER: return SymlinkFollowMode.NEVER;
+ case assets.FollowMode.ALWAYS: return SymlinkFollowMode.ALWAYS;
+ case assets.FollowMode.BLOCK_EXTERNAL: return SymlinkFollowMode.BLOCK_EXTERNAL;
+ case assets.FollowMode.EXTERNAL: return SymlinkFollowMode.EXTERNAL;
+ }
+}

packages/@aws-cdk/aws-s3-assets/lib/asset.ts

@@ -15,7 +15,7 @@ import { Construct as CoreConstruct } from '@aws-cdk/core';
 
 const ARCHIVE_EXTENSIONS = ['.zip', '.jar'];
 
-export interface AssetOptions extends assets.CopyOptions, cdk.AssetOptions {
+export interface AssetOptions extends assets.CopyOptions, cdk.FileCopyOptions, cdk.AssetOptions {
  /**
  * A list of principals that should be able to read this asset from S3.
  * You can use `asset.grantRead(principal)` to grant read permissions later.
@@ -128,7 +128,7 @@ export class Asset extends CoreConstruct implements cdk.IAsset {
  const staging = new cdk.AssetStaging(this, 'Stage', {
  ...props,
  sourcePath: path.resolve(props.path),
- follow: toSymlinkFollow(props.follow),
+ follow: props.followSymlinks ?? toSymlinkFollow(props.follow),
  assetHash: props.assetHash ?? props.sourceHash,
  });
 

packages/@aws-cdk/core/lib/fs/options.ts

@@ -56,19 +56,9 @@ export enum IgnoreMode {
  * context flag is set.
  */
  DOCKER = 'docker'
-};
-
-/**
- * Obtains applied when copying directories into the staging location.
- */
-export interface CopyOptions {
- /**
- * A strategy for how to handle symlinks.
- *
- * @default SymlinkFollowMode.NEVER
- */
- readonly follow?: SymlinkFollowMode;
+}
 
+interface FileOptions {
  /**
  * Glob patterns to exclude from the copy.
  *
@@ -85,9 +75,30 @@ export interface CopyOptions {
 }
 
 /**
- * Options related to calculating source hash.
+ * Options applied when copying directories
+ */
+export interface CopyOptions extends FileOptions {
+ /**
+ * A strategy for how to handle symlinks.
+ *
+ * @default SymlinkFollowMode.NEVER
+ */
+ readonly follow?: SymlinkFollowMode;
+}
+
+/**
+ * Options applied when copying directories into the staging location.
  */
-export interface FingerprintOptions extends CopyOptions {
+export interface FileCopyOptions extends FileOptions {
+ /**
+ * A strategy for how to handle symlinks.
+ *
+ * @default SymlinkFollowMode.NEVER
+ */
+ readonly followSymlinks?: SymlinkFollowMode;
+}
+
+interface ExtraHashOptions {
  /**
  * Extra information to encode into the fingerprint (e.g. build instructions
  * and other inputs)
@@ -96,3 +107,15 @@ export interface FingerprintOptions extends CopyOptions {
  */
  readonly extraHash?: string;
 }
+
+/**
+ * Options related to calculating source hash.
+ */
+export interface FingerprintOptions extends CopyOptions, ExtraHashOptions {
+}
+
+/**
+ * Options related to calculating source hash.
+ */
+export interface FileFingerprintOptions extends FileCopyOptions, ExtraHashOptions {
+}