Merge pull request #245 from ChristopheBougere/asl-validator

feat: asl validation

Author: horike37

README.md

@@ -14,6 +14,7 @@ This is the Serverless Framework plugin for AWS Step Functions.
      - [CloudWatch Alarms](#cloudwatch-alarms)
      - [CloudWatch Notifications](#cloudwatch-notifications)
      - [Blue-Green deployments](#blue-green-deployment)
+     - [Pre-deployment validation](#pre-deployment-validation)
  - [Current Gotcha](#current-gotcha)
  - [Events](#events)
      - [API Gateway](#api-gateway)
@@ -135,6 +136,7 @@ stepFunctions:
   activities:
     - myTask
     - yourTask
+  validate: true # enable pre-deployment definition validation (disabled by default)
 
 plugins:
   - serverless-step-functions
@@ -334,6 +336,15 @@ stepFunctions:
         ...
 ```
 
+### Pre-deployment validation
+
+By default, your state machine definition will be validated during deployment by StepFunctions. This can be cumbersome when developing because you have to upload your service for every typo in your definition. In order to go faster, you can enable pre-deployment validation using [asl-validator](https://www.npmjs.com/package/asl-validator) which should detect most of the issues (like a missing state property).
+
+```yaml
+stepFunctions:
+  validate: true
+```
+
 ## Current Gotcha
 
 Please keep this gotcha in mind if you want to reference the `name` from the `resources` section. To generate Logical ID for CloudFormation, the plugin transforms the specified name in serverless.yml based on the following scheme.

lib/deploy/stepFunctions/compileStateMachines.js

@@ -2,6 +2,7 @@
 
 const _ = require('lodash');
 const Joi = require('@hapi/joi');
+const aslValidator = require('asl-validator');
 const Chance = require('chance');
 const BbPromise = require('bluebird');
 const schema = require('./compileStateMachines.schema');
@@ -80,6 +81,18 @@ module.exports = {
         }
 
         if (stateMachineObj.definition) {
+          if (this.serverless.service.stepFunctions.validate) {
+            const { isValid, errors } = aslValidator(stateMachineObj.definition);
+            if (isValid) {
+              this.serverless.cli.consoleLog(`✓ State machine "${stateMachineName}" definition is valid`);
+            } else {
+              const errorMessage = [
+                `✕ State machine "${stateMachineName}" definition is invalid:`,
+                JSON.stringify(errors),
+              ].join('\n');
+              throw new this.serverless.classes.Error(errorMessage);
+            }
+          }
           if (typeof stateMachineObj.definition === 'string') {
             DefinitionString = JSON.stringify(stateMachineObj.definition)
               .replace(/\\n|\\r|\\n\\r/g, '');

lib/deploy/stepFunctions/compileStateMachines.test.js

@@ -11,6 +11,9 @@ describe('#compileStateMachines', () => {
 
   beforeEach(() => {
     serverless = new Serverless();
+    serverless.cli = {
+      consoleLog: () => {},
+    };
     serverless.servicePath = true;
     serverless.service.service = 'step-functions';
     serverless.service.provider.compiledCloudFormationTemplate = {
@@ -1024,4 +1027,85 @@ describe('#compileStateMachines', () => {
       expect(topicArn).to.deep.equal({ Ref: 'MyTopic' });
     });
   });
+
+  it('should not validate definition if not enabled', () => {
+    serverless.service.stepFunctions = {
+      stateMachines: {
+        myStateMachine1: {
+          definition: {
+            StartAt: 'Start',
+            States: {
+              Start: {
+                Type: 'Inexistant type',
+                End: true,
+              },
+            },
+          },
+        },
+      },
+      validate: false,
+    };
+    // Definition is invalid, but should succeed because validate=false
+    serverlessStepFunctions.compileStateMachines();
+  });
+
+  it('should validate definition and pass', () => {
+    serverless.service.stepFunctions = {
+      stateMachines: {
+        myStateMachine1: {
+          definition: {
+            StartAt: 'GetAttResource',
+            States: {
+              GetAttResource: {
+                Type: 'Task',
+                Resource: {
+                  'Fn::GetAtt': [
+                    'lambda-name_GetAtt',
+                    'Arn',
+                  ],
+                },
+                Next: 'RefResource',
+              },
+              RefResource: {
+                Type: 'Task',
+                Resource: {
+                  Ref: 'lambda-name_Ref',
+                },
+                Next: 'ArnResource',
+              },
+              ArnResource: {
+                Type: 'Task',
+                Resource: 'arn:aws:lambda:region-1:1234567890:function:lambda-name_Arn',
+                End: true,
+              },
+            },
+          },
+        },
+      },
+      validate: true,
+    };
+    // Definition is valid, should succeed
+    serverlessStepFunctions.compileStateMachines();
+  });
+
+  it('should validate definition and fail', () => {
+    serverless.service.stepFunctions = {
+      stateMachines: {
+        myStateMachine1: {
+          definition: {
+            StartAt: 'Start',
+            States: {
+              Start: {
+                Type: 'Inexistant type',
+                End: true,
+              },
+            },
+          },
+        },
+      },
+      validate: true,
+    };
+    // Definition is invalid and validate=true, should throw
+    expect(() => serverlessStepFunctions.compileStateMachines()).to.throw(Error);
+  });
 });

lib/yamlParser.js

@@ -17,7 +17,9 @@ module.exports = {
       .parse(serverlessYmlPath)
       .then(serverlessFileParam => this.serverless.variables.populateObject(serverlessFileParam)
         .then((parsedObject) => {
-          this.serverless.service.stepFunctions = {};
+          this.serverless.service.stepFunctions = {
+            validate: parsedObject.stepFunctions ? parsedObject.stepFunctions.validate : false,
+          };
           this.serverless.service.stepFunctions.stateMachines = parsedObject.stepFunctions
             && parsedObject.stepFunctions.stateMachines
             ? parsedObject.stepFunctions.stateMachines : {};

package-lock.json

@@ -42,6 +42,7 @@
   },
   "dependencies": {
     "@hapi/joi": "^15.0.2",
+    "asl-validator": "^1.4.0",
     "aws-sdk": "^2.282.1",
     "bluebird": "^3.4.0",
     "chalk": "^1.1.1",