Add trigger handler for storage events

packages/backend-storage/API.md

@@ -6,7 +6,9 @@
 
 import { BackendOutputStorageStrategy } from '@aws-amplify/plugin-types';
 import { ConstructFactory } from '@aws-amplify/plugin-types';
+import { FunctionResources } from '@aws-amplify/plugin-types';
 import { IBucket } from 'aws-cdk-lib/aws-s3';
+import { IFunction } from 'aws-cdk-lib/aws-lambda';
 import { ResourceProvider } from '@aws-amplify/plugin-types';
 import { StorageOutput } from '@aws-amplify/backend-output-schemas';
 
@@ -18,8 +20,15 @@ export type AmplifyStorageProps = {
     name: string;
     versioned?: boolean;
     outputStorageStrategy?: BackendOutputStorageStrategy<StorageOutput>;
+    triggers?: Partial<Record<AmplifyStorageTriggerEvent, ConstructFactory<ResourceProvider<FunctionResources>>>>;
 };
 
+// @public (undocumented)
+export type AmplifyStorageTriggerEvent = 'onDelete' | 'onUpload';
+
+// @public (undocumented)
+export type AmplifyStorageTriggerHandlers = Partial<Record<AmplifyStorageTriggerEvent, IFunction>>;
+
 // @public
 export const defineStorage: (props: AmplifyStorageProps) => ConstructFactory<ResourceProvider<StorageResources>>;
 

packages/backend-storage/src/construct.ts

@@ -1,7 +1,10 @@
 import { Construct } from 'constructs';
-import { Bucket, BucketProps, IBucket } from 'aws-cdk-lib/aws-s3';
+import { Bucket, BucketProps, EventType, IBucket } from 'aws-cdk-lib/aws-s3';
 import {
+  AmplifyFunction,
   BackendOutputStorageStrategy,
+  ConstructFactory,
+  FunctionResources,
   ResourceProvider,
 } from '@aws-amplify/plugin-types';
 import {
@@ -14,6 +17,13 @@
   StackMetadataBackendOutputStorageStrategy,
 } from '@aws-amplify/backend-output-storage';
 import { fileURLToPath } from 'url';
+import {
+  FunctionInstanceProvider,
+  addEventSource,
+} from './function_instance_provider.js';
+import { IFunction } from 'aws-cdk-lib/aws-lambda';
+import { AmplifyStorageTriggerEvent } from './factory.js';
+import { S3EventSource } from 'aws-cdk-lib/aws-lambda-event-sources';
 
 // Be very careful editing this value. It is the string that is used to attribute stacks to Amplify Storage in BI metrics
 const storageStackType = 'storage-S3';
@@ -22,6 +32,12 @@
   name: string;
   versioned?: boolean;
   outputStorageStrategy?: BackendOutputStorageStrategy<StorageOutput>;
+  triggers?: Partial<
+    Record<
+      AmplifyStorageTriggerEvent,
+      ConstructFactory<ResourceProvider<FunctionResources>>
+    >
+  >;
 };
 
 export type StorageResources = {
@@ -38,6 +54,7 @@
   implements ResourceProvider<StorageResources>
 {
   readonly resources: StorageResources;
+  private readonly functionInstanceProvider: FunctionInstanceProvider;
   /**
    * Create a new AmplifyStorage instance
    */
@@ -47,11 +64,11 @@
     const bucketProps: BucketProps = {
       versioned: props.versioned || false,
     };
+    const bucket = new Bucket(this, 'Bucket', bucketProps);
 
     this.resources = {
-      bucket: new Bucket(this, 'Bucket', bucketProps),
+      bucket,
     };
-
     this.storeOutput(props.outputStorageStrategy);
 
     new AttributionMetadataStorage().storeAttributionMetadata(
@@ -61,6 +78,17 @@
     );
   }
 
+  /**
+   * Attach a Lambda function trigger handler to the S3 events
+   * @param events - list of S3 events that will trigger the handler
+   * @param handler - The function that will handle the event
+   */
+  addTrigger = (events: EventType[], handler: IFunction): void => {
+    handler.addEventSource(
+      new S3EventSource(this.resources.bucket as Bucket, { events })
+    );
+  };
+
   /**
    * Store storage outputs using provided strategy
    */

packages/backend-storage/src/factory.ts

@@ -14,12 +14,24 @@ import {
   StorageResources,
 } from './construct.js';
 import { AmplifyUserError } from '@aws-amplify/platform-core';
+import { IFunction } from 'aws-cdk-lib/aws-lambda';
+import {
+  FunctionInstanceProvider,
+  buildConstructFactoryFunctionInstanceProvider,
+} from './function_instance_provider.js';
+import { EventType } from 'aws-cdk-lib/aws-s3';
 
 export type AmplifyStorageFactoryProps = Omit<
   AmplifyStorageProps,
   'outputStorageStrategy'
 >;
 
+export type AmplifyStorageTriggerEvent = 'onDelete' | 'onUpload';
+
+export type AmplifyStorageTriggerHandlers = Partial<
+  Record<AmplifyStorageTriggerEvent, IFunction>
+>;
+
 /**
  * Singleton factory for a Storage bucket that can be used in `resource.ts` files
  */
@@ -39,11 +51,9 @@ class AmplifyStorageFactory
   /**
    * Get a singleton instance of the Bucket
    */
-  getInstance = ({
-    constructContainer,
-    outputStorageStrategy,
-    importPathVerifier,
-  }: ConstructFactoryGetInstanceProps): AmplifyStorage => {
+  getInstance = (props: ConstructFactoryGetInstanceProps): AmplifyStorage => {
+    const { constructContainer, outputStorageStrategy, importPathVerifier } =
+      props;
     importPathVerifier?.verify(
       this.importStack,
       path.join('amplify', 'storage', 'resource'),
@@ -53,6 +63,7 @@ class AmplifyStorageFactory
     if (!this.generator) {
       this.generator = new AmplifyStorageGenerator(
         this.props,
+        buildConstructFactoryFunctionInstanceProvider(props),
         outputStorageStrategy
       );
     }
@@ -76,14 +87,34 @@ class AmplifyStorageGenerator implements ConstructContainerEntryGenerator {
 
   constructor(
     private readonly props: AmplifyStorageProps,
+    private readonly functionInstanceProvider: FunctionInstanceProvider,
     private readonly outputStorageStrategy: BackendOutputStorageStrategy<BackendOutputEntry>
   ) {}
 
   generateContainerEntry = (scope: Construct) => {
-    return new AmplifyStorage(scope, `${this.props.name}`, {
+    const storageConstruct = new AmplifyStorage(scope, `${this.props.name}`, {
       ...this.props,
       outputStorageStrategy: this.outputStorageStrategy,
     });
+
+    Object.entries(this.props.triggers || {}).forEach(
+      ([triggerEvent, handlerFactory]) => {
+        const events = [];
+        const handler = this.functionInstanceProvider.provide(handlerFactory);
+        // triggerEvent is converted string from Object.entries
+        switch (triggerEvent as AmplifyStorageTriggerEvent) {
+          case 'onDelete':
+            events.push(EventType.OBJECT_REMOVED);
+            break;
+          case 'onUpload':
+            events.push(EventType.OBJECT_CREATED);
+            break;
+        }
+        storageConstruct.addTrigger(events, handler);
+      }
+    );
+
+    return storageConstruct;
   };
 }
 

packages/backend-storage/src/function_instance_provider.ts

@@ -0,0 +1,36 @@
+import {
+  AmplifyFunction,
+  ConstructFactory,
+  ConstructFactoryGetInstanceProps,
+} from '@aws-amplify/plugin-types';
+import { IFunction } from 'aws-cdk-lib/aws-lambda';
+import {
+  S3EventSource,
+  S3EventSourceProps,
+} from 'aws-cdk-lib/aws-lambda-event-sources';
+import { Bucket } from 'aws-cdk-lib/aws-s3';
+
+export type FunctionInstanceProvider = {
+  provide: (func: ConstructFactory<AmplifyFunction>) => IFunction;
+};
+
+/**
+ * Build a function instance provider using the construct factory.
+ */
+export const buildConstructFactoryFunctionInstanceProvider = (
+  props: ConstructFactoryGetInstanceProps
+) => ({
+  provide: (func: ConstructFactory<AmplifyFunction>): IFunction =>
+    func.getInstance(props).resources.lambda,
+});
+
+/**
+ * Add s3 event source for lambda function.
+ */
+export const addEventSource = (
+  bucket: Bucket,
+  lambda: IFunction,
+  eventSourceProp: S3EventSourceProps
+) => {
+  lambda.addEventSource(new S3EventSource(bucket, eventSourceProp));
+};

packages/backend/src/index.ts

@@ -1,3 +1,6 @@
+import { defineFunction } from '@aws-amplify/backend-function';
+import { defineStorage } from '@aws-amplify/backend-storage';
+
 export { defineBackend } from './backend_factory.js';
 export * from './backend.js';
 export * from './secret.js';
@@ -16,3 +19,12 @@ export { defineStorage } from '@aws-amplify/backend-storage';
 
 // function
 export { defineFunction } from '@aws-amplify/backend-function';
+
+const onDeleteHandler = defineFunction();
+
+defineStorage({
+  name: 'myStorage',
+  triggers: {
+    onDelete: onDeleteHandler,
+  },
+});

packages/integration-tests/src/test-in-memory/integration_tests.test.ts

@@ -6,6 +6,8 @@
 import { it } from 'node:test';
 import { dataWithoutAuth } from '../test-projects/standalone-data-auth-modes/amplify/test_factories.js';
 import { dataWithoutAuthNoAuthMode } from '../test-projects/standalone-data-sandbox-mode/amplify/test_factories.js';
+import assert from 'node:assert';
+import { Match } from 'aws-cdk-lib/assertions';
 
 /**
  * This test suite is meant to provide a fast feedback loop to sanity check that different feature verticals are working properly together.
@@ -41,6 +43,23 @@
     // eslint-disable-next-line spellcheck/spell-checker
     'testNameBucketB4152AD5',
   ]);
+
+  /* eslint-disable spellcheck/spell-checker */
+  templates.storage.hasResource('Custom::S3BucketNotifications', {
+    DependsOn: [
+      'testNameBucketAllowBucketNotificationsToamplifytestAppIdtestBranchNamebranch7d6f6c854afunctiononDeletelambda572CB9D7EA473960',
+      'testNameBucketAllowBucketNotificationsToamplifytestAppIdtestBranchNamebranch7d6f6c854afunctiononUploadlambda74F01BD6AFF08959',
+    ],
+  });
+
+  templates.myFunc.hasResource('AWS::Lambda::Function', {
+    DependsOn: ['onDeletelambdaServiceRole3B882F08'],
+  });
+
+  templates.myFunc.hasResource('AWS::Lambda::Function', {
+    DependsOn: ['onUploadlambdaServiceRoleDBC7D933'],
+  });
+  /* eslint-enable spellcheck/spell-checker */
 });
 
 void it('data without auth with lambda auth mode', () => {

packages/integration-tests/src/test-projects/data-storage-auth-with-triggers-ts/amplify/function.ts

@@ -19,3 +19,7 @@ export const node16Func = defineFunction({
   },
   runtime: 16
 })
+
+
+export const onDelete = defineFunction({ 'name': 'onDelete', entry: './func-src/handler.ts' });
+export const onUpload = defineFunction({ 'name': 'onUpload', entry: './func-src/handler.ts' });

packages/integration-tests/src/test-projects/data-storage-auth-with-triggers-ts/amplify/storage/resource.ts

@@ -1,3 +1,10 @@
 import { defineStorage } from '@aws-amplify/backend';
+import { onDelete, onUpload } from '../function.js';
 
-export const storage = defineStorage({name: 'testName'});
+export const storage = defineStorage({
+    name: 'testName',
+    triggers: {
+        onDelete,
+        onUpload,
+    }
+});