feat(apigatewayv2): websocket api (#13031)

feat(apigatewayv2): add support for WebSocket APIs

BREAKING CHANGE: `HttpApiMapping` (and related interfaces for `Attributed` and `Props`) has been renamed to `ApiMapping`
* **apigatewayv2:** `CommonStageOptions` has been renamed to `StageOptions`
* **apigatewayv2:** `HttpStage.fromStageName` has been removed in favour of `HttpStage.fromHttpStageAttributes`
* **apigatewayv2:** `DefaultDomainMappingOptions` has been removed in favour of `DomainMappingOptions`
* **apigatewayv2:** `HttpApiProps.defaultDomainMapping` has been changed from `DefaultDomainMappingOptions` to `DomainMappingOptions`
* **apigatewayv2:** `HttpApi.defaultStage` has been changed from `HttpStage` to `IStage`
* **apigatewayv2:** `IHttpApi.defaultStage` has been removed

closes #2872

Some notes:
1. Only Lambda Integration is currently supported
2. No support for `IntegrationResponse` and `RouteResponse`.
3. The `$default` stageName does not seem to work for WebSocket APIs. Therefore modified the API for defaultStage in the API.

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

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

@@ -21,6 +21,8 @@
   - [Lambda Integration](#lambda)
   - [HTTP Proxy Integration](#http-proxy)
   - [Private Integration](#private-integration)
+- [WebSocket APIs](#websocket-apis)
+  - [Lambda WebSocket Integration](#lambda-websocket-integration)
 
 ## HTTP APIs
 
@@ -146,3 +148,32 @@ const httpEndpoint = new HttpApi(stack, 'HttpProxyPrivateApi', {
   }),
 });
 ```
+
+## WebSocket APIs
+
+WebSocket integrations connect a route to backend resources. The following integrations are supported in the CDK.
+
+### Lambda WebSocket Integration
+
+Lambda integrations enable integrating a WebSocket API route with a Lambda function. When a client connects/disconnects 
+or sends message specific to a route, the API Gateway service forwards the request to the Lambda function
+
+The API Gateway service will invoke the lambda function with an event payload of a specific format.
+
+The following code configures a `sendmessage` route with a Lambda integration
+
+```ts
+const webSocketApi = new WebSocketApi(stack, 'mywsapi');
+new WebSocketStage(stack, 'mystage', {
+  webSocketApi,
+  stageName: 'dev',
+  autoDeploy: true,
+});
+
+const messageHandler = new lambda.Function(stack, 'MessageHandler', {...});
+webSocketApi.addRoute('sendmessage', {
+  integration: new LambdaWebSocketIntegration({
+    handler: connectHandler,
+  }),
+});
+```

packages/@aws-cdk/aws-apigatewayv2-integrations/lib/index.ts

@@ -1 +1,2 @@
 export * from './http';
+export * from './websocket';

packages/@aws-cdk/aws-apigatewayv2-integrations/lib/websocket/index.ts

@@ -0,0 +1 @@
+export * from './lambda';

packages/@aws-cdk/aws-apigatewayv2-integrations/lib/websocket/lambda.ts

@@ -0,0 +1,44 @@
+import {
+  IWebSocketRouteIntegration,
+  WebSocketIntegrationType,
+  WebSocketRouteIntegrationBindOptions,
+  WebSocketRouteIntegrationConfig,
+} from '@aws-cdk/aws-apigatewayv2';
+import { ServicePrincipal } from '@aws-cdk/aws-iam';
+import { IFunction } from '@aws-cdk/aws-lambda';
+import { Names, Stack } from '@aws-cdk/core';
+
+/**
+ * Lambda WebSocket Integration props
+ */
+export interface LambdaWebSocketIntegrationProps {
+  /**
+   * The handler for this integration.
+   */
+  readonly handler: IFunction
+}
+
+/**
+ * Lambda WebSocket Integration
+ */
+export class LambdaWebSocketIntegration implements IWebSocketRouteIntegration {
+  constructor(private props: LambdaWebSocketIntegrationProps) {}
+
+  bind(options: WebSocketRouteIntegrationBindOptions): WebSocketRouteIntegrationConfig {
+    const route = options.route;
+    this.props.handler.addPermission(`${Names.nodeUniqueId(route.node)}-Permission`, {
+      scope: options.scope,
+      principal: new ServicePrincipal('apigateway.amazonaws.com'),
+      sourceArn: Stack.of(route).formatArn({
+        service: 'execute-api',
+        resource: route.webSocketApi.apiId,
+        resourceName: `*/*${route.routeKey}`,
+      }),
+    });
+
+    return {
+      type: WebSocketIntegrationType.AWS_PROXY,
+      uri: this.props.handler.functionArn,
+    };
+  }
+}