From 3e617a81cfd3509b118808bb17f658820ac6800e Mon Sep 17 00:00:00 2001 From: Hornwitser Date: Tue, 17 Aug 2021 05:07:46 +0200 Subject: [PATCH] Add exponential backoff helper Add helper class for implementing exponential backoff delay. --- packages/lib/ExponentialBackoff.js | 85 ++++++++++++++++++++++++++++++ packages/lib/browser.js | 1 + packages/lib/index.js | 2 + test/lib/ExponentialBackoff.js | 57 ++++++++++++++++++++ 4 files changed, 145 insertions(+) create mode 100644 packages/lib/ExponentialBackoff.js create mode 100644 test/lib/ExponentialBackoff.js diff --git a/packages/lib/ExponentialBackoff.js b/packages/lib/ExponentialBackoff.js new file mode 100644 index 00000000..f8c30516 --- /dev/null +++ b/packages/lib/ExponentialBackoff.js @@ -0,0 +1,85 @@ +"use strict"; + + +/** + * Helper class for implementing the exponential backoff algorithm + * + * Provides a convenient interface for implementing an exponential backoff + * when reconnecting or resending in a distributed network. + * + * Once instantiated the delay method will return the next interval to wait + * for in milliseconds before making another attempt. For each attempt the + * delay chosen is a random value between 0 and the current maximum delay + * wwhich starts at a value of 2 * `base` and doubles for ever attempt up to + * the passed value of `max`. The value for the delay will reset back to + * `base` if more time than the value for `reset` has passed between two + * invocations of delay. + * + * @alias module:lib/ExponentialBackoff + */ +class ExponentialBackoff { + /** + * Construct ExponentialBackoff helper + * + * The options passed may also be modified on the instance at runtime. + * + * @param {object=} options - + * Options for this exponential backoff helper + * @param {number=} [options.base=1] - + * Base delay in seconds. The first delay will on average be this + * long, but can be anywhere between 0 and 2 times this value. + * @param {number=} [options.max=60] - + * Maximum delay in seconds. A delay will not take more than this + * value. + * @param {number=} [options.reset=2*max] - + * Time in seconds between two invocations of delay which will cause + * it to start over with `base` instead of doubling. + */ + constructor(options = {}) { + /** + * Base delay in seconds. The first delay will on average be this + * long, but can be anywhere between 0 and 2 times this value. + * @type {number} + */ + this.base = options.base || 1; + /** + * Maximum delay in seconds. A delay will not take more than this + * value. + * @type {number} + */ + this.max = options.max || 60; + /** + * Time in seconds between two invocations of delay which will cause + * it to start over with `base` instead of doubling. + * @type {number} + */ + this.reset = options.reset || 2 * this.max; + + this._exp = 0; + this._lastInvocationTime = Date.now(); + } + + /** + * Compute the next delay to wait + * + * Returns the next delay to wait according to the exponential backoff + * algorithm. This is a value between 0 and min(2 * options.base * + * 2retries, optinos.max). + * + * @returns {number} time in milliseconds to wait. + */ + delay() { + let invocationTime = Date.now(); + let interval = (invocationTime - this._lastInvocationTime) / 1000; + this._lastInvocationTime = invocationTime; + + if (interval > this.reset) { + this._exp = 0; + } + + this._exp = Math.min(this._exp + 1, Math.log2(this.max)); + return Math.random() * this.base * 2 ** this._exp * 1000; + } +} + +module.exports = ExponentialBackoff; diff --git a/packages/lib/browser.js b/packages/lib/browser.js index 35623b28..23c9850e 100644 --- a/packages/lib/browser.js +++ b/packages/lib/browser.js @@ -8,4 +8,5 @@ export { default as libPlugin } from "./plugin"; export { default as libSchema } from "./schema"; export { default as libUsers } from "./users"; +export { default as ExponentialBackoff } from "./ExponentialBackoff"; export { default as RateLimiter } from "./RateLimiter"; diff --git a/packages/lib/index.js b/packages/lib/index.js index b2929a4d..0c89ef93 100644 --- a/packages/lib/index.js +++ b/packages/lib/index.js @@ -19,6 +19,7 @@ const libSchema = require("./schema"); const libSharedCommands = require("./shared_commands"); const libUsers = require("./users"); +const ExponentialBackoff = require("./ExponentialBackoff"); const RateLimiter = require("./RateLimiter"); @@ -43,5 +44,6 @@ module.exports = { libSharedCommands, libUsers, + ExponentialBackoff, RateLimiter, }; diff --git a/test/lib/ExponentialBackoff.js b/test/lib/ExponentialBackoff.js new file mode 100644 index 00000000..9234cf21 --- /dev/null +++ b/test/lib/ExponentialBackoff.js @@ -0,0 +1,57 @@ +"use strict"; +const assert = require("assert").strict; + +const ExponentialBackoff = require("@clusterio/lib/ExponentialBackoff"); + +describe("lib/ExponentialBackoff", function() { + describe("class RateLimiter", function() { + it("should give a delay", function() { + let backoff = new ExponentialBackoff(); + assert.equal(typeof backoff.delay(), "number"); + }); + + it("should give exponentially increasing delays", function() { + let buckets = []; + for (let i = 0; i < 100; i++) { + let backoff = new ExponentialBackoff({ base: 1, max: 1024 }); + for (let j = 0; j < 10; j++) { + buckets[j] = (buckets[j] || 0) + backoff.delay(); + } + } + + for (let i = 0; i < 10; i++) { + let average = buckets[i] / 100 / 1000; // Divide by 1000 for ms to s conversion. + let scale = 2 ** i; + // Eyeball statistics told me that a deviation of about 40% + // of the expected average would be 6 standard deviations + // for a sum of 100 values and thus highly improbable. + assert( + average / scale > 0.6 && average / scale < 1.4, + `Expected average to be in range ${scale * 0.6} to ${scale * 1.4} but got ${average}` + ); + } + }); + + it("should not exceed max value", function() { + for (let max of [0.1, 0.5, 1, 2, 50, 100, 1000, 100000]) { + let backoff = new ExponentialBackoff({ base: 1, max }); + for (let j = 0; j < 100; j++) { + let value = backoff.delay() / 1000; // Divide by 100 for ms to s conversion + assert(value <= max, `delay returned a value greater than max: ${value} > ${max}`); + } + } + }); + + it("should reset if enough time passes", function() { + let backoff = new ExponentialBackoff({ reset: 100 }); + backoff.delay(); + assert.equal(backoff._exp, 1); + backoff._lastInvocationTime = Date.now() - 99 * 1000; + backoff.delay(); + assert.equal(backoff._exp, 2); + backoff._lastInvocationTime = Date.now() - 101 * 1000; + backoff.delay(); + assert.equal(backoff._exp, 1); + }); + }); +});