77 | var events = require('events');
78 | var precond = require('precond');
79 | var util = require('util'); Copyright (c) 2012 Mathieu Turcotte
72 | Licensed under the MIT license.
73 |
77 | var events = require('events');
78 | var precond = require('precond');
79 | var util = require('util');A class to hold the state of a backoff operation. Accepts a backoff strategy 91 | to generate the backoff delays.
92 | 93 |function Backoff(backoffStrategy) {
96 | events.EventEmitter.call(this);
97 |
98 | this.backoffStrategy_ = backoffStrategy;
99 | this.maxNumberOfRetry_ = -1;
100 | this.backoffNumber_ = 0;
101 | this.backoffDelay_ = 0;
102 | this.timeoutID_ = -1;
103 |
104 | this.handlers = {
105 | backoff: this.onBackoff_.bind(this)
106 | };
107 | }
108 | util.inherits(Backoff, events.EventEmitter);Sets a limit, greater than 0, on the maximum number of backoffs. A ‘fail’ 120 | event will be emitted when the limit is reached.
121 | 122 |Backoff.prototype.failAfter = function(maxNumberOfRetry) {
125 | precond.checkArgument(maxNumberOfRetry > 0,
126 | 'Expected a maximum number of retry greater than 0 but got %s.',
127 | maxNumberOfRetry);
128 |
129 | this.maxNumberOfRetry_ = maxNumberOfRetry;
130 | };Starts a backoff operation. Accepts an optional parameter to let the 142 | listeners know why the backoff operation was started.
143 | 144 |Backoff.prototype.backoff = function(err) {
147 | precond.checkState(this.timeoutID_ === -1, 'Backoff in progress.');
148 |
149 | if (this.backoffNumber_ === this.maxNumberOfRetry_) {
150 | this.emit('fail', err);
151 | this.reset();
152 | } else {
153 | this.backoffDelay_ = this.backoffStrategy_.next();
154 | this.timeoutID_ = setTimeout(this.handlers.backoff, this.backoffDelay_);
155 | this.emit('backoff', this.backoffNumber_, this.backoffDelay_, err);
156 | }
157 | };Handles the backoff timeout completion.
169 | 170 |Backoff.prototype.onBackoff_ = function() {
173 | this.timeoutID_ = -1;
174 | this.emit('ready', this.backoffNumber_, this.backoffDelay_);
175 | this.backoffNumber_++;
176 | };Stops any backoff operation and resets the backoff delay to its inital value.
188 | 189 |Backoff.prototype.reset = function() {
192 | this.backoffNumber_ = 0;
193 | this.backoffStrategy_.reset();
194 | clearTimeout(this.timeoutID_);
195 | this.timeoutID_ = -1;
196 | };
197 |
198 | module.exports = Backoff; Copyright (c) 2012 Mathieu Turcotte
72 | Licensed under the MIT license.
73 |
77 | var util = require('util');
78 | var precond = require('precond');
79 |
80 | var BackoffStrategy = require('./strategy');Exponential backoff strategy.
92 | 93 |function ExponentialBackoffStrategy(options) {
96 | BackoffStrategy.call(this, options);
97 | this.backoffDelay_ = 0;
98 | this.nextBackoffDelay_ = this.getInitialDelay();
99 | this.factor_ = ExponentialBackoffStrategy.DEFAULT_FACTOR;
100 |
101 | if (options && options.factor !== undefined) {
102 | precond.checkArgument(options.factor > 1,
103 | 'Exponential factor should be greater than 1 but got %s.',
104 | options.factor);
105 | this.factor_ = options.factor;
106 | }
107 | }
108 | util.inherits(ExponentialBackoffStrategy, BackoffStrategy);Default multiplication factor used to compute the next backoff delay from 120 | the current one. The value can be overridden by passing a custom factor as 121 | part of the options.
122 | 123 |ExponentialBackoffStrategy.DEFAULT_FACTOR = 2;
126 |
127 | ExponentialBackoffStrategy.prototype.next_ = function() {
128 | this.backoffDelay_ = Math.min(this.nextBackoffDelay_, this.getMaxDelay());
129 | this.nextBackoffDelay_ = this.backoffDelay_ * this.factor_;
130 | return this.backoffDelay_;
131 | };
132 |
133 | ExponentialBackoffStrategy.prototype.reset_ = function() {
134 | this.backoffDelay_ = 0;
135 | this.nextBackoffDelay_ = this.getInitialDelay();
136 | };
137 |
138 | module.exports = ExponentialBackoffStrategy; Copyright (c) 2012 Mathieu Turcotte
72 | Licensed under the MIT license.
73 |
77 | var util = require('util');
78 |
79 | var BackoffStrategy = require('./strategy');Fibonacci backoff strategy.
91 | 92 |function FibonacciBackoffStrategy(options) {
95 | BackoffStrategy.call(this, options);
96 | this.backoffDelay_ = 0;
97 | this.nextBackoffDelay_ = this.getInitialDelay();
98 | }
99 | util.inherits(FibonacciBackoffStrategy, BackoffStrategy);
100 |
101 | FibonacciBackoffStrategy.prototype.next_ = function() {
102 | var backoffDelay = Math.min(this.nextBackoffDelay_, this.getMaxDelay());
103 | this.nextBackoffDelay_ += this.backoffDelay_;
104 | this.backoffDelay_ = backoffDelay;
105 | return backoffDelay;
106 | };
107 |
108 | FibonacciBackoffStrategy.prototype.reset_ = function() {
109 | this.nextBackoffDelay_ = this.getInitialDelay();
110 | this.backoffDelay_ = 0;
111 | };
112 |
113 | module.exports = FibonacciBackoffStrategy; Copyright (c) 2012 Mathieu Turcotte
72 | Licensed under the MIT license.
73 |
77 | var events = require('events');
78 | var precond = require('precond');
79 | var util = require('util');
80 |
81 | var Backoff = require('./backoff');
82 | var FibonacciBackoffStrategy = require('./strategy/fibonacci');Wraps a function to be called in a backoff loop.
94 | 95 |function FunctionCall(fn, args, callback) {
98 | events.EventEmitter.call(this);
99 |
100 | precond.checkIsFunction(fn, 'Expected fn to be a function.');
101 | precond.checkIsArray(args, 'Expected args to be an array.');
102 | precond.checkIsFunction(callback, 'Expected callback to be a function.');
103 |
104 | this.function_ = fn;
105 | this.arguments_ = args;
106 | this.callback_ = callback;
107 | this.lastResult_ = [];
108 | this.numRetries_ = 0;
109 |
110 | this.backoff_ = null;
111 | this.strategy_ = null;
112 | this.failAfter_ = -1;
113 |
114 | this.state_ = FunctionCall.State_.PENDING;
115 | }
116 | util.inherits(FunctionCall, events.EventEmitter);States in which the call can be.
128 | 129 |FunctionCall.State_ = {Call isn’t started yet.
143 | 144 | PENDING: 0,Call is in progress.
158 | 159 | RUNNING: 1,Call completed successfully which means that either the wrapped function 173 | returned successfully or the maximal number of backoffs was reached.
174 | 175 | COMPLETED: 2,The call was aborted.
189 | 190 | ABORTED: 3
193 | };Checks whether the call is pending.
205 | 206 |FunctionCall.prototype.isPending = function() {
209 | return this.state_ == FunctionCall.State_.PENDING;
210 | };Checks whether the call is in progress.
222 | 223 |FunctionCall.prototype.isRunning = function() {
226 | return this.state_ == FunctionCall.State_.RUNNING;
227 | };Checks whether the call is completed.
239 | 240 |FunctionCall.prototype.isCompleted = function() {
243 | return this.state_ == FunctionCall.State_.COMPLETED;
244 | };Checks whether the call is aborted.
256 | 257 |FunctionCall.prototype.isAborted = function() {
260 | return this.state_ == FunctionCall.State_.ABORTED;
261 | };Sets the backoff strategy to use. Can only be called before the call is 273 | started otherwise an exception will be thrown.
274 | 275 |FunctionCall.prototype.setStrategy = function(strategy) {
278 | precond.checkState(this.isPending(), 'FunctionCall in progress.');
279 | this.strategy_ = strategy;
280 | return this; // Return this for chaining.
281 | };Returns all intermediary results returned by the wrapped function since 293 | the initial call.
294 | 295 |FunctionCall.prototype.getLastResult = function() {
298 | return this.lastResult_.concat();
299 | };Returns the number of times the wrapped function call was retried.
311 | 312 |FunctionCall.prototype.getNumRetries = function() {
315 | return this.numRetries_;
316 | };Sets the backoff limit.
328 | 329 |FunctionCall.prototype.failAfter = function(maxNumberOfRetry) {
332 | precond.checkState(this.isPending(), 'FunctionCall in progress.');
333 | this.failAfter_ = maxNumberOfRetry;
334 | return this; // Return this for chaining.
335 | };Aborts the call.
347 | 348 |FunctionCall.prototype.abort = function() {
351 | precond.checkState(!this.isCompleted(), 'FunctionCall already completed.');
352 |
353 | if (this.isRunning()) {
354 | this.backoff_.reset();
355 | }
356 |
357 | this.state_ = FunctionCall.State_.ABORTED;
358 | };Initiates the call to the wrapped function. Accepts an optional factory 370 | function used to create the backoff instance; used when testing.
371 | 372 |FunctionCall.prototype.start = function(backoffFactory) {
375 | precond.checkState(!this.isAborted(), 'FunctionCall aborted.');
376 | precond.checkState(this.isPending(), 'FunctionCall already started.');
377 |
378 | var strategy = this.strategy_ || new FibonacciBackoffStrategy();
379 |
380 | this.backoff_ = backoffFactory ?
381 | backoffFactory(strategy) :
382 | new Backoff(strategy);
383 |
384 | this.backoff_.on('ready', this.doCall_.bind(this, true /* isRetry */));
385 | this.backoff_.on('fail', this.doCallback_.bind(this));
386 | this.backoff_.on('backoff', this.handleBackoff_.bind(this));
387 |
388 | if (this.failAfter_ > 0) {
389 | this.backoff_.failAfter(this.failAfter_);
390 | }
391 |
392 | this.state_ = FunctionCall.State_.RUNNING;
393 | this.doCall_(false /* isRetry */);
394 | };Calls the wrapped function.
406 | 407 |FunctionCall.prototype.doCall_ = function(isRetry) {
410 | if (isRetry) {
411 | this.numRetries_++;
412 | }
413 | var eventArgs = ['call'].concat(this.arguments_);
414 | events.EventEmitter.prototype.emit.apply(this, eventArgs);
415 | var callback = this.handleFunctionCallback_.bind(this);
416 | this.function_.apply(null, this.arguments_.concat(callback));
417 | };Calls the wrapped function’s callback with the last result returned by the 429 | wrapped function.
430 | 431 |FunctionCall.prototype.doCallback_ = function() {
434 | this.callback_.apply(null, this.lastResult_);
435 | };Handles wrapped function’s completion. This method acts as a replacement 447 | for the original callback function.
448 | 449 |FunctionCall.prototype.handleFunctionCallback_ = function() {
452 | if (this.isAborted()) {
453 | return;
454 | }
455 |
456 | var args = Array.prototype.slice.call(arguments);
457 | this.lastResult_ = args; // Save last callback arguments.
458 | events.EventEmitter.prototype.emit.apply(this, ['callback'].concat(args));
459 |
460 | if (args[0]) {
461 | this.backoff_.backoff(args[0]);
462 | } else {
463 | this.state_ = FunctionCall.State_.COMPLETED;
464 | this.doCallback_();
465 | }
466 | };Handles the backoff event by reemitting it.
478 | 479 |FunctionCall.prototype.handleBackoff_ = function(number, delay, err) {
482 | this.emit('backoff', number, delay, err);
483 | };
484 |
485 | module.exports = FunctionCall; Copyright (c) 2012 Mathieu Turcotte
72 | Licensed under the MIT license.
73 |
77 | var Backoff = require('./lib/backoff');
78 | var ExponentialBackoffStrategy = require('./lib/strategy/exponential');
79 | var FibonacciBackoffStrategy = require('./lib/strategy/fibonacci');
80 | var FunctionCall = require('./lib/function_call.js');
81 |
82 | module.exports.Backoff = Backoff;
83 | module.exports.FunctionCall = FunctionCall;
84 | module.exports.FibonacciStrategy = FibonacciBackoffStrategy;
85 | module.exports.ExponentialStrategy = ExponentialBackoffStrategy;Constructs a Fibonacci backoff.
97 | 98 |module.exports.fibonacci = function(options) {
101 | return new Backoff(new FibonacciBackoffStrategy(options));
102 | };Constructs an exponential backoff.
114 | 115 |module.exports.exponential = function(options) {
118 | return new Backoff(new ExponentialBackoffStrategy(options));
119 | };Constructs a FunctionCall for the given function and arguments.
131 | 132 |module.exports.call = function(fn, vargs, callback) {
135 | var args = Array.prototype.slice.call(arguments);
136 | fn = args[0];
137 | vargs = args.slice(1, args.length - 1);
138 | callback = args[args.length - 1];
139 | return new FunctionCall(fn, vargs, callback);
140 | }; Copyright (c) 2012 Mathieu Turcotte
72 | Licensed under the MIT license.
73 |
77 | var events = require('events');
78 | var util = require('util');
79 |
80 | function isDef(value) {
81 | return value !== undefined && value !== null;
82 | }Abstract class defining the skeleton for the backoff strategies. Accepts an 94 | object holding the options for the backoff strategy:
95 |randomisationFactor: The randomisation factor which must be between 0
97 | and 1 where 1 equates to a randomization factor of 100% and 0 to no
98 | randomization.initialDelay: The backoff initial delay in milliseconds.maxDelay: The backoff maximal delay in milliseconds.function BackoffStrategy(options) {
106 | options = options || {};
107 |
108 | if (isDef(options.initialDelay) && options.initialDelay < 1) {
109 | throw new Error('The initial timeout must be greater than 0.');
110 | } else if (isDef(options.maxDelay) && options.maxDelay < 1) {
111 | throw new Error('The maximal timeout must be greater than 0.');
112 | }
113 |
114 | this.initialDelay_ = options.initialDelay || 100;
115 | this.maxDelay_ = options.maxDelay || 10000;
116 |
117 | if (this.maxDelay_ <= this.initialDelay_) {
118 | throw new Error('The maximal backoff delay must be ' +
119 | 'greater than the initial backoff delay.');
120 | }
121 |
122 | if (isDef(options.randomisationFactor) &&
123 | (options.randomisationFactor < 0 || options.randomisationFactor > 1)) {
124 | throw new Error('The randomisation factor must be between 0 and 1.');
125 | }
126 |
127 | this.randomisationFactor_ = options.randomisationFactor || 0;
128 | }Gets the maximal backoff delay.
140 | 141 |BackoffStrategy.prototype.getMaxDelay = function() {
144 | return this.maxDelay_;
145 | };Gets the initial backoff delay.
157 | 158 |BackoffStrategy.prototype.getInitialDelay = function() {
161 | return this.initialDelay_;
162 | };Template method that computes and returns the next backoff delay in 174 | milliseconds.
175 | 176 |BackoffStrategy.prototype.next = function() {
179 | var backoffDelay = this.next_();
180 | var randomisationMultiple = 1 + Math.random() * this.randomisationFactor_;
181 | var randomizedDelay = Math.round(backoffDelay * randomisationMultiple);
182 | return randomizedDelay;
183 | };Computes and returns the next backoff delay. Intended to be overridden by 195 | subclasses.
196 | 197 |BackoffStrategy.prototype.next_ = function() {
200 | throw new Error('BackoffStrategy.next_() unimplemented.');
201 | };Template method that resets the backoff delay to its initial value.
213 | 214 |BackoffStrategy.prototype.reset = function() {
217 | this.reset_();
218 | };Resets the backoff delay to its initial value. Intended to be overridden by 230 | subclasses.
231 | 232 |BackoffStrategy.prototype.reset_ = function() {
235 | throw new Error('BackoffStrategy.reset_() unimplemented.');
236 | };
237 |
238 | module.exports = BackoffStrategy;