@digitraffic/common 2022.10.25-1 → 2022.10.28-2

package/src/aws/infra/stack/monitoredfunction.ts

@@ -0,0 +1,342 @@
+import { Function, FunctionProps } from "aws-cdk-lib/aws-lambda";
+import { Stack } from "aws-cdk-lib";
+import { SnsAction } from "aws-cdk-lib/aws-cloudwatch-actions";
+import { ComparisonOperator, Metric } from "aws-cdk-lib/aws-cloudwatch";
+import { DigitrafficStack } from "../stack/stack";
+import { ITopic } from "aws-cdk-lib/aws-sns";
+import {
+    databaseFunctionProps,
+    LambdaEnvironment,
+    MonitoredFunctionParameters,
+} from "../stack/lambda-configs";
+import { pascalCase } from "change-case";
+import { DigitrafficLogSubscriptions } from "../stack/subscription";
+import { TrafficType } from "../../../types/traffictype";
+
+/**
+ * Allows customization of CloudWatch Alarm properties
+ */
+export type MonitoredFunctionAlarmProps = {
+    /**
+     * Setting this to false will not create a CloudWatch alarm
+     */
+    readonly create: boolean;
+
+    readonly threshold?: number;
+
+    readonly evaluationPeriods?: number;
+
+    readonly datapointsToAlarm?: number;
+
+    readonly comparisonOperator?: ComparisonOperator;
+};
+
+export type MonitoredFunctionProps = {
+    readonly durationAlarmProps?: MonitoredFunctionAlarmProps;
+
+    readonly durationWarningProps?: MonitoredFunctionAlarmProps;
+
+    readonly errorAlarmProps?: MonitoredFunctionAlarmProps;
+
+    readonly throttleAlarmProps?: MonitoredFunctionAlarmProps;
+};
+
+/**
+ * Creates a Lambda function that monitors default CloudWatch Lambda metrics with CloudWatch Alarms.
+ */
+export class MonitoredFunction extends Function {
+    readonly givenName: string;
+
+    /** disable all alarms */
+    public static readonly DISABLE_ALARMS: MonitoredFunctionProps = {
+        durationAlarmProps: {
+            create: false,
+        },
+        durationWarningProps: {
+            create: false,
+        },
+        errorAlarmProps: {
+            create: false,
+        },
+        throttleAlarmProps: {
+            create: false,
+        },
+    };
+
+    /**
+     * Create new MonitoredFunction.  Use topics from given DigitrafficStack.
+     *
+     * @param stack DigitrafficStack
+     * @param id Lambda construct Id
+     * @param functionProps Lambda function properties
+     * @param props Monitored function properties
+     */
+    static create(
+        stack: DigitrafficStack,
+        id: string,
+        functionProps: FunctionProps,
+        props?: MonitoredFunctionProps
+    ): MonitoredFunction {
+        if (
+            props === MonitoredFunction.DISABLE_ALARMS &&
+            stack.configuration.production
+        ) {
+            throw new Error(
+                `Function ${functionProps.functionName} has DISABLE_ALARMS.  Remove before installing to production or define your own properties!`
+            );
+        }
+
+        return new MonitoredFunction(
+            stack,
+            id,
+            functionProps,
+            stack.alarmTopic,
+            stack.warningTopic,
+            stack.configuration.production,
+            stack.configuration.trafficType,
+            props
+        );
+    }
+
+    /**
+     * Create new MonitoredFunction.  Use topics from given DigitrafficStack.  Generate names from given name and configuration shortName.
+     *
+     * For example, shortName FOO and given name update-things will create function FOO-UpdateThings and use code from lambda/update-things/update-things.ts method handler.
+     *
+     * @param stack DigitrafficStack
+     * @param name param-case name
+     * @param environment Lambda environment
+     * @param functionParameters Lambda function parameters
+     */
+    static createV2(
+        stack: DigitrafficStack,
+        name: string,
+        environment: LambdaEnvironment,
+        functionParameters?: MonitoredFunctionParameters
+    ): MonitoredFunction {
+        const functionName =
+            functionParameters?.functionName ||
+            `${stack.configuration.shortName}-${pascalCase(name)}`;
+        const functionProps = databaseFunctionProps(
+            stack,
+            environment,
+            functionName,
+            name,
+            functionParameters
+        );
+
+        return MonitoredFunction.create(
+            stack,
+            functionName,
+            functionProps,
+            functionParameters
+        );
+    }
+
+    /**
+     * @param scope Stack
+     * @param id Lambda construct Id
+     * @param functionProps Lambda function properties
+     * @param alarmSnsTopic SNS topic for alarms
+     * @param warningSnsTopic SNS topic for warnings
+     * @param production Is the stack a production stack, used for determining the alarm topic
+     * @param trafficType Traffic type, used for alarm names. Set to null if Lambda is not related to any traffic type.
+     * @param props Monitored function properties
+     */
+    constructor(
+        scope: Stack,
+        id: string,
+        functionProps: FunctionProps,
+        alarmSnsTopic: ITopic,
+        warningSnsTopic: ITopic,
+        production: boolean,
+        trafficType: TrafficType | null,
+        props?: MonitoredFunctionProps
+    ) {
+        super(scope, id, functionProps);
+
+        if (functionProps.functionName === undefined) {
+            throw new Error("Function name not provided");
+        }
+        this.givenName = functionProps.functionName;
+
+        const alarmSnsAction = new SnsAction(alarmSnsTopic);
+        const warningSnsAction = new SnsAction(warningSnsTopic);
+
+        if (props?.durationAlarmProps?.create !== false) {
+            if (!functionProps.timeout) {
+                throw new Error("Timeout needs to be explicitly set");
+            }
+
+            this.createAlarm(
+                scope,
+                this.metricDuration().with({ statistic: "max" }),
+                "Duration",
+                "Duration alarm",
+                `Duration has exceeded ${functionProps.timeout.toSeconds()} seconds`,
+                trafficType,
+                this.getAlarmActionForEnv(
+                    alarmSnsAction,
+                    warningSnsAction,
+                    production
+                ),
+                functionProps.timeout.toMilliseconds(),
+                1,
+                1,
+                ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+                props?.durationAlarmProps
+            );
+        }
+        if (props?.durationWarningProps?.create !== false) {
+            if (!functionProps.timeout) {
+                throw new Error("Timeout needs to be explicitly set");
+            }
+
+            this.createAlarm(
+                scope,
+                this.metricDuration().with({ statistic: "max" }),
+                "Duration-Warning",
+                "Duration warning",
+                `Duration is 85 % of max ${functionProps.timeout.toSeconds()} seconds`,
+                trafficType,
+                warningSnsAction,
+                functionProps.timeout.toMilliseconds() * 0.85,
+                1,
+                1,
+                ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+                props?.durationWarningProps
+            );
+        }
+
+        if (props?.errorAlarmProps?.create !== false) {
+            this.createAlarm(
+                scope,
+                this.metricErrors(),
+                "Errors",
+                "Errors alarm",
+                "Invocations did not succeed",
+                trafficType,
+                this.getAlarmActionForEnv(
+                    alarmSnsAction,
+                    warningSnsAction,
+                    production
+                ),
+                1,
+                1,
+                1,
+                ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+                props?.errorAlarmProps
+            );
+        }
+
+        if (props?.throttleAlarmProps?.create !== false) {
+            this.createAlarm(
+                scope,
+                this.metricThrottles(),
+                "Throttles",
+                "Throttles alarm",
+                "Has throttled",
+                trafficType,
+                this.getAlarmActionForEnv(
+                    alarmSnsAction,
+                    warningSnsAction,
+                    production
+                ),
+                0,
+                1,
+                1,
+                ComparisonOperator.GREATER_THAN_THRESHOLD,
+                props?.throttleAlarmProps
+            );
+        }
+    }
+
+    private createAlarm(
+        stack: Stack,
+        metric: Metric,
+        alarmId: string,
+        alarmName: string,
+        alarmDescription: string,
+        trafficType: TrafficType | null,
+        alarmSnsAction: SnsAction,
+        threshold: number,
+        evaluationPeriods: number,
+        datapointsToAlarm: number,
+        comparisonOperator: ComparisonOperator,
+        alarmProps?: MonitoredFunctionAlarmProps
+    ) {
+        metric
+            .createAlarm(stack, `${this.node.id}-${alarmId}`, {
+                alarmName: `${trafficType ?? ""} ${stack.stackName} ${
+                    this.functionName
+                } ${alarmName}`.trim(),
+                alarmDescription,
+                threshold: alarmProps?.threshold ?? threshold,
+                evaluationPeriods:
+                    alarmProps?.evaluationPeriods ?? evaluationPeriods,
+                datapointsToAlarm:
+                    alarmProps?.datapointsToAlarm ?? datapointsToAlarm,
+                comparisonOperator:
+                    alarmProps?.comparisonOperator ?? comparisonOperator,
+            })
+            .addAlarmAction(alarmSnsAction);
+    }
+
+    private getAlarmActionForEnv(
+        alarmAction: SnsAction,
+        warningAction: SnsAction,
+        production: boolean
+    ): SnsAction {
+        return production ? alarmAction : warningAction;
+    }
+}
+
+export class MonitoredDBFunction {
+    /**
+     * Create new MonitoredDBFunction.  Use topics from given DigitrafficStack.  Generate names from given name and configuration shortName.
+     * Grant secret and create log subscription.
+     *
+     * For example, shortName FOO and given name update-things will create function FOO-UpdateThings and use code from lambda/update-things/update-things.ts method handler.
+     *
+     * If you don't need to pass any extra arguments to lambda-environment, you can leave environment out and this function will create the
+     * default Lambda Environment with SECRET_ID and DB_APPLICATION.
+     *
+     * @param stack DigitrafficStack
+     * @param name param-case name
+     * @param environment Lambda environment
+     * @param functionParameters Lambda function parameters
+     */
+    static create(
+        stack: DigitrafficStack,
+        name: string,
+        environment?: LambdaEnvironment,
+        functionParameters?: MonitoredFunctionParameters
+    ): MonitoredFunction {
+        const functionName =
+            functionParameters?.functionName ||
+            `${stack.configuration.shortName}-${pascalCase(name)}`;
+        const env = environment ? environment : stack.createLambdaEnvironment();
+        const functionProps = databaseFunctionProps(
+            stack,
+            env,
+            functionName,
+            name,
+            functionParameters
+        );
+
+        const mf = MonitoredFunction.create(
+            stack,
+            functionName,
+            functionProps,
+            functionParameters
+        );
+
+        stack.grantSecret(mf);
+
+        if (stack.configuration.logsDestinationArn) {
+            new DigitrafficLogSubscriptions(stack, mf);
+        }
+
+        return mf;
+    }
+}

package/src/aws/infra/stack/rest_apis.ts

@@ -0,0 +1,223 @@
+import {
+    RestApi,
+    MethodLoggingLevel,
+    GatewayResponse,
+    ResponseType,
+    EndpointType,
+    RestApiProps, JsonSchema, Model, CfnDocumentationPart, Resource,
+} from 'aws-cdk-lib/aws-apigateway';
+import {PolicyDocument, PolicyStatement, Effect, AnyPrincipal} from 'aws-cdk-lib/aws-iam';
+import {Construct} from "constructs";
+import {DigitrafficStack} from "./stack";
+import {createDefaultUsagePlan, createUsagePlan} from "../usage-plans";
+import {ModelWithReference} from "../../types/model-with-reference";
+import {getModelReference} from "../../../utils/api-model";
+import {MediaType} from "../../types/mediatypes";
+import {DocumentationPart, DocumentationProperties} from "../documentation";
+
+import R = require('ramda');
+
+export class DigitrafficRestApi extends RestApi {
+    readonly apiKeyIds: string[];
+    readonly enableDocumentation: boolean;
+
+    constructor(
+        stack: DigitrafficStack, apiId: string, apiName: string, allowFromIpAddresses?: string[] | undefined, config?: Partial<RestApiProps>,
+    ) {
+        const policyDocument = allowFromIpAddresses == null ? createDefaultPolicyDocument() : createIpRestrictionPolicyDocument(allowFromIpAddresses);
+
+        // override default config with given extra config
+        const apiConfig = {...{
+            deployOptions: {
+                loggingLevel: MethodLoggingLevel.ERROR,
+            },
+            restApiName: apiName,
+            endpointTypes: [EndpointType.REGIONAL],
+            policy: policyDocument,
+        }, ...config};
+
+        super(stack, apiId, apiConfig);
+
+        this.apiKeyIds = [];
+        this.enableDocumentation = stack.configuration.stackFeatures?.enableDocumentation ?? true;
+
+        add404Support(this, stack);
+    }
+
+    hostname(): string {
+        return `${this.restApiId}.execute-api.${(this.stack as DigitrafficStack).region}.amazonaws.com`;
+    }
+
+    createUsagePlan(apiKeyId: string, apiKeyName: string): string {
+        const newKeyId = createUsagePlan(this, apiKeyId, apiKeyName).keyId;
+
+        this.apiKeyIds.push(newKeyId);
+
+        return newKeyId;
+    }
+
+    createUsagePlanV2(apiName: string): string {
+        const newKeyId = createDefaultUsagePlan(this, apiName).keyId;
+
+        this.apiKeyIds.push(newKeyId);
+
+        return newKeyId;
+    }
+
+    addJsonModel(modelName: string, schema: JsonSchema) {
+        return this.getModelWithReference(this.addModel(modelName, {
+            contentType: MediaType.APPLICATION_JSON,
+            modelName,
+            schema,
+        }));
+    }
+
+    addCSVModel(modelName: string) {
+        return this.getModelWithReference(this.addModel(modelName, {
+            contentType: MediaType.TEXT_CSV,
+            modelName,
+            schema: {},
+        }));
+    }
+
+    private getModelWithReference(model: Model): ModelWithReference {
+        return R.assoc('modelReference', getModelReference(model.modelId, this.restApiId), model) as ModelWithReference;
+    }
+
+    private addDocumentationPart(
+        resource: Resource, parameterName: string, resourceName: string, type: string, properties: DocumentationProperties,
+    ) {
+        const location: CfnDocumentationPart.LocationProperty = {
+            type,
+            path: resource.path,
+            name: type !== 'METHOD' ? parameterName : undefined,
+        };
+
+        new CfnDocumentationPart(this.stack, resourceName, {
+            restApiId: resource.api.restApiId,
+            location,
+            properties: JSON.stringify(properties),
+        });
+    }
+
+    documentResource(resource: Resource, ...documentationPart: DocumentationPart[]) {
+        if(this.enableDocumentation) {
+            documentationPart.forEach(dp => this.addDocumentationPart(
+                resource, dp.parameterName, `${resource.path}.${dp.parameterName}.Documentation`, dp.type, dp.documentationProperties,
+            ));
+        } else {
+            console.info("Skipping documentation for %s", resource.path);
+        }
+    }
+}
+
+/**
+ * Due to AWS API design API Gateway will always return 403 'Missing Authentication Token' for requests
+ * with a non-existent endpoint. This function translates this response to a 404.
+ * Requests with an invalid or missing API key are not affected (still return 403 'Forbidden').
+ * @param restApi RestApi
+ * @param stack Construct
+ */
+export function add404Support(restApi: RestApi, stack: Construct) {
+    new GatewayResponse(stack, `MissingAuthenticationTokenResponse-${restApi.restApiName}`, {
+        restApi,
+        type: ResponseType.MISSING_AUTHENTICATION_TOKEN,
+        statusCode: '404',
+        templates: {
+            'application/json': '{"message": "Not found"}',
+        },
+    });
+}
+
+export function add401Support(restApi: RestApi, stack: Construct) {
+    new GatewayResponse(stack, `AuthenticationFailedResponse-${restApi.restApiName}`, {
+        restApi,
+        type: ResponseType.UNAUTHORIZED,
+        statusCode: "401",
+        responseHeaders: {
+            'WWW-Authenticate': "'Basic'",
+        },
+    });
+}
+
+/**
+ * Due to AWS API design API Gateway will always return 403 'Missing Authentication Token' for requests
+ * with a non-existent endpoint. This function converts this response to a custom one.
+ * Requests with an invalid or missing API key are not affected (still return 403 'Forbidden').
+ * @param returnCode
+ * @param message
+ * @param restApi RestApi
+ * @param stack Construct
+ */
+export function setReturnCodeForMissingAuthenticationToken(returnCode: number,
+    message: string,
+    restApi: RestApi,
+    stack: Construct) {
+
+    new GatewayResponse(stack, `MissingAuthenticationTokenResponse-${restApi.restApiName}`, {
+        restApi,
+        type: ResponseType.MISSING_AUTHENTICATION_TOKEN,
+        statusCode: `${returnCode}`,
+        templates: {
+            'application/json': `{"message": ${message}}`,
+        },
+    });
+}
+
+export function createRestApi(stack: Construct, apiId: string, apiName: string, allowFromIpAddresses?: string[] | undefined): RestApi {
+    const policyDocument = allowFromIpAddresses == null ? createDefaultPolicyDocument() : createIpRestrictionPolicyDocument(allowFromIpAddresses);
+    const restApi = new RestApi(stack, apiId, {
+        deployOptions: {
+            loggingLevel: MethodLoggingLevel.ERROR,
+        },
+        restApiName: apiName,
+        endpointTypes: [EndpointType.REGIONAL],
+        policy: policyDocument,
+    });
+    add404Support(restApi, stack);
+    return restApi;
+}
+
+export function createDefaultPolicyDocument() {
+    return new PolicyDocument({
+        statements: [
+            new PolicyStatement({
+                effect: Effect.ALLOW,
+                actions: [
+                    "execute-api:Invoke",
+                ],
+                resources: [
+                    "*",
+                ],
+                principals: [
+                    new AnyPrincipal(),
+                ],
+            }),
+        ],
+    });
+}
+
+
+export function createIpRestrictionPolicyDocument(allowFromIpAddresses: string[]): PolicyDocument {
+    return new PolicyDocument({
+        statements: [
+            new PolicyStatement({
+                effect: Effect.ALLOW,
+                conditions: {
+                    "IpAddress": {
+                        "aws:SourceIp": allowFromIpAddresses,
+                    },
+                },
+                actions: [
+                    "execute-api:Invoke",
+                ],
+                resources: [
+                    "*",
+                ],
+                principals: [
+                    new AnyPrincipal(),
+                ],
+            }),
+        ],
+    });
+}