feat(location): support RouteCalculator (#30682)

### Issue # (if applicable)

Closes #30681 .

### Reason for this change
In [aws-location-alpha](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-location-alpha-readme.html), [route calculator](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_location.CfnRouteCalculator.html) has not been supported yet.



### Description of changes
Add `RouteCalculator` class.



### Description of how you validated changes
Add unit tests and integ tests.


### Checklist
- [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

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

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

@@ -77,3 +77,30 @@ const geofenceCollection = new location.GeofenceCollection(this, 'GeofenceCollec
 
 geofenceCollection.grantRead(role);
 ```
+
+## Route Calculator
+
+Route calculator resources allow you to find routes and estimate travel time based on up-to-date road network and live traffic information from your chosen data provider.
+
+For more information, see [Routes](https://docs.aws.amazon.com/location/latest/developerguide/route-concepts.html).
+
+To create a route calculator, define a `RouteCalculator`:
+
+```ts
+new location.RouteCalculator(this, 'RouteCalculator', {
+  routeCalculatorName: 'MyRouteCalculator', // optional, defaults to a generated name
+  dataSource: location.DataSource.ESRI,
+});
+```
+
+Use the `grant()` or `grantRead()` method to grant the given identity permissions to perform actions
+on the route calculator:
+
+```ts
+declare const role: iam.Role;
+
+const routeCalculator = new location.RouteCalculator(this, 'RouteCalculator', {
+  dataSource: location.DataSource.ESRI,
+});
+routeCalculator.grantRead(role);
+```

packages/@aws-cdk/aws-location-alpha/lib/index.ts

@@ -1,4 +1,6 @@
 export * from './geofence-collection';
 export * from './place-index';
+export * from './route-calculator';
+export * from './util';
 
 // AWS::Location CloudFormation Resources:

packages/@aws-cdk/aws-location-alpha/lib/place-index.ts

@@ -2,7 +2,7 @@ import * as iam from 'aws-cdk-lib/aws-iam';
 import { ArnFormat, IResource, Lazy, Resource, Stack, Token } from 'aws-cdk-lib/core';
 import { Construct } from 'constructs';
 import { CfnPlaceIndex } from 'aws-cdk-lib/aws-location';
-import { generateUniqueId } from './util';
+import { DataSource, generateUniqueId } from './util';
 
 /**
  * A Place Index
@@ -59,25 +59,6 @@ export interface PlaceIndexProps {
   readonly description?: string;
 }
 
-/**
- * Data source for a place index
- */
-export enum DataSource {
-  /**
-   * Esri
-   *
-   * @see https://docs.aws.amazon.com/location/latest/developerguide/esri.html
-   */
-  ESRI = 'Esri',
-
-  /**
-   * HERE
-   *
-   * @see https://docs.aws.amazon.com/location/latest/developerguide/HERE.html
-   */
-  HERE = 'Here',
-}
-
 /**
  * Intend use for the results of an operation
  */

packages/@aws-cdk/aws-location-alpha/lib/route-calculator.ts

@@ -0,0 +1,158 @@
+import * as iam from 'aws-cdk-lib/aws-iam';
+import { ArnFormat, IResource, Lazy, Resource, Stack, Token } from 'aws-cdk-lib/core';
+import { Construct } from 'constructs';
+import { CfnRouteCalculator } from 'aws-cdk-lib/aws-location';
+import { generateUniqueId, DataSource } from './util';
+
+/**
+ * A Route Calculator
+ */
+export interface IRouteCalculator extends IResource {
+  /**
+   * The name of the route calculator
+   *
+   * @attribute
+   */
+  readonly routeCalculatorName: string;
+
+  /**
+   * The Amazon Resource Name (ARN) of the route calculator resource
+   *
+   * @attribute Arn,CalculatorArn
+   */
+  readonly routeCalculatorArn: string;
+}
+
+/**
+ * Properties for a route calculator
+ */
+export interface RouteCalculatorProps {
+  /**
+   * A name for the route calculator
+   *
+   * Must be between 1 and 100 characters and contain only alphanumeric characters,
+   * hyphens, periods and underscores.
+   *
+   * @default - A name is automatically generated
+   */
+  readonly routeCalculatorName?: string;
+
+  /**
+   * Data source for the route calculator
+   */
+  readonly dataSource: DataSource;
+
+  /**
+   * A description for the route calculator
+   *
+   * @default - no description
+   */
+  readonly description?: string;
+}
+
+/**
+ * A Route Calculator
+ *
+ * @see https://docs.aws.amazon.com/location/latest/developerguide/places-concepts.html
+ */
+export class RouteCalculator extends Resource implements IRouteCalculator {
+  /**
+   * Use an existing route calculator by name
+   */
+  public static fromRouteCalculatorName(scope: Construct, id: string, routeCalculatorName: string): IRouteCalculator {
+    const routeCalculatorArn = Stack.of(scope).formatArn({
+      service: 'geo',
+      resource: 'route-calculator',
+      resourceName: routeCalculatorName,
+    });
+
+    return RouteCalculator.fromRouteCalculatorArn(scope, id, routeCalculatorArn);
+  }
+
+  /**
+   * Use an existing route calculator by ARN
+   */
+  public static fromRouteCalculatorArn(scope: Construct, id: string, routeCalculatorArn: string): IRouteCalculator {
+    const parsedArn = Stack.of(scope).splitArn(routeCalculatorArn, ArnFormat.SLASH_RESOURCE_NAME);
+
+    if (!parsedArn.resourceName) {
+      throw new Error(`Route Calculator Arn ${routeCalculatorArn} does not have a resource name.`);
+    }
+
+    class Import extends Resource implements IRouteCalculator {
+      public readonly routeCalculatorName = parsedArn.resourceName!;
+      public readonly routeCalculatorArn = routeCalculatorArn;
+    }
+
+    return new Import(scope, id, {
+      account: parsedArn.account,
+      region: parsedArn.region,
+    });
+  }
+
+  public readonly routeCalculatorName: string;
+
+  public readonly routeCalculatorArn: string;
+
+  /**
+   * The timestamp for when the route calculator resource was created in ISO 8601 format
+   *
+   * @attribute
+   */
+  public readonly routeCalculatorCreateTime: string;
+
+  /**
+   * The timestamp for when the route calculator resource was last updated in ISO 8601 format
+   *
+   * @attribute
+   */
+  public readonly routeCalculatorUpdateTime: string;
+
+  constructor(scope: Construct, id: string, props: RouteCalculatorProps) {
+
+    if (props.description && !Token.isUnresolved(props.description) && props.description.length > 1000) {
+      throw new Error(`\`description\` must be between 0 and 1000 characters. Received: ${props.description.length} characters`);
+    }
+
+    if (props.routeCalculatorName && !Token.isUnresolved(props.routeCalculatorName) && !/^[-.\w]{1,100}$/.test(props.routeCalculatorName)) {
+      throw new Error(`Invalid route calculator name. The route calculator name must be between 1 and 100 characters and contain only alphanumeric characters, hyphens, periods and underscores. Received: ${props.routeCalculatorName}`);
+    }
+
+    super(scope, id, {
+      physicalName: props.routeCalculatorName ?? Lazy.string({ produce: () => generateUniqueId(this) }),
+    });
+
+    const routeCalculator = new CfnRouteCalculator(this, 'Resource', {
+      calculatorName: this.physicalName,
+      dataSource: props.dataSource ?? DataSource.ESRI,
+      description: props.description,
+    });
+
+    this.routeCalculatorName = routeCalculator.ref;
+    this.routeCalculatorArn = routeCalculator.attrArn;
+    this.routeCalculatorCreateTime = routeCalculator.attrCreateTime;
+    this.routeCalculatorUpdateTime = routeCalculator.attrUpdateTime;
+  }
+
+  /**
+   * Grant the given principal identity permissions to perform the actions on this route calculator.
+   */
+  public grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant {
+    return iam.Grant.addToPrincipal({
+      grantee: grantee,
+      actions: actions,
+      resourceArns: [this.routeCalculatorArn],
+    });
+  }
+
+  /**
+   * Grant the given identity permissions to access to a route calculator resource to calculate a route.
+   *
+   * @see https://docs.aws.amazon.com/location/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-calculate-route
+   */
+  public grantRead(grantee: iam.IGrantable): iam.Grant {
+    return this.grant(grantee,
+      'geo:CalculateRoute',
+    );
+  }
+}

packages/@aws-cdk/aws-location-alpha/lib/util.ts

@@ -8,3 +8,29 @@ export function generateUniqueId(context: IConstruct): string {
   }
   return name;
 }
+
+/**
+ * Data source for a place index
+ */
+export enum DataSource {
+  /**
+   * Esri
+   *
+   * @see https://docs.aws.amazon.com/location/latest/developerguide/esri.html
+   */
+  ESRI = 'Esri',
+
+  /**
+   * Grab provides routing functionality for Southeast Asia.
+   *
+   * @see https://docs.aws.amazon.com/location/latest/developerguide/grab.html
+   */
+  GRAB = 'Grab',
+
+  /**
+   * HERE
+   *
+   * @see https://docs.aws.amazon.com/location/latest/developerguide/HERE.html
+   */
+  HERE = 'Here',
+}

packages/@aws-cdk/aws-location-alpha/test/integ.route-calculator.js.snapshot/cdk-integ-location-route-calculator.template.json

@@ -0,0 +1,45 @@
+{
+ "Resources": {
+  "RouteCalculator0F2D109D": {
+   "Type": "AWS::Location::RouteCalculator",
+   "Properties": {
+    "CalculatorName": "cdkinteglocationroutecalculatorRouteCalculator916939B5",
+    "DataSource": "Esri"
+   }
+  }
+ },
+ "Parameters": {
+  "BootstrapVersion": {
+   "Type": "AWS::SSM::Parameter::Value<String>",
+   "Default": "/cdk-bootstrap/hnb659fds/version",
+   "Description": "Version of the CDK Bootstrap resources in this environment, automatically retrieved from SSM Parameter Store. [cdk:skip]"
+  }
+ },
+ "Rules": {
+  "CheckBootstrapVersion": {
+   "Assertions": [
+    {
+     "Assert": {
+      "Fn::Not": [
+       {
+        "Fn::Contains": [
+         [
+          "1",
+          "2",
+          "3",
+          "4",
+          "5"
+         ],
+         {
+          "Ref": "BootstrapVersion"
+         }
+        ]
+       }
+      ]
+     },
+     "AssertDescription": "CDK bootstrap stack version 6 required. Please run 'cdk bootstrap' with a recent version of the CDK CLI."
+    }
+   ]
+  }
+ }
+}