oracledb 6.6.0 → 6.7.1

package/lib/impl/base.js

@@ -0,0 +1,45 @@
+// Copyright (c) 2024, Oracle and/or its affiliates.
+
+//-----------------------------------------------------------------------------
+//
+// This software is dual-licensed to you under the Universal Permissive License
+// (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
+// 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose
+// either license.
+//
+// If you elect to accept the software under the Apache License, Version 2.0,
+// the following applies:
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+//-----------------------------------------------------------------------------
+
+'use strict';
+
+class BaseImpl {
+
+  //---------------------------------------------------------------------------
+  // _getConnectTraceConfig()
+  //
+  // Retrieves connect trace config from connection object.
+  //---------------------------------------------------------------------------
+  _getConnectTraceConfig() {
+    const connImpl = this._getConnImpl();
+    if (connImpl) {
+      return connImpl._getConnectTraceConfig();
+    }
+  }
+
+}
+
+module.exports = BaseImpl;

package/lib/impl/connection.js

@@ -69,6 +69,32 @@ class ConnectionImpl {
     return this;
   }
 
+  //---------------------------------------------------------------------------
+  // _getConnectTraceConfig()
+  //
+  // returns the necessary connection config used for debug/trace.
+  // ---------------------------------------------------------------------------
+  _getConnectTraceConfig() {
+    let traceConfig;
+
+    if (this._pool) {
+      traceConfig = this._pool._getConnectTraceConfig();
+    } else {
+      traceConfig = {connectString: this._connectString, user: this._user};
+    }
+    traceConfig.serviceName = this.getServiceName();
+    traceConfig.instanceName = this.getInstanceName();
+    traceConfig.pdbName = this.getDbName();
+
+    // Thick mode doesnt have these properties for now.
+    if (settings.thin) {
+      traceConfig.hostName = this.getHostName();
+      traceConfig.port = this.getPort();
+      traceConfig.protocol = this.getProtocol();
+    }
+    return traceConfig;
+  }
+
   //---------------------------------------------------------------------------
   // _getDbObjectType()
   //
@@ -589,6 +615,33 @@ class ConnectionImpl {
     errors.throwNotImplemented("unsubscribing from events");
   }
 
+  //---------------------------------------------------------------------------
+  // getHostName()
+  //
+  // Returns the Oracle Database host name associated with the connection.
+  //---------------------------------------------------------------------------
+  getHostName() {
+    errors.throwNotImplemented("getting HostName");
+  }
+
+  //---------------------------------------------------------------------------
+  // getPort()
+  //
+  // Returns the Oracle Database port number associated with the connection.
+  //---------------------------------------------------------------------------
+  getPort() {
+    errors.throwNotImplemented("getting Port");
+  }
+
+  //---------------------------------------------------------------------------
+  // getProtocol()
+  //
+  // Returns the protocol associated with the connection.
+  //---------------------------------------------------------------------------
+  getProtocol() {
+    errors.throwNotImplemented("getting Protocol");
+  }
+
 }
 
 // export just the class

package/lib/impl/lob.js

@@ -28,8 +28,9 @@
 
 const ConnectionImpl = require('./connection.js');
 const errors = require('../errors.js');
+const BaseImpl = require('./base.js');
 
-class LobImpl {
+class LobImpl extends BaseImpl {
 
   //---------------------------------------------------------------------------
   // _getConnImpl()

package/lib/impl/pool.js

@@ -174,6 +174,21 @@ class PoolImpl {
     errors.throwNotImplemented("getting the pool statement cache size");
   }
 
+  //---------------------------------------------------------------------------
+  // _getConnectTraceConfig()
+  //
+  // Returns the necessary connection config used by pool for debug/trace.
+  //---------------------------------------------------------------------------
+  _getConnectTraceConfig() {
+    return {
+      connectString: this._connectString,
+      user: this._user,
+      poolMin: this.getPoolMin(),
+      poolMax: this.getPoolMax(),
+      poolIncrement: this.getPoolIncrement()
+    };
+  }
+
   //---------------------------------------------------------------------------
   // getSodaMetaDataCache()
   //

package/lib/impl/resultset.js

@@ -34,9 +34,10 @@ const future = require('../future.js');
 const types = require('../types.js');
 const Lob = require('../lob.js');
 const oson = require('./datahandlers/oson.js');
+const BaseImpl = require('./base.js');
 
 // define implementation class
-class ResultSetImpl {
+class ResultSetImpl extends BaseImpl {
 
   //---------------------------------------------------------------------------
   // _determineFetchType()

package/lib/impl/sodaCollection.js

@@ -27,8 +27,9 @@
 'use strict';
 
 const errors = require('../errors.js');
+const BaseImpl = require('./base.js');
 
-class SodaCollectionImpl {
+class SodaCollectionImpl extends BaseImpl {
 
   //---------------------------------------------------------------------------
   // _getConnImpl()

package/lib/impl/sodaDatabase.js

@@ -27,8 +27,9 @@
 'use strict';
 
 const errors = require('../errors.js');
+const BaseImpl = require('./base.js');
 
-class SodaDatabaseImpl {
+class SodaDatabaseImpl extends BaseImpl {
 
   //---------------------------------------------------------------------------
   // _getConnImpl()

package/lib/impl/sodaDocCursor.js

@@ -27,8 +27,9 @@
 'use strict';
 
 const errors = require('../errors.js');
+const BaseImpl = require('./base.js');
 
-class SodaDocCursorImpl {
+class SodaDocCursorImpl extends BaseImpl {
 
   //---------------------------------------------------------------------------
   // _getConnImpl()

package/lib/impl/sodaOperation.js

@@ -27,8 +27,9 @@
 'use strict';
 
 const errors = require('../errors.js');
+const BaseImpl = require('./base.js');
 
-class SodaOperationImpl {
+class SodaOperationImpl extends BaseImpl {
 
   //---------------------------------------------------------------------------
   // _getConnImpl()

package/lib/lob.js

@@ -300,7 +300,8 @@ nodbUtil.wrapFns(Lob.prototype, errors.ERR_BUSY_LOB,
   "close",
   "fileExists",
   "getData");
-Lob.prototype._serializedRead = nodbUtil.serialize(Lob.prototype._readData);
-Lob.prototype._serializedWrite = nodbUtil.serialize(Lob.prototype._writeData);
+Lob.prototype._serializedRead = nodbUtil.wrapFn(Lob.prototype._readData, true);
+Lob.prototype._serializedWrite =
+  nodbUtil.wrapFn(Lob.prototype._writeData, true);
 
 module.exports = Lob;

package/lib/oracledb.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2015, 2023, Oracle and/or its affiliates.
+// Copyright (c) 2015, 2024, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -47,8 +47,10 @@ errors.assert(vs[0] > 14 || (vs[0] === 14 && vs[1] >= 6),
 const AqDeqOptions = require('./aqDeqOptions.js');
 const AqEnqOptions = require('./aqEnqOptions.js');
 const AqMessage = require('./aqMessage.js');
+const protocolUtil = require('./thin/protocol/utils.js');
 const AqQueue = require('./aqQueue.js');
 const future = require('./future.js');
+const traceHandler = require('./traceHandler.js');
 const BaseDbObject = require('./dbObject.js');
 const Connection = require('./connection.js');
 const Lob = require('./lob.js');
@@ -65,14 +67,23 @@ const SodaOperation = require('./sodaOperation.js');
 const poolCache = {};
 const tempUsedPoolAliases = {};
 const defaultPoolAlias = 'default';
+let configProviderCache;
 
 // save arguments for call to initOracleClient()
 let _initOracleClientArgs;
 
 // Load the Oracledb binary
 function _initCLib(options) {
+  // Ensure that webpack compile does not throw any issues or warnings
+  // See https://github.com/oracle/node-oracledb/issues/1156
+  // and https://github.com/oracle/node-oracledb/issues/1678
+  const nodeVer = typeof process !== 'undefined' && process.versions?.node;
   /*global __non_webpack_require__*/  // quieten eslint
-  const requireBinary = (typeof __non_webpack_require__ === 'function') ? __non_webpack_require__ : require; // See Issue 1156
+  const requireBinary = nodeVer
+    ? (typeof __webpack_require__ === 'function')
+      ? __non_webpack_require__
+      : require
+    : undefined;
   const binaryLocations = [
     '../' + nodbUtil.RELEASE_DIR + '/' + nodbUtil.BINARY_FILE,  // pre-built binary
     '../' + nodbUtil.RELEASE_DIR + '/' + nodbUtil.BUILD_FILE,   // binary built from source
@@ -319,6 +330,38 @@ async function _verifyOptions(options, inCreatePool) {
     outOptions.privilege = options.privilege;
   }
 
+  // machine must be a string
+  if (options.machine !== undefined) {
+    nodbUtil.assertParamPropNetworkName(options, 1, "machine");
+    outOptions.machine = options.machine;
+  }
+
+  // osUser must be a string
+  if (options.osUser !== undefined) {
+    nodbUtil.assertParamPropNetworkName(options, 1, "osUser");
+    outOptions.osUser = options.osUser;
+  }
+
+  // driverName must be a string
+  if (options.driverName !== undefined) {
+    errors.assertParamPropValue(typeof options.driverName === 'string',
+      1, "driverName");
+    outOptions.driverName = options.driverName;
+  }
+
+  // program must be a string
+  if (options.program !== undefined) {
+    nodbUtil.assertParamPropNetworkName(options, 1, "program");
+    outOptions.program = options.program;
+  }
+
+  // terminal must be a string
+  if (options.terminal !== undefined) {
+    errors.assertParamPropValue(typeof options.terminal === 'string',
+      1, "terminal");
+    outOptions.terminal = options.terminal;
+  }
+
   // check pool specific options
   if (inCreatePool) {
 
@@ -545,9 +588,12 @@ async function createPool(options) {
   // add defaults to options, if needed
   settings.addToOptions(options,
     "connectionClass",
+    "driverName",
     "edition",
     "events",
     "externalAuth",
+    "machine",
+    "osUser",
     "stmtCacheSize",
     "poolMax",
     "poolMaxPerShard",
@@ -556,6 +602,8 @@ async function createPool(options) {
     "poolTimeout",
     "poolPingInterval",
     "poolPingTimeout",
+    "program",
+    "terminal",
     "queueMax",
     "queueTimeout");
 
@@ -580,6 +628,8 @@ async function createPool(options) {
   // create the pool, ensuring that the temporary pool alias cache is removed
   // once this has completed (either successfully or unsuccessfully)
   const pool = new Pool();
+  pool._impl._connectString = options.connectString;
+  pool._impl._user = options.user;
   try {
     await pool._impl.create(options);
   } finally {
@@ -606,6 +656,22 @@ async function createPool(options) {
   return pool;
 }
 
+//-----------------------------------------------------------------------------
+// getNetworkServiceNames()
+//
+// Returns a list of the network service names found in the
+// tnsnames.ora file which is inside the directory
+// configDir or the $TNS_ADMIN dir
+// If a tnsnames.ora file does not exist, then an exception is raised
+//-----------------------------------------------------------------------------
+async function getNetworkServiceNames(configDir) {
+  const { NLParamParser, tnsnamesFilePath } = require('./thin/sqlnet/paramParser.js');
+  const nlParamParser =  new NLParamParser;
+  const filePath = tnsnamesFilePath(configDir);
+  const aliasht = await nlParamParser.initializeNlpa(filePath);
+  const keysArr = [ ...aliasht.keys() ];
+  return keysArr;
+}
 
 //-----------------------------------------------------------------------------
 // getConnection()
@@ -638,16 +704,23 @@ async function getConnection(a1) {
   options = await _verifyOptions(options, false);
   settings.addToOptions(options,
     "connectionClass",
+    "driverName",
     "edition",
     "events",
     "externalAuth",
-    "stmtCacheSize");
+    "machine",
+    "osUser",
+    "program",
+    "stmtCacheSize",
+    "terminal");
   if (_initOracleClientArgs === undefined && !settings.thinDriverInitialized) {
     _initializeThinDriver();
   }
-
   const conn = new Connection();
   conn._impl = new impl.ConnectionImpl();
+
+  conn._impl._connectString = options.connectString;
+  conn._impl._user = options.user;
   await conn._impl.connect(options);
   if (_initOracleClientArgs === undefined) {
     settings.thinDriverInitialized = true;
@@ -777,43 +850,111 @@ async function shutdown(a1, a2) {
 // from Config Provider.
 //-----------------------------------------------------------------------------
 async function _checkConfigProvider(options) {
+  // Time for Cache entries to be deleted in milliseconds
+  const cacheEntriesDuration = settings.configProviderCacheTimeout * 1000;
+  let secondOpts;
   const url = options.connectString || options.connectionString;
   if (!url)
     return options;
-  let parsedUrl = url;
-  let urlExtendedPart;
-  const baseRegex = new RegExp("^config-(?<provider>[A-Za-z0-9]+)(://)(?<provider_arg>[^?]+)");
-  if (url.indexOf('?') != -1) {
-    parsedUrl = url.substring(0, url.indexOf('?'));
-    urlExtendedPart = url.substring(url.indexOf('?'), url.length); //extended part
-  }
-  const match = parsedUrl.match(baseRegex);
-  if (match) {
-    const provider = match.groups.provider;
-    const provider_arg = match.groups.provider_arg;
-    let configPckg;
-    try {
-      configPckg = require('./configProviders/' + provider);
-    } catch (err) {
-      errors.throwErr(errors.ERR_CONFIG_PROVIDER_NOT_SUPPORTED, provider);
-    }
-    const configProvider = new configPckg(provider_arg, urlExtendedPart);
-    try {
-      configProvider.init();
-    } catch (err) {
-      errors.throwErr(errors.ERR_CONFIG_PROVIDER_LOAD_FAILED, err.message);
+
+  if (configProviderCache && configProviderCache.has(url) && ((Date.now() - configProviderCache.get(url).timeAdded) < cacheEntriesDuration)) {
+    const cacheOpts1 = configProviderCache.get(url).cacheOpts;
+    secondOpts = { ...cacheOpts1};
+
+    //deobfuscate password
+    if (secondOpts.password)
+      secondOpts.password = protocolUtil.getDeobfuscatedValue(secondOpts.password.value, secondOpts.password.obfuscatedValue);
+
+    //deobfuscate walletContent
+    if (secondOpts.walletContent)
+      secondOpts.walletContent = protocolUtil.getDeobfuscatedValue(secondOpts.walletContent.value, secondOpts.walletContent.obfuscatedValue);
+
+  } else {
+    let parsedUrl = url;
+    let urlExtendedPart;
+    const baseRegex = new RegExp("^config-(?<provider>[A-Za-z0-9]+)(://)(?<provider_arg>[^?]+)");
+    if (url.indexOf('?') != -1) {
+      parsedUrl = url.substring(0, url.indexOf('?'));
+      urlExtendedPart = url.substring(url.indexOf('?'), url.length); //extended part
     }
-    let secondOpts;
-    try {
-      secondOpts = await configProvider.returnConfig();
-    } catch (err) {
-      errors.throwErr(errors.ERR_CONFIG_PROVIDER_FAILED_TO_RETRIEVE_CONFIG, err.message);
+    const match = parsedUrl.match(baseRegex);
+    if (match) {
+      const provider = match.groups.provider;
+      const provider_arg = match.groups.provider_arg;
+      let configPckg;
+      try {
+        configPckg = require('./configProviders/' + provider);
+      } catch (err) {
+        errors.throwErr(errors.ERR_CONFIG_PROVIDER_NOT_SUPPORTED, provider);
+      }
+      const configProvider = new configPckg(provider_arg, urlExtendedPart);
+      try {
+        configProvider.init();
+      } catch (err) {
+        errors.throwErr(errors.ERR_CONFIG_PROVIDER_LOAD_FAILED, err.message);
+      }
+      try {
+        if (!configProviderCache) {
+          configProviderCache = new Map();
+        }
+        secondOpts = await configProvider.returnConfig();
+        // obfuscate password & walletcontent and store config in the cache
+        const cacheOpts = { ...secondOpts};
+        if (secondOpts.password)
+          cacheOpts.password = protocolUtil.setObfuscatedValue(secondOpts.password);
+        if (secondOpts.walletContent)
+          cacheOpts.walletContent = protocolUtil.setObfuscatedValue(secondOpts.walletContent);
+        configProviderCache.set(url, { cacheOpts, timeAdded: Date.now()});
+      } catch (err) {
+        errors.throwErr(errors.ERR_CONFIG_PROVIDER_FAILED_TO_RETRIEVE_CONFIG, err.message);
+      }
     }
-    options = configProvider.modifyOptionsPrecedence(secondOpts, options);
+  }
+  if (secondOpts) {
+    options = modifyOptionsPrecedence(secondOpts, options);
   }
   return options;
 }
+/**
+  * Sets precedence for different parameters in cloudConfig/userConfig
+  * @param {cloudConfig} object - object retreived from cloud
+  * @param {userConfig} object -  user input Object
+  */
+function modifyOptionsPrecedence(cloudConfig, userConfig) {
+  // create a copy of userConfig object
+  userConfig = { ...userConfig };
+  if (!userConfig.user)
+    userConfig.user = cloudConfig.user;
+  if (!userConfig.password)
+    userConfig.password = cloudConfig.password;
+  if (cloudConfig.connectString) {
+    userConfig.connectString = cloudConfig.connectString;
+    userConfig.connectionString = undefined;
+  }
+  if (cloudConfig.walletContent)
+    userConfig.walletContent = cloudConfig.walletContent;
+  if (cloudConfig.poolMin)
+    userConfig.poolMin = cloudConfig.poolMin;
+  if (cloudConfig.poolMax)
+    userConfig.poolMax = cloudConfig.poolMax;
+  if (cloudConfig.poolIncrement)
+    userConfig.poolIncrement = cloudConfig.poolIncrement;
+  if (cloudConfig.poolTimeout)
+    userConfig.poolTimeout = cloudConfig.poolTimeout;
+  if (cloudConfig.poolPingInterval)
+    userConfig.poolPingInterval = cloudConfig.poolPingInterval;
+  if (cloudConfig.poolPingTimeout)
+    userConfig.poolPingTimeout = cloudConfig.poolPingTimeout;
+  if (cloudConfig.stmtCacheSize)
+    userConfig.stmtCacheSize = cloudConfig.stmtCacheSize;
+  if (cloudConfig.prefetchRows)
+    userConfig.prefetchRows = cloudConfig.prefetchRows;
+  if (cloudConfig.lobPrefetch)
+    userConfig.lobPrefetch = cloudConfig.lobPrefetch;
+
+  return userConfig;
 
+}
 //-----------------------------------------------------------------------------
 // startup()
 //
@@ -879,12 +1020,13 @@ module.exports = {
   SodaOperation,
 
   // top-level functions
-  getConnection: nodbUtil.callbackify(getConnection),
-  createPool: nodbUtil.callbackify(createPool),
+  getConnection: nodbUtil.callbackify(nodbUtil.wrapFn(getConnection)),
+  createPool: nodbUtil.callbackify(nodbUtil.wrapFn(createPool)),
+  getNetworkServiceNames: nodbUtil.callbackify(nodbUtil.wrapFn(getNetworkServiceNames)),
   getPool,
   initOracleClient,
-  shutdown: nodbUtil.callbackify(shutdown),
-  startup: nodbUtil.callbackify(startup),
+  shutdown: nodbUtil.callbackify(nodbUtil.wrapFn(shutdown)),
+  startup: nodbUtil.callbackify(nodbUtil.wrapFn(startup)),
 
   // CQN operation codes
   CQN_OPCODE_ALL_OPS: constants.CQN_OPCODE_ALL_OPS,
@@ -1076,6 +1218,9 @@ module.exports = {
   ARRAY: constants.OUT_FORMAT_ARRAY,
   OBJECT: constants.OUT_FORMAT_OBJECT,
 
+  // Trace Interface
+  traceHandler,
+
   // Instances
   future,
 
@@ -1180,6 +1325,10 @@ module.exports = {
     return settings.stmtCacheSize;
   },
 
+  get configProviderCacheTimeout() {
+    return settings.configProviderCacheTimeout;
+  },
+
   get thin() {
     return settings.thin;
   },
@@ -1213,6 +1362,11 @@ module.exports = {
     settings.dbObjectAsPojo = value;
   },
 
+  set driverName(value) {
+    errors.assertPropValue(typeof value === 'string', "driverName");
+    settings.driverName = value;
+  },
+
   set edition(value) {
     errors.assertPropValue(typeof value === 'string', "edition");
     settings.edition = value;
@@ -1265,11 +1419,25 @@ module.exports = {
     settings.lobPrefetchSize = value;
   },
 
+  set machine(value) {
+    errors.assertPropValue(typeof value === 'string', "machine");
+    const sanitizedValue = nodbUtil.sanitize(value);
+    errors.assertPropValue(value == sanitizedValue, "machine");
+    settings.machine = value;
+  },
+
   set maxRows(value) {
     errors.assertPropValue(Number.isInteger(value) && value >= 0, "maxRows");
     settings.maxRows = value;
   },
 
+  set osUser(value) {
+    errors.assertPropValue(typeof value === 'string', "osUser");
+    const sanitizedValue = nodbUtil.sanitize(value);
+    errors.assertPropValue(value == sanitizedValue, "osUser");
+    settings.osUser = value;
+  },
+
   set outFormat(value) {
     if (value !== constants.OUT_FORMAT_ARRAY &&
         value !== constants.OUT_FORMAT_OBJECT) {
@@ -1324,10 +1492,27 @@ module.exports = {
     settings.prefetchRows = value;
   },
 
+  set program(value) {
+    errors.assertPropValue(typeof value === 'string', "program");
+    const sanitizedValue = nodbUtil.sanitize(value);
+    errors.assertPropValue(value == sanitizedValue, "program");
+    settings.program = value;
+  },
+
   set stmtCacheSize(value) {
     errors.assertPropValue(Number.isInteger(value) && value >= 0,
       "stmtCacheSize");
     settings.stmtCacheSize = value;
   },
 
+  set terminal(value) {
+    errors.assertPropValue(typeof value === 'string', "terminal");
+    settings.terminal = value;
+  },
+  set configProviderCacheTimeout(value) {
+    errors.assertPropValue(Number.isInteger(value) && value >= 0,
+      "configProviderCacheTimeout");
+    settings.configProviderCacheTimeout = value;
+  }
+
 };

package/lib/pool.js

@@ -423,7 +423,7 @@ class Pool extends EventEmitter {
       throw err;
     }
 
-    if (this._connectionsOut >= poolMax ||
+    while (this._connectionsOut >= poolMax ||
         this.status === constants.POOL_STATUS_RECONFIGURING) {
 
       // when the queue is huge, throw error early without waiting for queue
@@ -798,12 +798,21 @@ class Pool extends EventEmitter {
     return this._user;
   }
 
+  //---------------------------------------------------------------------------
+  // connectTraceConfig
+  //
+  // Property for getting the connection related config.
+  //---------------------------------------------------------------------------
+  get connectTraceConfig() {
+    return this._impl && this._impl._getConnectTraceConfig();
+  }
 }
 
-Pool.prototype.close = nodbUtil.callbackify(Pool.prototype.close);
-Pool.prototype.getConnection = nodbUtil.callbackify(Pool.prototype.getConnection);
-Pool.prototype.reconfigure = nodbUtil.callbackify(Pool.prototype.reconfigure);
-Pool.prototype.setAccessToken = nodbUtil.callbackify(Pool.prototype.setAccessToken);
+nodbUtil.wrapFns(Pool.prototype, false,
+  "close",
+  "getConnection",
+  "reconfigure",
+  "setAccessToken");
 
 // DEPRECATED aliases
 Pool.prototype.terminate = Pool.prototype.close;

package/lib/settings.js

@@ -59,6 +59,7 @@ class Settings {
     this.queueTimeout = 60000;
     this.queueMax = 500;
     this.stmtCacheSize = 30;
+    this.configProviderCacheTimeout = 86400;
     this.thin = true;
     this.thinDriverInitialized = false;
     this.createFetchTypeMap(this.fetchAsString, this.fetchAsBuffer);