feat(elbv2): add fixed response support for application load balancers (#2328)

It follows the same pattern as the one used for `addTargetGroups` with the check on `priority`.

This allows for the following scenario: an infrastructure stack exporting an application listener with
a default fixed response and multiple application stacks registering their services with specific
paths/headers on the imported application listener.

Author: jogold

packages/@aws-cdk/aws-elasticloadbalancingv2/README.md

@@ -50,6 +50,17 @@ listener.addTargets('ApplicationFleet', {
 The security groups of the load balancer and the target are automatically
 updated to allow the network traffic.
 
+Use the `addFixedResponse()` method to add fixed response rules on the listener:
+
+```ts
+listener.addFixedResponse('Fixed', {
+    pathPattern: '/ok',
+    contentType: elbv2.ContentType.TEXT_PLAIN,
+    messageBody: 'OK',
+    statusCode: '200'
+});
+```
+
 #### Conditions
 
 It's possible to route traffic to targets based on conditions in the incoming

packages/@aws-cdk/aws-elasticloadbalancingv2/lib/alb/application-listener-rule.ts

@@ -17,10 +17,17 @@ export interface BaseApplicationListenerRuleProps {
   readonly priority: number;
 
   /**
-   * Target groups to forward requests to
+   * Target groups to forward requests to. Only one of `targetGroups` or
+   * `fixedResponse` can be specified.
    */
   readonly targetGroups?: IApplicationTargetGroup[];
 
+  /**
+   * Fixed response to return. Only one of `fixedResponse` or
+   * `targetGroups` can be specified.
+   */
+  readonly fixedResponse?: FixedResponse;
+
   /**
    * Rule applies if the requested host matches the indicated host
    *
@@ -54,6 +61,41 @@ export interface ApplicationListenerRuleProps extends BaseApplicationListenerRul
   readonly listener: IApplicationListener;
 }
 
+/**
+ * The content type for a fixed response
+ */
+export enum ContentType {
+  TEXT_PLAIN = 'text/plain',
+  TEXT_CSS = 'text/css',
+  TEXT_HTML =  'text/html',
+  APPLICATION_JAVASCRIPT = 'application/javascript',
+  APPLICATION_JSON = 'application/json'
+}
+
+/**
+ * A fixed response
+ */
+export interface FixedResponse {
+  /**
+   * The HTTP response code (2XX, 4XX or 5XX)
+   */
+  readonly statusCode: string;
+
+  /**
+   * The content type
+   *
+   * @default text/plain
+   */
+  readonly contentType?: ContentType;
+
+  /**
+   * The message
+   *
+   * @default no message
+   */
+  readonly messageBody?: string;
+}
+
 /**
  * Define a new listener rule
  */
@@ -75,6 +117,10 @@ export class ApplicationListenerRule extends cdk.Construct {
       throw new Error(`At least one of 'hostHeader' or 'pathPattern' is required when defining a load balancing rule.`);
     }
 
+    if (props.targetGroups && props.fixedResponse) {
+      throw new Error('Cannot combine `targetGroups` with `fixedResponse`.');
+    }
+
     this.listener = props.listener;
 
     const resource = new CfnListenerRule(this, 'Resource', {
@@ -93,6 +139,10 @@ export class ApplicationListenerRule extends cdk.Construct {
 
     (props.targetGroups || []).forEach(this.addTargetGroup.bind(this));
 
+    if (props.fixedResponse) {
+      this.addFixedResponse(props.fixedResponse);
+    }
+
     this.listenerRuleArn = resource.ref;
   }
 
@@ -114,6 +164,18 @@ export class ApplicationListenerRule extends cdk.Construct {
     targetGroup.registerListener(this.listener, this);
   }
 
+  /**
+   * Add a fixed response
+   */
+  public addFixedResponse(fixedResponse: FixedResponse) {
+    validateFixedResponse(fixedResponse);
+
+    this.actions.push({
+      fixedResponseConfig: fixedResponse,
+      type: 'fixed-response'
+    });
+  }
+
   /**
    * Validate the rule
    */
@@ -137,3 +199,18 @@ export class ApplicationListenerRule extends cdk.Construct {
     return ret;
   }
 }
+
+/**
+ * Validate the status code and message body of a fixed response
+ *
+ * @internal
+ */
+export function validateFixedResponse(fixedResponse: FixedResponse) {
+  if (fixedResponse.statusCode && !/^(2|4|5)\d\d$/.test(fixedResponse.statusCode)) {
+    throw new Error('`statusCode` must be 2XX, 4XX or 5XX.');
+  }
+
+  if (fixedResponse.messageBody && fixedResponse.messageBody.length > 1024) {
+    throw new Error('`messageBody` cannot have more than 1024 characters.');
+  }
+}

packages/@aws-cdk/aws-elasticloadbalancingv2/lib/alb/application-listener.ts

@@ -5,7 +5,7 @@ import { HealthCheck } from '../shared/base-target-group';
 import { ApplicationProtocol, SslPolicy } from '../shared/enums';
 import { determineProtocolAndPort } from '../shared/util';
 import { ApplicationListenerCertificate } from './application-listener-certificate';
-import { ApplicationListenerRule } from './application-listener-rule';
+import { ApplicationListenerRule, FixedResponse, validateFixedResponse } from './application-listener-rule';
 import { IApplicationLoadBalancer } from './application-load-balancer';
 import { ApplicationTargetGroup, IApplicationLoadBalancerTarget, IApplicationTargetGroup } from './application-target-group';
 
@@ -153,9 +153,7 @@ export class ApplicationListener extends BaseListener implements IApplicationLis
    * At least one TargetGroup must be added without conditions.
    */
   public addTargetGroups(id: string, props: AddApplicationTargetGroupsProps): void {
-    if ((props.hostHeader !== undefined || props.pathPattern !== undefined) !== (props.priority !== undefined)) {
-      throw new Error(`Setting 'pathPattern' or 'hostHeader' also requires 'priority', and vice versa`);
-    }
+    checkAddRuleProps(props);
 
     if (props.priority !== undefined) {
       // New rule
@@ -215,6 +213,35 @@ export class ApplicationListener extends BaseListener implements IApplicationLis
     return group;
   }
 
+  /**
+   * Add a fixed response
+   */
+  public addFixedResponse(id: string, props: AddFixedResponseProps) {
+    checkAddRuleProps(props);
+
+    const fixedResponse: FixedResponse = {
+      statusCode: props.statusCode,
+      contentType: props.contentType,
+      messageBody: props.messageBody
+    };
+
+    validateFixedResponse(fixedResponse);
+
+    if (props.priority) {
+      new ApplicationListenerRule(this, id + 'Rule', {
+        listener: this,
+        priority: props.priority,
+        fixedResponse,
+        ...props
+      });
+    } else {
+      this._addDefaultAction({
+        fixedResponseConfig: fixedResponse,
+        type: 'fixed-response'
+      });
+    }
+  }
+
   /**
    * Register that a connectable that has been added to this load balancer.
    *
@@ -539,3 +566,15 @@ export interface AddApplicationTargetsProps extends AddRuleProps {
    */
   readonly healthCheck?: HealthCheck;
 }
+
+/**
+ * Properties for adding a fixed response to a listener
+ */
+export interface AddFixedResponseProps extends AddRuleProps, FixedResponse {
+}
+
+function checkAddRuleProps(props: AddRuleProps) {
+  if ((props.hostHeader !== undefined || props.pathPattern !== undefined) !== (props.priority !== undefined)) {
+    throw new Error(`Setting 'pathPattern' or 'hostHeader' also requires 'priority', and vice versa`);
+  }
+}

packages/@aws-cdk/aws-elasticloadbalancingv2/lib/shared/base-listener.ts

@@ -7,7 +7,7 @@ import { ITargetGroup } from './base-target-group';
  */
 export abstract class BaseListener extends cdk.Construct {
   public readonly listenerArn: string;
-  private readonly defaultActions: any[] = [];
+  private readonly defaultActions: CfnListener.ActionProperty[] = [];
 
   constructor(scope: cdk.Construct, id: string, additionalProps: any) {
     super(scope, id);
@@ -30,12 +30,20 @@ export abstract class BaseListener extends cdk.Construct {
     return [];
   }
 
+  /**
+   * Add an action to the list of default actions of this listener
+   * @internal
+   */
+  protected _addDefaultAction(action: CfnListener.ActionProperty) {
+    this.defaultActions.push(action);
+  }
+
   /**
    * Add a TargetGroup to the list of default actions of this listener
    * @internal
    */
   protected _addDefaultTargetGroup(targetGroup: ITargetGroup) {
-    this.defaultActions.push({
+    this._addDefaultAction({
       targetGroupArn: targetGroup.targetGroupArn,
       type: 'forward'
     });

packages/@aws-cdk/aws-elasticloadbalancingv2/test/alb/test.listener.ts

@@ -482,6 +482,124 @@ export = {
 
     test.done();
   },
+
+  'Can add fixed responses'(test: Test) {
+    // GIVEN
+    const stack = new cdk.Stack();
+    const vpc = new ec2.VpcNetwork(stack, 'VPC');
+    const lb = new elbv2.ApplicationLoadBalancer(stack, 'LoadBalancer', {
+      vpc
+    });
+    const listener = lb.addListener('Listener', {
+      port: 80
+    });
+
+    // WHEN
+    listener.addFixedResponse('Default', {
+      contentType: elbv2.ContentType.TEXT_PLAIN,
+      messageBody: 'Not Found',
+      statusCode: '404'
+    });
+    listener.addFixedResponse('Hello', {
+      priority: 10,
+      pathPattern: '/hello',
+      statusCode: '503'
+    });
+
+    // THEN
+    expect(stack).to(haveResource('AWS::ElasticLoadBalancingV2::Listener', {
+      DefaultActions: [
+        {
+          FixedResponseConfig: {
+            ContentType: 'text/plain',
+            MessageBody: 'Not Found',
+            StatusCode: '404'
+          },
+          Type: 'fixed-response'
+        }
+      ]
+    }));
+
+    expect(stack).to(haveResource('AWS::ElasticLoadBalancingV2::ListenerRule', {
+      Actions: [
+        {
+          FixedResponseConfig: {
+            StatusCode: '503'
+          },
+          Type: 'fixed-response'
+        }
+      ]
+    }));
+
+    test.done();
+  },
+
+  'Throws with bad fixed responses': {
+
+    'status code'(test: Test) {
+      // GIVEN
+      const stack = new cdk.Stack();
+      const vpc = new ec2.VpcNetwork(stack, 'VPC');
+      const lb = new elbv2.ApplicationLoadBalancer(stack, 'LoadBalancer', {
+        vpc
+      });
+      const listener = lb.addListener('Listener', {
+        port: 80
+      });
+
+      // THEN
+      test.throws(() => listener.addFixedResponse('Default', {
+        statusCode: '301'
+      }), /`statusCode`/);
+
+      test.done();
+    },
+
+    'message body'(test: Test) {
+      // GIVEN
+      const stack = new cdk.Stack();
+      const vpc = new ec2.VpcNetwork(stack, 'VPC');
+      const lb = new elbv2.ApplicationLoadBalancer(stack, 'LoadBalancer', {
+        vpc
+      });
+      const listener = lb.addListener('Listener', {
+        port: 80
+      });
+
+      // THEN
+      test.throws(() => listener.addFixedResponse('Default', {
+        messageBody: 'a'.repeat(1025),
+        statusCode: '500'
+      }), /`messageBody`/);
+
+      test.done();
+    }
+  },
+
+  'Throws when specifying both target groups and fixed reponse'(test: Test) {
+    // GIVEN
+    const stack = new cdk.Stack();
+    const vpc = new ec2.VpcNetwork(stack, 'VPC');
+    const lb = new elbv2.ApplicationLoadBalancer(stack, 'LoadBalancer', {
+      vpc
+    });
+    const listener = lb.addListener('Listener', {
+      port: 80
+    });
+
+    // THEN
+    test.throws(() => new elbv2.ApplicationListenerRule(stack, 'Rule', {
+      listener,
+      priority: 10,
+      pathPattern: '/hello',
+      targetGroups: [new elbv2.ApplicationTargetGroup(stack, 'TargetGroup', { vpc, port: 80 })],
+      fixedResponse: {
+        statusCode: '500'
+      }
+    }), /`targetGroups`.*`fixedResponse`/);
+
+    test.done();
+  }
 };
 
 class ResourceWithLBDependency extends cdk.CfnResource {