feat(apigatewayv2-integrations): http api - support for request parameter mapping

packages/@aws-cdk/aws-apigatewayv2-integrations/README.md

@@ -21,6 +21,7 @@
   - [Lambda Integration](#lambda)
   - [HTTP Proxy Integration](#http-proxy)
   - [Private Integration](#private-integration)
+  - [Request Parameters](#request-parameters)
 - [WebSocket APIs](#websocket-apis)
   - [Lambda WebSocket Integration](#lambda-websocket-integration)
 
@@ -149,6 +150,52 @@ const httpEndpoint = new HttpApi(stack, 'HttpProxyPrivateApi', {
 });
 ```
 
+### Request Parameters
+
+Request parameter mapping allows API requests from clients to be modified before they reach backend integrations.
+To use parameter mapping, you specify API request parameters to modify, and specify how to modify the parameters. 
+
+Request parameter mapping is supported through a set of helper methods.
+The following example renames a request header from header1 to header2 by generating mappings
+`append:header.header2: $request.header.header1` and `remove:header.header1: ''`:
+
+```ts
+const vpc = new ec2.Vpc(stack, 'VPC');
+const lb = new elbv2.ALB(stack, 'lb', { vpc });
+const listener = lb.addListener('listener', { port: 80 });
+listener.addTargets('target', {
+  port: 80,
+});
+
+const httpEndpoint = new HttpApi(stack, 'HttpProxyPrivateApi', {
+  defaultIntegration: new HttpAlbIntegration({
+    listener,
+    requestParameters: new ParameterMapping()
+      .appendHeader('header2', MappingValue.header('header1'))
+      .removeHeader('header1');
+    }),
+  }),
+});
+```
+
+
+
+To use values which does not yet have any helper functions, you can use the custom methods:
+
+```ts
+const httpEndpoint = new HttpApi(stack, 'HttpProxyPrivateApi', {
+  defaultIntegration: new HttpAlbIntegration({
+    listener,
+    requestParameters: new RequestParameters()
+      .addParameter({
+        mappingKey: MappingKey.custom('new.header'),
+        mappingValue: MappingValue.custom('new.value'),
+    }),
+  }),
+});
+```
+
+
 ## WebSocket APIs
 
 WebSocket integrations connect a route to backend resources. The following integrations are supported in the CDK.

packages/@aws-cdk/aws-apigatewayv2/lib/http/api.ts

@@ -305,6 +305,7 @@ abstract class HttpApiBase extends ApiBase implements IHttpApi { // note that th
       connectionType: config.connectionType,
       payloadFormatVersion: config.payloadFormatVersion,
       secureServerName: config.secureServerName,
+      parameterMapping: config.parameterMapping,
     });
     this._integrationCache.saveIntegration(scope, config, integration);
 

packages/@aws-cdk/aws-apigatewayv2/lib/http/integration.ts

@@ -74,6 +74,68 @@ export class PayloadFormatVersion {
   }
 }
 
+export interface IMappingValue {
+  readonly value: string;
+};
+
+export class MappingValue implements IMappingValue {
+  public static readonly NONE = new MappingValue('');
+  public static requestHeader(name: string) { return new MappingValue(`$request.header.${name}`); }
+  public static requestQueryString(name: string) { return new MappingValue(`$request.querystring.${name}`); }
+  public static requestBody(name: string) { return new MappingValue(`$request.body.${name}`); }
+  public static requestPathFull() {return new MappingValue('$request.path'); }
+  public static requestPath(name: string) { return new MappingValue(`$request.path.${name}`); }
+  public static contextVariable(variableName: string) { return new MappingValue(`$context.${variableName}`); }
+  public static stageVariablesVariable(variableName: string) { return new MappingValue(`$stageVariables.${variableName}`); }
+  public static custom(value: string) {return new MappingValue(value); }
+  protected constructor(public readonly value: string) {}
+}
+
+export class ParameterMapping {
+  public readonly mappings: {[key: string]: string}
+  constructor() {
+    this.mappings = {};
+  }
+
+  public appendHeader(name: string, value: MappingValue): ParameterMapping {
+    this.mappings[`append:header.${name}`] = value.value;
+    return this;
+  }
+
+  public overwriteHeader(name: string, value: MappingValue): ParameterMapping {
+    this.mappings[`overwrite:header.${name}`] = value.value;
+    return this;
+  }
+
+  public removeHeader(name: string): ParameterMapping {
+    this.mappings[`remove:header.${name}`] = '';
+    return this;
+  }
+
+  public appendQueryString(name: string, value: MappingValue): ParameterMapping {
+    this.mappings[`append:querystring.${name}`] = value.value;
+    return this;
+  }
+  public overwriteQueryString(name: string, value: MappingValue): ParameterMapping {
+    this.mappings[`overwrite:querystring.${name}`] = value.value;
+    return this;
+  }
+  public removeQueryString(name: string): ParameterMapping {
+    this.mappings[`remove:querystring.${name}`] = '';
+    return this;
+  }
+
+  public overwritePath(value: MappingValue): ParameterMapping {
+    this.mappings['overwrite:path'] = value.value;
+    return this;
+  }
+
+  public custom(key: string, value:string): ParameterMapping {
+    this.mappings[key] = value;
+    return this;
+  }
+}
+
 /**
  * The integration properties
  */
@@ -128,6 +190,8 @@ export interface HttpIntegrationProps {
    * @default undefined private integration traffic will use HTTP protocol
    */
   readonly secureServerName?: string;
+
+  readonly parameterMapping?: ParameterMapping;
 }
 
 /**
@@ -149,6 +213,7 @@ export class HttpIntegration extends Resource implements IHttpIntegration {
       connectionId: props.connectionId,
       connectionType: props.connectionType,
       payloadFormatVersion: props.payloadFormatVersion?.version,
+      requestParameters: props.parameterMapping?.mappings,
     });
 
     if (props.secureServerName) {
@@ -237,4 +302,6 @@ export interface HttpRouteIntegrationConfig {
    * @default undefined private integration traffic will use HTTP protocol
    */
   readonly secureServerName?: string;
+
+  readonly parameterMapping?: ParameterMapping;
 }

packages/@aws-cdk/aws-apigatewayv2/test/http/route.test.ts

@@ -1,8 +1,9 @@
 import { Template } from '@aws-cdk/assertions';
 import { Stack, App } from '@aws-cdk/core';
 import {
-  HttpApi, HttpAuthorizer, HttpAuthorizerType, HttpConnectionType, HttpIntegrationType, HttpMethod, HttpRoute, HttpRouteAuthorizerBindOptions,
-  HttpRouteAuthorizerConfig, HttpRouteIntegrationConfig, HttpRouteKey, IHttpRouteAuthorizer, IHttpRouteIntegration, PayloadFormatVersion,
+  HttpApi, HttpAuthorizer, HttpAuthorizerType, HttpConnectionType, HttpIntegrationType, HttpMethod, HttpRoute,
+  HttpRouteAuthorizerBindOptions, HttpRouteAuthorizerConfig, HttpRouteIntegrationConfig, HttpRouteKey, IHttpRouteAuthorizer, IHttpRouteIntegration,
+  MappingValue, ParameterMapping, PayloadFormatVersion,
 } from '../../lib';
 
 describe('HttpRoute', () => {
@@ -174,6 +175,9 @@ describe('HttpRoute', () => {
           connectionType: HttpConnectionType.VPC_LINK,
           uri: 'some-target-arn',
           secureServerName: 'some-server-name',
+          parameterMapping: new ParameterMapping()
+            .appendHeader('header2', MappingValue.requestHeader('header1'))
+            .removeHeader('header1'),
         };
       }
     }
@@ -201,6 +205,47 @@ describe('HttpRoute', () => {
     Template.fromStack(stack).resourceCountIs('AWS::ApiGatewayV2::VpcLink', 0);
   });
 
+  test('configures private integration correctly when parameter mappings are passed', () => {
+    // GIVEN
+    const stack = new Stack();
+    const httpApi = new HttpApi(stack, 'HttpApi');
+
+    class PrivateIntegration implements IHttpRouteIntegration {
+      public bind(): HttpRouteIntegrationConfig {
+        return {
+          method: HttpMethod.ANY,
+          payloadFormatVersion: PayloadFormatVersion.VERSION_1_0,
+          type: HttpIntegrationType.HTTP_PROXY,
+          uri: 'some-target-arn',
+          parameterMapping: new ParameterMapping()
+            .appendHeader('header2', MappingValue.requestHeader('header1'))
+            .removeHeader('header1'),
+        };
+      }
+    }
+
+    // WHEN
+    new HttpRoute(stack, 'HttpRoute', {
+      httpApi,
+      integration: new PrivateIntegration(),
+      routeKey: HttpRouteKey.with('/books', HttpMethod.GET),
+    });
+
+    // THEN
+    expect(stack).toHaveResource('AWS::ApiGatewayV2::Integration', {
+      IntegrationType: 'HTTP_PROXY',
+      IntegrationMethod: 'ANY',
+      IntegrationUri: 'some-target-arn',
+      PayloadFormatVersion: '1.0',
+      RequestParameters: {
+        'append:header.header2': '$request.header.header1',
+        'remove:header.header1': '',
+      },
+    });
+
+    expect(stack).not.toHaveResource('AWS::ApiGatewayV2::VpcLink');
+  });
+
   test('can create route with an authorizer attached', () => {
     const stack = new Stack();
     const httpApi = new HttpApi(stack, 'HttpApi');