feat: add support for scheduling functions

.changeset/green-coins-lie.md

@@ -0,0 +1,5 @@
+---
+'@aws-amplify/backend-function': minor
+---
+
+add support for scheduling functions

.eslint_dictionary.json

@@ -27,6 +27,7 @@
   "commonjs",
   "corepack",
   "cors",
+  "cron",
   "ctor",
   "darwin",
   "datastore",

packages/backend-function/API.md

@@ -15,6 +15,9 @@ export type AddEnvironmentFactory = {
     addEnvironment: (key: string, value: string | BackendSecret) => void;
 };
 
+// @public (undocumented)
+export type CronSchedule = `${string} ${string} ${string} ${string} ${string}` | `${string} ${string} ${string} ${string} ${string} ${string}`;
+
 // @public
 export const defineFunction: (props?: FunctionProps) => ConstructFactory<ResourceProvider<FunctionResources> & ResourceAccessAcceptorFactory & AddEnvironmentFactory>;
 
@@ -26,11 +29,18 @@ export type FunctionProps = {
     memoryMB?: number;
     environment?: Record<string, string | BackendSecret>;
     runtime?: NodeVersion;
+    schedule?: FunctionSchedule | FunctionSchedule[];
 };
 
+// @public (undocumented)
+export type FunctionSchedule = TimeInterval | CronSchedule;
+
 // @public (undocumented)
 export type NodeVersion = 16 | 18 | 20;
 
+// @public (undocumented)
+export type TimeInterval = `every ${number}m` | `every ${number}h` | `every day` | `every week` | `every month` | `every year`;
+
 // (No @packageDocumentation comment for this package)
 
 ```

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

@@ -334,6 +334,77 @@ void describe('AmplifyFunctionFactory', () => {
     });
   });
 
+  void describe('schedule property', () => {
+    void it('sets valid schedule - rate', () => {
+      const lambda = defineFunction({
+        entry: './test-assets/default-lambda/handler.ts',
+        schedule: 'every 5m',
+      }).getInstance(getInstanceProps);
+      const template = Template.fromStack(Stack.of(lambda.resources.lambda));
+
+      template.hasResourceProperties('AWS::Events::Rule', {
+        ScheduleExpression: 'cron(*/5 * * * ? *)',
+        Targets: [
+          {
+            Arn: {
+              // eslint-disable-next-line spellcheck/spell-checker
+              'Fn::GetAtt': ['handlerlambdaE29D1580', 'Arn'],
+            },
+            Id: 'Target0',
+          },
+        ],
+      });
+    });
+
+    void it('sets valid schedule - cron', () => {
+      const lambda = defineFunction({
+        entry: './test-assets/default-lambda/handler.ts',
+        schedule: '0 1 * * ?',
+      }).getInstance(getInstanceProps);
+      const template = Template.fromStack(Stack.of(lambda.resources.lambda));
+
+      template.hasResourceProperties('AWS::Events::Rule', {
+        ScheduleExpression: 'cron(0 1 * * ? *)',
+        Targets: [
+          {
+            Arn: {
+              // eslint-disable-next-line spellcheck/spell-checker
+              'Fn::GetAtt': ['handlerlambdaE29D1580', 'Arn'],
+            },
+            Id: 'Target0',
+          },
+        ],
+      });
+    });
+
+    void it('sets valid schedule array', () => {
+      const lambda = defineFunction({
+        entry: './test-assets/default-lambda/handler.ts',
+        schedule: ['0 1 * * ?', 'every 5m'],
+      }).getInstance(getInstanceProps);
+      const template = Template.fromStack(Stack.of(lambda.resources.lambda));
+
+      template.resourceCountIs('AWS::Events::Rule', 2);
+
+      template.hasResourceProperties('AWS::Events::Rule', {
+        ScheduleExpression: 'cron(0 1 * * ? *)',
+      });
+
+      template.hasResourceProperties('AWS::Events::Rule', {
+        ScheduleExpression: 'cron(*/5 * * * ? *)',
+      });
+    });
+
+    void it('defaults to no event rule created', () => {
+      const lambda = defineFunction({
+        entry: './test-assets/default-lambda/handler.ts',
+      }).getInstance(getInstanceProps);
+      const template = Template.fromStack(Stack.of(lambda.resources.lambda));
+
+      template.resourceCountIs('AWS::Events::Rule', 0);
+    });
+  });
+
   void describe('resourceAccessAcceptor', () => {
     void it('attaches policy to execution role and configures ssm environment context', () => {
       const functionFactory = defineFunction({

packages/backend-function/src/factory.ts

@@ -31,13 +31,28 @@ import { FunctionEnvironmentTypeGenerator } from './function_env_type_generator.
 import { AttributionMetadataStorage } from '@aws-amplify/backend-output-storage';
 import { fileURLToPath } from 'node:url';
 import { AmplifyUserError, TagName } from '@aws-amplify/platform-core';
+import { convertFunctionSchedulesToRuleSchedules } from './schedule_parser.js';
+import * as targets from 'aws-cdk-lib/aws-events-targets';
+import { Rule } from 'aws-cdk-lib/aws-events';
 
 const functionStackType = 'function-Lambda';
 
 export type AddEnvironmentFactory = {
   addEnvironment: (key: string, value: string | BackendSecret) => void;
 };
 
+export type CronSchedule =
+  | `${string} ${string} ${string} ${string} ${string}`
+  | `${string} ${string} ${string} ${string} ${string} ${string}`;
+export type TimeInterval =
+  | `every ${number}m`
+  | `every ${number}h`
+  | `every day`
+  | `every week`
+  | `every month`
+  | `every year`;
+export type FunctionSchedule = TimeInterval | CronSchedule;
+
 /**
  * Entry point for defining a function in the Amplify ecosystem
  */
@@ -93,6 +108,19 @@ export type FunctionProps = {
    * Defaults to the oldest NodeJS LTS version. See https://nodejs.org/en/about/previous-releases
    */
   runtime?: NodeVersion;
+
+  /**
+   * A time interval string to periodically run the function.
+   * This can be either a string of `"every <positive whole number><m (minute) or h (hour)>"`, `"every day|week|month|year"` or cron expression.
+   * Defaults to no scheduling for the function.
+   * @example
+   * schedule: "every 5m"
+   * @example
+   * schedule: "every week"
+   * @example
+   * schedule: "0 9 * * 2" // every Monday at 9am
+   */
+  schedule?: FunctionSchedule | FunctionSchedule[];
 };
 
 /**
@@ -137,6 +165,7 @@ class FunctionFactory implements ConstructFactory<AmplifyFunction> {
       memoryMB: this.resolveMemory(),
       environment: this.props.environment ?? {},
       runtime: this.resolveRuntime(),
+      schedule: this.resolveSchedule(),
     };
   };
 
@@ -226,6 +255,18 @@ class FunctionFactory implements ConstructFactory<AmplifyFunction> {
 
     return this.props.runtime;
   };
+
+  private resolveSchedule = () => {
+    if (!this.props.schedule) {
+      return [];
+    }
+
+    const schedules = Array.isArray(this.props.schedule)
+      ? this.props.schedule
+      : [this.props.schedule];
+
+    return schedules;
+  };
 }
 
 type HydratedFunctionProps = Required<FunctionProps>;
@@ -305,7 +346,7 @@ class AmplifyFunction
     // This will be overwritten with the typed file at the end of synthesis
     functionEnvironmentTypeGenerator.generateProcessEnvShim();
 
-    let functionLambda;
+    let functionLambda: NodejsFunction;
     try {
       functionLambda = new NodejsFunction(scope, `${id}-lambda`, {
         entry: props.entry,
@@ -335,6 +376,36 @@ class AmplifyFunction
       );
     }
 
+    const timeIntervals = Array.isArray(props.schedule)
+      ? props.schedule
+      : [props.schedule];
+
+    try {
+      const schedules = convertFunctionSchedulesToRuleSchedules(
+        functionLambda,
+        timeIntervals
+      );
+      const lambdaTarget = new targets.LambdaFunction(functionLambda);
+
+      schedules.forEach((schedule, index) => {
+        // Lambda name will be prepended to rule id, so only using index here for uniqueness
+        const rule = new Rule(functionLambda, `schedule${index}`, {
+          schedule,
+        });
+
+        rule.addTarget(lambdaTarget);
+      });
+    } catch (error) {
+      throw new AmplifyUserError(
+        'FunctionScheduleInitializationError',
+        {
+          message: 'Failed to instantiate schedule for nodejs function',
+          resolution: 'See the underlying error message for more details.',
+        },
+        error as Error
+      );
+    }
+
     Tags.of(functionLambda).add(TagName.FRIENDLY_NAME, id);
 
     this.functionEnvironmentTranslator = new FunctionEnvironmentTranslator(