Sanitize code, add documentation and tests for 6.9 features

Author: sharadraju

doc/src/api_manual/oracledb.rst

@@ -3969,6 +3969,57 @@ Oracledb Methods
     path, such as from running ``ldconfig`` or set in the environment
     variable ``LD_LIBRARY_PATH``.
 
+.. method:: oracledb.registerConfigurationProviderHook()
+
+    .. versionadded:: 6.9
+
+    ::
+
+        registerConfigurationProviderHook(String configProvider, Function fn)
+
+    Registers the :ref:`centralized configuration provider
+    <configproviderplugins>` extension modules. These registered modules will
+    be called and executed during standalone and pool connection creation.
+
+    If you have defined your own extension module for any particular
+    centralized configuration provider, you need to register it using this
+    method in your code.
+
+    The parameters of the ``oracledb.registerConfigurationProviderHook()`` method
+    are:
+
+    .. _registerconfigurationproviderhookattrs:
+
+    .. list-table-with-summary:: oracledb.registerConfigurationProviderHook() Parameters
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 10 10 30
+        :width: 100%
+        :summary: The first column displays the parameter. The second column
+         displays the data type of the parameter. The third column displays
+         the description of the parameter.
+
+        * - Parameter
+          - Data Type
+          - Description
+        * - ``configProvider``
+          - String
+          - The centralized configuration provider extension that needs to be
+            accessed. The value can be the string "ociobject", "ocivault",
+            "azure", or "azurevault" which are the pre-supplied node-oracledb
+            configuration provider extensions.
+        * - ``fn``
+          - Function
+          - The hook function that needs to be registered. This hook
+            function will be invoked when :meth:`oracledb.getConnection()` or
+            :meth:`oracledb.createPool()` are called. The user hook function
+            is expected to return the configuration information from the
+            configuration provider specified in the ``configProvider``
+            parameter.
+
+    See :ref:`configproviderhookfn`.
+
 .. method:: oracledb.registerProcessConfigurationHook()
 
     .. versionadded:: 6.8

doc/src/release_notes.rst

@@ -35,6 +35,11 @@ Common Changes
     <ocivault>`, and :ref:`Microsoft Azure Key Vault configuration provider
     <azurekeyvault>`.
 
+#)  Moved centralized configuration provider support to be part of the
+    :ref:`plugins <configproviderplugins>` to prevent package build errors
+    with external bundlers such as webpack and esbuild.
+    See `Issue #1791 <https://github.com/oracle/node-oracledb/issues/1791>`__.
+
 #)  Added support for
     :ref:`instance principal authentication <_create_pool_oci_properties>`
     in :ref:`native IAM token-based authentication <cloudnativeauthoci>`
@@ -66,11 +71,6 @@ Common Changes
 Thin Mode Changes
 +++++++++++++++++
 
-#)  Moved centralized configuration provider support to be part of the
-    plugins to prevent package build errors with external bundlers like
-    webpack and esbuild. See:
-    `Issue #1791 <https://github.com/oracle/node-oracledb/issues/1791>`__.
-
 #)  Fixed bug which forced node-oracledb to resolve the database host name
     even if a proxy was specified in the connect string. Now the proxy
     specified in the connect string will resolve the database host name.

doc/src/user_guide/connection_handling.rst

@@ -670,7 +670,10 @@ To use an OCI Object Storage Centralized Configuration Provider, you must:
 
 2. Install the required OCI modules. See :ref:`ocimodules`.
 
-3. :ref:`Use an OCI Object Storage connection string URL <connstringoci>`
+3. Load the :ref:`ociobject <ociobjectplugin>` plugin in your application using
+   ``require('oracledb/plugins/configProviders/ociobject')``.
+
+4. :ref:`Use an OCI Object Storage connection string URL <connstringoci>`
    in the ``connectString`` property of connection and pool creation methods.
 
 Note that node-oracledb caches configurations by default, see
@@ -806,7 +809,10 @@ To use an OCI Vault Centralized Configuration Provider, you must:
 
 2. Install the required OCI modules. See :ref:`ocivaultmodules`.
 
-3. :ref:`Use an OCI Vault connection string URL <connstringocivault>` in the
+3. Load the :ref:`ocivault <ocivaultplugin>` plugin in your application using
+   ``require('oracledb/plugins/configProviders/ocivault')``.
+
+4. :ref:`Use an OCI Vault connection string URL <connstringocivault>` in the
    ``connectString`` property of connection and pool creation methods.
 
 Note that node-oracledb caches configurations by default, see
@@ -889,7 +895,10 @@ To use node-oracledb with Azure App Configuration, you must:
 
 2. Install the required Azure Application modules. See :ref:`azuremodules`.
 
-3. :ref:`Use an Azure App Configuration connection string URL
+3. Load the :ref:`azure <azureplugin>` plugin in your application using
+   ``require('oracledb/plugins/configProviders/azure')``.
+
+4. :ref:`Use an Azure App Configuration connection string URL
    <connstringazure>` in the ``connectString`` parameter of connection and
    pool creation methods.
 
@@ -1050,7 +1059,10 @@ To use node-oracledb with Azure Key Vault, you must:
 2. Install the required Azure Application modules. See
    :ref:`azurevaultmodules`.
 
-3. :ref:`Use an Azure Key Vault connection string URL <connstringazurevault>`
+3. Load the :ref:`azurevault <azurevaultplugin>` plugin in your application
+   using ``require('oracledb/plugins/configProviders/azurevault')``.
+
+4. :ref:`Use an Azure Key Vault connection string URL <connstringazurevault>`
    in the ``connectString`` parameter of connection and pool creation methods.
 
 Note that node-oracledb caches configurations by default, see
@@ -2884,11 +2896,64 @@ the number of open connections does not fall below ``poolMin``.
 Connection Hook Functions
 =========================
 
-Node-oracledb supports hook functions that can be used to customize connection
+Node-oracledb supports centralized configuration provider and process
+configuration hook functions that can be used to customize connection
 logic.
 
-Using oracledb.registerProcessConfigurationHook()
--------------------------------------------------
+.. _configproviderhookfn:
+
+Using Centralized Configuration Provider Hook Functions
+-------------------------------------------------------
+
+The :meth:`oracledb.registerConfigurationProviderHook()` method registers the
+:ref:`centralized configuration provider <configproviderplugins>` extension
+modules that were loaded in your code. When this method is called, it
+registers a user hook function that will be called internally by node-oracledb
+prior to connection or pool creation. The hook function will be invoked when
+:meth:`oracledb.getConnection()` or :meth:`oracledb.createPool()` are called
+with the ``connectString`` property prefixed with a specified configuration
+provider. Your hook function can retrieve the connection information, which
+node-oracledb can subsequently use to complete the connection or pool
+creation.
+
+Pre-supplied node-oracledb plugins such as :ref:`OCI Object Storage
+(ociobject) <ociobjectplugin>`, :ref:`OCI Vault (ocivault) <ocivaultplugin>`,
+:ref:`Azure App Configuration (azure) <azureplugin>`, and
+:ref:`Azure Key Vault (azurevault) <azurevaultplugin>` make use of
+:meth:`oracledb.registerConfigurationProviderHook()`. These plugins use the
+information found in a connection method's ``connectString`` property which
+allows node-oracledb to access the required information from the configuration
+provider, and connect to Oracle Database with this information. For the
+complete plugin implementation, see the respective folders of the
+configuration providers in the `plugins/configProviders <https://github.com/
+oracle/node-oracledb/tree/main/plugins/configProviders>`__ directory of the
+node-oracledb package. Also, you can define your own plugins for centralized
+configuration providers and register it using
+:meth:`oracledb.registerConfigurationProviderHook()`, similar to how the
+pre-supplied node-oracledb plugins are registered.
+
+Once you define the plugin and register it using
+:meth:`oracledb.registerConfigurationProviderHook`, you can connect to Oracle
+Database using the information stored in the configuration provider, for
+example, with OCI Vault:
+
+.. code-block:: javascript
+
+    // Load the ocivault plugin
+    require('oracledb/plugins/configProviders/ocivault');
+
+    // Use an OCI vault connection string
+    const connection = await oracledb.getConnection({
+        connectString : "config-ocivault://ocid1.vaultsecret.oc1?oci_tenancy=abc123&oci_user=ociuser1&oci_fingerprint=ab:14:ba:13&oci_key_file=ociabc/ocikeyabc.pem"
+    });
+
+For more information on the centralized configuration providers supported by
+node-oracledb, see :ref:`configurationprovider`.
+
+.. _processconfighookfns:
+
+Using Process Configuration Hook Functions
+------------------------------------------
 
 The :meth:`oracledb.registerProcessConfigurationHook()` method registers
 extension modules that were added to your code. When this method is called, it

doc/src/user_guide/extensions.rst

@@ -9,10 +9,33 @@ Extending node-oracledb
 You can extend the functionalities of node-oracledb by using plugins. The
 plugins provided by node-oracledb are listed in this section.
 
+.. _cloudnativeauthplugins:
+
+Cloud Native Authentication Plugins
+===================================
+
+.. versionadded:: 6.8
+
+Node-oracledb provides pre-supplied plugins for cloud native authentication
+which are listed in this section. These plugins enable token generation using
+the Software Development Kit (SDK) of the respective token-authentication
+method.
+
+The cloud native authentication token plugin implementation is available in
+the `plugins/token <https://github.com/oracle/node-oracledb/tree/main/plugins/
+token>`__ directory of the node-oracledb package.
+
+To load these node-oracledb plugins in your application, use
+``require('oracledb/plugins/token/<name of plugin>')``, for example:
+
+.. code-block:: javascript
+
+    require('oracledb/plugins/token/extensionOci');
+
 .. _extensionociplugin:
 
 Oracle Cloud Infrastructure (OCI) Cloud Native Authentication Plugin
-====================================================================
+--------------------------------------------------------------------
 
 Node-oracledb's ``extensionOci`` plugin enables token generation using `OCI
 Software Development Kit (SDK) <https://www.npmjs.com/package/oci-sdk>`__ when
@@ -35,7 +58,7 @@ See :ref:`cloudnativeauthoci` for more information.
 .. _extensionazureplugin:
 
 Azure Cloud Native Authentication Plugin
-========================================
+----------------------------------------
 
 Node-oracledb's ``extensionAzure`` plugin enables token generation using `Azure
 Software Development Kit (SDK) <https://www.npmjs.com/~azure-sdk>`__ when
@@ -52,3 +75,122 @@ that generates OAuth 2.0 tokens. This function is internally invoked when the
 :meth:`oracledb.getConnection()` or :meth:`oracledb.createPool()`.
 
 See :ref:`cloudnativeauthoauth` for more information.
+
+.. _configproviderplugins:
+
+Centralized Configuration Provider Plugins
+==========================================
+
+.. versionadded:: 6.9
+
+Node-oracledb provides pre-supplied plugins for centralized configuration
+providers which are listed in this section. These plugins provide access to
+database connection credentials and application configuration information
+stored in a centralized configuration provider.
+
+The centralized configuration provider plugin implementation is available in
+the `plugins/configProviders <https://github.com/oracle/node-oracledb/tree/
+main/plugins/configProviders>`__ directory of the node-oracledb package.
+
+To load these node-oracledb plugins in your application, use
+``require('oracledb/plugins/configProviders/<name of plugin>')``, for example:
+
+.. code-block:: javascript
+
+    require('oracledb/plugins/configProviders/ociobject');
+
+.. _ociobjectplugin:
+
+OCI Object Storage Centralized Configuration Provider Plugin
+------------------------------------------------------------
+
+.. versionadded:: 6.9
+
+``ociobject`` is a plugin that can be loaded in your application to provide
+access to configuration information stored in
+:ref:`Oracle Cloud Infrastructure (OCI) Object Storage <ociobjstorage>`.
+
+This plugin is implemented as a :ref:`centralized configuration provider hook
+function <configproviderhookfn>` to handle connection strings which have the
+prefix ``config-ociobject``, see :ref:`OCI Object Storage connection strings
+<connstringoci>`.
+
+To load the ``ociobject`` plugin in your application, use::
+
+.. code-block:: javascript
+
+    require('oracledb/plugins/configProviders/ociobject');
+
+See :ref:`ociobjstorage` for more information.
+
+.. _ocivaultplugin:
+
+OCI Vault Centralized Configuration Provider Plugin
+---------------------------------------------------
+
+.. versionadded:: 6.9
+
+``ocivault`` is a plugin that can be loaded in your application to provide
+access to configuration information stored in
+:ref:`Oracle Cloud Infrastructure (OCI) Vault <ocivault>`.
+
+This plugin is implemented as a :ref:`centralized configuration provider hook
+function <configproviderhookfn>` to handle connection strings which have the
+prefix ``config-ocivault``, see :ref:`OCI Vault connection strings
+<connstringocivault>`.
+
+To load the ``ocivault`` plugin in your application, use::
+
+.. code-block:: javascript
+
+    require('oracledb/plugins/configProviders/ocivault');
+
+See :ref:`ocivault` for more information.
+
+.. _azureplugin:
+
+Microsoft Azure App Centralized Configuration Provider Plugin
+-------------------------------------------------------------
+
+.. versionadded:: 6.9
+
+``azure`` is a plugin that can be loaded in your application to provide
+access to configuration information stored in
+:ref:`Azure App Configuration <azureappconfig>`.
+
+This plugin is implemented as a :ref:`centralized configuration provider hook
+function <configproviderhookfn>` to handle connection strings which have the
+prefix ``config-azure``, see :ref:`Azure App Configuration connection strings
+<connstringazure>`.
+
+To load the ``azure`` plugin in your application, use::
+
+.. code-block:: javascript
+
+    require('oracledb/plugins/configProviders/azure');
+
+See :ref:`azureappconfig` for more information.
+
+.. _azurevaultplugin:
+
+Microsoft Azure Key Vault Centralized Configuration Provider Plugin
+-------------------------------------------------------------------
+
+.. versionadded:: 6.9
+
+``azurevault`` is a plugin that can be loaded in your application to provide
+access to configuration information stored in
+:ref:`Azure Key Vault <azurekeyvault>`.
+
+This plugin is implemented as a :ref:`centralized configuration provider hook
+function <configproviderhookfn>` to handle connection strings which have the
+prefix ``config-azurevault``, see :ref:`Azure Key Vault connection strings
+<connstringazurevault>`.
+
+To load the ``azurevault`` plugin in your application, use::
+
+.. code-block:: javascript
+
+    require('oracledb/plugins/configProviders/azurevault');
+
+See :ref:`azurekeyvault` for more information.

lib/configProviders/file.js

@@ -69,5 +69,4 @@ async function hookFn(args) {
   }
   return [await configProvider.returnConfig(), configProvider.credential];
 }
-oracledb.registerConfigProviderHooks('file', hookFn);
-
+oracledb.registerConfigurationProviderHook('file', hookFn);

lib/oracledb.js

@@ -1157,12 +1157,12 @@ function registerProcessConfigurationHook(fn) {
 }
 
 //-----------------------------------------------------------------------------
-// registerConfigProviderHooks()
+// registerConfigurationProviderHook()
 //
-// Registers configProvider plugin modules and registered modules will be called and
-// executed during pool and standalone connection creation.
+// Registers Configuration Provider plugin modules and registered modules will
+// be called and executed during pool and standalone connection creation.
 //-----------------------------------------------------------------------------
-function registerConfigProviderHooks(configProvider, fn) {
+function registerConfigurationProviderHook(configProvider, fn) {
   errors.assertArgCount(arguments, 2, 2);
   errors.assertParamValue(typeof fn === 'function', 1);
   errors.assertParamValue(typeof configProvider === 'string', 1);
@@ -1200,7 +1200,7 @@ module.exports = {
   getPool,
   initOracleClient,
   registerProcessConfigurationHook,
-  registerConfigProviderHooks,
+  registerConfigurationProviderHook,
   shutdown: nodbUtil.callbackify(nodbUtil.wrapFn(shutdown)),
   startup: nodbUtil.callbackify(nodbUtil.wrapFn(startup)),