feat(core): customize bundling output packaging (#13076)

If the bundling output contains a single archive file (zip or jar), upload it
as-is to S3 without zipping it.

Allow to customize this behavior with `bundling.packaging`:
* `ALWAYS_ZIP`: The bundling output will always be zipped and uploaded to S3.
* `NEVER_ZIP`: The bundling output will not be zipped. Bundling will fail if
  the bundling output doesn't contain a single file.
* `AUTO`: If the bundling output contains a single archive file (zip or jar) it
  will not be zipped. Otherwise it will be zipped.

Closes #10776 
Closes #12651

----

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

packages/@aws-cdk/aws-s3-assets/README.md

@@ -124,6 +124,27 @@ new assets.Asset(this, 'BundledAsset', {
 Although optional, it's recommended to provide a local bundling method which can
 greatly improve performance.
 
+If the bundling output contains a single archive file (zip or jar) it will be
+uploaded to S3 as-is and will not be zipped. Otherwise the contents of the
+output directory will be zipped and the zip file will be uploaded to S3. This
+is the default behavior for `bundling.outputType` (`BundlingOutput.AUTO_DISCOVER`).
+
+Use `BundlingOutput.NOT_ARCHIVED` if the bundling output must always be zipped:
+
+```ts
+const asset = new assets.Asset(this, 'BundledAsset', {
+  path: '/path/to/asset',
+  bundling: {
+    image: BundlingDockerImage.fromRegistry('alpine'),
+    command: ['command-that-produces-an-archive.sh'],
+    outputType: BundlingOutput.NOT_ARCHIVED, // Bundling output will be zipped even though it produces a single archive file.
+  },
+});
+```
+
+Use `BundlingOutput.ARCHIVED` if the bundling output contains a single archive file and
+you don't want it to be zippped.
+
 ## CloudFormation Resource Metadata
 
 > NOTE: This section is relevant for authors of AWS Resource Constructs.

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

@@ -1,4 +1,3 @@
-import * as fs from 'fs';
 import * as path from 'path';
 import * as assets from '@aws-cdk/assets';
 import * as iam from '@aws-cdk/aws-iam';
@@ -13,8 +12,6 @@ import { toSymlinkFollow } from './compat';
 // eslint-disable-next-line no-duplicate-imports, import/order
 import { Construct as CoreConstruct } from '@aws-cdk/core';
 
-const ARCHIVE_EXTENSIONS = ['.zip', '.jar'];
-
 export interface AssetOptions extends assets.CopyOptions, cdk.AssetOptions {
   /**
    * A list of principals that should be able to read this asset from S3.
@@ -139,17 +136,12 @@ export class Asset extends CoreConstruct implements cdk.IAsset {
 
     this.assetPath = staging.relativeStagedPath(stack);
 
-    const packaging = determinePackaging(staging.sourcePath);
-
-    this.isFile = packaging === cdk.FileAssetPackaging.FILE;
+    this.isFile = staging.packaging === cdk.FileAssetPackaging.FILE;
 
-    // sets isZipArchive based on the type of packaging and file extension
-    this.isZipArchive = packaging === cdk.FileAssetPackaging.ZIP_DIRECTORY
-      ? true
-      : ARCHIVE_EXTENSIONS.some(ext => staging.sourcePath.toLowerCase().endsWith(ext));
+    this.isZipArchive = staging.isArchive;
 
     const location = stack.synthesizer.addFileAsset({
-      packaging,
+      packaging: staging.packaging,
       sourceHash: this.sourceHash,
       fileName: this.assetPath,
     });
@@ -210,19 +202,3 @@ export class Asset extends CoreConstruct implements cdk.IAsset {
     this.bucket.grantRead(grantee);
   }
 }
-
-function determinePackaging(assetPath: string): cdk.FileAssetPackaging {
-  if (!fs.existsSync(assetPath)) {
-    throw new Error(`Cannot find asset at ${assetPath}`);
-  }
-
-  if (fs.statSync(assetPath).isDirectory()) {
-    return cdk.FileAssetPackaging.ZIP_DIRECTORY;
-  }
-
-  if (fs.statSync(assetPath).isFile()) {
-    return cdk.FileAssetPackaging.FILE;
-  }
-
-  throw new Error(`Asset ${assetPath} is expected to be either a directory or a regular file`);
-}

packages/@aws-cdk/core/lib/asset-staging.ts

@@ -5,8 +5,8 @@ import * as cxapi from '@aws-cdk/cx-api';
 import { Construct } from 'constructs';
 import * as fs from 'fs-extra';
 import * as minimatch from 'minimatch';
-import { AssetHashType, AssetOptions } from './assets';
-import { BundlingOptions } from './bundling';
+import { AssetHashType, AssetOptions, FileAssetPackaging } from './assets';
+import { BundlingOptions, BundlingOutput } from './bundling';
 import { FileSystem, FingerprintOptions } from './fs';
 import { Names } from './names';
 import { Cache } from './private/cache';
@@ -17,6 +17,8 @@ import { Stage } from './stage';
 // eslint-disable-next-line
 import { Construct as CoreConstruct } from './construct-compat';
 
+const ARCHIVE_EXTENSIONS = ['.zip', '.jar'];
+
 /**
  * A previously staged asset
  */
@@ -138,6 +140,9 @@ export class AssetStaging extends CoreConstruct {
 
   private readonly cacheKey: string;
 
+  private _packaging = FileAssetPackaging.ZIP_DIRECTORY;
+  private _isArchive = true;
+
   constructor(scope: Construct, id: string, props: AssetStagingProps) {
     super(scope, id);
 
@@ -203,6 +208,20 @@ export class AssetStaging extends CoreConstruct {
     return this.assetHash;
   }
 
+  /**
+   * How this asset should be packaged.
+   */
+  public get packaging(): FileAssetPackaging {
+    return this._packaging;
+  }
+
+  /**
+   * Whether this asset is an archive (zip or jar).
+   */
+  public get isArchive(): boolean {
+    return this._isArchive;
+  }
+
   /**
    * Return the path to the staged asset, relative to the Cloud Assembly (manifest) directory of the given stack
    *
@@ -281,11 +300,16 @@ export class AssetStaging extends CoreConstruct {
     const bundleDir = this.determineBundleDir(this.assetOutdir, assetHash);
     this.bundle(bundling, bundleDir);
 
+    // Check bundling output content and determine if we will need to archive
+    const bundlingOutputType = bundling.outputType ?? BundlingOutput.AUTO_DISCOVER;
+    const bundledAsset = determineBundledAsset(bundleDir, bundlingOutputType);
+    this._packaging = bundledAsset.packaging;
+
     // Calculate assetHash afterwards if we still must
-    assetHash = assetHash ?? this.calculateHash(this.hashType, bundling, bundleDir);
-    const stagedPath = path.resolve(this.assetOutdir, renderAssetFilename(assetHash));
+    assetHash = assetHash ?? this.calculateHash(this.hashType, bundling, bundledAsset.path);
+    const stagedPath = path.resolve(this.assetOutdir, renderAssetFilename(assetHash, bundledAsset.extension));
 
-    this.stageAsset(bundleDir, stagedPath, 'move');
+    this.stageAsset(bundledAsset.path, stagedPath, 'move');
     return { assetHash, stagedPath };
   }
 
@@ -323,6 +347,8 @@ export class AssetStaging extends CoreConstruct {
     const stat = fs.statSync(sourcePath);
     if (stat.isFile()) {
       fs.copyFileSync(sourcePath, targetPath);
+      this._packaging = FileAssetPackaging.FILE;
+      this._isArchive = ARCHIVE_EXTENSIONS.includes(path.extname(sourcePath).toLowerCase());
     } else if (stat.isDirectory()) {
       fs.mkdirSync(targetPath);
       FileSystem.copyDirectory(sourcePath, targetPath, this.fingerprintOptions);
@@ -502,3 +528,57 @@ function sortObject(object: { [key: string]: any }): { [key: string]: any } {
   }
   return ret;
 }
+
+/**
+ * Returns the single archive file of a directory or undefined
+ */
+function singleArchiveFile(directory: string): string | undefined {
+  if (!fs.existsSync(directory)) {
+    throw new Error(`Directory ${directory} does not exist.`);
+  }
+
+  if (!fs.statSync(directory).isDirectory()) {
+    throw new Error(`${directory} is not a directory.`);
+  }
+
+  const content = fs.readdirSync(directory);
+  if (content.length === 1) {
+    const file = path.join(directory, content[0]);
+    const extension = path.extname(content[0]).toLowerCase();
+    if (fs.statSync(file).isFile() && ARCHIVE_EXTENSIONS.includes(extension)) {
+      return file;
+    }
+  }
+
+  return undefined;
+}
+
+interface BundledAsset {
+  path: string,
+  packaging: FileAssetPackaging,
+  extension?: string
+}
+
+/**
+ * Returns the bundled asset to use based on the content of the bundle directory
+ * and the type of output.
+ */
+function determineBundledAsset(bundleDir: string, outputType: BundlingOutput): BundledAsset {
+  const archiveFile = singleArchiveFile(bundleDir);
+
+  // auto-discover means that if there is an archive file, we take it as the
+  // bundle, otherwise, we will archive here.
+  if (outputType === BundlingOutput.AUTO_DISCOVER) {
+    outputType = archiveFile ? BundlingOutput.ARCHIVED : BundlingOutput.NOT_ARCHIVED;
+  }
+
+  switch (outputType) {
+    case BundlingOutput.NOT_ARCHIVED:
+      return { path: bundleDir, packaging: FileAssetPackaging.ZIP_DIRECTORY };
+    case BundlingOutput.ARCHIVED:
+      if (!archiveFile) {
+        throw new Error('Bundling output directory is expected to include only a single .zip or .jar file when `output` is set to `ARCHIVED`');
+      }
+      return { path: archiveFile, packaging: FileAssetPackaging.FILE, extension: path.extname(archiveFile) };
+  }
+}

packages/@aws-cdk/core/lib/bundling.ts

@@ -79,6 +79,41 @@ export interface BundlingOptions {
    * @experimental
    */
   readonly local?: ILocalBundling;
+
+  /**
+   * The type of output that this bundling operation is producing.
+   *
+   * @default BundlingOutput.AUTO_DISCOVER
+   *
+   * @experimental
+   */
+  readonly outputType?: BundlingOutput;
+}
+
+/**
+ * The type of output that a bundling operation is producing.
+ *
+ * @experimental
+ */
+export enum BundlingOutput {
+  /**
+   * The bundling output directory includes a single .zip or .jar file which
+   * will be used as the final bundle. If the output directory does not
+   * include exactly a single archive, bundling will fail.
+   */
+  ARCHIVED = 'archived',
+
+  /**
+   * The bundling output directory contains one or more files which will be
+   * archived and uploaded as a .zip file to S3.
+   */
+  NOT_ARCHIVED = 'not-archived',
+
+  /**
+   * If the bundling output directory contains a single archive file (zip or jar)
+   * it will not be zipped. Otherwise the bundling output will be zipped.
+   */
+  AUTO_DISCOVER = 'auto-discover',
 }
 
 /**

packages/@aws-cdk/core/test/docker-stub.sh

@@ -24,5 +24,18 @@ if echo "$@" | grep "DOCKER_STUB_SUCCESS"; then
   exit 0
 fi
 
-echo "Docker mock only supports one of the following commands: DOCKER_STUB_SUCCESS_NO_OUTPUT,DOCKER_STUB_FAIL,DOCKER_STUB_SUCCESS"
+if echo "$@" | grep "DOCKER_STUB_MULTIPLE_FILES"; then
+  outdir=$(echo "$@" | xargs -n1 | grep "/asset-output" | head -n1 | cut -d":" -f1)
+  touch ${outdir}/test1.txt
+  touch ${outdir}/test2.txt
+  exit 0
+fi
+
+if echo "$@" | grep "DOCKER_STUB_SINGLE_ARCHIVE"; then
+  outdir=$(echo "$@" | xargs -n1 | grep "/asset-output" | head -n1 | cut -d":" -f1)
+  touch ${outdir}/test.zip
+  exit 0
+fi
+
+echo "Docker mock only supports one of the following commands: DOCKER_STUB_SUCCESS_NO_OUTPUT,DOCKER_STUB_FAIL,DOCKER_STUB_SUCCESS,DOCKER_STUB_MULTIPLE_FILES,DOCKER_SINGLE_ARCHIVE"
 exit 1