@bifravst/http-api-mock 3.0.2 → 3.0.4

package/npm/cdk/App.ts

@@ -0,0 +1,26 @@
+import type { PackedLambda } from '@bifravst/aws-cdk-lambda-helpers'
+import type { PackedLayer } from '@bifravst/aws-cdk-lambda-helpers/layer'
+import { App } from 'aws-cdk-lib'
+import { HTTPAPIMockStack } from './Stack.ts'
+
+export class HTTPAPIMockApp extends App {
+	public constructor(
+		stackName: string,
+		{
+			lambdaSources,
+			layer,
+		}: {
+			lambdaSources: {
+				httpApiMock: PackedLambda
+			}
+			layer: PackedLayer
+		},
+	) {
+		super({
+			context: {
+				isTest: true,
+			},
+		})
+		new HTTPAPIMockStack(this, stackName, { lambdaSources, layer })
+	}
+}

package/npm/cdk/Stack.ts

@@ -0,0 +1,66 @@
+import type { PackedLambda } from '@bifravst/aws-cdk-lambda-helpers'
+import { LambdaSource } from '@bifravst/aws-cdk-lambda-helpers/cdk'
+import type { PackedLayer } from '@bifravst/aws-cdk-lambda-helpers/layer'
+import type { App } from 'aws-cdk-lib'
+import { CfnOutput, aws_lambda as Lambda, Stack } from 'aws-cdk-lib'
+import { HttpApiMock } from './resources/HttpApiMock.ts'
+
+/**
+ * This is CloudFormation stack sets up a dummy HTTP API which stores all requests in SQS for inspection
+ */
+export class HTTPAPIMockStack extends Stack {
+	public constructor(
+		parent: App,
+		stackName: string,
+		{
+			lambdaSources,
+			layer,
+		}: {
+			lambdaSources: {
+				httpApiMock: PackedLambda
+			}
+			layer: PackedLayer
+		},
+	) {
+		super(parent, stackName, {
+			description:
+				'Provides a mock HTTP API for testing third-party API integrations.',
+		})
+
+		const baseLayer = new Lambda.LayerVersion(this, 'baseLayer', {
+			layerVersionName: `${Stack.of(this).stackName}-baseLayer`,
+			code: new LambdaSource(this, {
+				id: 'baseLayer',
+				zipFilePath: layer.layerZipFilePath,
+				hash: layer.hash,
+			}).code,
+			compatibleArchitectures: [Lambda.Architecture.ARM_64],
+			compatibleRuntimes: [Lambda.Runtime.NODEJS_24_X],
+		})
+
+		const httpMockApi = new HttpApiMock(this, {
+			lambdaSources,
+			layers: [baseLayer],
+		})
+
+		// Export these so the test runner can use them
+		new CfnOutput(this, 'apiURL', {
+			value: httpMockApi.api.url,
+			exportName: `${this.stackName}:apiURL`,
+		})
+		new CfnOutput(this, 'responsesTableName', {
+			value: httpMockApi.responsesTable.tableName,
+			exportName: `${this.stackName}:responsesTableName`,
+		})
+		new CfnOutput(this, 'requestsTableName', {
+			value: httpMockApi.requestsTable.tableName,
+			exportName: `${this.stackName}:requestsTableName`,
+		})
+	}
+}
+
+export type StackOutputs = {
+	apiURL: string
+	requestsTableName: string
+	responsesTableName: string
+}

package/npm/cdk/http-api-mock.ts

@@ -0,0 +1,109 @@
+import { Toolkit } from '@aws-cdk/toolkit-lib'
+import { CloudFormationClient } from '@aws-sdk/client-cloudformation'
+import { packLambdaFromPath } from '@bifravst/aws-cdk-lambda-helpers'
+import { packLayer } from '@bifravst/aws-cdk-lambda-helpers/layer'
+import { stackOutput } from '@bifravst/cloudformation-helpers'
+import commandLineArgs from 'command-line-args'
+import { writeFileSync } from 'node:fs'
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import pJSON from '../package.json' with { type: 'json' }
+import { randomString } from '../src/randomString.ts'
+import { HTTPAPIMockApp } from './App.ts'
+import type { StackOutputs } from './Stack.ts'
+
+const options = commandLineArgs([
+	{
+		name: 'config',
+		type: Boolean,
+		defaultValue: false,
+	},
+	{
+		name: 'destroy',
+		type: Boolean,
+		defaultValue: false,
+	},
+])
+
+const loadConfig = async (): Promise<
+	Partial<StackOutputs & { stackName: string }>
+> => {
+	try {
+		const config = JSON.parse(
+			await fs.readFile(
+				path.join(process.cwd(), 'http-api-mock.json'),
+				'utf-8',
+			),
+		)
+		return config
+	} catch {
+		return {}
+	}
+}
+
+const stackName =
+	process.env.HTTP_API_MOCK_STACK_NAME ??
+	(await loadConfig())?.stackName ??
+	`http-api-mock-${randomString()}`
+
+const saveConfig = async () => {
+	writeFileSync(
+		path.join(process.cwd(), 'http-api-mock.json'),
+		JSON.stringify(
+			{
+				stackName,
+				...(await stackOutput(new CloudFormationClient({}))<StackOutputs>(
+					stackName,
+				)),
+			},
+			null,
+			2,
+		),
+	)
+}
+
+if (options.config === true) {
+	await saveConfig()
+	process.exit(0)
+}
+
+const baseDir = path.join(path.dirname(fileURLToPath(import.meta.url)), '..')
+const distDir = await fs.mkdtemp(path.join(os.tmpdir(), 'temp-'))
+const lambdasDir = path.join(distDir, 'lambdas')
+await fs.mkdir(lambdasDir)
+const layersDir = path.join(distDir, 'layers')
+await fs.mkdir(layersDir)
+
+const dependencies: Array<keyof (typeof pJSON)['dependencies']> = [
+	'@bifravst/from-env',
+]
+
+const app = new HTTPAPIMockApp(stackName, {
+	lambdaSources: {
+		httpApiMock: await packLambdaFromPath({
+			id: 'httpApiMock',
+			sourceFilePath: 'cdk/resources/http-api-mock-lambda.ts',
+			baseDir,
+			distDir: lambdasDir,
+		}),
+	},
+	layer: await packLayer({
+		id: 'testResources',
+		dependencies,
+		baseDir,
+		distDir: layersDir,
+	}),
+})
+
+const cdk = new Toolkit()
+
+const cx = await cdk.fromAssemblyBuilder(async () => app.synth())
+
+if (options.destroy === true) {
+	await cdk.destroy(cx)
+} else {
+	await cdk.deploy(cx)
+	await saveConfig()
+}

package/npm/cdk/resources/HttpApiMock.ts

@@ -0,0 +1,117 @@
+import type { PackedLambda } from '@bifravst/aws-cdk-lambda-helpers'
+import {
+	LambdaLogGroup,
+	LambdaSource,
+} from '@bifravst/aws-cdk-lambda-helpers/cdk'
+import {
+	aws_apigateway as ApiGateway,
+	Duration,
+	aws_dynamodb as DynamoDB,
+	aws_iam as IAM,
+	aws_lambda as Lambda,
+	aws_logs as Logs,
+	RemovalPolicy,
+	Resource,
+} from 'aws-cdk-lib'
+import type { Construct } from 'constructs'
+
+export class HttpApiMock extends Resource {
+	public readonly api: ApiGateway.RestApi
+	public readonly requestsTable: DynamoDB.Table
+	public readonly responsesTable: DynamoDB.Table
+
+	public constructor(
+		parent: Construct,
+		{
+			lambdaSources,
+			layers,
+		}: {
+			lambdaSources: {
+				httpApiMock: PackedLambda
+			}
+			layers: Lambda.ILayerVersion[]
+		},
+	) {
+		super(parent, 'http-api-mock')
+
+		// This table will store all the requests made to the API Gateway
+		this.requestsTable = new DynamoDB.Table(this, 'requests', {
+			billingMode: DynamoDB.BillingMode.PAY_PER_REQUEST,
+			partitionKey: {
+				name: 'requestId',
+				type: DynamoDB.AttributeType.STRING,
+			},
+			sortKey: {
+				name: 'timestamp',
+				type: DynamoDB.AttributeType.STRING,
+			},
+			removalPolicy: RemovalPolicy.DESTROY,
+		})
+		this.requestsTable.addGlobalSecondaryIndex({
+			indexName: 'methodPathQuery',
+			partitionKey: {
+				name: 'methodPathQuery',
+				type: DynamoDB.AttributeType.STRING,
+			},
+			projectionType: DynamoDB.ProjectionType.ALL,
+		})
+
+		// This table will store optional responses to be sent
+		this.responsesTable = new DynamoDB.Table(this, 'responses', {
+			billingMode: DynamoDB.BillingMode.PAY_PER_REQUEST,
+			partitionKey: {
+				name: 'responseId',
+				type: DynamoDB.AttributeType.STRING,
+			},
+			sortKey: {
+				name: 'timestamp',
+				type: DynamoDB.AttributeType.STRING,
+			},
+			removalPolicy: RemovalPolicy.DESTROY,
+			timeToLiveAttribute: 'ttl',
+		})
+		this.responsesTable.addGlobalSecondaryIndex({
+			indexName: 'methodPathQuery',
+			partitionKey: {
+				name: 'methodPathQuery',
+				type: DynamoDB.AttributeType.STRING,
+			},
+			projectionType: DynamoDB.ProjectionType.ALL,
+		})
+
+		// This lambda will publish all requests made to the API Gateway in the queue
+		const lambda = new Lambda.Function(this, 'Lambda', {
+			description:
+				'Mocks a HTTP API and stores all requests in SQS for inspection, and optionally replies with enqued responses',
+			code: new LambdaSource(this, lambdaSources.httpApiMock).code,
+			layers,
+			handler: lambdaSources.httpApiMock.handler,
+			architecture: Lambda.Architecture.ARM_64,
+			runtime: Lambda.Runtime.NODEJS_24_X,
+			timeout: Duration.seconds(5),
+			environment: {
+				REQUESTS_TABLE_NAME: this.requestsTable.tableName,
+				RESPONSES_TABLE_NAME: this.responsesTable.tableName,
+				LOG_LEVEL: this.node.tryGetContext('logLevel'),
+				NODE_NO_WARNINGS: '1',
+			},
+			...new LambdaLogGroup(this, 'LambdaLogs', Logs.RetentionDays.ONE_DAY),
+		})
+		this.responsesTable.grantReadWriteData(lambda)
+		this.requestsTable.grantReadWriteData(lambda)
+
+		// This is the API Gateway, AWS CDK automatically creates a prod stage and deployment
+		this.api = new ApiGateway.RestApi(this, 'api', {
+			restApiName: `HTTP Mock API for testing`,
+			description: 'API Gateway to test outgoing requests',
+			binaryMediaTypes: ['application/octet-stream'],
+		})
+		const proxyResource = this.api.root.addResource('{proxy+}')
+		proxyResource.addMethod('ANY', new ApiGateway.LambdaIntegration(lambda))
+		// API Gateway needs to be able to call the lambda
+		lambda.addPermission('InvokeByApiGateway', {
+			principal: new IAM.ServicePrincipal('apigateway.amazonaws.com'),
+			sourceArn: this.api.arnForExecuteApi(),
+		})
+	}
+}

package/npm/cdk/resources/checkMatchingQueryParams.spec.ts

@@ -0,0 +1,67 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+import { checkMatchingQueryParams } from './checkMatchingQueryParams.ts'
+
+void describe('checkMatchingQueryParams', () => {
+	void it('should return true when expected is subset of actual parameters', () => {
+		const actual = {
+			param1: 'value1',
+			param2: 'value2',
+		}
+		const expected = {
+			param1: 'value1',
+		}
+
+		const result = checkMatchingQueryParams(actual, expected)
+		assert.equal(result, true)
+	})
+
+	void it('should return true when expected contains regular expression and it matches', () => {
+		const actual = {
+			param1: 'value1,value2,value3',
+		}
+		const expected = {
+			param1: '/\\bvalue2\\b/',
+		}
+
+		const result = checkMatchingQueryParams(actual, expected)
+		assert.equal(result, true)
+	})
+
+	void it('should return false when expected does not match actual parameters', () => {
+		const actual = {
+			param1: 'value1',
+			param2: 'value2',
+		}
+		const expected = {
+			param1: 'value2',
+		}
+
+		const result = checkMatchingQueryParams(actual, expected)
+		assert.equal(result, false)
+	})
+
+	void it('should return false when actual is null', () => {
+		const actual = null
+		const expected = {
+			param1: 'value1',
+		}
+
+		const result = checkMatchingQueryParams(actual, expected)
+		assert.equal(result, false)
+	})
+
+	void it('should return true when expected parameters having number or boolean', () => {
+		const actual = {
+			param1: 'true',
+			param2: '1',
+		}
+		const expected = {
+			param1: true,
+			param2: 1,
+		}
+
+		const result = checkMatchingQueryParams(actual, expected)
+		assert.equal(result, true)
+	})
+})

package/npm/cdk/resources/checkMatchingQueryParams.ts

@@ -0,0 +1,40 @@
+type Logger = {
+	debug: (...arg: any) => void
+}
+const matchRegex = /^\/(?<re>.+)\/(?<option>[gi])?$/
+
+export const checkMatchingQueryParams = (
+	actual: Record<string, unknown> | null,
+	expected: Record<string, unknown>,
+	log?: Logger,
+): boolean => {
+	log?.debug('checkMatchingQueryParams', { actual, expected })
+	if (actual === null) return false
+
+	// Check whether expected query parameters is subset of actual query parameters
+	for (const prop in expected) {
+		const expectedValue = expected[prop]
+		const actualValue = actual?.[prop]
+		if (actualValue === undefined) return false
+
+		if (typeof expectedValue === 'string') {
+			const match = matchRegex.exec(expectedValue)
+			if (match !== null) {
+				log?.debug('Compare using regex', { expectedValue })
+				// Expect is regex
+				const check = new RegExp(
+					match?.groups?.re ?? '',
+					match?.groups?.option,
+				).test(String(actualValue))
+				if (check === false) return false
+			} else {
+				if (actualValue !== expectedValue) return false
+			}
+		} else {
+			// All query parameters are string
+			if (actualValue !== String(expectedValue)) return false
+		}
+	}
+
+	return true
+}

package/npm/cdk/resources/http-api-mock-lambda.ts

@@ -0,0 +1,147 @@
+import {
+	DeleteItemCommand,
+	DynamoDBClient,
+	PutItemCommand,
+	ScanCommand,
+} from '@aws-sdk/client-dynamodb'
+import { marshall, unmarshall } from '@aws-sdk/util-dynamodb'
+import type {
+	APIGatewayEvent,
+	APIGatewayProxyResult,
+	Context,
+} from 'aws-lambda'
+import { URLSearchParams } from 'url'
+import { sortQueryString } from '../../src/sortQueryString.ts'
+import { checkMatchingQueryParams } from './checkMatchingQueryParams.ts'
+import { splitMockResponse } from './splitMockResponse.ts'
+
+const db = new DynamoDBClient({})
+
+export const handler = async (
+	event: APIGatewayEvent,
+	context: Context,
+): Promise<APIGatewayProxyResult> => {
+	console.log(JSON.stringify({ event }))
+	const query =
+		event.queryStringParameters !== null &&
+		event.queryStringParameters !== undefined
+			? new URLSearchParams(
+					event.queryStringParameters as Record<string, string>,
+				)
+			: undefined
+	const path = event.path.replace(/^\//, '')
+	const pathWithQuery = sortQueryString(
+		`${path}${query !== undefined ? `?${query.toString()}` : ''}`,
+	)
+
+	const request = {
+		methodPathQuery: `${event.httpMethod} ${pathWithQuery}`,
+		timestamp: new Date().toISOString(),
+		requestId: context.awsRequestId,
+		method: event.httpMethod,
+		path,
+		query: query === undefined ? null : Object.fromEntries(query),
+		body: event.body ?? '{}',
+		headers: JSON.stringify(event.headers),
+	}
+
+	// Check if response exists
+	console.debug(
+		`Checking if response exists for ${event.httpMethod} ${pathWithQuery}...`,
+	)
+	// Scan using httpMethod and path only so query strings can be partially matched
+	const { Items } = await db.send(
+		new ScanCommand({
+			TableName: process.env.RESPONSES_TABLE_NAME,
+			FilterExpression: 'begins_with(methodPathQuery, :methodPath)',
+			ExpressionAttributeValues: {
+				[':methodPath']: {
+					S: `${event.httpMethod} ${path}`,
+				},
+			},
+		}),
+	)
+	console.debug(
+		`Found response items beginning with same path: ${Items?.length}`,
+	)
+	// use newest response first
+	const itemsByTimestampDesc = (Items ?? [])
+		.map((Item) => unmarshall(Item))
+		.sort((a, b) => b.timestamp.localeCompare(a.timestamp))
+
+	let res: APIGatewayProxyResult = {
+		statusCode: 404,
+		body: 'No responses found',
+	}
+	for (const objItem of itemsByTimestampDesc) {
+		const hasExpectedQueryParams =
+			'queryParams' in objItem || query !== undefined
+		const matchedQueryParams = hasExpectedQueryParams
+			? checkMatchingQueryParams(
+					event.queryStringParameters,
+					objItem.queryParams,
+				)
+			: true
+		if (matchedQueryParams === false) continue
+
+		console.debug(`Matched response`, JSON.stringify({ response: objItem }))
+
+		if (
+			objItem?.requestId !== undefined &&
+			objItem?.timestamp !== undefined &&
+			objItem?.keep !== true
+		) {
+			await db.send(
+				new DeleteItemCommand({
+					TableName: process.env.RESPONSES_TABLE_NAME,
+					Key: marshall({
+						requestId: objItem.requestId,
+						timestamp: objItem.timestamp,
+					}),
+				}),
+			)
+		}
+
+		const { body, headers } = splitMockResponse(objItem.body ?? '')
+
+		// Send as binary, if mock response is HEX encoded. See https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-payload-encodings.html
+		const isBinary = /^[0-9a-f]+$/.test(body)
+		res = {
+			statusCode: objItem.statusCode ?? 200,
+			headers: isBinary
+				? {
+						...headers,
+						'Content-Type': 'application/octet-stream',
+					}
+				: headers,
+			body: isBinary
+				? /* body is HEX encoded */ Buffer.from(body, 'hex').toString('base64')
+				: body,
+			isBase64Encoded: isBinary,
+		}
+
+		break
+	}
+
+	console.debug(`Return response`, JSON.stringify({ response: res }))
+
+	await db.send(
+		new PutItemCommand({
+			TableName: process.env.REQUESTS_TABLE_NAME,
+			Item: marshall(
+				{
+					...request,
+					responseStatusCode: res.statusCode,
+					responseHeaders: res.headers,
+					responseBody: res.body,
+					responseIsBase64Encoded: res.isBase64Encoded,
+				},
+				{
+					removeUndefinedValues: true,
+				},
+			),
+		}),
+	)
+
+	return res
+}

package/npm/cdk/resources/splitMockResponse.spec.ts

@@ -0,0 +1,17 @@
+import assert from 'node:assert'
+import { describe, it } from 'node:test'
+import { splitMockResponse } from './splitMockResponse.ts'
+void describe('split mock response', () => {
+	void it('should parse headers and body', () =>
+		assert.deepEqual(
+			splitMockResponse(`Content-Type: application/octet-stream
+
+(binary A-GNSS data) other types`),
+			{
+				headers: {
+					'Content-Type': 'application/octet-stream',
+				},
+				body: '(binary A-GNSS data) other types',
+			},
+		))
+})

package/npm/cdk/resources/splitMockResponse.ts

@@ -0,0 +1,25 @@
+export const splitMockResponse = (
+	r: string,
+): { headers: Record<string, string>; body: string } => {
+	const trimmedLines = r
+		.split('\n')
+		.map((s) => s.trim())
+		.join('\n')
+	const blankLineLocation = trimmedLines.indexOf('\n\n')
+	if (blankLineLocation === -1)
+		return {
+			headers: {},
+			body: trimmedLines,
+		}
+	return {
+		headers: trimmedLines
+			.slice(0, blankLineLocation)
+			.split('\n')
+			.map((s) => s.split(':', 2))
+			.reduce(
+				(headers, [k, v]) => ({ ...headers, [k as string]: v?.trim() }),
+				{},
+			),
+		body: trimmedLines.slice(blankLineLocation + 2),
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bifravst/http-api-mock",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "Helper functions for AWS lambdas written in TypeScript.",
   "exports": {
     "./*": {
@@ -13,7 +13,7 @@
   "type": "module",
   "scripts": {
     "prepare": "husky && case \"$npm_command\" in install|ci) check-node-version --package ;; esac",
-    "prepublishOnly": "node --no-warnings --experimental-transform-types  ./.npm/compile.ts",
+    "prepublishOnly": "node --no-warnings --experimental-transform-types  ./.npm/compile.ts && cp -rv cdk/* npm/cdk",
     "test": "node --no-warnings --experimental-transform-types --test \"!(node_modules|e2e-tests|integration-tests)/**/*.spec.ts\""
   },
   "repository": {
@@ -77,6 +77,7 @@
     "@aws-sdk/client-cloudformation": "3.1111.0",
     "@aws-sdk/client-dynamodb": "3.1111.0",
     "@aws-sdk/client-sts": "3.1111.0",
+    "@aws-cdk/toolkit-lib": "1.38.2",
     "@aws-sdk/util-dynamodb": "3.996.9",
     "@bifravst/aws-cdk-lambda-helpers": "4.0.96",
     "@bifravst/cloudformation-helpers": "9.1.1",
@@ -84,10 +85,10 @@
     "@bifravst/run": "1.2.0",
     "aws-cdk-lib": "2.265.0",
     "cdk": "2.1136.0",
-    "chalk": "6.0.0"
+    "chalk": "6.0.0",
+    "command-line-args": "6.0.2"
   },
   "devDependencies": {
-    "@aws-cdk/toolkit-lib": "1.38.2",
     "@bifravst/eslint-config-typescript": "7.0.34",
     "@bifravst/prettier-config": "1.1.17",
     "@commitlint/config-conventional": "21.2.2",
@@ -96,7 +97,6 @@
     "@types/node": "26.2.0",
     "@typescript/native": "npm:typescript@7.0.2",
     "check-node-version": "4.2.1",
-    "command-line-args": "6.0.2",
     "commitlint": "21.2.2",
     "husky": "9.1.7",
     "lint-staged": "17.3.0",