Support external ApiGateway websocket API

fixes #6270

Author: christophgysin

docs/providers/aws/events/apigateway.md

@@ -1103,6 +1103,7 @@ provider:
   apiGateway:
     restApiId: xxxxxxxxxx # REST API resource ID. Default is generated by the framework
     restApiRootResourceId: xxxxxxxxxx # Root resource, represent as / path
+    websocketApiId: xxxxxxxxxx # Websocket API resource ID. Default is generated by the framewok
     description: Some Description # optional - description of deployment history
 
 functions:
@@ -1119,6 +1120,7 @@ provider:
   apiGateway:
     restApiId: xxxxxxxxxx
     restApiRootResourceId: xxxxxxxxxx
+    websocketApiId: xxxxxxxxxx
     description: Some Description
 
 functions:
@@ -1136,6 +1138,7 @@ provider:
   apiGateway:
     restApiId: xxxxxxxxxx
     restApiRootResourceId: xxxxxxxxxx
+    websocketApiId: xxxxxxxxxx
     description: Some Description
 
 functions:
@@ -1155,6 +1158,7 @@ provider:
   apiGateway:
     restApiId: xxxxxxxxxx
     restApiRootResourceId: xxxxxxxxxx
+    websocketApiId: xxxxxxxxxx
     description: Some Description
     restApiResources:
       /posts: xxxxxxxxxx
@@ -1170,6 +1174,7 @@ provider:
   apiGateway:
     restApiId: xxxxxxxxxx
     restApiRootResourceId: xxxxxxxxxx
+    websocketApiId: xxxxxxxxxx
     description: Some Description
     restApiResources:
       /posts: xxxxxxxxxx
@@ -1188,6 +1193,7 @@ provider:
   apiGateway:
     restApiId: xxxxxxxxxx
     # restApiRootResourceId: xxxxxxxxxx # Optional
+    websocketApiId: xxxxxxxxxx
     description: Some Description
     restApiResources:
       /posts: xxxxxxxxxx
@@ -1213,7 +1219,7 @@ functions:
 
 ### Easiest and CI/CD friendly example of using shared API Gateway and API Resources.
 
-You can define your API Gateway resource in its own service and export the `restApiId` and `restApiRootResourceId` using cloudformation cross-stack references.
+You can define your API Gateway resource in its own service and export the `restApiId`, `restApiRootResourceId` and `websocketApiId` using cloudformation cross-stack references.
 
 ```yml
 service: my-api
@@ -1231,6 +1237,13 @@ resources:
       Properties:
         Name: MyApiGW
 
+    MyWebsocketApi:
+      Type: AWS::ApiGatewayV2::Api
+      Properties:
+        Name: MyWebsocketApi
+        ProtocolType: WEBSOCKET
+        RouteSelectionExpression: '$request.body.action'
+
   Outputs:
     apiGatewayRestApiId:
       Value:
@@ -1245,9 +1258,16 @@ resources:
           - RootResourceId
       Export:
         Name: MyApiGateway-rootResourceId
+
+    websocketApiId:
+      Value:
+        Ref: MyWebsocketApi
+      Export:
+        Name: MyApiGateway-websocketApiId
+
 ```
 
-This creates API gateway and then exports the `restApiId` and `rootResourceId` values using cloudformation cross stack output.
+This creates API gateway and then exports the `restApiId`, `rootResourceId` and `websocketApiId` values using cloudformation cross stack output.
 We will import this and reference in future services.
 
 ```yml
@@ -1259,6 +1279,8 @@ provider:
       'Fn::ImportValue': MyApiGateway-restApiId
     restApiRootResourceId:
       'Fn::ImportValue': MyApiGateway-rootResourceId
+    websocketApiId:
+      'Fn::ImportValue': MyApiGateway-websocketApiId
 
 functions:
   service-a-functions
@@ -1272,6 +1294,8 @@ provider:
       'Fn::ImportValue': MyApiGateway-restApiId
     restApiRootResourceId:
       'Fn::ImportValue': MyApiGateway-rootResourceId
+    websocketApiId:
+      'Fn::ImportValue': MyApiGateway-websocketApiId
 
 functions:
   service-b-functions

docs/providers/aws/guide/serverless.yml.md

@@ -60,6 +60,7 @@ provider:
     restApiResources: # List of existing resources that were created in the REST API. This is required or the stack will be conflicted
       '/users': xxxxxxxxxx
       '/users/create': xxxxxxxxxx
+    websocketApiId: # Websocket API resource ID. Default is generated by the framewok
     apiKeySourceType: HEADER # Source of API key for usage plan. HEADER or AUTHORIZER.
     minimumCompressionSize: 1024 # Compress response when larger than specified size in bytes (must be between 0 and 10485760)
     description: Some Description # Optional description for the API Gateway stage deployment

lib/plugins/aws/package/compile/events/websockets/lib/api.js

@@ -5,6 +5,13 @@ const BbPromise = require('bluebird');
 
 module.exports = {
   compileApi() {
+    const apiGateway = this.serverless.service.provider.apiGateway || {};
+
+    // immediately return if we're using an external websocket API id
+    if (apiGateway.websocketApiId) {
+      return BbPromise.resolve();
+    }
+
     this.websocketsApiLogicalId = this.provider.naming.getWebsocketsApiLogicalId();
 
     const RouteSelectionExpression = this.serverless.service.provider

lib/plugins/aws/package/compile/events/websockets/lib/api.test.js

@@ -50,6 +50,18 @@ describe('#compileApi()', () => {
       });
     }));
 
+  it('should ignore API resource creation if there is predefined websocketApi config', () => {
+    awsCompileWebsocketsEvents.serverless.service.provider.apiGateway = {
+      websocketApiId: '5ezys3sght',
+    };
+    return awsCompileWebsocketsEvents.compileApi().then(() => {
+      const resources = awsCompileWebsocketsEvents.serverless.service.provider
+        .compiledCloudFormationTemplate.Resources;
+
+      expect(resources).to.not.have.property('WebsocketsApi');
+    });
+  });
+
   it('should add the websockets policy', () => awsCompileWebsocketsEvents
     .compileApi().then(() => {
       const resources = awsCompileWebsocketsEvents.serverless.service.provider

lib/plugins/aws/package/compile/events/websockets/lib/authorizers.js

@@ -16,9 +16,7 @@ module.exports = {
         [websocketsAuthorizerLogicalId]: {
           Type: 'AWS::ApiGatewayV2::Authorizer',
           Properties: {
-            ApiId: {
-              Ref: this.websocketsApiLogicalId,
-            },
+            ApiId: this.provider.getApiGatewayWebsocketApiId(),
             Name: event.authorizer.name,
             AuthorizerType: 'REQUEST',
             AuthorizerUri: event.authorizer.uri,

lib/plugins/aws/package/compile/events/websockets/lib/authorizers.test.js

@@ -90,6 +90,20 @@ describe('#compileAuthorizers()', () => {
       });
     });
 
+    it('should use existing Api if there is predefined websocketApi config', () => {
+      awsCompileWebsocketsEvents.serverless.service.provider.apiGateway = {
+        websocketApiId: '5ezys3sght',
+      };
+
+      return awsCompileWebsocketsEvents.compileAuthorizers().then(() => {
+        const resources = awsCompileWebsocketsEvents.serverless.service.provider
+          .compiledCloudFormationTemplate.Resources;
+
+        expect(resources.AuthWebsocketsAuthorizer.Properties).to.contain({
+          ApiId: '5ezys3sght',
+        });
+      });
+    });
   });
 
   describe('for routes without authorizer definition', () => {

lib/plugins/aws/package/compile/events/websockets/lib/deployment.js

@@ -18,9 +18,7 @@ module.exports = {
         Type: 'AWS::ApiGatewayV2::Deployment',
         DependsOn: routeLogicalIds,
         Properties: {
-          ApiId: {
-            Ref: this.websocketsApiLogicalId,
-          },
+          ApiId: this.provider.getApiGatewayWebsocketApiId(),
           Description: this.serverless.service.provider
             .websocketsDescription || 'Serverless Websockets',
         },
@@ -34,7 +32,7 @@ module.exports = {
           'Fn::Join': ['',
             [
               'wss://',
-              { Ref: this.provider.naming.getWebsocketsApiLogicalId() },
+              this.provider.getApiGatewayWebsocketApiId(),
               '.execute-api.',
               { Ref: 'AWS::Region' },
               '.',

lib/plugins/aws/package/compile/events/websockets/lib/integrations.js

@@ -14,9 +14,7 @@ module.exports = {
         [websocketsIntegrationLogicalId]: {
           Type: 'AWS::ApiGatewayV2::Integration',
           Properties: {
-            ApiId: {
-              Ref: this.websocketsApiLogicalId,
-            },
+            ApiId: this.provider.getApiGatewayWebsocketApiId(),
             IntegrationType: 'AWS_PROXY',
             IntegrationUri: {
               'Fn::Join': ['',

lib/plugins/aws/package/compile/events/websockets/lib/permissions.js

@@ -6,6 +6,7 @@ const BbPromise = require('bluebird');
 module.exports = {
   compilePermissions() {
     this.validated.events.forEach(event => {
+      const websocketApiId = this.provider.getApiGatewayWebsocketApiId();
       const lambdaLogicalId = this.provider.naming.getLambdaLogicalId(event.functionName);
 
       const websocketsPermissionLogicalId = this.provider.naming
@@ -14,7 +15,9 @@ module.exports = {
       _.merge(this.serverless.service.provider.compiledCloudFormationTemplate.Resources, {
         [websocketsPermissionLogicalId]: {
           Type: 'AWS::Lambda::Permission',
-          DependsOn: [this.websocketsApiLogicalId, lambdaLogicalId],
+          DependsOn: (websocketApiId.Ref !== undefined)
+            ? [websocketApiId.Ref, lambdaLogicalId]
+            : [lambdaLogicalId],
           Properties: {
             FunctionName: {
               'Fn::GetAtt': [lambdaLogicalId, 'Arn'],
@@ -32,7 +35,9 @@ module.exports = {
         const authorizerPermissionTemplate = {
           [websocketsAuthorizerPermissionLogicalId]: {
             Type: 'AWS::Lambda::Permission',
-            DependsOn: [this.websocketsApiLogicalId],
+            DependsOn: (websocketApiId.Ref !== undefined)
+              ? [websocketApiId.Ref]
+              : [],
             Properties: {
               Action: 'lambda:InvokeFunction',
               Principal: 'apigateway.amazonaws.com',

lib/plugins/aws/package/compile/events/websockets/lib/routes.js

@@ -16,9 +16,7 @@ module.exports = {
         [websocketsRouteLogicalId]: {
           Type: 'AWS::ApiGatewayV2::Route',
           Properties: {
-            ApiId: {
-              Ref: this.websocketsApiLogicalId,
-            },
+            ApiId: this.provider.getApiGatewayWebsocketApiId(),
             RouteKey: event.route,
             AuthorizationType: 'NONE',
             Target: {