feat(scheduler): start and end time for schedule construct (#28306)

This PR added support for start and end time of the schedule.

## Description
Currently, users cannot set a start time and an end time for the schedule.
A schedule without a start date will begin as soon as it is created and available, and without an end date, it will continue to invoke its target indefinitely.
With this feature, users can set the start and end dates of a schedule, allowing for more flexible schedule configurations.
https://docs.aws.amazon.com/ja_jp/AWSCloudFormation/latest/UserGuide/aws-resource-scheduler-schedule.html#cfn-scheduler-schedule-startdate
https://docs.aws.amazon.com/ja_jp/AWSCloudFormation/latest/UserGuide/aws-resource-scheduler-schedule.html#cfn-scheduler-schedule-enddate

In CloudFormation, users can use this feature as follows:
```yaml
  TestSchedule:
    Type: AWS::Scheduler::Schedule
    Properties: 
      StartDate: "2024-12-01T13:09:00.000Z"
      EndDate: "2025-12-01T00:00:00.001Z"
      ScheduleExpression: "at(2023-01-01T00:00:00)"
      State: "ENABLED"
      Target: # target
```

## Major changes
### add property to ScheduleProps interface
Added startDate and endDate properties, and typed these values as string based on the following PR comments.
#26819 (comment)

It is not necessary to specify both startDate and endDate, they can be set independently.
Validation is performed on the following points.
- Error if not following ISO 8601 format.
  - Must include milliseconds (yyyy-MM-ddTHH:mm:ss.SSSZ)
- Error if startDate is later than endDate

If a time before the current time is specified, the following error occurs in CFn, but no validation is performed because the timing of validation in CDK and the timing of actual deployment are different.
`The StartDate you specify cannot be earlier than 5 minutes ago.`

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: sakurai-ryo

packages/@aws-cdk/aws-scheduler-alpha/README.md

@@ -138,6 +138,20 @@ new Schedule(this, 'Schedule', {
 });
 ```
 
+### Configuring a start and end time of the Schedule
+
+If you choose a recurring schedule, you can set the start and end time of the Schedule by specifying the `start` and `end`.
+
+```ts
+declare const target: targets.LambdaInvoke;
+
+new Schedule(this, 'Schedule', {
+    schedule: ScheduleExpression.rate(cdk.Duration.hours(12)),
+    target: target,
+    start: new Date('2023-01-01T00:00:00.000Z'),
+    end: new Date('2023-02-01T00:00:00.000Z'),
+});
+```
 
 ## Scheduler Targets
 

packages/@aws-cdk/aws-scheduler-alpha/lib/schedule.ts

@@ -114,6 +114,22 @@ export interface ScheduleProps {
    * @default - All events in Scheduler are encrypted with a key that AWS owns and manages.
    */
   readonly key?: kms.IKey;
+
+  /**
+   * The date, in UTC, after which the schedule can begin invoking its target.
+   * EventBridge Scheduler ignores start for one-time schedules.
+   *
+   * @default - no value
+   */
+  readonly start?: Date;
+
+  /**
+   * The date, in UTC, before which the schedule can invoke its target.
+   * EventBridge Scheduler ignores end for one-time schedules.
+   *
+   * @default - no value
+   */
+  readonly end?: Date;
 }
 
 /**
@@ -254,6 +270,8 @@ export class Schedule extends Resource implements ISchedule {
 
     this.retryPolicy = targetConfig.retryPolicy;
 
+    this.validateTimeFrame(props.start, props.end);
+
     const resource = new CfnSchedule(this, 'Resource', {
       name: this.physicalName,
       flexibleTimeWindow: { mode: 'OFF' },
@@ -276,6 +294,8 @@ export class Schedule extends Resource implements ISchedule {
         sageMakerPipelineParameters: targetConfig.sageMakerPipelineParameters,
         sqsParameters: targetConfig.sqsParameters,
       },
+      startDate: props.start?.toISOString(),
+      endDate: props.end?.toISOString(),
     });
 
     this.scheduleName = this.getResourceNameAttribute(resource.ref);
@@ -306,4 +326,10 @@ export class Schedule extends Resource implements ISchedule {
     const isEmptyPolicy = Object.values(policy).every(value => value === undefined);
     return !isEmptyPolicy ? policy : undefined;
   }
-}
+
+  private validateTimeFrame(start?: Date, end?: Date) {
+    if (start && end && start >= end) {
+      throw new Error(`start must precede end, got start: ${start.toISOString()}, end: ${end.toISOString()}`);
+    }
+  }
+}

packages/@aws-cdk/aws-scheduler-alpha/test/integ.schedule.js.snapshot/aws-cdk-scheduler-schedule.assets.json

@@ -348,6 +348,38 @@
      }
     }
    }
+  },
+  "ScheduleWithTimeFrameC1C8BDCC": {
+   "Type": "AWS::Scheduler::Schedule",
+   "Properties": {
+    "EndDate": "2025-10-01T00:00:00.000Z",
+    "FlexibleTimeWindow": {
+     "Mode": "OFF"
+    },
+    "ScheduleExpression": "rate(12 hours)",
+    "ScheduleExpressionTimezone": "Etc/UTC",
+    "StartDate": "2024-04-15T06:30:00.000Z",
+    "State": "ENABLED",
+    "Target": {
+     "Arn": {
+      "Fn::GetAtt": [
+       "Function76856677",
+       "Arn"
+      ]
+     },
+     "Input": "\"Input Text\"",
+     "RetryPolicy": {
+      "MaximumEventAgeInSeconds": 180,
+      "MaximumRetryAttempts": 3
+     },
+     "RoleArn": {
+      "Fn::GetAtt": [
+       "Role1ABCC5F0",
+       "Arn"
+      ]
+     }
+    }
+   }
   }
  },
  "Parameters": {

packages/@aws-cdk/aws-scheduler-alpha/test/integ.schedule.js.snapshot/aws-cdk-scheduler-schedule.template.json

@@ -90,6 +90,14 @@ new scheduler.Schedule(stack, 'CustomerKmsSchedule', {
   key,
 });
 
+const currentYear = new Date().getFullYear();
+new scheduler.Schedule(stack, 'ScheduleWithTimeFrame', {
+  schedule: expression,
+  target: target,
+  start: new Date(`${currentYear + 1}-04-15T06:30:00.000Z`),
+  end: new Date(`${currentYear + 2}-10-01T00:00:00.000Z`),
+});
+
 new IntegTest(app, 'integtest-schedule', {
   testCases: [stack],
 });

packages/@aws-cdk/aws-scheduler-alpha/test/integ.schedule.js.snapshot/cdk.out

@@ -128,4 +128,37 @@ describe('Schedule', () => {
       },
     });
   });
-});
+
+  describe('schedule timeFrame', () => {
+    test.each([
+      { StartDate: '2023-04-15T06:20:00.000Z', EndDate: '2023-10-01T00:00:00.000Z' },
+      { StartDate: '2023-04-15T06:25:00.000Z' },
+      { EndDate: '2023-10-01T00:00:00.000Z' },
+    ])('schedule can set start and end', (timeFrame) => {
+      new Schedule(stack, 'TestSchedule', {
+        schedule: expr,
+        target: new SomeLambdaTarget(func, role),
+        start: timeFrame.StartDate ? new Date(timeFrame.StartDate) : undefined,
+        end: timeFrame.EndDate ? new Date(timeFrame.EndDate) : undefined,
+      });
+
+      Template.fromStack(stack).hasResourceProperties('AWS::Scheduler::Schedule', {
+        ...timeFrame,
+      });
+    });
+
+    test.each([
+      { start: '2023-10-01T00:00:00.000Z', end: '2023-10-01T00:00:00.000Z' },
+      { start: '2023-10-01T00:00:00.000Z', end: '2023-09-01T00:00:00.000Z' },
+    ])('throw error when start does not come before end', ({ start, end }) => {
+      expect(() => {
+        new Schedule(stack, 'TestSchedule', {
+          schedule: expr,
+          target: new SomeLambdaTarget(func, role),
+          start: new Date(start),
+          end: new Date(end),
+        });
+      }).toThrow(`start must precede end, got start: ${start}, end: ${end}`);
+    });
+  });
+});