feat(s3): add option to auto delete objects upon bucket removal

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

@@ -341,3 +341,20 @@ bucket.urlForObject('objectname'); // Path-Style URL
 bucket.virtualHostedUrlForObject('objectname'); // Virtual Hosted-Style URL
 bucket.virtualHostedUrlForObject('objectname', { regional: false }); // Virtual Hosted-Style URL but non-regional
 ```
+
+### Bucket deletion
+
+When a bucket is removed from a stack (or the stack is deleted), the S3
+bucket will be removed according to its removal policy (which by default will
+simply orphan the bucket and leave it in your AWS account). If the removal
+policy is set to `RemovalPolicy.DESTROY`, the bucket will be deleted as long
+as it does not contain any objects.
+
+To override this and force all objects to get deleted during bucket deletion,
+enable the`autoDeleteObjects` option.
+
+```ts
+const bucket = new Bucket(this, 'MyTempFileBucket', {
+  removalPolicy: RemovalPolicy.DESTROY,
+  autoDeleteObjects: true,
+});

packages/@aws-cdk/aws-s3/lib/auto-delete-objects-handler/index.ts

@@ -0,0 +1,43 @@
+export async function handler(event: AWSLambda.CloudFormationCustomResourceEvent, s3?: any) {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports, import/no-extraneous-dependencies
+  if (!s3) { s3 = new (require('aws-sdk').S3)(); }
+  if (event.RequestType === 'Create') { return onCreate(s3, event); }
+  if (event.RequestType === 'Update') { return onUpdate(s3, event); }
+  if (event.RequestType === 'Delete') { return onDelete(s3, event); }
+  throw new Error('Invalid request type.');
+}
+
+/**
+ * Recursively delete all items in the bucket
+ *
+ * @param {AWS.S3} s3 the S3 client
+ * @param {*} bucketName the bucket name
+ */
+async function emptyBucket(s3: any, bucketName: string) {
+  const listedObjects = await s3.listObjectVersions({ Bucket: bucketName }).promise();
+  const contents = (listedObjects.Versions || []).concat(listedObjects.DeleteMarkers || []);
+  if (contents.length === 0) {
+    return;
+  };
+
+  let records = contents.map((record: any) => ({ Key: record.Key, VersionId: record.VersionId }));
+  await s3.deleteObjects({ Bucket: bucketName, Delete: { Objects: records } }).promise();
+
+  if (listedObjects?.IsTruncated === 'true' ) await emptyBucket(s3, bucketName);
+}
+
+async function onCreate(_s3: any, _event: AWSLambda.CloudFormationCustomResourceCreateEvent) {
+  return;
+}
+
+async function onUpdate(_s3: any, _event: AWSLambda.CloudFormationCustomResourceUpdateEvent) {
+  return;
+}
+
+async function onDelete(s3: any, deleteEvent: AWSLambda.CloudFormationCustomResourceDeleteEvent) {
+  const bucketName = deleteEvent.ResourceProperties?.BucketName;
+  if (!bucketName) {
+    throw new Error('No BucketName was provided.');
+  }
+  await emptyBucket(s3, bucketName);
+}

packages/@aws-cdk/aws-s3/lib/bucket.ts

@@ -1,8 +1,9 @@
 import { EOL } from 'os';
+import * as path from 'path';
 import * as events from '@aws-cdk/aws-events';
 import * as iam from '@aws-cdk/aws-iam';
 import * as kms from '@aws-cdk/aws-kms';
-import { Fn, IResource, Lazy, RemovalPolicy, Resource, Stack, Token } from '@aws-cdk/core';
+import { Fn, IResource, Lazy, RemovalPolicy, Resource, Stack, Token, CustomResource, CustomResourceProvider, CustomResourceProviderRuntime } from '@aws-cdk/core';
 import { Construct } from 'constructs';
 import { BucketPolicy } from './bucket-policy';
 import { IBucketNotificationDestination } from './destination';
@@ -12,6 +13,8 @@ import { LifecycleRule } from './rule';
 import { CfnBucket } from './s3.generated';
 import { parseBucketArn, parseBucketName } from './util';
 
+const AUTO_DELETE_OBJECTS_RESOURCE_TYPE = 'Custom::AutoDeleteObjects';
+
 export interface IBucket extends IResource {
   /**
    * The ARN of the bucket.
@@ -1026,6 +1029,16 @@ export interface BucketProps {
    */
   readonly removalPolicy?: RemovalPolicy;
 
+  /**
+   * Whether all objects should be automatically deleted when the bucket is
+   * removed from the stack.
+   *
+   * Requires the removal policy to be set to destroy.
+   *
+   * @default false
+   */
+  readonly autoDeleteObjects?: boolean;
+
   /**
    * Whether this bucket should have versioning turned on or not.
    *
@@ -1301,6 +1314,20 @@ export class Bucket extends BucketBase {
     if (props.publicReadAccess) {
       this.grantPublicAccess();
     }
+
+    if (props.autoDeleteObjects) {
+      if (props.removalPolicy !== RemovalPolicy.DESTROY) {
+        throw new Error("Cannot use 'autoDeleteObjects' property on a bucket without setting removal policy to 'destroy'.");
+      }
+
+      new CustomResource(this, 'AutoDeleteObjectsResource', {
+        resourceType: AUTO_DELETE_OBJECTS_RESOURCE_TYPE,
+        serviceToken: this.getOrCreateAutoDeleteObjectsResource(),
+        properties: {
+          BucketName: this.bucketName,
+        },
+      });
+    }
   }
 
   /**
@@ -1692,6 +1719,23 @@ export class Bucket extends BucketBase {
       };
     });
   }
+
+  private getOrCreateAutoDeleteObjectsResource() {
+    return CustomResourceProvider.getOrCreate(this, AUTO_DELETE_OBJECTS_RESOURCE_TYPE, {
+      codeDirectory: path.join(__dirname, 'auto-delete-objects-handler'),
+      runtime: CustomResourceProviderRuntime.NODEJS_12,
+      policyStatements: [
+        {
+          Effect: 'Allow',
+          Resource: '*',
+          Action: [
+            ...perms.BUCKET_READ_ACTIONS,
+            ...perms.BUCKET_DELETE_ACTIONS,
+          ],
+        },
+      ],
+    });
+  }
 }
 
 /**

packages/@aws-cdk/aws-s3/package.json

@@ -77,7 +77,8 @@
     "cdk-integ-tools": "0.0.0",
     "cfn2ts": "0.0.0",
     "nodeunit": "^0.11.3",
-    "pkglint": "0.0.0"
+    "pkglint": "0.0.0",
+    "sinon": "9.2.0"
   },
   "dependencies": {
     "@aws-cdk/aws-events": "0.0.0",