Make maximum transaction retry time configurable

Commit makes driver aware of a new config property `maxTransactionRetryTime`
to tune amount of time transactions executed via
`Session#readTransaction(function(Transaction))` and
`Session#writeTransaction(function(Transaction))` can be retried.

It also adds JSDoc for `connectionPoolSize` property.

Author: lutovich

src/v1/driver.js

@@ -115,7 +115,7 @@ class Driver {
    */
   session(mode, bookmark) {
     const sessionMode = Driver._validateSessionMode(mode);
-    return this._createSession(sessionMode, this._connectionProvider, bookmark);
+    return this._createSession(sessionMode, this._connectionProvider, bookmark, this._config);
   }
 
   static _validateSessionMode(rawMode) {
@@ -132,8 +132,8 @@ class Driver {
   }
 
   //Extension point
-  _createSession(mode, connectionProvider, bookmark) {
-    return new Session(mode, connectionProvider, bookmark);
+  _createSession(mode, connectionProvider, bookmark, config) {
+    return new Session(mode, connectionProvider, bookmark, config);
   }
 
   _driverOnErrorCallback(error) {

src/v1/index.js

@@ -100,6 +100,16 @@ let USER_AGENT = "neo4j-javascript/" + VERSION;
  *       // port, and this is then used to verify the host certificate does not change.
  *       // This setting has no effect unless TRUST_ON_FIRST_USE is enabled.
  *       knownHosts:"~/.neo4j/known_hosts",
+ *
+ *       // The max number of connections that are allowed idle in the pool at any time.
+ *       // Connection will be destroyed if this threshold is exceeded.
+ *       connectionPoolSize: 50,
+ *
+ *       // Specify the maximum time in milliseconds transactions are allowed to retry via
+ *       // {@link Session#readTransaction()} and {@link Session#writeTransaction()} functions. These functions
+ *       // will retry the given unit of work on `ServiceUnavailable`, `SessionExpired` and transient errors with
+ *       // exponential backoff using initial delay of 1 second. Default value is 30000 which is 30 seconds.
+ *       maxTransactionRetryTime: 30000,
  *     }
  *
  * @param {string} url The URL for the Neo4j database, for instance "bolt://localhost"

src/v1/internal/transaction-executor.js

@@ -27,10 +27,10 @@ const DEFAULT_RETRY_DELAY_JITTER_FACTOR = 0.2;
 export default class TransactionExecutor {
 
   constructor(maxRetryTimeMs, initialRetryDelayMs, multiplier, jitterFactor) {
-    this._maxRetryTimeMs = maxRetryTimeMs || DEFAULT_MAX_RETRY_TIME_MS;
-    this._initialRetryDelayMs = initialRetryDelayMs || DEFAULT_INITIAL_RETRY_DELAY_MS;
-    this._multiplier = multiplier || DEFAULT_RETRY_DELAY_MULTIPLIER;
-    this._jitterFactor = jitterFactor || DEFAULT_RETRY_DELAY_JITTER_FACTOR;
+    this._maxRetryTimeMs = _valueOrDefault(maxRetryTimeMs, DEFAULT_MAX_RETRY_TIME_MS);
+    this._initialRetryDelayMs = _valueOrDefault(initialRetryDelayMs, DEFAULT_INITIAL_RETRY_DELAY_MS);
+    this._multiplier = _valueOrDefault(multiplier, DEFAULT_RETRY_DELAY_MULTIPLIER);
+    this._jitterFactor = _valueOrDefault(jitterFactor, DEFAULT_RETRY_DELAY_JITTER_FACTOR);
 
     this._inFlightTimeoutIds = [];
 
@@ -140,3 +140,10 @@ export default class TransactionExecutor {
     }
   }
 };
+
+function _valueOrDefault(value, defaultValue) {
+  if (value || value === 0) {
+    return value;
+  }
+  return defaultValue;
+}

src/v1/routing-driver.js

@@ -35,8 +35,8 @@ class RoutingDriver extends Driver {
     return new LoadBalancer(address, connectionPool, driverOnErrorCallback);
   }
 
-  _createSession(mode, connectionProvider, bookmark) {
-    return new RoutingSession(mode, connectionProvider, bookmark, (error, conn) => {
+  _createSession(mode, connectionProvider, bookmark, config) {
+    return new RoutingSession(mode, connectionProvider, bookmark, config, (error, conn) => {
       if (error.code === SERVICE_UNAVAILABLE || error.code === SESSION_EXPIRED) {
         // connection is undefined if error happened before connection was acquired
         if (conn) {
@@ -66,8 +66,8 @@ class RoutingDriver extends Driver {
 }
 
 class RoutingSession extends Session {
-  constructor(mode, connectionProvider, bookmark, onFailedConnection) {
-    super(mode, connectionProvider, bookmark);
+  constructor(mode, connectionProvider, bookmark, config, onFailedConnection) {
+    super(mode, connectionProvider, bookmark, config);
     this._onFailedConnection = onFailedConnection;
   }
 

src/v1/session.js

@@ -38,15 +38,16 @@ class Session {
    * @param {string} mode the default access mode for this session.
    * @param {ConnectionProvider} connectionProvider - the connection provider to acquire connections from.
    * @param {string} [bookmark=undefined] - the initial bookmark for this session.
+   * @param {Object} [config={}] - this driver configuration.
    */
-  constructor(mode, connectionProvider, bookmark) {
+  constructor(mode, connectionProvider, bookmark, config) {
     this._mode = mode;
     this._readConnectionHolder = new ConnectionHolder(READ, connectionProvider);
     this._writeConnectionHolder = new ConnectionHolder(WRITE, connectionProvider);
     this._open = true;
     this._hasTx = false;
     this._lastBookmark = bookmark;
-    this._transactionExecutor = new TransactionExecutor()
+    this._transactionExecutor = _createTransactionExecutor(config);
   }
 
   /**
@@ -134,7 +135,7 @@ class Session {
    * Transaction will automatically be committed unless the given function throws or returns a rejected promise.
    * Some failures of the given function or the commit itself will be retried with exponential backoff with initial
    * delay of 1 second and maximum retry time of 30 seconds. Maximum retry time is configurable via driver config's
-   * {@link #maxTransactionRetryTime} property in milliseconds.
+   * <code>maxTransactionRetryTime</code> property in milliseconds.
    *
    * @param {function(Transaction)} transactionWork - callback that executes operations against
    * a given {@link Transaction}.
@@ -151,7 +152,7 @@ class Session {
    * Transaction will automatically be committed unless the given function throws or returns a rejected promise.
    * Some failures of the given function or the commit itself will be retried with exponential backoff with initial
    * delay of 1 second and maximum retry time of 30 seconds. Maximum retry time is configurable via driver config's
-   * {@link #maxTransactionRetryTime} property in milliseconds.
+   * <code>maxTransactionRetryTime</code> property in milliseconds.
    *
    * @param {function(Transaction)} transactionWork - callback that executes operations against
    * a given {@link Transaction}.
@@ -232,4 +233,9 @@ class _RunObserver extends StreamObserver {
   }
 }
 
+function _createTransactionExecutor(config) {
+  const maxRetryTimeMs = (config && config.maxTransactionRetryTime) ? config.maxTransactionRetryTime : null;
+  return new TransactionExecutor(maxRetryTimeMs);
+}
+
 export default Session;

test/internal/transaction-executor.test.js

@@ -150,6 +150,25 @@ describe('TransactionExecutor', () => {
     }, 1000);
   });
 
+  it('should allow zero max retry time', () => {
+    const executor = new TransactionExecutor(0);
+    expect(executor._maxRetryTimeMs).toEqual(0);
+  });
+
+  it('should allow zero initial delay', () => {
+    const executor = new TransactionExecutor(42, 0);
+    expect(executor._initialRetryDelayMs).toEqual(0);
+  });
+
+  it('should disallow zero multiplier', () => {
+    expect(() => new TransactionExecutor(42, 42, 0)).toThrow();
+  });
+
+  it('should allow zero jitter factor', () => {
+    const executor = new TransactionExecutor(42, 42, 42, 0);
+    expect(executor._jitterFactor).toEqual(0);
+  });
+
   function testRetryWhenTransactionCreatorFails(errorCodes, done) {
     const executor = new TransactionExecutor();
     const transactionCreator = throwingTransactionCreator(errorCodes, new FakeTransaction());

test/v1/examples.test.js

@@ -97,7 +97,7 @@ describe('examples', function() {
     });
   });
 
-  it('should be able to configure session pool size', function (done) {
+  it('should be able to configure connection pool size', function (done) {
    var neo4j = neo4jv1;
     // tag::configuration[]
     var driver = neo4j.driver("bolt://localhost:7687", neo4j.auth.basic("neo4j", "neo4j"), {connectionPoolSize: 50});
@@ -118,6 +118,17 @@ describe('examples', function() {
     });
   });
 
+  it('should be able to configure maximum transaction retry time', function () {
+    var neo4j = neo4jv1;
+    // tag::configuration[]
+    var maxRetryTimeMs = 45 * 1000; // 45 seconds
+    var driver = neo4j.driver('bolt://localhost:7687', neo4j.auth.basic('neo4j', 'neo4j'), {maxTransactionRetryTime: maxRetryTimeMs});
+    //end::configuration[]
+
+    var session = driver.session();
+    expect(session._transactionExecutor._maxRetryTimeMs).toBe(maxRetryTimeMs);
+  });
+
   it('should document a statement', function(done) {
     var session = driverGlobal.session();
     // tag::statement[]