oracledb 6.6.0 → 6.7.0

package/lib/traceHandler.js

@@ -0,0 +1,133 @@
+// 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';
+
+/**
+ * TraceHandler interface defination which application needs to implement
+ * the hooks defined. The hooks will be called by the driver with traceContext
+ * data.
+ *
+ * TraceContext Data details.
+ * connectLevelConfig - Connection Config details.
+ *      protcol         - tcp/tcps protocol.
+ *      user            - user/schema associated.
+ *      instanceName    - instance Name.
+ *      pdbName         - PDB name.
+ *      serviceName     - service name.
+ *      connectString   - connect string passed.
+ *      hostName        - host name.
+ *      port            - port number.
+ *      poolMin         - pool Min.
+ *      poolMax         - pool Max.
+ *      poolIncrement   - pool Increment.
+ *
+ * callLevelConfig - Post connection, call leveldetails.
+ *      statement       - SQL statement.
+ *      values          - Bind values.
+ *
+ * additionalConfig - Custom Config based on the methods executed.
+ *      args            - input arguments of function.
+ *      self            - the current instance on which function is called.
+ *      result          - the result object returned after calling function.
+ *      implicitRelease - true if implicit release is done.
+ *
+ */
+
+class TraceHandlerBase {
+
+  constructor() {
+    this._config = {};
+  }
+
+  // check if sending traces is enabled.
+  isEnabled() {
+    return (this._config.enable);
+  }
+
+  // Enable sending traces
+  enable() {
+    this._config.enable = true;
+  }
+
+  // Disable sending traces
+  disable() {
+    this._config.enable = false;
+  }
+
+  // It is called before invoking a public async method.
+  onEnterFn(/*traceContext*/) {
+  }
+
+  // It is called after invoking a public async method.
+  // The same traceContext object passed inside onEnterFn
+  // will be passed in this function.
+  onExitFn(/*traceContext*/) {
+  }
+
+  // called when a round trip is begun
+  // OpenTelemetry will start a new span as a child of the public API span.
+  onBeginRoundTrip(/*traceContext*/) {
+  }
+
+  // called when a round trip has ended
+  // OpenTelemetry will end the span
+  // The same traceContext object passed inside onBeginRoundTrip
+  // is passed here.
+  onEndRoundTrip(/*traceContext*/) {
+  }
+
+}
+
+// singleton object pointing to traceHandler instance.
+let _currentTraceObject;
+
+// It enables user defined implementation of
+// TraceHandlerBase interface to be used.
+function setTraceInstance(obj) {
+  _currentTraceObject = obj;
+}
+
+// It returns the user defined instance implementing the interface.
+function getTraceInstance() {
+  return _currentTraceObject;
+}
+
+// returns if tracing is enabled.
+function isEnabled() {
+  return _currentTraceObject?.isEnabled();
+}
+
+module.exports = {
+  // class
+  TraceHandlerBase,
+
+  // methods
+  setTraceInstance,
+  getTraceInstance,
+  isEnabled
+
+};

package/lib/util.js

@@ -32,6 +32,16 @@ const process = require('process');
 const util = require('util');
 const types = require('./types.js');
 const constants = require('./constants.js');
+const traceHandler = require('./traceHandler.js');
+
+// set of valid network characters
+const validNetworkCharacterSet = new Set(['A', 'B', 'C', 'D', 'E', 'F', 'G',
+  'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V',
+  'W', 'X', 'Y', 'Z', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k',
+  'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z',
+  '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '<', '>', '/', '\\', ',',
+  '.', ':', ';', '\'', '"', '-', '_', '$', '+', '*', '#', '&', '!', '%', '?',
+  '@']);
 
 // node-oracledb version number
 let packageJSON;
@@ -54,6 +64,17 @@ const BUILD_FILE = 'oracledb.node';
 // Staging directory used by maintainers building the npm package
 const STAGING_DIR = 'package/Staging';
 
+//-----------------------------------------------------------------------------
+// assertParamPropNetworkName()
+//
+// Asserts input vaue and sanitized value passes specified condition
+// -----------------------------------------------------------------------------
+function assertParamPropNetworkName(obj, parameterNum, propName) {
+  errors.assertParamPropString(obj, parameterNum, propName);
+  const sanitizedValue = sanitize(obj[propName]);
+  errors.assertParamPropValue(obj[propName] === sanitizedValue, parameterNum, propName);
+}
+
 // getInstallURL returns a string with installation URL
 function getInstallURL() {
   return ('Node-oracledb installation instructions: https://node-oracledb.readthedocs.io/en/latest/user_guide/installation.html');
@@ -113,6 +134,79 @@ function getInstallHelp() {
   return mesg;
 }
 
+function getOperationName(methodName) {
+  const className = (this.constructor.name === 'Object') ? 'oracledb'
+    : `oracledb.${this.constructor.name}`;
+  return `${className}.${methodName}`;
+}
+
+// It returns an userContext after populating the traceContext with this below data.
+//    Operation derived from className, methodName.
+//    Initialize the callLevelTraceData.
+//    traceContext is filled.
+function traceEnterFn(traceContext) {
+  if (!traceHandler.isEnabled()) {
+    return;
+  }
+
+  // initialize callLevel data
+  if (this._impl) {
+    this._impl._callLevelTraceData = {};
+  }
+
+  // fill the traceContext.
+  traceContext.additionalConfig = {};
+  traceContext.additionalConfig.self = this;
+  traceContext.additionalConfig.args = traceContext.args;
+  traceContext.operation = getOperationName.call(this, traceContext.fn.name);
+  traceContext.connectLevelConfig = this._impl?._getConnectTraceConfig();
+  traceHandler.getTraceInstance().onEnterFn(traceContext);
+}
+
+// It calls the onExitFn method providing the userContext resturned in onEnterFn.
+function traceExitFn(traceContext, result, err) {
+  const callExitFn = traceHandler.isEnabled();
+  if (!callExitFn) {
+    return;
+  }
+
+  // Fill the traceContext.
+  if (err) {
+    traceContext.error = Object.assign(({}, err));
+  }
+  traceContext.additionalConfig.result = result;
+  if (this._impl) {
+    // fill function call state.
+    traceContext.callLevelConfig = this._impl._callLevelTraceData;
+  }
+  if (['oracledb.getConnection', 'oracledb.createPool'].includes(traceContext.operation)) {
+    if (err) {
+      if (traceContext.args && traceContext.args.length >= 1) {
+        // connectString and user information is populated in traceContext,
+        // which is useful if an error happens and connection object is not created.
+        const config = {};
+        const inp = traceContext.args[0];
+        config.user = inp.user || inp.username;
+        config.connectString = inp.connectString || inp.connectionString;
+        traceContext.connectLevelConfig = config;
+      }
+    } else {
+      traceContext.connectLevelConfig = result._impl._getConnectTraceConfig();
+    }
+  } else if (traceContext.operation === 'oracledb.Pool.getConnection') {
+    if (!err) {
+      // we update the connectTraceConfig with more values with returned conn.
+      traceContext.connectLevelConfig = result._impl._getConnectTraceConfig();
+    }
+  }
+
+  traceHandler.getTraceInstance().onExitFn(traceContext);
+  if (this._impl) {
+    // cleanup the function call state.
+    this._impl._callLevelTraceData = undefined;
+  }
+}
+
 // The callbackify function is used to wrap async methods to add optional
 // callback support. If the last parameter passed to a method is a function,
 // then it is assumed that the callback pattern is being used and the promise
@@ -124,9 +218,7 @@ function callbackify(func) {
     // if last argument is not a function, simply invoke the function as usual
     // and a promise will be returned
     if (typeof arguments[arguments.length - 1] !== 'function') {
-      return func.apply(this, arguments).catch(function stackCapture(err) {
-        throw errors.transformErr(err, stackCapture);
-      });
+      return func.apply(this, arguments);
     }
 
     // otherwise, resolve or reject the promise and invoke the callback
@@ -134,9 +226,7 @@ function callbackify(func) {
     const cb = arguments[arguments.length - 1];
     func.apply(this, args).then(function(result) {
       cb(null, result);
-    }, function stackCapture(err) {
-      cb(errors.transformErr(err, stackCapture));
-    });
+    }, cb);
   };
   if (func.name) {
     Object.defineProperty(wrapper, 'name', { value: func.name });
@@ -144,17 +234,30 @@ function callbackify(func) {
   return wrapper;
 }
 
-// The serialize function is used to wrap methods to ensure that the connection
-// is not used concurrently by multiple threads
-function serialize(func) {
-  return async function() {
+// the wrapFn() function is used to wrap a single method to ensure that calls
+// are serialized and that concurrent calls are prevented where that is needed;
+// this method also ensures that error information is captured correctly.
+// If tracing is enabled, the hooks onEnterFn and onExitFn are called after
+// the input traceContext is prepared. The func is passed in traceContext
+// which is filled with additional context inside onEnterFn.
+function wrapFn(func, serialize, preventConcurrentErrorCode) {
+  const wrapper = async function wrapper() {
 
     let connImpl;
+    const traceEnabled = traceHandler.isEnabled();
+    const traceContext = {fn: func, args: arguments};
+
+    // if concurrent operations are to be prevented, check for that now
+    if (preventConcurrentErrorCode) {
+      if (this._isActive)
+        errors.throwErr(preventConcurrentErrorCode);
+      this._isActive = true;
+    }
 
     // determine the connection implementation associated with the object, if
     // one currently exists and acquire the "lock"; this simply checks to see
     // if another operation is in progress, and if so, waits for it to complete
-    if (this._impl) {
+    if (serialize && this._impl) {
       connImpl = this._impl._getConnImpl();
       await connImpl._acquireLock();
     }
@@ -162,48 +265,54 @@ function serialize(func) {
     // call the function and ensure that the lock is "released" once the
     // function has completed -- either successfully or in failure -- but only
     // if a connection implementation is currently associated with this object
+    let result, tErr;
     try {
-      return await func.apply(this, arguments);
+      if (traceEnabled) {
+        traceEnterFn.call(this, traceContext);
+      }
+      result = await traceContext.fn.apply(this, arguments);
+      return result;
+    } catch (err) {
+      tErr = errors.transformErr(err, wrapper);
+      throw tErr;
     } finally {
       if (connImpl)
         connImpl._releaseLock();
+      if (preventConcurrentErrorCode) {
+        this._isActive = false;
+      }
+      if (traceEnabled) {
+        traceExitFn.call(this, traceContext, result, tErr);
+      }
     }
-  };
-}
 
-function preventConcurrent(func, errorCode) {
-  return async function() {
-    if (this._isActive)
-      errors.throwErr(errorCode);
-    this._isActive = true;
-    try {
-      return await func.apply(this, arguments);
-    } finally {
-      this._isActive = false;
-    }
   };
+  if (func.name) {
+    Object.defineProperty(wrapper, 'name', { value: func.name });
+  }
+  return wrapper;
 }
 
 // The wrapFns() function is used to wrap the named methods on the prototype
-// in multiple ways (serialize, preventConcurrent and callbackify); the
+// so that a number of common tasks can be done in a single place; the
 // arguments following the formal arguments contain the names of methods to
 // wrap on the prototype; if the first extra argument is an error code, it is
 // used to wrap to prevent concurrent access
 function wrapFns(proto) {
   let nameIndex = 1;
+  let serialize = true;
   let preventConcurrentErrorCode;
   if (typeof arguments[1] === 'number') {
-    nameIndex = 2;
+    nameIndex++;
     preventConcurrentErrorCode = arguments[1];
+  } else if (typeof arguments[1] === 'boolean') {
+    nameIndex++;
+    serialize = arguments[1];
   }
   for (let i = nameIndex; i < arguments.length; i++) {
     const name = arguments[i];
     const f = proto[name];
-    if (preventConcurrentErrorCode) {
-      proto[name] = callbackify(preventConcurrent(serialize(f),
-        preventConcurrentErrorCode));
-    } else
-      proto[name] = callbackify(serialize(f));
+    proto[name] = callbackify(wrapFn(f, serialize, preventConcurrentErrorCode));
   }
 }
 
@@ -412,6 +521,42 @@ function makeDate(useLocal, year, month, day, hour, minute,
     fseconds) - offset * 60000);
 }
 
+//---------------------------------------------------------------------------
+// sanitize()
+//
+// this function replaces invalid characters in a string with characters
+// guaranteed to be in the Network Character Set.
+//---------------------------------------------------------------------------
+function sanitize(text) {
+  let value = text.split('');
+
+  // if first character is single/double quote
+  if ((value[0] === '\'' || value[0] === '"')) {
+    value = value.splice(1);
+  }
+
+  // if last character is single/double quote
+  if ((value[value.length - 1] === '\'' || value[value.length - 1] === '"')) {
+    value.pop();
+  }
+
+  // look for invalid characters, and replace them with '?'
+  // in case of default values and throw an error
+  // for user provided values
+  for (let i = 0; i < value.length; i++) {
+    if (!validNetworkCharacterSet.has(value[i])) {
+      value[i] = '?';
+    }
+  }
+
+  // if last character is a backslash
+  if (value[value.length - 1] === '\\') {
+    value[value.length - 1] = '?';
+  }
+
+  return value.join('');
+}
+
 // define exports
 module.exports = {
   BINARY_FILE,
@@ -420,6 +565,7 @@ module.exports = {
   RELEASE_DIR,
   STAGING_DIR,
   addTypeProperties,
+  assertParamPropNetworkName,
   callbackify,
   denormalizePrivateKey,
   getInstallURL,
@@ -436,8 +582,8 @@ module.exports = {
   isXid,
   normalizeXid,
   makeDate,
-  preventConcurrent,
-  serialize,
+  sanitize,
   verifySodaDoc,
+  wrapFn,
   wrapFns
 };

package/lib/version.js

@@ -30,7 +30,7 @@
 
 module.exports = {
   VERSION_MAJOR: 6,
-  VERSION_MINOR: 6,
+  VERSION_MINOR: 7,
   VERSION_PATCH: 0,
   VERSION_SUFFIX: ''
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oracledb",
-  "version": "6.6.0",
+  "version": "6.7.0",
   "description": "A Node.js module for Oracle Database access from JavaScript and TypeScript",
   "license": "(Apache-2.0 OR UPL-1.0)",
   "homepage": "http://oracle.github.io/node-oracledb/",

package/build/Release/oracledb-6.6.0-darwin-arm64.node-buildinfo.txt

@@ -1 +0,0 @@
-oracledb-6.6.0-darwin-arm64.node v22.2.0 6e81601d4d09137e859660fbbe090e1b272adbb2 5f182c720d6541c3b267d5d370f606f90b5b0c38 Wed, 17 Jul 2024 06:45:24 GMT

package/build/Release/oracledb-6.6.0-darwin-x64.node-buildinfo.txt

@@ -1 +0,0 @@
-oracledb-6.6.0-darwin-x64.node v20.11.1 6e81601d4d09137e859660fbbe090e1b272adbb2 5f182c720d6541c3b267d5d370f606f90b5b0c38 Wed, 17 Jul 2024 04:43:48 GMT

package/build/Release/oracledb-6.6.0-js-buildinfo.txt

@@ -1 +0,0 @@
-6e81601d4d09137e859660fbbe090e1b272adbb2

package/build/Release/oracledb-6.6.0-linux-arm64.node-buildinfo.txt

@@ -1 +0,0 @@
-oracledb-6.6.0-linux-arm64.node v20.12.2 6e81601d4d09137e859660fbbe090e1b272adbb2 5f182c720d6541c3b267d5d370f606f90b5b0c38 Wed, 17 Jul 2024 07:10:04 GMT

package/build/Release/oracledb-6.6.0-linux-x64.node-buildinfo.txt

@@ -1 +0,0 @@
-oracledb-6.6.0-linux-x64.node v16.20.2 6e81601d4d09137e859660fbbe090e1b272adbb2 5f182c720d6541c3b267d5d370f606f90b5b0c38 Wed, 17 Jul 2024 07:13:04 GMT

package/build/Release/oracledb-6.6.0-win32-x64.node-buildinfo.txt

@@ -1 +0,0 @@
-oracledb-6.6.0-win32-x64.node v18.16.0 6e81601d4d09137e859660fbbe090e1b272adbb2 5f182c720d6541c3b267d5d370f606f90b5b0c38 Wed, 17 Jul 2024 07:26:50 GMT