Network code formatting and error updates, test case, examples and documentation corrections

Author: sharadraju

doc/src/release_notes.rst

@@ -23,11 +23,23 @@ Common Changes
 Thin Mode Changes
 +++++++++++++++++
 
-#) Fixed issue which stopped applications from connecting to Oracle Database
-   with distinct TNS aliases from more than one tnsnames.ora file.
-    
-#) Fixed bug that fails to throw an error, when fetching data greater
-   than the ``maxSize`` property of outbinds in Oracle Database 12.1. 
+#)  Fixed issue which stopped applications from connecting to Oracle Database
+    with distinct TNS aliases from more than one
+    :ref:`tnsnames.ora <tnsadmin>` file.
+
+#)  Fixed bug that fails to throw an error, when fetching data greater
+    than the :ref:`maxSize <executebindparammaxsize>` property of outbinds in
+    Oracle Database 12.1.
+
+#)  Fixed bug that throws incorrect error message when invalid ``retryCount``
+    parameter is specified in the connect string.
+
+#)  Throw error in case of TLS initialization failure when resend response
+    network packets are received.
+
+#)  Added new error message, when invalid or unresolvable host name is
+    provided in the connect string.
+    See `Issue #1673 <https://github.com/oracle/node-oracledb/issues/1673>`__.
 
 node-oracledb `v6.7.0 <https://github.com/oracle/node-oracledb/compare/v6.6.0...v6.7.0>`__ (18 Nov 2024)
 ---------------------------------------------------------------------------------------------------------

examples/README.md

@@ -65,7 +65,7 @@ File Name                                                 | Description
 [`aqraw.js`](aqraw.js)                                    | Basic Oracle Advanced Queuing (AQ) example passing text messages
 [`aqutil.js`](aqutil.js)                                  | Common file to setup the user credentials for all the Advanced Queuing (AQ) examples.
 [`blobhttp.js`](blobhttp.js)                              | Simple web app that streams an image
-[`azureConfigProvider.js`](azureConfigProvider.js)        | Show how to connect to an Oracle Database using Azure Configuration Providers
+[`azureConfigProvider.js`](azureConfigProvider.js)        | Show how to connect to Oracle Database using Azure Configuration Provider
 [`calltimeout.js`](calltimeout.js)                        | Shows how to cancel a SQL statement if it doesn't complete in a specified time
 [`connect.js`](connect.js)                                | Basic example for creating a standalone (non-pooled) connection
 [`connectionpool.js`](connectionpool.js)                  | Basic example creating a pool of connections
@@ -102,7 +102,8 @@ File Name                                                 | Description
 [`lobstream2.js`](lobstream2.js)                          | Shows using Stream data events to fetch a CLOB
 [`lowercasecolumns.js`](lowercasecolumns.js)              | Shows how a type handler can convert column names to lower case
 [`metadata.js`](metadata.js)                              | Shows the metadata available after executing SELECT statements
-[`ociConfigProvider.js`](ociConfigProvider.js)            | Show how to connect to an Oracle Database using OCI Configuration Providers
+[`ociConfigProvider.js`](ociConfigProvider.js)            | Show how to connect to Oracle Database using OCI Config Provider
+[`ociConfigProviderPool.js`](ociConfigProviderPool.js)    | Show how to connect with custom pool settings to Oracle Database using OCI Config Provider
 [`plsqlarray.js`](plsqlarray.js)                          | Examples of binding PL/SQL "INDEX BY" tables
 [`plsqlfunc.js`](plsqlfunc.js)                            | How to call a PL/SQL function
 [`plsqlproc.js`](plsqlproc.js)                            | How to call a PL/SQL procedure

examples/ociConfigProviderPool.js

@@ -0,0 +1,108 @@
+/* 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.
+ *
+ * NAME
+ *   ociConfigProviderPool.js
+ *
+ * DESCRIPTION
+ *   Sample program using connection pool to connect to the database using
+ *   DB connect string, username and password fetched from the OCI
+ *   Configuration Providers using the OCI Object Store Connect String URL.
+ *
+ *****************************************************************************/
+
+'use strict';
+
+Error.stackTraceLimit = 50;
+
+const oracledb = require('oracledb');
+
+// This example runs in both node-oracledb Thin and Thick modes.
+//
+// Optionally run in node-oracledb Thick mode
+if (process.env.NODE_ORACLEDB_DRIVER_MODE === 'thick') {
+
+  // Thick mode requires Oracle Client or Oracle Instant Client libraries.
+  // On Windows and macOS Intel you can specify the directory containing the
+  // libraries at runtime or before Node.js starts.  On other platforms (where
+  // Oracle libraries are available) the system library search path must always
+  // include the Oracle library path before Node.js starts.  If the search path
+  // is not correct, you will get a DPI-1047 error.  See the node-oracledb
+  // installation documentation.
+  let clientOpts = {};
+  // On Windows and macOS Intel platforms, set the environment
+  // variable NODE_ORACLEDB_CLIENT_LIB_DIR to the Oracle Client library path
+  if (process.platform === 'win32' || (process.platform === 'darwin' && process.arch === 'x64')) {
+    clientOpts = { libDir: process.env.NODE_ORACLEDB_CLIENT_LIB_DIR };
+  }
+  oracledb.initOracleClient(clientOpts);  // enable node-oracledb Thick mode
+}
+
+console.log(oracledb.thin ? 'Running in thin mode' : 'Running in thick mode');
+
+async function run() {
+  // Replace the connect string with correct OCI Config Store URL
+  // Replace xxxx in the connect string with the correct authentication parameter values
+  let pool, connection;
+  const options = {
+    connectString: 'config-ociobject://test.region.oraclecloud.com/n/testnamespace/b/testbucket/o/testobject?oci_tenancy=xxxx&oci_user=xxxx&oci_fingerprint=xxxx&oci_key_file=xxxx',
+  };
+  try {
+    // Create a pool and get a connection from the pool
+    pool = await oracledb.createPool(options);
+    console.log('Pool Created Successfully');
+
+    console.log('pool.stmtCacheSize:', pool.stmtCacheSize);
+    console.log('pool.poolMin:', pool.poolMin);
+    console.log('pool.poolMax', pool.poolMax);
+    console.log('pool.poolIncrement:', pool.poolIncrement);
+    console.log('pool.poolTimeout:', pool.poolTimeout);
+    console.log('pool.poolPingInterval:', pool.poolPingInterval);
+    console.log('pool.poolPingTimeout:', pool.poolPingTimeout);
+
+    connection = await pool.getConnection(options);
+    console.log('\nCreated connection from the pool successfully!');
+
+  } catch (err) {
+    console.error(err);
+  } finally {
+    if (connection) {
+      try {
+        await connection.close();
+      } catch (err) {
+        console.error(err);
+      }
+    }
+
+    if (pool) {
+      try {
+        await pool.close();
+      } catch (err) {
+        console.error(err);
+      }
+    }
+  }
+}
+
+run();

lib/errors.js

@@ -195,6 +195,7 @@ const ERR_OCIOBJECT_CONFIG_PROVIDER_AUTH_FAILED = 526;
 const ERR_AZURE_VAULT_AUTH_FAILED = 527;
 const ERR_AZURE_SERVICE_PRINCIPAL_AUTH_FAILED = 528;
 const ERR_WALLET_TYPE_NOT_SUPPORTED = 529;
+const ERR_HOST_NOT_FOUND = 530;
 
 // Oracle SUCCESS_WITH_INFO warning start from 700
 const WRN_COMPILATION_CREATE = 700;
@@ -527,6 +528,8 @@ messages.set(ERR_AZURE_SERVICE_PRINCIPAL_AUTH_FAILED,         // NJS-528
   'Azure service principal authentication requires either a client certificate path or a client secret string');
 messages.set(ERR_WALLET_TYPE_NOT_SUPPORTED,                   // NJS-529
   'Invalid wallet content format. Supported format is PEM');
+messages.set(ERR_HOST_NOT_FOUND,                          // NJS-530
+  'The host addresses or URLs provided by the connect string are incorrect or unresolvable in your network.');
 
 // Oracle SUCCESS_WITH_INFO warning
 messages.set(WRN_COMPILATION_CREATE,                          // NJS-700
@@ -844,6 +847,7 @@ module.exports = {
   ERR_CONFIG_PROVIDER_NOT_SUPPORTED,
   ERR_CONFIG_PROVIDER_LOAD_FAILED,
   ERR_WALLET_TYPE_NOT_SUPPORTED,
+  ERR_HOST_NOT_FOUND,
   ERR_INVALID_BIND_NAME,
   ERR_WRONG_NUMBER_OF_BINDS,
   ERR_BUFFER_LENGTH_INSUFFICIENT,

lib/thin/sqlnet/connStrategy.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
+// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -90,6 +90,7 @@ class ConnStrategy {
     this.descriptionList.push(this.currentDescription);
     this.currentDescription = null;
   }
+
   /**
   * Execute the Connection Options from the array.  When a refuse packet is received from
   * server this method is called again and the next connect option is tried.
@@ -148,8 +149,8 @@ class ConnStrategy {
   }
   // sleep time expects milliseconds
 
-
 }
+
 function sleep(time) {
   return new Promise((resolve) => setTimeout(resolve, time));
 }

lib/thin/sqlnet/navNodes.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
+// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -315,6 +315,7 @@ class Description {
       }
     }
   }
+
   toString() {
     let s = new String(""), child ;
 
@@ -428,9 +429,6 @@ class DescriptionList {
 }
 
 
-
-
-
 /**
  * Class that contains information about a possible connection.
  */
@@ -453,23 +451,25 @@ const NavSchemaObject = {
 const options = {
   all: true,
 };
+
 /**
  * Class that navigates the address node in the tree.
  */
 class NavAddress extends Address {
   constructor() {
     super();
   }
+
   /**
    * Set the connection option to this address.
    * @param {object} cs
    */
   async navigate(cs) {
     let addresses;
-    let nullHost = 0;
+    let nullHost = false;
     let needToCloseDescription = false;
     if (!this.host) {
-      nullHost = 1;
+      nullHost = true;
       this.host = os.hostname();
       try {
         await dnsPromises.lookup(this.host, options);
@@ -495,7 +495,7 @@ class NavAddress extends Address {
           co.httpsProxyPort = this.httpsProxyPort;
           co.desc = cs.getcurrentDescription();
           co.CNdata.push(cs.sBuf.join(""));
-          if (nullHost == 1)
+          if (nullHost)
             co.CNdata.push('(address=(protocol=' + this.prot + ')(host=' + this.host + ')(port=' + this.port + '))');
           else
             co.CNdata.push(this.toString());
@@ -505,6 +505,8 @@ class NavAddress extends Address {
         }
       } catch {
         // do nothing
+        // Any error in the try block is ignored, because we want to try
+        // the next address
       }
     } else {
       const co = new ConnOption();
@@ -527,8 +529,6 @@ class NavAddress extends Address {
 
   }
 
-
-
   /**
    * AddToString is used to construct a string representation of the TNS
    * Address. Constructing a string is mainly needed when source route is ON.
@@ -557,10 +557,10 @@ class NavAddressList extends AddressList {
   }
 
   /**
- * Method decides how to traverse and sets the active children based on
- * the loadbalancing, failover values.
- * @param {object} cs
- */
+   * Method decides how to traverse and sets the active children based on
+   * the loadbalancing, failover values.
+   * @param {object} cs
+   */
   async navigate(cs) {
     await this.navigate2(cs, 0);
   }
@@ -592,6 +592,7 @@ class NavAddressList extends AddressList {
     cs.sBuf.length = this.sBuflength;
 
   }
+
   addToString(cs) {
     const NVString = this.toString();
     let cOpts = new Array();
@@ -604,7 +605,6 @@ class NavAddressList extends AddressList {
     }
   }
 
-
   getChildrenSize() {
     let size = 0;
     for (let i = 0; i < this.activeChildren.length; i++) {
@@ -762,7 +762,6 @@ class NavDescription extends Description {
   }
 
   closeNVPair(cs) {
-
     if (cs.getcurrentDescription() == null)
       return;
     let cOpts = new Array();
@@ -812,11 +811,9 @@ class NavDescription extends Description {
   }
 
   getIntValue(stringInt, defaultValue) {
-    try {
+    if (/^\d+$/.test(stringInt))
       return parseInt(stringInt);
-    } catch (exception) {
-      return defaultValue;
-    }
+    return defaultValue;
   }
 
 }
@@ -884,7 +881,5 @@ class NavDescriptionList extends DescriptionList {
 
   }
 
-
-
 }
 module.exports = {NavAddress, NavAddressList, NavDescription, NavDescriptionList};

lib/thin/sqlnet/networkSession.js

@@ -143,6 +143,7 @@ class NetworkSession {
   async getAddress(addressNode, userConfig) {
     /* Get the next address */
     const address = await addressNode.execute(userConfig);
+
     /* Prepare connection attributes */
     const uuid = this.sAtts ? this.sAtts.uuid : null;
     this.sAtts = new SessionAtts(uuid);
@@ -196,8 +197,10 @@ class NetworkSession {
   }
 
   /**
-   * Establish network session .Make transport level connection, send NSPTCN(connect packet) and read the response.
-   * @returns NetError.(connection successfully established(NetError.CONNECTED) or reason for failure)
+   * Establish network session. Make transport level connection, send
+   * NSPTCN(connect packet) and read the response. @returns NetError.
+   * (connection successfully established(NetError.CONNECTED)
+   * or reason for failure)
    */
   async connect2(address, userConfig) {
     /* Sanitise SDU */
@@ -534,8 +537,8 @@ class NetworkSession {
     try {
       address = await this.getAddress(addressNode, userConfig);
     } catch (err) {
-      if (err.message == "All options tried") /* Not even one valid Address */
-        errors.throwErr(errors.ERR_INVALID_CONNECT_STRING_PARAMETERS, "Ensure the ADDRESS parameters have been entered correctly, the most likely incorrect parameter is the host name");
+      if (err.message == "All options tried") /* Not even one valid address */
+        errors.throwErr(errors.ERR_HOST_NOT_FOUND);
       else
         errors.throwErr(errors.ERR_INVALID_CONNECT_STRING_PARAMETERS, err.message);
     }
@@ -617,7 +620,8 @@ class NetworkSession {
   /**
    * receive inband notification
    * @param {Object} obj Return the notification into user provided object
-   * @returns Error number sent from server, or error on the connection. returns 0 if healthy connection
+   * @returns Error number sent from server, or error on the connection.
+   * returns 0 if healthy connection
    */
   recvInbandNotif() {
     let error = 0;