@liflig/cdk 3.0.21 → 3.1.0

package/lib/api-gateway/http-api-gateway.d.ts

@@ -0,0 +1,500 @@
+import * as constructs from "constructs";
+import * as cdk from "aws-cdk-lib";
+import type * as elb from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import type * as ec2 from "aws-cdk-lib/aws-ec2";
+import * as lambda from "aws-cdk-lib/aws-lambda";
+import type * as sqs from "aws-cdk-lib/aws-sqs";
+import * as apigw from "aws-cdk-lib/aws-apigatewayv2";
+import * as logs from "aws-cdk-lib/aws-logs";
+import * as iam from "aws-cdk-lib/aws-iam";
+import type { IUserPool } from "aws-cdk-lib/aws-cognito";
+import * as route53 from "aws-cdk-lib/aws-route53";
+/**
+ * Props for the {@link ApiGateway} construct.
+ *
+ * @author Kristian Rekstad <kre@capraconsulting.no>
+ * @author Hermann Mørkrid <hem@liflig.no>
+ */
+export type ApiGatewayProps<AuthScopesT extends string = string> = {
+    /** Settings for the external-facing part of the API-GW. */
+    dns: ApiGatewayDnsProps;
+    /**
+     * If no integration is specified for a route, this integration is used.
+     *
+     * See {@link IntegrationProps} for the available options.
+     */
+    defaultIntegration?: IntegrationProps;
+    /**
+     * If no authorization is specified for a route, this authorization is used.
+     *
+     * See {@link AuthorizationProps} for the available options.
+     */
+    defaultAuthorization?: AuthorizationProps<AuthScopesT>;
+    routes: ApiGatewayRoute<AuthScopesT>[];
+    /**
+     * The API-GW access logs for the `$default` stage are kept.
+     * This has options for the logs.
+     */
+    accessLogs?: ApiGatewayAccessLogsProps;
+    /**
+     * Set to false to disable route-level metrics.
+     * This can increase CloudWatch costs when not disabled.
+     *
+     * See [AWS: Working with metrics for HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-metrics.html?icmpid=apigateway_console_help#:~:text=and%20stage%20ID.-,ApiId%2C%20Stage%2C%20Route,-Filters%20API%20Gateway)
+     * for more info.
+     *
+     * @default true
+     */
+    detailedMetrics?: boolean;
+    /**
+     * Throttling of requests.
+     * If not set, the AWS default of 5000 burst and 10000 rate is used.
+     *
+     * The default throttling is per-account, and counts all APIs in the account and region.
+     * If you have another API in this region getting 10_000 request rate, it may impact this API as well.
+     */
+    throttling?: {
+        /**
+         * Going over `5_000` may require you to contact AWS Support - they are account bound.
+         */
+        burst?: number;
+        /**
+         * Going over `10_000` may require you to contact AWS Support - they are account bound.
+         */
+        rate?: number;
+    };
+    /**
+     * Sets CORS headers on responses from the API Gateway to allow all origins, headers and methods.
+     * Useful if your API should be accessed by any browser.
+     */
+    corsAllowAll?: boolean;
+    /**
+     * If some settings in this construct do not work for you, this is an escape hatch mechanism to
+     * override anything.
+     */
+    propsOverride?: {
+        /**
+         * Override settings for the {@link apigw.HttpApi} (accessible in {@link ApiGateway.httpApi}).
+         *
+         * For example, if you have a frontend accessing this API, you might want to set
+         * [CORS preflight](https://docs.aws.amazon.com/cdk/api/v1/docs/aws-apigatewayv2-readme.html#cross-origin-resource-sharing-cors)
+         * settings.
+         */
+        httpApi?: Partial<apigw.HttpApiProps>;
+    };
+};
+export type ApiGatewayDnsProps = {
+    /**
+     * Only the subdomain prefix, which should be the name of the service.
+     * Example: Subdomain `product` would give the end result of an API-GW with
+     * `product.platform.example.no`.
+     */
+    subdomain: string;
+    /**
+     * Hosted Zone for the external facing domain.
+     * This is where routes will be created, to redirect consumers to the API-GW.
+     * For example a HZ for `platform.example.no`.
+     */
+    hostedZone: route53.IHostedZone;
+    /**
+     * The Time To Live (TTL) for the public DNS A record that will expose the API-GW.
+     * This is how long DNS servers will cache the record.
+     *
+     * A long TTL (hours) is beneficial to DNS servers, but makes developers (you) wait longer when
+     * doing changes.
+     *
+     * @default 5 minutes
+     */
+    ttl?: cdk.Duration;
+};
+export type ApiGatewayRoute<AuthScopesT extends string = string> = {
+    /** The path of the route to expose through the API Gateway. Use "/" for the root route. */
+    path: string;
+    /**
+     * By default, we only forward requests that match the route's path exactly. So for a route with
+     * path `/api/users`, a request to `/api/users` will be forwarded, but a request to
+     * `/api/users/admin` will not. If you want to forward requests to all sub-paths under the route's
+     * path, you can set this to true.
+     *
+     * @default false
+     */
+    includeSubpaths?: boolean;
+    /**
+     * The HTTP method to expose. `ANY` exposes all HTTP methods on the path.
+     *
+     * @default "ANY"
+     */
+    method?: HttpMethod;
+    /**
+     * The integration that the route will forward to. See {@link IntegrationProps} for the available
+     * options.
+     *
+     * If undefined, uses the {@link ApiGatewayProps.defaultIntegration}.
+     */
+    integration?: IntegrationProps;
+    /**
+     * How requests on the route are authenticated. See {@link AuthorizationProps} for the available
+     * options.
+     *
+     * If undefined, uses the {@link ApiGatewayProps.defaultAuthorization}.
+     */
+    authorization?: AuthorizationProps<AuthScopesT>;
+};
+export type HttpMethod = "ANY" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD";
+export type IntegrationProps = 
+/** Use this when connecting the route to an ALB (Application Load Balancer). */
+({
+    type: "ALB";
+} & AlbIntegrationProps)
+/** Use this when connecting route to a Lambda. */
+ | ({
+    type: "Lambda";
+} & LambdaIntegrationProps)
+/** Use this when connecting a route to send to an SQS queue. */
+ | ({
+    type: "SQS";
+} & SqsIntegrationProps);
+/**
+ * Props for the API-GW -> ALB (Application Load Balancer) integration.
+ *
+ * See the note on {@link ApiGateway} about the load balancer security group.
+ */
+export type AlbIntegrationProps = {
+    /**
+     * A listener on e.g. port 443 (HTTPS).
+     *
+     * See the note on {@link ApiGateway} about the load balancer security group.
+     */
+    loadBalancerListener: elb.IApplicationListener;
+    /**
+     * The host name (domain name) of the backend service that we want to reach through the ALB.
+     *
+     * This is used to:
+     * - Verify the HTTPS certificate of the backend service, so that the request forwarded from
+     *   API-GW can use TLS
+     * - Set the `Host` header on the request when forwarding to the ALB, so that requests can be
+     *   routed to the correct Target Group
+     *
+     * Example value: `<service>.staging.my-project.liflig.io` (not prefixed by `https://`).
+     */
+    hostName: string;
+    /**
+     * The VPC used by the ALB. The API-GW integration will connect to the ALB using a VPC Link for
+     * this VPC.
+     *
+     * See the note on {@link ApiGateway} about the load balancer security group.
+     */
+    vpc: ec2.IVpc;
+    /**
+     * A security group (SG) that allows incoming traffic to the ALB. Will be used by the VPC link, so
+     * the API-GW integration can connect.
+     *
+     * This is usually the same SG as the ALB uses, because they have a rule that allows traffic from
+     * others in the same SG.
+     *
+     * See the note on {@link ApiGateway} about the load balancer security group.
+     */
+    securityGroup: ec2.ISecurityGroup;
+    /**
+     * Map request parameters (add/overwrite path/headers/query params) before forwarding to the
+     * backend.
+     *
+     * See {@link https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-parameter-mapping.html}
+     * for more on this. Read the 'Reserved headers' section for which headers cannot be overridden.
+     * In addition to the AWS-reserved headers, you should not override the 'Host' header either, as
+     * that's used for routing the request to the correct service behind the load balancer.
+     *
+     * ### Example:
+     *
+     * Adding a header:
+     * ```
+     * mapParameters: (parameters) => parameters.overwriteHeader(
+     *    "X-My-Custom-Header",
+     *    apigw.MappingValue.custom("my-custom-value"),
+     * )
+     * ```
+     *
+     * Overwriting the path (if, for example, you configure a `/users` route on the API Gateway that
+     * you want to forward to `/api/users` on the backend):
+     * ```
+     * mapParameters: (parameters) => parameters.overwritePath("/api/users")
+     * ```
+     */
+    mapParameters?: (parameters: apigw.ParameterMapping) => void;
+};
+export type LambdaIntegrationProps = {
+    /**
+     * The Lambda integration uses the V2 payload format:
+     * {@link https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html}
+     *
+     * If writing the Lambda in TypeScript, this means you should use `APIGatewayProxyEventV2` as the
+     * request type, and `APIGatewayProxyResultV2` as the response type.
+     */
+    lambda: lambda.IFunction;
+};
+export type SqsIntegrationProps = {
+    queue: sqs.IQueue;
+    /**
+     * Message attributes to pass on to SQS. The keys in this object are the names of the attributes.
+     * Each attribute has a DataType field, and either a StringValue or BinaryValue field depending on
+     * its type. See AWS docs:
+     * https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_MessageAttributeValue.html
+     *
+     * In the StringValue field, you can do API Gateway parameter mapping:
+     * https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-parameter-mapping.html
+     *
+     * Example:
+     * ```
+     * messageAttributes: {
+     *   clientId: {
+     *     DataType: "String",
+     *     StringValue: "${context.authorizer.clientId}",
+     *   },
+     * },
+     * ```
+     */
+    messageAttributes?: {
+        [attributeName: string]: {
+            DataType: "String" | "Number";
+            StringValue: string;
+        } | {
+            DataType: "Binary";
+            /** Base64-encoded binary data object. */
+            BinaryValue: string;
+        };
+    };
+};
+export type AuthorizationProps<AuthScopesT extends string = string> = 
+/**
+ * No authentication, for when you want a fully public route (or handle authentication in the
+ * backend integration).
+ */
+{
+    type: "NONE";
+}
+/**
+ * AWS IAM authorization.
+ * https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-access-control-iam.html
+ */
+ | {
+    type: "IAM";
+}
+/**
+ * Creates a custom authorizer lambda which reads `Authorization: Bearer <token>` header and
+ * verifies the token against a Cognito user pool.
+ */
+ | ({
+    type: "COGNITO_USER_POOL";
+} & CognitoUserPoolAuthorizerProps<AuthScopesT>)
+/**
+ * Creates a custom authorizer lambda which reads `Authorization: Basic <base64-encoded credentials>`
+ * header and verifies the credentials against a given secret.
+ */
+ | ({
+    type: "BASIC_AUTH";
+} & BasicAuthAuthorizerProps)
+/**
+ * Creates a custom authorizer lambda which allows both:
+ * - `Authorization: Bearer <token>` header, for which the token is checked against the given
+ *   Cognito user pool
+ * - `Authorization: Basic <base64-encoded credentials>` header, for which the credentials are
+ *   checked against the credentials from the given basic auth secret name
+ *
+ * If either of these are given and valid, the request is authenticated.
+ */
+ | ({
+    type: "COGNITO_USER_POOL_OR_BASIC_AUTH";
+} & CognitoUserPoolOrBasicAuthAuthorizerProps<AuthScopesT>);
+export type CognitoUserPoolAuthorizerProps<AuthScopesT extends string = string> = {
+    userPool: IUserPool;
+    /**
+     * Verifies that token claims contain the given scope.
+     *
+     * When defined as part of a resource server, scopes are on the format:
+     * `{resource server identifier}/{scope name}`, e.g. `external/view_users`.
+     *
+     * To get more type safety on this parameter, see the docs for the `AuthScopesT` type parameter on
+     * {@link ApiGateway}.
+     */
+    requiredScope?: AuthScopesT;
+    /**
+     * Name of secret in AWS Secrets Manager that stores basic auth credentials for the backend
+     * service, to be forwarded to the backend if Cognito user pool authentication succeeded.
+     *
+     * The secret value must follow this format:
+     * ```json
+     * {"username":"<username>","password":"<password>"}
+     * ```
+     *
+     * This prop solves the following use-case:
+     * - You want to do Cognito user pool authentication in the API Gateway
+     * - You want an additional auth check in the backend, but you don't want to deal with Cognito
+     *   there
+     * - The backend uses basic auth
+     *
+     * This prop solves this by letting you specify credentials to pass to the backend after API-GW
+     * authentication succeeds. You can pass the encoded credentials through
+     * {@link AlbIntegrationProps.mapParameters}, using the `authorizer.internalAuthorizationHeader`
+     * context variable, like so:
+     * ```
+     * mapParameters: (parameters) => parameters.overwriteHeader(
+     *   // 'Authorization' header cannot be overridden, so we use a custom header
+     *   "X-Internal-Authorization",
+     *   apigw.MappingValue.contextVariable("authorizer.internalAuthorizationHeader"),
+     * )
+     * ```
+     * The backend can then check the `X-Internal-Authorization` header.
+     */
+    credentialsForInternalAuthorization?: string;
+};
+export type BasicAuthAuthorizerProps = {
+    /**
+     * Name of secret in AWS Secrets Manager that stores basic auth credentials. The secret value must
+     * follow this format:
+     * ```json
+     * {"username":"<username>","password":"<password>"}
+     * ```
+     */
+    credentialsSecretName: string;
+};
+export type CognitoUserPoolOrBasicAuthAuthorizerProps<AuthScopesT extends string = string> = {
+    userPool: IUserPool;
+    /**
+     * Name of secret in AWS Secrets Manager that stores basic auth credentials. The secret value must
+     * follow this format:
+     * ```json
+     * {"username":"<username>","password":"<password>"}
+     * ```
+     */
+    basicAuthCredentialsSecretName?: string;
+    /**
+     * Verifies that token claims contain the given scope. Only applicable for `Bearer` token requests
+     * checked against the Cognito User Pool (not applicable for basic auth).
+     *
+     * When defined as part of a resource server, scopes are on the format:
+     * `{resource server identifier}/{scope name}`, e.g. `external/view_users`.
+     *
+     * To get more type safety on this parameter, see the docs for the `AuthScopesT` type parameter on
+     * {@link ApiGateway}.
+     */
+    requiredScope?: AuthScopesT;
+};
+export type ApiGatewayAccessLogsProps = {
+    /**
+     * Delete the access logs if this construct is deleted?
+     *
+     * Maybe you want to DESTROY instead. Or for legal reasons, retain for audit.
+     *
+     * @default RemovalPolicy.RETAIN
+     */
+    removalPolicy?: cdk.RemovalPolicy;
+    /**
+     * How long to keep the logs. If undefined, uses the same default as new AWS log groups.
+     *
+     * @default RetentionDays.TWO_YEARS
+     */
+    retention?: logs.RetentionDays;
+    /**
+     * A custom JSON log format, which uses variables from `"$context"`.
+     *
+     * See [AWS: CloudWatch log formats for API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-logging.html#apigateway-cloudwatch-log-formats)
+     * for formats and rules. It is possible to use other formats like CLF and XML, but this construct
+     * only supports JSON for now.
+     *
+     * For a list of all possible variables to log, see
+     * [AWS: $context Variables for data models, authorizers, mapping templates, and CloudWatch access logging](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html#context-variable-reference)
+     * and
+     * [AWS: $context Variables for access logging only](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html#context-variable-reference-access-logging-only) .
+     *
+     * @default {@link defaultAccessLogFormat}
+     */
+    accessLogFormat?: Record<string, string>;
+};
+/**
+ * This construct tries to simplify the creation of an API Gateway for a service, by collecting most
+ * of the common setup here.
+ *
+ * The approach followed in this construct is:
+ * 1. One API-GW per service
+ * 3. One subdomain per API-GW / service
+ * 4. Use HTTP API, not REST
+ * 5. Use a $default stage with autodeploy
+ * 6. Support multiple routes (with possible `/{proxy+}` to let all sub-paths through)
+ * 7. Allow custom integration/authorizer for each route, or defaults for the whole gateway
+ *
+ * The route integration is one of these:
+ * - ALB private integration with VPC Link using HTTPS to the ALB
+ * - Lambda integration
+ * - SQS integration
+ *
+ * ### Load Balancer Security Group
+ *
+ * Note that the load balancer used in an {@link AlbIntegrationProps} must allow outbound HTTPS
+ * traffic to its SecurityGroup. Otherwise, the VPC Link used by the API-GW can't get traffic from
+ * the ALB.
+ *
+ * ```
+ * const loadBalancerSecurityGroup = new ec2.SecurityGroup(..., {
+ *   allowAllOutbound: false,
+ * })
+ *
+ * loadBalancerSecurityGroup.addEgressRule(
+ *   loadBalancerSecurityGroup,
+ *   ec2.Port.tcp(443),
+ *   "Outbound to self for ALB to API-GW VPC-Link",
+ * )
+ *
+ * const loadBalancer = new lifligLoadBalancer.LoadBalancer(...,
+ *   {
+ *     overrideLoadBalancerProps: {
+ *       securityGroup: loadBalancerSecurityGroup,
+ *     },
+ *   },
+ * )
+ * ```
+ *
+ * @template AuthScopesT This type parameter allows you to improve type safety on the
+ * `requiredScope` field on {@link CognitoUserPoolOrBasicAuthAuthorizerProps}, by narrowing the type
+ * to specific strings. You can then extend the `ApiGateway` with this type to enforce those scopes
+ * across the application. Remember that auth scopes must be on the format
+ * `{resource server identifier}/{scope name}`.
+ *
+ * Example:
+ * ```
+ * type AuthScopes = "external/read_users" | "internal/create_users"
+ *
+ * export class MyProjectApiGateway extends ApiGateway<AuthScopes> {}
+ * ```
+ * TypeScript will then enforce that `requiredScope` is one of `AuthScopes`, and provide
+ * auto-complete.
+ *
+ * @author Kristian Rekstad <kre@capraconsulting.no>
+ * @author Hermann Mørkrid <hem@liflig.no>
+ */
+export declare class ApiGateway<AuthScopesT extends string = string> extends constructs.Construct {
+    /** The API Gateway HTTP API. This is the main construct for API-GW. */
+    readonly httpApi: apigw.HttpApi;
+    /** The routes which connect the {@link httpApi} to the backend integration(s). */
+    readonly routes: apigw.HttpRoute[];
+    /** The domain which consumers must use.*/
+    readonly domain: string;
+    /** Access log group. */
+    readonly logGroup: logs.LogGroup;
+    private readonly props;
+    constructor(scope: constructs.Construct, id: string, props: ApiGatewayProps<AuthScopesT>);
+    /** @throws Error */
+    private static validateProps;
+    /**
+     * The authorizer only accepts requests from external users that are authorized.
+     * Unauthorized users are stopped in the API-GW, and not forwarded to the integration.
+     */
+    private createAuthorizer;
+    private createIntegration;
+    /**
+     * Allows a grantable target (role, user etc.) permission to invoke the API.
+     * Only works when using `IAM` as {@link ApiGatewayRoute.authorization}.
+     *
+     * @param target A grantable, like {@link iam.Role}
+     */
+    grantInvoke(target: iam.IGrantable): void;
+}