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,
+ };
+ }
+}