Added support for caching configurations for a configurable period of

time.

Author: anthony-tuininga

doc/src/user_guide/connection_handling.rst

@@ -572,6 +572,7 @@ cdef class ConnectParamsImpl:
         public str driver_name
         public dict extra_auth_params
         public bint thick_mode_dsn_passthrough
+        public str _config_cache_key
 
     cdef int _check_credentials(self) except -1
     cdef int _copy(self, ConnectParamsImpl other_params) except -1

src/oracledb/base_impl.pxd

@@ -59,6 +59,7 @@ from .interchange.nanoarrow_bridge cimport (
 import array
 
 import base64
+import copy
 import datetime
 import decimal
 import getpass
@@ -71,6 +72,7 @@ import socket
 import ssl
 import string
 import sys
+import time
 import warnings
 
 cydatetime.import_datetime()

src/oracledb/base_impl.pyx

@@ -120,7 +120,7 @@ cdef class ConnectParamsImpl:
             if address is not self._default_address:
                 address.set_from_args(args)
 
-    def set_from_config(self, dict config):
+    def set_from_config(self, dict config, bint update_cache=True):
         """
         Internal method for setting the property from the supplied
         configuration.
@@ -140,6 +140,8 @@ cdef class ConnectParamsImpl:
         args = config.get("pyo")
         if args is not None:
             self.set(args)
+        if update_cache and self._config_cache_key is not None:
+            update_config_cache(self._config_cache_key, config)
 
     cdef int _check_credentials(self) except -1:
         """

src/oracledb/impl/base/connect_params.pyx

@@ -159,6 +159,10 @@ EXTENDED_PARAM_NAMES = set([
 
 ])
 
+# this cache stores the configurations acquired from one of the configuration
+# stores
+cdef dict cached_configs = {}
+
 # add all of the common parameters to the extended parameters using the
 # python-oracledb specific name
 for name in COMMON_PARAM_NAMES:
@@ -227,6 +231,43 @@ cdef class BaseParser:
             self.temp_pos += 1
 
 
+cdef int update_config_cache(str config_cache_key, dict config) except -1:
+    """
+    Updates the cache with the specified configuration.
+    """
+    cdef:
+        double current_time, soft_expiry_time, hard_expiry_time
+        uint32_t time_to_live, time_to_live_grace_period
+        object setting
+
+    # the config can include config_time_to_live; the default value is 86400
+    # (24 hours); an explicit value of 0 disables caching
+    setting = config.get("config_time_to_live")
+    if setting is None:
+        time_to_live = 86400
+    else:
+        time_to_live = int(setting)
+    if time_to_live == 0:
+        return 0
+
+    # the config settings can also include config_time_to_live_grace_period;
+    # the default value is 1800 (30 minutes)
+    setting = config.get("config_time_to_live_grace_period")
+    if setting is None:
+        time_to_live_grace_period = 1800
+    else:
+        time_to_live_grace_period = int(setting)
+
+    # calculate soft and hard expiry times and keep them with the config
+    current_time = time.monotonic()
+    soft_expiry_time = current_time + time_to_live
+    hard_expiry_time = soft_expiry_time + time_to_live_grace_period
+    config = copy.deepcopy(config)
+    config["config_cache_soft_expiry_time"] = soft_expiry_time
+    config["config_cache_hard_expiry_time"] = hard_expiry_time
+    cached_configs[config_cache_key] = config
+
+
 cdef class ConnectStringParser(BaseParser):
 
     cdef:
@@ -237,6 +278,48 @@ cdef class ConnectStringParser(BaseParser):
         Description description
         dict parameters
 
+    cdef int _call_protocol_hook(self, str protocol, str arg,
+                                 object fn) except -1:
+        """
+        Check if the config cache has an entry; if an extry exists and it has
+        not expired, use it; otherwise, call the protocol hook function.
+        """
+        cdef:
+            double current_time = 0, expiry_time = 0
+            dict config
+
+        # check to see if the cache has a value and that it has not reached the
+        # soft expiry time
+        config = cached_configs.get(self.data_as_str)
+        if config is not None:
+            current_time = time.monotonic()
+            expiry_time = config["config_cache_soft_expiry_time"]
+            if current_time <= expiry_time:
+                self.params_impl.set_from_config(config, update_cache=False)
+                return 0
+
+        # call the protocol hook function; the cache key is set on the
+        # parameters instance so that calls by the hook function to
+        # set_from_config() will update the cache
+        params = self.params_impl._get_public_instance()
+        self.params_impl._config_cache_key = self.data_as_str
+        try:
+            fn(protocol, arg, params)
+        except Exception as e:
+
+            # if the hook fails but a config exists in the cache and the hard
+            # expiry time has not been reached the existing config is used
+            if config is not None:
+                expiry_time = config["config_cache_hard_expiry_time"]
+                if current_time <= expiry_time:
+                    self.params_impl.set_from_config(config, update_cache=False)
+                    return 0
+                del cached_configs[self.params_impl._config_cache_key]
+            errors._raise_err(errors.ERR_PROTOCOL_HANDLER_FAILED,
+                              protocol=protocol, arg=arg, cause=e)
+        finally:
+            self.params_impl._config_cache_key = None
+
     cdef bint _is_host_or_service_name_char(self, Py_UCS4 ch):
         """
         Returns whether or not the given character is allowed to be used inside
@@ -377,19 +460,14 @@ cdef class ConnectStringParser(BaseParser):
         Parses an easy connect string.
         """
         cdef:
-            object params, fn
+            object fn
             str protocol, arg
         protocol = self._parse_easy_connect_protocol()
         if protocol is not None:
             fn = REGISTERED_PROTOCOLS.get(protocol)
             if fn is not None:
                 arg = self.data_as_str[self.temp_pos:]
-                params = self.params_impl._get_public_instance()
-                try:
-                    fn(protocol, arg, params)
-                except Exception as e:
-                    errors._raise_err(errors.ERR_PROTOCOL_HANDLER_FAILED,
-                                      protocol=protocol, arg=arg, cause=e)
+                self._call_protocol_hook(protocol, arg, fn)
                 self.description_list = self.params_impl.description_list
                 self.pos = self.num_chars
                 return 0

src/oracledb/impl/base/parsers.pyx

@@ -181,7 +181,6 @@ def _process_config(parameters, connect_params):
     )
     config["user"] = _get_setting(client, key, "user", label, required=False)
     pwd = _get_setting(client, key, "password", label, required=False)
-
     if pwd is not None:
         try:
             pwd = json.loads(pwd)
@@ -193,8 +192,14 @@ def _process_config(parameters, connect_params):
                 " containing Azure Vault details."
             )
             raise Exception(message)
-
     config["password"] = pwd
+    config["config_time_to_live"] = _get_setting(
+        client, key, "config_time_to_live", label, required=False
+    )
+    config["config_time_to_live_grace_period"] = _get_setting(
+        client, key, "config_time_to_live_grace_period", label, required=False
+    )
+
     # get the python-oracledb specific parameters
     settings = _get_setting(client, key, "pyo", label, required=False)
     if settings is not None:

src/oracledb/plugins/azure_config_provider.py

@@ -25,8 +25,7 @@
 # -----------------------------------------------------------------------------
 # azure_tokens.py
 #
-# Python file defining the methods that generates an OAuth access token
-# using the MSAL SDK
+# Methods that generates an OAuth2 access token using the MSAL SDK
 # -----------------------------------------------------------------------------
 
 import msal
@@ -37,11 +36,14 @@ def generate_token(token_auth_config, refresh=False):
     """
     Generates an Azure access token based on provided credentials.
     """
-    auth_type = token_auth_config.get("authType", "").lower()
+    user_auth_type = token_auth_config.get("auth_type") or ""
+    auth_type = user_auth_type.lower()
     if auth_type == "azureserviceprincipal":
         return _service_principal_credentials(token_auth_config)
     else:
-        raise ValueError(f"Unrecognized authentication method: {auth_type}")
+        raise ValueError(
+            f"Unrecognized auth_type authentication method: {user_auth_type}"
+        )
 
 
 def _service_principal_credentials(token_auth_config):
@@ -50,8 +52,8 @@ def _service_principal_credentials(token_auth_config):
     """
     msal_config = {
         "authority": token_auth_config["authority"],
-        "client_id": token_auth_config["clientId"],
-        "client_credential": token_auth_config["clientSecret"],
+        "client_id": token_auth_config["client_id"],
+        "client_credential": token_auth_config["client_credential"],
     }
     # Initialize the Confidential Client Application
     cca = msal.ConfidentialClientApplication(**msal_config)

src/oracledb/plugins/azure_tokens.py

@@ -86,6 +86,7 @@ def _get_config(parameters, connect_params):
         settings, "connect_descriptor"
     )
 
+    # user and password
     if connect_params.user is None:
         config["user"] = settings.get("user")
         if "password" in settings:
@@ -97,10 +98,16 @@ def _get_config(parameters, connect_params):
             # password should be stored in JSON and not plain text.
             config["password"] = pwd
 
+    # config cache settings
+    config["config_time_to_live"] = settings.get("config_time_to_live")
+    config["config_time_to_live_grace_period"] = settings.get(
+        "config_time_to_live_grace_period"
+    )
+
     # pyo parameters settings
     config["pyo"] = settings.get("pyo", None)
 
-    # parse connect string and set requested parameters
+    # set the configuration
     connect_params.set_from_config(config)
 
 

src/oracledb/plugins/oci_config_provider.py

@@ -25,8 +25,7 @@
 # -----------------------------------------------------------------------------
 # oci_tokens.py
 #
-# Python file defining the methods that genearates an OCI access
-# token using the OCI SDK
+# Methods that generates an OCI access token using the OCI SDK
 # -----------------------------------------------------------------------------
 
 import oci
@@ -39,13 +38,16 @@ def generate_token(token_auth_config, refresh=False):
     """
     Generates an OCI access token based on provided credentials.
     """
-    auth_type = token_auth_config.get("authType", "").lower()
-    if auth_type == "configfilebasedauthentication":
+    user_auth_type = token_auth_config.get("auth_type") or ""
+    auth_type = user_auth_type.lower()
+    if auth_type == "configfileauthentication":
         return _config_file_based_authentication(token_auth_config)
     elif auth_type == "simpleauthentication":
         return _simple_authentication(token_auth_config)
     else:
-        raise ValueError(f"Unrecognized authentication method: {auth_type}")
+        raise ValueError(
+            f"Unrecognized auth_type authentication method {user_auth_type}"
+        )
 
 
 def _get_key_pair():
@@ -81,16 +83,16 @@ def _get_key_pair():
         )
         private_key_pem = p_key
 
-    return {"privateKey": private_key_pem, "publicKey": public_key_pem}
+    return {"private_key": private_key_pem, "public_key": public_key_pem}
 
 
 def _config_file_based_authentication(token_auth_config):
     """
-    Config file base authentication implementation, config parameters
+    Config file base authentication implementation: config parameters
     are provided in a file.
     """
     file_location = token_auth_config.get(
-        "configFileLocation", oci.config.DEFAULT_LOCATION
+        "file_location", oci.config.DEFAULT_LOCATION
     )
     profile = token_auth_config.get("profile", oci.config.DEFAULT_PROFILE)
 
@@ -105,22 +107,22 @@ def _config_file_based_authentication(token_auth_config):
 
     response = client.generate_scoped_access_token(
         generate_scoped_access_token_details=oci.identity_data_plane.models.GenerateScopedAccessTokenDetails(
-            scope="urn:oracle:db::id::*", public_key=key_pair["publicKey"]
+            scope="urn:oracle:db::id::*", public_key=key_pair["public_key"]
         )
     )
 
     # access_token is a tuple holding token and private key
     access_token = (
         response.data.token,
-        key_pair["privateKey"],
+        key_pair["private_key"],
     )
 
     return access_token
 
 
 def _simple_authentication(token_auth_config):
     """
-    Simple authentication, config parameters are passed as parameters
+    Simple authentication: config parameters are passed as parameters
     """
     config = {
         "user": token_auth_config["user"],
@@ -139,14 +141,14 @@ def _simple_authentication(token_auth_config):
 
     response = client.generate_scoped_access_token(
         generate_scoped_access_token_details=oci.identity_data_plane.models.GenerateScopedAccessTokenDetails(
-            scope="urn:oracle:db::id::*", public_key=key_pair["publicKey"]
+            scope="urn:oracle:db::id::*", public_key=key_pair["public_key"]
         )
     )
 
     # access_token is a tuple holding token and private key
     access_token = (
         response.data.token,
-        key_pair["privateKey"],
+        key_pair["private_key"],
     )
 
     return access_token