validate *.api against JSON schema during code generation #558

Author: ehennum

lib/endpointDeclarationValidator.js

@@ -0,0 +1,115 @@
+/*
+ * Copyright (c) 2020 MarkLogic Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+'use strict';
+
+const Ajv = require('ajv');
+
+const endpointDeclarationSchema =
+{"$schema":      "http://json-schema.org/draft-07/schema#",
+  "title":       "MarkLogic Endpoint Function Declaration",
+  "$comment":    "SIMPLIFIED TO THE STABLE DECLARATIONS USED FOR CODE GENERATION",
+  "type":        "object",
+  "definitions": {
+    "desc": {
+      "type":"string", "description":"Documentation about the property"
+    },
+    "datatype": {
+      "type":"string", "description":"The type of the value",
+      "enum":[
+        "boolean", "date", "dateTime", "dayTimeDuration", "decimal", "double", "float",
+        "int", "long", "string", "time", "unsignedInt", "unsignedLong",
+        "array", "object",
+        "binaryDocument", "jsonDocument", "textDocument", "xmlDocument",
+        "session"
+      ]
+    },
+    "nullable": {
+      "type":"boolean", "description":"Whether a null value is allowed",
+      "default":false
+    },
+    "multiple": {
+      "type":"boolean", "description":"Whether multiple values are allowed",
+      "default":false
+    }
+//  "$comment": "SIMPLIFIED BY DELETING doubleMeter, doubleLiteral, ulMeter, AND unsignedLongLiteral"
+  },
+  "propertyNames": {
+//    "$comment": "MODIFIED TO ALLOW FOR PROPERTIES DELETED DURING SIMPLIFICATION OR ADDED IN LATER RELEASES",
+    "pattern": "^\\$?[A-Za-z_][\\w.-]*$"
+  },
+  "properties":  {
+    "functionName": {
+      "type":"string", "description":"The name of a database function provided by a service declared by service.json"
+    },
+    "endpoint": {
+      "type":"string", "description":"The full path name of a standalone bulk IO endpoint"
+    },
+    "desc":         {"$ref":"#/definitions/desc"},
+    "params":       {
+      "type":"array", "description":"The parameters of the function",
+      "items": {
+        "type":"object",
+        "required":   ["name", "datatype"],
+        "propertyNames": {
+          "pattern": "^(\\$[A-Za-z_][\\w.-]*|name|desc|datatype|nullable|multiple)$"
+        },
+        "properties": {
+          "name":  {
+            "type":"string", "description":"The name of the function parameter"
+          },
+          "desc":     {"$ref":"#/definitions/desc"},
+          "datatype": {"$ref":"#/definitions/datatype"},
+          "nullable": {"$ref":"#/definitions/nullable"},
+          "multiple": {"$ref":"#/definitions/multiple"}
+        }
+      }
+    },
+    "return": {
+      "type":"object", "description":"The return value of the function",
+      "required":   ["datatype"],
+      "propertyNames": {
+        "pattern": "^(\\$[A-Za-z_][\\w.-]*|desc|datatype|nullable|multiple)$"
+      },
+      "properties": {
+        "desc":     {"$ref":"#/definitions/desc"},
+        "datatype": {"$ref":"#/definitions/datatype"},
+        "nullable": {"$ref":"#/definitions/nullable"},
+        "multiple": {"$ref":"#/definitions/multiple"}
+      }
+    }
+//  "$comment": "SIMPLIFIED BY DELETING errorDetail AND monitoring"
+  }
+};
+
+const ajv = new Ajv({
+  allErrors:      true,
+  validateSchema: false // true
+});
+
+const validateWithSchema = ajv.compile(endpointDeclarationSchema);
+
+function validate(endpointDeclaration) {
+  const isValid = validateWithSchema(endpointDeclaration);
+  const result = {isValid: isValid};
+  if (!isValid) {
+    result.errors = validateWithSchema.errors;
+  }
+  return result;
+}
+
+module.exports = {
+  validate: validate
+};

lib/proxy-generator.js

@@ -25,6 +25,8 @@ const {generate} = require('astring');
 
 const Vinyl = require('./optional.js').library('vinyl');
 
+const endpointDeclarationValidator = require('./endpointDeclarationValidator');
+
 // START SHARED WITH Modules/MarkLogic/rest-api/lib/openapi-transform.sjs IN THE SERVER
 function expandDataDeclaration(id, dataDeclaration) {
   const datatype = dataDeclaration.datatype;
@@ -612,6 +614,10 @@ function generateModuleSource(moduleName, servicedef, endpointdefs) {
       } else if (endpoint.declaration.functionName === void 0 || endpoint.declaration.functionName === null) {
         throw new Error(`endpoint declaration without functionName property`);
       }
+      const validationResult = endpointDeclarationValidator.validate(endpoint.declaration);
+      if (!(validationResult.isValid)) {
+        throw new Error(`invalid endpoint declaration ${validationResult.errors}`);
+      }
     });
   }
   const proxyAST = buildModule(moduleName, servicedef, endpointdefs);
@@ -805,5 +811,6 @@ function transformDirectoryToSource() {
 module.exports = {
   generateSource:    generateModuleSource,
   readDeclarations:  readDeclarationsFromDirectory,
-  generate:          transformDirectoryToSource
+  generate:          transformDirectoryToSource,
+  validate:          endpointDeclarationValidator.validate
 };

npm-shrinkwrap.json

@@ -43,6 +43,7 @@
     "node": ">=10.15.0"
   },
   "devDependencies": {
+    "ajv": "^6.12.4",
     "ast-types": "^0.13.2",
     "astring": "^1.4.3",
     "bunyan": "^1.8.12",

package.json

@@ -175,4 +175,26 @@ describe('negative generation', function() {
       done();
     }
   });
+  it('with endpoint failing to match schema', function(done) {
+    [
+      '{"functionName":1}',
+      '{"functionName":"numericParams", "params":1}',
+      '{"functionName":"numericParamsItem", "params":[1]}',
+      '{"functionName":"missingParamsName", "params":[{"datatype":"int"}]}',
+      '{"functionName":"numericParamsName", "params":[{"name":1, "datatype":"int"}]}',
+      '{"functionName":"missingParamsDataType", "params":[{"name":"p1"}]}',
+      '{"functionName":"incorrectParamsDataType", "params":[{"name":"p1", "datatype":"notAType"}]}',
+      '{"functionName":"stringParamsMultiple", "params":[{"name":"p1", "datatype":"int", "multiple":"true"}]}',
+      '{"functionName":"stringParamsNullable", "params":[{"name":"p1", "datatype":"int", "nullable":"true"}]}',
+      '{"functionName":"numericReturn", "return":1}',
+      '{"functionName":"missingReturnDataType", "return":{"multiple":true}}',
+      '{"functionName":"incorrectReturnDataType", "return":{"datatype":"notAType"}}',
+      '{"functionName":"stringReturnMultiple", "return":{"datatype":"int", "multiple":"true"}}',
+      '{"functionName":"stringReturnNullable", "return":{"datatype":"int", "nullable":"true"}}'
+    ].forEach((badApi, i) => {
+      const validationResult = proxy.validate(JSON.parse(badApi));
+      expect(validationResult.isValid).to.eql(false);
+    });
+    done();
+  });
 });