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

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

packages/backend-function/API.md

@@ -10,6 +10,9 @@ import { FunctionResources } from '@aws-amplify/plugin-types';
 import { ResourceAccessAcceptorFactory } from '@aws-amplify/plugin-types';
 import { ResourceProvider } from '@aws-amplify/plugin-types';
 
+// @public (undocumented)
+export type Cron = `${string} ${string} ${string} ${string} ${string}` | `${string} ${string} ${string} ${string} ${string} ${string}`;
+
 // @public
 export const defineFunction: (props?: FunctionProps) => ConstructFactory<ResourceProvider<FunctionResources> & ResourceAccessAcceptorFactory>;
 
@@ -21,11 +24,18 @@ export type FunctionProps = {
     memoryMB?: number;
     environment?: Record<string, string | BackendSecret>;
     runtime?: NodeVersion;
+    schedule?: TimeInterval | TimeInterval[];
 };
 
 // @public (undocumented)
 export type NodeVersion = 16 | 18 | 20;
 
+// @public (undocumented)
+export type Rate = `every ${number}m` | `every ${number}h` | `every day` | `every week` | `every month` | `every year`;
+
+// @public (undocumented)
+export type TimeInterval = Rate | Cron;
+
 // (No @packageDocumentation comment for this package)
 
 ```

packages/backend-function/src/factory.ts

@@ -31,9 +31,23 @@ import { FunctionEnvironmentTypeGenerator } from './function_env_type_generator.
 import { AttributionMetadataStorage } from '@aws-amplify/backend-output-storage';
 import { fileURLToPath } from 'url';
 import { AmplifyUserError, TagName } from '@aws-amplify/platform-core';
+import { CronOptions, Rule, Schedule } from 'aws-cdk-lib/aws-events';
+import * as targets from 'aws-cdk-lib/aws-events-targets';
 
 const functionStackType = 'function-Lambda';
 
+export type Cron =
+  | `${string} ${string} ${string} ${string} ${string}`
+  | `${string} ${string} ${string} ${string} ${string} ${string}`;
+export type Rate =
+  | `every ${number}m`
+  | `every ${number}h`
+  | `every day`
+  | `every week`
+  | `every month`
+  | `every year`;
+export type TimeInterval = Rate | Cron;
+
 /**
  * Entry point for defining a function in the Amplify ecosystem
  */
@@ -87,6 +101,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?: TimeInterval | TimeInterval[];
 };
 
 /**
@@ -131,6 +158,7 @@ class FunctionFactory implements ConstructFactory<AmplifyFunction> {
       memoryMB: this.resolveMemory(),
       environment: this.props.environment ?? {},
       runtime: this.resolveRuntime(),
+      schedule: this.resolveSchedule(),
     };
   };
 
@@ -220,6 +248,33 @@ 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];
+
+    schedules.forEach((schedule) => {
+      if (isRate(schedule)) {
+        const { value } = parseRate(schedule);
+
+        if (value && !isPositiveWholeNumber(value)) {
+          throw new Error(`schedule must be set with a positive whole number`);
+        }
+      } else {
+        if (!isValidCron(schedule)) {
+          // TODO: Better error messaging here or throw within each part of isValidCron in order to give more concise error messages
+          throw new Error(`schedule cron expression is not valid`);
+        }
+      }
+    });
+
+    return this.props.schedule;
+  };
 }
 
 type HydratedFunctionProps = Required<FunctionProps>;
@@ -296,7 +351,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,
@@ -323,6 +378,30 @@ class AmplifyFunction
       );
     }
 
+    try {
+      const timeIntervals = Array.isArray(props.schedule)
+        ? props.schedule
+        : [props.schedule];
+
+      timeIntervals.forEach((interval, index) => {
+        // Lambda name will be prepended to rule id, so only using index here for uniqueness
+        const rule = new Rule(this, `lambda-schedule${index}`, {
+          schedule: Schedule.cron(translateToCronOptions(interval)),
+        });
+
+        rule.addTarget(new targets.LambdaFunction(functionLambda));
+      });
+    } catch (error) {
+      throw new AmplifyUserError(
+        'NodeJSFunctionScheduleInitializationError',
+        {
+          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(
@@ -396,3 +475,140 @@ const nodeVersionMap: Record<NodeVersion, Runtime> = {
   18: Runtime.NODEJS_18_X,
   20: Runtime.NODEJS_20_X,
 };
+
+const isRate = (timeInterval: TimeInterval): timeInterval is Rate => {
+  return timeInterval.split(' ')[0] === 'every';
+};
+
+const parseRate = (rate: Rate) => {
+  const interval = rate.split(' ')[1];
+
+  const regex = /\d/;
+  if (interval.match(regex)) {
+    return {
+      value: parseInt(interval.substring(0, interval.length - 1)),
+      unit: interval.charAt(interval.length - 1),
+    };
+  }
+
+  return {
+    unit: interval,
+  };
+};
+
+const isPositiveWholeNumber = (test: number) => test > 0 && test % 1 === 0;
+
+const isValidCron = (cron: Cron): boolean => {
+  const cronParts = cron.split(' ');
+
+  if (cronParts.length !== 5 && cronParts.length !== 6) {
+    return false;
+  }
+
+  const [minute, hour, dayOfMonth, month, dayOfWeek, year] = cronParts;
+
+  return (
+    isValidCronPart(minute, 0, 59) &&
+    isValidCronPart(hour, 0, 23) &&
+    (dayOfMonth === '?' || isValidCronPart(dayOfMonth, 1, 31)) &&
+    isValidCronPart(month, 1, 12) &&
+    (dayOfWeek === '?' || isValidCronPart(dayOfWeek, 1, 7)) &&
+    (!year || isValidCronPart(year, 1970, 2199))
+  );
+};
+
+const isValidCronPart = (part: string, min: number, max: number): boolean => {
+  if (part === '*') {
+    return true;
+  }
+  if (part.includes('/')) {
+    return isValidStepValue(part, min, max);
+  }
+  if (part.includes('-')) {
+    return isValidRange(part, min, max);
+  }
+  if (part.includes(',')) {
+    return isValidList(part, min, max);
+  }
+
+  return isWholeNumberBetweenInclusive(Number(part), min, max);
+};
+
+const isValidStepValue = (value: string, min: number, max: number): boolean => {
+  const originalBase = value.split('/')[0];
+  const [base, step] = value.split('/').map(Number);
+
+  if (originalBase === '*') {
+    return !isNaN(step) && step > 0;
+  }
+
+  return (
+    !isNaN(base) &&
+    !isNaN(step) &&
+    isWholeNumberBetweenInclusive(base, min, max) &&
+    step > 0
+  );
+};
+
+const isValidRange = (value: string, min: number, max: number): boolean => {
+  const [start, end] = value.split('-').map(Number);
+  return (
+    !isNaN(start) &&
+    !isNaN(end) &&
+    isWholeNumberBetweenInclusive(start, min, max) &&
+    isWholeNumberBetweenInclusive(end, min, max) &&
+    start <= end
+  );
+};
+
+const isValidList = (value: string, min: number, max: number): boolean => {
+  return value
+    .split(',')
+    .every((v) => isWholeNumberBetweenInclusive(Number(v), min, max));
+};
+
+const translateToCronOptions = (timeInterval: TimeInterval): CronOptions => {
+  if (isRate(timeInterval)) {
+    const { value, unit } = parseRate(timeInterval);
+    switch (unit) {
+      case 'm':
+        return { minute: `*/${value}` };
+      case 'h':
+        return { minute: '0', hour: `*/${value}` };
+      case 'day':
+        return { minute: '0', hour: '0', day: `*` };
+      case 'week':
+        return { minute: '0', hour: '0', weekDay: `1` };
+      case 'month':
+        return { minute: '0', hour: '0', day: '1', month: `*` };
+      case 'year':
+        return {
+          minute: '0',
+          hour: '0',
+          day: '1',
+          month: '1',
+          year: `*`,
+        };
+      default:
+        // This should never happen with strict types
+        throw new Error('Could not determine the schedule for the function');
+    }
+  } else {
+    const cronArray = timeInterval.split(' ');
+    const result: Record<string, string> = {
+      minute: cronArray[0],
+      hour: cronArray[1],
+      month: cronArray[3],
+      year: cronArray.length === 6 ? cronArray[5] : '*',
+    };
+
+    // Branching logic here is because we cannot supply both day and weekDay
+    if (cronArray[2] === '*') {
+      result.weekDay = cronArray[4];
+    } else {
+      result.day = cronArray[2];
+    }
+
+    return result;
+  }
+};