From 93b34713c3260580104735a7ace107db2bc67b8d Mon Sep 17 00:00:00 2001 From: oleg Date: Thu, 7 Jan 2016 23:48:31 +0300 Subject: [PATCH] add doc for bulds collection + small api fixes --- docs/developing-plugins/builds-collection.md | 50 ++++++++++++++++ lib/build.js | 62 +++++++++++++++++++- lib/distributor.js | 19 +++--- package.json | 2 + resources/builds.js | 2 +- test/distributor/main.js | 4 +- 6 files changed, 126 insertions(+), 13 deletions(-) create mode 100644 docs/developing-plugins/builds-collection.md diff --git a/docs/developing-plugins/builds-collection.md b/docs/developing-plugins/builds-collection.md new file mode 100644 index 0000000..90e771c --- /dev/null +++ b/docs/developing-plugins/builds-collection.md @@ -0,0 +1,50 @@ + +## BuildsCollection() + + Facade entity which accumulates operations with currently running and + db saved builds. + +## BuildsCollection.create(params:Object, [callback(err)]:Function) + + Create build by running given project. + - `params.projectName` - project to build + - `params.withScmChangesOnly` - if true then build will be started only if + there is scm changes for project + - `params.queueQueued` - if true then currently queued project can be queued + again + - `params.initiator` - contains information about initiator of the build, + must contain `type` property e.g. when one build triggers another: + initiator: {type: 'build', id: 123, number: 10, project: {name: 'project1'} + +## BuildsCollection.cancel(id:Number, [callback(err)]:Function) + + Cancel build by id. + Note that only queued build can be canceled currently. + +## BuildsCollection.get(id:Number, callback(err,build):Function) + + Get build by id. + +## BuildsCollection.getLogLines(params:Object, callback(err,logLinesData):Function) + + Get log lines for the given build. + - `params.buildId` - target build + - `params.from` - if set then lines from that number will be returned + - `params.to` - if set then lines to that number will be returned + +## BuildsCollection.getAvgBuildDuration(builds:Array.) + + Calculate average build duration for the given builds. + +## BuildsCollection.getRecent(params:Object, callback(err,builds):Function) + + Get builds sorted by date in descending order. + - `params.projectName` - optional project filter + - `params.status` - optional status filter, can be used only when + `params.projectName` is set. When used builds in the result will contain + only following fields: id, number, startDate, endDate + +## BuildsCollection.getDoneStreak(params:Object, callback(err,doneStreak):Function) + + Get info about current done builds streak. + - `params.projectName` - optional project filter diff --git a/lib/build.js b/lib/build.js index ffcdb93..072d70f 100644 --- a/lib/build.js +++ b/lib/build.js @@ -30,20 +30,56 @@ BuildsCollection.prototype._proxyDistributorEvent = function(source, dest) { }); }; +/** + * Create build by running given project. + * - `params.projectName` - project to build + * - `params.withScmChangesOnly` - if true then build will be started only if + * there is scm changes for project + * - `params.queueQueued` - if true then currently queued project can be queued + * again + * - `params.initiator` - contains information about initiator of the build, + * must contain `type` property e.g. when one build triggers another: + * initiator: {type: 'build', id: 123, number: 10, project: {name: 'project1'} + * + * @param {Object} params + * @param {Function} [callback(err)] + */ BuildsCollection.prototype.create = function(params, callback) { this.distributor.run(params, callback); }; -BuildsCollection.prototype.cancel = function(params, callback) { - this.distributor.cancel(params, callback); +/** + * Cancel build by id. + * Note that only queued build can be canceled currently. + * + * @param {Number} id + * @param {Function} [callback(err)] + */ +BuildsCollection.prototype.cancel = function(id, callback) { + this.distributor.cancel(id, callback); }; +/** + * Get build by id. + * + * @param {Number} id + * @param {Function} callback(err,build) + */ BuildsCollection.prototype.get = function(id, callback) { this.db.builds.find({start: {id: id}}, function(err, builds) { callback(err, builds && builds[0]); }); }; +/** + * Get log lines for the given build. + * - `params.buildId` - target build + * - `params.from` - if set then lines from that number will be returned + * - `params.to` - if set then lines to that number will be returned + * + * @param {Object} params + * @param {Function} callback(err,logLinesData) + */ BuildsCollection.prototype.getLogLines = function(params, callback) { var self = this; @@ -95,6 +131,11 @@ BuildsCollection.prototype.getLogLinesTail = function(params, callback) { ); }; +/** + * Calculate average build duration for the given builds. + * + * @param {Object[]} builds + */ BuildsCollection.prototype.getAvgBuildDuration = function(builds) { var durationsSum = _(builds).reduce(function(sum, build) { return sum + (build.endDate - build.startDate); @@ -102,6 +143,16 @@ BuildsCollection.prototype.getAvgBuildDuration = function(builds) { return Math.round(durationsSum / builds.length); }; +/** + * Get builds sorted by date in descending order. + * - `params.projectName` - optional project filter + * - `params.status` - optional status filter, can be used only when + * `params.projectName` is set. When used builds in the result will contain + * only following fields: id, number, startDate, endDate + * + * @param {Object} params + * @param {Function} callback(err,builds) + */ BuildsCollection.prototype.getRecent = function(params, callback) { params.limit = params.limit || 20; var self = this; @@ -127,6 +178,13 @@ BuildsCollection.prototype.getRecent = function(params, callback) { ); }; +/** + * Get info about current done builds streak. + * - `params.projectName` - optional project filter + * + * @param {Object} params + * @param {Function} callback(err,doneStreak) + */ BuildsCollection.prototype.getDoneStreak = function(params, callback) { var self = this; diff --git a/lib/distributor.js b/lib/distributor.js index d6efee7..9d244b9 100644 --- a/lib/distributor.js +++ b/lib/distributor.js @@ -286,17 +286,21 @@ Distributor.prototype._updateBuild = function(build, changes, callback) { ); }; -Distributor.prototype.cancel = function(params, callback) { +Distributor.prototype.cancel = function(id, callback) { + callback = callback || function(err) { + if (err) logger.error('Error during cancel: ', err.stack || err); + }; var self = this; + Steppy( function() { var queueItemIndex = _(self.queue).findIndex(function(item) { - return item.build.id === params.buildId; + return item.build.id === id; }); if (queueItemIndex === -1) { throw new Error( - 'Build with id "' + params.buildId + '" not found for cancel' + 'Build with id "' + id + '" not found for cancel' ); } @@ -317,13 +321,12 @@ Distributor.prototype.cancel = function(params, callback) { }; Distributor.prototype.run = function(params, callback) { + callback = callback || function(err) { + if (err) logger.error('Error during run: ', err.stack || err); + }; var self = this, project; - callback = callback || function(err) { - if (err) { - logger.error('Error during run: ', err.stack || err); - } - }; + Steppy( function() { project = _(self.projects.get(params.projectName)).clone(); diff --git a/package.json b/package.json index 5fe9e43..5bbf4e1 100644 --- a/package.json +++ b/package.json @@ -11,6 +11,8 @@ "dev": "gulp", "sync": "npm install && npm prune && bower install && bower prune", "docProjectsCollection": "dox --api --skipSingleStar < lib/project.js | sed '/^ - \\[ProjectsCollection/ d' > docs/developing-plugins/projects-collection.md", + "docBuildsCollection": "dox --api --skipSingleStar < lib/build.js | sed '/^ - \\[BuildsCollection/ d' > docs/developing-plugins/builds-collection.md", + "doc": "nrun docProjectsCollection && nrun docBuildsCollection", "buildJs": "r.js -o static/js/requirejs/buid.js", "buildClean": "rm static/index.html", "buildHtml": "jade views/index.jade --obj '{\"env\": \"production\"}' -o static/", diff --git a/resources/builds.js b/resources/builds.js index 8bc61c9..c7567c0 100644 --- a/resources/builds.js +++ b/resources/builds.js @@ -84,7 +84,7 @@ module.exports = function(app) { function() { var buildId = req.data.buildId; logger.log('Cancel build: "%s"', buildId); - app.builds.cancel({buildId: buildId}, this.slot()); + app.builds.cancel(buildId, this.slot()); }, function() { res.send(); diff --git a/test/distributor/main.js b/test/distributor/main.js index c4b3dab..7c03656 100644 --- a/test/distributor/main.js +++ b/test/distributor/main.js @@ -155,7 +155,7 @@ describe('Distributor main', function() { var originalRunNext = distributor._runNext; distributor._runNext = function() { - distributor.cancel({buildId: 1}, function(err) { + distributor.cancel(1, function(err) { cancelError = err; }); originalRunNext.apply(distributor, arguments); @@ -198,7 +198,7 @@ describe('Distributor main', function() { var originalRunNext = distributor._runNext; distributor._runNext = function() { - distributor.cancel({buildId: 2}, function(err) { + distributor.cancel(2, function(err) { cancelError = err; }); originalRunNext.apply(distributor, arguments);