Add ephemeralStorageSizeMB option to defineFunction (#2283)

* Add ephemeralStorageSize option to defineFunction

* fixup

* fix: remove unit from default value

* re-generate api reports

* rename ephemeralStorageSize to ephemeralStorageSizeMB

* add `mebibytes` to eslint dictionary

* fix: throw AmplifyUserError instead of Error

.changeset/nasty-tables-heal.md

@@ -0,0 +1,5 @@
+---
+'@aws-amplify/backend-function': minor
+---
+
+Add ephemeralStorageSizeMB option to defineFunction

.eslint_dictionary.json

@@ -100,6 +100,7 @@
   "lstat",
   "macos",
   "matchers",
+  "mebibytes",
   "mfas",
   "minify",
   "mkdtemp",

packages/backend-function/API.md

@@ -93,6 +93,7 @@ export type FunctionProps = {
     entry?: string;
     timeoutSeconds?: number;
     memoryMB?: number;
+    ephemeralStorageSizeMB?: number;
     environment?: Record<string, string | BackendSecret>;
     runtime?: NodeVersion;
     schedule?: FunctionSchedule | FunctionSchedule[];

packages/backend-function/src/factory.test.ts

@@ -683,4 +683,71 @@ void describe('AmplifyFunctionFactory', () => {
       'function-Lambda'
     );
   });
+
+  void describe('ephemeralStorageSizeMB property', () => {
+    void it('sets valid ephemeralStorageSize', () => {
+      const lambda = defineFunction({
+        entry: './test-assets/default-lambda/handler.ts',
+        ephemeralStorageSizeMB: 1024,
+      }).getInstance(getInstanceProps);
+      const template = Template.fromStack(lambda.stack);
+
+      template.hasResourceProperties('AWS::Lambda::Function', {
+        EphemeralStorage: { Size: 1024 },
+      });
+    });
+
+    void it('sets default ephemeralStorageSizeMB', () => {
+      const lambda = defineFunction({
+        entry: './test-assets/default-lambda/handler.ts',
+      }).getInstance(getInstanceProps);
+      const template = Template.fromStack(lambda.stack);
+
+      template.hasResourceProperties('AWS::Lambda::Function', {
+        EphemeralStorage: { Size: 512 },
+      });
+    });
+
+    void it('throws on ephemeralStorageSizeMB below 512 MB', () => {
+      assert.throws(
+        () =>
+          defineFunction({
+            entry: './test-assets/default-lambda/handler.ts',
+            ephemeralStorageSizeMB: 511,
+          }).getInstance(getInstanceProps),
+        new AmplifyUserError('InvalidEphemeralStorageSizeMBError', {
+          message: `Invalid function ephemeralStorageSizeMB of 511`,
+          resolution: `ephemeralStorageSizeMB must be a whole number between 512 and 10240 inclusive`,
+        })
+      );
+    });
+
+    void it('throws on ephemeralStorageSizeMB above 10240 MB', () => {
+      assert.throws(
+        () =>
+          defineFunction({
+            entry: './test-assets/default-lambda/handler.ts',
+            ephemeralStorageSizeMB: 10241,
+          }).getInstance(getInstanceProps),
+        new AmplifyUserError('InvalidEphemeralStorageSizeMBError', {
+          message: `Invalid function ephemeralStorageSizeMB of 10241`,
+          resolution: `ephemeralStorageSizeMB must be a whole number between 512 and 10240 inclusive`,
+        })
+      );
+    });
+
+    void it('throws on fractional ephemeralStorageSizeMB', () => {
+      assert.throws(
+        () =>
+          defineFunction({
+            entry: './test-assets/default-lambda/handler.ts',
+            ephemeralStorageSizeMB: 512.5,
+          }).getInstance(getInstanceProps),
+        new AmplifyUserError('InvalidEphemeralStorageSizeMBError', {
+          message: `Invalid function ephemeralStorageSizeMB of 512.5`,
+          resolution: `ephemeralStorageSizeMB must be a whole number between 512 and 10240 inclusive`,
+        })
+      );
+    });
+  });
 });

packages/backend-function/src/factory.ts

@@ -26,7 +26,7 @@ import {
   SsmEnvironmentEntry,
   StackProvider,
 } from '@aws-amplify/plugin-types';
-import { Duration, Stack, Tags } from 'aws-cdk-lib';
+import { Duration, Size, Stack, Tags } from 'aws-cdk-lib';
 import { Rule } from 'aws-cdk-lib/aws-events';
 import * as targets from 'aws-cdk-lib/aws-events-targets';
 import { Policy } from 'aws-cdk-lib/aws-iam';
@@ -115,6 +115,13 @@ export type FunctionProps = {
    */
   memoryMB?: number;
 
+  /**
+   * The size of the function's /tmp directory in MB.
+   * Must be a whole number.
+   * @default 512
+   */
+  ephemeralStorageSizeMB?: number;
+
   /**
    * Environment variables that will be available during function execution
    */
@@ -236,6 +243,7 @@ class FunctionFactory implements ConstructFactory<AmplifyFunction> {
       entry: this.resolveEntry(),
       timeoutSeconds: this.resolveTimeout(),
       memoryMB: this.resolveMemory(),
+      ephemeralStorageSizeMB: this.resolveEphemeralStorageSize(),
       environment: this.resolveEnvironment(),
       runtime: this.resolveRuntime(),
       schedule: this.resolveSchedule(),
@@ -324,6 +332,28 @@ class FunctionFactory implements ConstructFactory<AmplifyFunction> {
     return this.props.memoryMB;
   };
 
+  private resolveEphemeralStorageSize = () => {
+    const ephemeralStorageSizeMin = 512;
+    const ephemeralStorageSizeMax = 10240;
+    const ephemeralStorageSizeDefault = 512;
+    if (this.props.ephemeralStorageSizeMB === undefined) {
+      return ephemeralStorageSizeDefault;
+    }
+    if (
+      !isWholeNumberBetweenInclusive(
+        this.props.ephemeralStorageSizeMB,
+        ephemeralStorageSizeMin,
+        ephemeralStorageSizeMax
+      )
+    ) {
+      throw new AmplifyUserError('InvalidEphemeralStorageSizeMBError', {
+        message: `Invalid function ephemeralStorageSizeMB of ${this.props.ephemeralStorageSizeMB}`,
+        resolution: `ephemeralStorageSizeMB must be a whole number between ${ephemeralStorageSizeMin} and ${ephemeralStorageSizeMax} inclusive`,
+      });
+    }
+    return this.props.ephemeralStorageSizeMB;
+  };
+
   private resolveEnvironment = () => {
     if (this.props.environment === undefined) {
       return {};
@@ -509,6 +539,7 @@ class AmplifyFunction
         entry: props.entry,
         timeout: Duration.seconds(props.timeoutSeconds),
         memorySize: props.memoryMB,
+        ephemeralStorageSize: Size.mebibytes(props.ephemeralStorageSizeMB),
         runtime: nodeVersionMap[props.runtime],
         layers: props.resolvedLayers,
         bundling: {