artillery-engine-apigw-fronted-lambda 2.0.0

package/README.md

@@ -0,0 +1,43 @@
+# artillery-engine-apigw-fronted-lambda
+
+A custom artillery engine that provides the capability to run artillery performance tests directly against lambdas that expect to be invoked by API Gateway
+
+Adapted from https://github.com/artilleryio/artillery/blob/main/examples/artillery-engine-example/index.js
+
+## Compatibility
+
+This project is designed to work with [artillery](https://github.com/artilleryio/artillery)@^2.0.0
+
+## Install
+
+Install the plugin:
+
+```bash
+npm install -D artillery-engine-apigw-fronted-lambda
+```
+
+add it to your `config.engines` object in your performance test payload yml file and set the engine for each scenario:
+
+```yml
+config:
+  target: my-stack-name
+  phases:
+    - arrivalCount: 1
+      duration: 1
+  engines:
+    apigw-fronted-lambda: {}
+scenarios:
+  - name: do-something
+    engine: apigw-fronted-lambda
+    flow:
+      - invoke:
+          lambda: my-lambda-name
+          event:
+            pathParameters: ... # object
+            queryStringParameters: ... # object
+            body: ... # Can be an object or a string. If an object is given it is stringified
+          capture:
+            json: $.jsonPath
+            as: variableName
+      - log: 'My variable: {{ variableName }}'
+```

package/build/index.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * THIS CUSTOM ENGINE HAS BEEN ADAPTED FROM https://github.com/artilleryio/artillery/blob/main/examples/artillery-engine-example/index.js
+ * IN ORDER TO PROVIDE THE CAPABILITY TO DIRECTLY INVOKE LAMBDAS
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const async_1 = require("async");
+const int_commons_1 = require("@artilleryio/int-commons");
+const client_lambda_1 = require("@aws-sdk/client-lambda");
+const jsonpath_plus_1 = require("jsonpath-plus");
+const APIGWFrontedLambdaFetcher_1 = require("./lib/APIGWFrontedLambdaFetcher");
+const { template } = int_commons_1.engine_util;
+(function overrideConsoleLog() {
+    const originalLog = console.log;
+    console.log = (...args) => {
+        const output = args.map((arg) => (typeof arg === 'object' ? JSON.stringify(arg) : arg)).join(' ');
+        if (output.includes('_aws')) {
+            process.stdout.write(output); // Write to stdout without adding an extra newline
+        }
+        else {
+            originalLog(...args); // Use the original console.log for everything else
+        }
+    };
+})();
+/**
+ * Simple custom engine that invokes a lambda function when an "invoke"
+ * action is found.
+ */
+class LambdaEngine {
+    // Artillery initializes each engine with the following arguments:
+    //
+    // - script is the entire script object, with .config and .scenarios properties
+    // - ee is an EventEmitter we can use to subscribe to events from Artillery, and
+    //   to report custom metrics
+    // - helpers is a collection of utility functions
+    constructor(script, ee, helpers) {
+        this.script = script;
+        this.ee = ee;
+        this.helpers = helpers;
+        this.target = script.config.target;
+        this.opts = { ...script.config.engines['apigw-fronted-lambda'] };
+        this.fetcher = new APIGWFrontedLambdaFetcher_1.default(new client_lambda_1.LambdaClient({ region: this.opts.region ?? 'ap-southeast-2' }));
+    }
+    // For each scenario in the script using this engine, Artillery calls this function
+    // to create a VU function
+    createScenario(scenarioSpec, ee) {
+        const tasks = scenarioSpec.flow.map((rs) => this.step(rs, ee));
+        return function scenario(initialContext, callback) {
+            ee.emit('started');
+            function vuInit(vuCallback) {
+                // we can run custom VU-specific init code here
+                return vuCallback(null, initialContext);
+            }
+            const steps = [vuInit].concat(tasks);
+            async_1.default.waterfall(steps, (err, context) => {
+                if (err) {
+                    console.error(err);
+                }
+                return callback(err, context);
+            });
+        };
+    }
+    // This is a convenience function where we delegate common actions like loop, log, and think,
+    // and handle actions which are custom for our engine, i.e. the "invoke" action in this case
+    step(rs, ee) {
+        if (rs.loop) {
+            const steps = rs.loop.map((loopStep) => this.step(loopStep, ee));
+            return this.helpers.createLoopWithCount(rs.count || -1, steps, { overValues: rs.over });
+        }
+        if (rs.log) {
+            return (context, callback) => {
+                console.log(template(rs.log, context));
+                return process.nextTick(() => {
+                    callback(null, context);
+                });
+            };
+        }
+        if (rs.think) {
+            return this.helpers.createThink(rs, this.script.config.defaults?.think || {});
+        }
+        if (rs.function) {
+            return (context, callback) => {
+                const func = this.script.config.processor[rs.function];
+                if (!func) {
+                    return process.nextTick(() => {
+                        callback(null, context);
+                    });
+                }
+                return func(context, ee, () => callback(null, context));
+            };
+        }
+        if (rs.invoke) {
+            const { lambda, event, capture } = rs.invoke;
+            const fullLambdaName = `${this.target}-${lambda}`;
+            const eventBody = typeof event.body === 'object' ? JSON.stringify(event.body) : event.body;
+            return (context, callback) => {
+                // Resolve each of the path parameters and query string parameters
+                const pathParametersResolved = Object.keys(event.pathParameters || {}).reduce((acc, key) => {
+                    acc[key] = template(event.pathParameters[key], context);
+                    return acc;
+                }, {});
+                const queryStringParametersResolved = Object.keys(event.queryStringParameters || {}).reduce((acc, key) => {
+                    acc[key] = template(event.queryStringParameters[key], context);
+                    return acc;
+                }, {});
+                this.fetcher
+                    .fetch({
+                    lambdaName: fullLambdaName,
+                    pathParameters: pathParametersResolved,
+                    queryStringParameters: queryStringParametersResolved,
+                    body: eventBody,
+                })
+                    .then((response) => {
+                    // Capture the response body into a context variable if needed
+                    if (capture && capture.json && capture.as) {
+                        try {
+                            const [extractedValue] = (0, jsonpath_plus_1.JSONPath)({ path: capture.json, json: response.data });
+                            if (extractedValue) {
+                                context.vars[capture.as] = extractedValue;
+                            }
+                            else {
+                                console.warn(`No value found for JSONPath: ${capture.json}`);
+                            }
+                        }
+                        catch (err) {
+                            console.error('Error processing JSONPath:', err);
+                        }
+                    }
+                })
+                    .catch((err) => {
+                    console.error('Error fetching lambda:', err);
+                })
+                    .finally(() => {
+                    ee.emit('counter', 'lambda.invocation_count', 1);
+                    return callback(null, context);
+                });
+            };
+        }
+        //
+        // Ignore any unrecognized actions:
+        //
+        return function doNothing(context, callback) {
+            return callback(null, context);
+        };
+    }
+}
+module.exports = LambdaEngine;

package/build/lib/APIGWFrontedLambdaFetcher.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const client_lambda_1 = require("@aws-sdk/client-lambda");
+const aws_embedded_metrics_1 = require("aws-embedded-metrics");
+/**
+ * Fetches JSON data by invoking a lambda that would ordinarily be invoked via a HTTP/S request through API Gateway.
+ */
+class APIGWFrontedLambdaFetcher {
+    /**
+     * @param lambdaClient An instance of an @aws-sdk/client-lambda client
+     * @param options.reportMetrics Whether to report response codes for the fetcher to the custom metric. Optional. Default is true.
+     */
+    constructor(lambdaClient, options = {}) {
+        this.lambdaClient = lambdaClient;
+        this.reportMetrics = options.reportMetrics ?? true;
+    }
+    /**
+     * Puts a custom metric for the response code of a Lambda function into CloudWatch.
+     * @param lambdaName The name of the Lambda function
+     * @param statusCode The status code of the response
+     */
+    async putResponseCodeMetric(lambdaName, statusCode) {
+        if (!this.reportMetrics) {
+            return;
+        }
+        const metrics = (0, aws_embedded_metrics_1.createMetricsLogger)();
+        metrics.setNamespace('LambdaResponses');
+        metrics.setDimensions({ Lambda: lambdaName });
+        metrics.putMetric(`StatusCode_${statusCode}`, 1, aws_embedded_metrics_1.Unit.Count);
+        await metrics.flush();
+    }
+    /**
+     * The fetcher function that fetches data from the origin lambda.
+     * Data is expected to be returned from the lambda invocation in the format { statusCode: number, body: string }
+     * The `body` is expected to be a JSON string.
+     * @param options.lambdaName The name of the Lambda function to fetch data from
+     * @param options.pathParameters The path parameters to invoke the Lambda function with
+     * @param options.queryStringParameters The query parameters to invoke the Lambda function with
+     * @param options.body The body to invoke the Lambda function with
+     * @returns {FetchResponse<T>} The JSON body and statusCode returned from the Lambda function response
+     */
+    async fetch(options) {
+        const { lambdaName, pathParameters, queryStringParameters, body: eventBody } = options;
+        const event = { pathParameters, queryStringParameters, body: eventBody };
+        const command = new client_lambda_1.InvokeCommand({
+            FunctionName: lambdaName,
+            InvocationType: 'RequestResponse',
+            Payload: JSON.stringify(event),
+        });
+        // Invoke the Lambda function with a single retry
+        const response = await this.lambdaClient.send(command).catch(async (error) => {
+            // Log initial failure to custom metric
+            this.putResponseCodeMetric(lambdaName, 500);
+            // Wait 50ms before retrying
+            await new Promise((resolve) => {
+                setTimeout(resolve, 50);
+            });
+            console.error(`[APIGWFrontedLambdaFetcher] Retrying Lambda invocation (${lambdaName}) after error: ${error}`);
+            // Retry the Lambda invocation
+            return this.lambdaClient.send(command).catch((err) => {
+                // Log final failure to custom metric
+                this.putResponseCodeMetric(lambdaName, 500);
+                throw err;
+            });
+        });
+        if (response.Payload) {
+            let text;
+            // Parse the response
+            try {
+                text = response.Payload.transformToString();
+                const { statusCode, body, headers } = JSON.parse(text);
+                const code = statusCode ?? response.StatusCode;
+                await this.putResponseCodeMetric(lambdaName, code);
+                return {
+                    data: JSON.parse(body),
+                    statusCode: code,
+                    ttl: this.parseCacheControlSeconds(headers?.['Cache-Control']),
+                };
+            }
+            catch (err) {
+                console.debug(`[APIGWFrontedLambdaFetcher] Error transforming lambda payload. Text:\n${text}`);
+                await this.putResponseCodeMetric(lambdaName, response.StatusCode);
+                throw err;
+            }
+        }
+        throw new Error(`[APIGWFrontedLambdaFetcher] No payload returned from Lambda invocation. Response: ${JSON.stringify(response, null, 2)}`);
+    }
+    /**
+     * Generates a cache key for a given Lambda function and its parameters
+     * The order of parameters is not relevant, as they are sorted before serialization.
+     * If the request includes a body, it is NOT included in the cache key. Any request with a body
+     * will cause this function to throw an error and be treated as if it were a cache miss.
+     * @param options.lambdaName The name of the Lambda function
+     * @param options.pathParameters The path parameters to invoke the Lambda function with
+     * @param options.queryStringParameters The query parameters to invoke the Lambda function with
+     * @param options.body If included, causes the function to throw an error
+     * @param options.uncacheable If true, throws an error indicating that the request is uncacheable
+     */
+    generateCacheKey(options) {
+        const { lambdaName, pathParameters, queryStringParameters, body, uncacheable } = options;
+        if (uncacheable) {
+            throw new Error('[APIGWFrontedLambdaFetcher] Uncacheable option is set to true, cannot generate cache key.');
+        }
+        if (body) {
+            throw new Error('[APIGWFrontedLambdaFetcher] Body is not supported in cache keys for Lambda function requests');
+        }
+        // Serialize parameters in a consistent order
+        const pathParamsString = pathParameters
+            ? Object.entries(pathParameters)
+                .sort()
+                .map(([k, v]) => `${k}=${v}`)
+                .join('&')
+            : '';
+        const queryParamsString = queryStringParameters
+            ? Object.entries(queryStringParameters)
+                .sort()
+                .map(([k, v]) => `${k}=${v}`)
+                .join('&')
+            : '';
+        // Build and return the cache key
+        return `${lambdaName}:${pathParamsString}:${queryParamsString}`;
+    }
+    /**
+     * Parses the Cache-Control header to extract the max-age or s-maxage value in seconds.
+     * 0 is returned if no-cache or no-store is present.
+     * If the header is not present or does not contain a valid cache-control directive, null is returned.
+     * @param header The Cache-Control header value
+     */
+    parseCacheControlSeconds(cacheControlHeader) {
+        if (typeof cacheControlHeader !== 'string')
+            return null;
+        // If the header contains 'no-cache' or 'no-store', return 0 to indicate no caching
+        if (cacheControlHeader.includes('no-cache') || cacheControlHeader.includes('no-store')) {
+            return 0;
+        }
+        // Match s-maxage=* first
+        const sMaxAgeMatch = cacheControlHeader.match(/\bs-maxage=(\d+)\b/i);
+        if (sMaxAgeMatch) {
+            return Number.parseInt(sMaxAgeMatch[1], 10);
+        }
+        // If no s-maxage, match max-age=*
+        const maxAgeMatch = cacheControlHeader.match(/\bmax-age=(\d+)\b/i);
+        if (maxAgeMatch) {
+            return Number.parseInt(maxAgeMatch[1], 10);
+        }
+        return null; // No valid cache-control directive found
+    }
+}
+exports.default = APIGWFrontedLambdaFetcher;

package/package.json

@@ -0,0 +1,50 @@
+{
+  "description": "A custom artillery engine to invoke lambdas fronted by API gateway",
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "license": "MIT",
+  "main": "./build/index.js",
+  "name": "artillery-engine-apigw-fronted-lambda",
+  "scripts": {
+    "build": "tsc --outDir build",
+    "lint": "eslint . --ignore-pattern build/",
+    "test": "jest"
+  },
+  "dependencies": {
+    "@aws-sdk/client-lambda": "^3.709.0",
+    "async": "^3.2.6",
+    "aws-embedded-metrics": "^4.2.1",
+    "jsonpath-plus": "^10.4.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.0.1",
+    "@commitlint/config-conventional": "^21.0.1",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^13.1.5",
+    "@types/artillery": "^2.0.194",
+    "@types/async": "^3.2.25",
+    "@types/aws-lambda": "^8.10.161",
+    "@types/debug": "^4.1.13",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.19.19",
+    "aws-sdk-client-mock": "^4.1.0",
+    "aws-sdk-client-mock-jest": "^4.1.0",
+    "bom-eslint-config": "^1.0.1",
+    "commitlint": "^21.0.1",
+    "jest": "^30.4.2",
+    "semantic-release": "^25.0.3",
+    "ts-jest": "^29.4.9",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "artillery": "^2.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "version": "2.0.0"
+}