oracledb 5.2.0 → 5.5.0

package/lib/connection.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2016, 2021, Oracle and/or its affiliates. All rights reserved
+// Copyright (c) 2016, 2022, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -172,7 +172,20 @@ async function close(a1) {
     nodbUtil.assert(nodbUtil.isObject(a1), 'NJS-005', 1);
     options = a1;
   }
-  await this._close(options);
+
+  // If already in the process of closing, throw an error instead of doing
+  // a roundtrip
+  if (this._closing) {
+    throw new Error (nodbUtil.getErrorMessage('NJS-003'));
+  }
+
+  this._closing = true;
+  try {
+    await this._close(options);
+  } finally {
+    this._closing = false;
+  }
+
   for (const cls of Object.values(this._dbObjectClasses)) {
     cls.prototype.constructor = Object;
     cls.prototype = null;
@@ -314,6 +327,144 @@ function buildDbObjectClass(schema, name, fqn) {
   return (DbObject);
 }
 
+//-----------------------------------------------------------------------------
+//  tpcBegin()
+//    Starts a two-phase-commit transaction
+//----------------------------------------------------------------------------
+async function tpcBegin(xid, flag, timeout) {
+  nodbUtil.checkArgCount(arguments, 1, 3);
+  nodbUtil.assert(nodbUtil.isXid(xid), 'NJS-005', 1);
+
+  if (arguments.length < 3) {
+    timeout = 60;   // seconds
+  } else {
+    nodbUtil.assert(typeof timeout === 'number', 'NJS-005', 3);
+  }
+
+  if (arguments.length < 2) {
+    flag = this._oracledb.TPC_BEGIN_NEW;
+  } else {
+    nodbUtil.assert(typeof flag === 'number', 'NJS-005', 2);
+  }
+  await this._tpcBegin(xid, flag, timeout);
+}
+
+
+//-----------------------------------------------------------------------------
+//  tpcCommit
+//    Commit the two-phase-commit transaction
+//-----------------------------------------------------------------------------
+async function tpcCommit(xid, onePhase) {
+  nodbUtil.checkArgCount(arguments, 0, 2);
+
+  if (arguments.length < 2) {
+    onePhase = false;
+  } else {
+    nodbUtil.assert(typeof onePhase === 'boolean', 'NJS-005', 2);
+  }
+  if (arguments.length >= 1) {
+    nodbUtil.assert(nodbUtil.isXid(xid), 'NJS-005', 1);
+  }
+  await this._tpcCommit(xid, onePhase);
+}
+
+
+//-----------------------------------------------------------------------------
+//  tpcEnd
+//    Ends the two-phase-commit transaction
+//-----------------------------------------------------------------------------
+async function tpcEnd(xid, flag) {
+  nodbUtil.checkArgCount(arguments, 0, 2);
+
+  if (arguments.length < 2) {
+    flag = this._oracledb.TPC_END_NORMAL;
+  } else {
+    nodbUtil.assert(typeof flag === 'number', 'NJS-005', 2);
+  }
+
+  if (arguments.length >= 1) {
+    nodbUtil.assert(nodbUtil.isXid(xid), 'NJS-005', 1);
+  }
+
+  await this._tpcEnd(xid, flag);
+}
+
+
+//-----------------------------------------------------------------------------
+//  tpcForget
+//    causes the server to forget a heuristically completed global transaction.
+//-----------------------------------------------------------------------------
+async function tpcForget(xid) {
+
+  nodbUtil.checkArgCount(arguments, 1, 1);
+  nodbUtil.assert(nodbUtil.isXid(xid), 'NJS-005', 1);
+
+  await this._tpcForget(xid);
+}
+
+
+//-----------------------------------------------------------------------------
+//  tpcPrepare
+//    prepares a global transaction for commit.
+//-----------------------------------------------------------------------------
+async function tpcPrepare(xid) {
+  nodbUtil.checkArgCount(arguments, 0, 1);
+
+  if (arguments.length >= 1) {
+    nodbUtil.assert(nodbUtil.isXid(xid), 'NJS-005', 1);
+  }
+
+  return await this._tpcPrepare(xid);
+}
+
+
+//-----------------------------------------------------------------------------
+//  tpcRecover
+//    Returns a list of pending transactions
+//-----------------------------------------------------------------------------
+async function tpcRecover(asString) {
+  nodbUtil.checkArgCount(arguments, 0, 1);
+
+  if (arguments.length == 1) {
+    nodbUtil.assert(typeof asString === 'boolean', 'NJS-005', 1);
+  } else {
+    asString = true;
+  }
+
+  const sqlStr = `
+    SELECT
+        formatid as "formatId",
+        UTL_RAW.CAST_TO_VARCHAR2(globalid) as "globalTransactionId",
+        UTL_RAW.CAST_TO_VARCHAR2(branchid) as "branchQualifier"
+    FROM DBA_PENDING_TRANSACTIONS`;
+  const sqlBuf = `
+    SELECT
+        formatid as "formatId",
+        globalid as "globalTransactionId",
+        branchid as "branchQualifier"
+    FROM DBA_PENDING_TRANSACTIONS`;
+  const options = {
+    outFormat: this._oracledb.OUT_FORMAT_OBJECT,
+  };
+
+  const result = await this._execute(asString ? sqlStr : sqlBuf, {}, options);
+  return result.resultSet._getAllRows(options, result.metaData, false);
+}
+
+
+//-----------------------------------------------------------------------------
+//  tpcRollback()
+//    Rollbacks the current changes in two-phase-commit
+//-----------------------------------------------------------------------------
+async function tpcRollback(xid) {
+  nodbUtil.checkArgCount(arguments, 0, 1);
+  if (arguments.length == 1) {
+    nodbUtil.assert(nodbUtil.isXid(xid), 'NJS-005', 1);
+  }
+
+  await this._tpcRollback(xid);
+}
+
 
 // define class
 class Connection extends EventEmitter {
@@ -323,6 +474,7 @@ class Connection extends EventEmitter {
     this._dbObjectClasses = {};
     this._requestQueue = [];
     this._inProgress = false;
+    this._closing = false;
   }
 
   // extend class with promisified functions
@@ -344,6 +496,13 @@ class Connection extends EventEmitter {
     this.shutdown = nodbUtil.callbackify(nodbUtil.serialize(shutdown));
     this.startup = nodbUtil.callbackify(nodbUtil.serialize(startup));
     this.subscribe = nodbUtil.callbackify(nodbUtil.serialize(subscribe));
+    this.tpcBegin = nodbUtil.callbackify(nodbUtil.serialize(tpcBegin));
+    this.tpcCommit = nodbUtil.callbackify(nodbUtil.serialize(tpcCommit));
+    this.tpcEnd = nodbUtil.callbackify(nodbUtil.serialize(tpcEnd));
+    this.tpcForget = nodbUtil.callbackify(nodbUtil.serialize(tpcForget));
+    this.tpcPrepare = nodbUtil.callbackify(nodbUtil.serialize(tpcPrepare));
+    this.tpcRecover = nodbUtil.callbackify(nodbUtil.serialize(tpcRecover));
+    this.tpcRollback = nodbUtil.callbackify(nodbUtil.serialize(tpcRollback));
     this.unsubscribe = nodbUtil.callbackify(nodbUtil.serialize(unsubscribe));
   }
 
@@ -395,6 +554,18 @@ class Connection extends EventEmitter {
     return (this._getSodaDatabase());
   }
 
+  //--------------------------------------------------------------------------
+  //  isHealthy()
+  //    To get the health status of the connection.
+  //  NOTE: if this function returns false, the application must close the
+  //        connection obect.
+  //        This is a synchronous call.
+  //---------------------------------------------------------------------------
+  isHealthy() {
+    return (!this._closing && this._isHealthy());
+  }
+
+
   // The queryStream function is similar to execute except that it immediately
   // returns a QueryStream.
   queryStream(sql, binding, options) {

package/lib/dbObject.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2019, 2021, Oracle and/or its affiliates.  All rights reserved.
+// Copyright (c) 2019, 2022, Oracle and/or its affiliates.
 //
 //----------------------------------------------------------------------------
 //

package/lib/lob.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2016, 2021, Oracle and/or its affiliates. All rights reserved
+// Copyright (c) 2016, 2022, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //

package/lib/oracledb.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2015, 2021, Oracle and/or its affiliates. All rights reserved
+// Copyright (c) 2015, 2022, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -43,6 +43,7 @@ const BaseDbObject = require('./dbObject.js');
 const Connection = require('./connection.js');
 const Lob = require('./lob.js');
 const Pool = require('./pool.js');
+const PoolStatistics = require('./poolStatistics.js');
 const ResultSet = require('./resultset.js');
 const SodaDatabase = require('./sodaDatabase.js');
 const SodaCollection = require('./sodaCollection.js');
@@ -99,11 +100,13 @@ class OracleDb {
   }
 
   // extend class with promisified functions
-  _extend() {
-    this.getConnection = nodbUtil.callbackify(getConnection);
-    this.createPool = nodbUtil.callbackify(createPool);
-    this.shutdown = nodbUtil.callbackify(shutdown);
-    this.startup = nodbUtil.callbackify(startup);
+  _extend(_oracledb) {
+    this.getConnection = nodbUtil.callbackify(getConnection).bind(_oracledb);
+    this.createPool = nodbUtil.callbackify(createPool).bind(_oracledb);
+    this.shutdown = nodbUtil.callbackify(shutdown).bind(_oracledb);
+    this.startup = nodbUtil.callbackify(startup).bind(_oracledb);
+    this.initOracleClient = this.initOracleClient.bind(_oracledb);
+    this._accessTokenHandler = this._accessTokenHandler.bind(_oracledb);
   }
 
   // temporary method for determining if an object is a date until
@@ -112,6 +115,22 @@ class OracleDb {
     return util.isDate(val);
   }
 
+  // handler for access token callbacks
+  async _accessTokenHandler(userFn, externalObj, refresh) {
+    let accessToken;
+    try {
+      let result = userFn(refresh);
+      if (result instanceof Promise) {
+        result = await result;
+      }
+
+      _checkToken(result);
+      accessToken = result;
+    } finally {
+      this._returnAccessToken(externalObj, accessToken);
+    }
+  }
+
   // retrieves a pool from the pool cache (synchronous method)
   getPool(poolAlias) {
     let pool;
@@ -173,6 +192,21 @@ async function createPool(poolAttrs) {
     throw new Error(nodbUtil.getErrorMessage('NJS-046', poolAlias));
   }
 
+  if (poolAttrs.accessToken !== undefined) {
+    // cannot set username or password for token based authentication
+    if (poolAttrs.user !== undefined ||
+        poolAttrs.password !== undefined) {
+      throw new Error(nodbUtil.getErrorMessage('NJS-084'));
+    }
+
+    // homogeneous and externalAuth must be set to true for token based
+    // authentication
+    if (poolAttrs.homogeneous === false ||
+        poolAttrs.externalAuth === false) {
+      throw new Error(nodbUtil.getErrorMessage('NJS-085'));
+    }
+  }
+
   // create an adjusted set of pool attributes to pass to the C layer; the
   // session callback must be removed if it is a JavaScript function and the
   // queue timeout is used to specify the maximum amount of time that the C
@@ -190,6 +224,28 @@ async function createPool(poolAttrs) {
     adjustedPoolAttrs.queueTimeout = this.queueTimeout;
   }
 
+  // token based authentication
+  if (poolAttrs.accessToken !== undefined) {
+    // accessTokenCallback is depricated from node-oracledb 5.5
+    if (poolAttrs.accessTokenCallback !== undefined &&
+        typeof poolAttrs.accessToken === 'function') {
+      throw new Error(nodbUtil.getErrorMessage('NJS-088'));
+    }
+
+    let accessToken;
+    if (typeof poolAttrs.accessToken === 'function') {
+      adjustedPoolAttrs.accessTokenCallback = poolAttrs.accessToken;
+      accessToken = await poolAttrs.accessToken(false);
+
+      if (_isTokenExpired(accessToken)) {
+        accessToken = await poolAttrs.accessToken(true);
+      }
+    } else {
+      accessToken = poolAttrs.accessToken;
+    }
+    _checkToken(accessToken, adjustedPoolAttrs);
+  }
+
   // Need to prevent another call in the same stack from succeeding, otherwise
   // two pools could be created with the same poolAlias and the second one that
   // comes back would overwrite the first in the cache.
@@ -269,6 +325,31 @@ async function getConnection(a1) {
 
   // otherwise, create a new standalone connection
   } else {
+    if (connAttrs.accessToken !== undefined) {
+      // cannot set username or password for token based authentication
+      if (connAttrs.user !== undefined ||
+          connAttrs.password !== undefined) {
+        throw new Error(nodbUtil.getErrorMessage('NJS-084'));
+      }
+
+      // externalAuth must be set to true for token based authentication
+      if (connAttrs.externalAuth === false) {
+        throw new Error(nodbUtil.getErrorMessage('NJS-086'));
+      }
+
+      let accessToken;
+      if (typeof connAttrs.accessToken === 'function') {
+        accessToken = await connAttrs.accessToken(false);
+
+        if (_isTokenExpired(accessToken)) {
+          accessToken = await connAttrs.accessToken(true);
+        }
+      } else {
+        accessToken = connAttrs.accessToken;
+      }
+      _checkToken(accessToken, connAttrs);
+    }
+
     try {
       return await this._getConnection(connAttrs);
     } catch (err) {
@@ -366,6 +447,78 @@ async function startup(a1, a2) {
 }
 
 
+//-----------------------------------------------------------------------------
+// _isTokenExpiredUtil()
+//   Function to check validity and expiry of token
+//-----------------------------------------------------------------------------
+function _isTokenExpiredUtil(accessToken) {
+  nodbUtil.assert(typeof accessToken === 'string', 'NJS-084', 1);
+
+  if (accessToken.split('.')[1] === undefined) {
+    throw new Error(nodbUtil.getErrorMessage('NJS-084'));
+  }
+
+  const base64Url = accessToken.split('.')[1];
+  const base64 = base64Url.replace(/-/g, '+').replace(/_/g, '/');
+  const buff = Buffer.from(base64, 'base64');
+  const payloadInit = buff.toString('ascii');
+
+  let expiry = JSON.parse(payloadInit).exp;
+  nodbUtil.assert(expiry != undefined, 'NJS-084');
+  expiry = expiry * 1000;
+
+  return (new Date().getTime() > expiry);
+}
+
+
+//-----------------------------------------------------------------------------
+// _isTokenExpired()
+//   Function to check validity of token parameter
+//-----------------------------------------------------------------------------
+function _isTokenExpired(accessToken) {
+  switch (typeof accessToken) {
+    case 'string':
+      if (accessToken === '') {
+        throw new Error(nodbUtil.getErrorMessage('NJS-084'));
+      }
+
+      return _isTokenExpiredUtil(accessToken);
+    case 'object':
+      if (accessToken.token === undefined ||
+          accessToken.token === '' ||
+          accessToken.privateKey === undefined ||
+          accessToken.privateKey === '') {
+        throw new Error(nodbUtil.getErrorMessage('NJS-084'));
+      }
+
+      return _isTokenExpiredUtil(accessToken.token);
+    default:
+      throw new Error(nodbUtil.getErrorMessage('NJS-084'));
+  }
+}
+
+
+//-----------------------------------------------------------------------------
+// _checkToken()
+//   Function to check validity of token parameter
+//-----------------------------------------------------------------------------
+function _checkToken(accessToken, attrs) {
+  if (_isTokenExpired(accessToken)) {
+    throw new Error(nodbUtil.getErrorMessage('NJS-087'));
+  }
+
+  if (attrs === undefined)
+    return;
+
+  if (typeof accessToken === 'string') {
+    attrs.token = accessToken;
+  } else {
+    attrs.token = accessToken.token;
+    attrs.privateKey = accessToken.privateKey;
+  }
+}
+
+
 // create instance which will be exported
 let oracleDbInst = new OracleDb();
 
@@ -380,6 +533,7 @@ proto.BaseDbObject = BaseDbObject;
 proto.Connection = Connection;
 proto.Lob = Lob;
 proto.Pool = Pool;
+proto.PoolStatistics = PoolStatistics;
 proto.ResultSet = ResultSet;
 proto.SodaDatabase = SodaDatabase;
 proto.SodaCollection = SodaCollection;

package/lib/pool.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2016, 2021, Oracle and/or its affiliates. All rights reserved
+// Copyright (c) 2016, 2022, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -22,6 +22,8 @@
 const EventEmitter = require('events');
 const nodbUtil = require('./util.js');
 const util = require('util');
+const PoolStatistics = require('./poolStatistics.js');
+
 
 //-----------------------------------------------------------------------------
 // _checkRequestQueue()
@@ -328,44 +330,7 @@ function logStatistics() {
   if (stats === null) {
     throw new Error(nodbUtil.getErrorMessage('NJS-083'));
   }
-
-  console.log('\nPool statistics:');
-  console.log('...gathered at:', new Date(stats.gatheredDate).toISOString());
-  console.log('...up time (milliseconds):', stats.upTime);
-  console.log('...up time from last reset (milliseconds)',
-    stats.upTimeSinceReset);
-  console.log('...connection requests:', stats.connectionRequests);
-  console.log('...requests enqueued:', stats.requestsEnqueued);
-  console.log('...requests dequeued:', stats.requestsDequeued);
-  console.log('...requests failed:', stats.failedRequests);
-  console.log('...requests exceeding queueMax:', stats.rejectedRequests);
-  console.log('...requests exceeding queueTimeout:', stats.requestTimeouts);
-  console.log('...current queue length:', stats.currentQueueLength);
-  console.log('...maximum queue length:', stats.maximumQueueLength);
-  console.log('...sum of time in queue (milliseconds):', stats.timeInQueue);
-  console.log('...minimum time in queue (milliseconds):',
-    stats.minimumTimeInQueue);
-  console.log('...maximum time in queue (milliseconds):',
-    stats.maximumTimeInQueue);
-  console.log('...average time in queue (milliseconds):',
-    stats.averageTimeInQueue);
-  console.log('...pool connections in use:', stats.connectionsInUse);
-  console.log('...pool connections open:', stats.connectionsOpen);
-  console.log('Pool attributes:');
-  console.log('...poolAlias:', stats.poolAlias);
-  console.log('...queueMax:', stats.queueMax);
-  console.log('...queueTimeout (milliseconds):', stats.queueTimeout);
-  console.log('...poolMin:', stats.poolMin);
-  console.log('...poolMax:', stats.poolMax);
-  console.log('...poolIncrement:', stats.poolIncrement);
-  console.log('...poolTimeout (seconds):', stats.poolTimeout);
-  console.log('...poolPingInterval (seconds):', stats.poolPingInterval);
-  console.log('...poolMaxPerShard:', stats.poolMaxPerShard);
-  console.log('...sessionCallback:', stats.sessionCallback);
-  console.log('...stmtCacheSize:', stats.stmtCacheSize);
-  console.log('...sodaMetaDataCache:', stats.sodaMetaDataCache);
-  console.log('Related environment variables:');
-  console.log('...UV_THREADPOOL_SIZE:', stats.threadPoolSize);
+  stats.logStatistics();
 }
 
 
@@ -375,54 +340,12 @@ function logStatistics() {
 //  properties
 //-----------------------------------------------------------------------------
 function getStatistics() {
-  let averageTimeInQueue;
-  let stats = { };
-
-  // if the pool is not OPEN, throw appropriate err
   this._checkPoolOpen(false);
 
   if (this._enableStatistics !== true) {
     return null;
   }
-
-  averageTimeInQueue = 0;
-
-  if (this._totalRequestsEnqueued !== 0) {
-    averageTimeInQueue = Math.round(this._totalTimeInQueue /
-        this._totalRequestsEnqueued);
-  }
-
-  stats.gatheredDate = Date.now ();
-  stats.upTime = stats.gatheredDate - this._createdDate;
-  stats.upTimeSinceReset = stats.gatheredDate - this._timeOfReset;
-  stats.connectionRequests = this._totalConnectionRequests;
-  stats.requestsEnqueued = this._totalRequestsEnqueued;
-  stats.requestsDequeued = this._totalRequestsDequeued;
-  stats.failedRequests = this._totalFailedRequests;
-  stats.rejectedRequests = this._totalRequestsRejected;
-  stats.requestTimeouts = this._totalRequestTimeouts;
-  stats.maximumQueueLength = this._maximumQueueLength;
-  stats.currentQueueLength = this._connRequestQueue.length;
-  stats.timeInQueue = this._totalTimeInQueue;
-  stats.minimumTimeInQueue = this._minTimeInQueue;
-  stats.maximumTimeInQueue = this._maxTimeInQueue;
-  stats.averageTimeInQueue = averageTimeInQueue;
-  stats.connectionsInUse = this.connectionsInUse;
-  stats.connectionsOpen = this.connectionsOpen;
-  stats.poolAlias = this.poolAlias;
-  stats.queueMax = this.queueMax;
-  stats.queueTimeout = this.queueTimeout;
-  stats.poolMin = this.poolMin;
-  stats.poolMax = this.poolMax;
-  stats.poolIncrement = this.poolIncrement;
-  stats.poolTimeout = this.poolTimeout;
-  stats.poolPingInterval = this.poolPingInterval;
-  stats.poolMaxPerShard = this.poolMaxPerShard;
-  stats.stmtCacheSize = this.stmtCacheSize;
-  stats.sodaMetaDataCache = this.sodaMetaDataCache;
-  stats.threadPoolSize = process.env.UV_THREADPOOL_SIZE;
-
-  return stats;
+  return new PoolStatistics(this);
 }
 
 
@@ -467,6 +390,35 @@ function _setup(poolAttrs, poolAlias, oracledb) {
       this._sessionCallback = poolAttrs.sessionCallback;
   }
 
+  // Properties - edition, events, externalAuth - values can be set globally
+  // on oracledb and can be overridden at pool creation time.
+  if (typeof poolAttrs.edition !== 'undefined') {
+    this.edition = poolAttrs.edition;
+  } else {
+    this.edition = oracledb.edition;
+  }
+
+  if (typeof poolAttrs.events !== 'undefined') {
+    this.events = poolAttrs.events;
+  } else {
+    this.events = oracledb.events;
+  }
+
+  if (typeof poolAttrs.externalAuth !== 'undefined') {
+    this.externalAuth = poolAttrs.externalAuth;
+  } else {
+    this.externalAuth = oracledb.externalAuth;
+  }
+
+  // Properties - homogeneous, user, connectString - are NOT global properties
+  if (typeof poolAttrs.homogeneous !== 'undefined') {
+    this.homogeneous = poolAttrs.homogeneous;
+  } else {
+    this.homogeneous = true;
+  }
+  this.user = poolAttrs.user || poolAttrs.userName;
+  this.connectString = poolAttrs.connectString || poolAttrs.connectionString;
+
   // register event handler for when request queue should be checked
   this.on('_checkRequestQueue', this._checkRequestQueue);
 
@@ -536,6 +488,18 @@ function _setup(poolAttrs, poolAlias, oracledb) {
 }
 
 
+//-----------------------------------------------------------------------------
+// setAccessToken()
+//   set parameters for token based authentication
+//-----------------------------------------------------------------------------
+async function setAccessToken(options) {
+  // check arguments
+  nodbUtil.checkArgCount(arguments, 1, 1);
+  nodbUtil.assert(nodbUtil.isObject(options), 'NJS-005', 1);
+  await this._setAccessToken(options);
+}
+
+
 class Pool extends EventEmitter {
 
   _extend(oracledb) {
@@ -545,6 +509,7 @@ class Pool extends EventEmitter {
     this.close = nodbUtil.callbackify(close);
     this.getConnection = nodbUtil.callbackify(getConnection);
     this.reconfigure = nodbUtil.callbackify(reconfigure);
+    this.setAccessToken = nodbUtil.callbackify(setAccessToken);
     this.logStatistics = logStatistics;
     this.getStatistics = getStatistics;
     this.terminate = this.close;