Add cancelBuild() function

Author: aw

README.md

@@ -56,10 +56,14 @@ The following functions are exported:
 * `makeHMAC()` to generate an SHA256 HMAC from a string and key
 * `buildRequest()` to generate a request object to be sent to the `apiCall()` function
 * `apiCall()` to send the actual request data to the Meta API
+
+The following helper functions are exported:
+
 * `buildOVA()` to build an OVA through the Meta API
 * `getStatus()` to obtain the status of an OVA build
 * `pollStatus()` to poll the status of an OVA build (every 5 seconds)
 * `getDownloads()` to obtain the list of download files for an OVA build
+* `cancelBuild()` to cancel a running OVA build
 
 See the usage docs below.
 
@@ -151,7 +155,21 @@ meta.buildRequest apiParams, (error, result) =>
 coffee> { Status: '200 OK' }
 ```
 
-#### Build an OVA (returns the builddate)
+#### Change a NodeJS `http.request()` option (example: `family` (for IPv6))
+
+```coffee
+meta.options.agent = new https.Agent { family: 6 }
+meta.buildRequest undefined, (error, result) =>
+  unless error
+    meta.apiCall result, (err, res, data) ->
+      console.log data
+```
+
+### Helper examples
+
+The following helper functions are designed to simplify API calls and return simple string results
+
+#### buildOVA() - Build an OVA (returns the builddate)
 
 ```coffee
 apiParams =
@@ -169,7 +187,7 @@ meta.buildOVA "/path/to/your/app.tcz", apiParams, (err, res) ->
 coffee> 1574834281.966265128
 ```
 
-#### Poll the status of an OVA (returns the status)
+#### pollStatus() - Poll the status of an OVA (returns the status)
 
 ```coffee
 meta.pollStatus '1574834281.966265128', undefined, (err, res) ->
@@ -182,7 +200,7 @@ meta.pollStatus '1574834281.966265128', undefined, (err, res) ->
 coffee> success
 ```
 
-#### Get the list of download URLs
+#### getDownloads() - Get the list of download URLs (returns a list of URLs)
 
 ```coffee
 meta.getDownloads '1574834281.966265128', (err, res) ->
@@ -195,14 +213,17 @@ meta.getDownloads '1574834281.966265128', (err, res) ->
 coffee> https://yourdomain.com:443/downloads/build-1574834281.966265128/your-appliance-v1.2.3-release.ova
 ```
 
-#### Change a NodeJS `http.request()` option (example: `family` (for IPv6))
+#### cancelBuild() - Cancel an OVA build (returns OK)
 
 ```coffee
-meta.options.agent = new https.Agent { family: 6 }
-meta.buildRequest undefined, (error, result) =>
-  unless error
-    meta.apiCall result, (err, res, data) ->
-      console.log data
+meta.cancelBuild '1574834281.966265128', (err, res) ->
+  if err
+    console.error err
+    process.exit 1
+  else
+    console.log res
+
+coffee> OK
 ```
 
 ## JavaScript
@@ -284,7 +305,24 @@ meta.buildRequest(apiParams, (error, result) => {
 });
 ```
 
-#### Build an OVA (returns the builddate)
+#### Change a NodeJS `http.request()` option (example: `family` (for IPv6))
+
+```js
+meta.options.agent = new https.Agent({ family: 6 });
+meta.buildRequest(void 0, (error, result) => {
+  if (!error) {
+    return meta.apiCall(result, function(err, res, data) {
+      return console.log(data);
+    });
+  }
+});
+```
+
+### Helper examples
+
+The following helper functions are designed to simplify API calls and return simple string results
+
+#### buildOVA() - Build an OVA (returns the builddate)
 
 ```js
 apiParams = {
@@ -303,7 +341,7 @@ meta.buildOVA("/path/to/your/app.tcz", apiParams, function(err, res) {
 });
 ```
 
-#### Poll the status of an OVA (returns the status object)
+#### pollStatus() - Poll the status of an OVA (returns the status)
 
 ```js
 meta.pollStatus('1574834281.966265128', void 0, function(err, res) {
@@ -316,7 +354,7 @@ meta.pollStatus('1574834281.966265128', void 0, function(err, res) {
   });
 ```
 
-#### Get the list of download URLs
+#### getDownloads() - Get the list of download URLs (returns a list of URLs)
 
 ```js
 meta.getDownloads('1574834281.966265128', function(err, res) {
@@ -329,17 +367,17 @@ meta.getDownloads('1574834281.966265128', function(err, res) {
   });
 ```
 
-#### Change a NodeJS `http.request()` option (example: `family` (for IPv6))
+#### cancelBuild() - Cancel an OVA build (returns OK)
 
 ```js
-meta.options.agent = new https.Agent({ family: 6 });
-meta.buildRequest(void 0, (error, result) => {
-  if (!error) {
-    return meta.apiCall(result, function(err, res, data) {
-      return console.log(data);
-    });
-  }
-});
+meta.cancelBuild('1574941961.314614280', function(err, res) {
+    if (err) {
+      console.error(err);
+      return process.exit(1);
+    } else {
+      return console.log(res);
+    }
+  });
 ```
 
 # Testing

lib/on-prem-meta.js

@@ -17,7 +17,7 @@
   fs = require('fs');
 
   needle.defaults({
-    user_agent: 'nodeclient-on-prem-meta/1.3.0',
+    user_agent: 'nodeclient-on-prem-meta/1.4.0',
     response_timeout: 10000 // 10 seconds
   });
 
@@ -235,4 +235,32 @@
     });
   };
 
+  // returns a callback with an error in arg1, or 'OK' in arg2
+  // the error is an Error object if non-HTTP related
+  // the error is the request result if 404 or other HTTP error code (4xx or 5xx)
+  exports.cancelBuild = (build, callback) => {
+    var apiParams;
+    apiParams = {
+      method: 'POST',
+      endpoint: 'builds/cancel',
+      query: {
+        builddate: build
+      }
+    };
+    return this.buildRequest(apiParams, (error, result) => {
+      if (error) {
+        callback(error);
+      }
+      return this.apiCall(result, function(err, res, data) {
+        if (err) {
+          return callback(new Error(err));
+        } else if (res.statusCode === 200 && res.statusMessage === 'OK') {
+          return callback(null, res.statusMessage);
+        } else {
+          return callback(data);
+        }
+      });
+    });
+  };
+
 }).call(this);

package.json

@@ -2,7 +2,7 @@
   "description": "Official On-Prem Meta REST API client and helper library",
   "author": "Alexander Williams, Unscramble <[email protected]>",
   "name": "@on-prem/on-prem-meta",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "license": "MIT",
   "homepage": "https://on-premises.com",
   "main": "lib/on-prem-meta.js",

src/on-prem-meta.coffee

@@ -11,7 +11,7 @@ formData   = require 'form-data'
 fs         = require 'fs'
 
 needle.defaults
-  user_agent: 'nodeclient-on-prem-meta/1.3.0'
+  user_agent: 'nodeclient-on-prem-meta/1.4.0'
   response_timeout: 10000 # 10 seconds
 
 exports.makeSHA256 = (string) ->
@@ -164,3 +164,23 @@ exports.getDownloads = (build, callback) =>
         callback null, downloads.join('\n')
       else
         callback data
+
+# returns a callback with an error in arg1, or 'OK' in arg2
+# the error is an Error object if non-HTTP related
+# the error is the request result if 404 or other HTTP error code (4xx or 5xx)
+exports.cancelBuild = (build, callback) =>
+  apiParams =
+    method: 'POST'
+    endpoint: 'builds/cancel'
+    query:
+      builddate: build
+
+  this.buildRequest apiParams, (error, result) =>
+    callback error if error
+    this.apiCall result, (err, res, data) ->
+      if err
+        callback new Error err
+      else if res.statusCode is 200 and res.statusMessage is 'OK'
+        callback null, res.statusMessage
+      else
+        callback data