feat(appmesh): change HealthChecks to use protocol-specific union-like classes

packages/@aws-cdk/aws-appmesh/lib/gateway-route-spec.ts

@@ -1,5 +1,5 @@
 import { CfnGatewayRoute } from './appmesh.generated';
-import { Protocol } from './shared-interfaces';
+import { Protocol } from './private/utils';
 import { IVirtualService } from './virtual-service';
 
 // keep this import separate from other imports to reduce chance for merge conflicts with v2-main

packages/@aws-cdk/aws-appmesh/lib/private/utils.ts

@@ -1,45 +1,3 @@
-import * as cdk from '@aws-cdk/core';
-import { CfnVirtualGateway, CfnVirtualNode } from '../appmesh.generated';
-
-type AppMeshHealthCheck = CfnVirtualNode.HealthCheckProperty | CfnVirtualGateway.VirtualGatewayHealthCheckPolicyProperty
-
-/**
- * Validates health check properties, throws an error if they are misconfigured.
- *
- * @param healthCheck Healthcheck property from a Virtual Node or Virtual Gateway
- */
-export function validateHealthChecks(healthCheck: AppMeshHealthCheck) {
-  (Object.keys(healthCheck) as Array<keyof AppMeshHealthCheck>)
-    .filter((key) =>
-      HEALTH_CHECK_PROPERTY_THRESHOLDS[key] &&
-          typeof healthCheck[key] === 'number' &&
-          !cdk.Token.isUnresolved(healthCheck[key]),
-    ).map((key) => {
-      const [min, max] = HEALTH_CHECK_PROPERTY_THRESHOLDS[key]!;
-      const value = healthCheck[key]!;
-
-      if (value < min) {
-        throw new Error(`The value of '${key}' is below the minimum threshold (expected >=${min}, got ${value})`);
-      }
-      if (value > max) {
-        throw new Error(`The value of '${key}' is above the maximum threshold (expected <=${max}, got ${value})`);
-      }
-    });
-}
-
-/**
- * Minimum and maximum thresholds for HeathCheck numeric properties
- *
- * @see https://docs.aws.amazon.com/app-mesh/latest/APIReference/API_HealthCheckPolicy.html
- */
-const HEALTH_CHECK_PROPERTY_THRESHOLDS: {[key in (keyof AppMeshHealthCheck)]?: [number, number]} = {
-  healthyThreshold: [2, 10],
-  intervalMillis: [5000, 300000],
-  port: [1, 65535],
-  timeoutMillis: [2000, 60000],
-  unhealthyThreshold: [2, 10],
-};
-
 /**
  * Generated Connection pool config
  */
@@ -64,4 +22,14 @@ export interface ConnectionPoolConfig {
    * @default - none
    */
   readonly maxRequests?: number;
+}
+
+/**
+ * Enum of supported AppMesh protocols
+ */
+export enum Protocol {
+  HTTP = 'http',
+  TCP = 'tcp',
+  HTTP2 = 'http2',
+  GRPC = 'grpc',
 }

packages/@aws-cdk/aws-appmesh/lib/route-spec.ts

@@ -1,6 +1,7 @@
 import * as cdk from '@aws-cdk/core';
 import { CfnRoute } from './appmesh.generated';
-import { Protocol, HttpTimeout, GrpcTimeout, TcpTimeout } from './shared-interfaces';
+import { Protocol } from './private/utils';
+import { HttpTimeout, GrpcTimeout, TcpTimeout } from './shared-interfaces';
 import { IVirtualNode } from './virtual-node';
 
 // keep this import separate from other imports to reduce chance for merge conflicts with v2-main

packages/@aws-cdk/aws-appmesh/lib/shared-interfaces.ts

@@ -1,6 +1,7 @@
 import * as cdk from '@aws-cdk/core';
 import { CfnVirtualGateway, CfnVirtualNode } from './appmesh.generated';
 import { ClientPolicy } from './client-policy';
+import { Protocol } from './private/utils';
 import { IVirtualService } from './virtual-service';
 
 // keep this import separate from other imports to reduce chance for merge conflicts with v2-main
@@ -58,70 +59,160 @@ export interface TcpTimeout {
 }
 
 /**
- * Enum of supported AppMesh protocols
+ * Properties used to define healthchecks.
  */
-export enum Protocol {
-  HTTP = 'http',
-  TCP = 'tcp',
-  HTTP2 = 'http2',
-  GRPC = 'grpc',
-}
-
-/**
- * Properties used to define healthchecks when creating virtual nodes.
- * All values have a default if only specified as {} when creating.
- * If property not set, then no healthchecks will be defined.
- */
-export interface HealthCheck {
+export interface HealthCheckCommonOptions {
   /**
-   * Number of successful attempts before considering the node UP
+   * The number of consecutive successful health checks that must occur before declaring listener healthy.
    *
-   * @default 2
+   * @default 5
    */
   readonly healthyThreshold?: number;
 
   /**
-   * Interval in milliseconds to re-check
+   * The time period in milliseconds between each health check execution.
    *
-   * @default 5 seconds
+   * @default Duration.seconds(30)
    */
   readonly interval?: cdk.Duration;
 
   /**
-   * The path where the application expects any health-checks, this can also be the application path.
+   * The amount of time to wait when receiving a response from the health check, in milliseconds.
    *
-   * @default /
+   * @default Duration.seconds(5)
    */
-  readonly path?: string;
+  readonly timeout?: cdk.Duration;
 
   /**
-   * The TCP port number for the healthcheck
+   * The number of consecutive failed health checks that must occur before declaring a listener unhealthy.
    *
-   * @default - same as corresponding port mapping
+   * @default - 2
    */
-  readonly port?: number;
+  readonly unhealthyThreshold?: number;
+}
 
+/**
+ * Properties used to define healthchecks.
+ */
+export interface HttpHealthCheckOptions extends HealthCheckCommonOptions {
   /**
-   * The protocol to use for the healthcheck, for convinience a const enum has been defined.
-   * Protocol.HTTP or Protocol.TCP
+   * The destination path for the health check request.
    *
-   * @default - same as corresponding port mapping
+   * @default /
    */
-  readonly protocol?: Protocol;
+  readonly path?: string;
+}
 
+/**
+ * All Properties for Health Checks for mesh endpoints
+ */
+export interface HealthCheckConfig {
   /**
-   * Timeout in milli-seconds for the healthcheck to be considered a fail.
+   * VirtualNode CFN configuration for Health Checks
    *
-   * @default 2 seconds
+   * @default - no health checks
    */
-  readonly timeout?: cdk.Duration;
+  readonly virtualNodeHealthCheck?: CfnVirtualNode.HealthCheckProperty;
 
   /**
-   * Number of failed attempts before considering the node DOWN.
+   * VirtualGateway CFN configuration for Health Checks
    *
-   * @default 2
+   * @default - no health checks
    */
-  readonly unhealthyThreshold?: number;
+  readonly virtualGatewayHealthCheck?: CfnVirtualGateway.VirtualGatewayHealthCheckPolicyProperty;
+}
+
+/**
+ * Contains static factory methods for creating health checks for different protocols
+ */
+export abstract class HealthCheck {
+  /**
+   * Construct a HTTP health check
+   */
+  public static http(options: HttpHealthCheckOptions = {}): HealthCheck {
+    return new HealthCheckImpl(Protocol.HTTP, options.healthyThreshold, options.unhealthyThreshold, options.interval, options.timeout, options.path);
+  }
+
+  /**
+   * Construct a HTTP2 health check
+   */
+  public static http2(options: HttpHealthCheckOptions = {}): HealthCheck {
+    return new HealthCheckImpl(Protocol.HTTP2, options.healthyThreshold, options.unhealthyThreshold, options.interval, options.timeout, options.path);
+  }
+
+  /**
+   * Construct a GRPC health check
+   */
+  public static grpc(options: HealthCheckCommonOptions= {}): HealthCheck {
+    return new HealthCheckImpl(Protocol.GRPC, options.healthyThreshold, options.unhealthyThreshold, options.interval, options.timeout);
+  }
+
+  /**
+   * Construct a TCP health check
+   */
+  public static tcp(options: HealthCheckCommonOptions = {}): HealthCheck {
+    return new HealthCheckImpl(Protocol.TCP, options.healthyThreshold, options.unhealthyThreshold, options.interval, options.timeout);
+  }
+
+  /**
+   * Called when the AccessLog type is initialized. Can be used to enforce
+   * mutual exclusivity with future properties
+   */
+  public abstract bind(scope: Construct): HealthCheckConfig;
+}
+
+class HealthCheckImpl extends HealthCheck {
+  constructor(
+    private readonly protocol: Protocol,
+    private readonly healthyThreshold: number = 5,
+    private readonly unhealthyThreshold: number = 2,
+    private readonly interval: cdk.Duration = cdk.Duration.seconds(30),
+    private readonly timeout: cdk.Duration = cdk.Duration.seconds(5),
+    private readonly path?: string) {
+    super();
+    if (healthyThreshold < 2 || healthyThreshold > 10) {
+      throw new Error('healthyThreshold must be between 2 and 10');
+    }
+
+    if (unhealthyThreshold < 2 || unhealthyThreshold > 10) {
+      throw new Error('unhealthyThreshold must be between 2 and 10');
+    }
+
+    if (interval.toMilliseconds() < 5000 || interval.toMilliseconds() > 300_000) {
+      throw new Error('interval must be more than 5 seconds and less than 300 seconds');
+    }
+
+    if (timeout.toMilliseconds() < 2000 || timeout.toMilliseconds() > 60_000) {
+      throw new Error('timeout must be more than 2 seconds and less than 60 seconds');
+    }
+
+    // Default to / for HTTP Health Checks
+    if (path === undefined && (protocol === Protocol.HTTP || protocol === Protocol.HTTP2)) {
+      this.path = '/';
+    }
+  }
+
+  public bind(_scope: Construct): HealthCheckConfig {
+    return {
+      virtualNodeHealthCheck: {
+        protocol: this.protocol,
+        healthyThreshold: this.healthyThreshold,
+        unhealthyThreshold: this.unhealthyThreshold,
+        intervalMillis: this.interval.toMilliseconds(),
+        timeoutMillis: this.timeout.toMilliseconds(),
+        path: this.path,
+      },
+      virtualGatewayHealthCheck: {
+        protocol: this.protocol,
+        healthyThreshold: this.healthyThreshold,
+        unhealthyThreshold: this.unhealthyThreshold,
+        intervalMillis: this.interval.toMilliseconds(),
+        timeoutMillis: this.timeout.toMilliseconds(),
+        path: this.path,
+      },
+    };
+  }
+
 }
 
 /**

packages/@aws-cdk/aws-appmesh/lib/virtual-gateway-listener.ts

@@ -1,12 +1,10 @@
-import * as cdk from '@aws-cdk/core';
 import { CfnVirtualGateway } from './appmesh.generated';
-import { validateHealthChecks, ConnectionPoolConfig } from './private/utils';
+import { ConnectionPoolConfig, Protocol } from './private/utils';
 import {
   GrpcConnectionPool,
   HealthCheck,
   Http2ConnectionPool,
   HttpConnectionPool,
-  Protocol,
 } from './shared-interfaces';
 import { TlsCertificate, TlsCertificateConfig } from './tls-certificate';
 
@@ -143,7 +141,7 @@ class VirtualGatewayListenerImpl extends VirtualGatewayListener {
           port: this.port,
           protocol: this.protocol,
         },
-        healthCheck: this.healthCheck ? renderHealthCheck(this.healthCheck, this.protocol, this.port): undefined,
+        healthCheck: this.healthCheck ? this.healthCheck.bind(scope).virtualGatewayHealthCheck: undefined,
         tls: tlsConfig ? renderTls(tlsConfig) : undefined,
         connectionPool: this.connectionPool ? renderConnectionPool(this.connectionPool, this.protocol) : undefined,
       },
@@ -162,34 +160,6 @@ function renderTls(tlsCertificateConfig: TlsCertificateConfig): CfnVirtualGatewa
   };
 }
 
-function renderHealthCheck(hc: HealthCheck, listenerProtocol: Protocol,
-  listenerPort: number): CfnVirtualGateway.VirtualGatewayHealthCheckPolicyProperty {
-
-  if (hc.protocol === Protocol.TCP) {
-    throw new Error('TCP health checks are not permitted for gateway listeners');
-  }
-
-  if (hc.protocol === Protocol.GRPC && hc.path) {
-    throw new Error('The path property cannot be set with Protocol.GRPC');
-  }
-
-  const protocol = hc.protocol? hc.protocol : listenerProtocol;
-
-  const healthCheck: CfnVirtualGateway.VirtualGatewayHealthCheckPolicyProperty = {
-    healthyThreshold: hc.healthyThreshold || 2,
-    intervalMillis: (hc.interval || cdk.Duration.seconds(5)).toMilliseconds(), // min
-    path: hc.path || ((protocol === Protocol.HTTP || protocol === Protocol.HTTP2) ? '/' : undefined),
-    port: hc.port || listenerPort,
-    protocol: hc.protocol || listenerProtocol,
-    timeoutMillis: (hc.timeout || cdk.Duration.seconds(2)).toMilliseconds(),
-    unhealthyThreshold: hc.unhealthyThreshold || 2,
-  };
-
-  validateHealthChecks(healthCheck);
-
-  return healthCheck;
-}
-
 function renderConnectionPool(connectionPool: ConnectionPoolConfig, listenerProtocol: Protocol):
 CfnVirtualGateway.VirtualGatewayConnectionPoolProperty {
   return ({

packages/@aws-cdk/aws-appmesh/lib/virtual-node-listener.ts

@@ -1,9 +1,8 @@
-import * as cdk from '@aws-cdk/core';
 import { CfnVirtualNode } from './appmesh.generated';
-import { validateHealthChecks, ConnectionPoolConfig } from './private/utils';
+import { ConnectionPoolConfig, Protocol } from './private/utils';
 import {
   GrpcConnectionPool, GrpcTimeout, HealthCheck, Http2ConnectionPool, HttpConnectionPool,
-  HttpTimeout, OutlierDetection, Protocol, TcpConnectionPool, TcpTimeout,
+  HttpTimeout, OutlierDetection, TcpConnectionPool, TcpTimeout,
 } from './shared-interfaces';
 import { TlsCertificate, TlsCertificateConfig } from './tls-certificate';
 
@@ -185,7 +184,7 @@ class VirtualNodeListenerImpl extends VirtualNodeListener {
           port: this.port,
           protocol: this.protocol,
         },
-        healthCheck: this.healthCheck ? this.renderHealthCheck(this.healthCheck) : undefined,
+        healthCheck: this.healthCheck ? this.healthCheck.bind(scope).virtualNodeHealthCheck : undefined,
         timeout: this.timeout ? this.renderTimeout(this.timeout) : undefined,
         tls: tlsConfig ? this.renderTls(tlsConfig) : undefined,
         outlierDetection: this.outlierDetection ? this.renderOutlierDetection(this.outlierDetection) : undefined,
@@ -204,32 +203,6 @@ class VirtualNodeListenerImpl extends VirtualNodeListener {
     };
   }
 
-  private renderHealthCheck(hc: HealthCheck): CfnVirtualNode.HealthCheckProperty | undefined {
-    if (hc === undefined) { return undefined; }
-
-    if (hc.protocol === Protocol.TCP && hc.path) {
-      throw new Error('The path property cannot be set with Protocol.TCP');
-    }
-
-    if (hc.protocol === Protocol.GRPC && hc.path) {
-      throw new Error('The path property cannot be set with Protocol.GRPC');
-    }
-
-    const healthCheck: CfnVirtualNode.HealthCheckProperty = {
-      healthyThreshold: hc.healthyThreshold || 2,
-      intervalMillis: (hc.interval || cdk.Duration.seconds(5)).toMilliseconds(), // min
-      path: hc.path || (hc.protocol === Protocol.HTTP ? '/' : undefined),
-      port: hc.port || this.port,
-      protocol: hc.protocol || this.protocol,
-      timeoutMillis: (hc.timeout || cdk.Duration.seconds(2)).toMilliseconds(),
-      unhealthyThreshold: hc.unhealthyThreshold || 2,
-    };
-
-    validateHealthChecks(healthCheck);
-
-    return healthCheck;
-  }
-
   private renderTimeout(timeout: HttpTimeout): CfnVirtualNode.ListenerTimeoutProperty {
     return ({
       [this.protocol]: {

packages/@aws-cdk/aws-appmesh/lib/virtual-router-listener.ts

@@ -1,5 +1,5 @@
 import { CfnVirtualRouter } from './appmesh.generated';
-import { Protocol } from './shared-interfaces';
+import { Protocol } from './private/utils';
 
 // keep this import separate from other imports to reduce chance for merge conflicts with v2-main
 // eslint-disable-next-line no-duplicate-imports, import/order