@digitraffic/common 2026.3.17-1 → 2026.3.26-1-beta

package/dist/aws/infra/canaries/canary-alarm.js

@@ -0,0 +1,20 @@
+import { Alarm, ComparisonOperator } from "aws-cdk-lib/aws-cloudwatch";
+import { SnsAction } from "aws-cdk-lib/aws-cloudwatch-actions";
+import { Topic } from "aws-cdk-lib/aws-sns";
+export class CanaryAlarm {
+    constructor(stack, canary, params) {
+        const alarmName = params.alarm?.alarmName ?? `${params.name}-alarm`;
+        const alarm = new Alarm(stack, alarmName, {
+            alarmName,
+            alarmDescription: params.alarm?.description ?? "",
+            metric: canary.metricSuccessPercent(),
+            evaluationPeriods: params.alarm?.evalutionPeriods ?? 1,
+            threshold: params.alarm?.threshold ?? 100,
+            comparisonOperator: ComparisonOperator.LESS_THAN_THRESHOLD,
+        });
+        if (params.alarm?.topicArn) {
+            alarm.addAlarmAction(new SnsAction(Topic.fromTopicArn(stack, `${alarmName}-action`, params.alarm.topicArn)));
+        }
+    }
+}
+//# sourceMappingURL=canary-alarm.js.map

package/dist/aws/infra/canaries/canary-keys.d.ts

@@ -0,0 +1,3 @@
+export declare const ENV_API_KEY = "apiKeyId";
+export declare const ENV_HOSTNAME = "hostname";
+export declare const ENV_SECRET = "secret";

package/dist/aws/infra/canaries/canary-keys.js

@@ -0,0 +1,4 @@
+export const ENV_API_KEY = "apiKeyId";
+export const ENV_HOSTNAME = "hostname";
+export const ENV_SECRET = "secret";
+//# sourceMappingURL=canary-keys.js.map

package/dist/aws/infra/canaries/canary-parameters.d.ts

@@ -0,0 +1,19 @@
+import type { Runtime, Schedule } from "aws-cdk-lib/aws-synthetics";
+/** Optional env parameters for canary */
+type CanaryEnv = Record<string, string>;
+export interface CanaryParameters {
+    readonly name: string;
+    readonly schedule?: Schedule;
+    readonly secret?: string;
+    readonly handler: string;
+    readonly alarm?: {
+        readonly alarmName?: string;
+        readonly description?: string;
+        readonly evalutionPeriods?: number;
+        readonly threshold?: number;
+        readonly topicArn?: string;
+    };
+    readonly canaryEnv?: CanaryEnv;
+    readonly runtime?: Runtime;
+}
+export {};

package/dist/aws/infra/canaries/canary-parameters.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=canary-parameters.js.map

package/dist/aws/infra/canaries/canary-role.d.ts

@@ -0,0 +1,14 @@
+import { Role } from "aws-cdk-lib/aws-iam";
+import type { Construct } from "constructs";
+export declare class DigitrafficCanaryRole extends Role {
+    constructor(stack: Construct, canaryName: string);
+    /**
+     * Provides permissions to access resources within a VPC.
+     */
+    withDatabaseAccess(): this;
+    /**
+     * Same as withDatabaseAccess() - renamed to avoid confusion if used with UrlCanary.
+     * A UrlCanary needs these permissions to e.g. access a private API Gateway endpoint in a VPC.
+     */
+    withVpcAccess(): this;
+}

package/dist/aws/infra/canaries/canary-role.js

@@ -0,0 +1,51 @@
+import { ManagedPolicy, PolicyStatement, Role, ServicePrincipal, } from "aws-cdk-lib/aws-iam";
+const BASE_POLICY_STATEMENT_PROPS = {
+    actions: [
+        "logs:CreateLogStream",
+        "logs:PutLogEvents",
+        "logs:CreateLogGroup",
+        "logs:DescribeLogGroups",
+        "logs:DescribeLogStreams",
+    ],
+    resources: ["*"],
+};
+const CLOUDWATCH_STATEMENT_PROPS = {
+    actions: ["cloudwatch:PutMetricData"],
+    resources: ["*"],
+    conditions: {
+        StringEquals: {
+            "cloudwatch:namespace": "CloudWatchSynthetics",
+        },
+    },
+};
+export class DigitrafficCanaryRole extends Role {
+    constructor(stack, canaryName) {
+        super(stack, `canary-role-${canaryName}`, {
+            assumedBy: new ServicePrincipal("lambda.amazonaws.com"),
+            managedPolicies: [
+                ManagedPolicy.fromAwsManagedPolicyName("CloudWatchSyntheticsFullAccess"),
+            ],
+        });
+        this.addToPolicy(new PolicyStatement(BASE_POLICY_STATEMENT_PROPS));
+        this.addToPolicy(new PolicyStatement(CLOUDWATCH_STATEMENT_PROPS));
+    }
+    /**
+     * Provides permissions to access resources within a VPC.
+     */
+    withDatabaseAccess() {
+        // Won't work :(
+        // this.addToPolicy(new PolicyStatement(DB_STATEMENT_PROPS));
+        // Works
+        this.addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaVPCAccessExecutionRole"));
+        return this;
+    }
+    /**
+     * Same as withDatabaseAccess() - renamed to avoid confusion if used with UrlCanary.
+     * A UrlCanary needs these permissions to e.g. access a private API Gateway endpoint in a VPC.
+     */
+    withVpcAccess() {
+        this.addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaVPCAccessExecutionRole"));
+        return this;
+    }
+}
+//# sourceMappingURL=canary-role.js.map

package/dist/aws/infra/canaries/canary.d.ts

@@ -0,0 +1,8 @@
+import type { Role } from "aws-cdk-lib/aws-iam";
+import { Canary } from "aws-cdk-lib/aws-synthetics";
+import type { Construct } from "constructs";
+import type { LambdaEnvironment } from "../stack/lambda-configs.js";
+import type { CanaryParameters } from "./canary-parameters.js";
+export declare class DigitrafficCanary extends Canary {
+    constructor(scope: Construct, canaryName: string, role: Role, params: CanaryParameters, environmentVariables: LambdaEnvironment);
+}

package/dist/aws/infra/canaries/canary.js

@@ -0,0 +1,26 @@
+import { Duration } from "aws-cdk-lib";
+import { AssetCode, Canary, Runtime, Schedule, Test, } from "aws-cdk-lib/aws-synthetics";
+import { CanaryAlarm } from "./canary-alarm.js";
+export class DigitrafficCanary extends Canary {
+    constructor(scope, canaryName, role, params, environmentVariables) {
+        super(scope, canaryName, {
+            runtime: params.runtime ?? Runtime.SYNTHETICS_NODEJS_PUPPETEER_13_0,
+            role,
+            test: Test.custom({
+                code: new AssetCode("dist", {
+                    exclude: ["lambda", "out", "canaries"],
+                }),
+                handler: params.handler,
+            }),
+            environmentVariables: {
+                ...environmentVariables,
+                ...params.canaryEnv,
+            },
+            canaryName,
+            schedule: params.schedule ?? Schedule.rate(Duration.minutes(15)),
+        });
+        this.artifactsBucket.grantWrite(role);
+        new CanaryAlarm(scope, this, params);
+    }
+}
+//# sourceMappingURL=canary.js.map

package/dist/aws/infra/canaries/database-canary.d.ts

@@ -0,0 +1,17 @@
+import type { Role } from "aws-cdk-lib/aws-iam";
+import type { ISecret } from "aws-cdk-lib/aws-secretsmanager";
+import type { DigitrafficStack } from "../stack/stack.js";
+import { DigitrafficCanary } from "./canary.js";
+import type { CanaryParameters } from "./canary-parameters.js";
+export declare class DatabaseCanary extends DigitrafficCanary {
+    constructor(stack: DigitrafficStack, role: Role, secret: ISecret, params: CanaryParameters);
+    static create(stack: DigitrafficStack, role: Role, params: CanaryParameters): DatabaseCanary;
+    /**
+     * @param stack
+     * @param role
+     * @param name name of the typescipt file without -db -suffix. Max len is 10 char if @param canaryName is not given.
+     * @param params
+     * @param canaryName Optional name for canary if multiple canaries is made from same ${name}-db.ts canary file.
+     */
+    static createV2(stack: DigitrafficStack, role: Role, name: string, params?: Partial<CanaryParameters>, canaryName?: string): DatabaseCanary;
+}

package/dist/aws/infra/canaries/database-canary.js

@@ -0,0 +1,65 @@
+import { Duration } from "aws-cdk-lib";
+import { Schedule } from "aws-cdk-lib/aws-events";
+import { CfnCanary } from "aws-cdk-lib/aws-synthetics";
+import { DigitrafficCanary } from "./canary.js";
+export class DatabaseCanary extends DigitrafficCanary {
+    constructor(stack, role, secret, params) {
+        const canaryName = `${params.name}-db`;
+        const environmentVariables = stack.createDefaultLambdaEnvironment(`Synthetics-${canaryName}`);
+        // the handler code is defined at the actual project using this
+        super(stack, canaryName, role, params, environmentVariables);
+        this.artifactsBucket.grantWrite(this.role);
+        secret.grantRead(this.role);
+        // need to override vpc and security group, can't do this with cdk
+        if (this.node.defaultChild instanceof CfnCanary) {
+            const subnetIds = stack.vpc === undefined
+                ? []
+                : stack.vpc.privateSubnets.map((subnet) => subnet.subnetId);
+            const securityGroupIds = stack.lambdaDbSg === undefined
+                ? []
+                : [stack.lambdaDbSg.securityGroupId];
+            this.node.defaultChild.vpcConfig = {
+                vpcId: stack.vpc?.vpcId,
+                securityGroupIds,
+                subnetIds,
+            };
+        }
+    }
+    static create(stack, role, params) {
+        const secret = stack.getSecret();
+        return new DatabaseCanary(stack, role, secret, {
+            ...{
+                secret: stack.configuration.secretId,
+                schedule: Schedule.rate(Duration.hours(1)),
+                handler: `${params.name}.handler`,
+            },
+            ...params,
+        });
+    }
+    /**
+     * @param stack
+     * @param role
+     * @param name name of the typescipt file without -db -suffix. Max len is 10 char if @param canaryName is not given.
+     * @param params
+     * @param canaryName Optional name for canary if multiple canaries is made from same ${name}-db.ts canary file.
+     */
+    static createV2(stack, role, name, params = {}, canaryName = name) {
+        const secret = stack.getSecret();
+        return new DatabaseCanary(stack, role, secret, {
+            ...{
+                secret: stack.configuration.secretId,
+                schedule: Schedule.rate(Duration.hours(1)),
+                handler: `${name}-db.handler`,
+                name: canaryName,
+                alarm: {
+                    alarmName: canaryName === name
+                        ? `${stack.configuration.shortName}-DB-Alarm`
+                        : `${canaryName}-DB-Alarm`,
+                    topicArn: stack.configuration.alarmTopicArn,
+                },
+            },
+            ...params,
+        });
+    }
+}
+//# sourceMappingURL=database-canary.js.map

package/dist/aws/infra/canaries/database-checker.d.ts

@@ -0,0 +1,33 @@
+import type { Countable } from "../../../database/models.js";
+declare abstract class DatabaseCheck<T> {
+    readonly name: string;
+    readonly sql: string;
+    failed: boolean;
+    protected constructor(name: string, sql: string);
+    abstract check(value: T): void;
+}
+/**
+ * Checker for sql that checks the count.  Meaning that the
+ * sql must be structured as "select count(*) from <table> where <something>".
+ */
+export declare class DatabaseCountChecker {
+    readonly credentialsFunction: () => Promise<void>;
+    readonly checks: DatabaseCheck<Countable>[];
+    private constructor();
+    static createForProxy(): DatabaseCountChecker;
+    static createForRds(): DatabaseCountChecker;
+    /**
+     * Expect that the count is 1
+     */
+    expectOne(name: string, sql: string): DatabaseCountChecker;
+    /**
+     * Expect that the count is 0
+     */
+    expectZero(name: string, sql: string): DatabaseCountChecker;
+    /**
+     * Expect that the count is 1 or more
+     */
+    expectOneOrMore(name: string, sql: string): DatabaseCountChecker;
+    expect(): Promise<"OK">;
+}
+export {};

package/dist/aws/infra/canaries/database-checker.js

@@ -0,0 +1,119 @@
+import synthetics from "Synthetics";
+import { inDatabaseReadonly } from "../../../database/database.js";
+import { getEnvVariable } from "../../../utils/utils.js";
+import { logger } from "../../runtime/dt-logger-default.js";
+import { ProxyHolder } from "../../runtime/secrets/proxy-holder.js";
+import { RdsHolder } from "../../runtime/secrets/rds-holder.js";
+class DatabaseCheck {
+    name;
+    sql;
+    failed;
+    constructor(name, sql) {
+        this.name = name;
+        this.sql = sql;
+        this.failed = false;
+    }
+}
+class CountDatabaseCheck extends DatabaseCheck {
+    minCount;
+    maxCount;
+    constructor(name, sql, minCount, maxCount) {
+        super(name, sql);
+        if (!sql.toLowerCase().includes("select") ||
+            !sql.toLowerCase().includes("count")) {
+            throw new Error("sql must contain select count(*)");
+        }
+        if ((minCount === null || minCount === undefined) &&
+            (maxCount === null || maxCount === undefined)) {
+            throw new Error("no max or min given");
+        }
+        this.minCount = minCount;
+        this.maxCount = maxCount;
+    }
+    check(value) {
+        if ("count" in value) {
+            if (this.minCount && value.count < this.minCount) {
+                this.failed = true;
+                throw new Error(`count was ${value.count}, minimum is ${this.minCount}`);
+            }
+            if (this.maxCount && value.count > this.maxCount) {
+                this.failed = true;
+                throw new Error(`count was ${value.count}, max is ${this.maxCount}`);
+            }
+        }
+        else {
+            this.failed = true;
+            throw new Error("no count available");
+        }
+    }
+}
+const stepConfig = {
+    continueOnStepFailure: true,
+    screenshotOnStepStart: false,
+    screenshotOnStepSuccess: false,
+    screenshotOnStepFailure: false,
+};
+/**
+ * Checker for sql that checks the count.  Meaning that the
+ * sql must be structured as "select count(*) from <table> where <something>".
+ */
+export class DatabaseCountChecker {
+    credentialsFunction;
+    checks = [];
+    constructor(credentialsFunction) {
+        this.credentialsFunction = credentialsFunction;
+        synthetics.getConfiguration().disableRequestMetrics();
+        synthetics.getConfiguration().withFailedCanaryMetric(true);
+    }
+    static createForProxy() {
+        return new DatabaseCountChecker(() => new ProxyHolder(getEnvVariable("SECRET_ID")).setCredentials());
+    }
+    static createForRds() {
+        return new DatabaseCountChecker(() => new RdsHolder(getEnvVariable("SECRET_ID")).setCredentials());
+    }
+    /**
+     * Expect that the count is 1
+     */
+    expectOne(name, sql) {
+        this.checks.push(new CountDatabaseCheck(name, sql, 1, 1));
+        return this;
+    }
+    /**
+     * Expect that the count is 0
+     */
+    expectZero(name, sql) {
+        this.checks.push(new CountDatabaseCheck(name, sql, null, 0));
+        return this;
+    }
+    /**
+     * Expect that the count is 1 or more
+     */
+    expectOneOrMore(name, sql) {
+        this.checks.push(new CountDatabaseCheck(name, sql, 1, null));
+        return this;
+    }
+    async expect() {
+        if (!this.checks.length) {
+            throw new Error("No checks");
+        }
+        await this.credentialsFunction();
+        await inDatabaseReadonly(async (db) => {
+            for (const check of this.checks) {
+                logger.info({
+                    method: "DatabaseCountChecker.expect",
+                    message: `Running sql: ${check.sql}`,
+                });
+                const value = await db.one(check.sql);
+                const checkFunction = () => {
+                    check.check(value);
+                };
+                synthetics.executeStep(check.name, checkFunction, stepConfig);
+            }
+        });
+        if (this.checks.some((check) => check.failed)) {
+            throw new Error("Failed");
+        }
+        return "OK";
+    }
+}
+//# sourceMappingURL=database-checker.js.map

package/dist/aws/infra/canaries/url-canary.d.ts

@@ -0,0 +1,16 @@
+import type { Role } from "aws-cdk-lib/aws-iam";
+import type { ISecret } from "aws-cdk-lib/aws-secretsmanager";
+import type { DigitrafficRestApi } from "../stack/rest-api.js";
+import type { DigitrafficStack } from "../stack/stack.js";
+import { DigitrafficCanary } from "./canary.js";
+import type { CanaryParameters } from "./canary-parameters.js";
+export interface UrlCanaryParameters extends CanaryParameters {
+    readonly hostname: string;
+    readonly apiKeyId: string;
+    readonly inVpc?: boolean;
+}
+export declare class UrlCanary extends DigitrafficCanary {
+    constructor(stack: DigitrafficStack, role: Role, params: UrlCanaryParameters, secret?: ISecret);
+    static create(stack: DigitrafficStack, role: Role, publicApi: DigitrafficRestApi, params: Partial<UrlCanaryParameters>, secret?: ISecret): UrlCanary;
+    static getApiKey(publicApi: DigitrafficRestApi): string | undefined;
+}

package/dist/aws/infra/canaries/url-canary.js

@@ -0,0 +1,55 @@
+import { CfnCanary } from "aws-cdk-lib/aws-synthetics";
+import { DigitrafficCanary } from "./canary.js";
+import { ENV_API_KEY, ENV_HOSTNAME, ENV_SECRET } from "./canary-keys.js";
+export class UrlCanary extends DigitrafficCanary {
+    constructor(stack, role, params, secret) {
+        const canaryName = `${params.name}-url`;
+        const environmentVariables = {};
+        environmentVariables[ENV_HOSTNAME] = params.hostname;
+        if (params.secret) {
+            environmentVariables[ENV_SECRET] = params.secret;
+        }
+        if (params.apiKeyId) {
+            environmentVariables[ENV_API_KEY] = params.apiKeyId;
+        }
+        if (secret) {
+            secret.grantRead(role);
+        }
+        // the handler code is defined at the actual project using this
+        super(stack, canaryName, role, params, environmentVariables);
+        if (params.inVpc && this.node.defaultChild instanceof CfnCanary) {
+            const subnetIds = stack.vpc === undefined
+                ? []
+                : stack.vpc.privateSubnets.map((subnet) => subnet.subnetId);
+            const securityGroupIds = stack.lambdaDbSg === undefined
+                ? []
+                : [stack.lambdaDbSg.securityGroupId];
+            this.node.defaultChild.vpcConfig = {
+                vpcId: stack.vpc?.vpcId,
+                securityGroupIds,
+                subnetIds,
+            };
+        }
+    }
+    static create(stack, role, publicApi, params, secret) {
+        return new UrlCanary(stack, role, {
+            handler: `${params.name ?? undefined}.handler`,
+            hostname: publicApi.hostname(),
+            apiKeyId: UrlCanary.getApiKey(publicApi),
+            ...params,
+        }, secret);
+    }
+    static getApiKey(publicApi) {
+        const apiKeys = publicApi.apiKeyIds;
+        if (apiKeys.length > 1) {
+            console.info("rest api has more than one api key");
+        }
+        if (apiKeys.length === 0) {
+            console.info("rest api has no api keys");
+            return undefined;
+        }
+        // always use first api key
+        return publicApi.apiKeyIds[0];
+    }
+}
+//# sourceMappingURL=url-canary.js.map

package/dist/aws/infra/canaries/url-checker.d.ts

@@ -0,0 +1,45 @@
+import type { IncomingMessage } from "node:http";
+import type { FeatureCollection } from "geojson";
+import { MediaType } from "../../types/mediatypes.js";
+export declare const API_KEY_HEADER = "x-api-key";
+type CheckerFunction = (Res: IncomingMessage) => Promise<void>;
+type JsonCheckerFunction<T> = (json: T, body: string, message: IncomingMessage) => Promise<void>;
+export declare class UrlChecker {
+    private readonly requestOptions;
+    constructor(hostname: string, apiKey?: string);
+    static create(hostname: string, apiKeyId: string): Promise<UrlChecker>;
+    static createV2(): Promise<UrlChecker>;
+    expectStatus<T>(statusCode: number, url: string, callback: JsonCheckerFunction<T>): Promise<void>;
+    expect200<T>(url: string, ...callbacks: JsonCheckerFunction<T>[]): Promise<void>;
+    expect404(url: string): Promise<void>;
+    expect400(url: string): Promise<void>;
+    expect403WithoutApiKey(url: string, mediaType?: MediaType): Promise<void>;
+    done(): string;
+}
+export declare class ResponseChecker {
+    private readonly contentType;
+    private checkCors;
+    constructor(contentType: string);
+    static forJson(): ResponseChecker;
+    static forCSV(): ResponseChecker;
+    static forGeojson(): ResponseChecker;
+    static forJpeg(): ResponseChecker;
+    check(): CheckerFunction;
+    checkJson<T>(fn: (json: T, body: string, res: IncomingMessage) => void): CheckerFunction;
+    responseChecker(fn: (body: string, res: IncomingMessage) => void): CheckerFunction;
+}
+export declare const ContentChecker: {
+    checkJson<T>(fn: (json: T, body: string, res: IncomingMessage) => void): CheckerFunction;
+    checkResponse(fn: (body: string, res: IncomingMessage) => void): CheckerFunction;
+};
+export declare const ContentTypeChecker: {
+    checkContentType(contentType: MediaType): CheckerFunction;
+};
+export declare const GeoJsonChecker: {
+    validFeatureCollection(fn?: (json: FeatureCollection) => void): CheckerFunction;
+};
+export declare const HeaderChecker: {
+    checkHeaderExists(headerName: string): CheckerFunction;
+    checkHeaderMissing(headerName: string): CheckerFunction;
+};
+export {};