oracledb 5.5.0 → 6.0.1

package/lib/util.js

@@ -1,17 +1,24 @@
-// Copyright (c) 2016, 2022, Oracle and/or its affiliates.
+// Copyright (c) 2016, 2023, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
-// You may not use the identified files except in compliance with the Apache
-// License, Version 2.0 (the "License.")
+// 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
-// http://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.
+//    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.
 //
@@ -19,67 +26,35 @@
 
 'use strict';
 
+const { Buffer } = require('buffer');
+const errors = require('./errors.js');
+const process = require('process');
 const util = require('util');
+const types = require('./types.js');
 
 // node-oracledb version number
 let packageJSON;
 try {
   packageJSON = require('../package.json');
 } catch (err) {
-  throw new Error('package.json is missing');
+  errors.throwErr(errors.ERR_MISSING_FILE, 'package.json');
 }
 const PACKAGE_JSON_VERSION = packageJSON.version;
-module.exports.PACKAGE_JSON_VERSION = PACKAGE_JSON_VERSION;
 
 // Directory containing the node-oracledb add-on binary
 const RELEASE_DIR = 'build/Release';
-module.exports.RELEASE_DIR = RELEASE_DIR;
 
 // The default node-oracledb add-on binary filename for this Node.js
 const BINARY_FILE = 'oracledb-' + PACKAGE_JSON_VERSION + '-' + process.platform + '-' + process.arch + '.node';
-module.exports.BINARY_FILE = BINARY_FILE;
 
 // Staging directory used by maintainers building the npm package
 const STAGING_DIR = 'package/Staging';
-module.exports.STAGING_DIR = STAGING_DIR;
-
-// errorMessages is for NJS error messages used in the JavaScript layer
-const errorMessages = {
-  'NJS-002': 'NJS-002: invalid pool',
-  'NJS-004': 'NJS-004: invalid value for property %s',
-  'NJS-005': 'NJS-005: invalid value for parameter %d',
-  'NJS-009': 'NJS-009: invalid number of parameters',
-  'NJS-017': 'NJS-017: concurrent operations on ResultSet are not allowed',
-  'NJS-023': 'NJS-023: concurrent operations on LOB are not allowed',
-  'NJS-037': 'NJS-037: incompatible type of value provided',
-  'NJS-040': 'NJS-040: connection request timeout. Request exceeded queueTimeout of %d',
-  'NJS-041': 'NJS-041: cannot convert ResultSet to QueryStream after invoking methods',
-  'NJS-042': 'NJS-042: cannot invoke ResultSet methods after converting to QueryStream',
-  'NJS-043': 'NJS-043: ResultSet already converted to QueryStream',
-  'NJS-045': 'NJS-045: cannot load a node-oracledb binary for Node.js ' + process.versions.node + ' (' + process.platform + ' ' + process.arch + ') %s',
-  'NJS-046': 'NJS-046: poolAlias "%s" already exists in the connection pool cache',
-  'NJS-047': 'NJS-047: poolAlias "%s" not found in the connection pool cache',
-  'NJS-064': 'NJS-064: connection pool is closing',
-  'NJS-065': 'NJS-065: connection pool was closed',
-  'NJS-067': 'NJS-067: a pre-built node-oracledb binary was not found for %s',
-  'NJS-069': 'NJS-069: node-oracledb %s requires Node.js %s or later',
-  'NJS-076': 'NJS-076: connection request rejected. Pool queue length queueMax %d reached',
-  'NJS-081': 'NJS-081: concurrent operations on a connection are disabled',
-  'NJS-082': 'NJS-082: connection pool is being reconfigured',
-  'NJS-083': 'NJS-083: pool statistics not enabled',
-  'NJS-084': 'NJS-084: invalid access token',
-  'NJS-085': 'NJS-085: invalid connection pool configuration with token based authentication. The homogeneous and externalAuth attributes must be set to true',
-  'NJS-086': 'NJS-086: invalid standalone configuration with token based authentication. The externalAuth attribute must be set to true',
-  'NJS-087': 'NJS-087: access token has expired',
-  'NJS-088': 'NJS-088: accessTokenCallback cannot be specified when accessToken is a function'
-};
 
 // getInstallURL returns a string with installation URL
 function getInstallURL() {
-  return ('Node-oracledb installation instructions: https://oracle.github.io/node-oracledb/INSTALL.html');
+  return ('Node-oracledb installation instructions: https://node-oracledb.readthedocs.io/en/latest/user_guide/installation.html');
 }
 
-module.exports.getInstallURL = getInstallURL;
 
 // getInstallHelp returns a string with installation usage tips that may be helpful
 function getInstallHelp() {
@@ -96,7 +71,7 @@ function getInstallHelp() {
       url = 'https://www.oracle.com/database/technologies/instant-client.html\n';
       arch = process.arch;
     }
-    mesg += 'You must have ' + arch + ' Oracle Client libraries configured with ldconfig, or in LD_LIBRARY_PATH.\n';
+    mesg += 'You must have Linux ' + arch + ' Oracle Client libraries configured with ldconfig, or in LD_LIBRARY_PATH.\n';
     mesg += 'If you do not have Oracle Database on this computer, then install the Instant Client Basic or Basic Light package from \n';
     mesg += url;
   } else if (process.platform === 'darwin') {
@@ -107,7 +82,7 @@ function getInstallHelp() {
       url = 'https://www.oracle.com/database/technologies/instant-client.html\n';
       arch = process.arch;
     }
-    mesg += 'You must have the ' + arch + ' Oracle Instant Client Basic or Basic Light package libraries in\n';
+    mesg += 'You must have macOS ' + arch + ' Oracle Instant Client Basic or Basic Light package libraries in\n';
     mesg += '/usr/local/lib or set by calling oracledb.initOracleClient({libDir: "/my/instant_client_directory"}).\n';
     mesg += 'Oracle Instant Client can be downloaded from ' + url;
   } else if (process.platform === 'win32') {
@@ -121,7 +96,7 @@ function getInstallHelp() {
       url = 'https://www.oracle.com/database/technologies/instant-client.html\n';
       arch = process.arch;
     }
-    mesg += 'You must have ' + arch + ' Oracle Client libraries in your PATH environment variable.\n';
+    mesg += 'You must have Windows ' + arch + ' Oracle Client libraries in your PATH environment variable.\n';
     mesg += 'If you do not have Oracle Database on this computer, then install the Instant Client Basic or Basic Light package from\n';
     mesg += url;
     mesg += 'A Microsoft Visual Studio Redistributable suitable for your Oracle client library version must be available.\n';
@@ -134,41 +109,6 @@ function getInstallHelp() {
   return mesg;
 }
 
-module.exports.getInstallHelp = getInstallHelp;
-
-// getErrorMessage is used to get and format error messages to make throwing
-// errors a little more convenient.
-function getErrorMessage(errorCode) {
-  let args = Array.prototype.slice.call(arguments);
-  args[0] = errorMessages[errorCode];
-  return util.format.apply(util, args);
-}
-
-module.exports.getErrorMessage = getErrorMessage;
-
-// assert is typically used at the beginning of public functions to assert
-// preconditions for the function to execute. Most commonly it is used to
-// validate the number of arguments and their types and throw an error if they
-// don't match what is expected.
-function assert(condition, errorCode, messageArg1) {
-  if (!condition) {
-    throw new Error(getErrorMessage(errorCode, messageArg1));
-  }
-}
-
-module.exports.assert = assert;
-
-// checkArgCount is used to validate the number of arguments, particularly with
-// optional parameters (range of number of parameters).  If the number of
-// arguments is not within the given range, an error is thrown.
-function checkArgCount(args, minArgCount, maxArgCount) {
-  if (args.length < minArgCount || args.length > maxArgCount)
-    throw new Error(getErrorMessage('NJS-009'));
-}
-
-module.exports.checkArgCount = checkArgCount;
-
-
 // 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
@@ -180,9 +120,8 @@ 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(e) {
-        Error.captureStackTrace(e, stackCapture);
-        throw e;
+      return func.apply(this, arguments).catch(function stackCapture(err) {
+        throw errors.transformErr(err, stackCapture);
       });
     }
 
@@ -191,8 +130,9 @@ function callbackify(func) {
     const cb = arguments[arguments.length - 1];
     func.apply(this, args).then(function(result) {
       cb(null, result);
-    }, cb);
-
+    }, function stackCapture(err) {
+      cb(errors.transformErr(err, stackCapture));
+    });
   };
   if (func.name) {
     Object.defineProperty(wrapper, 'name', { value: func.name });
@@ -200,36 +140,37 @@ function callbackify(func) {
   return wrapper;
 }
 
-module.exports.callbackify = callbackify;
-
 // 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() {
 
-    // determine the connection associated with the object
-    const connection = this._getConnection();
+    let connImpl;
 
-    // acquire the "lock"; this simply checks to see if another operation is in
-    // progress, and if so, waits for it to complete
-    await connection._acquireLock();
+    // 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) {
+      connImpl = this._impl._getConnImpl();
+      await connImpl._acquireLock();
+    }
 
     // call the function and ensure that the lock is "released" once the
-    // function has completed -- either successfully or in failure
+    // function has completed -- either successfully or in failure -- but only
+    // if a connection implementation is currently associated with this object
     try {
       return await func.apply(this, arguments);
     } finally {
-      connection._releaseLock();
+      if (connImpl)
+        connImpl._releaseLock();
     }
   };
 }
 
-module.exports.serialize = serialize;
-
 function preventConcurrent(func, errorCode) {
   return async function() {
     if (this._isActive)
-      throw new Error(getErrorMessage(errorCode));
+      errors.throwErr(errorCode);
     this._isActive = true;
     try {
       return await func.apply(this, arguments);
@@ -239,31 +180,176 @@ function preventConcurrent(func, errorCode) {
   };
 }
 
-module.exports.preventConcurrent = preventConcurrent;
+// The wrapFns() function is used to wrap the named methods on the prototype
+// in multiple ways (serialize, preventConcurrent and callbackify); 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 preventConcurrentErrorCode;
+  if (typeof arguments[1] === 'number') {
+    nameIndex = 2;
+    preventConcurrentErrorCode = 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));
+  }
+}
+
+function isArrayOfStrings(value) {
+  if (!Array.isArray(value))
+    return false;
+  for (let i = 0; i < value.length; i++) {
+    if (typeof value[i] !== 'string')
+      return false;
+  }
+  return true;
+}
 
 function isObject(value) {
   return value !== null && typeof value === 'object';
 }
 
-module.exports.isObject = isObject;
-
 function isObjectOrArray(value) {
   return (value !== null && typeof value === 'object') || Array.isArray(value);
 }
 
-module.exports.isObjectOrArray = isObjectOrArray;
+function isShardingKey(value) {
+  if (!Array.isArray(value))
+    return false;
+  for (let i = 0; i < value.length; i++) {
+    const element = value[i];
+    const ok = typeof element === 'string' ||
+      typeof element === 'number' || Buffer.isBuffer(element) ||
+      util.isDate(element);
+    if (!ok)
+      return false;
+  }
+  return true;
+}
 
 function isSodaDocument(value) {
   return (value != null && value._sodaDocumentMarker);
 }
 
 function isXid(value) {
-  return (isObject(value) &&
-            (value.formatId !== undefined) &&
-            (value.globalTransactionId !== undefined) &&
-            (value.branchQualifier !== undefined));
+  return (isObject(value) && Number.isInteger(value.formatId) &&
+    (Buffer.isBuffer(value.globalTransactionId) ||
+      typeof value.globalTransactionId === 'string') &&
+    (Buffer.isBuffer(value.branchQualifier) ||
+      typeof value.branchQualifier === 'string'));
 }
 
-module.exports.isXid = isXid;
+function verifySodaDoc(content) {
+  if (isSodaDocument(content))
+    return content._impl;
+  errors.assertParamValue(isObject(content), 1);
+  return Buffer.from(JSON.stringify(content));
+}
+
+function isTokenExpired(token) {
+  errors.assert(typeof token === 'string', errors.ERR_TOKEN_BASED_AUTH);
+  if (token.split('.')[1] === undefined) {
+    errors.throwErr(errors.ERR_TOKEN_BASED_AUTH);
+  }
+
+  const base64Url = token.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;
+  errors.assert(expiry != undefined, errors.ERR_TOKEN_BASED_AUTH);
+  expiry = expiry * 1000;
+
+  return (new Date().getTime() > expiry);
+}
+
+function isTokenValid(accessToken) {
+  switch (typeof accessToken) {
+    case 'string':
+      if (accessToken === '') {
+        errors.throwErr(errors.ERR_TOKEN_BASED_AUTH);
+      }
+
+      return !isTokenExpired(accessToken);
+    case 'object':
+      if (accessToken.token === undefined ||
+          accessToken.token === '' ||
+          accessToken.privateKey === undefined ||
+          accessToken.privateKey === '') {
+        errors.throwErr(errors.ERR_TOKEN_BASED_AUTH);
+      }
+
+      return !isTokenExpired(accessToken.token);
+    default:
+      errors.throwErr(errors.ERR_TOKEN_BASED_AUTH);
+  }
+}
 
-module.exports.isSodaDocument = isSodaDocument;
+function isPrivateKeyValid(accessToken) {
+  errors.assert(typeof accessToken.privateKey === 'string',
+    errors.ERR_TOKEN_BASED_AUTH);
+
+  if (accessToken.privateKey.startsWith("-----BEGIN PRIVATE KEY-----") ||
+    accessToken.privateKey.endsWith("-----END PRIVATE KEY-----")) {
+    return false;
+  }
+
+  return true;
+}
+
+//-----------------------------------------------------------------------------
+// addTypeProperties()
+//
+// Adds derived properties about the type as a convenience to the user.
+// Currently this is only the name of type, which is either the name of the
+// database object type (if the value refers to a database object) or the name
+// of the Oracle database type.
+// -----------------------------------------------------------------------------
+function addTypeProperties(obj, attrName) {
+  const clsAttrName = attrName + "Class";
+  const nameAttrName = attrName + "Name";
+  const cls = obj[clsAttrName];
+  let dbType = obj[attrName];
+  if (typeof dbType === 'number') {
+    dbType = obj[attrName] = types.getTypeByNum(dbType);
+  }
+  if (cls) {
+    obj[nameAttrName] = cls.prototype.fqn;
+  } else if (dbType) {
+    obj[nameAttrName] = dbType.columnTypeName;
+  }
+}
+
+// define exports
+module.exports = {
+  BINARY_FILE,
+  PACKAGE_JSON_VERSION,
+  RELEASE_DIR,
+  STAGING_DIR,
+  addTypeProperties,
+  callbackify,
+  getInstallURL,
+  getInstallHelp,
+  isArrayOfStrings,
+  isObject,
+  isObjectOrArray,
+  isPrivateKeyValid,
+  isShardingKey,
+  isSodaDocument,
+  isTokenExpired,
+  isTokenValid,
+  isXid,
+  preventConcurrent,
+  serialize,
+  verifySodaDoc,
+  wrapFns
+};

package/lib/version.js

@@ -0,0 +1,36 @@
+// Copyright (c) 2023, 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.
+//
+//-----------------------------------------------------------------------------
+
+// Version information.
+// Keep in sync with package.json.
+// Leave the suffix an empty string for production releases.
+
+module.exports = {
+  VERSION_MAJOR: 6,
+  VERSION_MINOR: 0,
+  VERSION_PATCH: 1,
+  VERSION_SUFFIX: ''
+};

package/package/README.md

@@ -6,46 +6,49 @@ to create a custom package for hosting on a local server.
 
 Most users do not need to use anything in this directory.
 
-# Maintainers
+# Building an Install Package
 
 In a clone or copy of the repository:
 
-- Run `npm run buildbinary`.  This calls `buildbinary.js` to create a
-  node-oracledb binary for the current operating system.  Depending how Node.js
-  was installed, you may need to run `npm install node-gyp -g` first.
+- If you want to build a package that installs node-oracledb with both 'Thin'
+  and 'Thick' modes, then run `npm run buildbinary`.  This calls
+  `buildbinary.js` to create a node-oracledb 'Thick' mode binary for the
+  current operating system.  Depending on how Node.js was installed, you may
+  need to run `npm install node-gyp -g` first.
 
   You can run `npm run buildbinary` on each operating system architecture that
-  you want to include in your package.  Copy the node-oracledb binaries and
-  related build metadata information files from all `package/Staging`
-  directories to the `package/Staging` directory on one machine.
-
-- Run `npm run buildpackage`.  This calls `buildpackage.js` to make the
-  node-oracledb package containing the node-oracledb JavaScript files, the
-  available binaries, and a `package.json` that has `install` and `prune` script
-  targets.  The package will be created in the top level directory.  It can be
-  uploaded to npmjs.com, or to your own local server, and then used as a
-  dependency in your projects.
+  you want to include in your package.  Copy the node-oracledb Thick mode
+  binaries and related build metadata information files from all
+  `package/Staging` directories to the `package/Staging` directory on one
+  machine.
+
+- On the machine with any (or no) desired Thick mode binaries in
+  `package/Staging`, run `npm run buildpackage`.  This calls `buildpackage.js`
+  to make the node-oracledb package containing the node-oracledb JavaScript
+  files, the available Thick mode binaries, and a `package.json` that has
+  `install` and `prune` script targets.  The package will be created in the top
+  level directory.  It can be uploaded to npmjs.com by maintainers of
+  node-oracledb, or you can upload to your own local server and then use it as
+  a dependency in your projects.
 
 # Package Installation
 
-- When running `npm install` with the created package, the `package.json`
-  install script runs `install.js` to check the availability of a binary module
-  for the current Node.js version and operating system architecture.
+- Running `npm install` with the created package always installs node-oracledb
+  Thin mode.  The installation script also runs `install.js` to check the
+  availability of the optional Thick mode binary module.  A warning will be
+  displayed if the binary is not found for the current Node.js version and
+  operating system architecture.
 
-- If installation succeeds, space conscious users can then run `npm run prune`
-  which removes pre-built binaries for all other architectures.
+- If you are space-conscious, then run `npm run prune` after installation.
+  This removes pre-built binaries for all other architectures.
 
-- If `npm install` fails because a suitable binary is not available, users must
-  then compile node-oracledb using source code from GitHub.  Alternatively a
-  different version of node-oracledb, Node.js, or different operating system may
-  have a suitable pre-built binary available.  See
-  https://github.com/oracle/node-oracledb/releases for information about Node.js
-  versions and pre-built node-oracledb binaries.
+  If you only ever want Thin mode, then remove all the Thick mode binaries by
+  running `npm run prune all`.
 
-The
+Note the
 [`package.json`](https://github.com/oracle/node-oracledb/blob/main/package.json)
 in GitHub doesn't have an `install` script target by default.  This means that
-node-gyp will be invoked to compile node-oracledb.  This allows installation
-from GitHub [source
-code](https://oracle.github.io/node-oracledb/INSTALL.html#github) when no
-suitable pre-built binary is available.
+node-gyp will be invoked to compile the optional node-oracledb Thick mode
+binary.  This allows installation of Thick mode from GitHub [source
+code](https://node-oracledb.readthedocs.io/en/latest/user_guide/installation.html#github)
+when no suitable pre-built binary is available.