@digitraffic/common 2026.9.4-1 → 2026.9.4-2

package/dist/__test__/stack/dt-function.test.js

@@ -61,6 +61,7 @@ describe("FunctionBuilder test", () => {
         template.hasResourceProperties("AWS::Lambda::Function", {
             Environment: {
                 Variables: {
+                    [EnvKeys.APP_NAME]: "road-test",
                     [EnvKeys.SECRET_ID]: "testSecret",
                     [TEST_ENV_VAR]: TEST_ENV_VALUE,
                 },
@@ -139,11 +140,9 @@ describe("FunctionBuilder test", () => {
         });
     });
     test("Lambda handler module is resolved from path last element", () => {
-        const template = createTemplate((_builder) => { }, false, "api/charging-network/v1/operators");
-        // const lambdas = template.findResources("AWS::Lambda::Function");
-        // console.debug(JSON.stringify(lambdas, null, 2));
+        const template = createTemplate((_builder) => { }, false, "api/feature/v1/get-items");
         template.hasResourceProperties("AWS::Lambda::Function", {
-            Handler: "operators.handler",
+            Handler: "get-items.handler",
         });
     });
     test("Lambda handler module is same as lambda name", () => {
@@ -336,122 +335,5 @@ describe("FunctionBuilder test", () => {
                 .build();
         }).toThrow('Lambda test-Test cannot use wildcard action "*" in withAllowedActions');
     });
-    describe("withAdotTracing", () => {
-        test("given withAdotTracing is called / when lambda is built / then AWS_LAMBDA_EXEC_WRAPPER is set", () => {
-            // given/when
-            const template = createTemplate((builder) => {
-                builder.withAdotTracing();
-            });
-            // then
-            expectEnvironmentValue(template, "AWS_LAMBDA_EXEC_WRAPPER", "/opt/otel-instrument");
-        });
-        test("given withAdotTracing is called / when lambda is built / then OTEL_AWS_APPLICATION_SIGNALS_ENABLED is false", () => {
-            // given/when
-            const template = createTemplate((builder) => {
-                builder.withAdotTracing();
-            });
-            // then
-            expectEnvironmentValue(template, "OTEL_AWS_APPLICATION_SIGNALS_ENABLED", "false");
-        });
-        test("given withAdotTracing is called / when lambda is built / then X-Ray active tracing is enabled", () => {
-            // given/when
-            const template = createTemplate((builder) => {
-                builder.withAdotTracing();
-            });
-            // then
-            template.hasResourceProperties("AWS::Lambda::Function", {
-                TracingConfig: { Mode: "Active" },
-            });
-        });
-        test("given withAdotTracing is called / when lambda is built / then CloudWatch Lambda Application Signals policy is attached", () => {
-            // given/when
-            const template = createTemplate((builder) => {
-                builder.withAdotTracing();
-            });
-            // then — the managed policy ARN contains CloudWatchLambdaApplicationSignalsExecutionRolePolicy
-            const roles = template.findResources("AWS::IAM::Role");
-            const lambdaRoleKey = Object.keys(roles).find((key) => key.includes("ServiceRole"));
-            expect(lambdaRoleKey).toBeDefined();
-            const role = roles[lambdaRoleKey];
-            const managedPolicyArns = JSON.stringify(role["Properties"]?.["ManagedPolicyArns"]);
-            expect(managedPolicyArns).toContain("CloudWatchLambdaApplicationSignalsExecutionRolePolicy");
-        });
-        test("given withAdotTracing on Node.js runtime / when lambda is built / then JS ADOT layer is attached", () => {
-            // given/when — default runtime is NODEJS_24_X
-            const template = createTemplate((builder) => {
-                builder.withAdotTracing();
-            });
-            // then
-            template.hasResourceProperties("AWS::Lambda::Function", {
-                Layers: Match.arrayWith([
-                    Match.stringLikeRegexp("AWSOpenTelemetryDistroJs"),
-                ]),
-            });
-        });
-        test("given withAdotTracing on Python runtime / when lambda is built / then Python ADOT layer is attached", () => {
-            // given/when
-            const template = createTemplate((builder) => {
-                builder.withRuntime(Runtime.PYTHON_3_12).withAdotTracing();
-            });
-            // then
-            template.hasResourceProperties("AWS::Lambda::Function", {
-                Layers: Match.arrayWith([
-                    Match.stringLikeRegexp("AWSOpenTelemetryDistroPython"),
-                ]),
-            });
-        });
-        test("given withAdotTracing is NOT called / when lambda is built / then ADOT env vars are absent", () => {
-            // given/when
-            const template = createTemplate((_builder) => { });
-            // then
-            expectEnvironmentValueMissing(template, "AWS_LAMBDA_EXEC_WRAPPER");
-            expectEnvironmentValueMissing(template, "OTEL_AWS_APPLICATION_SIGNALS_ENABLED");
-        });
-        test("given withAdotTracing is NOT called / when lambda is built / then tracing is not Active", () => {
-            // given/when
-            const template = createTemplate((_builder) => { });
-            // then
-            template.hasResourceProperties("AWS::Lambda::Function", {
-                TracingConfig: Match.absent(),
-            });
-        });
-        test("given withAdotTracing combined with other builder methods / when lambda is built / then all properties are present", () => {
-            // given/when
-            const template = createTemplate((builder) => {
-                builder
-                    .withAdotTracing()
-                    .withMemorySize(512)
-                    .withTimeout(Duration.seconds(30))
-                    .withEnvironment({ CUSTOM_KEY: "custom_value" });
-            });
-            // then — ADOT config present
-            expectEnvironmentValue(template, "AWS_LAMBDA_EXEC_WRAPPER", "/opt/otel-instrument");
-            template.hasResourceProperties("AWS::Lambda::Function", {
-                TracingConfig: { Mode: "Active" },
-            });
-            // then — other builder settings also present
-            template.hasResourceProperties("AWS::Lambda::Function", {
-                MemorySize: 512,
-                Timeout: 30,
-            });
-            expectEnvironmentValue(template, "CUSTOM_KEY", "custom_value");
-        });
-        test("given withAdotTracing on plain builder / when lambda is built / then ADOT config is applied without database env vars", () => {
-            // given/when
-            const template = createTemplate((builder) => {
-                builder.withAdotTracing();
-            }, true);
-            // then — ADOT config present
-            expectEnvironmentValue(template, "AWS_LAMBDA_EXEC_WRAPPER", "/opt/otel-instrument");
-            template.hasResourceProperties("AWS::Lambda::Function", {
-                TracingConfig: { Mode: "Active" },
-                Layers: Match.arrayWith([
-                    Match.stringLikeRegexp("AWSOpenTelemetryDistroJs"),
-                ]),
-            });
-            // then — no database env vars
-            expectEnvironmentValueMissing(template, "DB_APPLICATION");
-        });
-    });
 });
 //# sourceMappingURL=dt-function.test.js.map

package/dist/__test__/utils/lead-time-logging.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__test__/utils/lead-time-logging.test.js

@@ -0,0 +1,153 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { logger } from "../../aws/runtime/dt-logger-default.js";
+import { logLeadTime, logLeadTimes } from "../../utils/lead-time-logging.js";
+describe("lead-time-logging", () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    test("logLeadTime logs expected payload", () => {
+        const infoSpy = vi
+            .spyOn(logger, "info")
+            .mockImplementation(() => undefined);
+        const errorSpy = vi
+            .spyOn(logger, "error")
+            .mockImplementation(() => undefined);
+        logLeadTime("lead-time", "test-target", 123);
+        expect(infoSpy).toHaveBeenCalledTimes(1);
+        expect(infoSpy).toHaveBeenCalledWith({
+            method: "LeadTimeLogging.logLeadTime",
+            customLeadTime: true,
+            customName: "lead-time",
+            customTarget: "test-target",
+            tookMs: 123,
+        });
+        expect(errorSpy).toHaveBeenCalledTimes(0);
+    });
+    test("logLeadTime merges extra fields", () => {
+        const infoSpy = vi
+            .spyOn(logger, "info")
+            .mockImplementation(() => undefined);
+        logLeadTime("mqtt-time", "mqtt", 88, {
+            customSource: "mqtt",
+            customRetriesCount: 2,
+        });
+        expect(infoSpy).toHaveBeenCalledTimes(1);
+        expect(infoSpy).toHaveBeenCalledWith({
+            method: "LeadTimeLogging.logLeadTime",
+            customLeadTime: true,
+            customName: "mqtt-time",
+            customTarget: "mqtt",
+            tookMs: 88,
+            customSource: "mqtt",
+            customRetriesCount: 2,
+        });
+    });
+    test("logLeadTime logs error if logger.info throws", () => {
+        const infoError = new Error("boom");
+        vi.spyOn(logger, "info").mockImplementation(() => {
+            throw infoError;
+        });
+        const errorSpy = vi
+            .spyOn(logger, "error")
+            .mockImplementation(() => undefined);
+        logLeadTime("process-time", "target", 10);
+        expect(errorSpy).toHaveBeenCalledTimes(1);
+        expect(errorSpy).toHaveBeenCalledWith({
+            method: "LeadTimeLogging.logLeadTime",
+            message: "Error logging lead time",
+            error: infoError,
+        });
+    });
+    test("logLeadTimes logs only lead-time when only leadTimeMs is safe", () => {
+        const infoSpy = vi
+            .spyOn(logger, "info")
+            .mockImplementation(() => undefined);
+        logLeadTimes({ target: "x", leadTimeMs: 10 });
+        expect(infoSpy).toHaveBeenCalledTimes(1);
+        expect(infoSpy).toHaveBeenNthCalledWith(1, {
+            method: "LeadTimeLogging.logLeadTime",
+            customLeadTime: true,
+            customName: "lead-time",
+            customTarget: "x",
+            tookMs: 10,
+        });
+    });
+    test("logLeadTimes logs only process-time when only processTimeMs is safe", () => {
+        const infoSpy = vi
+            .spyOn(logger, "info")
+            .mockImplementation(() => undefined);
+        logLeadTimes({ target: "x", processTimeMs: 20 });
+        expect(infoSpy).toHaveBeenCalledTimes(1);
+        expect(infoSpy).toHaveBeenNthCalledWith(1, {
+            method: "LeadTimeLogging.logLeadTime",
+            customLeadTime: true,
+            customName: "process-time",
+            customTarget: "x",
+            tookMs: 20,
+        });
+    });
+    test("logLeadTimes logs both in order with extra fields", () => {
+        const infoSpy = vi
+            .spyOn(logger, "info")
+            .mockImplementation(() => undefined);
+        const input = {
+            target: "device",
+            leadTimeMs: 11,
+            processTimeMs: 22,
+            extraFields: { customSource: "mqtt", customPartition: 3 },
+        };
+        logLeadTimes(input);
+        expect(infoSpy).toHaveBeenCalledTimes(2);
+        expect(infoSpy).toHaveBeenNthCalledWith(1, {
+            method: "LeadTimeLogging.logLeadTime",
+            customLeadTime: true,
+            customName: "lead-time",
+            customTarget: "device",
+            tookMs: 11,
+            customSource: "mqtt",
+            customPartition: 3,
+        });
+        expect(infoSpy).toHaveBeenNthCalledWith(2, {
+            method: "LeadTimeLogging.logLeadTime",
+            customLeadTime: true,
+            customName: "process-time",
+            customTarget: "device",
+            tookMs: 22,
+            customSource: "mqtt",
+            customPartition: 3,
+        });
+    });
+    test("logLeadTimes ignores non-safe values", () => {
+        const infoSpy = vi
+            .spyOn(logger, "info")
+            .mockImplementation(() => undefined);
+        logLeadTimes({
+            target: "x",
+            leadTimeMs: 1.5,
+            processTimeMs: Number.MAX_SAFE_INTEGER + 1,
+        });
+        logLeadTimes({
+            target: "x",
+            leadTimeMs: Number.NaN,
+            processTimeMs: Infinity,
+        });
+        logLeadTimes({ target: "x" });
+        expect(infoSpy).toHaveBeenCalledTimes(0);
+    });
+    test("logLeadTimes logs negative safe integer values", () => {
+        const infoSpy = vi
+            .spyOn(logger, "info")
+            .mockImplementation(() => undefined);
+        logLeadTimes({ target: "x", leadTimeMs: -5 });
+        expect(infoSpy).toHaveBeenCalledTimes(1);
+        expect(infoSpy).toHaveBeenNthCalledWith(1, {
+            method: "LeadTimeLogging.logLeadTime",
+            customLeadTime: true,
+            customName: "lead-time",
+            customTarget: "x",
+            tookMs: -5,
+        });
+    });
+});
+// clean comment
+//# sourceMappingURL=lead-time-logging.test.js.map

package/dist/aws/infra/acl-builder.d.ts

@@ -32,13 +32,32 @@ export declare class AclBuilder {
      * Allow access only from the given addresses
      */
     withIpWhitelistRule(addresses: string[]): this;
-    withThrottleRule(name: string, limit: number, isHeaderRequired: boolean, isBasedOnIpAndUriPath: boolean, customResponseBodyKey?: string, path?: RegExp): this;
+    /**
+     * Adds a rate-based WAF rule for either blocking or counting requests.
+     *
+     * @param name WAF rule name and CloudWatch metric name.
+     * @param limit Maximum requests allowed in the WAF evaluation window.
+     * @param isHeaderRequired Whether the rule applies when the digitraffic-user header is present.
+     * @param isBasedOnIpAndUriPath Whether requests are aggregated by IP address and URI path.
+     * @param customResponseBodyKey Custom response body key; when provided, matching requests are blocked instead of counted.
+     * @param path Optional URI path pattern that limits which requests are included.
+     * @param excludedPath Optional URI path pattern that excludes matching requests from the rule.
+     */
+    withThrottleRule(name: string, limit: number, isHeaderRequired: boolean, isBasedOnIpAndUriPath: boolean, customResponseBodyKey?: string, path?: RegExp, excludedPath?: RegExp): this;
     withCustomResponseBody(key: string, customResponseBody: CfnWebACL.CustomResponseBodyProperty): this;
     withThrottleDigitrafficUserIp(limit: number | undefined): this;
     withThrottleDigitrafficUserIpAndUriPath(limit: number | undefined): this;
     withThrottleAnonymousUserIp(limit: number | undefined): AclBuilder;
     withThrottleAnonymousUserIpByUriPath(limit: number | undefined, path: RegExp | undefined): AclBuilder;
-    withThrottleAnonymousUserIpAndUriPath(limit: number | undefined): this;
+    /**
+     * Throttles anonymous requests by IP address and URI path.
+     *
+     * Existing callers that omit `excludedPath` retain the previous behavior.
+     *
+     * @param limit Maximum requests allowed for each IP and URI path combination.
+     * @param excludedPath Optional URI path pattern excluded from this throttle rule.
+     */
+    withThrottleAnonymousUserIpAndUriPath(limit: number | undefined, excludedPath?: RegExp): this;
     withCountDigitrafficUserIp(limit: number | undefined): this;
     withCountDigitrafficUserIpAndUriPath(limit: number | undefined): this;
     withCountAnonymousUserIp(limit: number | undefined): this;

package/dist/aws/infra/acl-builder.js

@@ -91,7 +91,18 @@ export class AclBuilder {
         });
         return this;
     }
-    withThrottleRule(name, limit, isHeaderRequired, isBasedOnIpAndUriPath, customResponseBodyKey, path) {
+    /**
+     * Adds a rate-based WAF rule for either blocking or counting requests.
+     *
+     * @param name WAF rule name and CloudWatch metric name.
+     * @param limit Maximum requests allowed in the WAF evaluation window.
+     * @param isHeaderRequired Whether the rule applies when the digitraffic-user header is present.
+     * @param isBasedOnIpAndUriPath Whether requests are aggregated by IP address and URI path.
+     * @param customResponseBodyKey Custom response body key; when provided, matching requests are blocked instead of counted.
+     * @param path Optional URI path pattern that limits which requests are included.
+     * @param excludedPath Optional URI path pattern that excludes matching requests from the rule.
+     */
+    withThrottleRule(name, limit, isHeaderRequired, isBasedOnIpAndUriPath, customResponseBodyKey, path, excludedPath) {
         const isBlockRule = !!customResponseBodyKey;
         const rules = isBlockRule ? this._blockRules : this._countRules;
         const action = isBlockRule
@@ -114,7 +125,7 @@ export class AclBuilder {
                 metricName: name,
             },
             action,
-            statement: createThrottleStatement(limit, isHeaderRequired, isBasedOnIpAndUriPath, path),
+            statement: createThrottleStatement(limit, isHeaderRequired, isBasedOnIpAndUriPath, path, excludedPath),
         });
         return this;
     }
@@ -160,13 +171,21 @@ export class AclBuilder {
         this._addThrottleResponseBody(customResponseBodyKey, limit);
         return this.withThrottleRule("ThrottleRuleWithAnonymousUserByPath", limit, false, false, customResponseBodyKey, path);
     }
-    withThrottleAnonymousUserIpAndUriPath(limit) {
+    /**
+     * Throttles anonymous requests by IP address and URI path.
+     *
+     * Existing callers that omit `excludedPath` retain the previous behavior.
+     *
+     * @param limit Maximum requests allowed for each IP and URI path combination.
+     * @param excludedPath Optional URI path pattern excluded from this throttle rule.
+     */
+    withThrottleAnonymousUserIpAndUriPath(limit, excludedPath) {
         if (limit === undefined) {
             return this;
         }
         const customResponseBodyKey = `IP_PATH_THROTTLE_ANONYMOUS_USER_${limit}`;
         this._addThrottleResponseBody(customResponseBodyKey, limit);
-        return this.withThrottleRule("ThrottleRuleIPQueryWithAnonymousUser", limit, false, true, customResponseBodyKey);
+        return this.withThrottleRule("ThrottleRuleIPQueryWithAnonymousUser", limit, false, true, customResponseBodyKey, undefined, excludedPath);
     }
     withCountDigitrafficUserIp(limit) {
         if (limit === undefined) {
@@ -289,8 +308,18 @@ function notStatement(statement) {
         },
     };
 }
-function createThrottleStatement(limit, isHeaderRequired, isBasedOnIpAndUriPath, path) {
-    // this statement matches empty digitraffic-user -header
+/**
+ * Creates the scope-down and rate-based statement used by a throttle rule.
+ *
+ * @param limit Maximum requests allowed in the WAF evaluation window.
+ * @param isHeaderRequired Whether the statement matches requests with the digitraffic-user header.
+ * @param isBasedOnIpAndUriPath Whether requests are aggregated by IP address and URI path.
+ * @param path Optional URI path pattern that limits which requests are included.
+ * @param excludedPath Optional URI path pattern that is explicitly excluded from the statement.
+ */
+function createThrottleStatement(limit, isHeaderRequired, isBasedOnIpAndUriPath, path, excludedPath) {
+    // Matches requests with a non-empty digitraffic-user header. For anonymous
+    // requests, the inverted statement matches requests without the header.
     const matchStatement = {
         sizeConstraintStatement: {
             comparisonOperator: isHeaderRequired ? "GT" : "GE",
@@ -324,6 +353,25 @@ function createThrottleStatement(limit, isHeaderRequired, isBasedOnIpAndUriPath,
             },
         };
     }
+    if (excludedPath) {
+        const excludedPathMatchStatement = {
+            regexMatchStatement: {
+                fieldToMatch: {
+                    uriPath: {},
+                },
+                regexString: excludedPath.source,
+                textTransformations: [{ priority: 0, type: "NONE" }],
+            },
+        };
+        scopeDownStatement = {
+            andStatement: {
+                statements: [
+                    scopeDownStatement,
+                    notStatement(excludedPathMatchStatement),
+                ],
+            },
+        };
+    }
     if (isBasedOnIpAndUriPath) {
         return {
             rateBasedStatement: {

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

@@ -1,6 +1,5 @@
 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";
@@ -66,10 +65,10 @@ export class DatabaseCountChecker {
         synthetics.getConfiguration().withFailedCanaryMetric(true);
     }
     static createForProxy() {
-        return new DatabaseCountChecker(() => new ProxyHolder(getEnvVariable("SECRET_ID")).setCredentials());
+        return new DatabaseCountChecker(() => ProxyHolder.create().setCredentials());
     }
     static createForRds() {
-        return new DatabaseCountChecker(() => new RdsHolder(getEnvVariable("SECRET_ID")).setCredentials());
+        return new DatabaseCountChecker(() => RdsHolder.create().setCredentials());
     }
     /**
      * Expect that the count is 1

package/dist/aws/infra/stack/dt-function.d.ts

@@ -1,4 +1,4 @@
-import type { Stack } from "aws-cdk-lib";
+import type { Size, Stack } from "aws-cdk-lib";
 import { Duration } from "aws-cdk-lib";
 import type { ISecurityGroup } from "aws-cdk-lib/aws-ec2";
 import type { IRole } from "aws-cdk-lib/aws-iam";
@@ -21,6 +21,7 @@ export declare class FunctionBuilder {
     private functionName;
     private environment;
     private vpc?;
+    private storageSize?;
     private alarms;
     private code;
     private handler;
@@ -28,7 +29,6 @@ export declare class FunctionBuilder {
     private readonly securityGroups;
     private readonly policyStatements;
     private readonly allowedActions;
-    private _adotTracing;
     private readonly _features;
     constructor(stack: Stack & DigitrafficStackInterface, lambdaName: string);
     /**
@@ -41,9 +41,19 @@ export declare class FunctionBuilder {
      */
     static plain(stack: Stack & DigitrafficStackInterface, lambdaName: string): FunctionBuilder;
     /**
-     * Use AssetCode from given path(dist/lambda/${path}).  Default path is lambdaName. Also calls withHandler with the same value.
-     */
-    withAssetCode(path?: string): this;
+     * Sets the Lambda deployment package to the directory `dist/lambda/${path}` and configures
+     * the handler to `basename(path).handler`.
+     * @param path - subdirectory under `dist/lambda/` that contains the compiled Lambda code.
+     *   The handler module name is derived from `basename(path)` (e.g. `"locations.handler"`).
+     *   Defaults to `lambdaName`.
+     *   Example: `"dump/locations"` → asset dir `dist/lambda/dump/locations/`, handler `locations.handler`.
+     * @param exclude - optional glob patterns to exclude from the asset bundle.
+     *   Patterns are relative to the asset root (`dist/lambda/${path}/`) — do NOT use a leading slash.
+     *   Use `**` to match files recursively.
+     *   Example: `["datex2-36", "datex2-37", "statuses"]` excludes sibling lambda subdirectories
+     *   that would otherwise be bundled into this lambda's deployment package.
+     */
+    withAssetCode(path?: string, exclude?: string[]): this;
     withCode(code: Code): this;
     /**
      * Use given handler(${name}.handler) to run the lambda.  Default value is lambdaName.
@@ -74,15 +84,13 @@ export declare class FunctionBuilder {
      */
     withRuntime(runtime: Runtime): this;
     /**
-     * Add Lambda layers.
+     * Set storage size for the lambda.  Defaults to AWS default (512MB).
      */
-    withLayers(...layers: ILayerVersion[]): this;
+    withStorageSize(storageSize: Size): this;
     /**
-     * Enable ADOT (AWS Distro for OpenTelemetry) tracing for this Lambda.
-     * Adds the ADOT Lambda layer, enables X-Ray active tracing,
-     * sets required environment variables, and attaches IAM permissions.
+     * Add Lambda layers.
      */
-    withAdotTracing(): this;
+    withLayers(...layers: ILayerVersion[]): this;
     /**
      * Set architecture for the lambda.  Default is Architecture.ARM_64.
      */
@@ -121,7 +129,6 @@ export declare class FunctionBuilder {
     build(): AwsFunction;
     private attachPolicies;
     private validateNoWildcardActions;
-    private getLayers;
     private getEnvironment;
     private createAlarms;
     private createAlarm;