export-backend.ts

import {
  CfnInclude,
  IncludedNestedStack,
} from 'aws-cdk-lib/cloudformation-include';
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { AmplifyExportedBackendProps } from './amplify-exported-backend-props';
import { BaseAmplifyExportedBackend } from './base-exported-backend';
import { Constants } from './constants';
import { AmplifyExportAssetHandler } from './export-backend-asset-handler';
import {
  APIGraphQLIncludedNestedStack,
  APIRestIncludedStack,
  AuthIncludedNestedStack,
} from './include-nested-stacks';
import {
  LambdaFunctionIncludedNestedStack,
} from './include-nested-stacks/lambda-function/lambda-function-nested-stack';
import { CategoryStackMapping } from './types/category-stack-mapping';
import { AwsCustomResource, AwsCustomResourcePolicy, PhysicalResourceId } from "aws-cdk-lib/custom-resources";
import { CfnParameter } from 'aws-cdk-lib';
import { CfnRole } from 'aws-cdk-lib/aws-iam';
import { CfnBucket } from 'aws-cdk-lib/aws-s3';

const { API_CATEGORY, AUTH_CATEGORY, FUNCTION_CATEGORY } = Constants;

/***
 * Used to include the backend generated by running `amplify export --out <path>` into the cdk app
 * @example
 * @see <amplify-export-docs-path>
 */
export class AmplifyExportedBackend
  extends BaseAmplifyExportedBackend {
  /**
   * cfnInclude of the Amplify backend
   */
  cfnInclude: CfnInclude;
  /**
   * The root stack created
   */
  rootStack: cdk.Stack;

  /**
   * @param scope The parent construct of this template
   * @param id The ID of this construct
   * @param props Initialization properties.
   */
  constructor(
    scope: Construct,
    id: string,
    props: AmplifyExportedBackendProps,
  ) {
    super(scope, id, props.path, props.amplifyEnvironment, props.amplifyAppId);

    this.rootStack = new cdk.Stack(scope, `${id}-amplify-backend-stack`, {
      ...props,
      stackName: this.exportBackendManifest.stackName,
    });

    const amplifyExportHandler = new AmplifyExportAssetHandler(
      this.rootStack,
      'asset',
      {
        backendPath: props.path,
        categoryStackMapping: this.categoryStackMappings,
        env: this.env,
        exportManifest: this.exportBackendManifest,
      },
    );
    this.exportBackendManifest =
      amplifyExportHandler.createAssetsAndUpdateParameters();

    const include = new CfnInclude(
      this.rootStack,
      'AmplifyCfnInclude',
      this.transformTemplateFile(this.exportBackendManifest.props, this.exportPath),
    );

    this.cfnInclude = include;

    amplifyExportHandler.setDependencies(include);

    // used to emulate the input parameters that the Amplify CLI uses
    const deploymentBucket = this.cfnInclude.getResource('DeploymentBucket') as CfnBucket;
    const authRole = this.cfnInclude.getResource('AuthRole') as CfnRole;
    const unauthRole = this.cfnInclude.getResource('UnauthRole') as CfnRole;
    new CfnParameter(this.rootStack, 'AuthRoleName', {
      type: 'String',
      default: authRole.roleName
    });
    new CfnParameter(this.rootStack, 'DeploymentBucketName', {
      type: 'String',
      default: deploymentBucket.bucketName
    });
    new CfnParameter(this.rootStack, 'UnauthRoleName', {
      type: 'String',
      default: unauthRole.roleName
    });

    // just like in amplify env add, we add the backend to the amplify application
    // and then deploy the CFN. This also ensures the amplify env only deletes when
    // the CFN is gone too.
    if(this.appId) {
      new AwsCustomResource(this.rootStack, 'CreateBackendEnvironment', {
        onCreate: {
          service: 'Amplify',
          action: 'createBackendEnvironment',
          parameters: {
            appId: this.appId,
            environmentName: this.env,
            stackName: this.rootStack.stackName,
            deploymentArtifacts: deploymentBucket.bucketName,
          },
          physicalResourceId: PhysicalResourceId.of(`${this.appId}-${this.env}-backendEnvironment`)
        },
        onDelete: {
          service: 'Amplify',
          action: 'deleteBackendEnvironment',
          parameters: {
            appId: this.appId,
            environmentName: this.env
          }
        },
        policy: AwsCustomResourcePolicy.fromSdkCalls({
          resources: AwsCustomResourcePolicy.ANY_RESOURCE,
        }),
      });
    }

    this.applyTags(this.rootStack, this.env);
  }

  private applyTags(rootStack: cdk.Stack, env: string) {
    this.exportTags.forEach((tag) => {
      rootStack.tags.setTag(tag.key, tag.value.replace('{project-env}', env));
    });
  }

  /**
   * Method to get the auth stack
   * @returns the nested stack of type {@link AuthIncludedNestedStack}
   * @throws {AmplifyCategoryNotFoundError} if the auth stack doesn't exist
   * @method
   * @function
   */
  authNestedStack(): AuthIncludedNestedStack {
    const cognitoResource = this.findResourceForNestedStack(
      AUTH_CATEGORY.NAME,
      AUTH_CATEGORY.SERVICE.COGNITO,
    );
    const stack = this.getCategoryNestedStack(cognitoResource);
    return new AuthIncludedNestedStack(stack);
  }

  /**
   * Use this to get the api graphql stack from the backend
   * @returns the nested stack of type {@link APIGraphQLIncludedNestedStack}
   * @throws {AmplifyCategoryNotFoundError} if the API graphql stack doesn't exist
   */
  graphqlNestedStacks(): APIGraphQLIncludedNestedStack {
    const categoryStackMapping = this.findResourceForNestedStack(
      API_CATEGORY.NAME,
      API_CATEGORY.SERVICE.APP_SYNC,
    );
    return new APIGraphQLIncludedNestedStack(
      this.getCategoryNestedStack(categoryStackMapping),
    );
  }

  /**
   * Use this to get all the lambda functions from the backend
   * @returns {LambdaFunctionIncludedNestedStack[]}
   * @throws {AmplifyCategoryNotFoundError} if the no Lambda Function stacks are found
   */
  lambdaFunctionNestedStacks(): LambdaFunctionIncludedNestedStack[] {
    return this.filterCategory(
      FUNCTION_CATEGORY.NAME,
      FUNCTION_CATEGORY.SERVICE.LAMBDA_FUNCTION,
    )
      .map((category) => this.getCategoryNestedStack(category))
      .map((stack) => new LambdaFunctionIncludedNestedStack(stack));
  }

  /**
   * Use this to get a specific lambda function from the backend
   * @returns {LambdaFunctionIncludedNestedStack}
   * @param functionName the function name to get from the nested stack
   * @throws {AmplifyCategoryNotFoundError} if the lambda function stack doesn't exist
   */
  lambdaFunctionNestedStackByName(
    functionName: string,
  ): LambdaFunctionIncludedNestedStack {
    const category = this.findResourceForNestedStack(
      FUNCTION_CATEGORY.NAME,
      FUNCTION_CATEGORY.SERVICE.LAMBDA_FUNCTION,
      functionName,
    );
    return new LambdaFunctionIncludedNestedStack(
      this.getCategoryNestedStack(category),
    );
  }

  nestedStackByCategortService(category: string, service: string) : IncludedNestedStack[] {
    return this.filterCategory(category, service).map(categoryMapping => this.getCategoryNestedStack(categoryMapping));
  }

  /**
   * Returns the stacks defined in the backend
   * @param category Categories defined in Amplify CLI like function, api, auth etc
   * @param resourceName @default is undefined
   */
  nestedStacksByCategory(
    category: string,
    resourceName?: string,
  ): IncludedNestedStack[] {
    return this.filterCategory(category, undefined, resourceName).map(
      this.getCategoryNestedStack,
    );
  }

  /**
   * Use this to get rest api stack from the backend
   * @param resourceName
   * @return {APIRestIncludedStack} the nested of type Rest API
   * @throws {AmplifyCategoryNotFoundError} if the API Rest stack doesn't exist
   */
  apiRestNestedStack(resourceName: string): APIRestIncludedStack {
    const categoryStackMapping = this.findResourceForNestedStack(
      API_CATEGORY.NAME,
      API_CATEGORY.SERVICE.API_GATEWAY,
      resourceName,
    );
    const stack = this.getCategoryNestedStack(categoryStackMapping);
    return new APIRestIncludedStack(stack, resourceName);
  }

  private getCategoryNestedStack(
    categoryStackMapping: CategoryStackMapping,
  ): IncludedNestedStack {
    return this.cfnInclude.getNestedStack(
      categoryStackMapping.category + categoryStackMapping.resourceName,
    );
  }
}