@aws/nx-plugin 0.20.0 → 0.22.0

package/src/utils/api-constructs/files/app/apis/http/__apiNameKebabCase__.ts.template

@@ -0,0 +1,135 @@
+import { Construct } from 'constructs';
+import * as url from 'url';
+import {
+  Code,
+  Runtime,
+  Function,
+  FunctionProps,
+  Tracing,
+} from 'aws-cdk-lib/aws-lambda';
+import { Duration } from 'aws-cdk-lib';
+import { CorsHttpMethod } from 'aws-cdk-lib/aws-apigatewayv2';
+import { HttpIamAuthorizer } from 'aws-cdk-lib/aws-apigatewayv2-authorizers';
+import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';
+import {
+  HttpApiIntegration,
+  IntegrationBuilder,
+} from '../../core/api/utils.js';
+import { HttpApi } from '../../core/api/http-api.js';
+<%_ if (backend.type === 'trpc') { _%>
+import { Procedures, routerToOperations } from '../../core/api/trpc-utils.js';
+import { AppRouter, appRouter } from '<%= backend.projectAlias %>';
+
+// String union type for all API operation names
+type Operations = Procedures<AppRouter>;
+<%_ } else if (backend.type === 'fastapi') { _%>
+import {
+  OPERATION_DETAILS,
+  Operations,
+} from '../../generated/<%- apiNameKebabCase %>/metadata.gen.js';
+<%_ } _%>
+
+/**
+ * Properties for creating a <%= apiNameClassName %> construct
+ *
+ * @template TIntegrations - Map of operation names to their integrations
+ */
+export interface <%= apiNameClassName %>Props<
+  TIntegrations extends Record<Operations, HttpApiIntegration>,
+> {
+  /**
+   * Map of operation names to their API Gateway integrations
+   */
+  integrations: TIntegrations;
+}
+
+/**
+ * A CDK construct that creates and configures an AWS API Gateway HTTP API
+ * specifically for <%= apiNameClassName %>.
+ * @template TIntegrations - Map of operation names to their integrations
+ */
+export class <%= apiNameClassName %><
+  TIntegrations extends Record<Operations, HttpApiIntegration>,
+> extends HttpApi<Operations, TIntegrations> {
+  /**
+   * Creates default integrations for all operations, which implement each operation as
+   * its own individual lambda function.
+   *
+   * @param scope - The CDK construct scope
+   * @returns An IntegrationBuilder with default lambda integrations
+   */
+  public static defaultIntegrations = (scope: Construct) => {
+    return IntegrationBuilder.http({
+      <%_ if (backend.type === 'trpc') { _%>
+      operations: routerToOperations(appRouter),
+      <%_ } else if (backend.type === 'fastapi') { _%>
+      operations: OPERATION_DETAILS,
+      <%_ } _%>
+      defaultIntegrationOptions: {
+        <%_ if (backend.type === 'trpc') { _%>
+        runtime: Runtime.NODEJS_LATEST,
+        handler: 'index.handler',
+        code: Code.fromAsset(
+          url.fileURLToPath(
+            new URL(
+              '../../../../../../dist/<%- backend.dir %>/bundle',
+              import.meta.url,
+            ),
+          ),
+        ),
+        <%_ } else if (backend.type === 'fastapi') { _%>
+        runtime: Runtime.PYTHON_3_12,
+        handler: '<%= backend.apiNameSnakeCase %>.main.handler',
+        code: Code.fromAsset(
+          url.fileURLToPath(
+            new URL(
+              '../../../../../../dist/<%- backend.dir %>/bundle',
+              import.meta.url,
+            ),
+          ),
+        ),
+        <%_ } _%>
+        timeout: Duration.seconds(30),
+        tracing: Tracing.ACTIVE,
+        environment: {
+          AWS_CONNECTION_REUSE_ENABLED: '1',
+        },
+      } satisfies FunctionProps,
+      buildDefaultIntegration: (op, props: FunctionProps) => {
+        const handler = new Function(scope, `<%= apiNameClassName %>${op}Handler`, props);
+        return {
+          handler,
+          integration: new HttpLambdaIntegration(`<%= apiNameClassName %>${op}Integration`, handler),
+        };
+      },
+    });
+  };
+
+  constructor(
+    scope: Construct,
+    id: string,
+    props: <%= apiNameClassName %>Props<TIntegrations>,
+  ) {
+    super(scope, id, {
+      apiName: '<%= apiNameClassName %>',
+      corsPreflight: {
+        allowOrigins: ['*'],
+        allowMethods: [CorsHttpMethod.ANY],
+        allowHeaders: [
+          'authorization',
+          'content-type',
+          'x-amz-content-sha256',
+          'x-amz-date',
+          'x-amz-security-token',
+        ],
+      },
+      defaultAuthorizer: new HttpIamAuthorizer(),
+      <%_ if (backend.type === 'trpc') { _%>
+      operations: routerToOperations(appRouter),
+      <%_ } else if (backend.type === 'fastapi') { _%>
+      operations: OPERATION_DETAILS,
+      <%_ } _%>
+      ...props,
+    });
+  }
+}

package/src/utils/api-constructs/files/app/apis/rest/__apiNameKebabCase__.ts.template

@@ -0,0 +1,156 @@
+import { Construct } from 'constructs';
+import * as url from 'url';
+import {
+  Code,
+  Runtime,
+  Function,
+  FunctionProps,
+  Tracing,
+} from 'aws-cdk-lib/aws-lambda';
+import {
+  AuthorizationType,
+  Cors,
+  LambdaIntegration,
+} from 'aws-cdk-lib/aws-apigateway';
+import { Duration, Stack } from 'aws-cdk-lib';
+import {
+  PolicyDocument,
+  PolicyStatement,
+  Effect,
+  AccountPrincipal,
+  AnyPrincipal,
+} from 'aws-cdk-lib/aws-iam';
+import {
+  IntegrationBuilder,
+  RestApiIntegration,
+} from '../../core/api/utils.js';
+import { RestApi } from '../../core/api/rest-api.js';
+<%_ if (backend.type === 'trpc') { _%>
+import { Procedures, routerToOperations } from '../../core/api/trpc-utils.js';
+import { AppRouter, appRouter } from '<%= backend.projectAlias %>';
+
+// String union type for all API operation names
+type Operations = Procedures<AppRouter>;
+<%_ } else if (backend.type === 'fastapi') { _%>
+import {
+  OPERATION_DETAILS,
+  Operations,
+} from '../../generated/<%- apiNameKebabCase %>/metadata.gen.js';
+<%_ } _%>
+
+/**
+ * Properties for creating a <%= apiNameClassName %> construct
+ *
+ * @template TIntegrations - Map of operation names to their integrations
+ */
+export interface <%= apiNameClassName %>Props<
+  TIntegrations extends Record<Operations, RestApiIntegration>,
+> {
+  /**
+   * Map of operation names to their API Gateway integrations
+   */
+  integrations: TIntegrations;
+}
+
+/**
+ * A CDK construct that creates and configures an AWS API Gateway REST API
+ * specifically for <%= apiNameClassName %>.
+ * @template TIntegrations - Map of operation names to their integrations
+ */
+export class <%= apiNameClassName %><
+  TIntegrations extends Record<Operations, RestApiIntegration>,
+> extends RestApi<Operations, TIntegrations> {
+  /**
+   * Creates default integrations for all operations, which implement each operation as
+   * its own individual lambda function.
+   *
+   * @param scope - The CDK construct scope
+   * @returns An IntegrationBuilder with default lambda integrations
+   */
+  public static defaultIntegrations = (scope: Construct) => {
+    return IntegrationBuilder.rest({
+      <%_ if (backend.type === 'trpc') { _%>
+      operations: routerToOperations(appRouter),
+      <%_ } else if (backend.type === 'fastapi') { _%>
+      operations: OPERATION_DETAILS,
+      <%_ } _%>
+      defaultIntegrationOptions: {
+        <%_ if (backend.type === 'trpc') { _%>
+        runtime: Runtime.NODEJS_LATEST,
+        handler: 'index.handler',
+        code: Code.fromAsset(
+          url.fileURLToPath(
+            new URL(
+              '../../../../../../dist/<%- backend.dir %>/bundle',
+              import.meta.url,
+            ),
+          ),
+        ),
+        <%_ } else if (backend.type === 'fastapi') { _%>
+        runtime: Runtime.PYTHON_3_12,
+        handler: '<%= backend.apiNameSnakeCase %>.main.handler',
+        code: Code.fromAsset(
+          url.fileURLToPath(
+            new URL(
+              '../../../../../../dist/<%- backend.dir %>/bundle',
+              import.meta.url,
+            ),
+          ),
+        ),
+        <%_ } _%>
+        timeout: Duration.seconds(30),
+        tracing: Tracing.ACTIVE,
+        environment: {
+          AWS_CONNECTION_REUSE_ENABLED: '1',
+        },
+      } satisfies FunctionProps,
+      buildDefaultIntegration: (op, props: FunctionProps) => {
+        const handler = new Function(scope, `<%= apiNameClassName %>${op}Handler`, props);
+        return { handler, integration: new LambdaIntegration(handler) };
+      },
+    });
+  };
+
+  constructor(
+    scope: Construct,
+    id: string,
+    props: <%= apiNameClassName %>Props<TIntegrations>,
+  ) {
+    super(scope, id, {
+      apiName: '<%= apiNameClassName %>',
+      defaultMethodOptions: {
+        authorizationType: AuthorizationType.IAM,
+      },
+      defaultCorsPreflightOptions: {
+        allowOrigins: Cors.ALL_ORIGINS,
+        allowMethods: Cors.ALL_METHODS,
+      },
+      policy: new PolicyDocument({
+        statements: [
+          // Here we grant any AWS credentials from the account that the project is deployed in to call the api.
+          // Machine to machine fine-grained access can be defined here using more specific principals (eg roles or
+          // users) and resources (eg which api paths may be invoked by which principal) if required.
+          new PolicyStatement({
+            effect: Effect.ALLOW,
+            principals: [new AccountPrincipal(Stack.of(scope).account)],
+            actions: ['execute-api:Invoke'],
+            resources: ['execute-api:/*'],
+          }),
+          // Open up OPTIONS to allow browsers to make unauthenticated preflight requests
+          new PolicyStatement({
+            effect: Effect.ALLOW,
+            principals: [new AnyPrincipal()],
+            actions: ['execute-api:Invoke'],
+            resources: ['execute-api:/*/OPTIONS/*'],
+          }),
+        ],
+      }),
+      <%_ if (backend.type === 'trpc') { _%>
+      operations: routerToOperations(appRouter),
+      <%_ } else if (backend.type === 'fastapi') { _%>
+      operations: OPERATION_DETAILS,
+      <%_ } _%>
+      ...props,
+    });
+  }
+}

package/src/utils/api-constructs/files/core/api/http/http-api.ts.template

@@ -0,0 +1,112 @@
+import { Construct } from 'constructs';
+import { RuntimeConfig } from '../runtime-config.js';
+import { Grant, IGrantable } from 'aws-cdk-lib/aws-iam';
+import { HttpApiIntegration, OperationDetails } from './utils.js';
+import { CfnOutput } from 'aws-cdk-lib';
+import {
+  HttpApi as _HttpApi,
+  HttpApiProps as _HttpApiProps,
+  HttpMethod,
+} from 'aws-cdk-lib/aws-apigatewayv2';
+
+/**
+ * Properties for creating an HttpApi construct.
+ *
+ * @template TIntegrations - Record mapping operation names to their integrations
+ * @template TOperation - String literal type representing operation names
+ */
+export interface HttpApiProps<
+  TIntegrations extends Record<TOperation, HttpApiIntegration>,
+  TOperation extends string,
+> extends _HttpApiProps {
+  /**
+   * Unique name for the API, used in runtime configuration
+   */
+  readonly apiName: string;
+  /**
+   * Map of operation names to their API path and HTTP method details
+   */
+  readonly operations: Record<TOperation, OperationDetails>;
+  /**
+   * Map of operation names to their API Gateway integrations
+   */
+  readonly integrations: TIntegrations;
+}
+
+/**
+ * A CDK construct that creates and configures an AWS API Gateway HTTP API.
+ *
+ * This class extends the base CDK HttpApi with additional functionality:
+ * - Type-safe operation and integration management
+ * - Automatic resource creation based on path patterns
+ * - Integration with runtime configuration for client discovery
+ *
+ * @template TOperation - String literal type representing operation names
+ * @template TIntegrations - Record mapping operation names to their integrations
+ */
+export class HttpApi<
+  TOperation extends string,
+  TIntegrations extends Record<TOperation, HttpApiIntegration>,
+> extends Construct {
+  /** The underlying CDK HttpApi instance */
+  public readonly api: _HttpApi;
+
+  /** Map of operation names to their API Gateway integrations */
+  public readonly integrations: TIntegrations;
+
+  constructor(
+    scope: Construct,
+    id: string,
+    {
+      apiName,
+      operations,
+      integrations,
+      ...props
+    }: HttpApiProps<TIntegrations, TOperation>,
+  ) {
+    super(scope, id);
+    this.integrations = integrations;
+
+    // Create the API Gateway REST API with logging enabled
+    this.api = new _HttpApi(this, 'Api', {
+      ...props,
+    });
+
+    // Create API resources and methods for each operation
+    (Object.entries(operations) as [TOperation, OperationDetails][]).map(
+      ([op, details]) => {
+        this.api.addRoutes({
+          path: details.path.startsWith('/')
+            ? details.path
+            : `/${details.path}`,
+          methods: [details.method as HttpMethod],
+          integration: integrations[op].integration,
+          ...integrations[op].options,
+        });
+      },
+    );
+
+    new CfnOutput(this, `${apiName}Url`, {
+      value: this.api.url!,
+    });
+
+    // Register the API URL in runtime configuration for client discovery
+    RuntimeConfig.ensure(this).config.apis = {
+      ...RuntimeConfig.ensure(this).config.apis!,
+      [apiName]: this.api.url!,
+    };
+  }
+
+  /**
+   * Grants IAM permissions to invoke any method on this API.
+   *
+   * @param grantee - The IAM principal to grant permissions to
+   */
+  public grantInvokeAccess(grantee: IGrantable) {
+    Grant.addToPrincipal({
+      grantee,
+      actions: ['execute-api:Invoke'],
+      resourceArns: [this.api.arnForExecuteApi('*', '/*', '*')],
+    });
+  }
+}

package/src/utils/api-constructs/files/core/api/rest/rest-api.ts.template

@@ -0,0 +1,137 @@
+import { Construct } from 'constructs';
+import {
+  RestApi as _RestApi,
+  RestApiProps as _RestApiProps,
+  AccessLogFormat,
+  IResource,
+  LogGroupLogDestination,
+  MethodLoggingLevel,
+} from 'aws-cdk-lib/aws-apigateway';
+import { LogGroup } from 'aws-cdk-lib/aws-logs';
+import { RuntimeConfig } from '../runtime-config.js';
+import { Grant, IGrantable } from 'aws-cdk-lib/aws-iam';
+import { OperationDetails, RestApiIntegration } from './utils.js';
+
+/**
+ * Properties for creating a RestApi construct.
+ *
+ * @template TIntegrations - Record mapping operation names to their integrations
+ * @template TOperation - String literal type representing operation names
+ */
+export interface RestApiProps<
+  TIntegrations extends Record<TOperation, RestApiIntegration>,
+  TOperation extends string,
+> extends _RestApiProps {
+  /**
+   * Unique name for the API, used in runtime configuration
+   */
+  readonly apiName: string;
+  /**
+   * Map of operation names to their API path and HTTP method details
+   */
+  readonly operations: Record<TOperation, OperationDetails>;
+  /**
+   * Map of operation names to their API Gateway integrations
+   */
+  readonly integrations: TIntegrations;
+}
+
+/**
+ * A CDK construct that creates and configures an AWS API Gateway REST API.
+ *
+ * This class extends the base CDK RestApi with additional functionality:
+ * - Type-safe operation and integration management
+ * - Automatic resource creation based on path patterns
+ * - Integration with runtime configuration for client discovery
+ *
+ * @template TOperation - String literal type representing operation names
+ * @template TIntegrations - Record mapping operation names to their integrations
+ */
+export class RestApi<
+  TOperation extends string,
+  TIntegrations extends Record<TOperation, RestApiIntegration>,
+> extends Construct {
+  /** The underlying CDK RestApi instance */
+  public readonly api: _RestApi;
+
+  /** Map of operation names to their API Gateway integrations */
+  public readonly integrations: TIntegrations;
+
+  constructor(
+    scope: Construct,
+    id: string,
+    {
+      apiName,
+      operations,
+      integrations,
+      ...props
+    }: RestApiProps<TIntegrations, TOperation>,
+  ) {
+    super(scope, id);
+    this.integrations = integrations;
+
+    // Create the API Gateway REST API with logging enabled
+    this.api = new _RestApi(this, 'Api', {
+      deployOptions: {
+        accessLogDestination: new LogGroupLogDestination(
+          new LogGroup(this, 'AccessLogs'),
+        ),
+        accessLogFormat: AccessLogFormat.clf(),
+        loggingLevel: MethodLoggingLevel.INFO,
+      },
+      ...props,
+    });
+
+    // Create API resources and methods for each operation
+    (Object.entries(operations) as [TOperation, OperationDetails][]).map(
+      ([op, details]) => {
+        const resource = this.getOrCreateResource(
+          this.api.root,
+          (details.path.startsWith('/')
+            ? details.path.slice(1)
+            : details.path
+          ).split('/'),
+        );
+        resource.addMethod(details.method, integrations[op].integration, integrations[op].options);
+      },
+    );
+
+    // Register the API URL in runtime configuration for client discovery
+    RuntimeConfig.ensure(this).config.apis = {
+      ...RuntimeConfig.ensure(this).config.apis!,
+      [apiName]: this.api.url!,
+    };
+  }
+
+  /**
+   * Recursively creates or retrieves API Gateway resources based on a path pattern.
+   *
+   * @param resource - The parent API Gateway resource
+   * @param pathParts - Array of path segments to create or retrieve
+   * @returns The API Gateway resource at the end of the path
+   */
+  private getOrCreateResource(
+    resource: IResource,
+    [nextPathPart, ...pathParts]: string[],
+  ): IResource {
+    if (!nextPathPart) {
+      return resource;
+    }
+    const childResource =
+      resource.getResource(nextPathPart) ?? resource.addResource(nextPathPart);
+    return this.getOrCreateResource(childResource, pathParts);
+  }
+
+  /**
+   * Grants IAM permissions to invoke any method on this API.
+   *
+   * @param grantee - The IAM principal to grant permissions to
+   */
+  public grantInvokeAccess(grantee: IGrantable) {
+    Grant.addToPrincipal({
+      grantee,
+      actions: ['execute-api:Invoke'],
+      resourceArns: [this.api.arnForExecuteApi('*', '/*', '*')],
+    });
+  }
+}

package/src/utils/api-constructs/files/core/api/trpc/trpc-utils.ts.template

@@ -0,0 +1,67 @@
+import { TRPCRouterRecord, AnyTRPCRouter } from '@trpc/server';
+import { OperationDetails } from './utils.js';
+import { HttpMethod } from 'aws-cdk-lib/aws-apigatewayv2';
+
+/**
+ * Helper type that recursively extracts procedure names from a tRPC router.
+ * This type traverses the router structure and builds fully qualified procedure names
+ * with dot notation for nested routers.
+ *
+ * @template T - The tRPC router record type
+ * @template Prefix - The current path prefix for nested procedures
+ */
+type _Procedures<T extends TRPCRouterRecord, Prefix extends string = ''> = {
+  [K in keyof T]: K extends string
+    ? T[K] extends TRPCRouterRecord
+      ? _Procedures<T[K], `${Prefix}${K}.`>
+      : `${Prefix}${K}`
+    : never;
+}[keyof T];
+
+/**
+ * Extracts all procedure names from a tRPC router as a union of string literals.
+ * This type is used to provide type-safe access to procedure names throughout the API.
+ *
+ * @template TRouter - The tRPC router type
+ */
+export type Procedures<TRouter extends AnyTRPCRouter> = _Procedures<
+  TRouter['_def']['record']
+>;
+
+/**
+ * Converts a tRPC router to a map of API operations.
+ * This method recursively traverses the router structure and creates operation details
+ * for each procedure, mapping queries to GET methods and mutations to POST methods.
+ *
+ * @param router - The tRPC router to convert
+ * @param prefix - The current path prefix for nested procedures
+ * @returns A map of procedure names to their API operation details
+ */
+export const routerToOperations = <TRouter extends AnyTRPCRouter>(
+  router: TRouter,
+  prefix = '',
+): Record<Procedures<TRouter>, OperationDetails> => {
+  return Object.fromEntries(
+    Object.entries(router._def.procedures).flatMap(
+      ([op, procedureOrRouter]: [string, any]) => {
+        const fullPath = prefix ? `${prefix}.${op}` : op;
+        return procedureOrRouter._def?.router
+          ? Object.entries(
+              routerToOperations<TRouter>(procedureOrRouter, fullPath),
+            )
+          : [
+              [
+                fullPath,
+                {
+                  path: fullPath,
+                  method:
+                    procedureOrRouter._def.type === 'query'
+                      ? HttpMethod.GET
+                      : HttpMethod.POST,
+                },
+              ],
+            ];
+      },
+    ),
+  ) as Record<Procedures<TRouter>, OperationDetails>;
+};